@jami-studio/pinpoint 0.1.12

package/dist/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { existsSync, mkdirSync, cpSync, readdirSync } from "fs";
+import { resolve, dirname, join } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var command = process.argv[2];
+if (command === "init") {
+  init();
+} else {
+  console.log("Usage: npx @agent-native/pinpoint@latest init");
+  console.log("");
+  console.log("Commands:");
+  console.log("  init    Copy agent scripts and skill to your project");
+  process.exit(0);
+}
+function init() {
+  const projectRoot = process.cwd();
+  const scriptsSource = resolve(__dirname, "../src/scripts");
+  const scriptsDest = resolve(projectRoot, "scripts");
+  if (!existsSync(scriptsDest)) {
+    mkdirSync(scriptsDest, { recursive: true });
+  }
+  const scriptFiles = readdirSync(scriptsSource).filter(
+    (f) => f.endsWith(".ts")
+  );
+  let copiedScripts = 0;
+  for (const file of scriptFiles) {
+    const dest = join(scriptsDest, file);
+    if (existsSync(dest)) {
+      console.log(`  skip  scripts/${file} (already exists)`);
+    } else {
+      cpSync(join(scriptsSource, file), dest);
+      console.log(`  added scripts/${file}`);
+      copiedScripts++;
+    }
+  }
+  const skillSource = resolve(__dirname, "../.agents/skills/pinpoint");
+  const skillDest = resolve(projectRoot, ".agents/skills/pinpoint");
+  if (existsSync(skillSource)) {
+    if (!existsSync(skillDest)) {
+      mkdirSync(skillDest, { recursive: true });
+    }
+    const skillFile = join(skillSource, "SKILL.md");
+    const skillDestFile = join(skillDest, "SKILL.md");
+    if (existsSync(skillFile)) {
+      if (existsSync(skillDestFile)) {
+        console.log(
+          "  skip  .agents/skills/pinpoint/SKILL.md (already exists)"
+        );
+      } else {
+        cpSync(skillFile, skillDestFile);
+        console.log("  added .agents/skills/pinpoint/SKILL.md");
+      }
+    }
+  }
+  console.log("");
+  console.log(
+    copiedScripts > 0 ? "Pinpoint initialized. Agent scripts are in scripts/." : "Pinpoint already initialized. No new files copied."
+  );
+  console.log("");
+  console.log("Next steps:");
+  console.log(
+    "  1. Add <Pinpoint /> to your client:  import { Pinpoint } from '@agent-native/pinpoint/react'"
+  );
+  console.log(
+    '  2. Add middleware to your server:     app.use("/api/pins", pagePinRoutes())'
+  );
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\r\n// @agent-native/pinpoint — CLI for project setup\r\n// MIT License\r\n//\r\n// Usage: npx @agent-native/pinpoint@latest init\r\n\r\nimport { existsSync, mkdirSync, cpSync, readdirSync } from \"node:fs\";\r\nimport { resolve, dirname, join } from \"node:path\";\r\nimport { fileURLToPath } from \"node:url\";\r\n\r\nconst __dirname = dirname(fileURLToPath(import.meta.url));\r\nconst command = process.argv[2];\r\n\r\nif (command === \"init\") {\r\n  init();\r\n} else {\r\n  console.log(\"Usage: npx @agent-native/pinpoint@latest init\");\r\n  console.log(\"\");\r\n  console.log(\"Commands:\");\r\n  console.log(\"  init    Copy agent scripts and skill to your project\");\r\n  process.exit(0);\r\n}\r\n\r\nfunction init() {\r\n  const projectRoot = process.cwd();\r\n\r\n  // 1. Copy agent scripts to scripts/\r\n  const scriptsSource = resolve(__dirname, \"../src/scripts\");\r\n  const scriptsDest = resolve(projectRoot, \"scripts\");\r\n\r\n  if (!existsSync(scriptsDest)) {\r\n    mkdirSync(scriptsDest, { recursive: true });\r\n  }\r\n\r\n  const scriptFiles = readdirSync(scriptsSource).filter((f) =>\r\n    f.endsWith(\".ts\"),\r\n  );\r\n  let copiedScripts = 0;\r\n\r\n  for (const file of scriptFiles) {\r\n    const dest = join(scriptsDest, file);\r\n    if (existsSync(dest)) {\r\n      console.log(`  skip  scripts/${file} (already exists)`);\r\n    } else {\r\n      cpSync(join(scriptsSource, file), dest);\r\n      console.log(`  added scripts/${file}`);\r\n      copiedScripts++;\r\n    }\r\n  }\r\n\r\n  // 2. Copy agent skill if .agents/ directory pattern exists\r\n  const skillSource = resolve(__dirname, \"../.agents/skills/pinpoint\");\r\n  const skillDest = resolve(projectRoot, \".agents/skills/pinpoint\");\r\n\r\n  if (existsSync(skillSource)) {\r\n    if (!existsSync(skillDest)) {\r\n      mkdirSync(skillDest, { recursive: true });\r\n    }\r\n    const skillFile = join(skillSource, \"SKILL.md\");\r\n    const skillDestFile = join(skillDest, \"SKILL.md\");\r\n    if (existsSync(skillFile)) {\r\n      if (existsSync(skillDestFile)) {\r\n        console.log(\r\n          \"  skip  .agents/skills/pinpoint/SKILL.md (already exists)\",\r\n        );\r\n      } else {\r\n        cpSync(skillFile, skillDestFile);\r\n        console.log(\"  added .agents/skills/pinpoint/SKILL.md\");\r\n      }\r\n    }\r\n  }\r\n\r\n  console.log(\"\");\r\n  console.log(\r\n    copiedScripts > 0\r\n      ? \"Pinpoint initialized. Agent scripts are in scripts/.\"\r\n      : \"Pinpoint already initialized. No new files copied.\",\r\n  );\r\n  console.log(\"\");\r\n  console.log(\"Next steps:\");\r\n  console.log(\r\n    \"  1. Add <Pinpoint /> to your client:  import { Pinpoint } from '@agent-native/pinpoint/react'\",\r\n  );\r\n  console.log(\r\n    '  2. Add middleware to your server:     app.use(\"/api/pins\", pagePinRoutes())',\r\n  );\r\n}\r\n"],"mappings":";;;AAMA,SAAS,YAAY,WAAW,QAAQ,mBAAmB;AAC3D,SAAS,SAAS,SAAS,YAAY;AACvC,SAAS,qBAAqB;AAE9B,IAAM,YAAY,QAAQ,cAAc,YAAY,GAAG,CAAC;AACxD,IAAM,UAAU,QAAQ,KAAK,CAAC;AAE9B,IAAI,YAAY,QAAQ;AACtB,OAAK;AACP,OAAO;AACL,UAAQ,IAAI,+CAA+C;AAC3D,UAAQ,IAAI,EAAE;AACd,UAAQ,IAAI,WAAW;AACvB,UAAQ,IAAI,wDAAwD;AACpE,UAAQ,KAAK,CAAC;AAChB;AAEA,SAAS,OAAO;AACd,QAAM,cAAc,QAAQ,IAAI;AAGhC,QAAM,gBAAgB,QAAQ,WAAW,gBAAgB;AACzD,QAAM,cAAc,QAAQ,aAAa,SAAS;AAElD,MAAI,CAAC,WAAW,WAAW,GAAG;AAC5B,cAAU,aAAa,EAAE,WAAW,KAAK,CAAC;AAAA,EAC5C;AAEA,QAAM,cAAc,YAAY,aAAa,EAAE;AAAA,IAAO,CAAC,MACrD,EAAE,SAAS,KAAK;AAAA,EAClB;AACA,MAAI,gBAAgB;AAEpB,aAAW,QAAQ,aAAa;AAC9B,UAAM,OAAO,KAAK,aAAa,IAAI;AACnC,QAAI,WAAW,IAAI,GAAG;AACpB,cAAQ,IAAI,mBAAmB,IAAI,mBAAmB;AAAA,IACxD,OAAO;AACL,aAAO,KAAK,eAAe,IAAI,GAAG,IAAI;AACtC,cAAQ,IAAI,mBAAmB,IAAI,EAAE;AACrC;AAAA,IACF;AAAA,EACF;AAGA,QAAM,cAAc,QAAQ,WAAW,4BAA4B;AACnE,QAAM,YAAY,QAAQ,aAAa,yBAAyB;AAEhE,MAAI,WAAW,WAAW,GAAG;AAC3B,QAAI,CAAC,WAAW,SAAS,GAAG;AAC1B,gBAAU,WAAW,EAAE,WAAW,KAAK,CAAC;AAAA,IAC1C;AACA,UAAM,YAAY,KAAK,aAAa,UAAU;AAC9C,UAAM,gBAAgB,KAAK,WAAW,UAAU;AAChD,QAAI,WAAW,SAAS,GAAG;AACzB,UAAI,WAAW,aAAa,GAAG;AAC7B,gBAAQ;AAAA,UACN;AAAA,QACF;AAAA,MACF,OAAO;AACL,eAAO,WAAW,aAAa;AAC/B,gBAAQ,IAAI,0CAA0C;AAAA,MACxD;AAAA,IACF;AAAA,EACF;AAEA,UAAQ,IAAI,EAAE;AACd,UAAQ;AAAA,IACN,gBAAgB,IACZ,yDACA;AAAA,EACN;AACA,UAAQ,IAAI,EAAE;AACd,UAAQ,IAAI,aAAa;AACzB,UAAQ;AAAA,IACN;AAAA,EACF;AACA,UAAQ;AAAA,IACN;AAAA,EACF;AACF;","names":[]}

package/dist/formatter-CR4COA5Z.js

@@ -0,0 +1,8 @@
+"use client";
+import {
+  formatPins
+} from "./chunk-XBX2J7WU.js";
+export {
+  formatPins
+};
+//# sourceMappingURL=formatter-CR4COA5Z.js.map

package/dist/formatter-CR4COA5Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index-NvFcZ4SO.d.ts

@@ -0,0 +1,200 @@
+type PinStatus = "open" | "acknowledged" | "resolved" | "dismissed";
+type DrawToolType = "freehand" | "arrow" | "circle" | "rect" | "text";
+interface DrawStroke {
+    points: {
+        x: number;
+        y: number;
+    }[];
+    color: string;
+    lineWidth: number;
+    type: "freehand" | "arrow" | "circle" | "rect";
+}
+interface TextNote {
+    x: number;
+    y: number;
+    text: string;
+    color: string;
+}
+interface QueuedAnnotation {
+    id: string;
+    pin?: Pin;
+    drawings?: DrawStroke[];
+    textNotes?: TextNote[];
+    timestamp: string;
+}
+interface AgentOutput {
+    message: string;
+    context: string;
+    submit?: boolean;
+}
+type ToolbarMode = "select" | "draw" | "queue";
+interface Pin {
+    id: string;
+    pageUrl: string;
+    createdAt: string;
+    updatedAt: string;
+    author?: string;
+    comment: string;
+    element: ElementInfo;
+    framework?: FrameworkInfo;
+    status: {
+        state: PinStatus;
+        changedAt: string;
+        changedBy?: string;
+    };
+}
+interface ElementInfo {
+    tagName: string;
+    id?: string;
+    classNames: string[];
+    selector: string;
+    textContent?: string;
+    boundingRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    computedStyles?: Record<string, string>;
+    ariaAttributes?: Record<string, string>;
+    dataAttributes?: Record<string, string>;
+    domPath?: string;
+}
+interface FrameworkInfo {
+    framework: string;
+    componentPath: string;
+    sourceFile?: string;
+    frameworkVersion?: string;
+}
+interface ElementContext {
+    element: ElementInfo;
+    framework?: FrameworkInfo;
+    htmlSnippet: string;
+    cssSelector: string;
+    computedStyles: Record<string, string>;
+}
+interface ComponentInfo {
+    name: string;
+    displayName?: string;
+    filePath?: string;
+    lineNumber?: number;
+    props?: Record<string, unknown>;
+}
+interface SourceLocation {
+    file: string;
+    line?: number;
+    column?: number;
+}
+interface Plugin {
+    name: string;
+    setup?(api: PinpointAPI, hooks: PluginHookRegistry): void;
+    hooks?: PluginHooks;
+    actions?: ContextMenuAction[];
+}
+interface PluginHooks {
+    onElementSelect?(element: Element, info: ElementContext): void;
+    onElementHover?(element: Element): void;
+    onBeforeCopy?(context: CopyContext): CopyContext | false;
+    transformOutput?(output: string): string;
+    onPinCreate?(pin: Pin): void;
+    onPinResolve?(pin: Pin): void;
+}
+interface PluginHookRegistry {
+    register(hookName: keyof PluginHooks, handler: Function): void;
+    unregister(hookName: keyof PluginHooks, handler: Function): void;
+}
+interface CopyContext {
+    pins: Pin[];
+    format: OutputFormat;
+    output: string;
+}
+type OutputFormat = "compact" | "standard" | "detailed";
+interface ContextMenuAction {
+    label: string;
+    icon?: string;
+    handler(element: Element, context: ElementContext): void;
+}
+interface PinpointAPI {
+    activate(): void;
+    deactivate(): void;
+    toggle(): void;
+    isActive(): boolean;
+    copyElement(element: Element): Promise<boolean>;
+    getElementContext(element: Element): Promise<ElementContext>;
+    freeze(elements?: Element[]): void;
+    unfreeze(): void;
+    openFile(filePath: string, lineNumber?: number): Promise<void>;
+    registerPlugin(plugin: Plugin): void;
+    unregisterPlugin(name: string): void;
+    getPins(): Pin[];
+    createPin(element: Element, comment: string): Pin;
+    resolvePin(id: string, message?: string): void;
+    dispose(): void;
+}
+interface PinStorage {
+    load(pageUrl: string): Promise<Pin[]>;
+    save(pin: Pin): Promise<void>;
+    update(id: string, patch: Partial<Pin>): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        pageUrl?: string;
+        status?: PinStatus;
+    }): Promise<Pin[]>;
+    clear(pageUrl?: string): Promise<void>;
+}
+interface PinpointConfig {
+    /** Target element to mount pinpoint into */
+    target?: HTMLElement;
+    /** Author name for annotations */
+    author?: string;
+    /** REST API endpoint for pin storage */
+    endpoint?: string;
+    /** Color scheme */
+    colorScheme?: "auto" | "light" | "dark";
+    /** Output detail level */
+    outputFormat?: OutputFormat;
+    /** Auto-submit to agent chat */
+    autoSubmit?: boolean;
+    /** Clear pins after sending */
+    clearOnSend?: boolean;
+    /** Custom bridge for sending annotations to an agent chat */
+    sendToAgent?: (output: AgentOutput) => void | Promise<void>;
+    /** Block page interactions during annotation */
+    blockInteractions?: boolean;
+    /** Freeze JS timers (opt-in, disabled by default) */
+    freezeJSTimers?: boolean;
+    /** Allowed origins for postMessage */
+    allowedOrigins?: string[];
+    /** Webhook URL for pin events */
+    webhookUrl?: string;
+    /** Include source file paths in output */
+    includeSourcePaths?: boolean;
+    /** Plugins */
+    plugins?: Plugin[];
+    /** Custom storage adapter */
+    storage?: PinStorage;
+    /** Initial position of the toolbar */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Marker color */
+    markerColor?: string;
+    /** Compact popup — hide technical details behind a toggle (default: true) */
+    compactPopup?: boolean;
+}
+interface FrameworkAdapter {
+    name: string;
+    detect(): boolean;
+    getComponentInfo(element: Element): ComponentInfo | null;
+    getSourceLocation(element: Element): SourceLocation | null;
+    freeze?(): void;
+    unfreeze?(): void;
+}
+interface PinEvent {
+    type: "pin:created" | "pin:updated" | "pin:deleted" | "pin:resolved";
+    pin: Pin;
+    timestamp: string;
+}
+
+export type { AgentOutput as A, ComponentInfo as C, DrawStroke as D, ElementContext as E, FrameworkInfo as F, OutputFormat as O, PinStorage as P, QueuedAnnotation as Q, SourceLocation as S, TextNote as T, Pin as a, PinStatus as b, ElementInfo as c, FrameworkAdapter as d, PluginHooks as e, Plugin as f, PinpointAPI as g, PinpointConfig as h, ContextMenuAction as i, CopyContext as j, DrawToolType as k, PinEvent as l, ToolbarMode as m };

