@vortex-browser/shared 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nicofroggo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @vortex-browser/shared
+
+Vortex 单子项目共享的类型与协议常量。**纯类型 / 常量包，无运行时副作用**。所有上游（extension / server / cli / mcp）都从这里导入，避免协议分裂。
+
+## 内容
+
+| 文件 | 内容 |
+|------|------|
+| `actions.ts` | 全部 action 名常量（`PageActions.NAVIGATE = "page.navigate"` 等），按模块分组的枚举 |
+| `protocol.ts` | `VtxRequest` / `VtxResponse` / `VtxEvent` / `NmRequest` / `NmResponse` 等线缆消息类型 |
+| `errors.ts` | `VtxErrorCode` 枚举（`TIMEOUT`、`NOT_FOUND`、`PERMISSION_DENIED` 等） |
+| `index.ts` | 统一 re-export |
+
+## 使用
+
+```ts
+import {
+  PageActions, DomActions,
+  type VtxRequest, type VtxResponse,
+  VtxErrorCode,
+} from "@vortex-browser/shared";
+
+const req: VtxRequest = {
+  id: "x",
+  action: PageActions.NAVIGATE,
+  params: { url: "https://example.com" },
+};
+```
+
+## 添加/修改 action
+
+1. 在 `actions.ts` 对应模块枚举里新增条目
+2. extension 端在 `packages/extension/src/handlers/<mod>.ts` 注册处理函数
+3. 如需新错误码：在 `errors.ts` 加 `VtxErrorCode` 成员
+
+## 构建
+
+```bash
+pnpm build       # tsc 一次
+pnpm dev         # tsc --watch
+```
+
+下游包通过 workspace 协议引用：`"@vortex-browser/shared": "workspace:*"`，改动后无需 publish 即生效。

package/dist/actions.d.ts

@@ -0,0 +1,118 @@
+export declare const TabActions: {
+    readonly LIST: "tab.list";
+    readonly CREATE: "tab.create";
+    readonly CLOSE: "tab.close";
+    readonly ACTIVATE: "tab.activate";
+    readonly GET_INFO: "tab.getInfo";
+};
+export declare const PageActions: {
+    readonly NAVIGATE: "page.navigate";
+    readonly RELOAD: "page.reload";
+    readonly BACK: "page.back";
+    readonly FORWARD: "page.forward";
+    readonly WAIT: "page.wait";
+    readonly INFO: "page.info";
+    readonly WAIT_FOR_NETWORK_IDLE: "page.waitForNetworkIdle";
+    /** XHR/Fetch 专用 idle 等待。语义上是 WAIT_FOR_NETWORK_IDLE + requestTypes=["XHR","Fetch"]。@since 0.4.0 */
+    readonly WAIT_FOR_XHR_IDLE: "page.waitForXhrIdle";
+    /** 等待 caller 传入的 JS 表达式返回 truthy。给 idle/element 无法表达的就绪信号
+     *  （如 Alpine `document.body._x_dataStack`、Vue `app.config.globalProperties.$ready`、
+     *  自定义 window flag）。@since 0.8.x */
+    readonly WAIT_FOR_EXPRESSION: "page.waitForExpression";
+};
+export declare const JsActions: {
+    readonly EVALUATE: "js.evaluate";
+    readonly EVALUATE_ASYNC: "js.evaluateAsync";
+    readonly CALL_FUNCTION: "js.callFunction";
+};
+export declare const DomActions: {
+    readonly QUERY: "dom.query";
+    readonly QUERY_ALL: "dom.queryAll";
+    readonly CLICK: "dom.click";
+    readonly TYPE: "dom.type";
+    readonly FILL: "dom.fill";
+    readonly SELECT: "dom.select";
+    readonly SCROLL: "dom.scroll";
+    readonly HOVER: "dom.hover";
+    readonly GET_ATTRIBUTE: "dom.getAttribute";
+    readonly GET_SCROLL_INFO: "dom.getScrollInfo";
+    readonly WAIT_FOR_MUTATION: "dom.waitForMutation";
+    /** 等待 DOM 子树在 quietMs ms 内无任何 mutation 后返回。与 WAIT_FOR_MUTATION 语义互补。@since 0.4.0 */
+    readonly WAIT_SETTLED: "dom.waitSettled";
+    /** 对 framework 受控组件（picker/cascader/select 等）提交值：打开→导航→点→确认的完整流程。@since 0.4.0 */
+    readonly COMMIT: "dom.commit";
+    readonly WATCH_MUTATIONS: "dom.watchMutations";
+    readonly UNWATCH_MUTATIONS: "dom.unwatchMutations";
+};
+export declare const ContentActions: {
+    readonly GET_TEXT: "content.getText";
+    readonly GET_HTML: "content.getHTML";
+    readonly GET_ACCESSIBILITY_TREE: "content.getAccessibilityTree";
+    readonly GET_ELEMENT_TEXT: "content.getElementText";
+    readonly GET_COMPUTED_STYLE: "content.getComputedStyle";
+};
+export declare const ConsoleActions: {
+    readonly GET_LOGS: "console.getLogs";
+    readonly GET_ERRORS: "console.getErrors";
+    readonly SUBSCRIBE: "console.subscribe";
+    readonly CLEAR: "console.clear";
+};
+export declare const NetworkActions: {
+    readonly GET_LOGS: "network.getLogs";
+    readonly GET_ERRORS: "network.getErrors";
+    readonly SUBSCRIBE: "network.subscribe";
+    readonly FILTER: "network.filter";
+    readonly CLEAR: "network.clear";
+    readonly GET_RESPONSE_BODY: "network.getResponseBody";
+};
+export declare const CaptureActions: {
+    readonly SCREENSHOT: "capture.screenshot";
+    readonly ELEMENT: "capture.element";
+    readonly GIF_START: "capture.gifStart";
+    readonly GIF_STOP: "capture.gifStop";
+    readonly GIF_FRAME: "capture.gifFrame";
+};
+export declare const StorageActions: {
+    readonly GET_COOKIES: "storage.getCookies";
+    readonly SET_COOKIE: "storage.setCookie";
+    readonly DELETE_COOKIE: "storage.deleteCookie";
+    readonly GET_LOCAL_STORAGE: "storage.getLocalStorage";
+    readonly SET_LOCAL_STORAGE: "storage.setLocalStorage";
+    readonly GET_SESSION_STORAGE: "storage.getSessionStorage";
+    readonly SET_SESSION_STORAGE: "storage.setSessionStorage";
+    readonly EXPORT_SESSION: "storage.exportSession";
+    readonly IMPORT_SESSION: "storage.importSession";
+};
+export declare const KeyboardActions: {
+    readonly PRESS: "keyboard.press";
+    readonly SHORTCUT: "keyboard.shortcut";
+};
+export declare const MouseActions: {
+    readonly CLICK: "mouse.click";
+    readonly DOUBLE_CLICK: "mouse.doubleClick";
+    readonly MOVE: "mouse.move";
+    readonly DRAG: "mouse.drag";
+};
+export declare const FramesActions: {
+    readonly LIST: "frames.list";
+    readonly FIND: "frames.find";
+};
+export declare const FileActions: {
+    readonly UPLOAD: "file.upload";
+    readonly DOWNLOAD: "file.download";
+    readonly GET_DOWNLOADS: "file.getDownloads";
+    readonly ON_DOWNLOAD_COMPLETE: "file.onDownloadComplete";
+};
+export declare const ObserveActions: {
+    readonly SNAPSHOT: "observe.snapshot";
+};
+export declare const EventsActions: {
+    /** 强制立即 flush dispatcher 的 notice+info buffer，绕过节流窗口 */
+    readonly DRAIN: "events.drain";
+};
+export declare const DiagnosticsActions: {
+    /** 返回扩展版本 + 支持的 action 列表指纹，供 MCP ping 做版本协商。@since 0.4.0 */
+    readonly VERSION: "diagnostics.version";
+};
+export type ActionString = (typeof TabActions)[keyof typeof TabActions] | (typeof PageActions)[keyof typeof PageActions] | (typeof JsActions)[keyof typeof JsActions] | (typeof DomActions)[keyof typeof DomActions] | (typeof ContentActions)[keyof typeof ContentActions] | (typeof ConsoleActions)[keyof typeof ConsoleActions] | (typeof NetworkActions)[keyof typeof NetworkActions] | (typeof CaptureActions)[keyof typeof CaptureActions] | (typeof StorageActions)[keyof typeof StorageActions] | (typeof KeyboardActions)[keyof typeof KeyboardActions] | (typeof MouseActions)[keyof typeof MouseActions] | (typeof FramesActions)[keyof typeof FramesActions] | (typeof FileActions)[keyof typeof FileActions] | (typeof ObserveActions)[keyof typeof ObserveActions] | (typeof EventsActions)[keyof typeof EventsActions] | (typeof DiagnosticsActions)[keyof typeof DiagnosticsActions];
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;IAQtB,kGAAkG;;IAElG;;wCAEoC;;CAE5B,CAAC;AAEX,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;;;;;IAYrB,oFAAoF;;IAEpF,iFAAiF;;;;CAIzE,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;;CAOjB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;CAMjB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;;;;;;CAUjB,CAAC;AAEX,eAAO,MAAM,eAAe;;;CAGlB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;CAKf,CAAC;AAEX,eAAO,MAAM,aAAa;;;CAGhB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;CAKd,CAAC;AAEX,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,aAAa;IACxB,wDAAwD;;CAEhD,CAAC;AAEX,eAAO,MAAM,kBAAkB;IAC7B,6DAA6D;;CAErD,CAAC;AAEX,MAAM,MAAM,YAAY,GACpB,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,GAC5C,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,GAC9C,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,GAC1C,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,GAC5C,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,GACtD,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,GAChD,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,GAClD,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,GAC9C,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,GACpD,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,GAClD,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/actions.js

