@elizaos/ui 2.0.0-beta.2 → 2.0.3-beta.2

package/agent-surface/AgentElementOverlay.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AgentElementOverlay — draws labelled indicators over every agent-addressable
+ * element when the view's registry has highlight mode on (toggled by the agent
+ * via the `set-highlight` capability, or by the user via the pill). Lets the
+ * user *see* exactly what the agent can target. Pointer-events are disabled so
+ * it never intercepts clicks.
+ */
+export declare function AgentElementOverlay(): import("react").ReactPortal | null;
+//# sourceMappingURL=AgentElementOverlay.d.ts.map

package/agent-surface/AgentElementOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentElementOverlay.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/AgentElementOverlay.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH,wBAAgB,mBAAmB,uCAmGlC"}

package/agent-surface/AgentElementOverlay.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AgentElementOverlay — draws labelled indicators over every agent-addressable
+ * element when the view's registry has highlight mode on (toggled by the agent
+ * via the `set-highlight` capability, or by the user via the pill). Lets the
+ * user *see* exactly what the agent can target. Pointer-events are disabled so
+ * it never intercepts clicks.
+ */
+import { useEffect, useState, useSyncExternalStore } from "react";
+import { createPortal } from "react-dom";
+import { useAgentSurface } from "./AgentSurfaceContext.hooks.js";
+const noopSubscribe = () => () => { };
+export function AgentElementOverlay() {
+    const surface = useAgentSurface();
+    const registry = surface?.registry ?? null;
+    // Re-render whenever the registry mutates (elements, status, highlight flag).
+    useSyncExternalStore(registry ? registry.subscribe : noopSubscribe, registry ? registry.getVersion : () => 0, () => 0);
+    // Re-measure on scroll / resize while highlighting so boxes track the layout.
+    const [, setTick] = useState(0);
+    const highlighting = registry?.isHighlighting() ?? false;
+    useEffect(() => {
+        if (!highlighting || typeof window === "undefined")
+            return;
+        let frameId = null;
+        const onChange = () => {
+            if (frameId !== null)
+                return;
+            frameId = window.requestAnimationFrame(() => {
+                frameId = null;
+                setTick((t) => t + 1);
+            });
+        };
+        const scrollOptions = { capture: true, passive: true };
+        window.addEventListener("scroll", onChange, scrollOptions);
+        window.addEventListener("resize", onChange);
+        return () => {
+            if (frameId !== null) {
+                window.cancelAnimationFrame(frameId);
+            }
+            window.removeEventListener("scroll", onChange, scrollOptions);
+            window.removeEventListener("resize", onChange);
+        };
+    }, [highlighting]);
+    if (!registry || !highlighting || typeof document === "undefined")
+        return null;
+    const snapshot = registry.snapshot();
+    const visible = snapshot.elements.filter((e) => e.visible && e.bounds);
+    return createPortal(_jsx("div", { "data-agent-overlay": true, "aria-hidden": true, style: {
+            position: "fixed",
+            inset: 0,
+            zIndex: 9000,
+            pointerEvents: "none",
+        }, children: visible.map((element) => {
+            const b = element.bounds;
+            if (!b)
+                return null;
+            return (_jsx("div", { "data-agent-indicator": element.id, style: {
+                    position: "fixed",
+                    left: b.x,
+                    top: b.y,
+                    width: b.width,
+                    height: b.height,
+                    border: element.focused
+                        ? "2px solid var(--accent, #ff7300)"
+                        : "1px dashed var(--accent, #ff7300)",
+                    borderRadius: 6,
+                    boxShadow: element.focused
+                        ? "0 0 0 2px var(--accent-muted, rgba(255,115,0,0.35))"
+                        : "none",
+                    boxSizing: "border-box",
+                }, children: _jsx("span", { style: {
+                        position: "absolute",
+                        top: -16,
+                        left: 0,
+                        fontSize: 10,
+                        lineHeight: "14px",
+                        padding: "0 4px",
+                        borderRadius: 4,
+                        color: "var(--accent-foreground, #fff)",
+                        background: "var(--accent, #ff7300)",
+                        whiteSpace: "nowrap",
+                        fontFamily: "var(--font-mono, monospace)",
+                    }, children: element.id }) }, element.id));
+        }) }), document.body);
+}

