hypha-debugger 0.1.1 → 0.1.3

package/dist/page-controller/actions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Element interaction actions: click, input, select, scroll.
+ * Adapted from @page-agent/page-controller (MIT License).
+ */
+import type { InteractiveElementDomNode } from "./types.js";
+export declare function getElementByIndex(selectorMap: Map<number, InteractiveElementDomNode>, index: number): HTMLElement;
+export declare function scrollIntoViewIfNeeded(element: HTMLElement): Promise<void>;
+export declare function clickElement(element: HTMLElement): Promise<void>;
+export declare function inputTextElement(element: HTMLElement, text: string): Promise<void>;
+export declare function selectOptionElement(selectElement: HTMLSelectElement, optionText: string): Promise<void>;
+export declare function scrollVertically(down: boolean, scroll_amount: number, element?: HTMLElement | null): Promise<string>;
+export declare function scrollHorizontally(right: boolean, scroll_amount: number, element?: HTMLElement | null): Promise<string>;

package/dist/page-controller/dom.d.ts

@@ -0,0 +1,31 @@
+import type { FlatDomTree, InteractiveElementDomNode } from "./types.js";
+export declare function resolveViewportExpansion(viewportExpansion?: number): number;
+export interface DomConfig {
+    viewportExpansion?: number;
+    interactiveBlacklist?: (Element | (() => Element))[];
+    interactiveWhitelist?: (Element | (() => Element))[];
+    includeAttributes?: string[];
+    highlightOpacity?: number;
+    highlightLabelOpacity?: number;
+}
+export declare function getFlatTree(config: DomConfig): FlatDomTree;
+interface TreeNode {
+    type: "text" | "element";
+    parent: TreeNode | null;
+    children: TreeNode[];
+    isVisible: boolean;
+    text?: string;
+    tagName?: string;
+    attributes?: Record<string, string>;
+    isInteractive?: boolean;
+    isTopElement?: boolean;
+    isNew?: boolean;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+}
+export declare function flatTreeToString(flatTree: FlatDomTree, includeAttributes?: string[]): string;
+export declare const getAllTextTillNextClickableElement: (node: TreeNode, maxDepth?: number) => string;
+export declare function getSelectorMap(flatTree: FlatDomTree): Map<number, InteractiveElementDomNode>;
+export declare function getElementTextMap(simplifiedHTML: string): Map<number, string>;
+export declare function cleanUpHighlights(): void;
+export {};

package/dist/page-controller/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * PageController: manages DOM state and element interactions.
+ * Adapted from @page-agent/page-controller (MIT License).
+ *
+ * This wraps the smart DOM analysis (interactive element detection,
+ * indexed element map) and provides an API for external agents.
+ */
+import * as dom from "./dom.js";
+export interface PageControllerConfig extends dom.DomConfig {
+}
+export interface BrowserState {
+    url: string;
+    title: string;
+    header: string;
+    content: string;
+    footer: string;
+    element_count: number;
+}
+export interface ActionResult {
+    success: boolean;
+    message: string;
+}
+export declare class PageController {
+    private config;
+    private flatTree;
+    private selectorMap;
+    private elementTextMap;
+    private simplifiedHTML;
+    private isIndexed;
+    constructor(config?: PageControllerConfig);
+    /**
+     * Get structured browser state for LLM consumption.
+     * Builds the DOM tree, highlights interactive elements, and returns
+     * a simplified text representation with numeric indices.
+     */
+    getBrowserState(): Promise<BrowserState>;
+    /**
+     * Update DOM tree, returns simplified HTML for LLM.
+     */
+    updateTree(): Promise<string>;
+    cleanUpHighlights(): Promise<void>;
+    private assertIndexed;
+    /** Clean up highlights after performing an action. */
+    private cleanUpAfterAction;
+    clickElement(index: number): Promise<ActionResult>;
+    inputText(index: number, text: string): Promise<ActionResult>;
+    selectOption(index: number, optionText: string): Promise<ActionResult>;
+    scroll(options: {
+        direction: "up" | "down" | "left" | "right";
+        amount?: number;
+        index?: number;
+    }): Promise<ActionResult>;
+    dispose(): void;
+}

