@pi-oxide/extension-js 0.12.3 → 0.13.0

package/shared/cs/snapshot-dom.d.ts

@@ -0,0 +1,47 @@
+/** Shared DOM helpers for inline snapshots (content script + MAIN-world injection). */
+export { allocateRefId, getNextRefId, syncRefIdCounterFromDom, } from './ref-id.js';
+export declare const INTERACTIVE_SELECTOR = "input, textarea, select, button, a, [role=\"button\"], [role=\"link\"]";
+export declare function readFormFields(el: Element): {
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    selected?: boolean;
+    required?: boolean;
+    valid?: boolean;
+    invalid?: boolean;
+    validationMessage?: string;
+    errorMessage?: string;
+};
+export declare function readErrorMessage(el: Element): string | undefined;
+export declare function enrichFormNode(el: Element, node: {
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    selected?: boolean;
+    required?: boolean;
+    valid?: boolean;
+    invalid?: boolean;
+    validationMessage?: string;
+    errorMessage?: string;
+}): void;
+export declare function resolveAbsoluteUrl(attr: string | null): string | undefined;
+export declare function resolveContainerRefId(el: Element): string | undefined;
+export declare function resolvePermalinkLink(el: Element): HTMLAnchorElement | null;
+export declare function getAccessibleRole(el: Element): string;
+export declare function hasDirectTextContent(el: Element): boolean;
+export declare function getOwnVisibleText(el: Element, maxLen?: number): string;
+export declare function isSelfOrAncestorHidden(el: Element): boolean;
+/** Include if the element would remain visible in a Markdown rendering. */
+export declare function isMarkdownVisible(el: Element): boolean;
+export declare function getAccessibleName(el: Element): string;
+export declare function shouldInclude(el: Element): boolean;
+/** Detect a hidden validation-shim input inside a combobox wrapper (react-select).
+ *  These inputs carry required/aria-required for form validation but are not
+ *  user-visible; they must appear in the snapshot labeled as validation-proxy. */
+export declare function isValidationProxyInput(el: Element): boolean;
+/** Resolve a human-readable field label from <label> element associations.
+ *  Tries: accessible name → label[for=id] → wrapping <label> → preceding sibling
+ *  <label> → parent's first <label> child. Falls back to the refId. */
+export declare function resolveFieldLabel(el: Element | null, fallback: string): string;

package/shared/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/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/generated.d.ts

@@ -0,0 +1,241 @@
+import { TreeSnapshot } from '@pi-oxide/dom-semantic-tree';
+
+export type CommandParams = FetchParams | SleepParams | PageClickParams | PageDblClickParams | PageFillParams | PageTypeParams | PagePressParams | PageSelectParams | PageSelectOptionParams | PageCheckParams | PageHoverParams | PageScrollParams | PageScrollToParams | PageGotoParams | PageFindParams | PageWaitForParams | PageExtractParams | PageAppendParams | PageWaitParams | StorageGetParams | StorageSetParams | StorageDeleteParams | DomSnapshotParams | DomFormatParams | TabClickParams | TabFillParams | 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;
+    run_id?: string;
+};
+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;
+};
+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 PageFindParams = {
+    selector: string;
+};
+export type PageGotoParams = {
+    url: string;
+};
+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 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;
+};

package/shared/log-levels.d.ts

@@ -0,0 +1,5 @@
+import { LogLevel } from './logger.js';
+
+/** Numeric levels shared by JS logger and Rust WASM tracing filter. */
+export declare const LOG_LEVEL_NUMERIC: Record<LogLevel, number>;
+export declare function numericToLogLevel(level: number): LogLevel;

package/shared/logger.d.ts