package/agent-surface/AgentSurfaceContext.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AgentSurfaceProvider — supplies the per-view ViewAgentRegistry to descendant
+ * elements via React context. Mounted by DynamicViewLoader around every view so
+ * any view that calls `useAgentElement` is automatically agent-controllable.
+ *
+ * The context object and useAgentSurface hook live in
+ * ./AgentSurfaceContext.hooks so this file can export only the provider
+ * component (React Fast Refresh-compatible).
+ */
+import { type ReactNode } from "react";
+import type { AgentViewType } from "./types";
+export interface AgentSurfaceProviderProps {
+    viewId: string;
+    viewType?: AgentViewType;
+    children: ReactNode;
+}
+export declare function AgentSurfaceProvider({ viewId, viewType, children, }: AgentSurfaceProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=AgentSurfaceContext.d.ts.map

package/agent-surface/AgentSurfaceContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSurfaceContext.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/AgentSurfaceContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,OAAO,CAAC;AAM1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACN,QAAgB,EAChB,QAAQ,GACT,EAAE,yBAAyB,2CA2B3B"}

package/agent-surface/AgentSurfaceContext.hooks.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AgentSurface context object + useAgentSurface hook. Kept out of
+ * AgentSurfaceContext.tsx so that file exports only the AgentSurfaceProvider
+ * component (React Fast Refresh-compatible).
+ */
+import type { ViewAgentRegistry } from "./registry";
+import type { AgentViewType } from "./types";
+export interface AgentSurfaceContextValue {
+    registry: ViewAgentRegistry;
+    viewId: string;
+    viewType: AgentViewType;
+}
+export declare const AgentSurfaceContext: import("react").Context<AgentSurfaceContextValue | null>;
+/** Returns the active view's registry, or null when rendered outside a view. */
+export declare function useAgentSurface(): AgentSurfaceContextValue | null;
+//# sourceMappingURL=AgentSurfaceContext.hooks.d.ts.map

package/agent-surface/AgentSurfaceContext.hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentSurfaceContext.hooks.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/AgentSurfaceContext.hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,eAAO,MAAM,mBAAmB,0DACsB,CAAC;AAEvD,gFAAgF;AAChF,wBAAgB,eAAe,IAAI,wBAAwB,GAAG,IAAI,CAEjE"}

package/agent-surface/AgentSurfaceContext.hooks.js

@@ -0,0 +1,11 @@
+/**
+ * AgentSurface context object + useAgentSurface hook. Kept out of
+ * AgentSurfaceContext.tsx so that file exports only the AgentSurfaceProvider
+ * component (React Fast Refresh-compatible).
+ */
+import { createContext, useContext } from "react";
+export const AgentSurfaceContext = createContext(null);
+/** Returns the active view's registry, or null when rendered outside a view. */
+export function useAgentSurface() {
+    return useContext(AgentSurfaceContext);
+}

package/agent-surface/AgentSurfaceContext.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * AgentSurfaceProvider — supplies the per-view ViewAgentRegistry to descendant
+ * elements via React context. Mounted by DynamicViewLoader around every view so
+ * any view that calls `useAgentElement` is automatically agent-controllable.
+ *
+ * The context object and useAgentSurface hook live in
+ * ./AgentSurfaceContext.hooks so this file can export only the provider
+ * component (React Fast Refresh-compatible).
+ */
+import { useEffect, useRef } from "react";
+import { AgentSurfaceContext, } from "./AgentSurfaceContext.hooks.js";
+import { getOrCreateViewRegistry, removeViewRegistry } from "./registry.js";
+export function AgentSurfaceProvider({ viewId, viewType = "gui", children, }) {
+    // The registry instance is owned for the lifetime of this provider.
+    const valueRef = useRef(null);
+    if (!valueRef.current ||
+        valueRef.current.viewId !== viewId ||
+        valueRef.current.viewType !== viewType) {
+        valueRef.current = {
+            registry: getOrCreateViewRegistry(viewId, viewType),
+            viewId,
+            viewType,
+        };
+    }
+    useEffect(() => {
+        // Re-assert the module-map entry on mount (it may have been created above
+        // during render) and tear it down on unmount.
+        getOrCreateViewRegistry(viewId, viewType);
+        return () => removeViewRegistry(viewId, viewType);
+    }, [viewId, viewType]);
+    return (_jsx(AgentSurfaceContext.Provider, { value: valueRef.current, children: children }));
+}

package/agent-surface/__e2e__/fixture.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Self-contained browser fixture for the agent-surface e2e. Renders a small
+ * "view" of agent-addressable controls inside an AgentSurfaceProvider and
+ * exposes the capability bridge on `window.__agentSurface` so a Playwright
+ * driver can act on it exactly like the floating pill would (list-elements,
+ * agent-fill, agent-click, set-highlight) — in a real browser, no app server.
+ */
+declare global {
+    interface Window {
+        __agentSurface?: (capability: string, params?: Record<string, unknown>) => unknown;
+    }
+}
+export {};
+//# sourceMappingURL=fixture.d.ts.map

package/agent-surface/__e2e__/fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../../../../src/agent-surface/__e2e__/fixture.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6EH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,cAAc,CAAC,EAAE,CACf,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC;KACd;CACF"}

package/agent-surface/__e2e__/fixture.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Self-contained browser fixture for the agent-surface e2e. Renders a small
+ * "view" of agent-addressable controls inside an AgentSurfaceProvider and
+ * exposes the capability bridge on `window.__agentSurface` so a Playwright
+ * driver can act on it exactly like the floating pill would (list-elements,
+ * agent-fill, agent-click, set-highlight) — in a real browser, no app server.
+ */
+import { useState } from "react";
+import { createRoot } from "react-dom/client";
+import { AgentElementOverlay } from "../AgentElementOverlay.js";
+import { AgentSurfaceProvider } from "../AgentSurfaceContext.js";
+import { handleAgentSurfaceCapability } from "../capabilities.js";
+import { AgentButton, AgentInput, IconTag } from "../components.js";
+import { getViewRegistry } from "../registry.js";
+import { useAgentElement } from "../useAgentElement.js";
+const VIEW = "e2e";
+function StatusPill({ label, on }) {
+    const { ref, agentProps } = useAgentElement({
+        id: `status-${label.toLowerCase()}`,
+        role: "status",
+        label: `${label} status`,
+        status: on ? "active" : "inactive",
+    });
+    return (_jsx("span", { ref: ref, ...agentProps, className: "rounded-full", style: {
+            padding: "2px 10px",
+            fontSize: 12,
+            background: on ? "#1f7a3f" : "#333",
+            color: "#fff",
+        }, children: label }));
+}
+function ViewBody() {
+    const [name, setName] = useState("");
+    const [count, setCount] = useState(0);
+    return (_jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 14 }, children: [_jsx("h2", { style: { margin: 0, fontSize: 18 }, children: "Demo view" }), _jsxs("div", { style: { display: "flex", gap: 8, alignItems: "center" }, children: [_jsx(StatusPill, { label: "Online", on: true }), _jsx(IconTag, { label: "finance", tone: "accent" }), _jsx(IconTag, { label: "error", tone: "danger", status: "error" })] }), _jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4 }, children: [_jsx("span", { style: { fontSize: 12, opacity: 0.8 }, children: "Name" }), _jsx(AgentInput, { agentId: "name", agentLabel: "Name", value: name, onChange: (e) => setName(e.target.value), style: { padding: "6px 10px", borderRadius: 6 } })] }), _jsxs("output", { "data-testid": "name-mirror", style: { fontSize: 13 }, children: ["name=", name || "(empty)"] }), _jsxs("div", { style: { display: "flex", gap: 8 }, children: [_jsx(AgentButton, { agentId: "increment", onClick: () => setCount((c) => c + 1), style: { padding: "6px 12px", borderRadius: 6 }, children: "Increment" }), _jsxs("output", { "data-testid": "count-mirror", style: { fontSize: 13 }, children: ["count=", count] })] })] }));
+}
+window.__agentSurface = (capability, params) => {
+    const registry = getViewRegistry(VIEW, "gui");
+    if (!registry)
+        throw new Error("registry not mounted");
+    return handleAgentSurfaceCapability(registry, capability, params);
+};
+const el = document.getElementById("root");
+if (el) {
+    createRoot(el).render(_jsx("div", { style: {
+            fontFamily: "system-ui, sans-serif",
+            color: "#eee",
+            background: "#0d1117",
+            padding: 28,
+            minHeight: "100vh",
+        }, children: _jsxs(AgentSurfaceProvider, { viewId: VIEW, viewType: "gui", children: [_jsx(ViewBody, {}), _jsx(AgentElementOverlay, {})] }) }));
+}

