@inspecto-dev/types 0.2.0-alpha.0 → 0.2.0-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inspecto Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
-# @inspecto/types
+# @inspecto-dev/types
 
-`@inspecto/types` contains all shared TypeScript definitions for the Inspecto monorepo.
+`@inspecto-dev/types` contains all shared TypeScript definitions for the Inspecto monorepo.
 
 ## Overview
 
@@ -9,6 +9,6 @@ This package serves as the single source of truth for all types and interfaces u
 ## Core Implementation
 
 - **Protocol Types**: Defines the request/response shapes for the local HTTP server (`OpenFileRequest`, `SnippetResponse`, `SendToAiRequest`).
-- **Configuration Types**: Defines the user configuration structure (`InspectoUserConfig`, `UnpluginOptions`, `InspectorOptions`).
-- **Domain Models**: Contains definitions for AI targets (`AiTool`), tool modes (`ToolMode`), and IDE types (`IdeType`).
+- **Configuration Types**: Defines the user configuration structure (`InspectoSettings`, `UnpluginOptions`, `InspectorOptions`).
+- **Domain Models**: Contains definitions for AI targets (`Provider`), tool modes (`ProviderMode`), and IDE types (`IdeType`).
 - **Constants**: Provides shared constants like `DEFAULT_INTENTS` and tool mode mappings to keep behavior consistent across packages.

package/dist/index.cjs

@@ -20,35 +20,122 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  AI_TARGET_TYPE: () => AI_TARGET_TYPE,
-  DEFAULT_TOOL_MODE: () => DEFAULT_TOOL_MODE,
+  DEFAULT_INTENTS: () => DEFAULT_INTENTS,
+  DEFAULT_PROVIDER_MODE: () => DEFAULT_PROVIDER_MODE,
+  INSPECTO_API_PATHS: () => INSPECTO_API_PATHS,
   VALID_MODES: () => VALID_MODES
 });
 module.exports = __toCommonJS(index_exports);