@@ -0,0 +1,117 @@
+export const TabActions = {
+    LIST: "tab.list",
+    CREATE: "tab.create",
+    CLOSE: "tab.close",
+    ACTIVATE: "tab.activate",
+    GET_INFO: "tab.getInfo",
+};
+export const PageActions = {
+    NAVIGATE: "page.navigate",
+    RELOAD: "page.reload",
+    BACK: "page.back",
+    FORWARD: "page.forward",
+    WAIT: "page.wait",
+    INFO: "page.info",
+    WAIT_FOR_NETWORK_IDLE: "page.waitForNetworkIdle",
+    /** XHR/Fetch 专用 idle 等待。语义上是 WAIT_FOR_NETWORK_IDLE + requestTypes=["XHR","Fetch"]。@since 0.4.0 */
+    WAIT_FOR_XHR_IDLE: "page.waitForXhrIdle",
+    /** 等待 caller 传入的 JS 表达式返回 truthy。给 idle/element 无法表达的就绪信号
+     *  （如 Alpine `document.body._x_dataStack`、Vue `app.config.globalProperties.$ready`、
+     *  自定义 window flag）。@since 0.8.x */
+    WAIT_FOR_EXPRESSION: "page.waitForExpression",
+};
+export const JsActions = {
+    EVALUATE: "js.evaluate",
+    EVALUATE_ASYNC: "js.evaluateAsync",
+    CALL_FUNCTION: "js.callFunction",
+};
+export const DomActions = {
+    QUERY: "dom.query",
+    QUERY_ALL: "dom.queryAll",
+    CLICK: "dom.click",
+    TYPE: "dom.type",
+    FILL: "dom.fill",
+    SELECT: "dom.select",
+    SCROLL: "dom.scroll",
+    HOVER: "dom.hover",
+    GET_ATTRIBUTE: "dom.getAttribute",
+    GET_SCROLL_INFO: "dom.getScrollInfo",
+    WAIT_FOR_MUTATION: "dom.waitForMutation",
+    /** 等待 DOM 子树在 quietMs ms 内无任何 mutation 后返回。与 WAIT_FOR_MUTATION 语义互补。@since 0.4.0 */
+    WAIT_SETTLED: "dom.waitSettled",
+    /** 对 framework 受控组件（picker/cascader/select 等）提交值：打开→导航→点→确认的完整流程。@since 0.4.0 */
+    COMMIT: "dom.commit",
+    WATCH_MUTATIONS: "dom.watchMutations",
+    UNWATCH_MUTATIONS: "dom.unwatchMutations",
+};
+export const ContentActions = {
+    GET_TEXT: "content.getText",
+    GET_HTML: "content.getHTML",
+    GET_ACCESSIBILITY_TREE: "content.getAccessibilityTree",
+    GET_ELEMENT_TEXT: "content.getElementText",
+    GET_COMPUTED_STYLE: "content.getComputedStyle",
+};
+export const ConsoleActions = {
+    GET_LOGS: "console.getLogs",
+    GET_ERRORS: "console.getErrors",
+    SUBSCRIBE: "console.subscribe",
+    CLEAR: "console.clear",
+};
+export const NetworkActions = {
+    GET_LOGS: "network.getLogs",
+    GET_ERRORS: "network.getErrors",
+    SUBSCRIBE: "network.subscribe",
+    FILTER: "network.filter",
+    CLEAR: "network.clear",
+    GET_RESPONSE_BODY: "network.getResponseBody",
+};
+export const CaptureActions = {
+    SCREENSHOT: "capture.screenshot",
+    ELEMENT: "capture.element",
+    GIF_START: "capture.gifStart",
+    GIF_STOP: "capture.gifStop",
+    GIF_FRAME: "capture.gifFrame",
+};
+export const StorageActions = {
+    GET_COOKIES: "storage.getCookies",
+    SET_COOKIE: "storage.setCookie",
+    DELETE_COOKIE: "storage.deleteCookie",
+    GET_LOCAL_STORAGE: "storage.getLocalStorage",
+    SET_LOCAL_STORAGE: "storage.setLocalStorage",
+    GET_SESSION_STORAGE: "storage.getSessionStorage",
+    SET_SESSION_STORAGE: "storage.setSessionStorage",
+    EXPORT_SESSION: "storage.exportSession",
+    IMPORT_SESSION: "storage.importSession",
+};
+export const KeyboardActions = {
+    PRESS: "keyboard.press",
+    SHORTCUT: "keyboard.shortcut",
+};
+export const MouseActions = {
+    CLICK: "mouse.click",
+    DOUBLE_CLICK: "mouse.doubleClick",
+    MOVE: "mouse.move",
+    DRAG: "mouse.drag",
+};
+export const FramesActions = {
+    LIST: "frames.list",
+    FIND: "frames.find",
+};
+export const FileActions = {
+    UPLOAD: "file.upload",
+    DOWNLOAD: "file.download",
+    GET_DOWNLOADS: "file.getDownloads",
+    ON_DOWNLOAD_COMPLETE: "file.onDownloadComplete",
+};
+export const ObserveActions = {
+    SNAPSHOT: "observe.snapshot",
+};
+export const EventsActions = {
+    /** 强制立即 flush dispatcher 的 notice+info buffer，绕过节流窗口 */
+    DRAIN: "events.drain",
+};
+export const DiagnosticsActions = {
+    /** 返回扩展版本 + 支持的 action 列表指纹，供 MCP ping 做版本协商。@since 0.4.0 */
+    VERSION: "diagnostics.version",
+};
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/commit-kinds.d.ts