package/agent-surface/capabilities.d.ts

@@ -0,0 +1,20 @@
+/**
+ * capabilities — translates agent view-interact capability calls into
+ * ViewAgentRegistry operations. DynamicViewLoader routes any capability in
+ * AGENT_SURFACE_CAPABILITY_IDS here before falling back to selector handling.
+ */
+import type { ViewAgentRegistry } from "./registry";
+import { type AgentActionResult, type AgentElementSnapshot, type AgentSurfaceSnapshot } from "./types";
+export declare function isAgentSurfaceCapability(capability: string): boolean;
+/**
+ * Handle one agent-surface capability against a view's registry.
+ * Throws on a missing required parameter so the failure surfaces to the agent
+ * (rather than silently returning a default).
+ */
+export declare function handleAgentSurfaceCapability(registry: ViewAgentRegistry, capability: string, params: Record<string, unknown> | undefined): AgentSurfaceSnapshot | AgentElementSnapshot | AgentElementSnapshot[] | AgentActionResult | {
+    focusedId: string | null;
+    element: AgentElementSnapshot | null;
+} | {
+    highlighting: boolean;
+};
+//# sourceMappingURL=capabilities.d.ts.map

package/agent-surface/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/capabilities.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAEL,KAAK,iBAAiB,EAEtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EAC1B,MAAM,SAAS,CAAC;AAMjB,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAEzC,oBAAoB,GACpB,oBAAoB,GACpB,oBAAoB,EAAE,GACtB,iBAAiB,GACjB;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAA;CAAE,GAClE;IAAE,YAAY,EAAE,OAAO,CAAA;CAAE,CAoE5B"}

