@kedataindo/docflow-core 0.0.11 → 0.0.13

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   LOCAL_STORAGE_KEY: () => LOCAL_STORAGE_KEY,
   PAGE_SIZES: () => PAGE_SIZES,
   PaginationPlus: () => PaginationPlus,
+  PerformanceMonitor: () => PerformanceMonitor,
   SearchAndReplaceExtension: () => SearchAndReplaceExtension,
   SubdocumentProvider: () => SubdocumentProvider,
   buildAIPrompt: () => buildAIPrompt,
@@ -46,6 +47,7 @@ __export(index_exports, {
   createActionMap: () => createActionMap,
   createCollaboration: () => createCollaboration,
   createEditor: () => createEditor,
+  createPerformanceMonitor: () => createPerformanceMonitor,
   definePlugin: () => definePlugin,
   findMatches: () => findMatches,
   getSearchState: () => getSearchState,
@@ -1262,6 +1264,188 @@ var PAGE_SIZES = {
   TABLOID: TABLOID_PAGE_SIZE
 };
 
+// src/PerformanceMonitor.ts
+var TARGET_FRAME_MS = 1e3 / 60;
+var formatMb = (bytes) => `${Math.round(bytes / 1024 / 1024)}MB`;
+var PerformanceMonitor = class {
+  container;
+  interval;
+  metrics;
+  root = null;
+  cpuBar = null;
+  cpuValue = null;
+  ramBar = null;
+  ramValue = null;
+  rafId = 0;
+  lastFrame = 0;
+  busyMs = 0;
+  windowStart = 0;
+  timer = null;
+  longTaskObserver = null;
+  destroyed = false;
+  constructor(options = {}) {
+    this.container = options.container ?? (typeof document !== "undefined" ? document.body : void 0);
+    this.interval = options.interval ?? 1e3;
+    this.metrics = new Set(options.metrics ?? ["cpu", "ram"]);
+  }
+  /** Append the widget to the container and start sampling. */
+  start() {
+    if (this.destroyed || this.root) return;
+    if (!this.container || typeof window === "undefined" || typeof document === "undefined") return;
+    this.buildWidget();
+    this.windowStart = performance.now();
+    this.lastFrame = this.windowStart;
+    this.busyMs = 0;
+    this.rafId = requestAnimationFrame(this.onFrame);
+    this.longTaskObserver = this.createLongTaskObserver();
+    this.timer = setInterval(this.onTick, this.interval);
+  }
+  /**
+   * Render a fresh snapshot. Used by the internal ticker; also public so
+   * tests and hosts can render known values (values are optional — a metric
+   * without a value keeps its previous text).
+   */
+  update(cpuPercent, ramBytes, ramLimitBytes) {
+    if (!this.root) return;
+    if (typeof cpuPercent === "number") {
+      const clamped = Math.max(0, Math.min(100, cpuPercent));
+      this.renderBar(this.cpuBar, clamped);
+      if (this.cpuValue) this.cpuValue.textContent = `${Math.round(clamped)}%`;
+    }
+    if (typeof ramBytes === "number") {
+      const pct = typeof ramLimitBytes === "number" && ramLimitBytes > 0 ? Math.max(0, Math.min(100, ramBytes / ramLimitBytes * 100)) : 0;
+      this.renderBar(this.ramBar, pct);
+      if (this.ramValue) {
+        this.ramValue.textContent = typeof ramLimitBytes === "number" && ramLimitBytes > 0 ? `${formatMb(ramBytes)} / ${formatMb(ramLimitBytes)}` : formatMb(ramBytes);
+      }
+    }
+  }
+  /** Stop sampling, disconnect observers, and remove the widget. */
+  destroy() {
+    this.destroyed = true;
+    if (this.rafId) cancelAnimationFrame(this.rafId);
+    this.rafId = 0;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.longTaskObserver?.disconnect();
+    this.longTaskObserver = null;
+    if (this.root && this.root.parentElement) {
+      this.root.parentElement.removeChild(this.root);
+    }
+    this.root = null;
+  }
+  buildWidget() {
+    const root = document.createElement("div");
+    root.setAttribute("data-docflow-perf-monitor", "");
+    root.style.cssText = [
+      "position:fixed",
+      "right:12px",
+      "bottom:12px",
+      "z-index:2147483000",
+      "background:rgba(15,23,42,0.55)",
+      "backdrop-filter:blur(6px)",
+      "-webkit-backdrop-filter:blur(6px)",
+      "color:rgba(226,232,240,0.9)",
+      "font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace",
+      "padding:8px 10px",
+      "border-radius:8px",
+      "border:1px solid rgba(255,255,255,0.14)",
+      "pointer-events:none",
+      "user-select:none",
+      "opacity:0.85",
+      "box-shadow:0 4px 16px rgba(0,0,0,0.25)"
+    ].join(";");
+    if (this.metrics.has("cpu")) {
+      root.appendChild(this.buildRow("CPU", (el) => this.cpuBar = el, (el) => this.cpuValue = el));
+    }
+    if (this.metrics.has("ram")) {
+      root.appendChild(this.buildRow("RAM", (el) => this.ramBar = el, (el) => this.ramValue = el));
+    }
+    this.root = root;
+    this.container.appendChild(root);
+  }
+  buildRow(label, setBar, setValue) {
+    const row = document.createElement("div");
+    row.style.cssText = "display:flex;align-items:center;gap:6px;white-space:nowrap";
+    const labelEl = document.createElement("span");
+    labelEl.textContent = label;
+    labelEl.style.cssText = "opacity:0.75;min-width:26px";
+    const track = document.createElement("div");
+    track.style.cssText = "width:46px;height:5px;border-radius:3px;background:rgba(255,255,255,0.18);overflow:hidden";
+    const bar = document.createElement("div");
+    bar.style.cssText = "width:0%;height:100%;border-radius:3px;background:#22d3ee;transition:width .3s ease";
+    track.appendChild(bar);
+    setBar(bar);
+    const value = document.createElement("span");
+    value.textContent = "\u2014";
+    value.style.cssText = "min-width:64px;text-align:right";
+    setValue(value);
+    row.append(labelEl, track, value);
+    return row;
+  }
+  renderBar(bar, pct) {
+    if (!bar) return;
+    bar.style.width = `${pct}%`;
+    bar.style.background = pct >= 80 ? "#f87171" : pct >= 50 ? "#fbbf24" : "#22d3ee";
+  }
+  onFrame = (now) => {
+    if (this.destroyed) return;
+    const delta = now - this.lastFrame;
+    this.lastFrame = now;
+    if (delta > TARGET_FRAME_MS) {
+      this.busyMs += delta - TARGET_FRAME_MS;
+    }
+    this.rafId = requestAnimationFrame(this.onFrame);
+  };
+  onTick = () => {
+    if (this.destroyed) return;
+    const now = performance.now();
+    const windowMs = now - this.windowStart || this.interval;
+    this.windowStart = now;
+    let cpu;
+    if (this.metrics.has("cpu")) {
+      cpu = Math.max(0, Math.min(100, this.busyMs / windowMs * 100));
+      this.busyMs = 0;
+    }
+    let ram;
+    let ramLimit;
+    if (this.metrics.has("ram")) {
+      const memory = this.getMemoryInfo();
+      if (memory) {
+        ram = memory.usedJSHeapSize;
+        ramLimit = memory.jsHeapSizeLimit;
+      }
+    }
+    this.update(cpu, ram, ramLimit);
+  };
+  getMemoryInfo() {
+    const perf = performance;
+    const memory = perf.memory;
+    if (!memory || typeof memory.usedJSHeapSize !== "number") return null;
+    return memory;
+  }
+  createLongTaskObserver() {
+    if (typeof PerformanceObserver === "undefined") return null;
+    try {
+      const observer = new PerformanceObserver((list) => {
+        if (this.destroyed) return;
+        for (const entry of list.getEntries()) {
+          this.busyMs += entry.duration;
+        }
+      });
+      observer.observe({ entryTypes: ["longtask"] });
+      return observer;
+    } catch {
+      return null;
+    }
+  }
+};
+function createPerformanceMonitor(options) {
+  const monitor = new PerformanceMonitor(options);
+  monitor.start();
+  return monitor;
+}
+
 // src/Editor.ts
 function sanitizePastedHTML(html) {
   let cleaned = html.replace(/<meta[^>]*>/gi, "");
@@ -1339,6 +1523,7 @@ function createEditor(options = {}) {
   };
   const plugins = migratedOptions.plugins ?? [];
   const collaborationSetup = migratedOptions.collaboration ? createCollaboration(migratedOptions.collaboration) : void 0;
+  const performanceMonitor = migratedOptions.debug ? createPerformanceMonitor() : void 0;
   let tiptapEditor = createTiptapEditor(migratedOptions, plugins, collaborationSetup);
   let pluginActions = createActionMap(tiptapEditor, plugins);
   for (const plugin of plugins) {
@@ -1379,6 +1564,7 @@ function createEditor(options = {}) {
       }
       tiptapEditor.destroy();
       collaborationSetup?.destroy();
+      performanceMonitor?.destroy();
     },
     use: (plugin) => {
       plugins.push(plugin);
@@ -1387,7 +1573,8 @@ function createEditor(options = {}) {
     },
     get pluginActions() {
       return pluginActions;
-    }
+    },
+    performanceMonitor
   };
   return editor;
 }
@@ -2235,6 +2422,7 @@ function openaiCompatibleProvider(config) {
   LOCAL_STORAGE_KEY,
   PAGE_SIZES,
   PaginationPlus,
+  PerformanceMonitor,
   SearchAndReplaceExtension,
   SubdocumentProvider,
   buildAIPrompt,
@@ -2244,6 +2432,7 @@ function openaiCompatibleProvider(config) {
   createActionMap,
   createCollaboration,
   createEditor,
+  createPerformanceMonitor,
   definePlugin,
   findMatches,
   getSearchState,

package/dist/index.d.cts

@@ -307,6 +307,70 @@ type AIDraftFn = (req: {
     k?: number;
 }, signal: AbortSignal) => AsyncIterable<AIDraftEvent>;
 
+/**
+ * Lightweight client-side performance monitor (debug overlay).
+ *
+ * Shows current CPU utilization (event-loop busy time measured via
+ * `requestAnimationFrame` + the Long Tasks API) and JS heap usage in a
+ * semi-transparent widget pinned to the bottom-right corner of the viewport.
+ *
+ * The widget is opt-in and controlled by the host through the `debug: true`
+ * EditorOptions flag, so it never appears in production builds unless the
+ * consumer enables it. Because it is implemented with plain DOM + inline
+ * styles (no CSS imports, no framework), it works in every host surface the
+ * library ships: vanilla `createEditor()`, the Vue component, and the
+ * `<docs-editor>` Web Component (Shadow DOM).
+ *
+ * This is a pure debug *view* — it never reads or mutates the ProseMirror
+ * document, so the "single source of truth" and LIBRARY_CONTRACT rules hold.
+ */
+type MonitorMetric = 'cpu' | 'ram';
+interface PerformanceMonitorOptions {
+    /** Element the widget is appended to. Defaults to `document.body`. */
+    container?: HTMLElement;
+    /** Refresh interval in ms. Defaults to 1000. */
+    interval?: number;
+    /** Which metrics to render. Defaults to `['cpu', 'ram']`. */
+    metrics?: MonitorMetric[];
+}
+declare class PerformanceMonitor {
+    private readonly container;
+    private readonly interval;
+    private readonly metrics;
+    private root;
+    private cpuBar;
+    private cpuValue;
+    private ramBar;
+    private ramValue;
+    private rafId;
+    private lastFrame;
+    private busyMs;
+    private windowStart;
+    private timer;
+    private longTaskObserver;
+    private destroyed;
+    constructor(options?: PerformanceMonitorOptions);
+    /** Append the widget to the container and start sampling. */
+    start(): void;
+    /**
+     * Render a fresh snapshot. Used by the internal ticker; also public so
+     * tests and hosts can render known values (values are optional — a metric
+     * without a value keeps its previous text).
+     */
+    update(cpuPercent?: number, ramBytes?: number, ramLimitBytes?: number): void;
+    /** Stop sampling, disconnect observers, and remove the widget. */
+    destroy(): void;
+    private buildWidget;
+    private buildRow;
+    private renderBar;
+    private onFrame;
+    private onTick;
+    private getMemoryInfo;
+    private createLongTaskObserver;
+}
+/** Convenience factory: creates + starts a monitor (returns a stopped one when no DOM). */
+declare function createPerformanceMonitor(options?: PerformanceMonitorOptions): PerformanceMonitor;
+
 /**
  * Sanitize pasted HTML content (e.g. from Google Docs) to prevent crashes
  * during ProseMirror parsing. Strips non-content tags like <meta>, <style>,
@@ -337,6 +401,12 @@ interface EditorOptions {
     aiStream?: AIStreamFn;
     /** Host-injected cited-draft transport (Phase 7E — editor → server → RAG LLM). */
     aiDraft?: AIDraftFn;
+    /**
+     * Enable the debug overlay (CPU + RAM monitor) pinned to the bottom-right
+     * corner of the viewport. Pure debug view — never touches document state.
+     * Defaults to `false`, so production consumers are unaffected.
+     */
+    debug?: boolean;
 }
 interface DocsEditor {
     editor: Editor;
@@ -346,6 +416,8 @@ interface DocsEditor {
     destroy: () => void;
     use: (plugin: DocsEditorPlugin) => void;
     pluginActions: Record<string, (...args: unknown[]) => boolean>;
+    /** Active performance monitor when `debug: true` was set (undefined otherwise). */
+    performanceMonitor?: PerformanceMonitor;
 }
 declare function createEditor(options?: EditorOptions): DocsEditor;
 
@@ -608,4 +680,4 @@ interface OpenAICompatibleConfig {
 }
 declare function openaiCompatibleProvider(config: OpenAICompatibleConfig): AIProvider;
 
-export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type OpenAICompatibleConfig, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };
+export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type MonitorMetric, type OpenAICompatibleConfig, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, createPerformanceMonitor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };

package/dist/index.d.ts

@@ -307,6 +307,70 @@ type AIDraftFn = (req: {
     k?: number;
 }, signal: AbortSignal) => AsyncIterable<AIDraftEvent>;
 
+/**
+ * Lightweight client-side performance monitor (debug overlay).
+ *
+ * Shows current CPU utilization (event-loop busy time measured via
+ * `requestAnimationFrame` + the Long Tasks API) and JS heap usage in a
+ * semi-transparent widget pinned to the bottom-right corner of the viewport.
+ *
+ * The widget is opt-in and controlled by the host through the `debug: true`
+ * EditorOptions flag, so it never appears in production builds unless the
+ * consumer enables it. Because it is implemented with plain DOM + inline
+ * styles (no CSS imports, no framework), it works in every host surface the
+ * library ships: vanilla `createEditor()`, the Vue component, and the
+ * `<docs-editor>` Web Component (Shadow DOM).
+ *
+ * This is a pure debug *view* — it never reads or mutates the ProseMirror
+ * document, so the "single source of truth" and LIBRARY_CONTRACT rules hold.
+ */
+type MonitorMetric = 'cpu' | 'ram';
+interface PerformanceMonitorOptions {
+    /** Element the widget is appended to. Defaults to `document.body`. */
+    container?: HTMLElement;
+    /** Refresh interval in ms. Defaults to 1000. */
+    interval?: number;
+    /** Which metrics to render. Defaults to `['cpu', 'ram']`. */
+    metrics?: MonitorMetric[];
+}
+declare class PerformanceMonitor {
+    private readonly container;
+    private readonly interval;
+    private readonly metrics;
+    private root;
+    private cpuBar;
+    private cpuValue;
+    private ramBar;
+    private ramValue;
+    private rafId;
+    private lastFrame;
+    private busyMs;
+    private windowStart;
+    private timer;
+    private longTaskObserver;
+    private destroyed;
+    constructor(options?: PerformanceMonitorOptions);
+    /** Append the widget to the container and start sampling. */
+    start(): void;
+    /**
+     * Render a fresh snapshot. Used by the internal ticker; also public so
+     * tests and hosts can render known values (values are optional — a metric
+     * without a value keeps its previous text).
+     */
+    update(cpuPercent?: number, ramBytes?: number, ramLimitBytes?: number): void;
+    /** Stop sampling, disconnect observers, and remove the widget. */
+    destroy(): void;
+    private buildWidget;
+    private buildRow;
+    private renderBar;
+    private onFrame;
+    private onTick;
+    private getMemoryInfo;
+    private createLongTaskObserver;
+}
+/** Convenience factory: creates + starts a monitor (returns a stopped one when no DOM). */
+declare function createPerformanceMonitor(options?: PerformanceMonitorOptions): PerformanceMonitor;
+
 /**
  * Sanitize pasted HTML content (e.g. from Google Docs) to prevent crashes
  * during ProseMirror parsing. Strips non-content tags like <meta>, <style>,
@@ -337,6 +401,12 @@ interface EditorOptions {
     aiStream?: AIStreamFn;
     /** Host-injected cited-draft transport (Phase 7E — editor → server → RAG LLM). */
     aiDraft?: AIDraftFn;
+    /**
+     * Enable the debug overlay (CPU + RAM monitor) pinned to the bottom-right
+     * corner of the viewport. Pure debug view — never touches document state.
+     * Defaults to `false`, so production consumers are unaffected.
+     */
+    debug?: boolean;
 }
 interface DocsEditor {
     editor: Editor;
@@ -346,6 +416,8 @@ interface DocsEditor {
     destroy: () => void;
     use: (plugin: DocsEditorPlugin) => void;
     pluginActions: Record<string, (...args: unknown[]) => boolean>;
+    /** Active performance monitor when `debug: true` was set (undefined otherwise). */
+    performanceMonitor?: PerformanceMonitor;
 }
 declare function createEditor(options?: EditorOptions): DocsEditor;
 
@@ -608,4 +680,4 @@ interface OpenAICompatibleConfig {
 }
 declare function openaiCompatibleProvider(config: OpenAICompatibleConfig): AIProvider;
 
-export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type OpenAICompatibleConfig, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };
+export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type MonitorMetric, type OpenAICompatibleConfig, PerformanceMonitor, type PerformanceMonitorOptions, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, createPerformanceMonitor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };

