Inspector

Use @azlib/inspector to diagnose UI performance issues during local development and map findings back to the most useful available code location.

Install one plugin. Option/Alt-click in the running app opens the matching source file in the editor that started the project. No route handlers, no client bootstrap, and no editor-launch code in the app.

Capabilities

• Bounded inspection sessions around one interaction, region, or time window
• Ranked findings with evidence and severity
• Exact, approximate, or unavailable source locations without overstating precision
• React-specific enrichment through an optional adapter
• Framework-agnostic DOM inspection through browser-native performance signals
• Vite, Webpack, and Next.js source hint injection configured from the consumer bundler
• Option/Alt-click source picker that highlights annotated DOM nodes and opens the file
• Node helper that opens the file in the editor that started the project and brings that app to the front

Plug and play

// vite.config.ts
import { defineConfig } from "vite";
import { inspectorVitePlugin } from "@azlib/inspector/vite";

export default defineConfig({
  plugins: [inspectorVitePlugin()],
});

// next.config.ts
import { withInspector } from "@azlib/inspector/next";

const nextConfig = {/* existing Next.js config */};

export default withInspector(nextConfig);

// webpack.config.cjs
const { inspectorWebpackPlugin } = require("@azlib/inspector/webpack");

module.exports = {
  plugins: [inspectorWebpackPlugin()],
};

Hold Option (macOS) or Alt (Windows/Linux) to highlight the nearest annotated element, then click to open it. The picker listens on pointerdown as well as click, because macOS can drop altKey and fire Alt keyup before the click reaches the page.

The plugin is development-only: Vite applies it during serve, Next.js wraps config when NODE_ENV is not production, and Webpack can pass { enabled: false }.

AI Agent Quick Reference

Core Exports

| Export | Type | Description | | --------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | createInspector(config?: InspectorConfig, adapters?: InspectionAdapter[]): InspectorInstance | Function | Instantiates the core UI performance diagnostic inspector. | | createReactInspectionAdapter(options: ReactAdapterOptions): InspectionAdapter | Function | Enriches findings with React-specific render durations and components metadata. | | createDomInspectionAdapter(options: DomAdapterOptions): InspectionAdapter | Function | Emits framework-neutral findings based on Long Tasks and DOM element layouts. | | readElementSourceHint(element: HTMLElement): SourceHint \| null | Function | Programmatically extracts injected build-time source hints from a DOM element. | | findNearestElementSourceHint(target: EventTarget \| null, attributeName?: string): SourcePickerTarget \| undefined | Function | Walks up from a DOM event target to the nearest element with an injected source hint. | | startSourcePicker(options?: SourcePickerOptions): () => void | Function | Installs a development overlay so Option/Alt-click can open the nearest annotated source location. Host plugins call this automatically. | | createSourcePickerEditorUrl(hint: SourceLocationMetadata, options?: { protocol?: "vscode" \| "cursor"; root?: string }): string | Function | Builds a vscode:// or cursor:// URL for a source hint. | | createSourcePickerFetchOpener(endpoint?: string): (target: SourcePickerTarget) => Promise<void> | Function | Builds an onOpen handler that requests a host open-source endpoint. Defaults to /__azlib/open-source. | | inspectorVitePlugin(options?: InspectorVitePluginOptions) from @azlib/inspector/vite | Function | Vite development plugin: source hints, picker bootstrap, and /__azlib/open-source middleware. | | inspectorWebpackPlugin(options?: InspectorWebpackPluginOptions) from @azlib/inspector/webpack | Function | Webpack plugin: source hints, picker entry, and webpack-dev-server open-source middleware. | | withInspector(nextConfig, options?) from @azlib/inspector/next | Function | Next.js config wrapper: Turbopack/Webpack source hints, client instrumentation, and open-source rewrite. | | openInProjectEditor(input) from @azlib/inspector/node | Function | Opens a project file through the editor URL scheme (cursor://file/...) so the running app jumps to the line without waiting on the cursor/code CLI handshake. | | createOpenSourceRequestHandler(options?) from @azlib/inspector/node | Function | Web Request → Response handler for a host /open-source route. Used by the plugins; apps do not need to mount it. |

Core Types & Configuration

• InspectorInstance:
  • startInspection(options: InspectionOptions): InspectionSession
  • stopInspection(session: InspectionSession): InspectionResult
• InspectionOptions:
  • targetKind: "dom" | "react" | "all"
  • scope?: InspectionScope
• InspectionScope:
  • mode: "full-surface" | "region" | "interaction" | "time-window"
  • regionHint?: string (CSS selector for target container element)
• SourceHintOptions:
  • attributeName?: string (defaults to data-azlib-inspector-source)
  • include?: RegExp
• SourcePickerOptions:
  • onOpen?: (target: SourcePickerTarget) => void | Promise<void>
  • formatEditorUrl?: (hint: SourceLocationMetadata) => string
  • enabled?: boolean

Basic Usage

import { createInspector } from "@azlib/inspector";

const inspector = createInspector();

// Start a targeted performance checking session
const session = inspector.startInspection({
  targetKind: "dom",
  scope: { mode: "region", regionHint: "#results-grid" },
});

// Perform UI interactions here...

const result = inspector.stopInspection(session);
if (result.status === "findings-reported") {
  console.log("Performance issues identified:", result.findings);
}

Optional overrides

The plugins already start the picker and open files. Use these only when a host cannot install a bundler plugin:

import { startSourcePicker } from "@azlib/inspector";

startSourcePicker(); // fetches /__azlib/open-source

import { createOpenSourceRequestHandler } from "@azlib/inspector/node";

export const GET = createOpenSourceRequestHandler({
  enabled: () => process.env.NODE_ENV === "development",
});

import {
  createSourcePickerEditorUrl,
  startSourcePicker,
} from "@azlib/inspector";

startSourcePicker({
  formatEditorUrl: (hint) =>
    createSourcePickerEditorUrl(hint, {
      protocol: "cursor",
      root: "/absolute/app/root",
    }),
});

Behavioral Gotchas

• Approximate DOM Source Hints: Injected DOM attributes identify the closest rendering wrapper element, not the exact line of JavaScript executing the slow calculation.
• Third-Party Code Isolation: Heavy script runs from third-party scripts (e.g. analytics widgets) will report an ownership value of third-party, and their source location values will be null.
• Empty Scopes Outcome: If a session finishes and no performance samples match the designated scope boundary, the returned status is no-findings rather than a success status with an empty array.
• Development-Only Usage: This package is designed exclusively for development/staging environments and should be omitted from production builds.