@pi-oxide/extension-js 0.12.4 → 0.13.0

package/shared/collect-inline-snapshot.d.ts

@@ -0,0 +1,50 @@
+export type InlineSnapshotNode = {
+    refId: string;
+    role: string;
+    tag: string;
+    controlType?: string;
+    actionable?: boolean;
+    forControl?: string;
+    recommendedAction?: string;
+    controls?: string;
+    expanded?: boolean;
+    name?: string;
+    text?: string;
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    selected?: boolean;
+    required?: boolean;
+    valid?: boolean;
+    invalid?: boolean;
+    validationMessage?: string;
+    errorMessage?: string;
+    href?: string;
+    src?: string;
+    alt?: string;
+    title?: string;
+    parentRefId?: string;
+    postId?: string;
+    permalink?: string;
+    imageUrls?: string[];
+    accept?: string;
+    filesCount?: number;
+};
+export type FormErrorEntry = {
+    field: string;
+    error: string;
+    refId: string;
+};
+export type InlineSnapshotResult = {
+    text: string;
+    nodes: InlineSnapshotNode[];
+    formErrors: FormErrorEntry[];
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export declare function collectInlineSnapshot(maxNodes: number): InlineSnapshotResult;

package/shared/cross/agent-errors.d.ts

@@ -0,0 +1,28 @@
+import { AsyncError } from './manifest.js';
+
+export declare function contentScriptMissingError(tabId?: number, url?: string): AsyncError;
+export declare function noTabError(action: string): AsyncError;
+export type StaleRefCandidate = {
+    refId: string;
+    role?: string;
+    name?: string;
+};
+export declare function staleRefError(refId: string, options?: {
+    label?: string;
+    candidates?: StaleRefCandidate[];
+    snapshot?: unknown;
+}): AsyncError;
+export declare function notInteractableError(action: string, refId: string, details?: Record<string, unknown>): AsyncError;
+export declare function observationRequiredError(action: string): AsyncError;
+export declare function ambiguousTargetError(label: string): AsyncError;
+export declare function isContentScriptConnectionError(msg: string): boolean;
+export declare function throwStructuredAgentError(error: AsyncError): never;
+export declare function labelNotFoundError(label: string, candidates?: StaleRefCandidate[], extra?: {
+    searchedIds?: string[];
+    ignoredIds?: string[];
+    targetRefId?: string;
+    targetName?: string;
+    ariaControlsBefore?: string | null;
+    ariaControlsAfter?: string | null;
+    isDropdown?: boolean;
+}): AsyncError;

package/shared/cross/array-buffer.d.ts

@@ -0,0 +1,4 @@
+/** Decode a base64 string into bytes. Throws on invalid input. */
+export declare function base64ToUint8Array(base64: string): Uint8Array;
+/** Convert Uint8Array to base64 without spread-arg limits on large buffers. */
+export declare function arrayBufferToBase64(bytes: Uint8Array): string;

package/shared/cross/collect-inline-snapshot.d.ts

@@ -0,0 +1,58 @@
+export type InlineSnapshotNode = {
+    refId: string;
+    role: string;
+    tag: string;
+    controlType?: string;
+    actionable?: boolean;
+    forControl?: string;
+    recommendedAction?: string;
+    controls?: string;
+    expanded?: boolean;
+    name?: string;
+    text?: string;
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    selected?: boolean;
+    required?: boolean;
+    valid?: boolean;
+    invalid?: boolean;
+    validationMessage?: string;
+    errorMessage?: string;
+    href?: string;
+    src?: string;
+    alt?: string;
+    title?: string;
+    parentRefId?: string;
+    postId?: string;
+    permalink?: string;
+    imageUrls?: string[];
+    accept?: string;
+    filesCount?: number;
+};
+export type FormErrorEntry = {
+    field: string;
+    error: string;
+    refId: string;
+};
+export type InlineSnapshotResult = {
+    text: string;
+    nodes: InlineSnapshotNode[];
+    formErrors: FormErrorEntry[];
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+};
+export declare const enrichDropdown: (el: Element, node: {
+    role?: string;
+    tag: string;
+    controlType?: string;
+    recommendedAction?: string;
+    controls?: string;
+    expanded?: boolean;
+}) => void;
+export declare function collectInlineSnapshot(maxNodes: number): InlineSnapshotResult;

package/shared/cross/content-script-actions.d.ts

@@ -0,0 +1,7 @@
+export declare function addContentScriptAction(action: string): void;
+export declare function isContentScriptAction(action: string): boolean;
+export declare function getContentScriptActions(): string[];
+/** Test-only helper: clear the dynamic content-script action set. */
+export declare function clearContentScriptActions(): void;
+/** Map registry action (page_click) to content-script handler key (click). */
+export declare function toHandlerAction(action: string): string;

package/shared/cross/content-script-tools.d.ts

@@ -0,0 +1,3 @@
+export type { ContentScriptToolSpec } from './page-specs.js';
+export { AWAIT_PROMISE_NOTE } from './page-specs.js';
+export declare const CONTENT_SCRIPT_TOOL_SPECS: readonly (import('./page-specs.js').ContentScriptToolSpec<unknown, unknown> | import('./page-specs.js').ContentScriptToolSpec)[];

package/shared/cross/dispatch.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import { AsyncResponse } from './manifest.js';
+
+export declare function formatValidationError(action: string, schema: z.ZodTypeAny, issues: z.ZodIssue[], params?: unknown): string;
+export declare function dispatchValidated<P, R>(paramsSchema: z.ZodSchema<P>, returnsSchema: z.ZodSchema<R>, handler: (params: P) => Promise<R> | R, params: unknown, action: string): Promise<AsyncResponse<R>>;

package/shared/cross/fetch-response.d.ts

@@ -0,0 +1,12 @@
+export type FetchValue = {
+    status: number;
+    ok: boolean;
+    headers: Record<string, string>;
+    body: string;
+    bodyEncoding: "text" | "base64";
+    byteLength: number;
+    contentType: string;
+    finalUrl: string;
+};
+/** Encode a fetch Response for page.fetch / web.fetch with binary-safe handling. */
+export declare function encodeFetchResponse(resp: Response): Promise<FetchValue>;

package/shared/cross/format-types.d.ts

@@ -0,0 +1,43 @@
+import { FsPathParams, FsStringResult } from '../../../pkg/extension_js.js';
+
+export type CsvAction = "parse";
+export type CsvActionMap = {
+    parse: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+};
+export type ZipAction = "list";
+export type ZipActionMap = {
+    list: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+};
+export type XlsxAction = "read";
+export type XlsxActionMap = {
+    read: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+};
+export type PdfAction = "text";
+export type PdfActionMap = {
+    text: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+};
+export type FormatCallMessage<TType extends string, TMap extends Record<string, {
+    params: unknown;
+    result: unknown;
+}>> = {
+    type: TType;
+    id: string;
+    action: keyof TMap & string;
+    params: TMap[keyof TMap]["params"];
+};
+export type CsvCallMessage = FormatCallMessage<"csvCall", CsvActionMap>;
+export type ZipCallMessage = FormatCallMessage<"zipCall", ZipActionMap>;
+export type XlsxCallMessage = FormatCallMessage<"xlsxCall", XlsxActionMap>;
+export type PdfCallMessage = FormatCallMessage<"pdfCall", PdfActionMap>;

package/shared/cross/fs-types.d.ts

@@ -0,0 +1,81 @@
+import { FsBoolResult, FsCopyParams, FsExistsResult, FsHashParams, FsHashResult, FsListResult, FsPathParams, FsReadRangeDataParams, FsReadRangeParams, FsStatResult, FsStringResult, FsWriteParams, FsWriteResult } from '../../../pkg/extension_js.js';
+
+export type FsActionMap = {
+    exists: {
+        params: FsPathParams;
+        result: FsExistsResult;
+    };
+    stat: {
+        params: FsPathParams;
+        result: FsStatResult;
+    };
+    read: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+    readText: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+    readBase64: {
+        params: FsPathParams;
+        result: FsStringResult;
+    };
+    list: {
+        params: FsPathParams;
+        result: FsListResult;
+    };
+    mkdir: {
+        params: FsPathParams;
+        result: FsBoolResult;
+    };
+    delete: {
+        params: FsPathParams;
+        result: FsBoolResult;
+    };
+    copy: {
+        params: FsCopyParams;
+        result: FsBoolResult;
+    };
+    move: {
+        params: FsCopyParams;
+        result: FsBoolResult;
+    };
+    write: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    writeText: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    writeBase64: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    append: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    appendText: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    appendBase64: {
+        params: FsWriteParams;
+        result: FsWriteResult;
+    };
+    readRange: {
+        params: FsReadRangeParams;
+        result: FsStringResult;
+    };
+    update: {
+        params: FsReadRangeDataParams;
+        result: FsBoolResult;
+    };
+    hash: {
+        params: FsHashParams;
+        result: FsHashResult;
+    };
+};
+export type FsAction = keyof FsActionMap;

package/shared/cross/generated.d.ts

@@ -0,0 +1,328 @@
+export type TreeSnapshot = {
+    version: string;
+    url: string | null;
+    title: string | null;
+    viewport: {
+        width: number;
+        height: number;
+        scrollX: number;
+        scrollY: number;
+    } | null;
+    nodes: SemanticNode[];
+    outline?: OutlineNode[];
+};
+export type SemanticNode = {
+    refId: string;
+    role: string;
+    name?: string;
+    description?: string;
+    tag: string;
+    id?: string;
+    classes?: string[];
+    value?: string;
+    placeholder?: string;
+    href?: string;
+    states: Record<string, boolean | undefined>;
+    inputType?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    inViewport: boolean;
+    visible: boolean;
+    path?: string;
+};
+export type OutlineNode = {
+    role: string;
+    name: string;
+    ref_id: string;
+};
+export type CommandParams = FetchParams | SleepParams | PageClickParams | PageDblClickParams | PageFillParams | PageSetFilesParams | PageTypeParams | PagePressParams | PageSelectParams | PageSelectOptionParams | PageCheckParams | PageHoverParams | PageScrollParams | PageScrollToParams | PageGotoParams | PageFindParams | PageWaitForParams | PageExtractParams | PageAppendParams | PageWaitParams | StorageGetParams | StorageSetParams | StorageDeleteParams | DomSnapshotParams | DomFormatParams | TabClickParams | TabFillParams | TabSetFilesParams | TabEvaluateParams | TabBackParams | TabWaitForLoadParams | TabScrollToParams | TabTypeParams | TabPressParams | TabSelectParams | TabSelectOptionParams | TabCheckParams | TabHoverParams | TabUnhoverParams | TabScrollParams | TabDblClickParams | FsWriteParams | FsPathParams | FsCopyParams | FsUpdateParams | FsHashParams | FsReadRangeParams;
+export type AsyncCommand = {
+    call_id: number;
+    action: string;
+    params: CommandParams;
+};
+export type CellError = {
+    kind: "compile";
+    name: string | null;
+    message: string;
+    line: number | null;
+} | {
+    kind: "runtime";
+    name: string | null;
+    message: string;
+    line: number | null;
+    action: string | null;
+    code: string | null;
+    stack: string | null;
+} | {
+    kind: "fuel_exhausted";
+} | {
+    kind: "internal";
+    message: string;
+};
+export type CellStatus = "done" | "async_pending";
+export type DomSnapshotParams = {
+    interactive_only: boolean;
+    max_nodes: bigint;
+};
+export type DomFormatParams = {
+    snapshot: TreeSnapshot;
+    format?: string;
+};
+export type FetchParams = {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string | null;
+    timeout: bigint;
+    store?: boolean;
+};
+export type FsCopyParams = {
+    from: string;
+    to: string;
+};
+export type FsHashParams = {
+    path: string;
+    algo: string;
+};
+export type FsPathParams = {
+    path: string;
+};
+export type FsReadRangeParams = {
+    path: string;
+    offset: bigint;
+    len: number;
+};
+export type FsUpdateParams = {
+    path: string;
+    offset: bigint;
+    data: string;
+};
+export type FsWriteParams = {
+    path: string;
+    data: string;
+};
+export type PageAppendParams = {
+    refId?: string;
+    label?: string;
+    text: string;
+};
+export type PageCheckParams = {
+    refId?: string;
+    label?: string;
+    checked: boolean;
+};
+export type PageClickParams = {
+    refId?: string;
+    label?: string;
+};
+export type PageDblClickParams = {
+    refId?: string;
+    label?: string;
+};
+export type PageExtractParams = {
+    fields: string[];
+};
+export type PageFillParams = {
+    refId?: string;
+    label?: string;
+    value: string;
+};
+export type SetFileSource = {
+    name?: string;
+    mimeType?: string;
+    url?: string;
+    path?: string;
+    handle?: string;
+};
+export type PageSetFilesParams = {
+    refId?: string;
+    label?: string;
+    files: SetFileSource[];
+};
+export type PageFindParams = {
+    selector: string;
+};
+export type PageDomParams = {
+    selector: string;
+    depth: number;
+    includeHidden: boolean;
+};
+export type PageGotoParams = {
+    url: string;
+    timeout?: bigint;
+    waitUntil?: "load" | "networkidle";
+};
+export type SnapshotFilter = {
+    role?: string | string[];
+    tag?: string | string[];
+    text?: string;
+    name?: string;
+    interactiveOnly?: boolean;
+    href?: string;
+    src?: string;
+    limit?: number;
+};
+export type PageSnapshotQueryParams = {
+    filter?: SnapshotFilter;
+    max_nodes?: number;
+};
+export type TabSnapshotQueryParams = {
+    filter?: SnapshotFilter;
+    max_nodes?: number;
+    tabId: number;
+};
+export type PageHoverParams = {
+    refId?: string;
+    label?: string;
+};
+export type PageSubmitParams = {
+    refId?: string;
+    label?: string;
+};
+export type PageCheckRadioParams = {
+    name: string;
+    value: string;
+};
+export type PagePressParams = {
+    refId?: string;
+    label?: string;
+    key: string;
+};
+export type PageScrollParams = {
+    direction: string;
+    amount: number;
+};
+export type PageScrollToParams = {
+    refId?: string;
+    label?: string;
+    x?: number;
+    y?: number;
+};
+export type PageSelectParams = {
+    refId?: string;
+    label?: string;
+    value: string | string[];
+};
+export type PageSelectOptionParams = {
+    refId?: string;
+    label?: string;
+    value: string;
+};
+export type PageTypeParams = {
+    refId?: string;
+    label?: string;
+    text: string;
+};
+export type PageWaitForParams = {
+    selector: string;
+    timeout: bigint;
+};
+export type PageWaitParams = {
+    duration: bigint;
+};
+export type RunResult = {
+    stdout: string[];
+    stderr: string[];
+    result: string | null;
+    error: CellError | null;
+    commands: CommandParams[];
+    fuel_exhausted: boolean;
+    execution_count: number;
+    status: CellStatus;
+    pending_commands: AsyncCommand[];
+};
+export type SleepParams = {
+    duration: bigint;
+};
+export type StorageDeleteParams = {
+    key: string;
+};
+export type StorageGetParams = {
+    key: string;
+};
+export type StorageSetParams = {
+    key: string;
+    value: string;
+};
+export type TabBackParams = {
+    tabId: bigint;
+};
+export type TabCheckParams = {
+    tabId: bigint;
+    refId: string;
+    checked: boolean;
+};
+export type TabClickParams = {
+    tabId: bigint;
+    refId: string;
+};
+export type TabDblClickParams = {
+    tabId: bigint;
+    refId: string;
+};
+export type TabEvaluateParams = {
+    tabId: bigint;
+    script: string;
+};
+export type TabFillParams = {
+    tabId: bigint;
+    refId: string;
+    value: string;
+};
+export type TabSetFilesParams = {
+    tabId?: number;
+    refId?: string;
+    label?: string;
+    files: SetFileSource[];
+};
+export type TabHoverParams = {
+    tabId: bigint;
+    refId: string;
+};
+export type TabPressParams = {
+    tabId: bigint;
+    key: string;
+};
+export type TabScrollParams = {
+    tabId: bigint;
+    direction: string;
+    amount: number;
+};
+export type TabScrollToParams = {
+    tabId: bigint;
+    x?: number;
+    y?: number;
+    refId?: string;
+    label?: string;
+};
+export type TabSelectParams = {
+    tabId: bigint;
+    refId: string;
+    value: string;
+};
+export type TabSelectOptionParams = {
+    tabId: bigint;
+    refId: string;
+    value: string;
+};
+export type TabTypeParams = {
+    tabId: bigint;
+    refId: string;
+    text: string;
+};
+export type TabUnhoverParams = {
+    tabId: bigint;
+};
+export type TabWaitForLoadParams = {
+    tabId: bigint;
+    timeout: bigint;
+};