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

package/src/agents/PulsingDot.tsx

@@ -0,0 +1,28 @@
+export interface PulsingDotProps {
+  /** Forwarded to the outer wrapper. Consumers attach all visual
+   *  styling (size, animation, color) via this hook or by selecting
+   *  on `[data-pyric-ui="pulsing-dot"]`. */
+  className?: string;
+}
+
+/**
+ * Headless "live / streaming" indicator. Ships zero visual styling.
+ *
+ * Renders three nested spans so consumers can style ring + core
+ * independently:
+ *
+ *   <span data-pyric-ui="pulsing-dot">
+ *     <span data-pyric-pulse-ring />
+ *     <span data-pyric-pulse-core />
+ *   </span>
+ *
+ * Animation, color, and size are entirely consumer-defined.
+ */
+export function PulsingDot({ className }: PulsingDotProps) {
+  return (
+    <span data-pyric-ui="pulsing-dot" className={className}>
+      <span data-pyric-pulse-ring aria-hidden="true" />
+      <span data-pyric-pulse-core aria-hidden="true" />
+    </span>
+  );
+}

package/src/agents/inbrowser-agent-usage.d.ts

@@ -0,0 +1,141 @@
+declare module '@inbrowser/agent/usage' {
+  export type ContextWindowStatus = 'unknown' | 'low' | 'medium' | 'high' | 'critical';
+
+  export interface ContextWindowBreakdownRow {
+    id: string;
+    label: string;
+    tokens: number;
+    color: string;
+    estimated: boolean;
+  }
+
+  export interface ContextWindowCompactionStats {
+    compacted: boolean;
+    originalChars: number;
+    compactedChars: number;
+    bytesSaved: number;
+    turnsCompacted: number;
+    messagesCompacted: number;
+  }
+
+  export interface ContextWindowPricingEstimate {
+    totalUsd: number | null;
+    promptUsd: number | null;
+    cachedPromptUsd?: number | null;
+  }
+
+  export interface ContextWindowPricing {
+    current: ContextWindowPricingEstimate | null;
+    compacted: ContextWindowPricingEstimate | null;
+    savedCostUsd: number | null;
+  }
+
+  export interface ContextWindowCompactionPreview {
+    rawTokens: number;
+    currentTokens: number;
+    compactedTokens: number;
+    automaticSavedTokens: number;
+    manualSavedTokens: number;
+    savedTokens: number;
+    stats: ContextWindowCompactionStats;
+    retains: readonly string[];
+    loses: readonly string[];
+  }
+
+  export interface RequestInputComposition {
+    system: number;
+    history: number;
+    resentToolResults: number;
+    currentPrompt: number;
+    toolSchemas: number;
+  }
+
+  export interface SessionToolRef {
+    name: string;
+    callId: string;
+    messageId?: string;
+    tokens?: number;
+  }
+
+  export interface SessionRequestUsage {
+    id: string;
+    requestId: string;
+    turnId: string;
+    iteration: number;
+    ts?: number;
+    providerId?: string;
+    providerLabel?: string;
+    modelLabel?: string;
+    strategy?: string;
+    strategySource?: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    freshInputTokens: number;
+    visibleOutputTokens: number;
+    tokensTotal: number;
+    costUsd?: number;
+    usageSource: 'provider' | 'estimate';
+    composition: RequestInputComposition;
+    messageCount: number;
+    toolResultMessageCount: number;
+    toolNames: readonly string[];
+    toolSchemaNames: readonly string[];
+    emittedToolCalls: readonly SessionToolRef[];
+    resentToolResults: readonly SessionToolRef[];
+    cacheInsight?: string;
+  }
+
+  export interface SessionTurnUsage {
+    turnId: string;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    tokensTotal: number;
+    requests: number;
+    costUsd?: number;
+  }
+
+  export interface SessionUsageCategoryDetail {
+    label: string;
+    tokens: number;
+    share?: number;
+  }
+
+  export interface SessionTokenUsage {
+    turns: number | null;
+    requests: number | null;
+    tokensTotal: number;
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    reasoningTokens: number;
+    costUsdTotal?: number;
+    workMultiplier?: number;
+    averageRequestTokens?: number;
+    turnRows: readonly SessionTurnUsage[];
+    requestRows: readonly SessionRequestUsage[];
+    categoryDetails: Record<string, SessionUsageCategoryDetail>;
+    teachingNotes?: {
+      providerUsage: string;
+      estimatedComposition: string;
+      contextVsSpend: string;
+    };
+  }
+
+  export interface ContextWindowSnapshot {
+    basis: 'estimated-next-send';
+    usedTokens: number;
+    limitTokens: number | null;
+    percentFull?: number;
+    status: ContextWindowStatus;
+    breakdown: readonly ContextWindowBreakdownRow[];
+    compaction: ContextWindowCompactionStats;
+    compactionPreview: ContextWindowCompactionPreview;
+    pricing: ContextWindowPricing;
+    toolCount: number;
+    sessionUsage?: SessionTokenUsage;
+  }
+}

