react-inspector-devtools 0.0.0-stage → 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,158 @@
+import type { ComponentType } from 'react';
+export type BuiltInPanelId = 'elements' | 'console' | 'network' | 'application';
+export type PanelId = BuiltInPanelId | 'settings' | (string & {});
+export type DockPosition = 'bottom' | 'right' | 'floating';
+export type ThemeSetting = 'system' | 'light' | 'dark';
+export type ResolvedTheme = 'light' | 'dark';
+export interface InspectorOptions {
+    enableElementPicker?: boolean;
+    enableDeviceToolbar?: boolean;
+    enableConsole?: boolean;
+    enableNetwork?: boolean;
+    enableApplication?: boolean;
+    /** Emulate width/height media queries, matchMedia and window.innerWidth in device mode. Default true. */
+    emulateMediaQueries?: boolean;
+}
+export interface InspectorDevToolsProps {
+    /** Master switch. When false nothing is rendered and nothing is instrumented. Default true. */
+    enabled?: boolean;
+    /** Open the panel on first mount (persisted state wins afterwards). Default false. */
+    defaultOpen?: boolean;
+    /** Controlled open state. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    position?: DockPosition;
+    theme?: ThemeSetting;
+    /** Initial height when docked to the bottom (px). */
+    height?: number;
+    /** Initial width when docked to the right (px). */
+    width?: number;
+    /** Keyboard shortcut, e.g. "Ctrl+Shift+D". "Ctrl" also matches Cmd on macOS. Pass false to disable. */
+    shortcut?: string | false;
+    /** Built-in panels to show, in order. */
+    panels?: BuiltInPanelId[];
+    /** Additional custom panels. */
+    customPanels?: PanelDefinition[];
+    options?: InspectorOptions;
+    /** CSS selector or element for the app root used by the device toolbar. Auto-detected by default. */
+    target?: string | HTMLElement;
+    /** Show a small floating launcher button when the tools are closed. Default true. */
+    showLauncher?: boolean;
+    /** When docked, push page content aside instead of overlaying it. Default false. */
+    dockPushesContent?: boolean;
+    maxConsoleEntries?: number;
+    maxNetworkEntries?: number;
+    /** Requests whose URL matches are not recorded (e.g. HMR / analytics). */
+    ignoreUrls?: (string | RegExp)[];
+    /** z-index of the devtools layer. */
+    zIndex?: number;
+}
+export interface PanelDefinition {
+    id: string;
+    title: string;
+    icon?: ComponentType<{
+        size?: number;
+    }>;
+    component: ComponentType;
+    order?: number;
+}
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
+export type ConsoleEntryKind = 'log' | 'table' | 'group-start' | 'group-end' | 'trace' | 'exception' | 'rejection' | 'input' | 'result' | 'system';
+export interface ConsoleEntry {
+    id: number;
+    level: ConsoleLevel;
+    kind: ConsoleEntryKind;
+    /** The original console method, if any. */
+    method?: string;
+    args: unknown[];
+    timestamp: number;
+    stack?: string;
+    /** Indentation depth from console.group nesting. */
+    depth: number;
+    /** For group-start entries: whether the group starts collapsed. */
+    collapsed?: boolean;
+    /** Id of the enclosing group-start entry chain. */
+    groupPath: number[];
+    /** Number of identical consecutive messages collapsed into this one. */
+    repeat: number;
+    /** Source location, e.g. "app.tsx:12" */
+    source?: string;
+    /** Entry restored from a previous page load (args are plain strings). */
+    preserved?: boolean;
+    /** Columns for console.table */
+    columns?: string[];
+}
+export type ResourceType = 'fetch' | 'xhr' | 'js' | 'css' | 'doc' | 'font' | 'img' | 'media' | 'manifest' | 'ws' | 'other';
+export type RequestState = 'pending' | 'complete' | 'failed' | 'aborted';
+export type BodyState = 'none' | 'pending' | 'available' | 'truncated' | 'unavailable' | 'binary' | 'streaming';
+export interface RequestPayload {
+    kind: 'text' | 'json' | 'form' | 'urlencoded' | 'binary' | 'none' | 'unknown';
+    text?: string;
+    /** For form / urlencoded payloads */
+    fields?: [string, string][];
+    size?: number;
+}
+export interface WebSocketFrame {
+    direction: 'send' | 'receive';
+    data: string;
+    size: number;
+    time: number;
+    opcode: 'text' | 'binary';
+}
+export interface NetworkTiming {
+    startTime: number;
+    redirect?: number;
+    dns?: number;
+    connect?: number;
+    ssl?: number;
+    request?: number;
+    waiting?: number;
+    download?: number;
+    total?: number;
+}
+export interface NetworkRequest {
+    id: string;
+    url: string;
+    method: string;
+    type: ResourceType;
+    initiator: string;
+    /** Call-site stack of the initiator, if captured */
+    initiatorStack?: string;
+    state: RequestState;
+    status?: number;
+    statusText?: string;
+    requestHeaders: [string, string][];
+    responseHeaders: [string, string][];
+    payload?: RequestPayload;
+    responseBody?: string;
+    /** object URL for image previews */
+    responseObjectUrl?: string;
+    bodyState: BodyState;
+    mimeType?: string;
+    /** performance.now() based */
+    startTime: number;
+    endTime?: number;
+    /** Date.now() based */
+    wallTime: number;
+    requestSize?: number;
+    responseSize?: number;
+    transferSize?: number;
+    fromCache?: boolean;
+    timing?: NetworkTiming;
+    error?: string;
+    responseType?: string;
+    redirected?: boolean;
+    frames?: WebSocketFrame[];
+    preserved?: boolean;
+}
+export interface DevicePreset {
+    id: string;
+    name: string;
+    width: number;
+    height: number;
+    dpr: number;
+    category: 'mobile' | 'tablet' | 'desktop' | 'custom';
+    touch?: boolean;
+    userAgent?: string;
+}
+export type StorageArea = 'local' | 'session';