@@ -0,0 +1,3 @@
+export declare const COMMIT_KINDS: readonly ["daterange", "datetimerange", "cascader", "select", "time", "checkbox-group", "aria-select"];
+export type CommitKind = (typeof COMMIT_KINDS)[number];
+//# sourceMappingURL=commit-kinds.d.ts.map

package/dist/commit-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-kinds.d.ts","sourceRoot":"","sources":["../src/commit-kinds.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,YAAY,wGAQf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/commit-kinds.js

@@ -0,0 +1,20 @@
+// Single source of truth for vortex_fill commit driver kinds.
+//
+// Consumed by:
+// - packages/extension/src/patterns/commit-drivers.ts (CommitKind type + runtime registry)
+// - packages/mcp/src/tools/schemas-public.ts (vortex_fill.kind enum)
+// - packages/mcp/src/tools/schemas.ts (internal vortex_fill enum)
+//
+// Adding or removing a kind requires implementing / removing the corresponding
+// driver in commit-drivers.ts AND updating dom.ts commit handler switch.
+// I15 invariant test locks public schema enum === COMMIT_KINDS to prevent drift.
+export const COMMIT_KINDS = [
+    "daterange",
+    "datetimerange",
+    "cascader",
+    "select",
+    "time",
+    "checkbox-group",
+    "aria-select",
+];
+//# sourceMappingURL=commit-kinds.js.map