package/dist/index.js

@@ -1193,6 +1193,188 @@ var PAGE_SIZES = {
   TABLOID: TABLOID_PAGE_SIZE
 };
 
+// src/PerformanceMonitor.ts
+var TARGET_FRAME_MS = 1e3 / 60;
+var formatMb = (bytes) => `${Math.round(bytes / 1024 / 1024)}MB`;
+var PerformanceMonitor = class {
+  container;
+  interval;
+  metrics;
+  root = null;
+  cpuBar = null;
+  cpuValue = null;
+  ramBar = null;
+  ramValue = null;
+  rafId = 0;
+  lastFrame = 0;
+  busyMs = 0;
+  windowStart = 0;
+  timer = null;
+  longTaskObserver = null;
+  destroyed = false;
+  constructor(options = {}) {
+    this.container = options.container ?? (typeof document !== "undefined" ? document.body : void 0);
+    this.interval = options.interval ?? 1e3;
+    this.metrics = new Set(options.metrics ?? ["cpu", "ram"]);
+  }
+  /** Append the widget to the container and start sampling. */
+  start() {
+    if (this.destroyed || this.root) return;
+    if (!this.container || typeof window === "undefined" || typeof document === "undefined") return;
+    this.buildWidget();
+    this.windowStart = performance.now();
+    this.lastFrame = this.windowStart;
+    this.busyMs = 0;
+    this.rafId = requestAnimationFrame(this.onFrame);
+    this.longTaskObserver = this.createLongTaskObserver();
+    this.timer = setInterval(this.onTick, this.interval);
+  }
+  /**
+   * Render a fresh snapshot. Used by the internal ticker; also public so
+   * tests and hosts can render known values (values are optional — a metric
+   * without a value keeps its previous text).
+   */
+  update(cpuPercent, ramBytes, ramLimitBytes) {
+    if (!this.root) return;
+    if (typeof cpuPercent === "number") {
+      const clamped = Math.max(0, Math.min(100, cpuPercent));
+      this.renderBar(this.cpuBar, clamped);
+      if (this.cpuValue) this.cpuValue.textContent = `${Math.round(clamped)}%`;
+    }
+    if (typeof ramBytes === "number") {
+      const pct = typeof ramLimitBytes === "number" && ramLimitBytes > 0 ? Math.max(0, Math.min(100, ramBytes / ramLimitBytes * 100)) : 0;
+      this.renderBar(this.ramBar, pct);
+      if (this.ramValue) {
+        this.ramValue.textContent = typeof ramLimitBytes === "number" && ramLimitBytes > 0 ? `${formatMb(ramBytes)} / ${formatMb(ramLimitBytes)}` : formatMb(ramBytes);
+      }
+    }
+  }
+  /** Stop sampling, disconnect observers, and remove the widget. */
+  destroy() {
+    this.destroyed = true;
+    if (this.rafId) cancelAnimationFrame(this.rafId);
+    this.rafId = 0;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.longTaskObserver?.disconnect();
+    this.longTaskObserver = null;
+    if (this.root && this.root.parentElement) {
+      this.root.parentElement.removeChild(this.root);
+    }
+    this.root = null;
+  }
+  buildWidget() {
+    const root = document.createElement("div");
+    root.setAttribute("data-docflow-perf-monitor", "");
+    root.style.cssText = [
+      "position:fixed",
+      "right:12px",
+      "bottom:12px",
+      "z-index:2147483000",
+      "background:rgba(15,23,42,0.55)",
+      "backdrop-filter:blur(6px)",
+      "-webkit-backdrop-filter:blur(6px)",
+      "color:rgba(226,232,240,0.9)",
+      "font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace",
+      "padding:8px 10px",
+      "border-radius:8px",
+      "border:1px solid rgba(255,255,255,0.14)",
+      "pointer-events:none",
+      "user-select:none",
+      "opacity:0.85",
+      "box-shadow:0 4px 16px rgba(0,0,0,0.25)"
+    ].join(";");
+    if (this.metrics.has("cpu")) {
+      root.appendChild(this.buildRow("CPU", (el) => this.cpuBar = el, (el) => this.cpuValue = el));
+    }
+    if (this.metrics.has("ram")) {
+      root.appendChild(this.buildRow("RAM", (el) => this.ramBar = el, (el) => this.ramValue = el));
+    }
+    this.root = root;
+    this.container.appendChild(root);
+  }
+  buildRow(label, setBar, setValue) {
+    const row = document.createElement("div");
+    row.style.cssText = "display:flex;align-items:center;gap:6px;white-space:nowrap";
+    const labelEl = document.createElement("span");
+    labelEl.textContent = label;
+    labelEl.style.cssText = "opacity:0.75;min-width:26px";
+    const track = document.createElement("div");
+    track.style.cssText = "width:46px;height:5px;border-radius:3px;background:rgba(255,255,255,0.18);overflow:hidden";
+    const bar = document.createElement("div");
+    bar.style.cssText = "width:0%;height:100%;border-radius:3px;background:#22d3ee;transition:width .3s ease";
+    track.appendChild(bar);
+    setBar(bar);
+    const value = document.createElement("span");
+    value.textContent = "\u2014";
+    value.style.cssText = "min-width:64px;text-align:right";
+    setValue(value);
+    row.append(labelEl, track, value);
+    return row;
+  }
+  renderBar(bar, pct) {
+    if (!bar) return;
+    bar.style.width = `${pct}%`;
+    bar.style.background = pct >= 80 ? "#f87171" : pct >= 50 ? "#fbbf24" : "#22d3ee";
+  }
+  onFrame = (now) => {
+    if (this.destroyed) return;
+    const delta = now - this.lastFrame;
+    this.lastFrame = now;
+    if (delta > TARGET_FRAME_MS) {
+      this.busyMs += delta - TARGET_FRAME_MS;
+    }
+    this.rafId = requestAnimationFrame(this.onFrame);
+  };
+  onTick = () => {
+    if (this.destroyed) return;
+    const now = performance.now();
+    const windowMs = now - this.windowStart || this.interval;
+    this.windowStart = now;
+    let cpu;
+    if (this.metrics.has("cpu")) {
+      cpu = Math.max(0, Math.min(100, this.busyMs / windowMs * 100));
+      this.busyMs = 0;
+    }
+    let ram;
+    let ramLimit;
+    if (this.metrics.has("ram")) {
+      const memory = this.getMemoryInfo();
+      if (memory) {
+        ram = memory.usedJSHeapSize;
+        ramLimit = memory.jsHeapSizeLimit;
+      }
+    }
+    this.update(cpu, ram, ramLimit);
+  };
+  getMemoryInfo() {
+    const perf = performance;
+    const memory = perf.memory;
+    if (!memory || typeof memory.usedJSHeapSize !== "number") return null;
+    return memory;
+  }
+  createLongTaskObserver() {
+    if (typeof PerformanceObserver === "undefined") return null;
+    try {
+      const observer = new PerformanceObserver((list) => {
+        if (this.destroyed) return;
+        for (const entry of list.getEntries()) {
+          this.busyMs += entry.duration;
+        }
+      });
+      observer.observe({ entryTypes: ["longtask"] });
+      return observer;
+    } catch {
+      return null;
+    }
+  }
+};
+function createPerformanceMonitor(options) {
+  const monitor = new PerformanceMonitor(options);
+  monitor.start();
+  return monitor;
+}
+
 // src/Editor.ts
 function sanitizePastedHTML(html) {
   let cleaned = html.replace(/<meta[^>]*>/gi, "");
@@ -1270,6 +1452,7 @@ function createEditor(options = {}) {
   };
   const plugins = migratedOptions.plugins ?? [];
   const collaborationSetup = migratedOptions.collaboration ? createCollaboration(migratedOptions.collaboration) : void 0;
+  const performanceMonitor = migratedOptions.debug ? createPerformanceMonitor() : void 0;
   let tiptapEditor = createTiptapEditor(migratedOptions, plugins, collaborationSetup);
   let pluginActions = createActionMap(tiptapEditor, plugins);
   for (const plugin of plugins) {
@@ -1310,6 +1493,7 @@ function createEditor(options = {}) {
       }
       tiptapEditor.destroy();
       collaborationSetup?.destroy();
+      performanceMonitor?.destroy();
     },
     use: (plugin) => {
       plugins.push(plugin);
@@ -1318,7 +1502,8 @@ function createEditor(options = {}) {
     },
     get pluginActions() {
       return pluginActions;
-    }
+    },
+    performanceMonitor
   };
   return editor;
 }
@@ -2165,6 +2350,7 @@ export {
   LOCAL_STORAGE_KEY,
   PAGE_SIZES,
   PaginationPlus,
+  PerformanceMonitor,
   SearchAndReplaceExtension,
   SubdocumentProvider,
   buildAIPrompt,
@@ -2174,6 +2360,7 @@ export {
   createActionMap,
   createCollaboration,
   createEditor,
+  createPerformanceMonitor,
   definePlugin,
   findMatches,
   getSearchState,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kedataindo/docflow-core",
   "license": "UNLICENSED",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",