@inspecto-dev/types 0.2.0-alpha.4 → 0.3.0

package/dist/index.cjs

@@ -27,83 +27,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/intents.ts
-var DEFAULT_INTENTS = [
-  // ── 1. Explain Component ─────────────────────────────────────────────────
-  // Frequency: ★★★★★ — Most common action when navigating unfamiliar codebases
-  {
-    id: "explain",
-    label: "Explain Component",
-    prompt: `The following is a {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Please explain:
-
-1. What this component does and its responsibility in the UI
-2. Key props and their purpose
-3. Important state or side effects (if applicable)
-4. Any non-obvious logic or edge cases worth noting`
-  },
-  // ── 2. Fix Bug ───────────────────────────────────────────────────────────
-  // Frequency: ★★★★★ — Debugging is the highest time-cost activity in frontend dev
-  {
-    id: "fix-bug",
-    label: "Fix Bug",
-    prompt: `I found a bug in the following {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Please:
-
-1. Identify potential bugs or issues in this code
-2. Explain the root cause of each issue
-3. Provide a fixed version with minimal changes
-
-If you need more context (e.g. parent component, API response shape),
-please ask before suggesting a fix.`
-  },
-  // ── 3. Fix Styles ────────────────────────────────────────────────────────
-  // Frequency: ★★★★ — Styling issues are top-3 daily pain points for frontend devs
-  {
-    id: "fix-styles",
-    label: "Fix Styles",
-    prompt: `The following component from \`{{file}}\` (line {{line}}) has a styling issue.
-
-Please:
-
-1. Review the current styles (className / inline styles / CSS-in-JS / Style blocks)
-2. Identify common issues: layout shifts, overflow, z-index conflicts,
-   responsive breakpoints, or visual inconsistencies
-3. Suggest fixes using the same styling approach already in use
-
-Note: Maintain the existing styling conventions (e.g. Tailwind, CSS Modules, scoped styles).`
-  },
-  // ── 4. Refactor Component ────────────────────────────────────────────────
-  // Frequency: ★★★★ — Sustained demand after features stabilize; large component splits
-  {
-    id: "refactor",
-    label: "Refactor Component",
-    prompt: `Please refactor the following {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Refactoring goals (apply as relevant):
-
-- Extract reusable sub-components or composables/hooks
-- Improve readability and reduce complexity
-- Remove redundant state or unnecessary re-renders
-- Apply {{framework}} best practices
-- Maintain existing behavior \u2014 no functional changes
-
-Please show the refactored version with a brief explanation of each change.`
-  },
-  // ── 5. Open in Editor ────────────────────────────────────────────────────
-  // Type: local action (no AI prompt) — jumps directly to source in IDE
-  {
-    id: "open-in-editor",
-    label: "Open in Editor",
-    prompt: "",
-    // unused — isAction handles this
-    isAction: true
-  }
-];
-
-// src/index.ts
+// src/providers.ts
 var VALID_MODES = {
   copilot: ["extension"],
   "claude-code": ["extension", "cli"],
@@ -122,6 +46,8 @@ var DEFAULT_PROVIDER_MODE = {
   trae: "builtin",
   cursor: "builtin"
 };
+
+// src/api.ts
 var INSPECTO_API_PATHS = {
   HEALTH: "/inspecto/api/v1/health",
   CLIENT_CONFIG: "/inspecto/api/v1/client/config",
@@ -129,9 +55,55 @@ var INSPECTO_API_PATHS = {
   IDE_OPEN: "/inspecto/api/v1/ide/open",
   PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet",
   AI_DISPATCH: "/inspecto/api/v1/ai/dispatch",
+  AI_BATCH_DISPATCH: "/inspecto/api/v1/ai/dispatch/annotations",
   AI_TICKET: "/inspecto/api/v1/ai/ticket"
-  // Usage: /inspecto/api/v1/ai/ticket/:id
 };
+
+// src/intents.ts
+var DEFAULT_INTENTS = [
+  {
+    id: "explain",
+    label: "Explain",
+    aiIntent: "ask",
+    prompt: `Explain what this {{framework}} component from \`{{file}}\` (line {{line}}) does.
+
+Focus on:
+- its UI responsibility
+- key props, state, or side effects
+- any non-obvious logic worth noticing`
+  },
+  {
+    id: "fix-bug",
+    label: "Fix Bug",
+    aiIntent: "fix",
+    prompt: `Help fix a bug in this {{framework}} component from \`{{file}}\` (line {{line}}).
+
+Please:
+- identify the most likely root cause
+- explain why it happens
+- suggest the smallest safe fix
+
+If important context is missing, ask for it before proposing broader changes.`
+  },
+  {
+    id: "fix-ui",
+    label: "Fix UI",
+    aiIntent: "fix",
+    prompt: `Help fix a UI issue in this {{framework}} component from \`{{file}}\` (line {{line}}).
+
+Please review layout, spacing, overflow, alignment, layering, and visual consistency,
+then suggest fixes using the same styling approach already used in this codebase.`
+  },
+  {
+    id: "improve",
+    label: "Improve",
+    aiIntent: "review",
+    prompt: `Review this {{framework}} component from \`{{file}}\` (line {{line}}) and suggest practical improvements.
+
+Focus on readability, maintainability, and small structural cleanups.
+Keep behavior unchanged unless a change is clearly justified.`
+  }
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_INTENTS,

package/dist/index.d.cts

@@ -1,119 +1,36 @@
-declare const DEFAULT_INTENTS: ({
-    id: string;
-    label: string;
-    prompt: string;
-    isAction?: never;
-} | {
-    id: string;
-    label: string;
-    prompt: string;
-    isAction: boolean;
-})[];
-
-/** Modifier keys that can be used as inspector activation hotkeys */
 type HotKey = 'ctrlKey' | 'altKey' | 'metaKey' | 'shiftKey';
-/**
- * Hotkey configuration strings.
- * E.g. "alt", "cmd+shift", or false to disable.
- */
 type HotKeyString = 'alt' | 'shift' | 'ctrl' | 'meta' | 'cmd' | 'alt+shift' | 'ctrl+shift' | 'meta+shift' | 'cmd+shift';
-/**
- * Hotkey configuration.
- * - String: modifier key or combo (e.g., "alt", "cmd+shift")
- * - false: disable hotkey activation entirely
- */
 type HotKeys = HotKeyString | false;
-/** Parsed source location from the data-inspecto attribute */
 interface SourceLocation {
-    /** Absolute or relative file path depending on pathType config */
     file: string;
-    /** 1-based line number */
     line: number;
-    /** 1-based column number */
     column: number;
-    /** Optional: component or element name for display */
     name?: string;
 }
-/** Format of the data-inspecto attribute value: "filepath:line:col" */
 type SourceAttrValue = string;
-/**
- * Path type injected into data-inspecto attributes.
- * - 'absolute': full filesystem path (default) — safe across monorepo aliases
- * - 'relative': path relative to project root — shorter, but may break with pnpm virtual store
- */
 type PathType = 'relative' | 'absolute';
-/** Configuration for the @inspecto-dev/plugin build plugin */
+type LogLevel = 'info' | 'warn' | 'error' | 'silent';
 interface UnpluginOptions {
-    /**
-     * Additional file extensions to transform beyond .jsx/.tsx/.js/.ts
-     * @default []
-     */
     include?: string[];
-    /**
-     * File path patterns to exclude from transform
-     * Matched against absolute file path using picomatch
-     * node_modules and dist are always excluded
-     * @default []
-     */
     exclude?: string[];
-    /**
-     * Element tag names to skip source injection.
-     * Useful for framework-internal elements that should not carry source data.
-     * @default ['template', 'script', 'style', 'Transition', 'TransitionGroup',
-     *           'KeepAlive', 'Teleport', 'Suspense', 'Fragment']
-     */
     escapeTags?: string[];
-    /**
-     * Path type for the injected data-inspecto attribute value.
-     * Use 'absolute' (default) to avoid issues with monorepo path aliases
-     * and pnpm virtual store symlinks.
-     * @default 'absolute'
-     */
     pathType?: PathType;
-    /**
-     * The attribute name injected on JSX elements.
-     * Change only if 'data-inspecto' conflicts with another tool.
-     * @default 'data-inspecto'
-     */
     attributeName?: string;
-    /**
-     * Console log level for the plugin.
-     * - 'info': Print startup info, warnings, and errors
-     * - 'warn': Print warnings and errors only
-     * - 'error': Print errors only
-     * - 'silent': Disable all console output
-     * @default 'warn'
-     */
     logLevel?: LogLevel;
 }
-type LogLevel = 'info' | 'warn' | 'error' | 'silent';
-/** Supported IDEs */
+
 type IdeType = 'vscode' | 'trae' | 'trae-cn' | 'cursor' | 'unknown';
-/** All supported AI tool providers */
 type Provider = 'copilot' | 'claude-code' | 'gemini' | 'codex' | 'coco' | 'trae' | 'cursor';
-/** Whether the AI provider is an editor extension, CLI tool, or clipboard fallback */
 type ProviderMode = 'extension' | 'cli' | 'clipboard' | 'builtin';
 interface InspectoSettings {
     ide?: IdeType;
-    /** Flat namespaced configuration (e.g. `provider.default`, `provider.claude-code.cli.bin`) */
     [key: `provider.${string}`]: string | string[] | boolean | undefined;
     'inspector.hotKey'?: HotKeys;
-    /**
-     * Theme for the inspector panel.
-     */
     'inspector.theme'?: 'light' | 'dark' | 'auto';
-    /**
-     * Whether to inject the raw code snippet into the prompt.
-     * Default is false (saves tokens, lets IDE AI read the file directly).
-     */
     'prompt.includeSnippet'?: boolean;
-    /**
-     * Whether to automatically send the prompt when opened in the AI tool.
-     * Default is false (user must manually hit send).
-     */
     'prompt.autoSend'?: boolean;
+    'prompt.annotationResponseMode'?: 'unified' | 'per-annotation';
 }
-/** Static mapping: which modes each tool actually supports */
 declare const VALID_MODES: Record<Provider, ProviderMode[]>;
 declare const DEFAULT_PROVIDER_MODE: Record<Provider, ProviderMode>;
 interface ToolOverrides {
@@ -132,203 +49,260 @@ interface AiPayload {
     line?: number;
     column?: number;
     snippet?: string;
+    screenshotContext?: ScreenshotContext;
     overrides?: ToolOverrides;
     autoSend?: boolean;
-    /** Added in v2: Unique ticket ID for the IDE to fetch this payload from the local server to bypass URI length limits */
     ticket?: string;
 }
 interface ChannelDef {
     type: ProviderMode;
     execute: (payload: AiPayload) => Promise<void>;
 }
+interface ProviderInfo {
+    mode: ProviderMode;
+    installed: boolean;
+}
+interface IdeInfo {
+    ide: IdeType;
+    scheme: string;
+    workspaceRoot?: string;
+    providers: Record<Provider, ProviderInfo>;
+}
+interface InspectoConfig {
+    ide: IdeType;
+    providers?: Record<Provider, ProviderInfo>;
+    prompts?: IntentConfig[];
+    hotKeys?: HotKeys;
+    theme?: 'light' | 'dark' | 'auto';
+    includeSnippet?: boolean;
+    annotationResponseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextConfig;
+    screenshotContext?: ScreenshotContextConfig;
+}
+interface ServerState {
+    port: number | null;
+    running: boolean;
+    projectRoot: string;
+    configRoot: string;
+    cwd: string;
+    ideInfo?: IdeInfo | null;
+}
+
+type AiIntent = 'ask' | 'fix' | 'review' | 'redesign';
+type AnnotationIntent = AiIntent;
 type IntentLabels = Partial<Record<Provider | 'clipboard', string>>;
-/**
- * Configuration for a custom intent in the AI menu.
- */
-interface IntentConfig {
-    /** Unique identifier for this intent */
-    id?: string;
-    /** The text displayed on the intent button */
+interface IntentConfigBase {
+    id: string;
     label?: string;
-    /**
-     * Prepend text to the prompt template.
-     * Useful for extending built-in prompts without rewriting the whole template.
-     */
     prependPrompt?: string;
-    /**
-     * Append text to the prompt template.
-     * Useful for extending built-in prompts (e.g. "Please reply in Chinese").
-     */
     appendPrompt?: string;
     prompt?: string;
-    /**
-     * If true, this intent doesn't send a prompt to AI,
-     * but rather triggers a built-in action (like 'open-in-editor').
-     * @internal For built-in intents only.
-     */
-    isAction?: boolean;
-    /**
-     * Enabled status.
-     * If false, this item is explicitly hidden from the menu without having to remove its configuration.
-     */
     enabled?: boolean;
 }
+interface AiIntentConfig extends IntentConfigBase {
+    aiIntent: AiIntent;
+}
+type IntentConfig = AiIntentConfig;
 type InspectoPromptsConfig = (string | IntentConfig)[] | {
     $replace: true;
     items: (string | IntentConfig)[];
 };
-/** Configuration for the browser-side inspector component */
 interface InspectorOptions {
-    /**
-     * Hotkeys to hold while clicking to activate inspector.
-     * Pass false to disable hotkey activation.
-     * @default ['altKey']
-     */
     hotKeys?: HotKeys;
-    /**
-     * Custom labels for each AI target button.
-     * Useful for localization or branding.
-     */
     labels?: IntentLabels;
-    /**
-     * Placeholder text for the "Ask AI" input box.
-     */
     askPlaceholder?: string;
-    /**
-     * Base URL of the local HTTP server spun up by the unplugin.
-     * Usually auto-detected via the injected __AI_INSPECTOR_PORT__ global.
-     * Override only if running in a non-standard setup.
-     */
     serverUrl?: string;
-    /**
-     * Maximum number of lines to include in the extracted code snippet.
-     * Larger values provide more context but may hit AI token limits.
-     * @default 100
-     */
     maxSnippetLines?: number;
-    /**
-     * Whether the inspector panel is visible/active on mount.
-     * @default false
-     */
     defaultActive?: boolean;
-    /**
-     * Theme for the inspector panel.
-     * If 'auto' or undefined, it relies on CSS media queries (prefers-color-scheme)
-     * or inherits from the host environment if manually managed.
-     */
     theme?: 'light' | 'dark' | 'auto';
-    /**
-     * Whether to inject the raw code snippet into the prompt.
-     * Default is false (saves tokens, lets IDE AI read the file directly).
-     */
     includeSnippet?: boolean;
+    annotationResponseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextConfig;
+    screenshotContext?: ScreenshotContextConfig;
+}
+interface SendToAiRequest {
+    location: SourceLocation;
+    snippet: string;
+    prompt?: string;
+    target?: Provider;
+    runtimeContext?: RuntimeContextEnvelope;
+    screenshotContext?: ScreenshotContext;
+}
+interface SendToAiResponse {
+    success: boolean;
+    error?: string;
+    errorCode?: AiErrorCode;
+    fallbackPayload?: {
+        prompt: string;
+        file: string;
+    };
+}
+interface AiStrategyContext {
+    location: SourceLocation;
+    snippet: string;
+    fileUri: string;
+    prompt: string;
+}
+interface AiStrategyResult {
+    success: boolean;
+    error?: string;
+    errorCode?: AiErrorCode;
 }
 
-declare const INSPECTO_API_PATHS: {
-    readonly HEALTH: "/inspecto/api/v1/health";
-    readonly CLIENT_CONFIG: "/inspecto/api/v1/client/config";
-    readonly IDE_INFO: "/inspecto/api/v1/ide/info";
-    readonly IDE_OPEN: "/inspecto/api/v1/ide/open";
-    readonly PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet";
-    readonly AI_DISPATCH: "/inspecto/api/v1/ai/dispatch";
-    readonly AI_TICKET: "/inspecto/api/v1/ai/ticket";
-};
-/** POST /open — browser asks server to open file in IDE */
+type RuntimeEvidenceKind = 'runtime-error' | 'promise-rejection' | 'console-error' | 'failed-request';
+type RuntimeEvidenceLevel = 'high' | 'medium' | 'low';
+interface RuntimeEvidenceRecord {
+    id: string;
+    kind: RuntimeEvidenceKind;
+    timestamp: number;
+    message: string;
+    stack?: string;
+    sourceUrl?: string;
+    sourceFile?: string;
+    route?: string;
+    componentHints?: string[];
+    occurrenceCount: number;
+    relevanceScore: number;
+    relevanceLevel: RuntimeEvidenceLevel;
+    relevanceReasons: string[];
+    request?: {
+        method?: string;
+        url?: string;
+        pathname?: string;
+        status?: number;
+        responseSummary?: string;
+    };
+}
+interface RuntimeContextSummary {
+    runtimeErrorCount: number;
+    failedRequestCount: number;
+    includedRecordIds: string[];
+}
+interface RuntimeContextEnvelope {
+    summary: RuntimeContextSummary;
+    records: RuntimeEvidenceRecord[];
+}
+interface RuntimeContextConfig {
+    enabled?: boolean;
+    preview?: boolean;
+    maxRuntimeErrors?: number;
+    maxFailedRequests?: number;
+}
+interface ScreenshotContext {
+    enabled: boolean;
+    capturedAt: string;
+    mimeType: string;
+    imageDataUrl?: string;
+    imageAssetId?: string;
+}
+interface ScreenshotContextConfig {
+    enabled?: boolean;
+}
 interface OpenFileRequest {
     file: string;
     line: number;
     column: number;
 }
-/** GET /snippet — browser asks server for source code context */
 interface SnippetRequest {
     file: string;
     line: number;
     column: number;
-    /** Max lines to return in snippet, default 100 */
     maxLines?: number;
 }
 interface SnippetResponse {
-    /** Extracted code snippet (trimmed to maxSnippetLines) */
     snippet: string;
-    /** Actual start line of the returned snippet (1-based) */
     startLine: number;
-    /** File path echoed back */
     file: string;
-    /** Component or element name if detectable */
     name?: string;
 }
-/** POST /send-to-ai — browser asks server to dispatch context to an AI tool */
-interface SendToAiRequest {
+interface AnnotationTarget {
+    id: string;
     location: SourceLocation;
-    snippet: string;
-    /** Prompt template. Server may override with its own template. */
-    prompt?: string;
-    /** Target AI tool. If not provided, server will resolve it based on config */
-    target?: Provider;
-}
-interface SendToAiResponse {
-    success: boolean;
-    error?: string;
-    /** Error code for structured error handling in the browser */
-    errorCode?: AiErrorCode;
-    /** Payload for client-side fallback (e.g. copying to clipboard if IDE fails to handle URI) */
-    fallbackPayload?: {
-        prompt: string;
-        file: string;
+    label: string;
+    selector?: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
     };
+    snippet?: string;
 }
-/** Standard error codes returned by the local HTTP server */
-type AiErrorCode = 'IDE_NOT_FOUND' | 'EXTENSION_NOT_INSTALLED' | 'CLIPBOARD_WRITE_FAILED' | 'SNIPPET_TOO_LARGE' | 'FILE_NOT_FOUND' | 'UNKNOWN';
-interface ProviderInfo {
-    mode: ProviderMode;
-    installed: boolean;
+interface FeedbackRecord {
+    id: string;
+    displayOrder: number;
+    target: AnnotationTarget;
+    note: string;
+    intent: AnnotationIntent;
+    cssContextEnabled?: boolean;
 }
-interface IdeInfo {
-    ide: IdeType;
-    scheme: string;
-    workspaceRoot?: string;
-    providers: Record<Provider, ProviderInfo>;
+interface FeedbackRecordDraft {
+    id: string;
+    displayOrder?: number;
+    target: AnnotationTarget | null;
+    note: string;
+    intent: AnnotationIntent;
+    cssContextEnabled?: boolean;
 }
-/** GET /config response — browser-facing runtime configuration */
-interface InspectoConfig {
-    ide: IdeType;
-    /** List of AI targets available in the environment to show/enable in UI */
-    providers?: Record<Provider, ProviderInfo>;
-    /** Fully resolved and merged list of intent configurations for the UI to display */
-    prompts?: IntentConfig[];
-    hotKeys?: HotKeys;
-    theme?: 'light' | 'dark' | 'auto';
-    includeSnippet?: boolean;
+interface FeedbackRecordSession {
+    current: FeedbackRecordDraft;
+    records: FeedbackRecord[];
 }
-/** Shared mutable state managed by the local HTTP server module */
-interface ServerState {
-    /** Port the HTTP server is currently listening on */
-    port: number | null;
-    /** Whether the server is currently running */
-    running: boolean;
-    /** Absolute path to project root (from git rev-parse or process.cwd()) */
-    projectRoot: string;
-    /** Absolute path to the config root (where .inspecto lives) */
-    configRoot: string;
-    /** The directory where the bundler is running (process.cwd()) */
-    cwd: string;
-    /** Cached IDE info pushed from the extension */
-    ideInfo?: IdeInfo | null;
+interface Annotation {
+    id: string;
+    note: string;
+    intent: AnnotationIntent;
+    targets: AnnotationTarget[];
 }
-/** Context passed to each AI strategy when sending code context */
-interface AiStrategyContext {
+interface AnnotationSession {
+    current: Annotation | null;
+    queue: Annotation[];
+}
+interface AnnotationTransportTarget {
     location: SourceLocation;
-    snippet: string;
-    /** Resolved absolute file URI (file:///...) */
-    fileUri: string;
-    /** Human-readable prompt constructed from location + snippet */
-    prompt: string;
+    label?: string;
+    selector?: string;
+    snippet?: string;
 }
-/** Result of executing an AI strategy */
-interface AiStrategyResult {
+interface AnnotationTransport {
+    note: string;
+    intent: AnnotationIntent;
+    targets: AnnotationTransportTarget[];
+}
+interface SendAnnotationsToAiRequest {
+    instruction?: string;
+    annotations: AnnotationTransport[];
+    responseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextEnvelope;
+    screenshotContext?: ScreenshotContext;
+    cssContextPrompt?: string;
+}
+interface SendAnnotationsToAiResponse {
     success: boolean;
     error?: string;
     errorCode?: AiErrorCode;
+    fallbackPayload?: {
+        prompt: string;
+    };
 }
+type AiErrorCode = 'INVALID_REQUEST' | 'FORBIDDEN_PATH' | 'IDE_NOT_FOUND' | 'EXTENSION_NOT_INSTALLED' | 'CLIPBOARD_WRITE_FAILED' | 'SNIPPET_TOO_LARGE' | 'FILE_NOT_FOUND' | 'UNKNOWN';
+
+declare const INSPECTO_API_PATHS: {
+    readonly HEALTH: "/inspecto/api/v1/health";
+    readonly CLIENT_CONFIG: "/inspecto/api/v1/client/config";
+    readonly IDE_INFO: "/inspecto/api/v1/ide/info";
+    readonly IDE_OPEN: "/inspecto/api/v1/ide/open";
+    readonly PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet";
+    readonly AI_DISPATCH: "/inspecto/api/v1/ai/dispatch";
+    readonly AI_BATCH_DISPATCH: "/inspecto/api/v1/ai/dispatch/annotations";
+    readonly AI_TICKET: "/inspecto/api/v1/ai/ticket";
+};
+
+declare const DEFAULT_INTENTS: {
+    id: string;
+    label: string;
+    aiIntent: string;
+    prompt: string;
+}[];
 
-export { type AiErrorCode, type AiPayload, type AiStrategyContext, type AiStrategyResult, type ChannelDef, DEFAULT_INTENTS, DEFAULT_PROVIDER_MODE, type HotKey, type HotKeyString, type HotKeys, INSPECTO_API_PATHS, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentLabels, type LogLevel, type OpenFileRequest, type PathType, type Provider, type ProviderInfo, type ProviderMode, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolOverrides, type UnpluginOptions, VALID_MODES };
+export { type AiErrorCode, type AiIntent, type AiIntentConfig, type AiPayload, type AiStrategyContext, type AiStrategyResult, type Annotation, type AnnotationIntent, type AnnotationSession, type AnnotationTarget, type AnnotationTransport, type AnnotationTransportTarget, type ChannelDef, DEFAULT_INTENTS, DEFAULT_PROVIDER_MODE, type FeedbackRecord, type FeedbackRecordDraft, type FeedbackRecordSession, type HotKey, type HotKeyString, type HotKeys, INSPECTO_API_PATHS, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentConfigBase, type IntentLabels, type LogLevel, type OpenFileRequest, type PathType, type Provider, type ProviderInfo, type ProviderMode, type RuntimeContextConfig, type RuntimeContextEnvelope, type RuntimeContextSummary, type RuntimeEvidenceKind, type RuntimeEvidenceLevel, type RuntimeEvidenceRecord, type ScreenshotContext, type ScreenshotContextConfig, type SendAnnotationsToAiRequest, type SendAnnotationsToAiResponse, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolOverrides, type UnpluginOptions, VALID_MODES };

package/dist/index.d.ts

@@ -1,119 +1,36 @@
-declare const DEFAULT_INTENTS: ({
-    id: string;
-    label: string;
-    prompt: string;
-    isAction?: never;
-} | {
-    id: string;
-    label: string;
-    prompt: string;
-    isAction: boolean;
-})[];
-
-/** Modifier keys that can be used as inspector activation hotkeys */
 type HotKey = 'ctrlKey' | 'altKey' | 'metaKey' | 'shiftKey';
-/**
- * Hotkey configuration strings.
- * E.g. "alt", "cmd+shift", or false to disable.
- */
 type HotKeyString = 'alt' | 'shift' | 'ctrl' | 'meta' | 'cmd' | 'alt+shift' | 'ctrl+shift' | 'meta+shift' | 'cmd+shift';
-/**
- * Hotkey configuration.
- * - String: modifier key or combo (e.g., "alt", "cmd+shift")
- * - false: disable hotkey activation entirely
- */
 type HotKeys = HotKeyString | false;
-/** Parsed source location from the data-inspecto attribute */
 interface SourceLocation {
-    /** Absolute or relative file path depending on pathType config */
     file: string;
-    /** 1-based line number */
     line: number;
-    /** 1-based column number */
     column: number;
-    /** Optional: component or element name for display */
     name?: string;
 }
-/** Format of the data-inspecto attribute value: "filepath:line:col" */
 type SourceAttrValue = string;
-/**
- * Path type injected into data-inspecto attributes.
- * - 'absolute': full filesystem path (default) — safe across monorepo aliases
- * - 'relative': path relative to project root — shorter, but may break with pnpm virtual store
- */
 type PathType = 'relative' | 'absolute';
-/** Configuration for the @inspecto-dev/plugin build plugin */
+type LogLevel = 'info' | 'warn' | 'error' | 'silent';
 interface UnpluginOptions {
-    /**
-     * Additional file extensions to transform beyond .jsx/.tsx/.js/.ts
-     * @default []
-     */
     include?: string[];
-    /**
-     * File path patterns to exclude from transform
-     * Matched against absolute file path using picomatch
-     * node_modules and dist are always excluded
-     * @default []
-     */
     exclude?: string[];
-    /**
-     * Element tag names to skip source injection.
-     * Useful for framework-internal elements that should not carry source data.
-     * @default ['template', 'script', 'style', 'Transition', 'TransitionGroup',
-     *           'KeepAlive', 'Teleport', 'Suspense', 'Fragment']
-     */
     escapeTags?: string[];
-    /**
-     * Path type for the injected data-inspecto attribute value.
-     * Use 'absolute' (default) to avoid issues with monorepo path aliases
-     * and pnpm virtual store symlinks.
-     * @default 'absolute'
-     */
     pathType?: PathType;
-    /**
-     * The attribute name injected on JSX elements.
-     * Change only if 'data-inspecto' conflicts with another tool.
-     * @default 'data-inspecto'
-     */
     attributeName?: string;
-    /**
-     * Console log level for the plugin.
-     * - 'info': Print startup info, warnings, and errors
-     * - 'warn': Print warnings and errors only
-     * - 'error': Print errors only
-     * - 'silent': Disable all console output
-     * @default 'warn'
-     */
     logLevel?: LogLevel;
 }
-type LogLevel = 'info' | 'warn' | 'error' | 'silent';
-/** Supported IDEs */
+
 type IdeType = 'vscode' | 'trae' | 'trae-cn' | 'cursor' | 'unknown';
-/** All supported AI tool providers */
 type Provider = 'copilot' | 'claude-code' | 'gemini' | 'codex' | 'coco' | 'trae' | 'cursor';
-/** Whether the AI provider is an editor extension, CLI tool, or clipboard fallback */
 type ProviderMode = 'extension' | 'cli' | 'clipboard' | 'builtin';
 interface InspectoSettings {
     ide?: IdeType;
-    /** Flat namespaced configuration (e.g. `provider.default`, `provider.claude-code.cli.bin`) */
     [key: `provider.${string}`]: string | string[] | boolean | undefined;
     'inspector.hotKey'?: HotKeys;
-    /**
-     * Theme for the inspector panel.
-     */
     'inspector.theme'?: 'light' | 'dark' | 'auto';
-    /**
-     * Whether to inject the raw code snippet into the prompt.
-     * Default is false (saves tokens, lets IDE AI read the file directly).
-     */
     'prompt.includeSnippet'?: boolean;
-    /**
-     * Whether to automatically send the prompt when opened in the AI tool.
-     * Default is false (user must manually hit send).
-     */
     'prompt.autoSend'?: boolean;
+    'prompt.annotationResponseMode'?: 'unified' | 'per-annotation';
 }
-/** Static mapping: which modes each tool actually supports */
 declare const VALID_MODES: Record<Provider, ProviderMode[]>;
 declare const DEFAULT_PROVIDER_MODE: Record<Provider, ProviderMode>;
 interface ToolOverrides {
@@ -132,203 +49,260 @@ interface AiPayload {
     line?: number;
     column?: number;
     snippet?: string;
+    screenshotContext?: ScreenshotContext;
     overrides?: ToolOverrides;
     autoSend?: boolean;
-    /** Added in v2: Unique ticket ID for the IDE to fetch this payload from the local server to bypass URI length limits */
     ticket?: string;
 }
 interface ChannelDef {
     type: ProviderMode;
     execute: (payload: AiPayload) => Promise<void>;
 }
+interface ProviderInfo {
+    mode: ProviderMode;
+    installed: boolean;
+}
+interface IdeInfo {
+    ide: IdeType;
+    scheme: string;
+    workspaceRoot?: string;
+    providers: Record<Provider, ProviderInfo>;
+}
+interface InspectoConfig {
+    ide: IdeType;
+    providers?: Record<Provider, ProviderInfo>;
+    prompts?: IntentConfig[];
+    hotKeys?: HotKeys;
+    theme?: 'light' | 'dark' | 'auto';
+    includeSnippet?: boolean;
+    annotationResponseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextConfig;
+    screenshotContext?: ScreenshotContextConfig;
+}
+interface ServerState {
+    port: number | null;
+    running: boolean;
+    projectRoot: string;
+    configRoot: string;
+    cwd: string;
+    ideInfo?: IdeInfo | null;
+}
+
+type AiIntent = 'ask' | 'fix' | 'review' | 'redesign';
+type AnnotationIntent = AiIntent;
 type IntentLabels = Partial<Record<Provider | 'clipboard', string>>;
-/**
- * Configuration for a custom intent in the AI menu.
- */
-interface IntentConfig {
-    /** Unique identifier for this intent */
-    id?: string;
-    /** The text displayed on the intent button */
+interface IntentConfigBase {
+    id: string;
     label?: string;
-    /**
-     * Prepend text to the prompt template.
-     * Useful for extending built-in prompts without rewriting the whole template.
-     */
     prependPrompt?: string;
-    /**
-     * Append text to the prompt template.
-     * Useful for extending built-in prompts (e.g. "Please reply in Chinese").
-     */
     appendPrompt?: string;
     prompt?: string;
-    /**
-     * If true, this intent doesn't send a prompt to AI,
-     * but rather triggers a built-in action (like 'open-in-editor').
-     * @internal For built-in intents only.
-     */
-    isAction?: boolean;
-    /**
-     * Enabled status.
-     * If false, this item is explicitly hidden from the menu without having to remove its configuration.
-     */
     enabled?: boolean;
 }
+interface AiIntentConfig extends IntentConfigBase {
+    aiIntent: AiIntent;
+}
+type IntentConfig = AiIntentConfig;
 type InspectoPromptsConfig = (string | IntentConfig)[] | {
     $replace: true;
     items: (string | IntentConfig)[];
 };
-/** Configuration for the browser-side inspector component */
 interface InspectorOptions {
-    /**
-     * Hotkeys to hold while clicking to activate inspector.
-     * Pass false to disable hotkey activation.
-     * @default ['altKey']
-     */
     hotKeys?: HotKeys;
-    /**
-     * Custom labels for each AI target button.
-     * Useful for localization or branding.
-     */
     labels?: IntentLabels;
-    /**
-     * Placeholder text for the "Ask AI" input box.
-     */
     askPlaceholder?: string;
-    /**
-     * Base URL of the local HTTP server spun up by the unplugin.
-     * Usually auto-detected via the injected __AI_INSPECTOR_PORT__ global.
-     * Override only if running in a non-standard setup.
-     */
     serverUrl?: string;
-    /**
-     * Maximum number of lines to include in the extracted code snippet.
-     * Larger values provide more context but may hit AI token limits.
-     * @default 100
-     */
     maxSnippetLines?: number;
-    /**
-     * Whether the inspector panel is visible/active on mount.
-     * @default false
-     */
     defaultActive?: boolean;
-    /**
-     * Theme for the inspector panel.
-     * If 'auto' or undefined, it relies on CSS media queries (prefers-color-scheme)
-     * or inherits from the host environment if manually managed.
-     */
     theme?: 'light' | 'dark' | 'auto';
-    /**
-     * Whether to inject the raw code snippet into the prompt.
-     * Default is false (saves tokens, lets IDE AI read the file directly).
-     */
     includeSnippet?: boolean;
+    annotationResponseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextConfig;
+    screenshotContext?: ScreenshotContextConfig;
+}
+interface SendToAiRequest {
+    location: SourceLocation;
+    snippet: string;
+    prompt?: string;
+    target?: Provider;
+    runtimeContext?: RuntimeContextEnvelope;
+    screenshotContext?: ScreenshotContext;
+}
+interface SendToAiResponse {
+    success: boolean;
+    error?: string;
+    errorCode?: AiErrorCode;
+    fallbackPayload?: {
+        prompt: string;
+        file: string;
+    };
+}
+interface AiStrategyContext {
+    location: SourceLocation;
+    snippet: string;
+    fileUri: string;
+    prompt: string;
+}
+interface AiStrategyResult {
+    success: boolean;
+    error?: string;
+    errorCode?: AiErrorCode;
 }
 
-declare const INSPECTO_API_PATHS: {
-    readonly HEALTH: "/inspecto/api/v1/health";
-    readonly CLIENT_CONFIG: "/inspecto/api/v1/client/config";
-    readonly IDE_INFO: "/inspecto/api/v1/ide/info";
-    readonly IDE_OPEN: "/inspecto/api/v1/ide/open";
-    readonly PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet";
-    readonly AI_DISPATCH: "/inspecto/api/v1/ai/dispatch";
-    readonly AI_TICKET: "/inspecto/api/v1/ai/ticket";
-};
-/** POST /open — browser asks server to open file in IDE */
+type RuntimeEvidenceKind = 'runtime-error' | 'promise-rejection' | 'console-error' | 'failed-request';
+type RuntimeEvidenceLevel = 'high' | 'medium' | 'low';
+interface RuntimeEvidenceRecord {
+    id: string;
+    kind: RuntimeEvidenceKind;
+    timestamp: number;
+    message: string;
+    stack?: string;
+    sourceUrl?: string;
+    sourceFile?: string;
+    route?: string;
+    componentHints?: string[];
+    occurrenceCount: number;
+    relevanceScore: number;
+    relevanceLevel: RuntimeEvidenceLevel;
+    relevanceReasons: string[];
+    request?: {
+        method?: string;
+        url?: string;
+        pathname?: string;
+        status?: number;
+        responseSummary?: string;
+    };
+}
+interface RuntimeContextSummary {
+    runtimeErrorCount: number;
+    failedRequestCount: number;
+    includedRecordIds: string[];
+}
+interface RuntimeContextEnvelope {
+    summary: RuntimeContextSummary;
+    records: RuntimeEvidenceRecord[];
+}
+interface RuntimeContextConfig {
+    enabled?: boolean;
+    preview?: boolean;
+    maxRuntimeErrors?: number;
+    maxFailedRequests?: number;
+}
+interface ScreenshotContext {
+    enabled: boolean;
+    capturedAt: string;
+    mimeType: string;
+    imageDataUrl?: string;
+    imageAssetId?: string;
+}
+interface ScreenshotContextConfig {
+    enabled?: boolean;
+}
 interface OpenFileRequest {
     file: string;
     line: number;
     column: number;
 }
-/** GET /snippet — browser asks server for source code context */
 interface SnippetRequest {
     file: string;
     line: number;
     column: number;
-    /** Max lines to return in snippet, default 100 */
     maxLines?: number;
 }
 interface SnippetResponse {
-    /** Extracted code snippet (trimmed to maxSnippetLines) */
     snippet: string;
-    /** Actual start line of the returned snippet (1-based) */
     startLine: number;
-    /** File path echoed back */
     file: string;
-    /** Component or element name if detectable */
     name?: string;
 }
-/** POST /send-to-ai — browser asks server to dispatch context to an AI tool */
-interface SendToAiRequest {
+interface AnnotationTarget {
+    id: string;
     location: SourceLocation;
-    snippet: string;
-    /** Prompt template. Server may override with its own template. */
-    prompt?: string;
-    /** Target AI tool. If not provided, server will resolve it based on config */
-    target?: Provider;
-}
-interface SendToAiResponse {
-    success: boolean;
-    error?: string;
-    /** Error code for structured error handling in the browser */
-    errorCode?: AiErrorCode;
-    /** Payload for client-side fallback (e.g. copying to clipboard if IDE fails to handle URI) */
-    fallbackPayload?: {
-        prompt: string;
-        file: string;
+    label: string;
+    selector?: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
     };
+    snippet?: string;
 }
-/** Standard error codes returned by the local HTTP server */
-type AiErrorCode = 'IDE_NOT_FOUND' | 'EXTENSION_NOT_INSTALLED' | 'CLIPBOARD_WRITE_FAILED' | 'SNIPPET_TOO_LARGE' | 'FILE_NOT_FOUND' | 'UNKNOWN';
-interface ProviderInfo {
-    mode: ProviderMode;
-    installed: boolean;
+interface FeedbackRecord {
+    id: string;
+    displayOrder: number;
+    target: AnnotationTarget;
+    note: string;
+    intent: AnnotationIntent;
+    cssContextEnabled?: boolean;
 }
-interface IdeInfo {
-    ide: IdeType;
-    scheme: string;
-    workspaceRoot?: string;
-    providers: Record<Provider, ProviderInfo>;
+interface FeedbackRecordDraft {
+    id: string;
+    displayOrder?: number;
+    target: AnnotationTarget | null;
+    note: string;
+    intent: AnnotationIntent;
+    cssContextEnabled?: boolean;
 }
-/** GET /config response — browser-facing runtime configuration */
-interface InspectoConfig {
-    ide: IdeType;
-    /** List of AI targets available in the environment to show/enable in UI */
-    providers?: Record<Provider, ProviderInfo>;
-    /** Fully resolved and merged list of intent configurations for the UI to display */
-    prompts?: IntentConfig[];
-    hotKeys?: HotKeys;
-    theme?: 'light' | 'dark' | 'auto';
-    includeSnippet?: boolean;
+interface FeedbackRecordSession {
+    current: FeedbackRecordDraft;
+    records: FeedbackRecord[];
 }
-/** Shared mutable state managed by the local HTTP server module */
-interface ServerState {
-    /** Port the HTTP server is currently listening on */
-    port: number | null;
-    /** Whether the server is currently running */
-    running: boolean;
-    /** Absolute path to project root (from git rev-parse or process.cwd()) */
-    projectRoot: string;
-    /** Absolute path to the config root (where .inspecto lives) */
-    configRoot: string;
-    /** The directory where the bundler is running (process.cwd()) */
-    cwd: string;
-    /** Cached IDE info pushed from the extension */
-    ideInfo?: IdeInfo | null;
+interface Annotation {
+    id: string;
+    note: string;
+    intent: AnnotationIntent;
+    targets: AnnotationTarget[];
 }
-/** Context passed to each AI strategy when sending code context */
-interface AiStrategyContext {
+interface AnnotationSession {
+    current: Annotation | null;
+    queue: Annotation[];
+}
+interface AnnotationTransportTarget {
     location: SourceLocation;
-    snippet: string;
-    /** Resolved absolute file URI (file:///...) */
-    fileUri: string;
-    /** Human-readable prompt constructed from location + snippet */
-    prompt: string;
+    label?: string;
+    selector?: string;
+    snippet?: string;
 }
-/** Result of executing an AI strategy */
-interface AiStrategyResult {
+interface AnnotationTransport {
+    note: string;
+    intent: AnnotationIntent;
+    targets: AnnotationTransportTarget[];
+}
+interface SendAnnotationsToAiRequest {
+    instruction?: string;
+    annotations: AnnotationTransport[];
+    responseMode?: 'unified' | 'per-annotation';
+    runtimeContext?: RuntimeContextEnvelope;
+    screenshotContext?: ScreenshotContext;
+    cssContextPrompt?: string;
+}
+interface SendAnnotationsToAiResponse {
     success: boolean;
     error?: string;
     errorCode?: AiErrorCode;
+    fallbackPayload?: {
+        prompt: string;
+    };
 }
+type AiErrorCode = 'INVALID_REQUEST' | 'FORBIDDEN_PATH' | 'IDE_NOT_FOUND' | 'EXTENSION_NOT_INSTALLED' | 'CLIPBOARD_WRITE_FAILED' | 'SNIPPET_TOO_LARGE' | 'FILE_NOT_FOUND' | 'UNKNOWN';
+
+declare const INSPECTO_API_PATHS: {
+    readonly HEALTH: "/inspecto/api/v1/health";
+    readonly CLIENT_CONFIG: "/inspecto/api/v1/client/config";
+    readonly IDE_INFO: "/inspecto/api/v1/ide/info";
+    readonly IDE_OPEN: "/inspecto/api/v1/ide/open";
+    readonly PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet";
+    readonly AI_DISPATCH: "/inspecto/api/v1/ai/dispatch";
+    readonly AI_BATCH_DISPATCH: "/inspecto/api/v1/ai/dispatch/annotations";
+    readonly AI_TICKET: "/inspecto/api/v1/ai/ticket";
+};
+
+declare const DEFAULT_INTENTS: {
+    id: string;
+    label: string;
+    aiIntent: string;
+    prompt: string;
+}[];
 
-export { type AiErrorCode, type AiPayload, type AiStrategyContext, type AiStrategyResult, type ChannelDef, DEFAULT_INTENTS, DEFAULT_PROVIDER_MODE, type HotKey, type HotKeyString, type HotKeys, INSPECTO_API_PATHS, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentLabels, type LogLevel, type OpenFileRequest, type PathType, type Provider, type ProviderInfo, type ProviderMode, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolOverrides, type UnpluginOptions, VALID_MODES };
+export { type AiErrorCode, type AiIntent, type AiIntentConfig, type AiPayload, type AiStrategyContext, type AiStrategyResult, type Annotation, type AnnotationIntent, type AnnotationSession, type AnnotationTarget, type AnnotationTransport, type AnnotationTransportTarget, type ChannelDef, DEFAULT_INTENTS, DEFAULT_PROVIDER_MODE, type FeedbackRecord, type FeedbackRecordDraft, type FeedbackRecordSession, type HotKey, type HotKeyString, type HotKeys, INSPECTO_API_PATHS, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentConfigBase, type IntentLabels, type LogLevel, type OpenFileRequest, type PathType, type Provider, type ProviderInfo, type ProviderMode, type RuntimeContextConfig, type RuntimeContextEnvelope, type RuntimeContextSummary, type RuntimeEvidenceKind, type RuntimeEvidenceLevel, type RuntimeEvidenceRecord, type ScreenshotContext, type ScreenshotContextConfig, type SendAnnotationsToAiRequest, type SendAnnotationsToAiResponse, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolOverrides, type UnpluginOptions, VALID_MODES };

package/dist/index.js

@@ -1,80 +1,4 @@
-// src/intents.ts
-var DEFAULT_INTENTS = [
-  // ── 1. Explain Component ─────────────────────────────────────────────────
-  // Frequency: ★★★★★ — Most common action when navigating unfamiliar codebases
-  {
-    id: "explain",
-    label: "Explain Component",
-    prompt: `The following is a {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Please explain:
-
-1. What this component does and its responsibility in the UI
-2. Key props and their purpose
-3. Important state or side effects (if applicable)
-4. Any non-obvious logic or edge cases worth noting`
-  },
-  // ── 2. Fix Bug ───────────────────────────────────────────────────────────
-  // Frequency: ★★★★★ — Debugging is the highest time-cost activity in frontend dev
-  {
-    id: "fix-bug",
-    label: "Fix Bug",
-    prompt: `I found a bug in the following {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Please:
-
-1. Identify potential bugs or issues in this code
-2. Explain the root cause of each issue
-3. Provide a fixed version with minimal changes
-
-If you need more context (e.g. parent component, API response shape),
-please ask before suggesting a fix.`
-  },
-  // ── 3. Fix Styles ────────────────────────────────────────────────────────
-  // Frequency: ★★★★ — Styling issues are top-3 daily pain points for frontend devs
-  {
-    id: "fix-styles",
-    label: "Fix Styles",
-    prompt: `The following component from \`{{file}}\` (line {{line}}) has a styling issue.
-
-Please:
-
-1. Review the current styles (className / inline styles / CSS-in-JS / Style blocks)
-2. Identify common issues: layout shifts, overflow, z-index conflicts,
-   responsive breakpoints, or visual inconsistencies
-3. Suggest fixes using the same styling approach already in use
-
-Note: Maintain the existing styling conventions (e.g. Tailwind, CSS Modules, scoped styles).`
-  },
-  // ── 4. Refactor Component ────────────────────────────────────────────────
-  // Frequency: ★★★★ — Sustained demand after features stabilize; large component splits
-  {
-    id: "refactor",
-    label: "Refactor Component",
-    prompt: `Please refactor the following {{framework}} component from \`{{file}}\` (line {{line}}).
-
-Refactoring goals (apply as relevant):
-
-- Extract reusable sub-components or composables/hooks
-- Improve readability and reduce complexity
-- Remove redundant state or unnecessary re-renders
-- Apply {{framework}} best practices
-- Maintain existing behavior \u2014 no functional changes
-
-Please show the refactored version with a brief explanation of each change.`
-  },
-  // ── 5. Open in Editor ────────────────────────────────────────────────────
-  // Type: local action (no AI prompt) — jumps directly to source in IDE
-  {
-    id: "open-in-editor",
-    label: "Open in Editor",
-    prompt: "",
-    // unused — isAction handles this
-    isAction: true
-  }
-];
-
-// src/index.ts
+// src/providers.ts
 var VALID_MODES = {
   copilot: ["extension"],
   "claude-code": ["extension", "cli"],
@@ -93,6 +17,8 @@ var DEFAULT_PROVIDER_MODE = {
   trae: "builtin",
   cursor: "builtin"
 };
+
+// src/api.ts
 var INSPECTO_API_PATHS = {
   HEALTH: "/inspecto/api/v1/health",
   CLIENT_CONFIG: "/inspecto/api/v1/client/config",
@@ -100,9 +26,55 @@ var INSPECTO_API_PATHS = {
   IDE_OPEN: "/inspecto/api/v1/ide/open",
   PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet",
   AI_DISPATCH: "/inspecto/api/v1/ai/dispatch",
+  AI_BATCH_DISPATCH: "/inspecto/api/v1/ai/dispatch/annotations",
   AI_TICKET: "/inspecto/api/v1/ai/ticket"
-  // Usage: /inspecto/api/v1/ai/ticket/:id
 };
+
+// src/intents.ts
+var DEFAULT_INTENTS = [
+  {
+    id: "explain",
+    label: "Explain",
+    aiIntent: "ask",
+    prompt: `Explain what this {{framework}} component from \`{{file}}\` (line {{line}}) does.
+
+Focus on:
+- its UI responsibility
+- key props, state, or side effects
+- any non-obvious logic worth noticing`
+  },
+  {
+    id: "fix-bug",
+    label: "Fix Bug",
+    aiIntent: "fix",
+    prompt: `Help fix a bug in this {{framework}} component from \`{{file}}\` (line {{line}}).
+
+Please:
+- identify the most likely root cause
+- explain why it happens
+- suggest the smallest safe fix
+
+If important context is missing, ask for it before proposing broader changes.`
+  },
+  {
+    id: "fix-ui",
+    label: "Fix UI",
+    aiIntent: "fix",
+    prompt: `Help fix a UI issue in this {{framework}} component from \`{{file}}\` (line {{line}}).
+
+Please review layout, spacing, overflow, alignment, layering, and visual consistency,
+then suggest fixes using the same styling approach already used in this codebase.`
+  },
+  {
+    id: "improve",
+    label: "Improve",
+    aiIntent: "review",
+    prompt: `Review this {{framework}} component from \`{{file}}\` (line {{line}}) and suggest practical improvements.
+
+Focus on readability, maintainability, and small structural cleanups.
+Keep behavior unchanged unless a change is clearly justified.`
+  }
+];
 export {
   DEFAULT_INTENTS,
   DEFAULT_PROVIDER_MODE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inspecto-dev/types",
-  "version": "0.2.0-alpha.4",
+  "version": "0.3.0",
   "description": "Shared TypeScript definitions for the Inspecto monorepo",
   "license": "MIT",
   "type": "module",