@agent-native/toolkit 0.0.0-beta-20260819143124

package/src/conformance/types.ts

@@ -0,0 +1,45 @@
+import type { DesignSystemComponents } from "../design-system/types.js";
+
+export type DesignSystemConformanceCategory =
+  | "contract"
+  | "leaf"
+  | "behavior"
+  | "overlay-interoperability";
+
+export interface DesignSystemConformanceCheckResult {
+  id: string;
+  category: DesignSystemConformanceCategory;
+  components: readonly (keyof DesignSystemComponents)[];
+  passed: boolean;
+  message?: string;
+}
+
+export interface DesignSystemConformanceReport {
+  contractVersion: number;
+  adapterName: string;
+  passed: boolean;
+  results: readonly DesignSystemConformanceCheckResult[];
+}
+
+export interface RunDesignSystemConformanceOptions {
+  adapterName?: string;
+  components: DesignSystemComponents;
+  contractVersion: number;
+  document?: Document;
+}
+
+export class DesignSystemConformanceError extends Error {
+  readonly report: DesignSystemConformanceReport;
+
+  constructor(report: DesignSystemConformanceReport) {
+    const failures = report.results
+      .filter((result) => !result.passed)
+      .map((result) => `${result.id}: ${result.message ?? "failed"}`)
+      .join("\n");
+    super(
+      `Design system conformance failed for ${report.adapterName}:\n${failures}`,
+    );
+    this.name = "DesignSystemConformanceError";
+    this.report = report;
+  }
+}

package/src/conformance/version.ts

@@ -0,0 +1,22 @@
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "../design-system/types.js";
+
+export const DESIGN_SYSTEM_CONTRACT_EVOLUTION_POLICY = {
+  minor: "New components and optional props are backward-compatible.",
+  major:
+    "Required props, removed components or props, and behavioral contract changes require a new contract major.",
+} as const;
+
+export function assertDesignSystemContractVersion(
+  adapterContractVersion: number,
+): void {
+  if (!Number.isInteger(adapterContractVersion) || adapterContractVersion < 1) {
+    throw new TypeError(
+      "Design system contractVersion must be a positive integer.",
+    );
+  }
+  if (adapterContractVersion !== DESIGN_SYSTEM_CONTRACT_VERSION) {
+    throw new RangeError(
+      `Design system contract major ${adapterContractVersion} is incompatible with Toolkit contract major ${DESIGN_SYSTEM_CONTRACT_VERSION}.`,
+    );
+  }
+}

package/src/context-ui/ContextMeter.spec.tsx

@@ -0,0 +1,73 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ContextMeterView } from "./ContextMeter.js";
+import { fallbackContextTranslate } from "./types.js";
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+const manifest = {
+  totalTokens: 300,
+  rawTokens: 300,
+  reclaimedTokens: 0,
+  tokenCountMethod: "exact" as const,
+  enforceable: true,
+  segments: [],
+  systemTokens: 100,
+  conversationTokens: 200,
+};
+
+describe("ContextMeterView localization", () => {
+  it("interpolates the providerless English fallback", () => {
+    expect(
+      fallbackContextTranslate("agentChat.contextMeter.summary", {
+        defaultValue: "Context {{percent}}% · {{totalTokens}}",
+        percent: 25,
+        totalTokens: "2.0k",
+      }),
+    ).toBe("Context 25% · 2.0k");
+  });
+
+  it("uses the supplied translator for its accessible label", () => {
+    const translate = (key: string, options: Record<string, unknown> = {}) => {
+      if (key === "agentChat.contextMeter.breakdown") return " AUFTEILUNG";
+      if (key === "agentChat.contextMeter.ariaLabel") {
+        return `Kontext ${options.percent}% ${options.totalTokens}${options.breakdown}`;
+      }
+      return String(options.defaultValue ?? key);
+    };
+
+    act(() => {
+      root.render(
+        <ContextMeterView
+          manifest={manifest}
+          contextWindow={1_200}
+          open={false}
+          onOpenChange={() => undefined}
+          translate={translate}
+        >
+          <div>Panel</div>
+        </ContextMeterView>,
+      );
+    });
+
+    expect(container.querySelector("button")?.getAttribute("aria-label")).toBe(
+      "Kontext 25% 300 AUFTEILUNG",
+    );
+  });
+});

