Pangular Inspector
On this page ▾
The symbols @pangular-inspector/devtools/plugin exports, generated from the package source.

@pangular-inspector/devtools/plugin

Import from @pangular-inspector/devtools/plugin. This page is generated from packages/devtools/src/plugin.ts and the files it re-exports. Run pnpm docs:api after you change the public API.

definePangularServerPlugin

Function. Source: packages/devtools/src/plugin.ts.

Types a server plugin. Returns it unchanged; the server checks it when it starts.

function definePangularServerPlugin(plugin: PangularServerPlugin): PangularServerPlugin;

PANGULAR_PLUGIN_API_VERSION

Constant. Source: packages/devtools/src/plugin.ts.

The plugin API version this package runs. A plugin that needs a later one is not run.

const PANGULAR_PLUGIN_API_VERSION: 1;

PangularPagePlugin

Interface. Source: packages/devtools/src/plugin.ts.

A plugin's page side.

interface PangularPagePlugin {
  /** Lowercase letters, digits and dashes, starting with a letter, such as `tanstack-query`. */
  id: string;
  /** The plugin's own version, shown in the panel. */
  version: string;
  /** The plugin API version it was written for. Defaults to 1. */
  apiVersion?: number;
  /** The name in the panel. Defaults to the id. */
  title?: string;
  description?: string;
  /** Runs once when the overlay starts the plugin; return a cleanup. */
  setup?(ctx: PangularPluginContext): void | (() => void);
  /** Returns the view to report. Called after Angular updates the page, while someone watches. */
  collect?(ctx: PangularPluginContext): PluginView | null | undefined;
  /**
   * Page actions, by name. They change the app, so `actions: false` (or
   * `plugins.<id>.actions: false`) in the devtools config blocks them.
   */
  actions?: Record<string, PangularPluginAction>;
}

PangularPluginAction

Type. Source: packages/devtools/src/plugin.ts.

A page action: runs on the page when the panel's button or a server plugin tool asks.

type PangularPluginAction = (args: unknown, ctx: PangularPluginContext) => unknown;

PangularPluginContext

Interface. Source: packages/devtools/src/plugin.ts.

What the overlay hands a page plugin.

interface PangularPluginContext {
  readonly apiVersion: number;
  /** The page id every report carries. */
  readonly pageId: string;
  /**
   * Whether a panel or an agent is watching. `collect` runs only while it is;
   * a `push` made meanwhile is sent once it is again.
   */
  readonly active: boolean;
  /** Angular's debug API (`window.ng`) in a development build, or `undefined`. */
  getNg(): Record<string, unknown> | undefined;
  /**
   * Reports a view without waiting for the next `collect`. It goes out about
   * 50 ms later, so a burst sends once; an unchanged view is skipped, and
   * while nobody watches it goes out once someone does.
   */
  push(view: PluginView): void;
  /**
   * Asks for a `collect`, such as after the plugin's store changed. It runs
   * while someone watches, at most once a second.
   */
  refresh(): void;
  /**
   * Makes a value safe to send: limits depth and size and masks secret-looking
   * names, JWTs and bearer tokens, like every other inspector. The overlay
   * runs it over every view too.
   */
  serialize(value: unknown, limits?: PluginSerializeLimits): unknown;
  /** Masks credentials, JWTs, bearer tokens and secret `key=value` pairs in a text. */
  redact(text: string): string;
  /** Whether a field name looks secret under the devtools config. */
  isSecretName(name: string): boolean;
}

PangularPluginPage

Interface. Source: packages/devtools/src/plugin.ts.

What a plugin page reported, as a server plugin reads it.

interface PangularPluginPage {
  pageId: string;
  url?: string;
  title?: string;
  /** When the page last reported, in ms since the epoch. */
  reportedAt: number;
  /** The page plugin's version. */
  version: string;
  /** The last view, already masked; `null` before the first one. */
  view: PluginView | null;
}

pangularPluginRegistry

Function. Source: packages/devtools/src/plugin.ts.

The registry on target, created on first use.

function pangularPluginRegistry(target: object = globalThis): PangularPluginRegistry;

PangularPluginRegistry

Interface. Source: packages/devtools/src/plugin.ts.

The global registry. Its shape is part of the API, since copies of this entry share it.

interface PangularPluginRegistry {
  api: number;
  plugins: PangularPagePlugin[];
  listeners: Set<() => void>;
}

PangularPluginTool

Interface. Source: packages/devtools/src/plugin.ts.

interface PangularPluginTool {
  /**
   * Lowercase letters, digits and dashes. The tool's id is
   * `pangular:plugin:<plugin id>:<name>`, which MCP clients call as
   * `pangular_plugin_<plugin id>_<name>`. That name can be at most 64
   * characters, so the plugin id and the tool name together at most 47; the
   * server skips a plugin with a longer one.
   */
  name: string;
  description: string;
  /** JSON Schema of the arguments object. */
  inputSchema?: Record<string, unknown>;
  /** Defaults to `read`. Anything else is dropped under `agent.readOnly` or with actions off. */
  safety?: PangularPluginToolSafety;
  handler(
    args: Record<string, unknown>,
    ctx: PangularPluginToolContext,
  ): string | {markdown: string} | Promise<string | {markdown: string}>;
}

PangularPluginToolContext

Interface. Source: packages/devtools/src/plugin.ts.

What a tool's handler gets. runPageAction refuses in read tools.