-var AI_TARGET_TYPE = {
-  "github-copilot": "plugin",
-  "claude-code": "plugin",
-  gemini: "plugin",
-  codex: "plugin",
-  coco: "cli"
+
+// 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
+var VALID_MODES = {
+  copilot: ["extension"],
+  "claude-code": ["extension", "cli"],
+  gemini: ["extension", "cli"],
+  codex: ["extension", "cli"],
+  coco: ["cli"],
+  trae: ["builtin"],
+  cursor: ["builtin"]
 };
-var DEFAULT_TOOL_MODE = {
-  "github-copilot": "plugin",
-  "claude-code": "plugin",
-  gemini: "plugin",
-  codex: "plugin",
-  coco: "cli"
+var DEFAULT_PROVIDER_MODE = {
+  copilot: "extension",
+  "claude-code": "extension",
+  gemini: "extension",
+  codex: "extension",
+  coco: "cli",
+  trae: "builtin",
+  cursor: "builtin"
 };
-var VALID_MODES = {
-  "github-copilot": ["plugin"],
-  "claude-code": ["plugin", "cli"],
-  gemini: ["plugin", "cli"],
-  codex: ["plugin", "cli"],
-  coco: ["cli"]
+var INSPECTO_API_PATHS = {
+  HEALTH: "/inspecto/api/v1/health",
+  CLIENT_CONFIG: "/inspecto/api/v1/client/config",
+  IDE_INFO: "/inspecto/api/v1/ide/info",
+  IDE_OPEN: "/inspecto/api/v1/ide/open",
+  PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet",
+  AI_DISPATCH: "/inspecto/api/v1/ai/dispatch",
+  AI_TICKET: "/inspecto/api/v1/ai/ticket"
+  // Usage: /inspecto/api/v1/ai/ticket/:id
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AI_TARGET_TYPE,
-  DEFAULT_TOOL_MODE,
+  DEFAULT_INTENTS,
+  DEFAULT_PROVIDER_MODE,
+  INSPECTO_API_PATHS,
   VALID_MODES
 });

package/dist/index.d.cts

@@ -1,13 +1,28 @@
+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.
- * - Array of HotKey: all specified keys must be held simultaneously to activate
- * - false: disable hotkey activation entirely (use programmatic toggle only)
- * @default ['altKey']
- * @example ['ctrlKey', 'shiftKey'] — Ctrl+Shift to activate
+ * - String: modifier key or combo (e.g., "alt", "cmd+shift")
+ * - false: disable hotkey activation entirely
  */
-type HotKeys = HotKey[] | false;
+type HotKeys = HotKeyString | false;
 /** Parsed source location from the data-inspecto attribute */
 interface SourceLocation {
     /** Absolute or relative file path depending on pathType config */
@@ -27,7 +42,7 @@ type SourceAttrValue = string;
  * - 'relative': path relative to project root — shorter, but may break with pnpm virtual store
  */
 type PathType = 'relative' | 'absolute';
-/** Configuration for the @inspecto/plugin build plugin */
+/** Configuration for the @inspecto-dev/plugin build plugin */
 interface UnpluginOptions {
     /**
      * Additional file extensions to transform beyond .jsx/.tsx/.js/.ts
@@ -61,71 +76,69 @@ interface UnpluginOptions {
      * @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' | 'unknown';
-/** All supported AI tools */
-type AiTool = 'github-copilot' | 'claude-code' | 'gemini' | 'codex' | 'coco';
-/** Backward compatibility alias */
-type AiTarget = AiTool;
-/** Whether the AI target is an editor plugin or a CLI tool */
-type ToolMode = 'plugin' | 'cli' | 'clipboard';
-/** Backward compatibility alias */
-type AiTargetType = ToolMode;
-interface ProviderConfig {
-    type?: ToolMode;
-    autoSend?: boolean;
-    bin?: string;
-    args?: string[];
-    cwd?: string;
-}
+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;
-    prefer?: string;
-    hotKeys?: HotKeys;
-    providers?: Record<string, ProviderConfig>;
+    /** 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).
      */
-    includeSnippet?: boolean;
-}
-/** Legacy configuration structure (for backward compatibility during migration) */
-interface LegacyInspectoUserConfig {
-    defaultTarget?: AiTool;
-    tools: Partial<Record<AiTool, {
-        mode: ToolMode;
-        cliBinary?: string;
-        cliArgs?: string[];
-    }>>;
-    menuOrder?: AiTool[];
+    '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;
 }
-/** Static mapping: target → type (DEPRECATED: Use config resolution instead) */
-declare const AI_TARGET_TYPE: Record<AiTool, ToolMode>;
-declare const DEFAULT_TOOL_MODE: Record<AiTool, ToolMode>;
-/** Which modes each tool actually supports */
-declare const VALID_MODES: Record<AiTool, ToolMode[]>;
+/** 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 {
-    type?: ToolMode;
+    type?: ProviderMode;
     binaryPath?: string;
     args?: string[];
     cwd?: string;
-    autoSend?: boolean;
     coldStartDelay?: number;
 }
 interface AiPayload {
     ide: IdeType;
-    target: AiTarget;
-    targetType: AiTargetType;
+    target: Provider;
+    targetType: ProviderMode;
     prompt: string;
     filePath?: string;
     line?: number;
     column?: number;
     snippet?: string;
     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: ToolMode;
+    type: ProviderMode;
     execute: (payload: AiPayload) => Promise<void>;
 }
 interface IntentLabels {
@@ -215,6 +228,16 @@ interface InspectorOptions {
      */
     includeSnippet?: boolean;
 }
+
+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 */
 interface OpenFileRequest {
     file: string;
@@ -253,25 +276,33 @@ interface SendToAiResponse {
     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;
+    };
 }
 /** 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: ToolMode;
+    mode: ProviderMode;
     installed: boolean;
 }
 interface IdeInfo {
     ide: IdeType;
     scheme: string;
-    providers: Record<AiTool, ProviderInfo>;
+    workspaceRoot?: string;
+    providers: Record<Provider, ProviderInfo>;
 }
 /** GET /config response — browser-facing runtime configuration */
 interface InspectoConfig {
     ide: IdeType;
-    providers: Record<AiTool, ProviderInfo>;
-    providerOverrides?: Partial<Record<AiTool, ToolOverrides>>;
-    prompts?: InspectoPromptsConfig;
+    /** 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;
 }
 /** Shared mutable state managed by the local HTTP server module */
@@ -305,4 +336,4 @@ interface AiStrategyResult {
     errorCode?: AiErrorCode;
 }
 
-export { AI_TARGET_TYPE, type AiErrorCode, type AiPayload, type AiStrategyContext, type AiStrategyResult, type AiTarget, type AiTargetType, type AiTool, type ChannelDef, DEFAULT_TOOL_MODE, type HotKey, type HotKeys, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentLabels, type LegacyInspectoUserConfig, type OpenFileRequest, type PathType, type ProviderConfig, type ProviderInfo, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolMode, type ToolOverrides, type UnpluginOptions, VALID_MODES };
+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 };

package/dist/index.d.ts

@@ -1,13 +1,28 @@
+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.
- * - Array of HotKey: all specified keys must be held simultaneously to activate
- * - false: disable hotkey activation entirely (use programmatic toggle only)
- * @default ['altKey']
- * @example ['ctrlKey', 'shiftKey'] — Ctrl+Shift to activate
+ * - String: modifier key or combo (e.g., "alt", "cmd+shift")
+ * - false: disable hotkey activation entirely
  */
-type HotKeys = HotKey[] | false;
+type HotKeys = HotKeyString | false;
 /** Parsed source location from the data-inspecto attribute */
 interface SourceLocation {
     /** Absolute or relative file path depending on pathType config */
@@ -27,7 +42,7 @@ type SourceAttrValue = string;
  * - 'relative': path relative to project root — shorter, but may break with pnpm virtual store
  */
 type PathType = 'relative' | 'absolute';
-/** Configuration for the @inspecto/plugin build plugin */
+/** Configuration for the @inspecto-dev/plugin build plugin */
 interface UnpluginOptions {
     /**
      * Additional file extensions to transform beyond .jsx/.tsx/.js/.ts
@@ -61,71 +76,69 @@ interface UnpluginOptions {
      * @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' | 'unknown';
-/** All supported AI tools */
-type AiTool = 'github-copilot' | 'claude-code' | 'gemini' | 'codex' | 'coco';
-/** Backward compatibility alias */
-type AiTarget = AiTool;
-/** Whether the AI target is an editor plugin or a CLI tool */
-type ToolMode = 'plugin' | 'cli' | 'clipboard';
-/** Backward compatibility alias */
-type AiTargetType = ToolMode;
-interface ProviderConfig {
-    type?: ToolMode;
-    autoSend?: boolean;
-    bin?: string;
-    args?: string[];
-    cwd?: string;
-}
+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;
-    prefer?: string;
-    hotKeys?: HotKeys;
-    providers?: Record<string, ProviderConfig>;
+    /** 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).
      */
-    includeSnippet?: boolean;
-}
-/** Legacy configuration structure (for backward compatibility during migration) */
-interface LegacyInspectoUserConfig {
-    defaultTarget?: AiTool;
-    tools: Partial<Record<AiTool, {
-        mode: ToolMode;
-        cliBinary?: string;
-        cliArgs?: string[];
-    }>>;
-    menuOrder?: AiTool[];
+    '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;
 }
-/** Static mapping: target → type (DEPRECATED: Use config resolution instead) */
-declare const AI_TARGET_TYPE: Record<AiTool, ToolMode>;
-declare const DEFAULT_TOOL_MODE: Record<AiTool, ToolMode>;
-/** Which modes each tool actually supports */
-declare const VALID_MODES: Record<AiTool, ToolMode[]>;
+/** 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 {
-    type?: ToolMode;
+    type?: ProviderMode;
     binaryPath?: string;
     args?: string[];
     cwd?: string;
-    autoSend?: boolean;
     coldStartDelay?: number;
 }
 interface AiPayload {
     ide: IdeType;
-    target: AiTarget;
-    targetType: AiTargetType;
+    target: Provider;
+    targetType: ProviderMode;
     prompt: string;
     filePath?: string;
     line?: number;
     column?: number;
     snippet?: string;
     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: ToolMode;
+    type: ProviderMode;
     execute: (payload: AiPayload) => Promise<void>;
 }
 interface IntentLabels {
@@ -215,6 +228,16 @@ interface InspectorOptions {
      */
     includeSnippet?: boolean;
 }
+
+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 */
 interface OpenFileRequest {
     file: string;
@@ -253,25 +276,33 @@ interface SendToAiResponse {
     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;
+    };
 }
 /** 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: ToolMode;
+    mode: ProviderMode;
     installed: boolean;
 }
 interface IdeInfo {
     ide: IdeType;
     scheme: string;
-    providers: Record<AiTool, ProviderInfo>;
+    workspaceRoot?: string;
+    providers: Record<Provider, ProviderInfo>;
 }
 /** GET /config response — browser-facing runtime configuration */
 interface InspectoConfig {
     ide: IdeType;
-    providers: Record<AiTool, ProviderInfo>;
-    providerOverrides?: Partial<Record<AiTool, ToolOverrides>>;
-    prompts?: InspectoPromptsConfig;
+    /** 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;
 }
 /** Shared mutable state managed by the local HTTP server module */
@@ -305,4 +336,4 @@ interface AiStrategyResult {
     errorCode?: AiErrorCode;
 }
 
-export { AI_TARGET_TYPE, type AiErrorCode, type AiPayload, type AiStrategyContext, type AiStrategyResult, type AiTarget, type AiTargetType, type AiTool, type ChannelDef, DEFAULT_TOOL_MODE, type HotKey, type HotKeys, type IdeInfo, type IdeType, type InspectoConfig, type InspectoPromptsConfig, type InspectoSettings, type InspectorOptions, type IntentConfig, type IntentLabels, type LegacyInspectoUserConfig, type OpenFileRequest, type PathType, type ProviderConfig, type ProviderInfo, type SendToAiRequest, type SendToAiResponse, type ServerState, type SnippetRequest, type SnippetResponse, type SourceAttrValue, type SourceLocation, type ToolMode, type ToolOverrides, type UnpluginOptions, VALID_MODES };
+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 };

package/dist/index.js

@@ -1,27 +1,111 @@
+// 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
-var AI_TARGET_TYPE = {
-  "github-copilot": "plugin",
-  "claude-code": "plugin",
-  gemini: "plugin",
-  codex: "plugin",
-  coco: "cli"
+var VALID_MODES = {
+  copilot: ["extension"],
+  "claude-code": ["extension", "cli"],
+  gemini: ["extension", "cli"],
+  codex: ["extension", "cli"],
+  coco: ["cli"],
+  trae: ["builtin"],
+  cursor: ["builtin"]
 };
-var DEFAULT_TOOL_MODE = {
-  "github-copilot": "plugin",
-  "claude-code": "plugin",
-  gemini: "plugin",
-  codex: "plugin",
-  coco: "cli"
+var DEFAULT_PROVIDER_MODE = {
+  copilot: "extension",
+  "claude-code": "extension",
+  gemini: "extension",
+  codex: "extension",
+  coco: "cli",
+  trae: "builtin",
+  cursor: "builtin"
 };
-var VALID_MODES = {
-  "github-copilot": ["plugin"],
-  "claude-code": ["plugin", "cli"],
-  gemini: ["plugin", "cli"],
-  codex: ["plugin", "cli"],
-  coco: ["cli"]
+var INSPECTO_API_PATHS = {
+  HEALTH: "/inspecto/api/v1/health",
+  CLIENT_CONFIG: "/inspecto/api/v1/client/config",
+  IDE_INFO: "/inspecto/api/v1/ide/info",
+  IDE_OPEN: "/inspecto/api/v1/ide/open",
+  PROJECT_SNIPPET: "/inspecto/api/v1/project/snippet",
+  AI_DISPATCH: "/inspecto/api/v1/ai/dispatch",
+  AI_TICKET: "/inspecto/api/v1/ai/ticket"
+  // Usage: /inspecto/api/v1/ai/ticket/:id
 };
 export {
-  AI_TARGET_TYPE,
-  DEFAULT_TOOL_MODE,
+  DEFAULT_INTENTS,
+  DEFAULT_PROVIDER_MODE,
+  INSPECTO_API_PATHS,
   VALID_MODES
 };

package/package.json

@@ -1,12 +1,9 @@
 {
   "name": "@inspecto-dev/types",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.2",
   "description": "Shared TypeScript definitions for the Inspecto monorepo",
   "license": "MIT",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/inspecto-dev/inspecto.git",
@@ -36,10 +33,17 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"
   }
-}
+}