@open-probe/shared 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 open-probe contributors
+
+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,26 @@
+# @open-probe/shared
+
+Shared TypeScript types and the **AFS v1** (Annotation Format Schema)
+protocol definitions used across all open-probe packages.
+
+This package has no runtime code worth importing on its own; it exists to
+keep `@open-probe/core`, `@open-probe/mcp-server`, `@open-probe/proxy`,
+and any future transports speaking the same wire format.
+
+```ts
+import type {
+  Annotation,
+  AnnotationIntent,
+  ElementInfo,
+  Framework,
+  ProbeConfig,
+  SourceLocation,
+} from '@open-probe/shared';
+```
+
+See the project [README](https://github.com/wzc520pyfm/open-probe#readme)
+for the full architecture.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+type Framework = 'react' | 'vue3' | 'vue2' | 'svelte' | 'solid' | 'preact' | 'unknown';
+interface SourceLocation {
+    filePath: string;
+    lineNumber: number;
+    columnNumber: number;
+    componentName: string;
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface SelectorResult {
+    primary: string;
+    alternatives: string[];
+    specificity: number;
+    grepHints: string[];
+}
+interface ElementInfo {
+    tagName: string;
+    componentName: string | null;
+    source: SourceLocation | null;
+    stack: SourceLocation[];
+    framework: Framework;
+}
+
+type AnnotationIntent = 'fix' | 'change' | 'question' | 'approve';
+type AnnotationSeverity = 'blocking' | 'important' | 'suggestion';
+type AnnotationStatus = 'pending' | 'acknowledged' | 'resolved' | 'dismissed';
+type AnnotationKind = 'feedback' | 'placement' | 'rearrange';
+interface ThreadMessage {
+    id: string;
+    role: 'human' | 'agent';
+    content: string;
+    timestamp: number;
+}
+interface PlacementData {
+    componentType: string;
+    width: number;
+    height: number;
+    scrollY: number;
+    text?: string;
+}
+interface RearrangeData {
+    selector: string;
+    label: string;
+    tagName: string;
+    originalRect: BoundingBox;
+    currentRect: BoundingBox;
+}
+interface Annotation {
+    id: string;
+    sessionId: string;
+    createdAt: string;
+    updatedAt?: string;
+    url: string;
+    status: AnnotationStatus;
+    resolvedAt?: string;
+    resolvedBy?: 'human' | 'agent';
+    comment: string;
+    intent: AnnotationIntent;
+    severity?: AnnotationSeverity;
+    thread?: ThreadMessage[];
+    element: string;
+    elementPath: string;
+    fullPath?: string;
+    cssClasses?: string;
+    computedStyles?: string;
+    accessibility?: string;
+    nearbyText?: string;
+    selectedText?: string;
+    boundingBox?: BoundingBox;
+    isFixed?: boolean;
+    isMultiSelect?: boolean;
+    kind?: AnnotationKind;
+    placement?: PlacementData;
+    rearrange?: RearrangeData;
+    framework: Framework;
+    source?: SourceLocation;
+    componentStack?: SourceLocation[];
+    selector?: SelectorResult;
+    outerHtml?: string;
+    screenshot?: string;
+}
+interface Session {
+    id: string;
+    url: string;
+    status: 'active' | 'approved' | 'closed';
+    createdAt: string;
+    updatedAt?: string;
+    projectId?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SessionWithAnnotations extends Session {
+    annotations: Annotation[];
+}
+type AFSEventType = 'session.created' | 'session.updated' | 'session.closed' | 'annotation.created' | 'annotation.updated' | 'annotation.deleted' | 'thread.message' | 'action.requested';
+interface AFSEvent<T = unknown> {
+    type: AFSEventType;
+    timestamp: string;
+    sessionId: string;
+    sequence: number;
+    payload: T;
+}
+interface PendingResponse {
+    count: number;
+    annotations: Annotation[];
+}
+type WsMessage = {
+    type: 'probe:hello';
+    refId: string;
+    clientId: string;
+    url: string;
+} | {
+    type: 'probe:annotation';
+    refId: string;
+    data: Annotation;
+} | {
+    type: 'probe:status';
+    refId: string;
+    annotationId: string;
+    status: AnnotationStatus;
+} | {
+    type: 'probe:console';
+    refId: string;
+    level: 'log' | 'warn' | 'error';
+    message: string;
+    stack?: string;
+} | {
+    type: 'probe:ack';
+    refId: string;
+    ok: boolean;
+    error?: string;
+};
+
+type OutputLevel = 'compact' | 'standard' | 'detailed' | 'forensic';
+type ToolbarPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type Theme = 'auto' | 'light' | 'dark';
+type TransportName = 'clipboard' | 'mcp' | 'server';
+interface SourceMapConfig {
+    enabled: boolean;
+    timeoutMs: number;
+    cacheSize: number;
+    allowOrigins: string[];
+}
+interface ResolverConfig {
+    enabled: Framework[] | 'auto';
+    sourceMap: SourceMapConfig;
+    truncateHtml: number;
+}
+interface ToolbarConfig {
+    position: ToolbarPosition;
+    activationKey: string;
+    theme: Theme;
+    enabled: boolean;
+    hideInProduction: boolean;
+}
+interface SelectorConfig {
+    strategies: string[];
+    blocklistClassPatterns: string[];
+    requireUniqueness: boolean;
+}
+interface McpConfig {
+    endpoint: string;
+    sessionId?: string;
+    apiKey?: string;
+}
+interface ServerTransportConfig {
+    endpoint: string;
+    protocol: 'http' | 'ws';
+    csrfToken?: string;
+    headers?: Record<string, string>;
+}
+interface PrivacyConfig {
+    redactInputs: boolean;
+    redactSelectors: string[];
+    captureScreenshot: boolean;
+}
+interface ProbeConfig {
+    transport: TransportName | TransportName[];
+    outputLevel: OutputLevel;
+    toolbar: ToolbarConfig;
+    resolver: ResolverConfig;
+    selector: SelectorConfig;
+    mcp: McpConfig;
+    server: ServerTransportConfig;
+    privacy: PrivacyConfig;
+    debug: boolean;
+}
+declare const DEFAULT_CONFIG: ProbeConfig;
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+declare function defineConfig(config: DeepPartial<ProbeConfig>): DeepPartial<ProbeConfig>;
+declare function mergeConfig(base: ProbeConfig, override: DeepPartial<ProbeConfig> | undefined): ProbeConfig;
+
+export { type AFSEvent, type AFSEventType, type Annotation, type AnnotationIntent, type AnnotationKind, type AnnotationSeverity, type AnnotationStatus, type BoundingBox, DEFAULT_CONFIG, type DeepPartial, type ElementInfo, type Framework, type McpConfig, type OutputLevel, type PendingResponse, type PlacementData, type PrivacyConfig, type ProbeConfig, type RearrangeData, type ResolverConfig, type SelectorConfig, type SelectorResult, type ServerTransportConfig, type Session, type SessionWithAnnotations, type SourceLocation, type SourceMapConfig, type Theme, type ThreadMessage, type ToolbarConfig, type ToolbarPosition, type TransportName, type WsMessage, defineConfig, mergeConfig };

package/dist/index.js

@@ -0,0 +1,90 @@
+// src/config.ts
+var DEFAULT_CONFIG = {
+  transport: "clipboard",
+  outputLevel: "standard",
+  toolbar: {
+    position: "bottom-right",
+    activationKey: "Mod+Shift+E",
+    theme: "auto",
+    enabled: true,
+    hideInProduction: true
+  },
+  resolver: {
+    enabled: "auto",
+    sourceMap: {
+      enabled: true,
+      timeoutMs: 3e3,
+      cacheSize: 64,
+      allowOrigins: []
+    },
+    truncateHtml: 1024
+  },
+  selector: {
+    strategies: [
+      "data-testid",
+      "aria-label",
+      "unique-id",
+      "stable-classes",
+      "role-and-text",
+      "structural"
+    ],
+    blocklistClassPatterns: [],
+    requireUniqueness: false
+  },
+  mcp: {
+    endpoint: "http://127.0.0.1:3100"
+  },
+  server: {
+    endpoint: "",
+    protocol: "http"
+  },
+  privacy: {
+    redactInputs: true,
+    redactSelectors: ['input[type="password"]', "[data-sensitive]"],
+    captureScreenshot: false
+  },
+  debug: false
+};
+function defineConfig(config) {
+  return config;
+}
+function mergeConfig(base, override) {
+  if (!override) return base;
+  const baseRec = base;
+  const overrideRec = override;
+  const merged = { ...baseRec };
+  for (const key of Object.keys(overrideRec)) {
+    const baseVal = baseRec[key];
+    const overrideVal = overrideRec[key];
+    if (overrideVal === void 0) continue;
+    if (baseVal !== null && typeof baseVal === "object" && !Array.isArray(baseVal) && typeof overrideVal === "object" && !Array.isArray(overrideVal)) {
+      merged[key] = mergeDeep(
+        baseVal,
+        overrideVal
+      );
+    } else {
+      merged[key] = overrideVal;
+    }
+  }
+  return merged;
+}
+function mergeDeep(a, b) {
+  const out = { ...a };
+  for (const key in b) {
+    const av = a[key];
+    const bv = b[key];
+    if (bv === void 0) continue;
+    if (av !== null && typeof av === "object" && !Array.isArray(av) && typeof bv === "object" && !Array.isArray(bv)) {
+      out[key] = mergeDeep(av, bv);
+    } else {
+      out[key] = bv;
+    }
+  }
+  return out;
+}
+export {
+  DEFAULT_CONFIG,
+  defineConfig,
+  mergeConfig
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import type { Framework } from './types.js';\n\nexport type OutputLevel = 'compact' | 'standard' | 'detailed' | 'forensic';\nexport type ToolbarPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';\nexport type Theme = 'auto' | 'light' | 'dark';\nexport type TransportName = 'clipboard' | 'mcp' | 'server';\n\nexport interface SourceMapConfig {\n  enabled: boolean;\n  timeoutMs: number;\n  cacheSize: number;\n  allowOrigins: string[];\n}\n\nexport interface ResolverConfig {\n  enabled: Framework[] | 'auto';\n  sourceMap: SourceMapConfig;\n  truncateHtml: number;\n}\n\nexport interface ToolbarConfig {\n  position: ToolbarPosition;\n  activationKey: string;\n  theme: Theme;\n  enabled: boolean;\n  hideInProduction: boolean;\n}\n\nexport interface SelectorConfig {\n  strategies: string[];\n  blocklistClassPatterns: string[];\n  requireUniqueness: boolean;\n}\n\nexport interface McpConfig {\n  endpoint: string;\n  sessionId?: string;\n  apiKey?: string;\n}\n\nexport interface ServerTransportConfig {\n  endpoint: string;\n  protocol: 'http' | 'ws';\n  csrfToken?: string;\n  headers?: Record<string, string>;\n}\n\nexport interface PrivacyConfig {\n  redactInputs: boolean;\n  redactSelectors: string[];\n  captureScreenshot: boolean;\n}\n\nexport interface ProbeConfig {\n  transport: TransportName | TransportName[];\n  outputLevel: OutputLevel;\n  toolbar: ToolbarConfig;\n  resolver: ResolverConfig;\n  selector: SelectorConfig;\n  mcp: McpConfig;\n  server: ServerTransportConfig;\n  privacy: PrivacyConfig;\n  debug: boolean;\n}\n\nexport const DEFAULT_CONFIG: ProbeConfig = {\n  transport: 'clipboard',\n  outputLevel: 'standard',\n  toolbar: {\n    position: 'bottom-right',\n    activationKey: 'Mod+Shift+E',\n    theme: 'auto',\n    enabled: true,\n    hideInProduction: true,\n  },\n  resolver: {\n    enabled: 'auto',\n    sourceMap: {\n      enabled: true,\n      timeoutMs: 3000,\n      cacheSize: 64,\n      allowOrigins: [],\n    },\n    truncateHtml: 1024,\n  },\n  selector: {\n    strategies: [\n      'data-testid',\n      'aria-label',\n      'unique-id',\n      'stable-classes',\n      'role-and-text',\n      'structural',\n    ],\n    blocklistClassPatterns: [],\n    requireUniqueness: false,\n  },\n  mcp: {\n    endpoint: 'http://127.0.0.1:3100',\n  },\n  server: {\n    endpoint: '',\n    protocol: 'http',\n  },\n  privacy: {\n    redactInputs: true,\n    redactSelectors: ['input[type=\"password\"]', '[data-sensitive]'],\n    captureScreenshot: false,\n  },\n  debug: false,\n};\n\nexport type DeepPartial<T> = {\n  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];\n};\n\nexport function defineConfig(config: DeepPartial<ProbeConfig>): DeepPartial<ProbeConfig> {\n  return config;\n}\n\nexport function mergeConfig(\n  base: ProbeConfig,\n  override: DeepPartial<ProbeConfig> | undefined\n): ProbeConfig {\n  if (!override) return base;\n  const baseRec = base as unknown as Record<string, unknown>;\n  const overrideRec = override as unknown as Record<string, unknown>;\n  const merged: Record<string, unknown> = { ...baseRec };\n  for (const key of Object.keys(overrideRec)) {\n    const baseVal = baseRec[key];\n    const overrideVal = overrideRec[key];\n    if (overrideVal === undefined) continue;\n    if (\n      baseVal !== null &&\n      typeof baseVal === 'object' &&\n      !Array.isArray(baseVal) &&\n      typeof overrideVal === 'object' &&\n      !Array.isArray(overrideVal)\n    ) {\n      merged[key] = mergeDeep(\n        baseVal as Record<string, unknown>,\n        overrideVal as Record<string, unknown>\n      );\n    } else {\n      merged[key] = overrideVal;\n    }\n  }\n  return merged as unknown as ProbeConfig;\n}\n\nfunction mergeDeep(\n  a: Record<string, unknown>,\n  b: Record<string, unknown>\n): Record<string, unknown> {\n  const out: Record<string, unknown> = { ...a };\n  for (const key in b) {\n    const av = a[key];\n    const bv = b[key];\n    if (bv === undefined) continue;\n    if (\n      av !== null &&\n      typeof av === 'object' &&\n      !Array.isArray(av) &&\n      typeof bv === 'object' &&\n      !Array.isArray(bv)\n    ) {\n      out[key] = mergeDeep(av as Record<string, unknown>, bv as Record<string, unknown>);\n    } else {\n      out[key] = bv;\n    }\n  }\n  return out;\n}\n"],"mappings":";AAiEO,IAAM,iBAA8B;AAAA,EACzC,WAAW;AAAA,EACX,aAAa;AAAA,EACb,SAAS;AAAA,IACP,UAAU;AAAA,IACV,eAAe;AAAA,IACf,OAAO;AAAA,IACP,SAAS;AAAA,IACT,kBAAkB;AAAA,EACpB;AAAA,EACA,UAAU;AAAA,IACR,SAAS;AAAA,IACT,WAAW;AAAA,MACT,SAAS;AAAA,MACT,WAAW;AAAA,MACX,WAAW;AAAA,MACX,cAAc,CAAC;AAAA,IACjB;AAAA,IACA,cAAc;AAAA,EAChB;AAAA,EACA,UAAU;AAAA,IACR,YAAY;AAAA,MACV;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA,wBAAwB,CAAC;AAAA,IACzB,mBAAmB;AAAA,EACrB;AAAA,EACA,KAAK;AAAA,IACH,UAAU;AAAA,EACZ;AAAA,EACA,QAAQ;AAAA,IACN,UAAU;AAAA,IACV,UAAU;AAAA,EACZ;AAAA,EACA,SAAS;AAAA,IACP,cAAc;AAAA,IACd,iBAAiB,CAAC,0BAA0B,kBAAkB;AAAA,IAC9D,mBAAmB;AAAA,EACrB;AAAA,EACA,OAAO;AACT;AAMO,SAAS,aAAa,QAA4D;AACvF,SAAO;AACT;AAEO,SAAS,YACd,MACA,UACa;AACb,MAAI,CAAC,SAAU,QAAO;AACtB,QAAM,UAAU;AAChB,QAAM,cAAc;AACpB,QAAM,SAAkC,EAAE,GAAG,QAAQ;AACrD,aAAW,OAAO,OAAO,KAAK,WAAW,GAAG;AAC1C,UAAM,UAAU,QAAQ,GAAG;AAC3B,UAAM,cAAc,YAAY,GAAG;AACnC,QAAI,gBAAgB,OAAW;AAC/B,QACE,YAAY,QACZ,OAAO,YAAY,YACnB,CAAC,MAAM,QAAQ,OAAO,KACtB,OAAO,gBAAgB,YACvB,CAAC,MAAM,QAAQ,WAAW,GAC1B;AACA,aAAO,GAAG,IAAI;AAAA,QACZ;AAAA,QACA;AAAA,MACF;AAAA,IACF,OAAO;AACL,aAAO,GAAG,IAAI;AAAA,IAChB;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,UACP,GACA,GACyB;AACzB,QAAM,MAA+B,EAAE,GAAG,EAAE;AAC5C,aAAW,OAAO,GAAG;AACnB,UAAM,KAAK,EAAE,GAAG;AAChB,UAAM,KAAK,EAAE,GAAG;AAChB,QAAI,OAAO,OAAW;AACtB,QACE,OAAO,QACP,OAAO,OAAO,YACd,CAAC,MAAM,QAAQ,EAAE,KACjB,OAAO,OAAO,YACd,CAAC,MAAM,QAAQ,EAAE,GACjB;AACA,UAAI,GAAG,IAAI,UAAU,IAA+B,EAA6B;AAAA,IACnF,OAAO;AACL,UAAI,GAAG,IAAI;AAAA,IACb;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@open-probe/shared",
+  "version": "0.1.1",
+  "description": "Shared types and AFS v1 protocol definitions for open-probe.",
+  "license": "MIT",
+  "author": "open-probe contributors",
+  "homepage": "https://github.com/wzc520pyfm/open-probe/tree/main/packages/shared#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wzc520pyfm/open-probe.git",
+    "directory": "packages/shared"
+  },
+  "bugs": {
+    "url": "https://github.com/wzc520pyfm/open-probe/issues"
+  },
+  "keywords": [
+    "open-probe",
+    "afs",
+    "annotation-format-schema",
+    "types"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}