@@ -0,0 +1,18 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "none";
+export { LOG_LEVEL_NUMERIC, numericToLogLevel } from './log-levels.js';
+export declare function setLogLevel(level: LogLevel): void;
+export declare function getLogLevel(): LogLevel;
+export declare function registerWasmSetLogLevel(fn: (level: number) => void): void;
+export declare class Logger {
+    private namespace;
+    constructor(namespace?: string);
+    private log;
+    trace(event: string, ...rest: unknown[]): void;
+    debug(event: string, ...rest: unknown[]): void;
+    info(event: string, ...rest: unknown[]): void;
+    warn(event: string, ...rest: unknown[]): void;
+    error(event: string, ...rest: unknown[]): void;
+    child(namespace: string): Logger;
+    timer(event: string, metadata?: Record<string, unknown>, level?: LogLevel): (finishMetadata?: Record<string, unknown>) => void;
+}
+export declare const logger: Logger;

package/shared/main/content-script-response.d.ts

@@ -0,0 +1,5 @@
+import { AsyncError, AsyncResponse } from '../cross/manifest.js';
+
+/** Preserve structured content-script errors; fall back for legacy string/malformed shapes. */
+export declare function parseAsyncError(raw: unknown, fallback?: AsyncError): AsyncError;
+export declare function unwrapContentScriptMessage(result: unknown): AsyncResponse;

package/shared/main/define-content-script-tool.d.ts

@@ -0,0 +1,7 @@
+import { ContentScriptToolSpec } from '../cross/content-script-tools.js';
+
+/** Register a content-script tool on the main thread.
+ *  - Adds a manifest entry via registerContentScriptJsCall
+ *  - Adds the action to the dynamic content-script action set
+ *  Does NOT call registerContentScriptSpec (content script registers its own specs). */
+export declare function defineContentScriptTool<P, R>(spec: ContentScriptToolSpec<P, R>): void;

package/shared/main/log-levels.d.ts

@@ -0,0 +1,5 @@
+import { LogLevel } from './logger.js';
+
+/** Numeric levels shared by JS logger and Rust WASM tracing filter. */
+export declare const LOG_LEVEL_NUMERIC: Record<LogLevel, number>;
+export declare function numericToLogLevel(level: number): LogLevel;

package/shared/main/logger.d.ts

@@ -0,0 +1,18 @@
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "none";
+export { LOG_LEVEL_NUMERIC, numericToLogLevel } from './log-levels.js';
+export declare function setLogLevel(level: LogLevel): void;
+export declare function getLogLevel(): LogLevel;
+export declare function registerWasmSetLogLevel(fn: (level: number) => void): void;
+export declare class Logger {
+    private namespace;
+    constructor(namespace?: string);
+    private log;
+    trace(event: string, ...rest: unknown[]): void;
+    debug(event: string, ...rest: unknown[]): void;
+    info(event: string, ...rest: unknown[]): void;
+    warn(event: string, ...rest: unknown[]): void;
+    error(event: string, ...rest: unknown[]): void;
+    child(namespace: string): Logger;
+    timer(event: string, metadata?: Record<string, unknown>, level?: LogLevel): (finishMetadata?: Record<string, unknown>) => void;
+}
+export declare const logger: Logger;

package/shared/main/routes.d.ts

@@ -0,0 +1,14 @@
+import { ExecutionContextId } from '../cross/manifest.js';
+import { Route, TabPolicy } from '../cross/types.js';
+
+export declare function setRoute(action: string, route: Route): void;
+export declare function getRoute(action: string): Route | undefined;
+export declare function clearRoutes(): void;
+export declare function inferTabPolicy(action: string): TabPolicy;
+export declare function inferEndpoint(owner: ExecutionContextId): Route["endpoint"];
+export declare function inferOwner(action: string, owner: ExecutionContextId): ExecutionContextId;
+export declare function routeFromOwner(action: string, owner: ExecutionContextId): Route;
+export declare function populateRoutesFromManifest(entries: Array<{
+    action: string;
+    owner: ExecutionContextId;
+}>): void;

package/shared/main/tool-registry.d.ts

