@pi-oxide/extension-js 0.12.4 → 0.13.0

package/content-script/action-result.d.ts

@@ -0,0 +1,4 @@
+import { PageActionResult } from '../shared/cross/schemas.js';
+
+export declare function makeActionResult(action: string, el: Element | null, extras?: Record<string, unknown>): PageActionResult;
+export declare function assertFillEffect(action: string, el: Element, refId: string, requested: string): void;

package/content-script/dom-tree.d.ts

@@ -0,0 +1,28 @@
+export type DomNode = {
+    refId?: string;
+    tag: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    attributes?: Record<string, string>;
+    hidden?: boolean;
+    hiddenReason?: "display-none" | "visibility-hidden" | "aria-hidden" | "opacity-zero" | "hidden-attr" | "inert";
+    value?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    href?: string;
+    src?: string;
+    alt?: string;
+    accept?: string;
+    filesCount?: number;
+    controlType?: string;
+    recommendedAction?: string;
+    controls?: string;
+    expanded?: boolean;
+    children?: DomNode[];
+};
+export declare function buildDomNode(el: Element, depth: number, includeHidden: boolean, observed?: Array<{
+    refId: string;
+    element: Element;
+}>): DomNode | null;

package/content-script/dom-utils.d.ts

@@ -0,0 +1,37 @@
+import { enrichFormNode, getAccessibleName, getAccessibleRole, shouldInclude } from '../shared/cs/snapshot-dom.js';
+
+export { enrichFormNode, getAccessibleName, getAccessibleRole, shouldInclude };
+/**
+ * Find an element by its opaque reference ID.
+ * @param refId — opaque element ref in 'e{N}' format (e.g. 'e2'). Must match schema regex ^e\d+$.
+ */
+export declare function getElementByRefId(refId: string): Element | null;
+export declare function assertInteractable(el: Element, action: string): void;
+export declare function findElementByLabel(query: string): Element | null;
+export declare function findCandidateLabels(query: string): string[];
+export type SemanticCandidate = {
+    refId: string;
+    role?: string;
+    name?: string;
+};
+export declare function findSemanticCandidates(query: string): SemanticCandidate[];
+export declare function asRecord(obj: unknown): Record<string, unknown>;
+export declare function getStringParam(params: unknown, key: string): string;
+export declare function getNumberParam(params: unknown, key: string, fallback: number): number;
+export declare function findCandidatesByRefId(refId: string): SemanticCandidate[];
+export declare function throwElementNotFound(refId: string | undefined, label: string | undefined, includeCandidates?: boolean): never;
+/**
+ * Resolve an element by refId (raw querySelector) with a label fallback.
+ *
+ * INTENTIONAL non-lease path: this deliberately bypasses the observation lease
+ * (requireTarget / requireTargetByLabel). The handlers that use this — type,
+ * append, select, check, hover, dblclick, set_files, scroll_to — mutate stable
+ * elements that rarely change between snapshot and action, so the lease's
+ * stale-element / fingerprint strictness is unnecessary here and would reject
+ * valid targets. Only `click` (and fill's refId path) use lease validation.
+ *
+ * Do NOT "unify" these handlers onto requireTarget — that changes behavior the
+ * project has explicitly chosen. If you need lease-validated resolution, use
+ * requireTarget/requireTargetByLabel directly (as click does).
+ */
+export declare function resolveTargetRaw(refId: string | undefined, label: string | undefined): Element;

package/content-script/file-resolution.d.ts

@@ -0,0 +1,22 @@
+/**
+ * File-input resolution for `set_files`. Resolves worker-processed file
+ * payloads (base64 bytes or fetched URL) into real `File` objects and
+ * verifies they landed on the input.
+ */
+export type ResolvedBytesFile = {
+    kind: "bytes";
+    name: string;
+    data: string;
+    mimeType?: string;
+};
+export type ResolvedUrlFile = {
+    kind: "url";
+    url: string;
+    name: string;
+    mimeType?: string;
+};
+export type ResolvedSetFile = ResolvedBytesFile | ResolvedUrlFile;
+export declare function parseResolvedFiles(params: unknown): ResolvedSetFile[];
+export declare function fileFromBytes(file: ResolvedBytesFile): File;
+export declare function fileFromUrl(file: ResolvedUrlFile): Promise<File>;
+export declare function assertSetFilesEffect(el: HTMLInputElement, refId: string, expectedNames: string[]): void;

package/content-script/form-validation.d.ts

@@ -0,0 +1,12 @@
+export type InvalidFormControl = {
+    refId: string | undefined;
+    tag: string;
+    role: string;
+    name: string | undefined;
+    field: string | undefined;
+    error: string;
+    value: string | undefined;
+    required: boolean;
+    validationMessage: string | undefined;
+};
+export declare function invalidFormControls(form: HTMLFormElement): InvalidFormControl[];

package/content-script/handlers.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+export type Handler<T = unknown, R = unknown> = (params: T, signal?: AbortSignal) => R | Promise<R>;
+export declare const handlers: Record<string, (params: any, signal?: AbortSignal) => unknown>;