package/dist/page-controller/page-info.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Page info utilities: viewport, scroll position, page dimensions.
+ * Adapted from @page-agent/page-controller (MIT License).
+ */
+export interface PageScrollInfo {
+    viewport_width: number;
+    viewport_height: number;
+    page_width: number;
+    page_height: number;
+    scroll_x: number;
+    scroll_y: number;
+    pixels_above: number;
+    pixels_below: number;
+    pages_above: number;
+    pages_below: number;
+    total_pages: number;
+    current_page_position: number;
+    pixels_left: number;
+    pixels_right: number;
+}
+export declare function getPageScrollInfo(): PageScrollInfo;

package/dist/page-controller/types.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Flat DOM tree types, adapted from @page-agent/page-controller.
+ * Original: https://github.com/alibaba/page-agent (MIT License)
+ */
+export interface FlatDomTree {
+    rootId: string;
+    map: Record<string, DomNode>;
+}
+export type DomNode = TextDomNode | ElementDomNode | InteractiveElementDomNode;
+export interface TextDomNode {
+    type: "TEXT_NODE";
+    text: string;
+    isVisible: boolean;
+    [key: string]: unknown;
+}
+export interface ElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isNew?: boolean;
+    isInteractive?: false;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+    [key: string]: unknown;
+}
+export interface InteractiveElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isInteractive: true;
+    highlightIndex: number;
+    ref: HTMLElement;
+    [key: string]: unknown;
+}

package/dist/services/page-controller.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Get the current browser state: page info, scroll position, and a
+ * simplified HTML representation with all interactive elements indexed
+ * as [0], [1], [2], etc. Use the indices to call click_element_by_index,
+ * input_text, select_option, or scroll.
+ */
+export declare function getBrowserState(viewport_only?: boolean): Promise<{
+    url: string;
+    title: string;
+    header: string;
+    content: string;
+    footer: string;
+    element_count: number;
+}>;
+export declare namespace getBrowserState {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                viewport_only: {
+                    type: string;
+                    description: string;
+                };
+            };
+        };
+    };
+}
+/**
+ * Click an interactive element by its index from get_browser_state.
+ */
+export declare function clickElementByIndex(index: number): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare namespace clickElementByIndex {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                index: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}
+/**
+ * Type text into an input, textarea, or contenteditable element by index.
+ */
+export declare function inputText(index: number, text: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare namespace inputText {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                index: {
+                    type: string;
+                    description: string;
+                };
+                text: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}
+/**
+ * Select a dropdown option by element index and option text.
+ */
+export declare function selectOption(index: number, option_text: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare namespace selectOption {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                index: {
+                    type: string;
+                    description: string;
+                };
+                option_text: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}
+/**
+ * Scroll the page or a specific scrollable container.
+ */
+export declare function scroll(direction: "up" | "down" | "left" | "right", amount?: number, index?: number): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare namespace scroll {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                direction: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                amount: {
+                    type: string;
+                    description: string;
+                };
+                index: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}
+/**
+ * Remove all visual element highlights/labels from the page.
+ */
+export declare function removeHighlights(): Promise<{
+    success: boolean;
+    message: string;
+}>;
+export declare namespace removeHighlights {
+    var __schema__: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {};
+        };
+    };
+}
+/**
+ * Dispose the page controller (for cleanup).
+ */
+export declare function disposeController(): void;

package/dist/ui/cursor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Animated AI cursor overlay.
+ * Shows a smooth-moving cursor with click ripple animation.
+ * Adapted from @page-agent/page-controller (MIT License).
+ *
+ * The cursor is injected as a fixed overlay and listens for
+ * custom events dispatched by the page-controller actions.
+ */
+export declare class AICursor {
+    private container;
+    private cursor;
+    private currentX;
+    private currentY;
+    private targetX;
+    private targetY;
+    private animating;
+    private visible;
+    private hideTimeout;
+    constructor();
+    moveTo(x: number, y: number): void;
+    private animateLoop;
+    triggerClickAnimation(): void;
+    destroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hypha-debugger",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Injectable debugger for web pages and AI agents, powered by Hypha RPC",
   "type": "module",
   "main": "dist/hypha-debugger.js",