@@ -0,0 +1,19 @@
+import { AsyncResponse, JsCallSpec, SerializableJsCallManifestEntry, ToolDefinition, ToolDoc } from '../cross/manifest.js';
+
+export type { AsyncError, AsyncResponse, CallContext, Command, ExecutionContextId, JsCallSpec, SerializableJsCallManifestEntry, ToolDefinition, ToolDoc, ToolDocParam, } from '../cross/manifest.js';
+export { coerceWasmParams, manifestEntryToWasm } from '../cross/manifest.js';
+export declare function setRunnerAbortController(controller: AbortController | null): void;
+export declare function getRunnerSignal(): AbortSignal | undefined;
+export declare function throwIfAborted(): void;
+/** Manifest-only registration for actions executed in the content script. */
+export declare function registerContentScriptJsCall<P, R>(spec: Omit<JsCallSpec<P, R>, "owner" | "handler">): void;
+export declare function registerJsCall<P, R>(spec: JsCallSpec<P, R>): void;
+export declare function getTool(action: string): ToolDefinition<unknown, unknown> | undefined;
+/** Test-only helper: remove a tool from the tool registry without touching the JS registry. */
+export declare function removeToolForTest(action: string): boolean;
+export declare function clearRegistry(): void;
+export declare function freezeJsRegistry(): void;
+export declare function clearJsRegistry(): void;
+export declare function getSerializableJsManifest(): SerializableJsCallManifestEntry[];
+export declare function dispatchTool(action: string, params: unknown, callId?: number, runId?: string, signal?: AbortSignal): Promise<AsyncResponse>;
+export declare function listTools(): ToolDoc[];

package/shared/ref-id.d.ts

@@ -0,0 +1,5 @@
+/** Monotonic refId allocator synced from existing DOM data-ref-id attributes. */
+export declare function syncRefIdCounterFromDom(): void;
+export declare function allocateRefId(el: Element): string;
+/** @deprecated Use allocateRefId after syncRefIdCounterFromDom */
+export declare function getNextRefId(): string;

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

@@ -0,0 +1,27 @@
+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[];
+}): 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/registry/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/registry/content-script-response.d.ts

@@ -0,0 +1,5 @@
+import { AsyncError, AsyncResponse } from './manifest.js';
+
+/** Preserve structured content-script errors; fall back for legacy string/malformed shapes. */
+export declare function parseAsyncError(raw: unknown, fallback?: AsyncError): AsyncError;
+export declare function unwrapContentScriptMessage(result: unknown): AsyncResponse;

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

@@ -0,0 +1,13 @@
+import { JsCallSpec } from './manifest.js';
+
+export type ContentScriptToolSpec<P = unknown, R = unknown> = Omit<JsCallSpec<P, R>, "owner" | "handler"> & {
+    handlerKey: string;
+};
+/** Static build-time list of content-script tool specs.
+ *  Both main-thread and content-script IIFE bundles import this at build time.
+ *  Single source of truth for content-script registry tools (page + web.tab).
+ *
+ *  TODO: Mutation returnDoc strings are hand-written pseudo-type-signatures.
+ *  When PageActionResultSchema changes, update all mutation returnDoc strings
+ *  to match, or generate them from the schema shape to eliminate drift. */
+export declare const CONTENT_SCRIPT_TOOL_SPECS: readonly ContentScriptToolSpec[];

package/shared/registry/define-content-script-tool.d.ts

@@ -0,0 +1,7 @@
+import { ContentScriptToolSpec } from './content-script-tools.js';
+
+/** Register a content-script tool on the main thread.
+ *  - Adds a manifest entry via registerContentScriptJsCall
+ *  - Adds the action to the dynamic content-script action set
+ *  Does NOT call registerContentScriptSpec (content script registers its own specs). */
+export declare function defineContentScriptTool<P, R>(spec: ContentScriptToolSpec<P, R>): void;

package/shared/registry/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>>;