package/src/agents/index.ts

@@ -0,0 +1,28 @@
+/**
+ * `@pyric/ui/agents` — headless structural components for agentic UIs
+ * (chat surfaces, tool-call drill-ins, streaming state indicators).
+ *
+ * Matches the rest of `@pyric/ui`: zero shipped CSS. Components emit
+ * `data-pyric-*` attributes and accept `className` slots. Consumers
+ * bring their own design system (Tailwind, CSS modules, plain CSS)
+ * and attach styling via attribute selectors or class names.
+ */
+
+export { Fold, type FoldProps, type FoldTone } from './Fold.js';
+export { Modal, type ModalProps } from './Modal.js';
+export { EmptyState, type EmptyStateProps } from './EmptyState.js';
+export { PulsingDot, type PulsingDotProps } from './PulsingDot.js';
+export {
+  ContextWindowMeter,
+  ContextWindowPanel,
+  ContextWindowRing,
+  RequestUsageTimeline,
+  SessionSpendSummary,
+  TokenUsageInline,
+  type ContextWindowMeterProps,
+  type ContextWindowPanelProps,
+  type ContextWindowRingProps,
+  type RequestUsageTimelineProps,
+  type SessionSpendSummaryProps,
+  type TokenUsageInlineProps,
+} from './ContextWindowUsage.js';

package/src/auth/authApi.ts