interface PangularPluginToolContext extends PangularServerPluginContext {
  /**
   * Runs one of the page plugin's `actions` on a page (`page`, or the newest)
   * and waits for its answer, up to `timeoutMs` (default 10000, at most 30000).
   * The page gives up after the same time and answers with a timeout.
   */
  runPageAction(
    name: string,
    args?: unknown,
    options?: {page?: string; timeoutMs?: number},
  ): Promise<PluginActionResult>;
}

PangularPluginToolSafety

Type. Source: packages/devtools/src/plugin.ts.

How much a tool can change. read tools only read; action tools change the running page until a reload; destructive ones can lose data.

type PangularPluginToolSafety = 'read' | 'action' | 'destructive';

PangularServerPlugin

Interface. Source: packages/devtools/src/plugin.ts.

A plugin's server side.

interface PangularServerPlugin {
  /** The same id as the page plugin. */
  id: string;
  version: string;
  apiVersion?: number;
  title?: string;
  description?: string;
  tools?: PangularPluginTool[];
  /** Creates the plugin's shared state with this value. */
  state?: {initialValue: unknown};
  /** Runs once when the devtools server starts; return a cleanup. */
  setup?(ctx: PangularServerPluginContext): void | (() => void);
}

PangularServerPluginContext

Interface. Source: packages/devtools/src/plugin.ts.

What a server plugin's setup and tools get.

interface PangularServerPluginContext {
  readonly pluginId: string;
  /** The pages that run this plugin, newest report first. */
  pages(): PangularPluginPage[];
  /** One page by id, or the newest without one. */
  page(pageId?: string): PangularPluginPage | undefined;
  /**
   * The plugin's shared state, `pangular:plugin.<id>`. Agents read it with
   * `devframe_state_read` while the plugin's tools are on.
   */
  state: {get(): unknown; set(value: unknown): void};
  serialize(value: unknown, limits?: PluginSerializeLimits): unknown;
  redact(text: string): string;
  /** A view as markdown, the way `pangular:inspect-plugin` writes it. */
  markdown(view: PluginView): string;
}

PluginActionResult

Interface. Source: packages/devtools/src/plugin.ts.

interface PluginActionResult {
  ok: boolean;
  /** The page that ran it. */
  pageId?: string;
  /** What the action returned, masked like other live values. */
  result?: unknown;
  error?: string;
}

PluginBadge

Interface. Source: packages/devtools/src/plugin-view.ts.

interface PluginBadge {
  label: string;
  tone?: PluginTone;
}

PluginCell

Type. Source: packages/devtools/src/plugin-view.ts.

A table cell: plain text or a number, or text with a tone.

type PluginCell = string | number | boolean | null | {text: string; tone?: PluginTone};

PluginListSection

Interface. Source: packages/devtools/src/plugin-view.ts.

interface PluginListSection {
  kind: 'list';
  title: string;
  items: {label: string; detail?: string; badge?: PluginBadge}[];
  empty?: string;
}

PluginSection

Type. Source: packages/devtools/src/plugin-view.ts.

type PluginSection =
  | PluginTableSection
  | PluginTreeSection
  | PluginListSection
  | PluginStatsSection
  | PluginTextSection;

PluginSerializeLimits

Interface. Source: packages/devtools/src/plugin.ts.

Limits a plugin can pass to serialize().

interface PluginSerializeLimits {
  depth?: number;
  keys?: number;
  items?: number;
  text?: number;
}

PluginStatsSection

Interface. Source: packages/devtools/src/plugin-view.ts.

interface PluginStatsSection {
  kind: 'stats';
  title: string;
  items: {label: string; value: string | number; tone?: PluginTone}[];
}

PluginTableSection

Interface. Source: packages/devtools/src/plugin-view.ts.

interface PluginTableSection {
  kind: 'table';
  title: string;
  columns: {key: string; label: string}[];
  rows: Record<string, PluginCell>[];
  /** Shown when `rows` is empty. */
  empty?: string;
}

PluginTextSection

Interface. Source: packages/devtools/src/plugin-view.ts.

interface PluginTextSection {
  kind: 'text';
  title: string;
  text: string;
}

PluginTone

Type. Source: packages/devtools/src/plugin-view.ts.

The tone of a badge, a stat or a table cell.

type PluginTone = 'ok' | 'warn' | 'danger' | 'accent' | 'neutral';

PluginTreeSection

Interface. Source: packages/devtools/src/plugin-view.ts.

A value shown as a tree of keys and values, folded past the first level.

interface PluginTreeSection {
  kind: 'tree';
  title: string;
  value: unknown;
}

PluginView

Interface. Source: packages/devtools/src/plugin-view.ts.

What a plugin reports for one page.

interface PluginView {
  /** One line under the plugin's title. */
  summary?: string;
  badges?: PluginBadge[];
  sections: PluginSection[];
  actions?: PluginViewAction[];
}

PluginViewAction

Interface. Source: packages/devtools/src/plugin-view.ts.

A button the panel shows for one of the plugin's page actions.

interface PluginViewAction {
  /** A key of the plugin's `actions`. */
  name: string;
  label: string;
  /** Asks before running, for actions that lose data. */
  confirm?: string;
}

registerPangularPlugin

Function. Source: packages/devtools/src/plugin.ts.

Registers a page plugin and returns a function that removes it. Registering the same id again replaces the plugin, as a hot reload does. Throws for an id that is not lowercase letters, digits and dashes, and warns about and drops an action whose name is not.

function registerPangularPlugin(plugin: PangularPagePlugin): () => void;
© 2026 Pangular Inspector contributors. Released under the MIT License.