@monkey2582/thinconsole 1.3.5 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monkey2582/thinconsole",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "thinConsole是一个轻量级、功能丰富的浏览器端 JavaScript 控制台增强库。它提供了一个可浮动的按钮，点击后可以展开一个功能强大的控制台面板，用于捕获和查看日志、管理本地存储（LocalStorage）、记录系统事件，并支持通过插件系统进行扩展。",
   "keywords": [
     "console",

package/thinConsole.d.ts

@@ -1,175 +1,110 @@
-// Type definitions for thinConsole v1.3.5
-// Project: thinConsole - A lightweight mobile web debugging console
-// UMD module: supports CommonJS, AMD, and global (browser window.thinConsole)
-
-// Class + namespace merge: class provides the value & constructor,
-// namespace provides additional types accessible as thinConsole.X
-declare class thinConsole {
-  constructor(options?: thinConsole.Options);
-
-  // ---- Instance properties ----
-  version: string;
-  options: Required<
-    Omit<thinConsole.Options, "filters"> & { filters: thinConsole.Filter[] | null }
-  >;
-  currentTab: string;
-  currentTheme: "light" | "dark";
-  selectedElement: Node | null;
-  logs: thinConsole.LogEntry[];
-  networkRequests: thinConsole.NetworkRequest[];
-  maxLog: number;
-  /** Maximum number of network requests to retain (default: 1000) */
-  maxNetwork: number;
-
-  // ---- Instance methods ----
-  show(tab?: string): thinConsole;
-  hide(): thinConsole;
-  destroy(): void;
-  switchTab(tab: string): void;
-  showNotification(message: string, type?: string): void;
-  toggleSearch(visible?: boolean): void;
-  toggleMute(): void;
-  clearAllLogs(silent?: boolean): void;
-  startElementPicker(): void;
-  deleteElement(element: Node): void;
-  copyElementHTML(element: Element): void;
-  expandToElement(element: Node): void;
-  getShadowRoot(element: Element): thinConsole.ShadowRootInfo | null;
-  registerPlugin(id: string, pluginClass: any, config?: any): thinConsole;
-  disablePlugin(id: string): thinConsole;
-  enablePlugin(id: string): thinConsole;
-  destroyPlugin(id: string): void;
-  triggerGlobalHook(name: thinConsole.HookName, ...args: any[]): thinConsole;
-  renderJSONTree(
-    obj: any,
-    key?: string,
-    path?: string,
-    chain?: any[],
-    noProto?: boolean
-  ): string;
-  renderHTMLTree(
-    element: Node,
-    key?: string,
-    path?: string,
-    depth?: number
-  ): string;
-  renderElementTree(element: Node, depth: number): string;
-  escapeHtml(str: string): string;
-  captureConsole(type: string, ...args: any[]): void;
+/**
+ * thinConsole - A lightweight web debugging console
+ * @version 1.3.7
+ */
 
-  /**
-   * Format a count number into compact display.
-   * - <= 999: returns the number as-is
-   * - 1000-99999: returns K format with 1 decimal (e.g. "1K", "1.1K")
-   * - >= 100000: returns "XK+" (e.g. "100K+")
-   * @param n The exact count
-   * @param plusK If true, append "+" for K values (used by network/storage)
-   * @returns Object with filterCount (display string/number) and exactCount (raw number)
-   */
-  _fmtCount(n: number, plusK?: boolean): thinConsole.FilterCountResult;
+declare namespace thinConsole {
 
-  /**
-   * Unified filter count updater for both built-in (console) and plugin tabs.
-   * @param container Filter button container (filterButtons or plugin view container)
-   * @param counts Count lookup object (type -> number | FilterCountResult)
-   * @param isPlugin If true, use plugin rendering (icon + orig); else console (cached HTML)
-   */
-  _updateFilterCounts(
-    container: HTMLElement | NodeListOf<Element> | null,
-    counts: Record<string, number | thinConsole.FilterCountResult> | null,
-    isPlugin: boolean
-  ): void;
-
-  // ---- Static properties ----
-  static readonly version: string;
-  static tC: thinConsole | null;
-  static plugins: Record<string, any>;
-  static hooks: Record<thinConsole.HookName, thinConsole.HookCallback[]>;
-
-  // ---- Static methods ----
-  static show(tab?: string): typeof thinConsole;
-  static hide(): typeof thinConsole;
-  static destroy(): void;
-  static log(...args: any[]): typeof thinConsole;
-  static info(...args: any[]): typeof thinConsole;
-  static warn(...args: any[]): typeof thinConsole;
-  static error(...args: any[]): typeof thinConsole;
-  static addPlugin(id: string, pluginClass: any, config?: any): typeof thinConsole;
-  static addTabs(
-    tabs: thinConsole.TabConfig | thinConsole.TabConfig[]
-  ): typeof thinConsole;
-  static addHook(
-    name: thinConsole.HookName,
-    callback: thinConsole.HookCallback
-  ): typeof thinConsole;
-  static removeHook(
-    name: thinConsole.HookName,
-    callback: thinConsole.HookCallback
-  ): typeof thinConsole;
-  static setFilterCounts(
-    counts: Record<string, number | thinConsole.FilterCountResult>
-  ): typeof thinConsole;
-}
+  /** Position configuration for the floating button */
+  interface Position {
+    x: number;
+    y: number;
+  }
 
-declare namespace thinConsole {
-  // ============= Options & Config =============
+  /** Custom filter configuration */
+  interface FilterConfig {
+    id: string;
+    name: string;
+  }
 
+  /** Constructor options */
   interface Options {
-    /** Button text (max 11 chars, no HTML special chars) */
+    /** Button text (max 11 chars, default "thinConsole") */
     text?: string;
-    /** Button background color */
+    /** Button background color (default "#007aff") */
     color?: string;
-    /** Button width (CSS value) */
+    /** Button width (default "auto") */
     width?: string;
-    /** Button height (CSS value) */
+    /** Button height (default "auto") */
     height?: string;
-    /** Theme mode */
-    theme?: "light" | "dark" | "auto";
-    /** Enable plugin system */
+    /** Theme: "light", "dark", "auto", or custom theme name (default "auto") */
+    theme?: string;
+    /** Enable plugins (default true) */
     plugins?: boolean;
-    /** List of disabled plugin IDs */
+    /** List of disabled plugin names (default []) */
     disabledPlugins?: string[];
-    /** Enable JS code execution via title click */
+    /** Enable JS execution (default true) */
     jsExecute?: boolean;
-    /** Floating button position */
-    pos?: { x: number; y: number };
-    /** Maximum number of log entries to retain (default: 1000) */
+    /** Button position, null = saved/dragged (default null) */
+    pos?: Position | null;
+    /** Max number of log entries (default 100000) */
     maxLog?: number;
-    /** Maximum number of network requests to retain (default: 1000) */
+    /** Max number of network requests (default 1000) */
     maxNetwork?: number;
-    /** Custom console filter definitions */
-    filters?: Filter[];
+    /** Per-plugin options keyed by plugin name (default {}) */
+    pluginOption?: Record<string, object>;
+    /** Custom log filters (default null = builtin) */
+    filters?: FilterConfig[] | null;
   }
 
-  interface Filter {
-    id: string;
-    name: string;
-    icon?: string;
+  /** Storage backend interface (local / session / cookie) */
+  interface StorageBackend {
+    get(key: string): string | null;
+    set(key: string, value: string, days?: number): void;
+    remove(key: string): void;
+    clear(): void;
+    length(): number;
+    key(index: number): string | null;
+  }
+
+  interface StorageAccessor {
+    local: StorageBackend;
+    session: StorageBackend;
+    cookie: StorageBackend;
+  }
+
+  /** Custom theme configuration */
+  interface ThemeConfig {
+    vars: Record<string, string>;
+    icons?: Record<string, string>;
+  }
+
+  /** Header button configuration */
+  interface HeaderButton {
+    icon: string;
+    fn?: () => void;
   }
 
+  /** Hook names and their handler arrays */
+  interface HookMap {
+    beforeRender: HookHandler[];
+    afterRender: HookHandler[];
+    beforeLog: HookHandler[];
+    afterLog: HookHandler[];
+    beforeOpen: HookHandler[];
+    afterOpen: HookHandler[];
+    beforeClose: HookHandler[];
+    afterClose: HookHandler[];
+    beforeClear: HookHandler[];
+    afterClear: HookHandler[];
+    pluginMount: HookHandler[];
+    pluginUnmount: HookHandler[];
+  }
+
+  type HookHandler = (...args: any[]) => void;
+
+  /** Custom tab configuration */
   interface TabConfig {
     id: string;
     name: string;
     icon?: string;
-    /** Static HTML content for the tab */
+    render?(container: HTMLElement): void;
     html?: string;
-    /** Dynamic render function for the tab content */
-    render?: (container: HTMLElement) => void;
-    /** Called when the tab is shown */
-    onShow?: () => void;
+    onShow?(): void;
   }
 
-  interface PluginTab {
-    id: string;
-    name: string;
-    icon: string;
-    plugin?: tCPlugin;
-    onShow?: () => void;
-  }
-
-  // ============= Data Interfaces =============
-
-  interface NetworkRequest {
+  /** Network request record */
+  interface NetRequest {
     id: number;
     url: string;
     method: string;
@@ -178,95 +113,253 @@ declare namespace thinConsole {
     reqHeaders: Record<string, string>;
     reqBody: any;
     resHeaders: Record<string, string>;
-    resBody: any;
+    resBody: string | null;
     startTime: number;
     endTime: number;
     duration: number;
-    error: any;
-  }
-
-  interface LogEntry {
-    id: number;
-    type: string;
-    args: any[];
-    time: number;
-    stack?: string;
-    subType?: string;
-    extra?: any;
+    error: string | null;
   }
 
-  interface ShadowRootInfo {
-    root: ShadowRoot;
-    mode: "open" | "closed";
+  /** Sandbox proxy that exposes instance API to plugins safely */
+  interface Sandbox {
+    tC: ThinConsole;
+    pluginOption: Record<string, object>;
+    readonly __isSandbox: boolean;
   }
 
-  // ============= Filter Count =============
-
   /**
-   * Result of count formatting. Used by filter buttons to display
-   * a compact count in parentheses and the exact value on hover.
-   *
-   * - `filterCount`: displayed inside () on active filters
-   *   (string like "1K" / "1K+" / "100K+", or the raw number if <= 999)
-   * - `exactCount`: shown in the title (tooltip) on hover
-   *
-   * For built-in tabs (console, network, storage) this is auto-generated
-   * by `_fmtCount()`. For extension/plugin tabs, developers can pass
-   * custom objects via `setFilterCounts()` to control both values.
+   * Base plugin class. Extend this to create a class-based plugin.
+   * ```ts
+   * class MyPlugin extends tCPlugin {
+   *   init() { /* ... *\/ }
+   *   addTab() { return { id: "my", name: "My Tab" }; }
+   * }
+   * thinConsole.addPlugin("my", MyPlugin);
+   * ```
    */
-  interface FilterCountResult {
-    filterCount: string | number;
-    exactCount: number;
-  }
-
-  // ============= Hooks =============
-
-  type HookName =
-    | "beforeRender"
-    | "afterRender"
-    | "beforeLog"
-    | "afterLog"
-    | "beforeOpen"
-    | "afterOpen"
-    | "beforeClose"
-    | "afterClose"
-    | "beforeClear"
-    | "afterClear"
-    | "pluginMount"
-    | "pluginUnmount";
-
-  type HookCallback = (...args: any[]) => void;
-
-  // ============= Plugin Base Class =============
-
-  class tCPlugin {
-    constructor(tC: thinConsole, config?: any);
-    /** The thinConsole instance this plugin is bound to */
-    tC: thinConsole;
-    /** Plugin configuration object */
-    config: any;
-    /** Plugin ID (auto-derived from class name, lowercased) */
+  class Plugin {
+    protected tC: ThinConsole;
+    pluginOption: Record<string, object>;
     id: string;
-    /** Initialize plugin — override in subclass */
+    constructor(tC: ThinConsole);
     init(): void;
-    /** Whether the current language is Chinese */
     iszh(): boolean;
-    /** Whether the current language is English */
     isen(): boolean;
-    /** Whether running on a mobile device */
     isMobile(): boolean;
-    /** Render plugin content into container — override in subclass */
     render(container: HTMLElement): void;
-    /** Called when plugin tab becomes visible — override in subclass */
     onShow(): void;
-    /** Called when plugin tab becomes hidden — override in subclass */
     onHide(): void;
-    /** Cleanup when plugin is destroyed — override in subclass */
     destroy(): void;
-    /** Define a tab for this plugin — override in subclass */
-    addTab?(): PluginTab;
   }
+
+  /** ThinConsole instance */
+  class ThinConsole {
+    constructor(options?: Options);
+
+    /** Version string */
+    readonly version: string;
+
+    /** Current options (sanitized) */
+    readonly options: Options;
+
+    /** Current tab id */
+    currentTab: string;
+
+    /** Current theme id */
+    currentTheme: string;
+
+    /** Max log entries */
+    maxLog: number;
+
+    /** Max network request records */
+    maxNetwork: number;
+
+    /** Currently selected element */
+    selectedElement: Element | null;
+
+    /** Initialize the console (creates button + overlay) */
+    init(): void;
+
+    /** Show the console overlay, optionally switching to a tab */
+    show(tab?: string): this;
+
+    /** Hide the console overlay */
+    hide(): this;
+
+    /** Destroy the instance and remove all DOM elements */
+    destroy(): void;
+
+    /** Destroy and recreate with new options */
+    setOption(options: Options): this;
+
+    /** Switch to a tab by id */
+    switchTab(tab: string): void;
+
+    /** Show a toast notification */
+    showNotification(message: string, type?: string): void;
+
+    /** Toggle mute state for console logs */
+    toggleMute(): void;
+
+    /** Toggle search bar visibility */
+    toggleSearch(): void;
+
+    /** Run code from the title input */
+    runCode(): void;
+
+    /** Copy a log entry */
+    copyLog(id: string, plain?: boolean, raw?: boolean): void;
+
+    /** Clear all logs */
+    clearAllLogs(all?: boolean): void;
+
+    /** Add a localStorage item (opens editor) */
+    addLSItem(): void;
+
+    /** Edit a localStorage item by key */
+    editLSItem(key: string): void;
+
+    /** Save the current localStorage editor content */
+    saveLSItem(): void;
+
+    /** Remove a localStorage item by key */
+    removeLSItem(key: string): void;
+
+    /** Start the element picker mode */
+    startElementPicker(): void;
+
+    /** Expand the element tree to reveal a specific element */
+    expandToElement(el: Element): void;
+
+    /** Copy an element's HTML */
+    copyElementHTML(el: Element): void;
+
+    /** Delete an element from the DOM */
+    deleteElement(el: Element): void;
+
+    /** Start observing DOM mutations for element tree updates */
+    startElementObserver(): void;
+
+    /** Stop the element mutation observer */
+    stopElementObserver(): void;
+
+    /** Re-render current tab content */
+    renderContent(): void;
+
+    /** Capture XHR and fetch network requests */
+    captureNetworkRequests(): void;
+
+    /** Render the network request list */
+    renderNetworkList(): void;
+
+    /** Clear network requests (respects active filter) */
+    clearNetworkRequests(): void;
+
+    /** Send a new network request from the request editor */
+    sendNewRequest(): void;
+
+    /** Show network request detail panel */
+    showNetDetail(id: number): void;
+
+    /** Resend a previous network request */
+    resendRequest(req: NetRequest): void;
+
+    /** Apply custom icon overrides */
+    applyIcon(icons: Record<string, string>): void;
+
+    /** Set the icon for a specific filter button */
+    setFilterIcon(filterId: string, iconId: string): boolean;
+
+    /** Disable a plugin by name */
+    disablePlugin(name: string): this;
+
+    /** Enable a previously disabled plugin */
+    enablePlugin(name: string): this;
+
+    /** Trigger a global hook with arguments */
+    triggerGlobalHook(name: keyof HookMap, ...args: any[]): void;
+
+    /** Load a single plugin by name */
+    loadSinglePlugin(name: string): this;
+
+    /** Create a sandbox proxy for plugin isolation */
+    createSandbox(target: ThinConsole): Sandbox;
+
+    /** Escape HTML special characters */
+    escapeHtml(str: string): string;
+
+    /** Safe JSON stringify with circular reference handling */
+    safeStringify(value: any, indent?: number, json?: boolean): string;
+
+    /** Get the icon SVG string */
+    icon(name: string, className?: string): string;
+
+    /** Storage accessor (local, session, cookie) */
+    readonly storage: StorageAccessor;
+  }
+
+  // ---- Static API ----
+
+  /** Current singleton instance, or null */
+  const tC: ThinConsole | null;
+
+  /** Registered plugins (class-based) */
+  const plugins: Record<string, typeof Plugin>;
+
+  /** Registered themes */
+  const themes: Record<string, ThemeConfig>;
+
+  /** Registered header buttons (max 5) */
+  const headerButtons: HeaderButton[];
+
+  /** Global hook arrays */
+  const hooks: HookMap;
+
+  /** Register a custom theme */
+  function addTheme(
+    name: string,
+    styles: string,
+    icons?: Record<string, string>
+  ): typeof thinConsole;
+
+  /** Add a header button (max 5) */
+  function addHeader(icon: string, fn?: () => void): typeof thinConsole;
+
+  /** Set options (destroys and recreates the singleton) */
+  function setOption(options: Options): typeof thinConsole;
+
+  /** Show the console overlay (static convenience) */
+  function show(tab?: string): typeof thinConsole;
+
+  /** Hide the console overlay (static convenience) */
+  function hide(): typeof thinConsole;
+
+  /** Destroy the singleton (static convenience) */
+  function destroy(): typeof thinConsole;
+
+  /** console.log passthrough (static convenience) */
+  function log(...args: any[]): typeof thinConsole;
+
+  /** console.info passthrough (static convenience) */
+  function info(...args: any[]): typeof thinConsole;
+
+  /** console.warn passthrough (static convenience) */
+  function warn(...args: any[]): typeof thinConsole;
+
+  /** console.error passthrough (static convenience) */
+  function error(...args: any[]): typeof thinConsole;
+
+  /** Register a plugin (class or function) */
+  function addPlugin(name: string, plugin: typeof Plugin | ((tC: Sandbox) => void)): typeof thinConsole;
+
+  /** Add custom tabs */
+  function addTabs(tabs: TabConfig | TabConfig[]): typeof thinConsole;
 }
 
+/** The Plugin base class, also available as window.tCPlugin */
+declare const tCPlugin: typeof thinConsole.Plugin;
+
+/** Main constructor: create or reuse the singleton */
+declare function thinConsole(options?: thinConsole.Options): thinConsole.ThinConsole;
+
 export = thinConsole;
-export as namespace thinConsole;