@pyric/ui 0.1.0-alpha.11 → 0.1.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyric/ui",
-  "version": "0.1.0-alpha.11",
+  "version": "0.1.0-alpha.12",
   "license": "Apache-2.0",
   "homepage": "https://pyric.dev",
   "repository": {
@@ -77,6 +77,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -92,7 +93,7 @@
     "react": ">=19",
     "react-dom": ">=19",
     "firebase": ">=12",
-    "pyric": "^0.1.0-alpha.11"
+    "pyric": "^0.1.0-alpha.12"
   },
   "peerDependenciesMeta": {
     "@inbrowser/agent": {
@@ -108,8 +109,8 @@
     "fake-indexeddb": "^6.0.0",
     "firebase": "^12.12.0",
     "jsdom": "^29.1.1",
-    "pyric": "^0.1.0-alpha.11",
-    "pyric-admin": "^0.1.0-alpha.11",
+    "pyric": "^0.1.0-alpha.12",
+    "pyric-admin": "^0.1.0-alpha.12",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-test-renderer": "^19.2.6",

package/src/agents/ContextWindowUsage.tsx

@@ -0,0 +1,514 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type {
+  ContextWindowSnapshot,
+  SessionRequestUsage,
+  SessionTokenUsage,
+} from '@inbrowser/agent/usage';
+
+type ClassSlots = {
+  root?: string;
+  header?: string;
+  body?: string;
+  row?: string;
+  label?: string;
+  value?: string;
+  bar?: string;
+  segment?: string;
+  empty?: string;
+};
+
+export interface ContextWindowRingProps {
+  snapshot: ContextWindowSnapshot;
+  size?: number;
+  className?: string;
+  innerClassName?: string;
+  style?: CSSProperties;
+}
+
+export interface ContextWindowMeterProps {
+  snapshot: ContextWindowSnapshot;
+  onOpen?: () => void;
+  className?: string;
+  buttonClassName?: string;
+  tooltipClassName?: string;
+  ringClassName?: string;
+  ringInnerClassName?: string;
+  formatTokens?: (tokens: number) => string;
+}
+
+export interface TokenUsageInlineProps {
+  usage?: SessionTokenUsage;
+  className?: string;
+  labelClassName?: string;
+  valueClassName?: string;
+  formatTokens?: (tokens: number) => string;
+}
+
+export interface SessionSpendSummaryProps {
+  usage?: SessionTokenUsage;
+  currentContextTokens?: number;
+  className?: string;
+  slots?: ClassSlots;
+  formatTokens?: (tokens: number) => string;
+}
+
+export interface RequestUsageTimelineProps {
+  requests: readonly SessionRequestUsage[];
+  onOpenTool?: (messageId: string, callId: string) => void;
+  className?: string;
+  slots?: ClassSlots;
+  formatTokens?: (tokens: number) => string;
+  empty?: ReactNode;
+}
+
+export interface ContextWindowPanelProps {
+  snapshot: ContextWindowSnapshot;
+  onCompactNow?: () => void;
+  className?: string;
+  slots?: ClassSlots;
+  formatTokens?: (tokens: number) => string;
+}
+
+const STATUS_COLORS: Record<ContextWindowSnapshot['status'], string> = {
+  unknown: '#8b8b95',
+  low: '#a4d4a8',
+  medium: '#f0c36a',
+  high: '#f08a8a',
+  critical: '#ff5c7a',
+};
+
+export function ContextWindowRing({
+  snapshot,
+  size = 20,
+  className,
+  innerClassName,
+  style,
+}: ContextWindowRingProps) {
+  const pct = snapshot.percentFull === undefined
+    ? 0.28
+    : Math.max(0, Math.min(1, snapshot.percentFull));
+  const degrees = Math.max(10, Math.round(pct * 360));
+  const color = `var(--pyric-context-window-status-color, ${STATUS_COLORS[snapshot.status]})`;
+  const track = 'var(--pyric-context-window-track-color, #3a3a45)';
+  const innerSize = Math.max(8, size - Math.max(6, Math.round(size * 0.34)));
+  return (
+    <span
+      data-pyric-ui="context-window-ring"
+      data-status={snapshot.status}
+      data-basis={snapshot.basis}
+      className={className}
+      style={{
+        display: 'inline-grid',
+        placeItems: 'center',
+        borderRadius: '999px',
+        width: size,
+        height: size,
+        background: `conic-gradient(${color} ${degrees}deg, ${track} ${degrees}deg)`,
+        ...style,
+      }}
+      aria-hidden="true"
+    >
+      <span
+        data-pyric-ui="context-window-ring-inner"
+        className={innerClassName}
+        style={{
+          display: 'block',
+          borderRadius: '999px',
+          width: innerSize,
+          height: innerSize,
+          background: 'var(--pyric-context-window-inner-color, currentColor)',
+        }}
+      />
+    </span>
+  );
+}
+
+export function ContextWindowMeter({
+  snapshot,
+  onOpen,
+  className,
+  buttonClassName,
+  tooltipClassName,
+  ringClassName,
+  ringInnerClassName,
+  formatTokens = formatCompactTokens,
+}: ContextWindowMeterProps) {
+  const title = `Context window: ${formatPercent(snapshot)} · ${formatRatio(snapshot, formatTokens)}`;
+  return (
+    <span
+      data-pyric-ui="context-window-meter"
+      data-status={snapshot.status}
+      data-basis={snapshot.basis}
+      className={className}
+    >
+      <button
+        type="button"
+        onClick={onOpen}
+        className={buttonClassName}
+        aria-label="Open context window details"
+        title={title}
+      >
+        <ContextWindowRing
+          snapshot={snapshot}
+          size={20}
+          className={ringClassName}
+          innerClassName={ringInnerClassName}
+        />
+      </button>
+      <span
+        data-pyric-ui="context-window-meter-tooltip"
+        className={tooltipClassName}
+      >
+        <span data-pyric-ui="context-window-meter-percent">
+          {formatPercent(snapshot)}
+        </span>
+        <span data-pyric-ui="context-window-meter-ratio">
+          {formatRatio(snapshot, formatTokens)}
+        </span>
+      </span>
+    </span>
+  );
+}
+
+export function TokenUsageInline({
+  usage,
+  className,
+  labelClassName,
+  valueClassName,
+  formatTokens = formatCompactTokens,
+}: TokenUsageInlineProps) {
+  if (!usage) return null;
+  return (
+    <dl data-pyric-ui="token-usage-inline" className={className}>
+      <MetricTerm
+        label="input"
+        value={formatTokens(usage.inputTokens)}
+        labelClassName={labelClassName}
+        valueClassName={valueClassName}
+      />
+      <MetricTerm
+        label="output"
+        value={formatTokens(usage.outputTokens)}
+        labelClassName={labelClassName}
+        valueClassName={valueClassName}
+      />
+      {usage.cachedInputTokens > 0 ? (
+        <MetricTerm
+          label="cached"
+          value={formatTokens(usage.cachedInputTokens)}
+          labelClassName={labelClassName}
+          valueClassName={valueClassName}
+        />
+      ) : null}
+      {usage.reasoningTokens > 0 ? (
+        <MetricTerm
+          label="reasoning"
+          value={formatTokens(usage.reasoningTokens)}
+          labelClassName={labelClassName}
+          valueClassName={valueClassName}
+        />
+      ) : null}
+    </dl>
+  );
+}
+
+export function SessionSpendSummary({
+  usage,
+  currentContextTokens,
+  className,
+  slots,
+  formatTokens = formatCompactTokens,
+}: SessionSpendSummaryProps) {
+  if (!usage || usage.tokensTotal <= 0) return null;
+  const contextCopies =
+    usage.workMultiplier ??
+    (currentContextTokens && currentContextTokens > 0
+      ? usage.tokensTotal / currentContextTokens
+      : undefined);
+  return (
+    <section
+      data-pyric-ui="session-spend-summary"
+      className={className ?? slots?.root}
+    >
+      <div data-pyric-ui="session-spend-summary-header" className={slots?.header}>
+        <span data-pyric-ui="session-spend-summary-title">Overall session spend</span>
+        <span data-pyric-ui="session-spend-summary-total">
+          {formatTokens(usage.tokensTotal)}
+        </span>
+      </div>
+      <dl data-pyric-ui="session-spend-summary-body" className={slots?.body}>
+        <MetricTerm
+          label="turns"
+          value={usage.turns === null ? 'unknown' : usage.turns.toLocaleString()}
+          labelClassName={slots?.label}
+          valueClassName={slots?.value}
+        />
+        <MetricTerm
+          label="requests"
+          value={usage.requests === null ? 'unknown' : usage.requests.toLocaleString()}
+          labelClassName={slots?.label}
+          valueClassName={slots?.value}
+        />
+        <MetricTerm
+          label="average request"
+          value={usage.averageRequestTokens ? formatTokens(usage.averageRequestTokens) : 'n/a'}
+          labelClassName={slots?.label}
+          valueClassName={slots?.value}
+        />
+        <MetricTerm
+          label="context multiplier"
+          value={contextCopies ? `${formatMultiplier(contextCopies)}x` : 'n/a'}
+          labelClassName={slots?.label}
+          valueClassName={slots?.value}
+        />
+      </dl>
+      <TokenUsageInline
+        usage={usage}
+        className={slots?.row}
+        labelClassName={slots?.label}
+        valueClassName={slots?.value}
+        formatTokens={formatTokens}
+      />
+    </section>
+  );
+}
+
+export function RequestUsageTimeline({
+  requests,
+  onOpenTool,
+  className,
+  slots,
+  formatTokens = formatCompactTokens,
+  empty,
+}: RequestUsageTimelineProps) {
+  if (requests.length === 0) {
+    return (
+      <div
+        data-pyric-ui="request-usage-timeline-empty"
+        className={slots?.empty ?? className}
+      >
+        {empty ?? 'No request usage rows available.'}
+      </div>
+    );
+  }
+  return (
+    <ol data-pyric-ui="request-usage-timeline" className={className ?? slots?.root}>
+      {requests.map((request) => (
+        <li
+          key={request.id}
+          data-pyric-ui="request-usage-row"
+          data-usage-source={request.usageSource}
+          data-provider={request.providerId}
+          className={slots?.row}
+        >
+          <div data-pyric-ui="request-usage-row-header" className={slots?.header}>
+            <span data-pyric-ui="request-usage-row-title">
+              Request {request.iteration + 1}
+            </span>
+            <span data-pyric-ui="request-usage-row-total">
+              {formatTokens(request.tokensTotal)}
+            </span>
+          </div>
+          <SegmentBar
+            rows={[
+              ['fresh-input', request.freshInputTokens, '#8bb7ff'],
+              ['cached-input', request.cachedInputTokens, '#a4d4a8'],
+              ['visible-output', request.visibleOutputTokens, '#f0c36a'],
+              ['reasoning-output', request.reasoningTokens, '#c9a7ff'],
+            ]}
+            total={Math.max(1, request.tokensTotal)}
+            barClassName={slots?.bar}
+            segmentClassName={slots?.segment}
+          />
+          <dl data-pyric-ui="request-usage-row-metrics" className={slots?.body}>
+            <MetricTerm
+              label="input"
+              value={formatTokens(request.inputTokens)}
+              labelClassName={slots?.label}
+              valueClassName={slots?.value}
+            />
+            <MetricTerm
+              label="output"
+              value={formatTokens(request.outputTokens)}
+              labelClassName={slots?.label}
+              valueClassName={slots?.value}
+            />
+            <MetricTerm
+              label="messages"
+              value={request.messageCount.toLocaleString()}
+              labelClassName={slots?.label}
+              valueClassName={slots?.value}
+            />
+          </dl>
+          {onOpenTool && request.emittedToolCalls.length > 0 ? (
+            <div data-pyric-ui="request-usage-tools">
+              {request.emittedToolCalls.map((tool) => (
+                <button
+                  key={`${tool.messageId ?? 'unknown'}:${tool.callId ?? tool.name}`}
+                  type="button"
+                  data-pyric-ui="request-usage-tool"
+                  disabled={!tool.messageId || !tool.callId}
+                  onClick={() => {
+                    if (tool.messageId && tool.callId) onOpenTool(tool.messageId, tool.callId);
+                  }}
+                >
+                  {tool.name}
+                </button>
+              ))}
+            </div>
+          ) : null}
+        </li>
+      ))}
+    </ol>
+  );
+}
+
+export function ContextWindowPanel({
+  snapshot,
+  onCompactNow,
+  className,
+  slots,
+  formatTokens = formatCompactTokens,
+}: ContextWindowPanelProps) {
+  return (
+    <section
+      data-pyric-ui="context-window-panel"
+      data-status={snapshot.status}
+      data-basis={snapshot.basis}
+      className={className ?? slots?.root}
+    >
+      <header data-pyric-ui="context-window-panel-header" className={slots?.header}>
+        <ContextWindowRing snapshot={snapshot} size={56} />
+        <div>
+          <div data-pyric-ui="context-window-panel-percent">
+            {formatPercent(snapshot)}
+          </div>
+          <div data-pyric-ui="context-window-panel-ratio">
+            {formatRatio(snapshot, formatTokens)}
+          </div>
+        </div>
+      </header>
+      <SegmentBar
+        rows={snapshot.breakdown.map((row) => [row.id, row.tokens, row.color])}
+        total={Math.max(1, snapshot.usedTokens)}
+        barClassName={slots?.bar}
+        segmentClassName={slots?.segment}
+      />
+      <dl data-pyric-ui="context-window-breakdown" className={slots?.body}>
+        {snapshot.breakdown.map((row) => (
+          <MetricTerm
+            key={row.id}
+            label={row.label}
+            value={formatTokens(row.tokens)}
+            labelClassName={slots?.label}
+            valueClassName={slots?.value}
+          />
+        ))}
+      </dl>
+      <SessionSpendSummary
+        usage={snapshot.sessionUsage}
+        currentContextTokens={snapshot.usedTokens}
+        slots={slots}
+        formatTokens={formatTokens}
+      />
+      {onCompactNow ? (
+        <button
+          type="button"
+          data-pyric-ui="context-window-compact-action"
+          onClick={onCompactNow}
+        >
+          Compact now
+        </button>
+      ) : null}
+    </section>
+  );
+}
+
+function MetricTerm({
+  label,
+  value,
+  labelClassName,
+  valueClassName,
+}: {
+  label: string;
+  value: string;
+  labelClassName?: string;
+  valueClassName?: string;
+}) {
+  return (
+    <div data-pyric-ui="metric-term">
+      <dt data-pyric-ui="metric-label" className={labelClassName}>
+        {label}
+      </dt>
+      <dd data-pyric-ui="metric-value" className={valueClassName}>
+        {value}
+      </dd>
+    </div>
+  );
+}
+
+function SegmentBar({
+  rows,
+  total,
+  barClassName,
+  segmentClassName,
+}: {
+  rows: readonly (readonly [id: string, tokens: number, color: string])[];
+  total: number;
+  barClassName?: string;
+  segmentClassName?: string;
+}) {
+  const visibleRows = rows.filter(([, tokens]) => tokens > 0);
+  if (visibleRows.length === 0) return null;
+  return (
+    <div data-pyric-ui="token-segment-bar" className={barClassName}>
+      {visibleRows.map(([id, tokens, color]) => (
+        <span
+          key={id}
+          data-pyric-ui="token-segment"
+          data-segment={id}
+          className={segmentClassName}
+          style={{
+            display: 'inline-block',
+            width: `${Math.max(1, (tokens / total) * 100)}%`,
+            background: `var(--pyric-token-segment-${id}, ${color})`,
+          }}
+        />
+      ))}
+    </div>
+  );
+}
+
+function formatRatio(
+  snapshot: ContextWindowSnapshot,
+  formatTokens: (tokens: number) => string,
+): string {
+  const used = formatTokens(snapshot.usedTokens);
+  if (!snapshot.limitTokens) return `${used} tokens used`;
+  return `${used} / ${formatTokens(snapshot.limitTokens)} tokens used`;
+}
+
+function formatPercent(snapshot: ContextWindowSnapshot): string {
+  if (snapshot.percentFull === undefined) return 'limit unknown';
+  return `${Math.round(snapshot.percentFull * 100)}% full`;
+}
+
+function formatCompactTokens(tokens: number): string {
+  if (tokens < 1000) return String(Math.max(0, Math.round(tokens)));
+  if (tokens < 100_000) {
+    const k = tokens / 1000;
+    const value = k.toFixed(1);
+    return `${value.endsWith('.0') ? value.slice(0, -2) : value}k`;
+  }
+  if (tokens < 1_000_000) return `${Math.round(tokens / 1000)}k`;
+  // Millions tier — "14.59M", never "14586k".
+  const m = (tokens / 1_000_000).toFixed(2);
+  return `${m.endsWith('.00') ? m.slice(0, -3) : m}M`;
+}
+
+function formatMultiplier(value: number): string {
+  if (!Number.isFinite(value)) return 'n/a';
+  if (value < 10) return value.toFixed(1);
+  if (value < 100) return Math.round(value).toString();
+  return value.toLocaleString(undefined, { maximumFractionDigits: 0 });
+}

package/src/agents/EmptyState.tsx

@@ -0,0 +1,27 @@
+import type { ReactNode } from 'react';
+
+export interface EmptyStateProps {
+  /** Optional pre-rendered icon node — consumers pass whatever icon
+   *  primitive their app uses (Material Symbols span, lucide-react
+   *  component, plain SVG, …). */
+  icon?: ReactNode;
+  title: ReactNode;
+  body?: ReactNode;
+  className?: string;
+}
+
+/**
+ * Headless zero-state. Structural only: icon slot, title, optional
+ * body, all wrapped in a flex container marked
+ * `[data-pyric-ui="empty-state"]`. Consumers attach all visual
+ * styling.
+ */
+export function EmptyState({ icon, title, body, className }: EmptyStateProps) {
+  return (
+    <div data-pyric-ui="empty-state" className={className}>
+      {icon ? <span data-pyric-empty-icon>{icon}</span> : null}
+      <p data-pyric-empty-title>{title}</p>
+      {body ? <p data-pyric-empty-body>{body}</p> : null}
+    </div>
+  );
+}

package/src/agents/Fold.tsx

@@ -0,0 +1,64 @@
+import type { ReactNode } from 'react';
+
+export type FoldTone = 'normal' | 'error' | 'thought';
+
+export interface FoldProps {
+  /** Visible summary line, always rendered. */
+  header: ReactNode;
+  /** Optional right-aligned action (e.g. a copy button). Children
+   *  should `stopPropagation` so clicks don't toggle the fold. */
+  headerAction?: ReactNode;
+  /** Revealed when the user expands. */
+  children: ReactNode;
+  defaultOpen?: boolean;
+  /** Surfaced via `[data-pyric-fold-tone]` so consumers can tint the
+   *  summary or border based on semantic context (error / thought).
+   *  Defaults to `normal`. */
+  tone?: FoldTone;
+  /** Forwarded to the root `<details>` element. */
+  className?: string;
+  /** Forwarded to the `<summary>` element. */
+  summaryClassName?: string;
+  /** Forwarded to the body wrapper revealed when open. */
+  bodyClassName?: string;
+}
+
+/**
+ * Headless disclosure container — native `<details>` for keyboard /
+ * a11y. Ships zero visual styling. Consumers style via the three
+ * `className` slots or by selecting on:
+ *
+ *   [data-pyric-ui="fold"]             — root `<details>`
+ *   [data-pyric-ui="fold"][open]       — expanded state
+ *   [data-pyric-fold-tone="error"]     — error tint
+ *   [data-pyric-fold-tone="thought"]   — thought-stream tint
+ *   [data-pyric-fold-summary]          — clickable summary row
+ *   [data-pyric-fold-chevron]          — disclosure indicator slot
+ *   [data-pyric-fold-body]             — revealed body wrapper
+ */
+export function Fold({
+  header,
+  headerAction,
+  children,
+  defaultOpen = false,
+  tone = 'normal',
+  className,
+  summaryClassName,
+  bodyClassName,
+}: FoldProps) {
+  return (
+    <details
+      data-pyric-ui="fold"
+      data-pyric-fold-tone={tone}
+      open={defaultOpen}
+      className={className}
+    >
+      <summary data-pyric-fold-summary className={summaryClassName}>
+        <span data-pyric-fold-chevron aria-hidden="true" />
+        <span data-pyric-fold-header>{header}</span>
+        {headerAction ? <span data-pyric-fold-action>{headerAction}</span> : null}
+      </summary>
+      <div data-pyric-fold-body className={bodyClassName}>{children}</div>
+    </details>
+  );
+}

package/src/agents/Modal.tsx

@@ -0,0 +1,65 @@
+import { useEffect, type ReactNode } from 'react';
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  children: ReactNode;
+  ariaLabel?: string;
+  /** Forwarded to the root wrapper (covers the full viewport). */
+  className?: string;
+  /** Forwarded to the backdrop element. */
+  backdropClassName?: string;
+  /** Forwarded to the inner panel. */
+  panelClassName?: string;
+}
+
+/**
+ * Headless modal — provides behavior only (Escape-to-close, backdrop
+ * click, `aria-modal`). Consumers attach all visual styling via the
+ * three `className` slots or by selecting on the emitted data
+ * attributes:
+ *
+ *   [data-pyric-ui="modal"]            — root viewport wrapper
+ *   [data-pyric-modal-backdrop]        — clickable backdrop
+ *   [data-pyric-modal-panel]           — inner panel containing children
+ */
+export function Modal({
+  open,
+  onClose,
+  children,
+  ariaLabel,
+  className,
+  backdropClassName,
+  panelClassName,
+}: ModalProps) {
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label={ariaLabel}
+      data-pyric-ui="modal"
+      className={className}
+    >
+      <div
+        data-pyric-modal-backdrop
+        className={backdropClassName}
+        onClick={onClose}
+        aria-hidden="true"
+      />
+      <div data-pyric-modal-panel className={panelClassName}>
+        {children}
+      </div>
+    </div>
+  );
+}