@agent-native/pinpoint 0.1.1

package/dist/types/index.d.ts

@@ -0,0 +1,193 @@
+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;
+}
+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;
+    /** 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 { ComponentInfo, ContextMenuAction, CopyContext, DrawStroke, DrawToolType, ElementContext, ElementInfo, FrameworkAdapter, FrameworkInfo, OutputFormat, Pin, PinEvent, PinStatus, PinStorage, PinpointAPI, PinpointConfig, Plugin, PluginHookRegistry, PluginHooks, QueuedAnnotation, SourceLocation, TextNote, ToolbarMode };

package/dist/types/index.js

@@ -0,0 +1 @@
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

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

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@agent-native/pinpoint",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Visual feedback and annotation tool for agent-native web applications",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BuilderIO/agent-native",
+    "directory": "packages/pinpoint"
+  },
+  "bugs": {
+    "url": "https://github.com/BuilderIO/agent-native/issues"
+  },
+  "homepage": "https://github.com/BuilderIO/agent-native#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./primitives": {
+      "types": "./dist/primitives/index.d.ts",
+      "import": "./dist/primitives/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    }
+  },
+  "bin": {
+    "pinpoint": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/scripts",
+    ".agents"
+  ],
+  "dependencies": {
+    "@medv/finder": "^4.0.2",
+    "bippy": "^0.5.32",
+    "element-source": "^0.0.3",
+    "solid-js": "^1.9.10",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@agent-native/core": ">=0.7",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/express": "^5.0.3",
+    "@types/node": "^24.2.1",
+    "@types/react": "^19.2.14",
+    "babel-preset-solid": "^1.9.10",
+    "esbuild-plugin-solid": "^0.6.0",
+    "express": "^5.1.0",
+    "tsup": "^8.4.0",
+    "typescript": "^6.0.3",
+    "vite-plugin-solid": "^2.11.0",
+    "vitest": "^4.1.5",
+    "@agent-native/core": "0.7.15"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run"
+  }
+}

package/src/scripts/create-pin.ts

@@ -0,0 +1,41 @@
+// @agent-native/pinpoint — Create annotation script
+// MIT License
+
+import { parseArgs, fail } from "@agent-native/core/scripts";
+import { FileStore } from "../storage/file-store.js";
+import { randomUUID } from "crypto";
+import type { Pin } from "../types/index.js";
+
+export default async function (args: string[]) {
+  const { pageUrl, selector, comment, author } = parseArgs(args) as {
+    pageUrl?: string;
+    selector?: string;
+    comment?: string;
+    author?: string;
+  };
+
+  if (!pageUrl) fail("--pageUrl is required");
+  if (!selector) fail("--selector is required");
+  if (!comment) fail("--comment is required");
+
+  const now = new Date().toISOString();
+  const pin: Pin = {
+    id: randomUUID(),
+    pageUrl: pageUrl!,
+    createdAt: now,
+    updatedAt: now,
+    author,
+    comment: comment!,
+    element: {
+      tagName: "unknown",
+      classNames: [],
+      selector: selector!,
+      boundingRect: { x: 0, y: 0, width: 0, height: 0 },
+    },
+    status: { state: "open", changedAt: now, changedBy: "agent" },
+  };
+
+  const store = new FileStore();
+  await store.save(pin);
+  console.log(`Created annotation ${pin.id} on ${pageUrl} → ${selector}`);
+}

package/src/scripts/delete-pin.ts

@@ -0,0 +1,15 @@
+// @agent-native/pinpoint — Delete annotation script
+// MIT License
+
+import { parseArgs, fail } from "@agent-native/core/scripts";
+import { FileStore } from "../storage/file-store.js";
+
+export default async function (args: string[]) {
+  const { id } = parseArgs(args) as { id?: string };
+
+  if (!id) fail("--id is required");
+
+  const store = new FileStore();
+  await store.delete(id!);
+  console.log(`Deleted annotation ${id}`);
+}

package/src/scripts/get-pins.ts

@@ -0,0 +1,35 @@
+// @agent-native/pinpoint — List/filter annotations script
+// MIT License
+
+import { parseArgs } from "@agent-native/core/scripts";
+import { FileStore } from "../storage/file-store.js";
+import type { PinStatus } from "../types/index.js";
+
+export default async function (args: string[]) {
+  const { pageUrl, status } = parseArgs(args) as {
+    pageUrl?: string;
+    status?: PinStatus;
+  };
+
+  const store = new FileStore();
+  const pins = await store.list({ pageUrl, status });
+
+  if (pins.length === 0) {
+    console.log("No annotations found.");
+    return;
+  }
+
+  console.log(`Found ${pins.length} annotation(s):\n`);
+
+  for (let i = 0; i < pins.length; i++) {
+    const pin = pins[i];
+    console.log(`${i + 1}. [${pin.status.state}] ${pin.element.selector}`);
+    console.log(`   Comment: ${pin.comment}`);
+    if (pin.author) console.log(`   Author: ${pin.author}`);
+    if (pin.framework?.sourceFile)
+      console.log(`   Source: ${pin.framework.sourceFile}`);
+    console.log(`   Page: ${pin.pageUrl}`);
+    console.log(`   ID: ${pin.id}`);
+    console.log();
+  }
+}

package/src/scripts/list-sessions.ts

@@ -0,0 +1,33 @@
+// @agent-native/pinpoint — List annotation sessions by page URL
+// MIT License
+
+import { FileStore } from "../storage/file-store.js";
+
+export default async function (_args: string[]) {
+  const store = new FileStore();
+  const pins = await store.list();
+
+  // Group by page URL
+  const sessions = new Map<string, { count: number; latest: string }>();
+  for (const pin of pins) {
+    const existing = sessions.get(pin.pageUrl);
+    if (!existing || pin.updatedAt > existing.latest) {
+      sessions.set(pin.pageUrl, {
+        count: (existing?.count ?? 0) + 1,
+        latest: pin.updatedAt,
+      });
+    } else {
+      existing.count++;
+    }
+  }
+
+  if (sessions.size === 0) {
+    console.log("No annotation sessions found.");
+    return;
+  }
+
+  console.log(`${sessions.size} page(s) with annotations:\n`);
+  for (const [url, info] of sessions) {
+    console.log(`  ${url} — ${info.count} pin(s), last updated ${info.latest}`);
+  }
+}

package/src/scripts/resolve-pin.ts

@@ -0,0 +1,26 @@
+// @agent-native/pinpoint — Resolve annotation script
+// MIT License
+
+import { parseArgs, fail } from "@agent-native/core/scripts";
+import { FileStore } from "../storage/file-store.js";
+
+export default async function (args: string[]) {
+  const { id, message } = parseArgs(args) as {
+    id?: string;
+    message?: string;
+  };
+
+  if (!id) fail("--id is required");
+
+  const store = new FileStore();
+  await store.update(id!, {
+    status: {
+      state: "resolved",
+      changedAt: new Date().toISOString(),
+      changedBy: "agent",
+    },
+    ...(message ? { comment: message } : {}),
+  });
+
+  console.log(`Resolved annotation ${id}`);
+}

package/src/scripts/run.ts

@@ -0,0 +1,8 @@
+// @agent-native/pinpoint — Script dispatcher
+// MIT License
+//
+// Required entry point for agent scripts. Routes to specific script modules.
+
+import { runScript } from "@agent-native/core/scripts";
+
+runScript();

package/src/scripts/update-pin.ts

@@ -0,0 +1,31 @@
+// @agent-native/pinpoint — Update annotation script
+// MIT License
+
+import { parseArgs, fail } from "@agent-native/core/scripts";
+import { FileStore } from "../storage/file-store.js";
+
+export default async function (args: string[]) {
+  const { id, comment, status } = parseArgs(args) as {
+    id?: string;
+    comment?: string;
+    status?: string;
+  };
+
+  if (!id) fail("--id is required");
+  if (!comment && !status) fail("--comment or --status is required");
+
+  const store = new FileStore();
+  const patch: Record<string, any> = {};
+
+  if (comment) patch.comment = comment;
+  if (status) {
+    patch.status = {
+      state: status,
+      changedAt: new Date().toISOString(),
+      changedBy: "agent",
+    };
+  }
+
+  await store.update(id!, patch);
+  console.log(`Updated annotation ${id}`);
+}