package/content-script/index.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface Window {
+        __jsNotebookContentScriptInjected?: boolean;
+    }
+}
+export {};

package/content-script/listbox.d.ts

@@ -0,0 +1,7 @@
+export declare function activateAndResolveListboxRoots(control: HTMLElement): Promise<{
+    roots: HTMLElement[];
+    searchedIds: string[];
+    allListboxes: HTMLElement[];
+    ariaControlsBefore: string | null;
+    ariaControlsAfter: string | null;
+}>;

package/content-script/logger.d.ts

@@ -0,0 +1,12 @@
+export declare const logger: {
+    debug: (event: string, meta?: Record<string, unknown>) => void;
+    info: (event: string, meta?: Record<string, unknown>) => void;
+    warn: (event: string, meta?: Record<string, unknown>) => void;
+    error: (event: string, meta?: Record<string, unknown>) => void;
+};
+export declare function initContentScriptLogger(): void;
+declare global {
+    interface Window {
+        __jsNotebookSetLogLevel?: (level: string) => void;
+    }
+}

package/content-script/message-router.d.ts

@@ -0,0 +1 @@
+export declare function installMessageListener(): void;

package/content-script/observation-lease.d.ts

@@ -0,0 +1,55 @@
+import { InlineSnapshotNode, InlineSnapshotResult } from '../shared/cross/collect-inline-snapshot.js';
+
+export interface ObservedTarget {
+    element: Element;
+    fingerprint: TargetFingerprint;
+}
+export interface TargetFingerprint {
+    tag: string;
+    role: string;
+    name: string;
+}
+/** Reset state — used by tests and on content-script load. */
+export declare function resetLease(): void;
+/**
+ * A snapshot succeeded; the page is now observed. Returns the new observationId.
+ * Pass the refId→element mapping so requireTarget can re-validate identity later.
+ */
+export declare function grantObservation(observed?: ReadonlyArray<{
+    refId: string;
+    element: Element;
+}>): string;
+/** Page state may have diverged; require a fresh observation before any action. */
+export declare function invalidateLease(): void;
+export declare function hasActiveObservation(): boolean;
+export declare function currentObservationId(): string | undefined;
+/**
+ * Re-validate the target at action time. Throws a structured agent error if:
+ * - the lease has no active observation
+ * - the refId is not part of the latest observation
+ * - the element was disconnected or replaced
+ * - the semantic fingerprint changed (role/name/tag rewrite)
+ *
+ * Returns the validated element on success.
+ */
+export declare function requireTarget(refId: string, action: string): Element;
+/**
+ * Resolve a label against the latest observation. Throws E_AMBIGUOUS_TARGET
+ * if multiple observed targets share the label. Returns the unique element.
+ */
+export declare function requireTargetByLabel(label: string, action: string): Element;
+/** Re-grant snapshot attached to lease-violation errors. */
+export interface RefreshSnapshot {
+    nodes: InlineSnapshotNode[];
+    observationId: string;
+    url: string;
+    title: string;
+}
+/**
+ * Collect an inline snapshot and grant the lease over every refId-bearing
+ * element it produced. Shared logic for snapshot-time grant and error-path
+ * refresh so the collect→resolve→grant sequence has one definition.
+ */
+export declare function grantFromInlineSnapshot(maxNodes: number): InlineSnapshotResult & {
+    observationId: string;
+};

package/content-script/registry.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+
+export type ContentScriptHandler = (params: unknown, signal?: AbortSignal) => unknown | Promise<unknown>;
+export type ContentScriptHandlerSpec = {
+    registryAction: string;
+    handlerKey: string;
+    params: z.ZodSchema<unknown>;
+    returns: z.ZodSchema<unknown>;
+};
+export declare function registerContentScriptSpec(spec: ContentScriptHandlerSpec): void;
+export declare function getContentScriptSpec(registryAction: string): ContentScriptHandlerSpec | undefined;
+/** Register content-script handler specs and announce readiness to the host. */
+export declare function registerContentScriptSpecs(specs: ContentScriptHandlerSpec[]): void;
+export declare function cancelContentScriptCall(callId: string): boolean;
+export declare function dispatchContentScriptCall(registryAction: string, _handlerKey: string, handler: ContentScriptHandler, params: unknown, callId?: string): Promise<{
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        message: string;
+        code: string;
+    };
+}>;

package/content-script/schemas.d.ts

@@ -0,0 +1,5 @@
+import { ContentScriptHandlerSpec } from './registry.js';
+
+/** Infra-only schemas for non-registryCall messages (ping connectivity probe). */
+export declare function buildInfraContentScriptSpecs(): ContentScriptHandlerSpec[];
+export declare function buildContentScriptSpecs(): ContentScriptHandlerSpec[];

package/content-script/snapshot.d.ts

@@ -0,0 +1,3 @@
+import { collectInlineSnapshot } from '../shared/collect-inline-snapshot.js';
+
+export { collectInlineSnapshot as inlineSnapshot };