begeniux 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,10 +1,14 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React$1 from 'react';
 
 type BehaviorEvent = {
     kind: "click";
     target: string;
     t: number;
+} | {
+    kind: "rage-click";
+    target: string;
+    count: number;
+    t: number;
 } | {
     kind: "scroll";
     depth: number;
@@ -19,76 +23,291 @@ type BehaviorEvent = {
     target: string;
     durationMs: number;
     t: number;
+} | {
+    kind: "focus";
+    target: string;
+    t: number;
+} | {
+    kind: "blur";
+    target: string;
+    durationMs: number;
+    t: number;
+} | {
+    kind: "input";
+    target: string;
+    t: number;
+} | {
+    kind: "submit";
+    target: string;
+    t: number;
+} | {
+    kind: "viewport-change";
+    width: number;
+    height: number;
+    t: number;
+} | {
+    kind: "error";
+    message: string;
+    t: number;
+} | {
+    kind: "custom";
+    name: string;
+    data: Record<string, unknown>;
+    t: number;
 };
-type BehaviorSummary = {
+type BehaviorSummary<TContext = {
+    route: string;
+}> = {
     clicks_per_min: number;
+    rage_clicks: number;
     avg_dwell_ms: number;
     scroll_depth: number;
     hover_count: number;
+    form_interactions: number;
+    errors_seen: number;
     events_seen: number;
-    page_context: {
-        route: string;
-        visible_product_ids: string[];
+    viewport: {
+        width: number;
+        height: number;
     };
+    custom: Record<string, number | string | boolean>;
+    page_context: TContext;
+};
+type Adaptation = {
+    kind: "set-css-var";
+    selector: string;
+    name: string;
+    value: string;
+} | {
+    kind: "add-class";
+    selector: string;
+    className: string;
+} | {
+    kind: "remove-class";
+    selector: string;
+    className: string;
+} | {
+    kind: "set-style";
+    selector: string;
+    property: string;
+    value: string;
+} | {
+    kind: "set-attribute";
+    selector: string;
+    name: string;
+    value: string;
+} | {
+    kind: "set-aria-label";
+    selector: string;
+    value: string;
 };
-type Variant = "decisive" | "deliberate" | "neutral";
-type AgentDirective = {
-    variant: Variant;
+type AdaptationPlan = {
+    adaptations: Adaptation[];
     confidence: number;
     reasoning: string;
+    meta?: Record<string, unknown>;
+};
+type AdaptInput<TContext = {
+    route: string;
+}> = {
+    summary: BehaviorSummary<TContext>;
+    designSystem: DesignSystem;
+    dom: {
+        visibleSelectors: string[];
+        route: string;
+    };
+};
+type ClassifyFn<TContext = {
+    route: string;
+}> = (input: AdaptInput<TContext>) => Promise<AdaptationPlan>;
+type CssVariableSpec = {
+    description: string;
+    type: "color";
+    defaultValue?: string;
+} | {
+    description: string;
+    type: "length";
+    defaultValue?: string;
+} | {
+    description: string;
+    type: "number";
+    range?: [number, number];
+    defaultValue?: string;
+} | {
+    description: string;
+    type: "string";
+    defaultValue?: string;
+} | {
+    description: string;
+    type: "enum";
+    values: string[];
+    defaultValue?: string;
+};
+type DesignSystem = {
+    cssVariables?: Record<string, CssVariableSpec>;
+    classes?: Record<string, string>;
+    examples?: AdaptationPlan[];
+};
+type ScopeOpts = {
+    allow?: string[];
+    deny?: string[];
+};
+type BehaviorListener = {
+    attach: (target: HTMLElement, push: (e: BehaviorEvent) => void) => () => void;
+};
+type BeGenContextValue<TContext = {
+    route: string;
+}> = {
+    summary: BehaviorSummary<TContext> | null;
+    lastPlan: AdaptationPlan | null;
+    appliedAdaptations: ReadonlyArray<Adaptation>;
+    recentEvents: ReadonlyArray<BehaviorEvent>;
+    /**
+     * Apply an AdaptationPlan via the provider's engine. Used by external
+     * adapters (e.g. CopilotKit frontend tool handler) that source plans
+     * outside the provider's `classify` loop.
+     */
+    applyPlan: (plan: AdaptationPlan) => void;
+    /** Read-only access to the active design system. */
+    getDesignSystem: () => DesignSystem;
 };
-type ClassifyFn = (summary: BehaviorSummary) => Promise<AgentDirective>;
-
-type BeGenContextValue = {
-    variant: Variant;
-    directive: AgentDirective | null;
-    summary: BehaviorSummary | null;
-    setVariant: (v: Variant) => void;
-    setDirective: (d: AgentDirective) => void;
-    setSummary: (s: BehaviorSummary) => void;
-};
-declare function BeGenProvider({ children }: {
-    children: React$1.ReactNode;
-}): react_jsx_runtime.JSX.Element;
 
-type BeGenSurfaceProps = {
-    variants: Record<Variant, React$1.ComponentType<any>>;
-    classify: ClassifyFn;
-    variantProps?: Record<string, any>;
-    pageContext: BehaviorSummary["page_context"];
-    seedPersona?: "decisive" | "deliberate";
+type BeGenProviderProps<TContext = {
+    route: string;
+}> = {
+    /** The agent's vocabulary — what CSS variables and classes it may emit. */
+    designSystem: DesignSystem;
+    /** Per-page state forwarded into every BehaviorSummary. */
+    pageContext: TContext;
+    /**
+     * Single-pass agent. Receives behavior + DOM + design system, returns a plan.
+     * If omitted, the provider does NOT call any agent — it only tracks behavior
+     * and exposes summaries via context. (Pair with createCopilotKitAdapter or
+     * createHttpAdapter for real adaptation.)
+     */
+    classify?: ClassifyFn<TContext>;
+    /** Restrict where the agent's adaptations may target. */
+    scope?: ScopeOpts;
+    /** Minimum ms between agent calls. Default 5000. */
     rateLimitMs?: number;
-    className?: string;
-    style?: React$1.CSSProperties;
-    children?: never;
+    /** Don't trigger an agent call until at least this many events have flushed since the last call. Default 5. */
+    triggerEveryEvents?: number;
+    /** Tracker idle-flush window. */
+    flushAfterMs?: number;
+    /** Tracker count-flush. */
+    flushEveryEvents?: number;
+    /** Tracker ring-buffer cap. */
+    bufferSize?: number;
+    /** Plug-in event sources. */
+    customListeners?: BehaviorListener[];
+    /** Element to scope listeners to. Default: document.body. */
+    containerRef?: React$1.RefObject<HTMLElement | null>;
+    /** Pre-canned events injected on mount (for demos). */
+    seedTrace?: BehaviorEvent[];
+    children: React$1.ReactNode;
 };
-declare function BeGenSurface(props: BeGenSurfaceProps): react_jsx_runtime.JSX.Element;
+declare function useBeGenContext<TContext = {
+    route: string;
+}>(): BeGenContextValue<TContext>;
+declare function BeGenProvider<TContext = {
+    route: string;
+}>(props: BeGenProviderProps<TContext>): React$1.ReactElement;
 
-type UseBehaviorTrackerOpts = {
-    containerRef: React.RefObject<HTMLElement>;
+type UseBehaviorTrackerOpts<TContext = {
+    route: string;
+}> = {
+    /** DOM element to scope listeners to. Defaults to document.body. */
+    containerRef?: React.RefObject<HTMLElement | null>;
+    /** Flush after this many events. Default 10. */
     flushEveryEvents?: number;
+    /** Flush after this many ms of idle. Default 5000. */
     flushAfterMs?: number;
+    /** Ring buffer cap. Default 50. */
     bufferSize?: number;
-    onFlush: (summary: BehaviorSummary) => void;
-    pageContext: BehaviorSummary["page_context"];
+    /** Called on every flush with the computed summary. */
+    onFlush: (summary: BehaviorSummary<TContext>) => void;
+    /** Page context (route, etc.) — included in every summary. */
+    pageContext: TContext;
+    /** Optional pre-canned events injected on mount. */
     seedTrace?: BehaviorEvent[];
+    /** Plug-in event sources beyond the built-ins. */
+    customListeners?: BehaviorListener[];
 };
-declare function useBehaviorTracker(opts: UseBehaviorTrackerOpts): {
+declare function useBehaviorTracker<TContext = {
+    route: string;
+}>(opts: UseBehaviorTrackerOpts<TContext>): {
     recentEvents: BehaviorEvent[];
 };
 
-declare function useBeGenContext(): BeGenContextValue;
-
-type CreateGeminiClassifierOpts = {
-    apiKey: string;
-    model?: string;
-    endpoint?: string;
-    fetchImpl?: typeof fetch;
+type AdaptationEngineEvent = {
+    kind: "applied";
+    adaptation: Adaptation;
+    matched: number;
+} | {
+    kind: "skipped";
+    adaptation: Adaptation;
+    reason: string;
+} | {
+    kind: "reverted";
+    count: number;
+};
+type AdaptationEngineOpts = {
+    root: HTMLElement;
+    scope?: ScopeOpts;
+    onEvent?: (e: AdaptationEngineEvent) => void;
 };
-declare function createGeminiClassifier(opts: CreateGeminiClassifierOpts): ClassifyFn;
+declare class AdaptationEngine {
+    private root;
+    private scope;
+    private onEvent?;
+    private revertLog;
+    private appliedSnapshot;
+    constructor(opts: AdaptationEngineOpts);
+    /** Apply a plan. Reverts the previous plan first so mutations don't accumulate. */
+    apply(plan: AdaptationPlan): void;
+    /** Roll back every adaptation applied since the last revertAll. */
+    revertAll(): void;
+    /** Read-only view of currently applied adaptations (for telemetry). */
+    getApplied(): ReadonlyArray<Adaptation>;
+    private applyOne;
+    private resolveTargets;
+    private selectorMatchesPattern;
+    private applyToElement;
+}
 
-declare function createHeuristicClassifier(): ClassifyFn;
+type DomSnapshotOpts = {
+    /** Maximum number of selectors to return (default 50). */
+    maxSelectors?: number;
+    /** Scope filter — only include elements whose selectors match allow / not deny. */
+    scope?: ScopeOpts;
+};
+/**
+ * Walk the visible DOM under `root` and return a deduplicated list of
+ * stable CSS selectors the agent can use. Prefers semantic anchors
+ * (id, data-* attributes, role, semantic tag names) over class soup.
+ */
+declare function snapshotVisibleSelectors(root: HTMLElement, opts?: DomSnapshotOpts): string[];
 
-declare const PERSONAS: Record<"decisive" | "deliberate", BehaviorEvent[]>;
+type HttpAdapterOpts = {
+    /** Endpoint that accepts POST {AdaptInput} and returns AdaptationPlan. */
+    url: string;
+    /** Extra headers (auth, etc.). */
+    headers?: Record<string, string>;
+    /** Optional fetch override (testing / SSR / proxy). */
+    fetchImpl?: typeof fetch;
+    /** Abort the request after this many ms. Default 8000. */
+    timeoutMs?: number;
+    /** Custom request body shaper if your endpoint expects a different envelope. */
+    bodyTransform?: (input: AdaptInput) => unknown;
+    /** Custom response shaper if your endpoint returns a different envelope. */
+    responseTransform?: (raw: unknown) => AdaptationPlan;
+};
+/**
+ * Generic transport. Posts {summary, designSystem, dom} to the given URL and
+ * expects an AdaptationPlan back. Use this when you have a custom API route
+ * (Next.js, Hono, Express, anything) that calls your LLM server-side and
+ * shapes the result into the contract.
+ */
+declare function createHttpAdapter(opts: HttpAdapterOpts): ClassifyFn;
 
-export { type AgentDirective, type BeGenContextValue, BeGenProvider, BeGenSurface, type BeGenSurfaceProps, type BehaviorEvent, type BehaviorSummary, type ClassifyFn, type CreateGeminiClassifierOpts, PERSONAS, type UseBehaviorTrackerOpts, type Variant, createGeminiClassifier, createHeuristicClassifier, useBeGenContext, useBehaviorTracker };
+export { type AdaptInput, type Adaptation, AdaptationEngine, type AdaptationEngineEvent, type AdaptationEngineOpts, type AdaptationPlan, type BeGenContextValue, BeGenProvider, type BeGenProviderProps, type BehaviorEvent, type BehaviorListener, type BehaviorSummary, type ClassifyFn, type CssVariableSpec, type DesignSystem, type DomSnapshotOpts, type HttpAdapterOpts, type ScopeOpts, type UseBehaviorTrackerOpts, createHttpAdapter, snapshotVisibleSelectors, useBeGenContext, useBehaviorTracker };