package/src/context-ui/ContextMeter.tsx

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../ui/tooltip.js";
+import { cn } from "../utils.js";
+import { formatContextTokens } from "./format.js";
+import {
+  fallbackContextTranslate,
+  type ContextManifestViewData,
+  type ContextTranslate,
+} from "./types.js";
+
+function ContextDonut({ pct, advisory }: { pct: number; advisory: boolean }) {
+  const radius = 7.5;
+  const circumference = 2 * Math.PI * radius;
+  const displayPct = Math.max(3, Math.min(100, pct));
+  const dashOffset = circumference - (displayPct / 100) * circumference;
+  return (
+    <span className="relative flex size-5 items-center justify-center">
+      <svg aria-hidden="true" viewBox="0 0 20 20" className="-rotate-90 size-5">
+        <circle
+          cx="10"
+          cy="10"
+          r={radius}
+          className="stroke-muted"
+          fill="none"
+          strokeWidth="3"
+        />
+        <circle
+          cx="10"
+          cy="10"
+          r={radius}
+          className={cn(advisory ? "stroke-amber-500" : "stroke-[#00B5FF]")}
+          fill="none"
+          strokeLinecap="round"
+          strokeWidth="3"
+          strokeDasharray={circumference}
+          strokeDashoffset={dashOffset}
+        />
+      </svg>
+      <span className="absolute size-2 rounded-full bg-background" />
+    </span>
+  );
+}
+
+export function ContextMeterView({
+  manifest,
+  contextWindow,
+  open,
+  onOpenChange,
+  children,
+  translate = fallbackContextTranslate,
+}: {
+  manifest: ContextManifestViewData;
+  contextWindow: number;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  children: ReactNode;
+  translate?: ContextTranslate;
+}) {
+  const pct = Math.min(
+    100,
+    Math.round((manifest.totalTokens / contextWindow) * 100),
+  );
+  const { conversationTokens, systemTokens } = manifest;
+  return (
+    <TooltipProvider delayDuration={200}>
+      <Popover open={open} onOpenChange={onOpenChange}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <PopoverTrigger asChild>
+              <button
+                type="button"
+                aria-label={translate("agentChat.contextMeter.ariaLabel", {
+                  defaultValue:
+                    "Context {{percent}}%, {{totalTokens}}{{breakdown}}. Open Context X-Ray.",
+                  percent: pct,
+                  totalTokens: formatContextTokens(manifest.totalTokens),
+                  breakdown:
+                    systemTokens > 0
+                      ? translate("agentChat.contextMeter.breakdown", {
+                          defaultValue:
+                            " total: {{systemTokens}} system + {{conversationTokens}} conversation",
+                          systemTokens: formatContextTokens(systemTokens),
+                          conversationTokens:
+                            formatContextTokens(conversationTokens),
+                        })
+                      : "",
+                })}
+                className={cn(
+                  "flex size-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent/50 hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+                  open && "bg-accent/60 text-foreground",
+                )}
+              >
+                <ContextDonut pct={pct} advisory={!manifest.enforceable} />
+              </button>
+            </PopoverTrigger>
+          </TooltipTrigger>
+          <TooltipContent>
+            {translate("agentChat.contextMeter.summary", {
+              defaultValue: "Context {{percent}}% · {{totalTokens}}",
+              percent: pct,
+              totalTokens: formatContextTokens(manifest.totalTokens),
+            })}
+            {systemTokens > 0
+              ? translate("agentChat.contextMeter.summaryBreakdown", {
+                  defaultValue:
+                    " ({{systemTokens}} system + {{conversationTokens}} conversation)",
+                  systemTokens: formatContextTokens(systemTokens),
+                  conversationTokens: formatContextTokens(conversationTokens),
+                })
+              : ""}
+          </TooltipContent>
+        </Tooltip>
+        <PopoverContent
+          align="end"
+          side="top"
+          sideOffset={8}
+          className="w-[min(92vw,380px)] overflow-hidden border-border/70 p-0"
+        >
+          {children}
+        </PopoverContent>
+      </Popover>
+    </TooltipProvider>
+  );
+}