@@ -0,0 +1,72 @@
+import { createContext, createElement, useContext, type ReactNode } from 'react';
+import { sandbox as authSandbox } from 'pyric/auth';
+
+/**
+ * The sandbox auth admin ops `useAuthUsers` drives, as an INJECTABLE bundle.
+ *
+ * WHY (same rationale as `@pyric/ui/firestore`'s FirestoreApi): the hook defaults
+ * to the in-process `pyric/auth` `sandbox` ops, but Pyric Studio's served mode
+ * drives the SAME ops over a SharedWorker (a parallel client over a MessagePort).
+ * Reading them from this context lets a consumer inject the worker client's fns
+ * so the hook operates on the live worker user DB without knowing the backend.
+ *
+ * The bundle is typed to the in-process signatures; a worker bundle is adapted
+ * (cast) at the Studio boundary. NOTE the worker `listUsers` is ASYNC (an RPC)
+ * whereas the in-process one is sync, so `useAuthUsers` tolerates a promise (it
+ * wraps the result in `Promise.resolve`).
+ *
+ * Default = the real `pyric/auth` sandbox ops, so every existing consumer is
+ * unchanged: no provider needed unless swapping the backend.
+ */
+export type AuthApi = Pick<
+  typeof authSandbox,
+  | 'listUsers'
+  | 'subscribeUsers'
+  | 'createUser'
+  | 'updateUser'
+  | 'deleteUser'
+  | 'clearUsers'
+  // Sign-in provider config (S-AUTH "Sign-in providers" section). Same shape
+  // as the user-DB ops above: a getter/setter plus a coarse subscription that
+  // re-reads on any change. `setAuthProviderConfig` ALSO fires a
+  // `provider_config_update` sandbox event, so a worker-backed bundle can ride
+  // the SAME event feed `subscribeUsers` already rides instead of standing up
+  // a second live channel — see `worker-live.ts`.
+  | 'getAuthProviderConfig'
+  | 'setAuthProviderConfig'
+  | 'subscribeAuthProviderConfig'
+>;
+
+const inProcessAuthApi: AuthApi = {
+  listUsers: authSandbox.listUsers,
+  subscribeUsers: authSandbox.subscribeUsers,
+  createUser: authSandbox.createUser,
+  updateUser: authSandbox.updateUser,
+  deleteUser: authSandbox.deleteUser,
+  clearUsers: authSandbox.clearUsers,
+  getAuthProviderConfig: authSandbox.getAuthProviderConfig,
+  setAuthProviderConfig: authSandbox.setAuthProviderConfig,
+  subscribeAuthProviderConfig: authSandbox.subscribeAuthProviderConfig,
+};
+
+const AuthApiContext = createContext<AuthApi>(inProcessAuthApi);
+
+/** Read the active auth API bundle (defaults to in-process `pyric/auth`). */
+export function useAuthApi(): AuthApi {
+  return useContext(AuthApiContext);
+}
+
+/**
+ * Provide an auth API bundle to the subtree. Pyric Studio supplies the
+ * in-process bundle for dev-seed review and the SharedWorker client bundle under
+ * `pyric dev --ui`.
+ */
+export function AuthApiProvider({
+  value,
+  children,
+}: {
+  value: AuthApi;
+  children: ReactNode;
+}) {
+  return createElement(AuthApiContext.Provider, { value }, children);
+}

package/src/auth/claims.ts

@@ -0,0 +1,63 @@
+/**
+ * Custom-claims validation for the add-account form — same checks and
+ * user-facing messages as the Firebase emulator UI (which reuses the
+ * Auth emulator's server validation: JSON-object shape, 1000-char cap,
+ * reserved-key deny list).
+ */
+
+/** Reserved JWT/OIDC keys the Auth emulator rejects as custom claims.
+ *  https://firebase.google.com/docs/auth/admin/create-custom-tokens */
+export const FORBIDDEN_CUSTOM_CLAIMS: readonly string[] = [
+  'iss',
+  'aud',
+  'sub',
+  'iat',
+  'exp',
+  'nbf',
+  'jti',
+  'nonce',
+  'azp',
+  'acr',
+  'amr',
+  'cnf',
+  'auth_time',
+  'firebase',
+  'at_hash',
+  'c_hash',
+];
+
+/** Serialized-length cap, matching the emulator's `CUSTOM_ATTRIBUTES_MAX_LENGTH`. */
+export const CUSTOM_CLAIMS_MAX_LENGTH = 1000;
+
+export type ClaimsValidationResult =
+  /** `claims` is `undefined` when the input was empty/whitespace. */
+  | { ok: true; claims: Record<string, unknown> | undefined }
+  | { ok: false; message: string };
+
+/**
+ * Validate the claims textarea's raw text. Empty input is valid (no
+ * claims). Messages match the emulator UI verbatim so users see the
+ * same wording in both tools.
+ */
+export function validateSerializedClaims(text: string): ClaimsValidationResult {
+  const trimmed = text.trim();
+  if (!trimmed) return { ok: true, claims: undefined };
+  if (trimmed.length > CUSTOM_CLAIMS_MAX_LENGTH) {
+    return { ok: false, message: 'Custom claims length must not exceed 1000 characters' };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return { ok: false, message: 'Custom claims must be a valid JSON object' };
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, message: 'Custom claims must be a valid JSON object' };
+  }
+  for (const key of FORBIDDEN_CUSTOM_CLAIMS) {
+    if (key in parsed) {
+      return { ok: false, message: `Custom claims must not have forbidden key: ${key}` };
+    }
+  }
+  return { ok: true, claims: parsed as Record<string, unknown> };
+}

package/src/auth/components/AuthProviderToggles.tsx