package/agent-surface/capabilities.js

@@ -0,0 +1,85 @@
+/**
+ * capabilities — translates agent view-interact capability calls into
+ * ViewAgentRegistry operations. DynamicViewLoader routes any capability in
+ * AGENT_SURFACE_CAPABILITY_IDS here before falling back to selector handling.
+ */
+import { AGENT_SURFACE_CAPABILITY_IDS, } from "./types.js";
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+export function isAgentSurfaceCapability(capability) {
+    return AGENT_SURFACE_CAPABILITY_IDS.has(capability);
+}
+/**
+ * Handle one agent-surface capability against a view's registry.
+ * Throws on a missing required parameter so the failure surfaces to the agent
+ * (rather than silently returning a default).
+ */
+export function handleAgentSurfaceCapability(registry, capability, params) {
+    switch (capability) {
+        case "list-elements": {
+            const snapshot = registry.snapshot();
+            const role = asString(params?.role);
+            const group = asString(params?.group);
+            let elements = snapshot.elements;
+            if (role)
+                elements = elements.filter((e) => e.role === role);
+            if (group)
+                elements = elements.filter((e) => e.group === group);
+            return elements;
+        }
+        case "get-agent-state":
+            return registry.snapshot();
+        case "describe-element": {
+            const id = asString(params?.id);
+            if (!id)
+                throw new Error("describe-element requires an `id` parameter");
+            const element = registry.describe(id);
+            if (!element)
+                throw new Error(`No element registered with id "${id}"`);
+            return element;
+        }
+        case "get-focus": {
+            const focusedId = registry.getFocusedId();
+            return {
+                focusedId,
+                element: focusedId ? registry.describe(focusedId) : null,
+            };
+        }
+        case "agent-click": {
+            const id = asString(params?.id);
+            if (!id)
+                throw new Error("agent-click requires an `id` parameter");
+            return registry.click(id);
+        }
+        case "agent-fill": {
+            const id = asString(params?.id);
+            const value = asString(params?.value);
+            if (!id)
+                throw new Error("agent-fill requires an `id` parameter");
+            if (value === null) {
+                throw new Error("agent-fill requires a string `value` parameter");
+            }
+            return registry.fill(id, value);
+        }
+        case "agent-focus": {
+            const id = asString(params?.id);
+            if (!id)
+                throw new Error("agent-focus requires an `id` parameter");
+            return registry.focus(id);
+        }
+        case "agent-scroll-to": {
+            const id = asString(params?.id);
+            if (!id)
+                throw new Error("agent-scroll-to requires an `id` parameter");
+            return registry.scrollTo(id);
+        }
+        case "set-highlight": {
+            const on = params?.on !== false;
+            registry.setHighlight(on);
+            return { highlighting: registry.isHighlighting() };
+        }
+        default:
+            throw new Error(`Unknown agent-surface capability "${capability}"`);
+    }
+}

