@agent-native/pinpoint 0.1.1

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 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\n// @agent-native/pinpoint — CLI for project setup\n// MIT License\n//\n// Usage: npx @agent-native/pinpoint init\n\nimport { existsSync, mkdirSync, cpSync, readdirSync } from \"node:fs\";\nimport { resolve, dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nconst __dirname = dirname(fileURLToPath(import.meta.url));\nconst command = process.argv[2];\n\nif (command === \"init\") {\n  init();\n} else {\n  console.log(\"Usage: npx @agent-native/pinpoint init\");\n  console.log(\"\");\n  console.log(\"Commands:\");\n  console.log(\"  init    Copy agent scripts and skill to your project\");\n  process.exit(0);\n}\n\nfunction init() {\n  const projectRoot = process.cwd();\n\n  // 1. Copy agent scripts to scripts/\n  const scriptsSource = resolve(__dirname, \"../src/scripts\");\n  const scriptsDest = resolve(projectRoot, \"scripts\");\n\n  if (!existsSync(scriptsDest)) {\n    mkdirSync(scriptsDest, { recursive: true });\n  }\n\n  const scriptFiles = readdirSync(scriptsSource).filter((f) =>\n    f.endsWith(\".ts\"),\n  );\n  let copiedScripts = 0;\n\n  for (const file of scriptFiles) {\n    const dest = join(scriptsDest, file);\n    if (existsSync(dest)) {\n      console.log(`  skip  scripts/${file} (already exists)`);\n    } else {\n      cpSync(join(scriptsSource, file), dest);\n      console.log(`  added scripts/${file}`);\n      copiedScripts++;\n    }\n  }\n\n  // 2. Copy agent skill if .agents/ directory pattern exists\n  const skillSource = resolve(__dirname, \"../.agents/skills/pinpoint\");\n  const skillDest = resolve(projectRoot, \".agents/skills/pinpoint\");\n\n  if (existsSync(skillSource)) {\n    if (!existsSync(skillDest)) {\n      mkdirSync(skillDest, { recursive: true });\n    }\n    const skillFile = join(skillSource, \"SKILL.md\");\n    const skillDestFile = join(skillDest, \"SKILL.md\");\n    if (existsSync(skillFile)) {\n      if (existsSync(skillDestFile)) {\n        console.log(\n          \"  skip  .agents/skills/pinpoint/SKILL.md (already exists)\",\n        );\n      } else {\n        cpSync(skillFile, skillDestFile);\n        console.log(\"  added .agents/skills/pinpoint/SKILL.md\");\n      }\n    }\n  }\n\n  console.log(\"\");\n  console.log(\n    copiedScripts > 0\n      ? \"Pinpoint initialized. Agent scripts are in scripts/.\"\n      : \"Pinpoint already initialized. No new files copied.\",\n  );\n  console.log(\"\");\n  console.log(\"Next steps:\");\n  console.log(\n    \"  1. Add <Pinpoint /> to your client:  import { Pinpoint } from '@agent-native/pinpoint/react'\",\n  );\n  console.log(\n    '  2. Add middleware to your server:     app.use(\"/api/pins\", pagePinRoutes())',\n  );\n}\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,wCAAwC;AACpD,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-25JPHXYA.js

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

package/dist/formatter-25JPHXYA.js.map

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

package/dist/index-5or67wLi.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 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-CJGmgMCD.d.ts

@@ -0,0 +1,79 @@
+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 {
+    /** 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;
+
+/**
+ * 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;
+
+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;
+
+/**
+ * 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 };