@@ -0,0 +1,147 @@
+import { useState, type FormEvent } from 'react';
+import { providerLabel } from '../providers.js';
+import type { AuthProviderConfigEntry } from '../hooks/useAuthProviderConfig.js';
+
+/** Providers always shown as a toggle row, regardless of whether the
+ *  backend has an explicit entry for them yet (an unconfigured provider
+ *  simply reads as disabled — same default the sandbox backend applies). */
+export const DEFAULT_KNOWN_PROVIDER_IDS = [
+  'password',
+  'anonymous',
+  'google.com',
+  'github.com',
+  'apple.com',
+  'microsoft.com',
+] as const;
+
+export interface AuthProviderTogglesProps {
+  /** Current config — usually `useAuthProviderConfig(auth).config`. */
+  config: AuthProviderConfigEntry[];
+  /** Fired when a toggle (known or custom) flips. */
+  onToggle: (providerId: string, enabled: boolean) => void;
+  /** Always-shown rows, in this order. Default: {@link DEFAULT_KNOWN_PROVIDER_IDS}. */
+  knownProviderIds?: readonly string[];
+  isLoading?: boolean;
+  error?: Error;
+  className?: string;
+}
+
+function isEnabled(config: AuthProviderConfigEntry[], providerId: string): boolean {
+  return config.find((c) => c.providerId === providerId)?.enabled ?? false;
+}
+
+/**
+ * Headless "Sign-in providers" toggle grid — the Authentication → Sign-in
+ * method surface. Known providers (password / anonymous / the built-in OAuth
+ * set) always render as a row; any OTHER provider already present in
+ * `config` (a custom OAuth id a host previously added) also gets a row. A
+ * free-text field lets a consumer enable an arbitrary OAuth provider id not
+ * in the known set — this is a SECTION, not a dialog: the add row lives
+ * inline, no modal.
+ *
+ * Fully headless: styling hangs off `data-pyric-*`, matching the rest of
+ * `@pyric/ui/auth` (`AuthUserList`, `AuthUserForm`, …). Data + mutation come
+ * from `useAuthProviderConfig`; this component only renders + fires events.
+ */
+export function AuthProviderToggles({
+  config,
+  onToggle,
+  knownProviderIds = DEFAULT_KNOWN_PROVIDER_IDS,
+  isLoading,
+  error,
+  className,
+}: AuthProviderTogglesProps) {
+  const [customId, setCustomId] = useState('');
+
+  const customEntries = config.filter(
+    (c) => !knownProviderIds.includes(c.providerId),
+  );
+
+  const handleAdd = (e: FormEvent) => {
+    e.preventDefault();
+    const id = customId.trim();
+    if (!id) return;
+    onToggle(id, true);
+    setCustomId('');
+  };
+
+  return (
+    <div className={className} data-pyric-ui="auth-provider-toggles">
+      {error ? (
+        <p data-pyric-provider-toggles-error role="alert">
+          {error.message}
+        </p>
+      ) : null}
+      <div role="list" aria-label="Sign-in providers" data-pyric-provider-toggle-list data-pyric-loading={isLoading ? '' : undefined}>
+        {knownProviderIds.map((providerId) => (
+          <ProviderToggleRow
+            key={providerId}
+            providerId={providerId}
+            enabled={isEnabled(config, providerId)}
+            onToggle={onToggle}
+          />
+        ))}
+        {customEntries.map((entry) => (
+          <ProviderToggleRow
+            key={entry.providerId}
+            providerId={entry.providerId}
+            enabled={entry.enabled}
+            onToggle={onToggle}
+            custom
+          />
+        ))}
+      </div>
+
+      <form data-pyric-add-provider-form onSubmit={handleAdd}>
+        <label data-pyric-field-label="custom-provider-id">
+          <span data-pyric-label-text>Add a custom OAuth provider</span>
+          <input
+            type="text"
+            data-pyric-field="custom-provider-id"
+            placeholder="e.g. yahoo.com"
+            value={customId}
+            onChange={(e) => setCustomId(e.target.value)}
+          />
+        </label>
+        <button type="submit" data-pyric-add-provider disabled={!customId.trim()}>
+          Add
+        </button>
+      </form>
+    </div>
+  );
+}
+
+function ProviderToggleRow({
+  providerId,
+  enabled,
+  onToggle,
+  custom,
+}: {
+  providerId: string;
+  enabled: boolean;
+  onToggle: (providerId: string, enabled: boolean) => void;
+  custom?: boolean;
+}) {
+  const inputId = `auth-provider-toggle-${providerId}`;
+  return (
+    <div
+      role="listitem"
+      data-pyric-provider-toggle
+      data-pyric-provider-id={providerId}
+      data-pyric-provider-enabled={enabled ? '' : undefined}
+      data-pyric-provider-custom={custom ? '' : undefined}
+    >
+      <label htmlFor={inputId} data-pyric-provider-toggle-label>
+        <input
+          id={inputId}
+          type="checkbox"
+          data-pyric-field="enabled"
+          checked={enabled}
+          onChange={(e) => onToggle(providerId, e.target.checked)}
+        />
+        <span data-pyric-provider-toggle-name>{providerLabel(providerId)}</span>
+        <span data-pyric-provider-toggle-id>{providerId}</span>
+      </label>
+    </div>
+  );
+}

