@agent-native/pinpoint 0.1.60 → 0.1.63

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index-C0P3S_D7.d.ts

@@ -0,0 +1,43 @@
+import { PinStorage, Pin, PinStatus, FrameworkInfo, ElementContext, ElementInfo, FrameworkAdapter, ComponentInfo, SourceLocation } from './types/index.js';
+
+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>;
+}
+
+interface SelectorOptions {
+    timeoutMs?: number;
+    skipClassPatterns?: RegExp[];
+}
+declare function buildSelector(element: Element, options?: SelectorOptions): string;
+
+declare function extractElementInfo(element: Element): ElementInfo;
+declare function buildElementContext(element: Element, frameworkInfo?: FrameworkInfo): ElementContext;
+
+declare function registerAdapter(adapter: FrameworkAdapter): void;
+declare function detectFramework(): FrameworkAdapter;
+declare function getComponentInfo(element: Element): ComponentInfo | null;
+declare function getSourceLocation(element: Element): SourceLocation | null;
+
+interface FreezeOptions {
+    jsTimers?: boolean;
+}
+declare function freeze(_elements?: Element[], options?: FreezeOptions): void;
+declare function unfreeze(): void;
+declare function isFreezeActive(): 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>;
+
+export { MemoryStore as M, buildSelector as a, buildElementContext as b, getSourceLocation as c, detectFramework as d, extractElementInfo as e, freeze as f, getComponentInfo as g, isFreezeActive as i, openFile as o, registerAdapter as r, unfreeze as u };

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { PinStorage, Pin, PinStatus, FrameworkAdapter, OutputFormat, AgentOutput, QueuedAnnotation, PluginHooks, Plugin, PinpointAPI } from './types/index.js';
+export { ComponentInfo, ContextMenuAction, CopyContext, DrawStroke, DrawToolType, ElementContext, ElementInfo, FrameworkInfo, PinEvent, PinpointConfig, SourceLocation, TextNote, ToolbarMode } from './types/index.js';
+export { M as MemoryStore, b as buildElementContext, a as buildSelector, d as detectFramework, e as extractElementInfo, f as freeze, g as getComponentInfo, c as getSourceLocation, i as isFreezeActive, o as openFile, r as registerAdapter, u as unfreeze } from './index-C0P3S_D7.js';
+import { z } from 'zod';
+
+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 {
+    onHover?: (element: Element | null, rect: DOMRect | null) => void;
+    onStableHover?: (element: Element) => void;
+    onSelect?: (element: Element) => void;
+    ignoreSelector?: string;
+    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);
+    private isOwnUI;
+    private shouldIgnore;
+    private pierceElementFromPoint;
+    private processHover;
+    private clearStableTimeout;
+    activate(): void;
+    deactivate(): void;
+    setBlockInteractions(value: boolean): void;
+    pause(): void;
+    resume(): void;
+    isPaused(): boolean;
+    isActive(): boolean;
+    getHoveredElement(): Element | null;
+    dispose(): void;
+}
+
+interface DragSelectOptions {
+    coverageThreshold?: number;
+    onDragStart?: (rect: DOMRect) => void;
+    onDragMove?: (rect: DOMRect) => void;
+    onDragEnd?: (elements: Element[]) => void;
+    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 {
+    text: string;
+    container: Element;
+    startOffset: number;
+    endOffset: number;
+    context: string;
+    rect: DOMRect;
+}
+interface TextSelectOptions {
+    onSelect?: (selection: TextSelection | null) => void;
+    minLength?: number;
+}
+declare class TextSelect {
+    private active;
+    private options;
+    private handleSelectionChange;
+    private debounceTimer;
+    constructor(options?: TextSelectOptions);
+    private getTextSelection;
+    activate(): void;
+    deactivate(): void;
+    getCurrentSelection(): TextSelection | null;
+    dispose(): void;
+}
+
+declare const reactAdapter: FrameworkAdapter;
+
+declare const vueAdapter: FrameworkAdapter;
+
+declare const genericAdapter: FrameworkAdapter;
+
+declare function formatPins(pins: Pin[], format?: OutputFormat): string;
+
+declare function formatRichPinContext(pin: Pin): string;
+declare function formatPinsForAgent(pins: Pin[], format?: OutputFormat): AgentOutput;
+declare function formatQueueForAgent(queue: QueuedAnnotation[], format?: OutputFormat): AgentOutput;
+
+declare function registerPlugin(plugin: Plugin, api?: PinpointAPI): void;
+declare function unregisterPlugin(name: string): void;
+declare function getPlugins(): string[];
+declare function dispatchHook(name: keyof PluginHooks, ...args: unknown[]): void;
+
+declare const agentNativePlugin: Plugin;
+
+declare function escapeHtml(str: string): string;
+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;
+
+export { AgentOutput, DragSelect, ElementInfoSchema, ElementPicker, FrameworkAdapter, FrameworkInfoSchema, OutputFormat, Pin, PinSchema, PinStatus, PinStorage, PinpointAPI, Plugin, PluginHooks, QueuedAnnotation, RestClient, TextSelect, agentNativePlugin, dispatchHook, escapeHtml, formatPins, formatPinsForAgent, formatQueueForAgent, formatRichPinContext, genericAdapter, getPlugins, isAllowedOrigin, reactAdapter, registerPlugin, sanitizeString, unregisterPlugin, vueAdapter };

package/dist/primitives/index.d.ts

@@ -0,0 +1,2 @@
+export { M as MemoryStore, a as buildSelector, d as detectFramework, e as extractElementInfo, f as freeze, g as getComponentInfo, b as getElementContext, c as getSourceLocation, i as isFreezeActive, o as openFile, u as unfreeze } from '../index-C0P3S_D7.js';
+import '../types/index.js';

package/dist/server/index.d.ts

@@ -0,0 +1,129 @@
+import { Router, Application } from 'express';
+import { PinStorage, Pin, PinStatus } from '../types/index.js';
+
+interface PinRoutesOptions {
+    dataDir?: string;
+}
+declare function pagePinRoutes(options?: PinRoutesOptions): Router;
+
+declare function registerPinpointA2A(app: Application, options?: {
+    dataDir?: string;
+}): void;
+
+declare function createPinpointMCPTools(options?: {
+    dataDir?: string;
+}): {
+    tools: ({
+        name: string;
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {
+                pageUrl: {
+                    type: string;
+                    description: string;
+                };
+                status: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                id?: undefined;
+                message?: undefined;
+                selector?: undefined;
+                comment?: undefined;
+            };
+            required?: undefined;
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {
+                id: {
+                    type: string;
+                    description: string;
+                };
+                message: {
+                    type: string;
+                    description: string;
+                };
+                pageUrl?: undefined;
+                status?: undefined;
+                selector?: undefined;
+                comment?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {
+                pageUrl: {
+                    type: string;
+                    description: string;
+                };
+                selector: {
+                    type: string;
+                    description: string;
+                };
+                comment: {
+                    type: string;
+                    description: string;
+                };
+                status?: undefined;
+                id?: undefined;
+                message?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: "object";
+            properties: {
+                id: {
+                    type: string;
+                    description: string;
+                };
+                pageUrl?: undefined;
+                status?: undefined;
+                message?: undefined;
+                selector?: undefined;
+                comment?: undefined;
+            };
+            required: string[];
+        };
+    })[];
+    handleTool(name: string, args: Record<string, any>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+};
+
+declare class FileStore implements PinStorage {
+    private dir;
+    constructor(dataDir?: string);
+    private validateId;
+    private pinPath;
+    private ensureDir;
+    private readPin;
+    private atomicWrite;
+    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>;
+}
+
+export { FileStore, type PinRoutesOptions, createPinpointMCPTools, pagePinRoutes, registerPinpointA2A };

package/dist/types/index.d.ts

@@ -0,0 +1,182 @@
+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?: HTMLElement;
+    author?: string;
+    endpoint?: string;
+    colorScheme?: "auto" | "light" | "dark";
+    outputFormat?: OutputFormat;
+    autoSubmit?: boolean;
+    clearOnSend?: boolean;
+    sendToAgent?: (output: AgentOutput) => void | Promise<void>;
+    blockInteractions?: boolean;
+    freezeJSTimers?: boolean;
+    allowedOrigins?: string[];
+    webhookUrl?: string;
+    includeSourcePaths?: boolean;
+    plugins?: Plugin[];
+    storage?: PinStorage;
+    position?: {
+        x: number;
+        y: number;
+    };
+    markerColor?: string;
+    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, ComponentInfo, ContextMenuAction, CopyContext, DrawStroke, DrawToolType, ElementContext, ElementInfo, FrameworkAdapter, FrameworkInfo, OutputFormat, Pin, PinEvent, PinStatus, PinStorage, PinpointAPI, PinpointConfig, Plugin, PluginHookRegistry, PluginHooks, QueuedAnnotation, SourceLocation, TextNote, ToolbarMode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/pinpoint",
-  "version": "0.1.60",
+  "version": "0.1.63",
   "description": "Visual feedback and annotation tool for agent-native web applications",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -71,7 +71,7 @@
     "typescript-7": "npm:typescript@^7.0.2",
     "vite-plugin-solid": "^2.11.0",
     "vitest": "^4.1.5",
-    "@agent-native/core": "0.196.0"
+    "@agent-native/core": "0.198.1"
   },
   "peerDependencies": {
     "@agent-native/core": ">=0.8.0",