package/dist/index.browser.d.ts

@@ -0,0 +1,377 @@
+import { P as PinStorage, a as Pin, b as PinStatus, F as FrameworkInfo, E as ElementContext, c as ElementInfo, d as FrameworkAdapter, C as ComponentInfo, S as SourceLocation, O as OutputFormat, A as AgentOutput, Q as QueuedAnnotation, e as PluginHooks, f as Plugin, g as PinpointAPI, h as PinpointConfig } from './index-NvFcZ4SO.js';
+export { i as ContextMenuAction, j as CopyContext, D as DrawStroke, k as DrawToolType, l as PinEvent, T as TextNote, m as ToolbarMode } from './index-NvFcZ4SO.js';
+import { z } from 'zod';
+
+declare class MemoryStore implements PinStorage {
+    private pins;
+    load(pageUrl: string): Promise<Pin[]>;
+    save(pin: Pin): Promise<void>;
+    update(id: string, patch: Partial<Pin>): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        pageUrl?: string;
+        status?: PinStatus;
+    }): Promise<Pin[]>;
+    clear(pageUrl?: string): Promise<void>;
+}
+
+declare class RestClient implements PinStorage {
+    private endpoint;
+    constructor(endpoint: string);
+    load(pageUrl: string): Promise<Pin[]>;
+    save(pin: Pin): Promise<void>;
+    update(id: string, patch: Partial<Pin>): Promise<void>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        pageUrl?: string;
+        status?: PinStatus;
+    }): Promise<Pin[]>;
+    clear(pageUrl?: string): Promise<void>;
+}
+
+declare const ElementInfoSchema: z.ZodObject<{
+    tagName: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    classNames: z.ZodArray<z.ZodString>;
+    selector: z.ZodString;
+    textContent: z.ZodOptional<z.ZodString>;
+    boundingRect: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    computedStyles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    ariaAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    dataAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    domPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const FrameworkInfoSchema: z.ZodObject<{
+    framework: z.ZodString;
+    componentPath: z.ZodString;
+    sourceFile: z.ZodOptional<z.ZodString>;
+    frameworkVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const PinSchema: z.ZodObject<{
+    id: z.ZodString;
+    pageUrl: z.ZodString;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    comment: z.ZodString;
+    element: z.ZodObject<{
+        tagName: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        classNames: z.ZodArray<z.ZodString>;
+        selector: z.ZodString;
+        textContent: z.ZodOptional<z.ZodString>;
+        boundingRect: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        computedStyles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        ariaAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        dataAttributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        domPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    framework: z.ZodOptional<z.ZodObject<{
+        framework: z.ZodString;
+        componentPath: z.ZodString;
+        sourceFile: z.ZodOptional<z.ZodString>;
+        frameworkVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodObject<{
+        state: z.ZodEnum<{
+            open: "open";
+            acknowledged: "acknowledged";
+            resolved: "resolved";
+            dismissed: "dismissed";
+        }>;
+        changedAt: z.ZodString;
+        changedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+
+interface ElementPickerOptions {
+    /** Called on hover with the element under the cursor */
+    onHover?: (element: Element | null, rect: DOMRect | null) => void;
+    /** Called after stable hover (100ms) with full element context */
+    onStableHover?: (element: Element) => void;
+    /** Called when an element is clicked/selected */
+    onSelect?: (element: Element) => void;
+    /** Elements to ignore (e.g., pinpoint's own UI) */
+    ignoreSelector?: string;
+    /** Whether to block page interactions during selection */
+    blockInteractions?: boolean;
+}
+declare class ElementPicker {
+    private active;
+    private paused;
+    private hoveredElement;
+    private rafId;
+    private stableTimeout;
+    private lastTarget;
+    private options;
+    private handleMouseMove;
+    private handleClick;
+    private handleKeyDown;
+    constructor(options?: ElementPickerOptions);
+    /**
+     * Check if an event originates from Pinpoint's own UI.
+     * Uses composedPath() to cross Shadow DOM boundaries.
+     */
+    private isOwnUI;
+    private shouldIgnore;
+    private pierceElementFromPoint;
+    private processHover;
+    private clearStableTimeout;
+    activate(): void;
+    deactivate(): void;
+    /** Update blockInteractions at runtime (called from settings toggle) */
+    setBlockInteractions(value: boolean): void;
+    /** Pause picking without removing listeners (e.g., while popup is open) */
+    pause(): void;
+    /** Resume picking after pause */
+    resume(): void;
+    isPaused(): boolean;
+    isActive(): boolean;
+    /** Get the currently hovered element */
+    getHoveredElement(): Element | null;
+    dispose(): void;
+}
+
+interface SelectorOptions {
+    /** Timeout for selector generation (ms) */
+    timeoutMs?: number;
+    /** Additional class names to skip */
+    skipClassPatterns?: RegExp[];
+}
+/**
+ * Generate a unique, human-readable CSS selector for an element.
+ * Uses @medv/finder (MIT) with configuration to skip CSS-in-JS hashes.
+ */
+declare function buildSelector(element: Element, options?: SelectorOptions): string;
+
+/**
+ * Extract comprehensive metadata from a DOM element.
+ */
+declare function extractElementInfo(element: Element): ElementInfo;
+/**
+ * Build a full ElementContext including HTML snippet and framework info.
+ */
+declare function buildElementContext(element: Element, frameworkInfo?: FrameworkInfo): ElementContext;
+
+interface DragSelectOptions {
+    /** Minimum coverage threshold (0-1) for an element to be considered selected */
+    coverageThreshold?: number;
+    /** Called when drag starts */
+    onDragStart?: (rect: DOMRect) => void;
+    /** Called during drag with the current selection rectangle */
+    onDragMove?: (rect: DOMRect) => void;
+    /** Called when drag ends with selected elements */
+    onDragEnd?: (elements: Element[]) => void;
+    /** Elements to ignore */
+    ignoreSelector?: string;
+}
+declare class DragSelect {
+    private active;
+    private dragging;
+    private startX;
+    private startY;
+    private options;
+    private handleMouseDown;
+    private handleMouseMove;
+    private handleMouseUp;
+    constructor(options?: DragSelectOptions);
+    private buildRect;
+    private getElementsInRect;
+    activate(): void;
+    deactivate(): void;
+    isDragging(): boolean;
+    dispose(): void;
+}
+
+interface TextSelection {
+    /** The selected text */
+    text: string;
+    /** The container element */
+    container: Element;
+    /** Start offset within the container */
+    startOffset: number;
+    /** End offset within the container */
+    endOffset: number;
+    /** Surrounding context (text before + selected + text after) */
+    context: string;
+    /** Bounding rect of the selection */
+    rect: DOMRect;
+}
+interface TextSelectOptions {
+    /** Called when text selection changes */
+    onSelect?: (selection: TextSelection | null) => void;
+    /** Minimum characters to trigger selection callback */
+    minLength?: number;
+}
+declare class TextSelect {
+    private active;
+    private options;
+    private handleSelectionChange;
+    private debounceTimer;
+    constructor(options?: TextSelectOptions);
+    private getTextSelection;
+    activate(): void;
+    deactivate(): void;
+    /** Get the current text selection, if any */
+    getCurrentSelection(): TextSelection | null;
+    dispose(): void;
+}
+
+/**
+ * Register a framework adapter. Adapters are tried in registration order.
+ */
+declare function registerAdapter(adapter: FrameworkAdapter): void;
+/**
+ * Auto-detect the current framework by trying each adapter's detect() method.
+ * Returns the first matching adapter, or the generic fallback.
+ */
+declare function detectFramework(): FrameworkAdapter;
+/**
+ * Get component info for an element using the detected framework adapter.
+ */
+declare function getComponentInfo(element: Element): ComponentInfo | null;
+/**
+ * Get source location for an element using the detected framework adapter.
+ */
+declare function getSourceLocation(element: Element): SourceLocation | null;
+
+declare const reactAdapter: FrameworkAdapter;
+
+declare const vueAdapter: FrameworkAdapter;
+
+declare const genericAdapter: FrameworkAdapter;
+
+/**
+ * Format pins into a human/agent-readable markdown string.
+ */
+declare function formatPins(pins: Pin[], format?: OutputFormat): string;
+
+/**
+ * Format a single pin into rich context for the agent.
+ *
+ * ```
+ * [Annotation on <button class="primary"> in <Header> component]
+ * Comment: "This button should be blue instead of gray"
+ * Element: button.primary at (120, 45)
+ * Source: src/components/Header.tsx:42
+ * ```
+ */
+declare function formatRichPinContext(pin: Pin): string;
+/**
+ * Format pins for agent chat.
+ * The full formatted output goes into message (visible in chat UI) so the user
+ * can see exactly what context the agent is working with.
+ */
+declare function formatPinsForAgent(pins: Pin[], format?: OutputFormat): AgentOutput;
+/**
+ * Format queued annotations for batch sending.
+ */
+declare function formatQueueForAgent(queue: QueuedAnnotation[], format?: OutputFormat): AgentOutput;
+
+/**
+ * Register a plugin.
+ */
+declare function registerPlugin(plugin: Plugin, api?: PinpointAPI): void;
+/**
+ * Unregister a plugin by name.
+ */
+declare function unregisterPlugin(name: string): void;
+/**
+ * Get all registered plugin names.
+ */
+declare function getPlugins(): string[];
+/**
+ * Dispatch a hook to all registered handlers.
+ */
+declare function dispatchHook(name: keyof PluginHooks, ...args: unknown[]): void;
+
+declare const agentNativePlugin: Plugin;
+
+interface FreezeOptions {
+    /** Freeze JS timers (opt-in, disabled by default) */
+    jsTimers?: boolean;
+}
+/**
+ * Freeze all animations, transitions, React updates, and media.
+ * Call unfreeze() to restore.
+ */
+declare function freeze(_elements?: Element[], options?: FreezeOptions): void;
+/**
+ * Unfreeze everything and restore normal behavior.
+ */
+declare function unfreeze(): void;
+/**
+ * Check if freeze is currently active.
+ */
+declare function isFreezeActive(): boolean;
+
+/**
+ * Escape HTML entities in a string.
+ * Use on all DOM-derived strings before rendering or including in output.
+ */
+declare function escapeHtml(str: string): string;
+/**
+ * Sanitize a string by removing control characters and limiting length.
+ */
+declare function sanitizeString(str: string, maxLength?: number): string;
+
+/**
+ * Validate that a message origin is allowed.
+ * Used for postMessage security when communicating with frames.
+ */
+declare function isAllowedOrigin(origin: string, allowedOrigins?: string[]): boolean;
+
+/**
+ * Open a file in the user's editor. Tries vscode:// protocol first,
+ * falls back to a fetch to /api/open-file.
+ */
+declare function openFile(filePath: string, lineNumber?: number): Promise<void>;
+
+interface MountResult {
+    dispose: () => void;
+    shadowRoot: ShadowRoot;
+    container: HTMLDivElement;
+}
+/**
+ * Mount the Pinpoint overlay into the DOM.
+ * Uses Shadow DOM for CSS isolation.
+ * Singleton guard prevents multiple instances (HMR-safe).
+ */
+declare function mountPinpoint(config?: PinpointConfig, target?: HTMLElement): MountResult;
+/**
+ * Unmount Pinpoint from the DOM.
+ */
+declare function unmountPinpoint(): void;
+
+declare class PinMarkerManager {
+    private markerColor;
+    private markers;
+    private updateTimer;
+    private onClick;
+    private onToggleSelect;
+    private selectedPinIds;
+    private showCheckboxes;
+    constructor(markerColor?: string);
+    setOnClick(handler: (pin: Pin) => void): void;
+    setOnToggleSelect(handler: (pin: Pin) => void): void;
+    setSelectedPins(ids: Set<string>): void;
+    setShowCheckboxes(show: boolean): void;
+    update(pins: Pin[]): void;
+    private updateCheckboxVisual;
+    private updateMarker;
+    startTracking(pins: Pin[]): void;
+    stopTracking(): void;
+    dispose(): void;
+}
+
+export { AgentOutput, ComponentInfo, DragSelect, ElementContext, ElementInfo, ElementInfoSchema, ElementPicker, FrameworkAdapter, FrameworkInfo, FrameworkInfoSchema, MemoryStore, OutputFormat, Pin, PinMarkerManager, PinSchema, PinStatus, PinStorage, PinpointAPI, PinpointConfig, Plugin, PluginHooks, QueuedAnnotation, RestClient, SourceLocation, TextSelect, agentNativePlugin, buildElementContext, buildSelector, detectFramework, dispatchHook, escapeHtml, extractElementInfo, formatPins, formatPinsForAgent, formatQueueForAgent, formatRichPinContext, freeze, genericAdapter, getComponentInfo, getPlugins, getSourceLocation, isAllowedOrigin, isFreezeActive, mountPinpoint, openFile, reactAdapter, registerAdapter, registerPlugin, sanitizeString, unfreeze, unmountPinpoint, unregisterPlugin, vueAdapter };