package/src/auth/components/AuthSignInHelper.tsx

@@ -0,0 +1,197 @@
+import { useState, type FormEvent, type ReactNode } from 'react';
+import type { HelperState, NewIdentitySpec, SandboxIdentity } from '../controller.js';
+import { validateSerializedClaims } from '../claims.js';
+import { providerLabel } from '../providers.js';
+
+export interface AuthSignInHelperProps {
+  /** Snapshot from `useAuthFlowHelper`. Renders nothing while
+   *  `state.request` is null. */
+  state: HelperState;
+  /** Settle with an existing identity (wire to the hook's `pick`). */
+  onPick: (uid: string) => void;
+  /** Create + sign in as a new identity (wire to the hook's `add`). */
+  onAdd: (spec: NewIdentitySpec) => void;
+  /** Dismiss the flow (wire to the hook's `cancel`). Rejects the app's
+   *  sign-in promise with `auth/popup-closed-by-user`. */
+  onCancel: () => void;
+  /**
+   * Optional renderer for an account row's content. Default renders
+   * the display name (or email, or uid) plus the email when both
+   * exist. The row button + data attributes stay owned by the
+   * component; this slot only fills the button's children.
+   */
+  renderAccount?: (identity: SandboxIdentity) => ReactNode;
+  /** Heading text. Default: `Sign in with <provider label>`. */
+  title?: ReactNode;
+  /** Optional helper text rendered under the title
+   *  (`[data-pyric-helper-description]`). Default: none. */
+  description?: ReactNode;
+  /** Prefill for the add-account form (e.g. a host-suggested email).
+   *  Read once on mount; `claims` is the raw textarea JSON text. */
+  initialValues?: { email?: string; displayName?: string; claims?: string };
+  className?: string;
+}
+
+/**
+ * Headless emulator-style sign-in helper: an account picker over the
+ * sandbox's known identities plus an add-account form (email, display
+ * name, custom-claims JSON with emulator-grade validation messages).
+ *
+ * Ships zero styling. Structure is addressable via the
+ * `data-pyric-*` contract:
+ *
+ * - root: `[data-pyric-ui="auth-signin-helper"]`,
+ *   `[data-pyric-provider-id]`, `[data-pyric-auth-type]`
+ * - picker: `[data-pyric-account-list]` > `[data-pyric-account-entry]`
+ *   > `button[data-pyric-account-pick]`
+ * - form: `form[data-pyric-add-account-form]`, fields
+ *   `[data-pyric-field="email" | "display-name" | "claims"]`,
+ *   `[data-pyric-claims-error]` (role=alert),
+ *   `button[data-pyric-cancel]`, `button[data-pyric-submit]`
+ *
+ * Positioning is the consumer's job — render it inside your own modal
+ * or panel (the flow is host-UI-agnostic; only `onCancel` carries the
+ * popup-closed semantics).
+ */
+export function AuthSignInHelper({
+  state,
+  onPick,
+  onAdd,
+  onCancel,
+  renderAccount,
+  title,
+  description,
+  initialValues,
+  className,
+}: AuthSignInHelperProps) {
+  const [email, setEmail] = useState(initialValues?.email ?? '');
+  const [displayName, setDisplayName] = useState(initialValues?.displayName ?? '');
+  const [claims, setClaims] = useState(initialValues?.claims ?? '');
+  const [claimsError, setClaimsError] = useState<string | null>(null);
+
+  if (!state.request) return null;
+  const { providerId, authType } = state.request;
+  const label = providerLabel(providerId);
+
+  const reset = () => {
+    setEmail('');
+    setDisplayName('');
+    setClaims('');
+    setClaimsError(null);
+  };
+
+  const cancel = () => {
+    onCancel();
+    reset();
+  };
+
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    const result = validateSerializedClaims(claims);
+    if (!result.ok) {
+      setClaimsError(result.message);
+      return;
+    }
+    if (!email.trim()) return;
+    onAdd({
+      email: email.trim(),
+      displayName: displayName.trim() || undefined,
+      customClaims: result.claims,
+    });
+    reset();
+  };
+
+  return (
+    <section
+      className={className}
+      data-pyric-ui="auth-signin-helper"
+      data-pyric-provider-id={providerId}
+      data-pyric-auth-type={authType}
+      aria-label={`Sign in with ${label}`}
+    >
+      <header data-pyric-helper-header>
+        <h2 data-pyric-helper-title>{title ?? `Sign in with ${label}`}</h2>
+        {description != null && <p data-pyric-helper-description>{description}</p>}
+      </header>
+
+      {state.identities.length > 0 && (
+        <ul data-pyric-account-list>
+          {state.identities.map((identity) => (
+            <li
+              key={identity.uid}
+              data-pyric-account-entry
+              data-pyric-account-uid={identity.uid}
+              data-pyric-provider-id={identity.providerId}
+            >
+              <button
+                type="button"
+                data-pyric-account-pick
+                onClick={() => {
+                  onPick(identity.uid);
+                  reset();
+                }}
+              >
+                {renderAccount ? (
+                  renderAccount(identity)
+                ) : (
+                  <>
+                    <span data-pyric-account-name>
+                      {identity.displayName || identity.email || identity.uid}
+                    </span>
+                    {identity.email && identity.displayName ? (
+                      <span data-pyric-account-email>{identity.email}</span>
+                    ) : null}
+                  </>
+                )}
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+
+      <form data-pyric-add-account-form onSubmit={submit}>
+        <input
+          type="email"
+          data-pyric-field="email"
+          aria-label="Email"
+          placeholder="email@example.com"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+        />
+        <input
+          type="text"
+          data-pyric-field="display-name"
+          aria-label="Display name (optional)"
+          placeholder="Display name (optional)"
+          value={displayName}
+          onChange={(e) => setDisplayName(e.target.value)}
+        />
+        <textarea
+          data-pyric-field="claims"
+          data-pyric-claims-invalid={claimsError != null ? '' : undefined}
+          aria-label="Custom claims (optional)"
+          aria-invalid={claimsError != null || undefined}
+          placeholder={'Enter valid json, e.g. {"role":"admin"}'}
+          value={claims}
+          onChange={(e) => {
+            setClaims(e.target.value);
+            setClaimsError(null);
+          }}
+        />
+        {claimsError != null && (
+          <p role="alert" data-pyric-claims-error>
+            {claimsError}
+          </p>
+        )}
+        <footer data-pyric-helper-actions>
+          <button type="button" data-pyric-cancel onClick={cancel}>
+            Cancel
+          </button>
+          <button type="submit" data-pyric-submit disabled={!email.trim()}>
+            Sign in
+          </button>
+        </footer>
+      </form>
+    </section>
+  );
+}