@livelayer/react 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -89,6 +89,8 @@ export declare interface AgentInfo {
      * `branding.hideBranding`.
      */
     hideBranding?: boolean;
+    /** Page-vision capture config served by the agent-info endpoint (0.25.0+). */
+    pageVision?: PageVisionClientConfig | null;
 }
 
 export declare interface AgentInfoHandle {
@@ -400,6 +402,15 @@ export declare interface AvatarWidgetProps {
      *   "read_page"    — request_page_context + request_routes
      */
     capabilities?: AgentCapability[];
+    /**
+     * Page vision: capture page screenshots for the agent at flow start /
+     * route change / step change. Defaults to the server-side config from
+     * the agent-info endpoint; pass null to force-disable on this host.
+     * NOTE: must be referentially stable across renders — an inline object
+     * literal rebuilds the capture controller every render and silently
+     * disables dedup/republish. Prefer the server config or a useMemo/const.
+     */
+    pageVision?: PageVisionClientConfig | null;
     onConnect?: () => void;
     onDisconnect?: () => void;
     onTranscript?: (entries: TranscriptEntry[]) => void;
@@ -492,6 +503,8 @@ export declare interface CameraStateHandle {
     clearError: () => void;
 }
 
+export declare type CaptureReason = "flow_start" | "route_change" | "step_change";
+
 export { clearFieldRegistry }
 
 export declare function clearPageContextCache(): void;
@@ -932,6 +945,26 @@ export declare interface PageContext {
     flow?: FlowContext;
 }
 
+export declare interface PageVisionClientConfig {
+    enabled: boolean;
+    captureOn: CaptureReason[];
+    maxWidth: number;
+    jpegQuality: number;
+    upload: PageVisionUploadConfig;
+}
+
+/**
+ * Direct-to-Supabase Storage upload over plain fetch — no supabase-js in
+ * the widget bundle. Keys are random UUIDs (unguessable; spec §5) and the
+ * bucket has an hourly server-side purge, so the public URL is a
+ * short-lived, signed-ish link.
+ */
+declare interface PageVisionUploadConfig {
+    supabaseUrl: string;
+    anonKey: string;
+    bucket: string;
+}
+
 declare interface Props {
     children: ReactNode;
     /** Callback fired when an error is caught. Useful for telemetry. */
@@ -1120,6 +1153,37 @@ export declare function useMediaDevices(): MediaDevicesHandle;
 
 export declare function useMicrophoneState(opts?: MicrophoneStateOptions): MicrophoneStateHandle;
 
+/**
+ * Fires page captures on session connect (flow_start), route change, and
+ * flow step change. Captures wait one animation frame (so the new view
+ * has painted) plus an idle slot (so the html-to-image clone pass doesn't
+ * jank the transition). All real logic lives in PageVisionController.
+ */
+export declare function usePageVision(args: UsePageVisionArgs): void;
+
+declare interface UsePageVisionArgs {
+    /**
+     * Page-vision config from agent info (null/undefined until fetched).
+     * Must be referentially stable across renders — an inline literal
+     * rebuilds the controller every render and silently kills dedup and
+     * republishLast.
+     */
+    config: PageVisionClientConfig | null | undefined;
+    connected: boolean;
+    pathname: string;
+    /** Latest flow.currentStep the widget observed (multi-step forms). */
+    currentStep: number | undefined;
+    publishData: (payload: Record<string, unknown>) => void;
+    /**
+     * Carry-forward 1: becomes true once the agent is ready to receive
+     * messages (first listening/speaking state). On the first false→true
+     * transition of each connect cycle, republishLast() is called so the
+     * worker receives the flow_start envelope even if its listener
+     * registered after the original publish.
+     */
+    agentReady: boolean;
+}
+
 /**
  * Returns the current pathname, reactive to SPA navigation.
  * Pass `controlledPathname` to skip internal detection (recommended for