package/dist/commit-kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-kinds.js","sourceRoot":"","sources":["../src/commit-kinds.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,eAAe;AACf,2FAA2F;AAC3F,qEAAqE;AACrE,kEAAkE;AAClE,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,iFAAiF;AAEjF,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW;IACX,eAAe;IACf,UAAU;IACV,QAAQ;IACR,MAAM;IACN,gBAAgB;IAChB,aAAa;CACL,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,106 @@
+export declare const VtxErrorCode: {
+    readonly ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND";
+    readonly ELEMENT_OCCLUDED: "ELEMENT_OCCLUDED";
+    readonly ELEMENT_OFFSCREEN: "ELEMENT_OFFSCREEN";
+    readonly ELEMENT_DISABLED: "ELEMENT_DISABLED";
+    readonly ELEMENT_DETACHED: "ELEMENT_DETACHED";
+    readonly SELECTOR_AMBIGUOUS: "SELECTOR_AMBIGUOUS";
+    readonly NAVIGATION_IN_PROGRESS: "NAVIGATION_IN_PROGRESS";
+    readonly PAGE_NOT_READY: "PAGE_NOT_READY";
+    readonly DIALOG_BLOCKING: "DIALOG_BLOCKING";
+    readonly IFRAME_NOT_READY: "IFRAME_NOT_READY";
+    readonly STALE_SNAPSHOT: "STALE_SNAPSHOT";
+    readonly INVALID_INDEX: "INVALID_INDEX";
+    readonly NAVIGATION_FAILED: "NAVIGATION_FAILED";
+    readonly TAB_NOT_FOUND: "TAB_NOT_FOUND";
+    readonly TAB_CLOSED: "TAB_CLOSED";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly JS_EXECUTION_ERROR: "JS_EXECUTION_ERROR";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly CSP_BLOCKED: "CSP_BLOCKED";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly NATIVE_MESSAGING_ERROR: "NATIVE_MESSAGING_ERROR";
+    readonly EXTENSION_NOT_CONNECTED: "EXTENSION_NOT_CONNECTED";
+    readonly INVALID_PARAMS: "INVALID_PARAMS";
+    readonly UNKNOWN_ACTION: "UNKNOWN_ACTION";
+    /** 目标元素属于框架托管的受控组件（如 Element Plus datetime-range picker），
+     *  不能用普通 DOM 原语（fill/type）安全提交值；需换用 vortex_dom_commit。 */
+    readonly UNSUPPORTED_TARGET: "UNSUPPORTED_TARGET";
+    /** vortex_dom_commit 的 driver 在流程中途失败（picker 打不开、日期格找不到、校验不一致等）。
+     *  context.extras 会带 stage 字段标识失败阶段。*/
+    readonly COMMIT_FAILED: "COMMIT_FAILED";
+    /** Actionability: element detached from DOM */
+    readonly NOT_ATTACHED: "NOT_ATTACHED";
+    /** Actionability: display:none / visibility:hidden / opacity:0 / 0x0 */
+    readonly NOT_VISIBLE: "NOT_VISIBLE";
+    /** Actionability: double-RAF sample shows unstable position (animating) */
+    readonly NOT_STABLE: "NOT_STABLE";
+    /** Actionability: hit-test hit a different element (covered) */
+    readonly OBSCURED: "OBSCURED";
+    /** Actionability: disabled / aria-disabled / fieldset[disabled] */
+    readonly DISABLED: "DISABLED";
+    /** Actionability: fill/type target is readonly or non-input */
+    readonly NOT_EDITABLE: "NOT_EDITABLE";
+    /** Fallback chain exhausted all paths */
+    readonly ACTION_FAILED_ALL_PATHS: "ACTION_FAILED_ALL_PATHS";
+    /** Drag operation but CDP unavailable */
+    readonly DRAG_REQUIRES_CDP: "DRAG_REQUIRES_CDP";
+    /** select action: 传入的 value 在 <select> 的 option 里既不匹配 value 属性、
+     *  也不匹配可见文本(label)。避免静默选不中却返回 success。
+     *  context.extras.available 带可选项清单供 agent 重新选取。*/
+    readonly NO_MATCHING_OPTION: "NO_MATCHING_OPTION";
+    /** 赋值/驱动类 act 原语(select 多选 / scroll / press 等)dispatch 后回读校验,
+     *  发现副作用未真正发生(选项未选中 / 未滚动 / 状态未变)。避免 dispatch 即返回
+     *  success 的 silent false-success(2026-06-03 act 原语白盒审计族 A)。*/
+    readonly NO_EFFECT: "NO_EFFECT";
+    /** a11y tree 不可用（CSP / sandboxed page），无法 getFullAXTree。*/
+    readonly A11Y_UNAVAILABLE: "A11Y_UNAVAILABLE";
+    /** chrome.debugger.attach 失败（缺权限、tab 已关闭等）。*/
+    readonly CDP_NOT_ATTACHED: "CDP_NOT_ATTACHED";
+    /** ref 关联节点 stale，descriptor 三级消解仍然失败。*/
+    readonly STALE_REF: "STALE_REF";
+    /** descriptor strict 模式下多匹配。*/
+    readonly AMBIGUOUS_DESCRIPTOR: "AMBIGUOUS_DESCRIPTOR";
+    /** RefStore 中找不到此 ref。*/
+    readonly REF_NOT_FOUND: "REF_NOT_FOUND";
+    /** snapshot 已过期（> 5 min）。*/
+    readonly SNAPSHOT_EXPIRED: "SNAPSHOT_EXPIRED";
+    /** 跨源 iframe，Accessibility.getFullAXTree 拒绝（CDP 已 attach，但 AX tree 不能跨源查询）。*/
+    readonly CROSS_ORIGIN_IFRAME: "CROSS_ORIGIN_IFRAME";
+    /** closed shadow host，无法穿透。*/
+    readonly CLOSED_SHADOW_DOM: "CLOSED_SHADOW_DOM";
+    /** 元素在 open shadow root 内：observe 经 querySelectorAllDeep 穿 shadow 发出了 ref，
+     *  但 act/fill 的 CSS selector 解析不穿 shadow → 永久不可解析。快速失败给诊断，
+     *  而非 NOT_ATTACHED 重试满 timeout（issue #27）。*/
+    readonly OPEN_SHADOW_DOM: "OPEN_SHADOW_DOM";
+    /** target 既不是合法 ref 也不是 valid descriptor 对象。*/
+    readonly INVALID_TARGET: "INVALID_TARGET";
+    /** action 不在 act 7 enum 内（click/fill/type/select/scroll/hover/drag）。*/
+    readonly UNSUPPORTED_ACTION: "UNSUPPORTED_ACTION";
+};
+export type VtxErrorCode = (typeof VtxErrorCode)[keyof typeof VtxErrorCode];
+export interface VtxErrorContext {
+    selector?: string;
+    index?: number;
+    snapshotId?: string;
+    tabId?: number;
+    frameId?: number;
+    /** 兜底字段：存放 handler 场景特有的结构化信息（如遮挡元素 tag、目标 URL、action 名等） */
+    extras?: Record<string, unknown>;
+}
+export interface VtxErrorPayload {
+    code: VtxErrorCode;
+    message: string;
+    hint?: string;
+    recoverable?: boolean;
+    context?: VtxErrorContext;
+}
+export type VtxErrorExtra = Omit<VtxErrorPayload, "code" | "message">;
+export declare class VtxError extends Error {
+    readonly code: VtxErrorCode;
+    readonly extra?: VtxErrorExtra | undefined;
+    constructor(code: VtxErrorCode, message: string, extra?: VtxErrorExtra | undefined);
+    toJSON(): VtxErrorPayload;
+    toString(): string;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;IAsCvB;8DAC0D;;IAE1D;2CACuC;;IAIvC,+CAA+C;;IAE/C,wEAAwE;;IAExE,2EAA2E;;IAE3E,gEAAgE;;IAEhE,mEAAmE;;IAEnE,+DAA+D;;IAE/D,yCAAyC;;IAEzC,yCAAyC;;IAEzC;;sDAEkD;;IAElD;;mEAE+D;;IAI/D,2DAA2D;;IAE3D,8CAA8C;;IAE9C,yCAAyC;;IAEzC,+BAA+B;;IAE/B,yBAAyB;;IAEzB,4BAA4B;;IAE5B,8EAA8E;;IAE9E,8BAA8B;;IAE9B;;iDAE6C;;IAI7C,+CAA+C;;IAE/C,uEAAuE;;CAE/D,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAED,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEtE,qBAAa,QAAS,SAAQ,KAAK;aAEf,IAAI,EAAE,YAAY;aAElB,KAAK,CAAC,EAAE,aAAa;gBAFrB,IAAI,EAAE,YAAY,EAClC,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,aAAa,YAAA;IAMvC,MAAM,IAAI,eAAe;IAWzB,QAAQ,IAAI,MAAM;CAGnB"}

package/dist/errors.hints.d.ts

@@ -0,0 +1,28 @@
+import { VtxError, VtxErrorCode } from "./errors.js";
+import type { VtxErrorContext } from "./errors.js";
+/**
+ * 错误元信息：给上游 LLM Agent 的恢复提示。
+ *
+ * `recoverable` 语义：
+ * - `true`：同一动作带参数调整后重试可能成功（如 ELEMENT_OCCLUDED 清理遮挡后重试）
+ * - `false`：同一动作重试无意义，但 hint 可能指引换一个动作达成目标
+ *   （如 TAB_CLOSED 需要换 tab，不是动作本身的重试）
+ *
+ * Hint quality contract（I19 + I20，see L5-spec §1.2/§1.4）:
+ * - 含 next-action 动词（call/use/verify/check/retry/wait/set/inspect/...）
+ * - 含工具名 OR 参数关键词（vortex_*, selector, mode, action, ...）
+ * - 长度 50-300 字符
+ * - 引用工具名必须在 v0.6 公开 11 之内（否则 LLM tools/list 看不到）
+ */
+export interface VtxErrorMeta {
+    hint: string;
+    recoverable: boolean;
+}
+export declare const DEFAULT_ERROR_META: Record<VtxErrorCode, VtxErrorMeta>;
+/**
+ * 便捷构造 VtxError：自动注入 DEFAULT_ERROR_META 的 hint 与 recoverable。
+ * 调用方只需传 code / message / context。
+ * 如需覆盖默认 hint 或 recoverable，传 `override` 参数。
+ */
+export declare function vtxError(code: VtxErrorCode, message: string, context?: VtxErrorContext, override?: Partial<VtxErrorMeta>): VtxError;
+//# sourceMappingURL=errors.hints.d.ts.map

package/dist/errors.hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.hints.d.ts","sourceRoot":"","sources":["../src/errors.hints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,aAAa,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,YAAY,EAAE,YAAY,CAkNjE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,EACzB,QAAQ,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC/B,QAAQ,CAQV"}

package/dist/errors.hints.js

@@ -0,0 +1,217 @@
+import { VtxError } from "./errors.js";
+export const DEFAULT_ERROR_META = {
+    // -- 元素定位 --
+    ELEMENT_NOT_FOUND: {
+        hint: "Element not found. Verify the selector or call vortex_observe to list interactive elements with their refs. If the element may live inside an iframe, call vortex_observe with scope='full' to descend into iframes — the returned element.frameId routes follow-up vortex_act correctly.",
+        recoverable: true,
+    },
+    ELEMENT_OCCLUDED: {
+        hint: "Element is covered by another (modal / overlay / cookie banner). Inspect via vortex_screenshot to identify the blocker, dismiss it via vortex_act with action='click' on its close selector, then retry.",
+        recoverable: true,
+    },
+    ELEMENT_OFFSCREEN: {
+        hint: "Element is outside the viewport. Call vortex_act with action='scroll' on the target to bring it into view, then retry the original action.",
+        recoverable: true,
+    },
+    ELEMENT_DISABLED: {
+        hint: "Element has the disabled attribute. Fill required prior fields via vortex_act or satisfy prerequisites to enable it, then retry.",
+        recoverable: true,
+    },
+    ELEMENT_DETACHED: {
+        hint: "Element was removed from the DOM. Call vortex_observe to capture the current state and retry with the new ref.",
+        recoverable: true,
+    },
+    SELECTOR_AMBIGUOUS: {
+        hint: "Selector matched multiple elements. Use a more specific selector, or call vortex_observe to get unique ref indexes (@eN form).",
+        recoverable: true,
+    },
+    // -- 页面状态 --
+    NAVIGATION_IN_PROGRESS: {
+        hint: "A page navigation is in progress. Call vortex_wait_for with mode='idle' and value='network' before retrying the action.",
+        recoverable: true,
+    },
+    PAGE_NOT_READY: {
+        hint: "Page DOM is not ready. Call vortex_wait_for with mode='element' on a load-marker selector, or mode='idle' value='network', before retrying.",
+        recoverable: true,
+    },
+    DIALOG_BLOCKING: {
+        hint: "A native browser dialog (alert / confirm / prompt) is blocking. Handle or dismiss it via vortex_act with action='click' on the OK / Cancel selector, then retry.",
+        recoverable: true,
+    },
+    IFRAME_NOT_READY: {
+        hint: "Target iframe is not ready or not yet loaded. Retry vortex_observe with scope='full' to descend into iframes — the returned elements carry frameId so follow-up vortex_act routes correctly.",
+        recoverable: true,
+    },
+    // -- Snapshot --
+    STALE_SNAPSHOT: {
+        hint: "Page has changed since the snapshot. Call vortex_observe to capture a fresh snapshot, then retry with the new ref.",
+        recoverable: true,
+    },
+    INVALID_INDEX: {
+        hint: "Index does not exist in this snapshot. Call vortex_observe to list valid ref indexes (@eN form).",
+        recoverable: true,
+    },
+    // -- 网络与标签 --
+    NAVIGATION_FAILED: {
+        hint: "Navigation failed (network error, blocked URL, or invalid URL). Verify the url argument passed to vortex_navigate and retry; the context may carry the underlying browser error.",
+        recoverable: true,
+    },
+    TAB_NOT_FOUND: {
+        hint: "tabId argument does not exist. Call vortex_tab_create to open a new tab, or omit tabId to operate on the active tab.",
+        recoverable: false,
+    },
+    TAB_CLOSED: {
+        hint: "The target tab was closed during execution. Call vortex_tab_create to open a new tab and re-run the flow, or pick another tabId.",
+        recoverable: false,
+    },
+    // -- 执行与权限 --
+    TIMEOUT: {
+        hint: "Action timed out. Increase the timeout argument, or call vortex_wait_for with mode='idle' to let the page settle before retrying.",
+        recoverable: true,
+    },
+    JS_EXECUTION_ERROR: {
+        hint: "Injected JavaScript threw an error. Inspect the error message in context.extras and adjust the selector or action arguments before retrying.",
+        recoverable: false,
+    },
+    PERMISSION_DENIED: {
+        hint: "Operation blocked by browser permission (cross-origin, file access, or extension permission). Verify the manifest permissions attribute and the target tab is not chrome://.",
+        recoverable: false,
+    },
+    CSP_BLOCKED: {
+        hint: "Action blocked by Content-Security-Policy. Use vortex_act with action='click' (which routes via CDP real mouse and bypasses page-side CSP), or pick a selector outside the CSP-restricted frame.",
+        recoverable: true,
+    },
+    INTERNAL_ERROR: {
+        hint: "Unexpected error in the vortex runtime (server / mcp). Inspect context.extras for the underlying message and retry — transient errors often recover.",
+        recoverable: true,
+    },
+    // -- 传输层 --
+    NATIVE_MESSAGING_ERROR: {
+        hint: "Native messaging channel error. Verify the vortex host is installed and the extension is reloaded; inspect the chrome://extensions page for the connection state.",
+        recoverable: false,
+    },
+    EXTENSION_NOT_CONNECTED: {
+        hint: "Vortex extension is not connected. Ensure Chrome is open with the extension enabled at chrome://extensions, then call vortex_observe to re-check connectivity.",
+        recoverable: false,
+    },
+    INVALID_PARAMS: {
+        hint: "Invalid parameters. Check the tool schema for required fields and value constraints, then retry with corrected arguments.",
+        recoverable: false,
+    },
+    UNKNOWN_ACTION: {
+        hint: "Unknown action. Verify the action argument spelling matches the tool's enum (e.g. vortex_act expects click / fill / type / select / scroll / hover).",
+        recoverable: false,
+    },
+    // -- 组件 / 框架 --
+    UNSUPPORTED_TARGET: {
+        hint: "Target is a framework-controlled component (e.g. Element Plus datetime-range picker). The runtime auto-routes to a commit driver via vortex_act; if the framework version is not yet covered, inspect context.extras.kind and pick a CSS selector outside the controlled region.",
+        recoverable: false,
+    },
+    COMMIT_FAILED: {
+        hint: "Commit driver failed mid-flow. Inspect context.extras.stage (open-picker / navigate-month / click-day / confirm / verify) to see which step broke; the page state may have changed or the framework version may not be matched by any driver.",
+        recoverable: true,
+    },
+    // -- L2 Action layer --
+    NOT_ATTACHED: {
+        hint: "Element detached from DOM. Call vortex_observe to re-locate the element and retry vortex_act with the fresh ref.",
+        recoverable: true,
+    },
+    NOT_VISIBLE: {
+        hint: "Element not visible (display:none / visibility:hidden / 0x0 box). Call vortex_wait_for with mode='element' on a parent visibility marker, or check whether the parent container is hidden.",
+        recoverable: true,
+    },
+    NOT_STABLE: {
+        hint: "Element position is unstable (animating). Call vortex_wait_for with mode='idle' to let the animation settle, then retry vortex_act.",
+        recoverable: true,
+    },
+    OBSCURED: {
+        hint: "Element hit-test failed; covered by another element (e.g. modal / loading overlay). Inspect via vortex_screenshot, dismiss the overlay (context.extras.blocker may identify it), then retry.",
+        recoverable: true,
+    },
+    DISABLED: {
+        hint: "Element is disabled (disabled attribute / aria-disabled / fieldset[disabled]). Complete prerequisite vortex_act interactions to unlock it before retrying.",
+        recoverable: true,
+    },
+    NOT_EDITABLE: {
+        hint: "Target is not editable (readonly or non-input element). Use vortex_extract to read its text instead, or pick a different selector that points to an actual input.",
+        recoverable: false,
+    },
+    ACTION_FAILED_ALL_PATHS: {
+        hint: "All fallback paths exhausted (dispatchEvent → CDP → ...). context.extras.attemptedPaths lists what was tried. Inspect via vortex_screenshot, retry with a different selector, or check whether the element lives in a closed shadow root.",
+        recoverable: false,
+    },
+    DRAG_REQUIRES_CDP: {
+        hint: "Drag operation requires CDP, but CDP is unavailable (DevTools may be open, or chrome.debugger attach was denied). Close DevTools and retry; drag is exposed via vortex_act with action='drag' once CDP attaches.",
+        recoverable: false,
+    },
+    // -- L3 Reasoning（@since 0.6.0 PR #3）--
+    A11Y_UNAVAILABLE: {
+        hint: "Accessibility tree unavailable on this page (CSP-restricted or sandboxed). Switch to a regular page or fall back to CSS selectors via vortex_act and vortex_extract.",
+        recoverable: false,
+    },
+    CDP_NOT_ATTACHED: {
+        hint: "chrome.debugger could not attach to the tab. Verify the manifest debugger attribute is granted, and the tab is not chrome:// or chrome-extension:// (CDP cannot attach to those).",
+        recoverable: false,
+    },
+    STALE_REF: {
+        hint: "Element ref is stale and could not be re-resolved by descriptor. Call vortex_observe to mint fresh refs and retry.",
+        recoverable: true,
+    },
+    AMBIGUOUS_DESCRIPTOR: {
+        hint: "Descriptor matched multiple elements in strict mode. Add a 'near' relation to disambiguate, narrow the name attribute, or set strict:false to take the first match.",
+        recoverable: true,
+    },
+    REF_NOT_FOUND: {
+        hint: "ref does not exist in the current RefStore. Call vortex_observe to mint fresh refs and retry the action.",
+        recoverable: true,
+    },
+    SNAPSHOT_EXPIRED: {
+        hint: "Snapshot expired (> 5 min). Call vortex_observe to capture a new snapshot and retry with the fresh ref.",
+        recoverable: true,
+    },
+    CROSS_ORIGIN_IFRAME: {
+        hint: "Accessibility.getFullAXTree was rejected for a cross-origin frameId; the AX tree cannot be queried across origin boundaries. Switch to a same-origin entry point or operate within the iframe via its own tab context.",
+        recoverable: false,
+    },
+    CLOSED_SHADOW_DOM: {
+        hint: "Element lives inside a closed shadow root and cannot be pierced. Ask the component author to switch the mode attribute to 'open', or expose an ARIA-rich light-DOM proxy selector.",
+        recoverable: false,
+    },
+    OPEN_SHADOW_DOM: {
+        hint: "Element lives inside an open shadow root that vortex_observe surfaced but act cannot reach via a CSS selector. Expose a light-DOM proxy selector for the control, or have the component render the actionable element in light DOM.",
+        recoverable: false,
+    },
+    NO_MATCHING_OPTION: {
+        hint: "The select value matched no <option> by value attribute or visible text. Read the available options (listed in context.extras.available) and retry vortex_act select with an exact option value or label.",
+        recoverable: true,
+    },
+    NO_EFFECT: {
+        hint: "The action dispatched but a post-action read-back showed no real change (option not selected, page not scrolled, state unchanged). The target may be a disabled option or a no-op scroll. Re-observe and verify the element is operable before retrying.",
+        recoverable: true,
+    },
+    // -- L4 Task layer（@since 0.6.0 PR #4）--
+    INVALID_TARGET: {
+        hint: "Use a target ref string like @e3 (returned from vortex_observe) or a CSS selector. The Descriptor object form arrives in v0.6.x once the resolver lands.",
+        recoverable: false,
+    },
+    UNSUPPORTED_ACTION: {
+        hint: "Verify the action argument matches one of vortex_act's enum values: click, fill, type, select, scroll, hover. The drag action is not yet exposed via vortex_act in v0.6.",
+        recoverable: false,
+    },
+};
+/**
+ * 便捷构造 VtxError：自动注入 DEFAULT_ERROR_META 的 hint 与 recoverable。
+ * 调用方只需传 code / message / context。
+ * 如需覆盖默认 hint 或 recoverable，传 `override` 参数。
+ */
+export function vtxError(code, message, context, override) {
+    const meta = DEFAULT_ERROR_META[code];
+    const extra = {
+        hint: override?.hint ?? meta.hint,
+        recoverable: override?.recoverable ?? meta.recoverable,
+    };
+    if (context !== undefined)
+        extra.context = context;
+    return new VtxError(code, message, extra);
+}
+//# sourceMappingURL=errors.hints.js.map

package/dist/errors.hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.hints.js","sourceRoot":"","sources":["../src/errors.hints.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -0,0 +1,117 @@
+export const VtxErrorCode = {
+    // -- 元素定位（6 类）--
+    ELEMENT_NOT_FOUND: "ELEMENT_NOT_FOUND",
+    ELEMENT_OCCLUDED: "ELEMENT_OCCLUDED",
+    ELEMENT_OFFSCREEN: "ELEMENT_OFFSCREEN",
+    ELEMENT_DISABLED: "ELEMENT_DISABLED",
+    ELEMENT_DETACHED: "ELEMENT_DETACHED",
+    SELECTOR_AMBIGUOUS: "SELECTOR_AMBIGUOUS",
+    // -- 页面状态（4 类）--
+    NAVIGATION_IN_PROGRESS: "NAVIGATION_IN_PROGRESS",
+    PAGE_NOT_READY: "PAGE_NOT_READY",
+    DIALOG_BLOCKING: "DIALOG_BLOCKING",
+    IFRAME_NOT_READY: "IFRAME_NOT_READY",
+    // -- Snapshot（2 类，配合 vortex_observe）--
+    STALE_SNAPSHOT: "STALE_SNAPSHOT",
+    INVALID_INDEX: "INVALID_INDEX",
+    // -- 网络与标签（3 类）--
+    NAVIGATION_FAILED: "NAVIGATION_FAILED",
+    TAB_NOT_FOUND: "TAB_NOT_FOUND",
+    TAB_CLOSED: "TAB_CLOSED",
+    // -- 执行与权限（5 类）--
+    TIMEOUT: "TIMEOUT",
+    JS_EXECUTION_ERROR: "JS_EXECUTION_ERROR",
+    PERMISSION_DENIED: "PERMISSION_DENIED",
+    CSP_BLOCKED: "CSP_BLOCKED",
+    INTERNAL_ERROR: "INTERNAL_ERROR",
+    // -- 传输层（4 类）--
+    NATIVE_MESSAGING_ERROR: "NATIVE_MESSAGING_ERROR",
+    EXTENSION_NOT_CONNECTED: "EXTENSION_NOT_CONNECTED",
+    INVALID_PARAMS: "INVALID_PARAMS",
+    UNKNOWN_ACTION: "UNKNOWN_ACTION",
+    // -- 组件 / 框架（2 类，@since 0.4.0）--
+    /** 目标元素属于框架托管的受控组件（如 Element Plus datetime-range picker），
+     *  不能用普通 DOM 原语（fill/type）安全提交值；需换用 vortex_dom_commit。 */
+    UNSUPPORTED_TARGET: "UNSUPPORTED_TARGET",
+    /** vortex_dom_commit 的 driver 在流程中途失败（picker 打不开、日期格找不到、校验不一致等）。
+     *  context.extras 会带 stage 字段标识失败阶段。*/
+    COMMIT_FAILED: "COMMIT_FAILED",
+    // -- L2 Action layer (added in PR #2) --
+    /** Actionability: element detached from DOM */
+    NOT_ATTACHED: "NOT_ATTACHED",
+    /** Actionability: display:none / visibility:hidden / opacity:0 / 0x0 */
+    NOT_VISIBLE: "NOT_VISIBLE",
+    /** Actionability: double-RAF sample shows unstable position (animating) */
+    NOT_STABLE: "NOT_STABLE",
+    /** Actionability: hit-test hit a different element (covered) */
+    OBSCURED: "OBSCURED",
+    /** Actionability: disabled / aria-disabled / fieldset[disabled] */
+    DISABLED: "DISABLED",
+    /** Actionability: fill/type target is readonly or non-input */
+    NOT_EDITABLE: "NOT_EDITABLE",
+    /** Fallback chain exhausted all paths */
+    ACTION_FAILED_ALL_PATHS: "ACTION_FAILED_ALL_PATHS",
+    /** Drag operation but CDP unavailable */
+    DRAG_REQUIRES_CDP: "DRAG_REQUIRES_CDP",
+    /** select action: 传入的 value 在 <select> 的 option 里既不匹配 value 属性、
+     *  也不匹配可见文本(label)。避免静默选不中却返回 success。
+     *  context.extras.available 带可选项清单供 agent 重新选取。*/
+    NO_MATCHING_OPTION: "NO_MATCHING_OPTION",
+    /** 赋值/驱动类 act 原语(select 多选 / scroll / press 等)dispatch 后回读校验,
+     *  发现副作用未真正发生(选项未选中 / 未滚动 / 状态未变)。避免 dispatch 即返回
+     *  success 的 silent false-success(2026-06-03 act 原语白盒审计族 A)。*/
+    NO_EFFECT: "NO_EFFECT",
+    // -- L3 Reasoning（9 类：8 @since 0.6.0 PR #3 + OPEN_SHADOW_DOM @issue #27）--
+    /** a11y tree 不可用（CSP / sandboxed page），无法 getFullAXTree。*/
+    A11Y_UNAVAILABLE: "A11Y_UNAVAILABLE",
+    /** chrome.debugger.attach 失败（缺权限、tab 已关闭等）。*/
+    CDP_NOT_ATTACHED: "CDP_NOT_ATTACHED",
+    /** ref 关联节点 stale，descriptor 三级消解仍然失败。*/
+    STALE_REF: "STALE_REF",
+    /** descriptor strict 模式下多匹配。*/
+    AMBIGUOUS_DESCRIPTOR: "AMBIGUOUS_DESCRIPTOR",
+    /** RefStore 中找不到此 ref。*/
+    REF_NOT_FOUND: "REF_NOT_FOUND",
+    /** snapshot 已过期（> 5 min）。*/
+    SNAPSHOT_EXPIRED: "SNAPSHOT_EXPIRED",
+    /** 跨源 iframe，Accessibility.getFullAXTree 拒绝（CDP 已 attach，但 AX tree 不能跨源查询）。*/
+    CROSS_ORIGIN_IFRAME: "CROSS_ORIGIN_IFRAME",
+    /** closed shadow host，无法穿透。*/
+    CLOSED_SHADOW_DOM: "CLOSED_SHADOW_DOM",
+    /** 元素在 open shadow root 内：observe 经 querySelectorAllDeep 穿 shadow 发出了 ref，
+     *  但 act/fill 的 CSS selector 解析不穿 shadow → 永久不可解析。快速失败给诊断，
+     *  而非 NOT_ATTACHED 重试满 timeout（issue #27）。*/
+    OPEN_SHADOW_DOM: "OPEN_SHADOW_DOM",
+    // -- L4 Task layer（2 类，@since 0.6.0 PR #4）--
+    /** target 既不是合法 ref 也不是 valid descriptor 对象。*/
+    INVALID_TARGET: "INVALID_TARGET",
+    /** action 不在 act 7 enum 内（click/fill/type/select/scroll/hover/drag）。*/
+    UNSUPPORTED_ACTION: "UNSUPPORTED_ACTION",
+};
+export class VtxError extends Error {
+    code;
+    extra;
+    constructor(code, message, extra) {
+        super(message);
+        this.code = code;
+        this.extra = extra;
+        this.name = "VtxError";
+    }
+    toJSON() {
+        const payload = {
+            code: this.code,
+            message: this.message,
+        };
+        if (this.extra?.hint !== undefined)
+            payload.hint = this.extra.hint;
+        if (this.extra?.recoverable !== undefined)
+            payload.recoverable = this.extra.recoverable;
+        if (this.extra?.context !== undefined)
+            payload.context = this.extra.context;
+        return payload;
+    }
+    toString() {
+        return `VtxError[${this.code}]: ${this.message}`;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 事件系统：vortex 从"被动响应请求"升格为"主动推送事件"。
+ *
+ * - urgent：默认推送（用户介入 / 阻塞性事件）
+ * - notice：订阅后推送
+ * - info：debug/观察用，需显式订阅
+ */
+export type VtxEventLevel = "info" | "notice" | "urgent";
+export declare const VtxEventType: {
+    readonly USER_SWITCHED_TAB: "user.switched_tab";
+    readonly USER_CLOSED_TAB: "user.closed_tab";
+    readonly DIALOG_OPENED: "dialog.opened";
+    readonly DOWNLOAD_COMPLETED: "download.completed";
+    readonly EXTENSION_DISCONNECTED: "extension.disconnected";
+    readonly PAGE_NAVIGATED: "page.navigated";
+    readonly NETWORK_ERROR_DETECTED: "network.error_detected";
+    readonly CONSOLE_ERROR: "console.error";
+    readonly FORM_SUBMITTED: "form.submitted";
+    readonly DOM_MUTATED: "dom.mutated";
+    readonly NETWORK_REQUEST: "network.request";
+};
+export type VtxEventType = (typeof VtxEventType)[keyof typeof VtxEventType];
+/**
+ * 每个事件类型的默认 level。未在表中的事件（例如 legacy 的
+ * "console.message" / "network.requestStart"）默认视为 "info"。
+ */
+export declare const EVENT_LEVEL: Record<string, VtxEventLevel>;
+export declare function eventLevelOf(eventName: string): VtxEventLevel;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEzD,eAAO,MAAM,YAAY;;;;;;;;;;;;CAiBf,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAYrD,CAAC;AAEF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAE7D"}

package/dist/events.js

@@ -0,0 +1,37 @@
+export const VtxEventType = {
+    // urgent
+    USER_SWITCHED_TAB: "user.switched_tab",
+    USER_CLOSED_TAB: "user.closed_tab",
+    DIALOG_OPENED: "dialog.opened",
+    DOWNLOAD_COMPLETED: "download.completed",
+    EXTENSION_DISCONNECTED: "extension.disconnected",
+    // notice
+    PAGE_NAVIGATED: "page.navigated",
+    NETWORK_ERROR_DETECTED: "network.error_detected",
+    CONSOLE_ERROR: "console.error",
+    FORM_SUBMITTED: "form.submitted",
+    // info
+    DOM_MUTATED: "dom.mutated",
+    NETWORK_REQUEST: "network.request",
+};
+/**
+ * 每个事件类型的默认 level。未在表中的事件（例如 legacy 的
+ * "console.message" / "network.requestStart"）默认视为 "info"。
+ */
+export const EVENT_LEVEL = {
+    "user.switched_tab": "urgent",
+    "user.closed_tab": "urgent",
+    "dialog.opened": "urgent",
+    "download.completed": "urgent",
+    "extension.disconnected": "urgent",
+    "page.navigated": "notice",
+    "network.error_detected": "notice",
+    "console.error": "notice",
+    "form.submitted": "notice",
+    "dom.mutated": "info",
+    "network.request": "info",
+};
+export function eventLevelOf(eventName) {
+    return EVENT_LEVEL[eventName] ?? "info";
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AASA,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,SAAS;IACT,iBAAiB,EAAE,mBAAmB;IACtC,eAAe,EAAE,iBAAiB;IAClC,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,oBAAoB;IACxC,sBAAsB,EAAE,wBAAwB;IAEhD,SAAS;IACT,cAAc,EAAE,gBAAgB;IAChC,sBAAsB,EAAE,wBAAwB;IAChD,aAAa,EAAE,eAAe;IAC9B,cAAc,EAAE,gBAAgB;IAEhC,OAAO;IACP,WAAW,EAAE,aAAa;IAC1B,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAIX;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkC;IACxD,mBAAmB,EAAE,QAAQ;IAC7B,iBAAiB,EAAE,QAAQ;IAC3B,eAAe,EAAE,QAAQ;IACzB,oBAAoB,EAAE,QAAQ;IAC9B,wBAAwB,EAAE,QAAQ;IAClC,gBAAgB,EAAE,QAAQ;IAC1B,wBAAwB,EAAE,QAAQ;IAClC,eAAe,EAAE,QAAQ;IACzB,gBAAgB,EAAE,QAAQ;IAC1B,aAAa,EAAE,MAAM;IACrB,iBAAiB,EAAE,MAAM;CAC1B,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,WAAW,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./protocol.js";
+export * from "./errors.js";
+export * from "./errors.hints.js";
+export * from "./actions.js";
+export * from "./events.js";
+export * from "./commit-kinds.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./protocol.js";
+export * from "./errors.js";
+export * from "./errors.hints.js";
+export * from "./actions.js";
+export * from "./events.js";
+export * from "./commit-kinds.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,74 @@
+import type { VtxErrorPayload } from "./errors.js";
+import type { VtxEventLevel } from "./events.js";
+export interface VtxRequest {
+    action: string;
+    params?: Record<string, unknown>;
+    id: string;
+    tabId?: number;
+}
+export interface VtxResponse {
+    action: string;
+    id: string;
+    result?: unknown;
+    error?: VtxErrorPayload;
+}
+export interface VtxEvent {
+    event: string;
+    data: unknown;
+    tabId?: number;
+    frameId?: number;
+    level?: VtxEventLevel;
+    timestamp: number;
+}
+export interface NmRequest {
+    type: "tool_request";
+    tool: string;
+    args: Record<string, unknown>;
+    requestId: string;
+    tabId?: number;
+}
+export interface NmResponse {
+    type: "tool_response";
+    requestId: string;
+    result?: unknown;
+    error?: VtxErrorPayload;
+}
+export interface NmEvent {
+    type: "event";
+    event: string;
+    data: unknown;
+    tabId?: number;
+    frameId?: number;
+    level?: VtxEventLevel;
+}
+export interface NmResponseChunk {
+    type: "tool_response_chunk";
+    requestId: string;
+    chunkIndex: number;
+    totalChunks: number;
+    data: string;
+}
+export interface NmPing {
+    type: "ping";
+}
+export interface NmPong {
+    type: "pong";
+}
+/**
+ * Server→Extension 控制消息。@since 0.4.0
+ *
+ * 目前仅支持 `reload-extension`：server 端 watcher 检测到扩展 dist 变化后
+ * 向扩展推送此消息，扩展侧调 `chrome.runtime.reload()` 自重载并读取新 dist，
+ * 避免每次 `pnpm -C packages/extension build` 后人工去 `chrome://extensions`
+ * 点刷新。与 MCP 的 O-3 `fs.watch` 自 exit 对称。
+ */
+export interface NmControl {
+    type: "control";
+    action: "reload-extension";
+    /** 可选：方便扩展侧日志打点/调试，不影响行为 */
+    reason?: string;
+}
+export type NmMessageFromServer = NmRequest | NmPing | NmControl;
+export type NmMessageFromExtension = NmResponse | NmEvent | NmResponseChunk | NmPong;
+export type NmMessage = NmMessageFromServer | NmMessageFromExtension;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AACjE,MAAM,MAAM,sBAAsB,GAAG,UAAU,GAAG,OAAO,GAAG,eAAe,GAAG,MAAM,CAAC;AACrF,MAAM,MAAM,SAAS,GAAG,mBAAmB,GAAG,sBAAsB,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@vortex-browser/shared",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT",
+  "description": "Shared types, action names, and error codes for Vortex browser automation.",
+  "keywords": [
+    "browser-automation",
+    "ai-agents",
+    "mcp",
+    "chrome-extension",
+    "llm",
+    "puppeteer-alternative",
+    "playwright-alternative"
+  ],
+  "homepage": "https://github.com/benbergg/vortex-browser",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/benbergg/vortex-browser.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}