opensteer 0.6.2 → 0.6.4

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import * as playwright from 'playwright';
 import { Page, BrowserContext, ElementHandle, Cookie, Browser } from 'playwright';
-import { a as OpensteerConfig, L as LaunchOptions, G as GotoOptions, S as SnapshotOptions, b as StateResult, c as ScreenshotOptions, d as ClickOptions, A as ActionResult, H as HoverOptions, I as InputOptions, e as SelectOptions, f as ScrollOptions, T as TabInfo, C as CookieParam, B as BaseActionOptions, g as BoundingBox, F as FileUploadOptions, E as ExtractOptions, h as ExtractFromPlanOptions, i as ExtractionRunResult, j as OpensteerCursorState, k as OpensteerAgentConfig, l as OpensteerAgentInstance, m as ElementPath, n as SnapshotMode, o as AiResolveCallback, p as AiExtractCallback, O as OpensteerAuthScheme, q as OpensteerAgentProvider, r as OpensteerAgentAction, s as OpensteerAgentResult, t as OpensteerAgentUsage, u as OpensteerCursorStyle, v as OpensteerCursorConfig, w as OpensteerAgentExecuteOptions } from './types-BxiRblC7.cjs';
-export { x as ActionWaitOptions, y as AiExtractArgs, z as AiExtractResult, D as AiResolveArgs, J as AiResolveCallbackResult, K as AiResolveResult, M as AttributeMatchClause, N as ContextHop, P as DomPath, Q as ExtractSchema, R as ExtractSchemaField, U as ExtractSchemaValue, V as ExtractionFieldPlan, W as ExtractionPlan, X as MatchClause, Y as MatchOperator, Z as OpensteerAgentMode, _ as OpensteerAgentModelConfig, $ as OpensteerBrowserConfig, a0 as OpensteerCloudAnnouncePolicy, a1 as OpensteerCloudBrowserProfileOptions, a2 as OpensteerCloudConfig, a3 as OpensteerCloudOptions, a4 as OpensteerCursorColor, a5 as OpensteerCursorProfile, a6 as OpensteerStorageConfig, a7 as PathNode, a8 as PathNodePosition, a9 as PositionMatchClause } from './types-BxiRblC7.cjs';
-import { A as ActionFailure, e as ActionFailureCode, C as CloudErrorCode, f as CloudActionFailureDetails, g as CloudSessionCreateRequest, h as CloudSessionCreateResponse, i as CloudSelectorCacheImportRequest, j as CloudSelectorCacheImportResponse, k as CloudActionMethod, l as CloudSelectorCacheImportEntry } from './browser-profile-client-DK9qa_Dj.cjs';
-export { m as ActionFailureBlocker, n as ActionFailureClassificationSource, o as ActionFailureDetails, p as BrowserProfileArchiveFormat, q as BrowserProfileClient, c as BrowserProfileCreateRequest, d as BrowserProfileDescriptor, a as BrowserProfileListRequest, b as BrowserProfileListResponse, r as BrowserProfileProxyPolicy, B as BrowserProfileStatus, s as CloudActionFailure, t as CloudActionRequest, u as CloudActionResponse, v as CloudActionSuccess, w as CloudBrowserProfileLaunchPreference, x as CloudFingerprintMode, y as CloudSessionContractVersion, z as CloudSessionLaunchConfig, D as CloudSessionSourceType, E as CloudSessionSummary, F as cloudSessionContractVersion } from './browser-profile-client-DK9qa_Dj.cjs';
+import { a as OpensteerConfig, L as LaunchOptions, b as OpensteerLocalProfileDescriptor, c as OpensteerRealBrowserOptions, G as GotoOptions, S as SnapshotOptions, d as StateResult, e as ScreenshotOptions, f as ClickOptions, A as ActionResult, H as HoverOptions, I as InputOptions, g as SelectOptions, h as ScrollOptions, T as TabInfo, C as CookieParam, B as BaseActionOptions, i as BoundingBox, F as FileUploadOptions, E as ExtractOptions, j as ExtractFromPlanOptions, k as ExtractionRunResult, l as OpensteerCursorState, m as OpensteerAgentConfig, n as OpensteerAgentInstance, o as ElementPath, p as SnapshotMode, q as AiResolveCallback, r as AiExtractCallback, O as OpensteerAuthScheme, s as OpensteerAgentProvider, t as OpensteerAgentAction, u as OpensteerAgentResult, v as OpensteerAgentUsage, w as OpensteerCursorStyle, x as OpensteerCursorConfig, y as OpensteerAgentExecuteOptions } from './types-BWItZPl_.cjs';
+export { z as ActionWaitOptions, D as AiExtractArgs, J as AiExtractResult, K as AiResolveArgs, M as AiResolveCallbackResult, N as AiResolveResult, P as AttributeMatchClause, Q as ContextHop, R as DomPath, U as ExtractSchema, V as ExtractSchemaField, W as ExtractSchemaValue, X as ExtractionFieldPlan, Y as ExtractionPlan, Z as MatchClause, _ as MatchOperator, $ as OpensteerAgentMode, a0 as OpensteerAgentModelConfig, a1 as OpensteerBrowserConfig, a2 as OpensteerCloudAnnouncePolicy, a3 as OpensteerCloudBrowserProfileOptions, a4 as OpensteerCloudConfig, a5 as OpensteerCloudOptions, a6 as OpensteerCursorColor, a7 as OpensteerCursorProfile, a8 as OpensteerLocalBrowserMode, a9 as OpensteerStorageConfig, aa as PathNode, ab as PathNodePosition, ac as PositionMatchClause } from './types-BWItZPl_.cjs';
+import { A as ActionFailure, e as ActionFailureCode, C as CloudErrorCode, f as CloudActionFailureDetails, g as CloudSessionCreateRequest, h as CloudSessionCreateResponse, i as CloudSelectorCacheImportRequest, j as CloudSelectorCacheImportResponse, k as CloudActionMethod, l as CloudSelectorCacheImportEntry } from './browser-profile-client-D6PuRefA.cjs';
+export { m as ActionFailureBlocker, n as ActionFailureClassificationSource, o as ActionFailureDetails, p as BrowserProfileArchiveFormat, q as BrowserProfileClient, c as BrowserProfileCreateRequest, d as BrowserProfileDescriptor, a as BrowserProfileListRequest, b as BrowserProfileListResponse, r as BrowserProfileProxyPolicy, B as BrowserProfileStatus, s as CloudActionFailure, t as CloudActionRequest, u as CloudActionResponse, v as CloudActionSuccess, w as CloudBrowserProfileLaunchPreference, x as CloudFingerprintMode, y as CloudSessionContractVersion, z as CloudSessionLaunchConfig, D as CloudSessionSourceType, E as CloudSessionSummary, F as cloudSessionContractVersion } from './browser-profile-client-D6PuRefA.cjs';
 
 interface RegistryEntry {
     file: string;
@@ -85,6 +85,8 @@ declare class Opensteer {
     private buildCloudSessionLaunchConfig;
     launch(options?: LaunchOptions): Promise<void>;
     static from(page: Page, config?: OpensteerConfig): Opensteer;
+    static listLocalProfiles(userDataDir?: string): OpensteerLocalProfileDescriptor[];
+    static fromSystemChrome(browser?: OpensteerRealBrowserOptions, config?: OpensteerConfig): Opensteer;
     close(): Promise<void>;
     private syncLocalSelectorCacheToCloud;
     goto(url: string, options?: GotoOptions): Promise<void>;
@@ -645,4 +647,4 @@ declare class SvgCursorRenderer implements CursorRenderer {
     private handleError;
 }
 
-export { type ActionExecutionResult, ActionFailure, ActionFailureCode, ActionResult, ActionWsClient, AiExtractCallback, type AiModelConfig, AiResolveCallback, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, BaseActionOptions, BoundingBox, CdpOverlayCursorRenderer, ClickOptions, CloudActionFailureDetails, CloudActionMethod, CloudCdpClient, type CloudCdpConnectArgs, type CloudCdpConnection, CloudErrorCode, CloudSelectorCacheImportEntry, CloudSelectorCacheImportRequest, CloudSelectorCacheImportResponse, CloudSessionClient, CloudSessionCreateRequest, CloudSessionCreateResponse, CookieParam, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CursorCapabilityReason, CursorController, type CursorIntent, type CursorMotionPlan, type CursorPoint, type CursorRenderer, type CursorStatus, ElementPath, ElementPathError, type ElementPathErrorCode, ExtractFromPlanOptions, ExtractOptions, ExtractionRunResult, type FieldSelector, FileUploadOptions, GotoOptions, HoverOptions, InputOptions, LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, OpensteerAgentAction, OpensteerAgentActionError, OpensteerAgentApiError, OpensteerAgentBusyError, OpensteerAgentConfig, OpensteerAgentConfigError, OpensteerAgentError, OpensteerAgentExecuteOptions, OpensteerAgentExecutionError, OpensteerAgentInstance, OpensteerAgentProvider, OpensteerAgentProviderError, OpensteerAgentResult, OpensteerAgentUsage, OpensteerAuthScheme, OpensteerCloudError, OpensteerConfig, OpensteerCuaAgentHandler, OpensteerCursorConfig, OpensteerCursorState, OpensteerCursorStyle, type PreparedSnapshot, type RegistryEntry, type ResolvedElementPath, ScreenshotOptions, ScrollOptions, SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, SnapshotMode, SnapshotOptions, StateResult, SvgCursorRenderer, TabInfo, buildArrayFieldPathCandidates, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, cloudNotLaunchedError, cloudUnsupportedMethodError, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createCuaClient, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, planSnappyCursorMotion, prepareSnapshot, pressKey, queryAllByElementPath, resolveAgentConfig, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };
+export { type ActionExecutionResult, ActionFailure, ActionFailureCode, ActionResult, ActionWsClient, AiExtractCallback, type AiModelConfig, AiResolveCallback, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, BaseActionOptions, BoundingBox, CdpOverlayCursorRenderer, ClickOptions, CloudActionFailureDetails, CloudActionMethod, CloudCdpClient, type CloudCdpConnectArgs, type CloudCdpConnection, CloudErrorCode, CloudSelectorCacheImportEntry, CloudSelectorCacheImportRequest, CloudSelectorCacheImportResponse, CloudSessionClient, CloudSessionCreateRequest, CloudSessionCreateResponse, CookieParam, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CursorCapabilityReason, CursorController, type CursorIntent, type CursorMotionPlan, type CursorPoint, type CursorRenderer, type CursorStatus, ElementPath, ElementPathError, type ElementPathErrorCode, ExtractFromPlanOptions, ExtractOptions, ExtractionRunResult, type FieldSelector, FileUploadOptions, GotoOptions, HoverOptions, InputOptions, LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, OpensteerAgentAction, OpensteerAgentActionError, OpensteerAgentApiError, OpensteerAgentBusyError, OpensteerAgentConfig, OpensteerAgentConfigError, OpensteerAgentError, OpensteerAgentExecuteOptions, OpensteerAgentExecutionError, OpensteerAgentInstance, OpensteerAgentProvider, OpensteerAgentProviderError, OpensteerAgentResult, OpensteerAgentUsage, OpensteerAuthScheme, OpensteerCloudError, OpensteerConfig, OpensteerCuaAgentHandler, OpensteerCursorConfig, OpensteerCursorState, OpensteerCursorStyle, OpensteerLocalProfileDescriptor, OpensteerRealBrowserOptions, type PreparedSnapshot, type RegistryEntry, type ResolvedElementPath, ScreenshotOptions, ScrollOptions, SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, SnapshotMode, SnapshotOptions, StateResult, SvgCursorRenderer, TabInfo, buildArrayFieldPathCandidates, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, cloudNotLaunchedError, cloudUnsupportedMethodError, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createCuaClient, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, planSnappyCursorMotion, prepareSnapshot, pressKey, queryAllByElementPath, resolveAgentConfig, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as playwright from 'playwright';
 import { Page, BrowserContext, ElementHandle, Cookie, Browser } from 'playwright';
-import { a as OpensteerConfig, L as LaunchOptions, G as GotoOptions, S as SnapshotOptions, b as StateResult, c as ScreenshotOptions, d as ClickOptions, A as ActionResult, H as HoverOptions, I as InputOptions, e as SelectOptions, f as ScrollOptions, T as TabInfo, C as CookieParam, B as BaseActionOptions, g as BoundingBox, F as FileUploadOptions, E as ExtractOptions, h as ExtractFromPlanOptions, i as ExtractionRunResult, j as OpensteerCursorState, k as OpensteerAgentConfig, l as OpensteerAgentInstance, m as ElementPath, n as SnapshotMode, o as AiResolveCallback, p as AiExtractCallback, O as OpensteerAuthScheme, q as OpensteerAgentProvider, r as OpensteerAgentAction, s as OpensteerAgentResult, t as OpensteerAgentUsage, u as OpensteerCursorStyle, v as OpensteerCursorConfig, w as OpensteerAgentExecuteOptions } from './types-BxiRblC7.js';
-export { x as ActionWaitOptions, y as AiExtractArgs, z as AiExtractResult, D as AiResolveArgs, J as AiResolveCallbackResult, K as AiResolveResult, M as AttributeMatchClause, N as ContextHop, P as DomPath, Q as ExtractSchema, R as ExtractSchemaField, U as ExtractSchemaValue, V as ExtractionFieldPlan, W as ExtractionPlan, X as MatchClause, Y as MatchOperator, Z as OpensteerAgentMode, _ as OpensteerAgentModelConfig, $ as OpensteerBrowserConfig, a0 as OpensteerCloudAnnouncePolicy, a1 as OpensteerCloudBrowserProfileOptions, a2 as OpensteerCloudConfig, a3 as OpensteerCloudOptions, a4 as OpensteerCursorColor, a5 as OpensteerCursorProfile, a6 as OpensteerStorageConfig, a7 as PathNode, a8 as PathNodePosition, a9 as PositionMatchClause } from './types-BxiRblC7.js';
-import { A as ActionFailure, e as ActionFailureCode, C as CloudErrorCode, f as CloudActionFailureDetails, g as CloudSessionCreateRequest, h as CloudSessionCreateResponse, i as CloudSelectorCacheImportRequest, j as CloudSelectorCacheImportResponse, k as CloudActionMethod, l as CloudSelectorCacheImportEntry } from './browser-profile-client-CaL-mwqs.js';
-export { m as ActionFailureBlocker, n as ActionFailureClassificationSource, o as ActionFailureDetails, p as BrowserProfileArchiveFormat, q as BrowserProfileClient, c as BrowserProfileCreateRequest, d as BrowserProfileDescriptor, a as BrowserProfileListRequest, b as BrowserProfileListResponse, r as BrowserProfileProxyPolicy, B as BrowserProfileStatus, s as CloudActionFailure, t as CloudActionRequest, u as CloudActionResponse, v as CloudActionSuccess, w as CloudBrowserProfileLaunchPreference, x as CloudFingerprintMode, y as CloudSessionContractVersion, z as CloudSessionLaunchConfig, D as CloudSessionSourceType, E as CloudSessionSummary, F as cloudSessionContractVersion } from './browser-profile-client-CaL-mwqs.js';
+import { a as OpensteerConfig, L as LaunchOptions, b as OpensteerLocalProfileDescriptor, c as OpensteerRealBrowserOptions, G as GotoOptions, S as SnapshotOptions, d as StateResult, e as ScreenshotOptions, f as ClickOptions, A as ActionResult, H as HoverOptions, I as InputOptions, g as SelectOptions, h as ScrollOptions, T as TabInfo, C as CookieParam, B as BaseActionOptions, i as BoundingBox, F as FileUploadOptions, E as ExtractOptions, j as ExtractFromPlanOptions, k as ExtractionRunResult, l as OpensteerCursorState, m as OpensteerAgentConfig, n as OpensteerAgentInstance, o as ElementPath, p as SnapshotMode, q as AiResolveCallback, r as AiExtractCallback, O as OpensteerAuthScheme, s as OpensteerAgentProvider, t as OpensteerAgentAction, u as OpensteerAgentResult, v as OpensteerAgentUsage, w as OpensteerCursorStyle, x as OpensteerCursorConfig, y as OpensteerAgentExecuteOptions } from './types-BWItZPl_.js';
+export { z as ActionWaitOptions, D as AiExtractArgs, J as AiExtractResult, K as AiResolveArgs, M as AiResolveCallbackResult, N as AiResolveResult, P as AttributeMatchClause, Q as ContextHop, R as DomPath, U as ExtractSchema, V as ExtractSchemaField, W as ExtractSchemaValue, X as ExtractionFieldPlan, Y as ExtractionPlan, Z as MatchClause, _ as MatchOperator, $ as OpensteerAgentMode, a0 as OpensteerAgentModelConfig, a1 as OpensteerBrowserConfig, a2 as OpensteerCloudAnnouncePolicy, a3 as OpensteerCloudBrowserProfileOptions, a4 as OpensteerCloudConfig, a5 as OpensteerCloudOptions, a6 as OpensteerCursorColor, a7 as OpensteerCursorProfile, a8 as OpensteerLocalBrowserMode, a9 as OpensteerStorageConfig, aa as PathNode, ab as PathNodePosition, ac as PositionMatchClause } from './types-BWItZPl_.js';
+import { A as ActionFailure, e as ActionFailureCode, C as CloudErrorCode, f as CloudActionFailureDetails, g as CloudSessionCreateRequest, h as CloudSessionCreateResponse, i as CloudSelectorCacheImportRequest, j as CloudSelectorCacheImportResponse, k as CloudActionMethod, l as CloudSelectorCacheImportEntry } from './browser-profile-client-OUHaODro.js';
+export { m as ActionFailureBlocker, n as ActionFailureClassificationSource, o as ActionFailureDetails, p as BrowserProfileArchiveFormat, q as BrowserProfileClient, c as BrowserProfileCreateRequest, d as BrowserProfileDescriptor, a as BrowserProfileListRequest, b as BrowserProfileListResponse, r as BrowserProfileProxyPolicy, B as BrowserProfileStatus, s as CloudActionFailure, t as CloudActionRequest, u as CloudActionResponse, v as CloudActionSuccess, w as CloudBrowserProfileLaunchPreference, x as CloudFingerprintMode, y as CloudSessionContractVersion, z as CloudSessionLaunchConfig, D as CloudSessionSourceType, E as CloudSessionSummary, F as cloudSessionContractVersion } from './browser-profile-client-OUHaODro.js';
 
 interface RegistryEntry {
     file: string;
@@ -85,6 +85,8 @@ declare class Opensteer {
     private buildCloudSessionLaunchConfig;
     launch(options?: LaunchOptions): Promise<void>;
     static from(page: Page, config?: OpensteerConfig): Opensteer;
+    static listLocalProfiles(userDataDir?: string): OpensteerLocalProfileDescriptor[];
+    static fromSystemChrome(browser?: OpensteerRealBrowserOptions, config?: OpensteerConfig): Opensteer;
     close(): Promise<void>;
     private syncLocalSelectorCacheToCloud;
     goto(url: string, options?: GotoOptions): Promise<void>;
@@ -645,4 +647,4 @@ declare class SvgCursorRenderer implements CursorRenderer {
     private handleError;
 }
 
-export { type ActionExecutionResult, ActionFailure, ActionFailureCode, ActionResult, ActionWsClient, AiExtractCallback, type AiModelConfig, AiResolveCallback, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, BaseActionOptions, BoundingBox, CdpOverlayCursorRenderer, ClickOptions, CloudActionFailureDetails, CloudActionMethod, CloudCdpClient, type CloudCdpConnectArgs, type CloudCdpConnection, CloudErrorCode, CloudSelectorCacheImportEntry, CloudSelectorCacheImportRequest, CloudSelectorCacheImportResponse, CloudSessionClient, CloudSessionCreateRequest, CloudSessionCreateResponse, CookieParam, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CursorCapabilityReason, CursorController, type CursorIntent, type CursorMotionPlan, type CursorPoint, type CursorRenderer, type CursorStatus, ElementPath, ElementPathError, type ElementPathErrorCode, ExtractFromPlanOptions, ExtractOptions, ExtractionRunResult, type FieldSelector, FileUploadOptions, GotoOptions, HoverOptions, InputOptions, LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, OpensteerAgentAction, OpensteerAgentActionError, OpensteerAgentApiError, OpensteerAgentBusyError, OpensteerAgentConfig, OpensteerAgentConfigError, OpensteerAgentError, OpensteerAgentExecuteOptions, OpensteerAgentExecutionError, OpensteerAgentInstance, OpensteerAgentProvider, OpensteerAgentProviderError, OpensteerAgentResult, OpensteerAgentUsage, OpensteerAuthScheme, OpensteerCloudError, OpensteerConfig, OpensteerCuaAgentHandler, OpensteerCursorConfig, OpensteerCursorState, OpensteerCursorStyle, type PreparedSnapshot, type RegistryEntry, type ResolvedElementPath, ScreenshotOptions, ScrollOptions, SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, SnapshotMode, SnapshotOptions, StateResult, SvgCursorRenderer, TabInfo, buildArrayFieldPathCandidates, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, cloudNotLaunchedError, cloudUnsupportedMethodError, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createCuaClient, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, planSnappyCursorMotion, prepareSnapshot, pressKey, queryAllByElementPath, resolveAgentConfig, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };
+export { type ActionExecutionResult, ActionFailure, ActionFailureCode, ActionResult, ActionWsClient, AiExtractCallback, type AiModelConfig, AiResolveCallback, type ArrayExtractedRow, type ArrayRowMetadata, type ArraySelector, BaseActionOptions, BoundingBox, CdpOverlayCursorRenderer, ClickOptions, CloudActionFailureDetails, CloudActionMethod, CloudCdpClient, type CloudCdpConnectArgs, type CloudCdpConnection, CloudErrorCode, CloudSelectorCacheImportEntry, CloudSelectorCacheImportRequest, CloudSelectorCacheImportResponse, CloudSessionClient, CloudSessionCreateRequest, CloudSessionCreateResponse, CookieParam, type CounterRequest, CounterResolutionError, type CounterResolutionErrorCode, type CursorCapabilityReason, CursorController, type CursorIntent, type CursorMotionPlan, type CursorPoint, type CursorRenderer, type CursorStatus, ElementPath, ElementPathError, type ElementPathErrorCode, ExtractFromPlanOptions, ExtractOptions, ExtractionRunResult, type FieldSelector, FileUploadOptions, GotoOptions, HoverOptions, InputOptions, LaunchOptions, LocalSelectorStorage, type MarkInteractivityOptions, OPENSTEER_HIDDEN_ATTR, OPENSTEER_INTERACTIVE_ATTR, OPENSTEER_SCROLLABLE_ATTR, OS_BOUNDARY_ATTR, OS_IFRAME_BOUNDARY_TAG, OS_NODE_ID_ATTR, OS_SHADOW_BOUNDARY_TAG, OS_UNAVAILABLE_ATTR, Opensteer, OpensteerActionError, OpensteerAgentAction, OpensteerAgentActionError, OpensteerAgentApiError, OpensteerAgentBusyError, OpensteerAgentConfig, OpensteerAgentConfigError, OpensteerAgentError, OpensteerAgentExecuteOptions, OpensteerAgentExecutionError, OpensteerAgentInstance, OpensteerAgentProvider, OpensteerAgentProviderError, OpensteerAgentResult, OpensteerAgentUsage, OpensteerAuthScheme, OpensteerCloudError, OpensteerConfig, OpensteerCuaAgentHandler, OpensteerCursorConfig, OpensteerCursorState, OpensteerCursorStyle, OpensteerLocalProfileDescriptor, OpensteerRealBrowserOptions, type PreparedSnapshot, type RegistryEntry, type ResolvedElementPath, ScreenshotOptions, ScrollOptions, SelectOptions, type SelectorFile, type SelectorRegistry, type SerializeOptions, type SerializedNodeMeta, type SerializedPageHTML, SnapshotMode, SnapshotOptions, StateResult, SvgCursorRenderer, TabInfo, buildArrayFieldPathCandidates, buildElementPathFromHandle, buildElementPathFromSelector, buildPathSelectorHint, cleanForAction, cleanForClickable, cleanForExtraction, cleanForFull, cleanForScrollable, clearCookies, cloneElementPath, closeTab, cloudNotLaunchedError, cloudUnsupportedMethodError, collectLocalSelectorCacheEntries, countArrayItemsWithPath, createCuaClient, createEmptyRegistry, createExtractCallback, createResolveCallback, createTab, exportCookies, extractArrayRowsWithPaths, extractArrayWithPaths, extractWithPaths, getCookies, getElementAttributes, getElementBoundingBox, getElementText, getElementValue, getModelProvider, getPageHtml, getPageTitle, importCookies, listTabs, markInteractiveElements, normalizeNamespace, performClick, performFileUpload, performHover, performInput, performScroll, performSelect, planSnappyCursorMotion, prepareSnapshot, pressKey, queryAllByElementPath, resolveAgentConfig, resolveCounterElement, resolveCountersBatch, resolveElementPath, resolveNamespaceDir, sanitizeElementPath, serializePageHTML, setCookie, switchTab, typeText, waitForVisualStability };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   BrowserProfileClient
-} from "./chunk-WJI7TGBQ.js";
+} from "./chunk-6B6LOYU3.js";
 import {
   ActionWsClient,
   CounterResolutionError,
@@ -78,7 +78,7 @@ import {
   switchTab,
   typeText,
   waitForVisualStability
-} from "./chunk-F2VDVOJO.js";
+} from "./chunk-G6V2DJRN.js";
 import {
   CloudCdpClient,
   CloudSessionClient,
@@ -87,7 +87,8 @@ import {
   cloudUnsupportedMethodError,
   normalizeNamespace,
   resolveNamespaceDir
-} from "./chunk-WDRMHPWL.js";
+} from "./chunk-KPPOTU3D.js";
+import "./chunk-K5CL76MG.js";
 import {
   createResolveCallback
 } from "./chunk-DN3GI5CH.js";

package/dist/{types-BxiRblC7.d.cts → types-BWItZPl_.d.cts}

@@ -72,17 +72,33 @@ interface GotoOptions {
     waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
     settleMs?: number;
 }
+type OpensteerLocalBrowserMode = 'chromium' | 'real';
+interface OpensteerLocalProfileDescriptor {
+    directory: string;
+    name: string;
+}
+interface OpensteerRealBrowserOptions {
+    headless?: boolean;
+    executablePath?: string;
+    userDataDir?: string;
+    profileDirectory?: string;
+}
 interface LaunchOptions {
     headless?: boolean;
     executablePath?: string;
     slowMo?: number;
+    /** Sandbox-only context options. Not supported with cdpUrl or mode "real". */
     context?: BrowserContextOptions;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
-    channel?: string;
-    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
+    /** Initial URL to open as part of owned real-browser startup. */
+    initialUrl?: string;
+    /** Local browser mode. Defaults to "chromium". */
+    mode?: OpensteerLocalBrowserMode;
+    /** Connect to a running CDP-enabled browser. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Browser user-data root directory for real-browser mode. */
+    userDataDir?: string;
+    /** Browser profile directory name for real-browser mode. */
+    profileDirectory?: string;
     /** Cloud browser profile preference. Applies only when cloud mode is enabled. */
     cloudBrowserProfile?: OpensteerCloudBrowserProfileOptions;
     /** Connection timeout in milliseconds. */
@@ -92,12 +108,14 @@ interface OpensteerBrowserConfig {
     headless?: boolean;
     executablePath?: string;
     slowMo?: number;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
-    channel?: string;
-    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
+    /** Local browser mode. Defaults to "chromium". */
+    mode?: OpensteerLocalBrowserMode;
+    /** Connect to a running CDP-enabled browser. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Browser user-data root directory for real-browser mode. */
+    userDataDir?: string;
+    /** Browser profile directory name for real-browser mode. */
+    profileDirectory?: string;
 }
 interface OpensteerStorageConfig {
     rootDir?: string;
@@ -324,4 +342,4 @@ interface OpensteerAgentInstance {
     execute(instructionOrOptions: string | OpensteerAgentExecuteOptions): Promise<OpensteerAgentResult>;
 }
 
-export type { OpensteerBrowserConfig as $, ActionResult as A, BaseActionOptions as B, CookieParam as C, AiResolveArgs as D, ExtractOptions as E, FileUploadOptions as F, GotoOptions as G, HoverOptions as H, InputOptions as I, AiResolveCallbackResult as J, AiResolveResult as K, LaunchOptions as L, AttributeMatchClause as M, ContextHop as N, OpensteerAuthScheme as O, DomPath as P, ExtractSchema as Q, ExtractSchemaField as R, SnapshotOptions as S, TabInfo as T, ExtractSchemaValue as U, ExtractionFieldPlan as V, ExtractionPlan as W, MatchClause as X, MatchOperator as Y, OpensteerAgentMode as Z, OpensteerAgentModelConfig as _, OpensteerConfig as a, OpensteerCloudAnnouncePolicy as a0, OpensteerCloudBrowserProfileOptions as a1, OpensteerCloudConfig as a2, OpensteerCloudOptions as a3, OpensteerCursorColor as a4, OpensteerCursorProfile as a5, OpensteerStorageConfig as a6, PathNode as a7, PathNodePosition as a8, PositionMatchClause as a9, StateResult as b, ScreenshotOptions as c, ClickOptions as d, SelectOptions as e, ScrollOptions as f, BoundingBox as g, ExtractFromPlanOptions as h, ExtractionRunResult as i, OpensteerCursorState as j, OpensteerAgentConfig as k, OpensteerAgentInstance as l, ElementPath as m, SnapshotMode as n, AiResolveCallback as o, AiExtractCallback as p, OpensteerAgentProvider as q, OpensteerAgentAction as r, OpensteerAgentResult as s, OpensteerAgentUsage as t, OpensteerCursorStyle as u, OpensteerCursorConfig as v, OpensteerAgentExecuteOptions as w, ActionWaitOptions as x, AiExtractArgs as y, AiExtractResult as z };
+export type { OpensteerAgentMode as $, ActionResult as A, BaseActionOptions as B, CookieParam as C, AiExtractArgs as D, ExtractOptions as E, FileUploadOptions as F, GotoOptions as G, HoverOptions as H, InputOptions as I, AiExtractResult as J, AiResolveArgs as K, LaunchOptions as L, AiResolveCallbackResult as M, AiResolveResult as N, OpensteerAuthScheme as O, AttributeMatchClause as P, ContextHop as Q, DomPath as R, SnapshotOptions as S, TabInfo as T, ExtractSchema as U, ExtractSchemaField as V, ExtractSchemaValue as W, ExtractionFieldPlan as X, ExtractionPlan as Y, MatchClause as Z, MatchOperator as _, OpensteerConfig as a, OpensteerAgentModelConfig as a0, OpensteerBrowserConfig as a1, OpensteerCloudAnnouncePolicy as a2, OpensteerCloudBrowserProfileOptions as a3, OpensteerCloudConfig as a4, OpensteerCloudOptions as a5, OpensteerCursorColor as a6, OpensteerCursorProfile as a7, OpensteerLocalBrowserMode as a8, OpensteerStorageConfig as a9, PathNode as aa, PathNodePosition as ab, PositionMatchClause as ac, OpensteerLocalProfileDescriptor as b, OpensteerRealBrowserOptions as c, StateResult as d, ScreenshotOptions as e, ClickOptions as f, SelectOptions as g, ScrollOptions as h, BoundingBox as i, ExtractFromPlanOptions as j, ExtractionRunResult as k, OpensteerCursorState as l, OpensteerAgentConfig as m, OpensteerAgentInstance as n, ElementPath as o, SnapshotMode as p, AiResolveCallback as q, AiExtractCallback as r, OpensteerAgentProvider as s, OpensteerAgentAction as t, OpensteerAgentResult as u, OpensteerAgentUsage as v, OpensteerCursorStyle as w, OpensteerCursorConfig as x, OpensteerAgentExecuteOptions as y, ActionWaitOptions as z };

package/dist/{types-BxiRblC7.d.ts → types-BWItZPl_.d.ts}

@@ -72,17 +72,33 @@ interface GotoOptions {
     waitUntil?: 'commit' | 'domcontentloaded' | 'load' | 'networkidle';
     settleMs?: number;
 }
+type OpensteerLocalBrowserMode = 'chromium' | 'real';
+interface OpensteerLocalProfileDescriptor {
+    directory: string;
+    name: string;
+}
+interface OpensteerRealBrowserOptions {
+    headless?: boolean;
+    executablePath?: string;
+    userDataDir?: string;
+    profileDirectory?: string;
+}
 interface LaunchOptions {
     headless?: boolean;
     executablePath?: string;
     slowMo?: number;
+    /** Sandbox-only context options. Not supported with cdpUrl or mode "real". */
     context?: BrowserContextOptions;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
-    channel?: string;
-    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
+    /** Initial URL to open as part of owned real-browser startup. */
+    initialUrl?: string;
+    /** Local browser mode. Defaults to "chromium". */
+    mode?: OpensteerLocalBrowserMode;
+    /** Connect to a running CDP-enabled browser. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Browser user-data root directory for real-browser mode. */
+    userDataDir?: string;
+    /** Browser profile directory name for real-browser mode. */
+    profileDirectory?: string;
     /** Cloud browser profile preference. Applies only when cloud mode is enabled. */
     cloudBrowserProfile?: OpensteerCloudBrowserProfileOptions;
     /** Connection timeout in milliseconds. */
@@ -92,12 +108,14 @@ interface OpensteerBrowserConfig {
     headless?: boolean;
     executablePath?: string;
     slowMo?: number;
-    /** Connect to a running browser. Example: "http://localhost:9222" */
-    connectUrl?: string;
-    /** Browser channel: "chrome", "chrome-beta", or "msedge" */
-    channel?: string;
-    /** Browser profile directory or Chromium user-data dir. Preserves cookies, extensions, and sessions. */
-    profileDir?: string;
+    /** Local browser mode. Defaults to "chromium". */
+    mode?: OpensteerLocalBrowserMode;
+    /** Connect to a running CDP-enabled browser. Example: "http://localhost:9222" */
+    cdpUrl?: string;
+    /** Browser user-data root directory for real-browser mode. */
+    userDataDir?: string;
+    /** Browser profile directory name for real-browser mode. */
+    profileDirectory?: string;
 }
 interface OpensteerStorageConfig {
     rootDir?: string;
@@ -324,4 +342,4 @@ interface OpensteerAgentInstance {
     execute(instructionOrOptions: string | OpensteerAgentExecuteOptions): Promise<OpensteerAgentResult>;
 }
 
-export type { OpensteerBrowserConfig as $, ActionResult as A, BaseActionOptions as B, CookieParam as C, AiResolveArgs as D, ExtractOptions as E, FileUploadOptions as F, GotoOptions as G, HoverOptions as H, InputOptions as I, AiResolveCallbackResult as J, AiResolveResult as K, LaunchOptions as L, AttributeMatchClause as M, ContextHop as N, OpensteerAuthScheme as O, DomPath as P, ExtractSchema as Q, ExtractSchemaField as R, SnapshotOptions as S, TabInfo as T, ExtractSchemaValue as U, ExtractionFieldPlan as V, ExtractionPlan as W, MatchClause as X, MatchOperator as Y, OpensteerAgentMode as Z, OpensteerAgentModelConfig as _, OpensteerConfig as a, OpensteerCloudAnnouncePolicy as a0, OpensteerCloudBrowserProfileOptions as a1, OpensteerCloudConfig as a2, OpensteerCloudOptions as a3, OpensteerCursorColor as a4, OpensteerCursorProfile as a5, OpensteerStorageConfig as a6, PathNode as a7, PathNodePosition as a8, PositionMatchClause as a9, StateResult as b, ScreenshotOptions as c, ClickOptions as d, SelectOptions as e, ScrollOptions as f, BoundingBox as g, ExtractFromPlanOptions as h, ExtractionRunResult as i, OpensteerCursorState as j, OpensteerAgentConfig as k, OpensteerAgentInstance as l, ElementPath as m, SnapshotMode as n, AiResolveCallback as o, AiExtractCallback as p, OpensteerAgentProvider as q, OpensteerAgentAction as r, OpensteerAgentResult as s, OpensteerAgentUsage as t, OpensteerCursorStyle as u, OpensteerCursorConfig as v, OpensteerAgentExecuteOptions as w, ActionWaitOptions as x, AiExtractArgs as y, AiExtractResult as z };
+export type { OpensteerAgentMode as $, ActionResult as A, BaseActionOptions as B, CookieParam as C, AiExtractArgs as D, ExtractOptions as E, FileUploadOptions as F, GotoOptions as G, HoverOptions as H, InputOptions as I, AiExtractResult as J, AiResolveArgs as K, LaunchOptions as L, AiResolveCallbackResult as M, AiResolveResult as N, OpensteerAuthScheme as O, AttributeMatchClause as P, ContextHop as Q, DomPath as R, SnapshotOptions as S, TabInfo as T, ExtractSchema as U, ExtractSchemaField as V, ExtractSchemaValue as W, ExtractionFieldPlan as X, ExtractionPlan as Y, MatchClause as Z, MatchOperator as _, OpensteerConfig as a, OpensteerAgentModelConfig as a0, OpensteerBrowserConfig as a1, OpensteerCloudAnnouncePolicy as a2, OpensteerCloudBrowserProfileOptions as a3, OpensteerCloudConfig as a4, OpensteerCloudOptions as a5, OpensteerCursorColor as a6, OpensteerCursorProfile as a7, OpensteerLocalBrowserMode as a8, OpensteerStorageConfig as a9, PathNode as aa, PathNodePosition as ab, PositionMatchClause as ac, OpensteerLocalProfileDescriptor as b, OpensteerRealBrowserOptions as c, StateResult as d, ScreenshotOptions as e, ClickOptions as f, SelectOptions as g, ScrollOptions as h, BoundingBox as i, ExtractFromPlanOptions as j, ExtractionRunResult as k, OpensteerCursorState as l, OpensteerAgentConfig as m, OpensteerAgentInstance as n, ElementPath as o, SnapshotMode as p, AiResolveCallback as q, AiExtractCallback as r, OpensteerAgentProvider as s, OpensteerAgentAction as t, OpensteerAgentResult as u, OpensteerAgentUsage as v, OpensteerCursorStyle as w, OpensteerCursorConfig as x, OpensteerAgentExecuteOptions as y, ActionWaitOptions as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensteer",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "Open-source browser automation SDK and CLI that lets AI agents build complex scrapers directly in your codebase.",
   "license": "MIT",
   "type": "module",
@@ -71,7 +71,7 @@
     "url": "https://github.com/steerlabs/opensteer/issues"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/cli/server.ts src/cli/skills-installer.ts src/cli/profile.ts src/cli/auth.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq --external openai --external @anthropic-ai/sdk --external @google/genai",
+    "build": "tsup src/index.ts src/cli/server.ts src/cli/skills-installer.ts src/cli/profile.ts src/cli/auth.ts src/cli/local-profile.ts --dts --format esm,cjs --clean --external ai --external zod --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/google --external @ai-sdk/xai --external @ai-sdk/groq --external openai --external @anthropic-ai/sdk --external @google/genai",
     "test": "vitest run",
     "test:live-web": "vitest run --config vitest.live-web.config.ts",
     "test:unit": "vitest run tests/html tests/element-path tests/config.test.ts tests/storage",

package/skills/opensteer/SKILL.md

@@ -8,7 +8,7 @@ description: "Browser automation, web scraping, and structured data extraction u
 **Exploring interactively?** Follow Phase 1.
 **Writing a scraper script?** Follow Phase 2.
 
-> Never use raw Playwright methods when an Opensteer equivalent exists. Never call `opensteer.navigate()` — the correct method is `opensteer.goto()`.
+> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method. The SDK covers navigation, clicks, hover, input, select, scroll, extraction, text retrieval, HTML retrieval, screenshots, and waits. The correct navigation method is `opensteer.goto()` (not `navigate`).
 
 ---
 
@@ -77,6 +77,8 @@ Repeat Step 3 → Step 4 for every distinct page type the scraper will visit.
 opensteer close
 ```
 
+> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method.
+
 ---
 
 ## Phase 2 — SDK Scraper Script
@@ -112,6 +114,13 @@ async function run() {
 run().catch((err) => { console.error(err); process.exit(1); });
 ```
 
+> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method.
+
+**Before writing a script, verify:**
+1. Every interaction uses `opensteer.click()`, `opensteer.input()`, `opensteer.hover()`, `opensteer.extract()` — not `page.*` equivalents
+2. Every extraction uses `opensteer.extract({ description: "..." })` — not `page.evaluate()` for DOM data
+3. Waits use `opensteer.waitForText()` — not `page.waitForSelector()` (unless no stable text exists)
+
 **Critical method signatures:**
 
 ```typescript
@@ -146,8 +155,7 @@ await opensteer.extract({
   },
 }); // first extraction run: agent defines the full object from the snapshot
 
-await opensteer.waitForText("literal text");
-await opensteer.page.waitForSelector("css-selector");                       // SPA content guard
+await opensteer.waitForText("literal text");                                // page-transition wait
 
 // Do NOT add waits before opensteer actions — they handle waiting internally.
 ```
@@ -164,16 +172,6 @@ opensteer open --connect-url http://localhost:9222 --name "my-scraper"
 # Verify CDP is running: curl -s http://127.0.0.1:9222/json/version
 ```
 
-**API-based extraction (site has internal REST/GraphQL endpoints):**
-Navigate first to acquire session cookies, then call `fetch()` inside `page.evaluate()`. This is the only valid use of `page.evaluate()`.
-```typescript
-await opensteer.goto("https://example.com");
-const data = await opensteer.page.evaluate(async () => {
-  const res = await fetch("https://api.example.com/items?limit=100");
-  return res.json();
-});
-```
-
 **Tab management:**
 ```bash
 opensteer tabs
@@ -183,8 +181,30 @@ opensteer tab-close 1
 ```
 
 **Debugging failures (diagnose in this order):**
-1. SPA content not loaded — add `waitForText` or `page.waitForSelector` before extraction.
+1. SPA content not loaded — add `opensteer.waitForText()` before extraction.
 2. Missing cache — re-run Phase 1 caching step for the page type that failed.
 3. Obstacle blocking target — cookie banner, modal, or login wall. Dismiss it first.
 
+### Advanced: Direct Page Access (rare)
+
+Use `opensteer.page` ONLY for these two patterns. There are no other valid uses.
+
+**SPA selector guard** — when `waitForText` cannot work (no stable visible text):
+```typescript
+await opensteer.page.waitForSelector("css-selector");
+```
+
+**Internal API call** — site has REST/GraphQL endpoints and you need session cookies:
+```typescript
+await opensteer.goto("https://example.com");
+const data = await opensteer.page.evaluate(async () => {
+  const res = await fetch("https://api.example.com/items?limit=100");
+  return res.json();
+});
+```
+
+These two patterns are the complete list.
+
+> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method.
+
 **Full references:** [cli-reference.md](references/cli-reference.md) | [sdk-reference.md](references/sdk-reference.md)

package/skills/opensteer/references/cli-reference.md

@@ -28,7 +28,7 @@ opensteer sessions                                  # List active sessions
 opensteer status                                    # Show resolved session/name state
 ```
 
-`open` does raw `page.goto()` (no stability wait). `navigate` includes `waitForVisualStability`. Use `open` once to start, then `navigate` for subsequent pages.
+`open` performs a basic navigation (no stability wait). `navigate` includes `waitForVisualStability`. Use `open` once to start, then `navigate` for subsequent pages.
 
 ## Observation
 

package/skills/opensteer/references/examples.md

@@ -59,7 +59,7 @@ async function run() {
     // Visit each detail page and extract using cached description
     for (const job of listings.jobs) {
       await opensteer.goto(job.url);
-      await opensteer.page.waitForSelector("h1");
+      await opensteer.waitForText(job.title || "Job details");
 
       const detail = await opensteer.extract({
         description: "job detail page",
@@ -77,9 +77,9 @@ run().catch((err) => {
 });
 ```
 
-## API-Based Extraction
+## Advanced: API-Based Extraction (uses direct page access)
 
-When a site has internal APIs (REST, GraphQL, Algolia), navigate first for cookies, then use `fetch()` inside `page.evaluate()`. This is the only valid use of `page.evaluate()` for data.
+> This is a rare pattern. Only use it when the site has internal REST/GraphQL endpoints and DOM extraction via `opensteer.extract()` is insufficient.
 
 ```typescript
 import { Opensteer } from "opensteer";
@@ -114,3 +114,5 @@ run().catch((err) => {
   process.exit(1);
 });
 ```
+
+> **SDK Rule**: For all other data extraction, use `opensteer.extract()`.

package/skills/opensteer/references/sdk-reference.md

@@ -12,15 +12,15 @@ const opensteer = new Opensteer({
 await opensteer.launch({ headless: false });
 await opensteer.close();
 
-// Or wrap an existing Playwright page:
+// Wrap an existing page instance:
 const opensteer = Opensteer.from(existingPage, { name: "my-scraper" });
 ```
 
 ## Properties
 
 ```typescript
-opensteer.page;    // Raw Playwright Page — only for page.evaluate(fetch), page.waitForSelector, page.waitForTimeout
-opensteer.context; // Raw Playwright BrowserContext
+opensteer.page;    // Low-level page handle (see "Advanced: Direct Page Access" in SKILL.md)
+opensteer.context; // Low-level browser context handle
 ```
 
 ## Navigation
@@ -113,8 +113,7 @@ const title = await opensteer.getTitle();
 ```typescript
 await opensteer.waitForText("Success");                              // Literal text on page
 await opensteer.waitForText("Success", { timeout: 5000 });
-await opensteer.page.waitForSelector("article");                     // CSS selector
-await opensteer.page.waitForSelector(".loading", { state: "hidden" });
+// For CSS selector waits, see "Advanced: Direct Page Access" in SKILL.md
 ```
 
 ## Tabs
@@ -142,13 +141,16 @@ await opensteer.importCookies("/tmp/cookies.json");
 await opensteer.uploadFile({ element: 5, paths: ["/path/to/file.pdf"] });
 ```
 
-## Methods That DO NOT Exist
+## Common Mistakes
 
-| Wrong (throws)                   | Correct                                |
-| -------------------------------- | -------------------------------------- |
-| `opensteer.evaluate(...)`        | `opensteer.page.evaluate(...)`         |
-| `opensteer.waitForSelector(...)` | `opensteer.page.waitForSelector(...)`  |
-| `opensteer.waitForLoad(...)`     | `opensteer.page.waitForLoadState(...)` |
-| `opensteer.navigate(...)`        | `opensteer.goto(...)`                  |
-| `opensteer.browser_launch(...)`  | `opensteer.launch(...)`                |
-| `opensteer.browser_close(...)`   | `opensteer.close(...)`                 |
+| If you want to...        | Use this                          |
+| ------------------------ | --------------------------------- |
+| Navigate to a URL        | `opensteer.goto(url)`             |
+| Launch the browser       | `opensteer.launch()`              |
+| Close the browser        | `opensteer.close()`               |
+| Get page text content    | `opensteer.getElementText()`      |
+| Get page HTML            | `opensteer.getHtml()`             |
+| Extract structured data  | `opensteer.extract()`             |
+| Wait for content         | `opensteer.waitForText()`         |
+
+> **SDK Rule**: Every browser action in a script MUST use an `opensteer.*` method.