package/agent-surface/components.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Agent-aware UI primitives. Thin wrappers that register themselves with the
+ * view's agent surface so the agent can target them, while rendering like any
+ * other element. Views can also use `useAgentElement` directly on bespoke
+ * markup — these cover the common control + tag cases.
+ */
+import type { ButtonHTMLAttributes, ComponentType, InputHTMLAttributes, ReactNode } from "react";
+import type { AgentElementRole } from "./types";
+type IconComponent = ComponentType<{
+    className?: string;
+    "aria-hidden"?: boolean;
+}>;
+export interface AgentButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Stable agent id, unique within the view. */
+    agentId: string;
+    /** Label the agent uses to target this button (defaults to text children). */
+    agentLabel?: string;
+    agentRole?: Extract<AgentElementRole, "button" | "toggle" | "tab" | "link">;
+    /** Status token rendered as `data-state` (e.g. "active", "loading"). */
+    agentStatus?: string;
+    agentGroup?: string;
+    agentDescription?: string;
+}
+export declare function AgentButton({ agentId, agentLabel, agentRole, agentStatus, agentGroup, agentDescription, children, ...rest }: AgentButtonProps): import("react/jsx-runtime").JSX.Element;
+export interface AgentInputProps extends InputHTMLAttributes<HTMLInputElement> {
+    agentId: string;
+    agentLabel: string;
+    agentRole?: Extract<AgentElementRole, "text-input" | "number-input">;
+    agentStatus?: string;
+    agentGroup?: string;
+    agentDescription?: string;
+}
+export declare function AgentInput({ agentId, agentLabel, agentRole, agentStatus, agentGroup, agentDescription, ...rest }: AgentInputProps): import("react/jsx-runtime").JSX.Element;
+declare const TONE_CLASSES: Record<string, string>;
+export interface IconTagProps {
+    /** Lucide (or any) icon component to render as the graphic. */
+    icon?: IconComponent;
+    label: ReactNode;
+    tone?: keyof typeof TONE_CLASSES;
+    /** Rendered as `data-state` and `data-status` so it counts as an indicator. */
+    status?: string;
+    className?: string;
+    title?: string;
+}
+/**
+ * IconTag — a compact, graphic-first chip (icon + label) used to replace bare
+ * text tags. The rounded-full pill + `data-status` make it register as a visual
+ * indicator in the view audit.
+ */
+export declare function IconTag({ icon: Icon, label, tone, status, className, title, }: IconTagProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=components.d.ts.map

package/agent-surface/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/components.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,SAAS,EACV,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhD,KAAK,aAAa,GAAG,aAAa,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,WAAW,gBACf,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IAC/C,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;IAC5E,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,UAAU,EACV,SAAoB,EACpB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,gBAAgB,2CAgBlB;AAED,MAAM,WAAW,eAAgB,SAAQ,mBAAmB,CAAC,gBAAgB,CAAC;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,EAAE,YAAY,GAAG,cAAc,CAAC,CAAC;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,UAAU,EACV,SAAwB,EACxB,WAAW,EACX,UAAU,EACV,gBAAgB,EAChB,GAAG,IAAI,EACR,EAAE,eAAe,2CAUjB;AAED,QAAA,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMxC,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,OAAO,YAAY,CAAC;IACjC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,EACtB,IAAI,EAAE,IAAI,EACV,KAAK,EACL,IAAgB,EAChB,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,YAAY,2CAgBd"}

package/agent-surface/components.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/utils.js";
+import { useAgentElement } from "./useAgentElement.js";
+export function AgentButton({ agentId, agentLabel, agentRole = "button", agentStatus, agentGroup, agentDescription, children, ...rest }) {
+    const label = agentLabel ?? (typeof children === "string" ? children : agentId);
+    const { ref, agentProps } = useAgentElement({
+        id: agentId,
+        role: agentRole,
+        label,
+        status: agentStatus,
+        group: agentGroup,
+        description: agentDescription,
+    });
+    return (_jsx("button", { ref: ref, type: "button", ...agentProps, ...rest, children: children }));
+}
+export function AgentInput({ agentId, agentLabel, agentRole = "text-input", agentStatus, agentGroup, agentDescription, ...rest }) {
+    const { ref, agentProps } = useAgentElement({
+        id: agentId,
+        role: agentRole,
+        label: agentLabel,
+        status: agentStatus,
+        group: agentGroup,
+        description: agentDescription,
+    });
+    return _jsx("input", { ref: ref, "aria-label": agentLabel, ...agentProps, ...rest });
+}
+const TONE_CLASSES = {
+    neutral: "bg-bg-muted text-text border-border",
+    accent: "bg-accent-subtle text-accent border-accent-muted",
+    success: "bg-status-success/15 text-status-success border-status-success/30",
+    warning: "bg-status-warning/15 text-status-warning border-status-warning/30",
+    danger: "bg-status-danger/15 text-status-danger border-status-danger/30",
+};
+/**
+ * IconTag — a compact, graphic-first chip (icon + label) used to replace bare
+ * text tags. The rounded-full pill + `data-status` make it register as a visual
+ * indicator in the view audit.
+ */
+export function IconTag({ icon: Icon, label, tone = "neutral", status, className, title, }) {
+    return (_jsxs("span", { "data-status": status ?? tone, "data-state": status ?? tone, title: title, className: cn("inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium", TONE_CLASSES[tone], className), children: [Icon ? _jsx(Icon, { className: "h-3 w-3", "aria-hidden": true }) : null, label] }));
+}

package/agent-surface/element-reporter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * AgentSurfaceElementReporter — reports a view's addressable element snapshot to
+ * the agent backend (POST /api/views/:id/elements) so the planner's "# Active
+ * View" awareness block can list elements and act on them by id WITHOUT a
+ * list-elements round-trip.
+ *
+ * Best-effort + debounced: it never throws into the view, and the server gates
+ * the report on the id matching the active (navigated-to) view, so a background
+ * or stale surface's report is simply dropped. Mounted inside AgentSurfaceProvider
+ * by the host wrappers (DynamicViewLoader, ShellViewAgentSurface) — not by the
+ * provider itself, so unit tests that render the provider directly stay offline.
+ *
+ * The payload builder and the subscribe/POST hook live in
+ * `element-reporter.hooks` so this module stays component-only (a React Fast
+ * Refresh requirement).
+ */
+/** Renders nothing; reports the surrounding view's elements to the backend. */
+export declare function AgentSurfaceElementReporter(): null;
+//# sourceMappingURL=element-reporter.d.ts.map

package/agent-surface/element-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-reporter.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/element-reporter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,+EAA+E;AAC/E,wBAAgB,2BAA2B,IAAI,IAAI,CAIlD"}

package/agent-surface/element-reporter.hooks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Element-reporter internals — the payload builder and the subscribe/POST hook.
+ *
+ * Split out of element-reporter.tsx so that module exports only the
+ * `AgentSurfaceElementReporter` component: React Fast Refresh requires a
+ * component-only module to hot-reload without forcing a full page reload.
+ */
+import type { ViewAgentRegistry } from "./registry";
+interface ReportedElement {
+    id: string;
+    role: string;
+    label: string;
+    value?: string;
+    focused?: boolean;
+}
+export declare function buildPayload(registry: ViewAgentRegistry): {
+    viewId: string;
+    elements: ReportedElement[];
+};
+/**
+ * Subscribe to a registry and push its element snapshot to the backend on mount
+ * and on every (debounced) change. Exported for direct/test use; the
+ * `AgentSurfaceElementReporter` component is the in-tree mount point.
+ */
+export declare function useAgentSurfaceElementReporter(registry: ViewAgentRegistry | null): void;
+export {};
+//# sourceMappingURL=element-reporter.hooks.d.ts.map

package/agent-surface/element-reporter.hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-reporter.hooks.d.ts","sourceRoot":"","sources":["../../../../../src/agent-surface/element-reporter.hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AASpD,UAAU,eAAe;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B,CAUA;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,iBAAiB,GAAG,IAAI,GACjC,IAAI,CAkDN"}

package/agent-surface/element-reporter.hooks.js

@@ -0,0 +1,79 @@
+/**
+ * Element-reporter internals — the payload builder and the subscribe/POST hook.
+ *
+ * Split out of element-reporter.tsx so that module exports only the
+ * `AgentSurfaceElementReporter` component: React Fast Refresh requires a
+ * component-only module to hot-reload without forcing a full page reload.
+ */
+import { useEffect } from "react";
+// The API client + url helper are loaded dynamically inside flush() (production
+// path only) so this module — re-exported from the widely-imported agent-surface
+// barrel and externalised into every plugin view bundle — stays import-light and
+// pulls no api/utils graph into its consumers.
+const REPORT_DEBOUNCE_MS = 400;
+export function buildPayload(registry) {
+    const snap = registry.snapshot();
+    const elements = snap.elements.map((e) => ({
+        id: e.id,
+        role: e.role,
+        label: e.label,
+        ...(typeof e.value === "string" ? { value: e.value } : {}),
+        ...(e.focused ? { focused: true } : {}),
+    }));
+    return { viewId: snap.viewId, elements };
+}
+/**
+ * Subscribe to a registry and push its element snapshot to the backend on mount
+ * and on every (debounced) change. Exported for direct/test use; the
+ * `AgentSurfaceElementReporter` component is the in-tree mount point.
+ */
+export function useAgentSurfaceElementReporter(registry) {
+    useEffect(() => {
+        // Inert without a registry, without fetch, or under the test runner (no
+        // backend to report to — mirrors the repo's NODE_ENV=test I/O convention).
+        const isTestEnv = typeof process !== "undefined" && process.env?.NODE_ENV === "test";
+        if (!registry || isTestEnv || typeof fetch === "undefined")
+            return;
+        let timer = null;
+        let cancelled = false;
+        const flush = () => {
+            const { viewId, elements } = buildPayload(registry);
+            // Nothing addressable yet (e.g. before any useAgentElement mounts, or a
+            // non-instrumented view) → skip the POST. Navigation clears server-side
+            // elements on view switch, so we never need to push an empty snapshot.
+            if (elements.length === 0)
+                return;
+            void (async () => {
+                try {
+                    const [{ fetchWithCsrf }, { resolveApiUrl }] = await Promise.all([
+                        import("../api/csrf-client.js"),
+                        import("../utils/asset-url.js"),
+                    ]);
+                    await fetchWithCsrf(resolveApiUrl(`/api/views/${encodeURIComponent(viewId)}/elements`), {
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" },
+                        body: JSON.stringify({ elements }),
+                    });
+                }
+                catch {
+                    // Best-effort: planner awareness is an optimization, never a hard dep.
+                }
+            })();
+        };
+        const schedule = () => {
+            if (cancelled)
+                return;
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(flush, REPORT_DEBOUNCE_MS);
+        };
+        schedule(); // initial snapshot
+        const unsubscribe = registry.subscribe(schedule);
+        return () => {
+            cancelled = true;
+            if (timer)
+                clearTimeout(timer);
+            unsubscribe();
+        };
+    }, [registry]);
+}

package/agent-surface/element-reporter.js

@@ -0,0 +1,24 @@
+/**
+ * AgentSurfaceElementReporter — reports a view's addressable element snapshot to
+ * the agent backend (POST /api/views/:id/elements) so the planner's "# Active
+ * View" awareness block can list elements and act on them by id WITHOUT a
+ * list-elements round-trip.
+ *
+ * Best-effort + debounced: it never throws into the view, and the server gates
+ * the report on the id matching the active (navigated-to) view, so a background
+ * or stale surface's report is simply dropped. Mounted inside AgentSurfaceProvider
+ * by the host wrappers (DynamicViewLoader, ShellViewAgentSurface) — not by the
+ * provider itself, so unit tests that render the provider directly stay offline.
+ *
+ * The payload builder and the subscribe/POST hook live in
+ * `element-reporter.hooks` so this module stays component-only (a React Fast
+ * Refresh requirement).
+ */
+import { useAgentSurface } from "./AgentSurfaceContext.hooks.js";
+import { useAgentSurfaceElementReporter } from "./element-reporter.hooks.js";
+/** Renders nothing; reports the surrounding view's elements to the backend. */
+export function AgentSurfaceElementReporter() {
+    const surface = useAgentSurface();
+    useAgentSurfaceElementReporter(surface?.registry ?? null);
+    return null;
+}