package/src/context-ui/ContextSegmentRow.tsx

@@ -0,0 +1,273 @@
+import { IconLock, IconPin, IconRotate2, IconX } from "@tabler/icons-react";
+import type { ReactNode } from "react";
+
+import { Popover, PopoverContent, PopoverTrigger } from "../ui/popover.js";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../ui/tooltip.js";
+import { cn } from "../utils.js";
+import { formatContextTokens } from "./format.js";
+import {
+  fallbackContextTranslate,
+  type ContextSegmentViewData,
+  type ContextTranslate,
+} from "./types.js";
+
+function statusLabel(
+  segment: ContextSegmentViewData,
+  translate: ContextTranslate,
+): string {
+  if (segment.protected)
+    return translate("agentChat.contextXray.status.protected", {
+      defaultValue: "Protected",
+    });
+  if (segment.status === "pinned")
+    return translate("agentChat.contextXray.status.pinned", {
+      defaultValue: "Pinned",
+    });
+  if (segment.status === "evicted")
+    return translate("agentChat.contextXray.status.evicted", {
+      defaultValue: "Evicted",
+    });
+  if (segment.status === "summarized")
+    return translate("agentChat.contextXray.status.summarized", {
+      defaultValue: "Summarized",
+    });
+  return translate("agentChat.contextXray.status.active", {
+    defaultValue: "Active",
+  });
+}
+
+export function SegmentProvenancePopoverView({
+  segment,
+  children,
+  translate = fallbackContextTranslate,
+}: {
+  segment: ContextSegmentViewData;
+  children: ReactNode;
+  translate?: ContextTranslate;
+}) {
+  return (
+    <Popover>
+      <PopoverTrigger asChild>{children}</PopoverTrigger>
+      <PopoverContent align="start" className="w-80 p-3">
+        <div className="space-y-2">
+          <div>
+            <div className="text-[11px] font-medium uppercase text-muted-foreground">
+              {translate("agentChat.contextXray.segment", {
+                defaultValue: "Segment",
+              })}
+            </div>
+            <div className="mt-0.5 break-words text-xs text-foreground">
+              {segment.label}
+            </div>
+          </div>
+          <div className="grid grid-cols-2 gap-2 text-[11px] text-muted-foreground">
+            <div>
+              <span className="block font-medium text-foreground">
+                {formatContextTokens(segment.tokenCount)}
+              </span>
+              {translate("agentChat.contextXray.tokens", {
+                defaultValue: "tokens",
+              })}
+              {segment.tokenMethod === "estimate"
+                ? translate("agentChat.contextXray.estimatedPrefix", {
+                    defaultValue: " estimated",
+                  })
+                : ""}
+            </div>
+            <div>
+              <span className="block font-medium text-foreground">
+                {statusLabel(segment, translate)}
+              </span>
+              {translate("agentChat.contextXray.currentStatus", {
+                defaultValue: "current status",
+              })}
+            </div>
+            <div>
+              <span className="block font-medium text-foreground">
+                {segment.msgIndex ?? "-"}
+              </span>
+              {translate("agentChat.contextXray.messageIndex", {
+                defaultValue: "message index",
+              })}
+            </div>
+            <div>
+              <span className="block font-medium text-foreground">
+                {segment.partIndex ?? "-"}
+              </span>
+              {translate("agentChat.contextXray.partIndex", {
+                defaultValue: "part index",
+              })}
+            </div>
+          </div>
+          {segment.protected ? (
+            <div className="rounded-md border border-border bg-muted/40 px-2 py-1.5 text-[11px] text-muted-foreground">
+              {translate("agentChat.contextXray.protectedDescription", {
+                defaultValue:
+                  "This segment is part of the active turn and cannot be evicted yet.",
+              })}
+            </div>
+          ) : null}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export function ContextSegmentRowView({
+  segment,
+  advisory,
+  onPin,
+  onEvict,
+  onRestore,
+  translate = fallbackContextTranslate,
+}: {
+  segment: ContextSegmentViewData;
+  advisory: boolean;
+  onPin: () => void;
+  onEvict: () => void;
+  onRestore: () => void;
+  translate?: ContextTranslate;
+}) {
+  const disabled = segment.protected || segment.status === "evicted";
+  return (
+    <div
+      tabIndex={0}
+      onKeyDown={(event) => {
+        if (event.key === "p") onPin();
+        if (event.key === "e" && !disabled) onEvict();
+        if (event.key === "u" && segment.status !== "active") onRestore();
+      }}
+      className={cn(
+        "group flex min-h-11 items-center gap-2 rounded-sm px-2 py-1.5 outline-none transition-colors hover:bg-accent/35 focus-visible:bg-accent/35 focus-visible:ring-1 focus-visible:ring-ring",
+        segment.status === "evicted" && "opacity-60",
+      )}
+    >
+      <SegmentProvenancePopoverView segment={segment} translate={translate}>
+        <button
+          type="button"
+          className="min-w-0 flex-1 text-start"
+          aria-label={translate("agentChat.contextXray.inspect", {
+            defaultValue: "Inspect {{name}}",
+            name: segment.label,
+          })}
+        >
+          <div
+            className={cn(
+              "truncate text-[13px] font-medium leading-5 text-foreground",
+              segment.status === "evicted" && "line-through",
+            )}
+          >
+            {segment.label}
+          </div>
+          <div className="flex items-center gap-1.5 text-[11px] text-muted-foreground">
+            <span>{formatContextTokens(segment.tokenCount)}</span>
+            {segment.tokenMethod === "estimate" ? <span>~</span> : null}
+            <span>·</span>
+            <span>{statusLabel(segment, translate)}</span>
+            {advisory ? (
+              <span>
+                ·{" "}
+                {translate("agentChat.contextXray.advisory", {
+                  defaultValue: "advisory",
+                })}
+              </span>
+            ) : null}
+          </div>
+        </button>
+      </SegmentProvenancePopoverView>
+      <div className="flex shrink-0 items-center gap-1 opacity-100 sm:opacity-0 sm:group-hover:opacity-100 sm:group-focus-within:opacity-100">
+        {segment.protected ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <span className="flex size-6 items-center justify-center rounded-md text-muted-foreground">
+                <IconLock className="h-3.5 w-3.5" />
+              </span>
+            </TooltipTrigger>
+            <TooltipContent>
+              {translate("agentChat.contextXray.protectedDuringTurn", {
+                defaultValue: "Protected during active turn",
+              })}
+            </TooltipContent>
+          </Tooltip>
+        ) : segment.status === "evicted" ||
+          segment.status === "summarized" ||
+          segment.status === "pinned" ? (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={onRestore}
+                className="flex size-6 items-center justify-center rounded-md text-muted-foreground hover:bg-background hover:text-foreground"
+                aria-label={
+                  segment.status === "pinned"
+                    ? translate("agentChat.contextXray.unpinSegment", {
+                        defaultValue: "Unpin segment",
+                      })
+                    : translate("agentChat.contextXray.restoreSegment", {
+                        defaultValue: "Restore segment",
+                      })
+                }
+              >
+                <IconRotate2 className="h-3.5 w-3.5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent>
+              {segment.status === "pinned"
+                ? translate("agentChat.contextXray.unpin", {
+                    defaultValue: "Unpin",
+                  })
+                : translate("agentChat.contextXray.restore", {
+                    defaultValue: "Restore",
+                  })}
+            </TooltipContent>
+          </Tooltip>
+        ) : (
+          <>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={onPin}
+                  className="flex size-6 items-center justify-center rounded-md text-muted-foreground hover:bg-background hover:text-foreground"
+                  aria-label={translate("agentChat.contextXray.pinSegment", {
+                    defaultValue: "Pin segment",
+                  })}
+                >
+                  <IconPin className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>
+                {translate("agentChat.contextXray.pin", {
+                  defaultValue: "Pin",
+                })}
+              </TooltipContent>
+            </Tooltip>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  type="button"
+                  onClick={onEvict}
+                  className="flex size-6 items-center justify-center rounded-md text-muted-foreground hover:bg-background hover:text-destructive"
+                  aria-label={translate("agentChat.contextXray.evictSegment", {
+                    defaultValue: "Evict segment",
+                  })}
+                >
+                  <IconX className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>
+                {advisory
+                  ? translate("agentChat.contextXray.recordEvictionIntent", {
+                      defaultValue: "Record eviction intent",
+                    })
+                  : translate("agentChat.contextXray.evict", {
+                      defaultValue: "Evict",
+                    })}
+              </TooltipContent>
+            </Tooltip>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/context-ui/ContextTreemap.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from "react";
+import { Treemap } from "recharts";
+
+import { contextGroupFill, formatContextTokens } from "./format.js";
+import type {
+  ContextSegmentViewData,
+  ContextSystemSectionViewData,
+  ContextTranslate,
+} from "./types.js";
+import { fallbackContextTranslate } from "./types.js";
+
+interface TreemapDatum {
+  name: string;
+  size: number;
+  group: string;
+  segmentId: string;
+}
+
+function TreemapContent(props: any) {
+  const { x, y, width, height, name, group, size } = props;
+  if (width < 8 || height < 8) return null;
+  const showLabel = width > 90 && height > 42;
+  return (
+    <g>
+      <rect
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        rx={3}
+        ry={3}
+        fill={contextGroupFill(group)}
+        stroke="var(--background)"
+        strokeWidth={2}
+      />
+      {showLabel ? (
+        <foreignObject
+          x={x + 6}
+          y={y + 6}
+          width={width - 12}
+          height={height - 12}
+        >
+          <div className="flex h-full flex-col justify-between overflow-hidden text-[11px] leading-tight text-white">
+            <div className="truncate font-medium">{name}</div>
+            <div className="text-white/85">{formatContextTokens(size)}</div>
+          </div>
+        </foreignObject>
+      ) : null}
+    </g>
+  );
+}
+
+export function ContextTreemapView({
+  segments,
+  systemSections = [],
+  onSelect,
+  translate = fallbackContextTranslate,
+}: {
+  segments: ContextSegmentViewData[];
+  systemSections?: ContextSystemSectionViewData[];
+  onSelect?: (segmentId: string) => void;
+  translate?: ContextTranslate;
+}) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [chartWidth, setChartWidth] = useState(0);
+  const data: TreemapDatum[] = segments
+    .filter((segment) => segment.status !== "evicted" && segment.tokenCount > 0)
+    .map((segment) => ({
+      name: segment.label,
+      size: segment.tokenCount,
+      group: segment.group,
+      segmentId: segment.segmentId,
+    }));
+  data.push(
+    ...systemSections
+      .filter((section) => section.tokenCount > 0)
+      .map((section) => ({
+        name: section.label,
+        size: section.tokenCount,
+        group: `System · ${section.governance}`,
+        segmentId: section.segmentId,
+      })),
+  );
+
+  useEffect(() => {
+    const element = containerRef.current;
+    if (!element) return;
+    const updateWidth = () =>
+      setChartWidth(Math.max(0, Math.floor(element.clientWidth - 8)));
+    updateWidth();
+    const observer =
+      typeof ResizeObserver !== "undefined"
+        ? new ResizeObserver(updateWidth)
+        : null;
+    observer?.observe(element);
+    window.addEventListener("resize", updateWidth);
+    return () => {
+      observer?.disconnect();
+      window.removeEventListener("resize", updateWidth);
+    };
+  }, []);
+
+  if (data.length === 0) {
+    return (
+      <div className="flex h-52 items-center justify-center rounded-md bg-muted/30 text-xs text-muted-foreground">
+        {translate("agentChat.contextXray.noActiveSegments", {
+          defaultValue: "No active segments",
+        })}
+      </div>
+    );
+  }
+  return (
+    <div ref={containerRef} className="h-56 min-w-0 rounded-md bg-muted/25 p-1">
+      {chartWidth > 0 ? (
+        <Treemap
+          width={chartWidth}
+          height={216}
+          data={data as any}
+          dataKey="size"
+          nameKey="name"
+          aspectRatio={4 / 3}
+          isAnimationActive={false}
+          content={<TreemapContent />}
+          onClick={(datum: any) => {
+            if (datum?.segmentId) onSelect?.(datum.segmentId);
+          }}
+        />
+      ) : null}
+    </div>
+  );
+}