package/dist/utils/cookies.d.ts

@@ -0,0 +1,32 @@
+export interface CookieRecord {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    /** epoch ms, or undefined for session cookies / unknown */
+    expires?: number;
+    size: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    partitioned?: boolean;
+    /** Which attributes could actually be read from the browser. */
+    source: 'document.cookie' | 'cookieStore';
+}
+/** Parses a document.cookie string. Only name/value are available through this API. */
+export declare function parseDocumentCookie(str: string): CookieRecord[];
+export interface CookieWrite {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+    expires?: number | null;
+    maxAge?: number | null;
+    secure?: boolean;
+    sameSite?: string;
+}
+export declare function serializeCookie(c: CookieWrite): string;
+export declare function readCookies(): Promise<CookieRecord[]>;
+export declare function writeCookie(c: CookieWrite): void;
+/** Deletes a cookie, trying the provided path/domain plus common fallbacks. */
+export declare function deleteCookie(name: string, path?: string, domain?: string): void;

package/dist/utils/domSelector.d.ts

@@ -0,0 +1,4 @@
+/** Builds a reasonably short unique CSS selector for an element. */
+export declare function cssPath(el: Element): string;
+/** Short label like div#app.container.main */
+export declare function elementLabel(el: Element, maxClasses?: number): string;

package/dist/utils/format.d.ts

@@ -0,0 +1,15 @@
+export declare function formatBytes(bytes: number | undefined | null): string;
+export declare function formatDuration(ms: number | undefined | null): string;
+export declare function formatClock(ts: number): string;
+export declare function byteLength(str: string): number;
+export declare function truncate(str: string, max: number): string;
+export declare function tryParseJSON(text: string | undefined): {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+};
+export declare function clamp(n: number, min: number, max: number): number;
+/** Extracts "file.js:12" from a stack line. */
+export declare function sourceFromStack(stack: string | undefined, skip?: number): string | undefined;
+export declare const nextId: (prefix?: string) => string;

package/dist/utils/mediaQuery.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A small media query evaluator used by the device toolbar to emulate
+ * viewport-dependent media queries against a virtual viewport.
+ *
+ * Features that do not depend on the viewport (prefers-color-scheme, etc.)
+ * are delegated to the real `matchMedia` through the `fallback` callback.
+ */
+export interface MediaEnv {
+    width: number;
+    height: number;
+    dpr: number;
+    touch: boolean;
+}
+export declare const VIEWPORT_FEATURE_RE: RegExp;
+export declare function dependsOnViewport(query: string): boolean;
+type Fallback = (query: string) => boolean;
+export declare function evaluateMediaQueryList(text: string, env: MediaEnv, fallback: Fallback): boolean;
+export declare function evaluateFeature(inner: string, env: MediaEnv, fallback: Fallback): boolean;
+export {};

package/dist/utils/safeStorage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Storage helpers that use the *original* Storage methods so devtools' own
+ * persistence never shows up as application activity.
+ */
+export declare const INTERNAL_PREFIX = "__rid_";
+/** Must be called before any Storage patching so we keep the real methods. */
+export declare function captureStorageOriginals(): void;
+export declare function readInternal<T>(key: string, fallback: T, kind?: 'local' | 'session'): T;
+export declare function writeInternal(key: string, value: unknown, kind?: 'local' | 'session'): void;
+export declare function isInternalKey(key: string): boolean;

package/dist/utils/shortcut.d.ts

@@ -0,0 +1,15 @@
+export interface ParsedShortcut {
+    key: string;
+    ctrlOrMeta: boolean;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    alt: boolean;
+}
+/**
+ * Parses strings like "Ctrl+Shift+D", "Cmd+Alt+I", "Mod+K".
+ * "Ctrl" and "Mod" match either Ctrl or Cmd (macOS), mirroring Chrome DevTools conventions.
+ */
+export declare function parseShortcut(input: string): ParsedShortcut | null;
+export declare function matchesShortcut(e: KeyboardEvent, s: ParsedShortcut): boolean;
+export declare function formatShortcut(input: string): string;

package/dist/utils/specificity.d.ts

@@ -0,0 +1,6 @@
+export type Specificity = [number, number, number];
+/** Splits a selector list on top-level commas. */
+export declare function splitSelectorList(selector: string): string[];
+/** Approximate CSS specificity calculation (Selectors Level 4). */
+export declare function specificity(selector: string): Specificity;
+export declare function compareSpecificity(x: Specificity, y: Specificity): number;

package/dist/utils/stack.d.ts

@@ -0,0 +1,2 @@
+/** Current call stack with devtools-internal frames removed. */
+export declare function callerStack(max?: number): string | undefined;

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "react-inspector-devtools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Embeddable Chrome DevTools-style developer tools for React applications: Elements, Console, Network, Application and Device Toolbar.",
+  "keywords": [
+    "react",
+    "devtools",
+    "inspector",
+    "debugger",
+    "console",
+    "network",
+    "dom",
+    "chrome-devtools"
+  ],
+  "license": "MIT",
+  "author": "Faizan Pinjari <fznpnjr4@gmail.com>",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "dev": "vite build --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "dependencies": {
+    "zustand": "^5.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.0",
+    "jsdom": "^27.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": "^8.0.0",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}