@kedataindo/docflow-layout-engine 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,44 @@
+DocFlow — Proprietary EULA Reference
+
+Copyright © 2026 PT Kedata Indonesia (the "Licensor"). All rights reserved.
+
+────────────────────────────────────────────────────────────────────────
+THIS IS A TEMPLATE / SCAFFOLD FILE.
+────────────────────────────────────────────────────────────────────────
+This document is a placeholder summarising the licensing model. The
+binding text is the **DocFlow End-User License Agreement (EULA)** to
+be supplied separately to each customer, paired with a signed Order
+Form (per-deal price + tier + connection cap + server-instance cap).
+Until the EULA is reviewed by counsel and published, you may treat
+this file as the canonical statement that:
+
+  1. The DocFlow software is proprietary and NOT open-source.
+  2. No rights are granted by viewing the source code unless the
+     customer has accepted the EULA in writing.
+  3. The bundled third-party components listed in `NOTICE` keep
+     their original open-source licenses (mostly MIT).
+
+The "MIT" placeholder in `README.md` (carried over from before the
+proprietary decision) is **incorrect** and is updated by PR #90
+(replace "MIT" → "Proprietary — see LICENSE + NOTICE").
+────────────────────────────────────────────────────────────────────────
+
+Licensing model (per PRD §5 — proprietary EULA + separate MSA):
+
+  • DocFlow EULA (End-User License Agreement) — perpetual,
+    non-exclusive, non-transferable, metered per simultaneous
+    connection per server instance. Standard tiers: Community (free,
+    no warranty), Professional, Enterprise, Government. Hosting
+    DocFlow as a third-party SaaS is **prohibited** without a
+    separate OEM/SaaS agreement.
+  • Maintenance & Support Agreement (MSA) — annual, separate from
+    the EULA. Required for Professional / Enterprise / Government
+    for SLA-backed support; optional for Community.
+  • Source-code escrow (Government tier) — source code is deposited
+    with an escrow agent; released to the licensee if the Licensor
+    ceases to operate or fails the maintenance SLA.
+
+Governing law: Republic of Indonesia (UU Hak Cipta No. 28/2014).
+Dispute venue: District Court of Central Jakarta.
+
+For licensing questions: legal@kedata.co

package/dist/index.cjs

@@ -23,6 +23,7 @@ __export(index_exports, {
   PAGE_SIZES: () => PAGE_SIZES,
   PageBreaker: () => PageBreaker,
   PageLayout: () => PageLayout,
+  VirtualPageOverlay: () => VirtualPageOverlay,
   getPageSize: () => getPageSize
 });
 module.exports = __toCommonJS(index_exports);
@@ -191,6 +192,7 @@ var PageLayout = class {
   resizeObserver = null;
   debounceTimer = null;
   lastDocHash = "";
+  lastBlockHashes = /* @__PURE__ */ new Map();
   lastShadowHash = "";
   lastSize = { width: 0, height: 0 };
   lastResult = null;
@@ -288,6 +290,7 @@ var PageLayout = class {
     this.shadowRoot = null;
     this.lastResult = null;
     this.lastDocHash = "";
+    this.lastBlockHashes = /* @__PURE__ */ new Map();
     this.lastShadowHash = "";
   }
   scheduleLayout() {
@@ -301,20 +304,56 @@ var PageLayout = class {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
     }
-    const docHash = this.computeDocHash();
     const size = this.getContainerSize();
-    if (this.lastResult && this.lastDocHash === docHash && this.lastSize.width === size.width && this.lastSize.height === size.height) {
+    const containerChanged = this.lastSize.width !== size.width || this.lastSize.height !== size.height;
+    const docHash = this.computeDocHash();
+    if (this.lastResult && !containerChanged && this.lastDocHash === docHash) {
       this.resolveAll(this.lastResult);
       return this.lastResult;
     }
     this.prepareShadowLayout();
-    const root = this.element;
-    const blocks = this.measureBlocks(root);
+    const blocks = this.measureBlocks(this.element);
     const availableHeight = this.availableHeight();
-    const pages = this.breaker.computePages(blocks, availableHeight, this.options.maxCharsPerPage);
+    const newBlockHashes = this.computeBlockHashes();
+    const allPages = this.breaker.computePages(blocks, availableHeight, this.options.maxCharsPerPage);
+    let pages;
+    if (this.lastResult && !containerChanged && this.lastBlockHashes.size > 0) {
+      let firstChangedBlockIdx = -1;
+      for (let i = 0; i < blocks.length; i++) {
+        if (newBlockHashes.get(i) !== this.lastBlockHashes.get(i)) {
+          firstChangedBlockIdx = i;
+          break;
+        }
+      }
+      if (firstChangedBlockIdx === -1 && newBlockHashes.size !== this.lastBlockHashes.size) {
+        firstChangedBlockIdx = Math.min(newBlockHashes.size, this.lastBlockHashes.size);
+      }
+      if (firstChangedBlockIdx >= 0) {
+        const firstChangedFrom = blocks[firstChangedBlockIdx]?.from ?? 0;
+        const oldPages = this.lastResult.pages;
+        let affectedPageIdx = oldPages.length;
+        for (let p = 0; p < oldPages.length; p++) {
+          const lastBlock = oldPages[p].blocks[oldPages[p].blocks.length - 1];
+          if (lastBlock && lastBlock.to >= firstChangedFrom) {
+            affectedPageIdx = p;
+            break;
+          }
+        }
+        if (affectedPageIdx > 0 && affectedPageIdx < allPages.length && oldPages[affectedPageIdx - 1]?.to === allPages[affectedPageIdx - 1]?.to) {
+          pages = [...oldPages.slice(0, affectedPageIdx), ...allPages.slice(affectedPageIdx)];
+        } else {
+          pages = allPages;
+        }
+      } else {
+        pages = allPages;
+      }
+    } else {
+      pages = allPages;
+    }
     const result = { pages, invalidatedAt: Date.now() };
     this.lastResult = result;
     this.lastDocHash = docHash;
+    this.lastBlockHashes = newBlockHashes;
     this.lastSize = size;
     this.resolveAll(result);
     return result;
@@ -334,6 +373,18 @@ var PageLayout = class {
     }
     return hash;
   }
+  /** Compute per-block hashes for incremental recalculation. */
+  computeBlockHashes() {
+    const map = /* @__PURE__ */ new Map();
+    let idx = 0;
+    for (const child of Array.from(this.element.children)) {
+      if (child instanceof HTMLElement) {
+        map.set(idx, child.tagName + (child.getAttribute("data-from") ?? "") + (child.getAttribute("data-to") ?? "") + (child.getAttribute("data-node-type") ?? "") + (child.textContent ?? ""));
+      }
+      idx++;
+    }
+    return map;
+  }
   getContainerSize() {
     const rect = this.element.getBoundingClientRect();
     return { width: rect.width, height: rect.height };
@@ -407,10 +458,136 @@ var PageLayout = class {
     return null;
   }
 };
+
+// src/VirtualPageOverlay.ts
+var VirtualPageOverlay = class {
+  pageLayout;
+  config;
+  scrollEl;
+  editorEl;
+  bufferPages;
+  lastResult = null;
+  lastVisible = [];
+  lastScrollTop = -1;
+  scrollHandler = null;
+  rafId = 0;
+  constructor(editor, config, scrollEl, bufferPages = 2) {
+    const ps = typeof config.pageSize === "string" ? getPageSize(config.pageSize) ?? { id: "a4", name: "A4", pageWidth: 794, pageHeight: 1123 } : config.pageSize;
+    this.config = {
+      pageSize: ps,
+      margins: config.margins ?? { top: 20, bottom: 20, left: 50, right: 50 },
+      pageGap: config.pageGap ?? 50,
+      headerLeft: config.headerLeft ?? "",
+      headerRight: config.headerRight ?? "",
+      footerLeft: config.footerLeft ?? "",
+      footerRight: config.footerRight ?? ""
+    };
+    this.scrollEl = scrollEl;
+    this.bufferPages = bufferPages;
+    this.editorEl = editor instanceof HTMLElement ? editor : editor.dom;
+    this.pageLayout = new PageLayout(editor, {
+      pageHeight: ps.pageHeight,
+      pageWidth: ps.pageWidth,
+      margins: this.config.margins
+    }, 150);
+  }
+  /** Run or re-run layout measurement. Resolves with current page data. */
+  async layout() {
+    const result = await this.pageLayout.layout();
+    this.lastResult = result;
+    return this.computeData();
+  }
+  /** Start observing scroll events to track visible pages. */
+  observe() {
+    if (this.scrollHandler) return;
+    this.scrollHandler = () => this.onScroll();
+    this.scrollEl.addEventListener("scroll", this.scrollHandler, { passive: true });
+    this.updateVisible();
+  }
+  /** Stop observing scroll events. */
+  disconnect() {
+    if (this.scrollHandler) {
+      this.scrollEl.removeEventListener("scroll", this.scrollHandler);
+      this.scrollHandler = null;
+    }
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+    this.pageLayout.destroy();
+  }
+  /** Get current page overlay data synchronously (cached). */
+  getData() {
+    return {
+      totalPages: this.lastResult?.pages.length ?? 1,
+      visiblePages: this.lastVisible,
+      config: this.config
+    };
+  }
+  /** Update configuration (page size, margins, etc.) — triggers re-layout. */
+  async updateConfig(config) {
+    if (config.pageSize) {
+      const ps = typeof config.pageSize === "string" ? getPageSize(config.pageSize) ?? this.config.pageSize : config.pageSize;
+      this.config.pageSize = ps;
+      this.pageLayout.destroy();
+      this.pageLayout = new PageLayout(this.editorEl, {
+        pageHeight: ps.pageHeight,
+        pageWidth: ps.pageWidth,
+        margins: this.config.margins
+      }, 150);
+    }
+    if (config.margins) {
+      this.config.margins = { ...this.config.margins, ...config.margins };
+    }
+    if (config.pageGap !== void 0) this.config.pageGap = config.pageGap;
+    if (config.headerLeft !== void 0) this.config.headerLeft = config.headerLeft;
+    if (config.headerRight !== void 0) this.config.headerRight = config.headerRight;
+    if (config.footerLeft !== void 0) this.config.footerLeft = config.footerLeft;
+    if (config.footerRight !== void 0) this.config.footerRight = config.footerRight;
+    return this.layout();
+  }
+  // ── Private ────────────────────────────────────────────────────────────
+  onScroll() {
+    if (this.rafId) return;
+    this.rafId = requestAnimationFrame(() => {
+      this.rafId = 0;
+      this.updateVisible();
+    });
+  }
+  async updateVisible() {
+    const st = this.scrollEl.scrollTop;
+    if (st === this.lastScrollTop) return;
+    this.lastScrollTop = st;
+    if (!this.lastResult) {
+      await this.layout();
+    }
+    this.computeData();
+  }
+  computeData() {
+    const pages = this.lastResult?.pages ?? [];
+    const totalPages = pages.length || 1;
+    const ph = this.config.pageSize.pageHeight + this.config.pageGap;
+    const viewportTop = this.scrollEl.scrollTop;
+    const viewportBottom = viewportTop + this.scrollEl.clientHeight;
+    const visible = [];
+    const startPage = Math.max(0, Math.floor(viewportTop / ph) - this.bufferPages);
+    const endPage = Math.min(totalPages, Math.ceil(viewportBottom / ph) + this.bufferPages);
+    for (let i = startPage; i < endPage; i++) {
+      visible.push({
+        index: i,
+        top: i * ph,
+        height: ph
+      });
+    }
+    this.lastVisible = visible;
+    return { totalPages, visiblePages: visible, config: this.config };
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   PAGE_SIZES,
   PageBreaker,
   PageLayout,
+  VirtualPageOverlay,
   getPageSize
 });

package/dist/index.d.cts

@@ -78,6 +78,7 @@ declare class PageLayout {
     private resizeObserver;
     private debounceTimer;
     private lastDocHash;
+    private lastBlockHashes;
     private lastShadowHash;
     private lastSize;
     private lastResult;
@@ -91,6 +92,8 @@ declare class PageLayout {
     private runLayout;
     private resolveAll;
     private computeDocHash;
+    /** Compute per-block hashes for incremental recalculation. */
+    private computeBlockHashes;
     private getContainerSize;
     private availableHeight;
     private prepareShadowLayout;
@@ -99,4 +102,69 @@ declare class PageLayout {
     private findTextNodeAtOffset;
 }
 
-export { type BlockInfo, type EditorLike, type LayoutOptions, type LayoutResult, type MeasureTextBlock, PAGE_SIZES, type Page, PageBreaker, PageLayout, type PageSize, type SplitResult, getPageSize };
+interface PageOverlayConfig {
+    pageSize: PageSize | string;
+    margins?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    pageGap?: number;
+    headerLeft?: string;
+    headerRight?: string;
+    footerLeft?: string;
+    footerRight?: string;
+}
+interface VisiblePage {
+    index: number;
+    top: number;
+    height: number;
+}
+interface PageOverlayData {
+    totalPages: number;
+    visiblePages: VisiblePage[];
+    config: Required<PageOverlayConfig> & {
+        pageSize: PageSize;
+    };
+}
+/**
+ * Manages virtualized page overlays for a ProseMirror editor.
+ *
+ * Instead of creating DOM nodes for ALL pages (like tiptap-pagination-plus),
+ * this only tracks which pages are currently visible in the viewport and
+ * provides the data needed to render a lightweight overlay layer.
+ *
+ * Usage:
+ *   const overlay = new VirtualPageOverlay(editor, config, scrollEl, bufferPages?)
+ *   overlay.layout().then(data => render(data))
+ *   // On scroll: overlay.updateVisible().then(data => render(data))
+ */
+declare class VirtualPageOverlay {
+    pageLayout: PageLayout;
+    private config;
+    private scrollEl;
+    private editorEl;
+    private bufferPages;
+    private lastResult;
+    private lastVisible;
+    private lastScrollTop;
+    private scrollHandler;
+    private rafId;
+    constructor(editor: EditorLike | HTMLElement, config: PageOverlayConfig, scrollEl: HTMLElement, bufferPages?: number);
+    /** Run or re-run layout measurement. Resolves with current page data. */
+    layout(): Promise<PageOverlayData>;
+    /** Start observing scroll events to track visible pages. */
+    observe(): void;
+    /** Stop observing scroll events. */
+    disconnect(): void;
+    /** Get current page overlay data synchronously (cached). */
+    getData(): PageOverlayData;
+    /** Update configuration (page size, margins, etc.) — triggers re-layout. */
+    updateConfig(config: Partial<PageOverlayConfig>): Promise<PageOverlayData>;
+    private onScroll;
+    private updateVisible;
+    private computeData;
+}
+
+export { type BlockInfo, type EditorLike, type LayoutOptions, type LayoutResult, type MeasureTextBlock, PAGE_SIZES, type Page, PageBreaker, PageLayout, type PageOverlayConfig, type PageOverlayData, type PageSize, type SplitResult, VirtualPageOverlay, type VisiblePage, getPageSize };

package/dist/index.d.ts

@@ -78,6 +78,7 @@ declare class PageLayout {
     private resizeObserver;
     private debounceTimer;
     private lastDocHash;
+    private lastBlockHashes;
     private lastShadowHash;
     private lastSize;
     private lastResult;
@@ -91,6 +92,8 @@ declare class PageLayout {
     private runLayout;
     private resolveAll;
     private computeDocHash;
+    /** Compute per-block hashes for incremental recalculation. */
+    private computeBlockHashes;
     private getContainerSize;
     private availableHeight;
     private prepareShadowLayout;
@@ -99,4 +102,69 @@ declare class PageLayout {
     private findTextNodeAtOffset;
 }
 
-export { type BlockInfo, type EditorLike, type LayoutOptions, type LayoutResult, type MeasureTextBlock, PAGE_SIZES, type Page, PageBreaker, PageLayout, type PageSize, type SplitResult, getPageSize };
+interface PageOverlayConfig {
+    pageSize: PageSize | string;
+    margins?: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    pageGap?: number;
+    headerLeft?: string;
+    headerRight?: string;
+    footerLeft?: string;
+    footerRight?: string;
+}
+interface VisiblePage {
+    index: number;
+    top: number;
+    height: number;
+}
+interface PageOverlayData {
+    totalPages: number;
+    visiblePages: VisiblePage[];
+    config: Required<PageOverlayConfig> & {
+        pageSize: PageSize;
+    };
+}
+/**
+ * Manages virtualized page overlays for a ProseMirror editor.
+ *
+ * Instead of creating DOM nodes for ALL pages (like tiptap-pagination-plus),
+ * this only tracks which pages are currently visible in the viewport and
+ * provides the data needed to render a lightweight overlay layer.
+ *
+ * Usage:
+ *   const overlay = new VirtualPageOverlay(editor, config, scrollEl, bufferPages?)
+ *   overlay.layout().then(data => render(data))
+ *   // On scroll: overlay.updateVisible().then(data => render(data))
+ */
+declare class VirtualPageOverlay {
+    pageLayout: PageLayout;
+    private config;
+    private scrollEl;
+    private editorEl;
+    private bufferPages;
+    private lastResult;
+    private lastVisible;
+    private lastScrollTop;
+    private scrollHandler;
+    private rafId;
+    constructor(editor: EditorLike | HTMLElement, config: PageOverlayConfig, scrollEl: HTMLElement, bufferPages?: number);
+    /** Run or re-run layout measurement. Resolves with current page data. */
+    layout(): Promise<PageOverlayData>;
+    /** Start observing scroll events to track visible pages. */
+    observe(): void;
+    /** Stop observing scroll events. */
+    disconnect(): void;
+    /** Get current page overlay data synchronously (cached). */
+    getData(): PageOverlayData;
+    /** Update configuration (page size, margins, etc.) — triggers re-layout. */
+    updateConfig(config: Partial<PageOverlayConfig>): Promise<PageOverlayData>;
+    private onScroll;
+    private updateVisible;
+    private computeData;
+}
+
+export { type BlockInfo, type EditorLike, type LayoutOptions, type LayoutResult, type MeasureTextBlock, PAGE_SIZES, type Page, PageBreaker, PageLayout, type PageOverlayConfig, type PageOverlayData, type PageSize, type SplitResult, VirtualPageOverlay, type VisiblePage, getPageSize };

package/dist/index.js

@@ -162,6 +162,7 @@ var PageLayout = class {
   resizeObserver = null;
   debounceTimer = null;
   lastDocHash = "";
+  lastBlockHashes = /* @__PURE__ */ new Map();
   lastShadowHash = "";
   lastSize = { width: 0, height: 0 };
   lastResult = null;
@@ -259,6 +260,7 @@ var PageLayout = class {
     this.shadowRoot = null;
     this.lastResult = null;
     this.lastDocHash = "";
+    this.lastBlockHashes = /* @__PURE__ */ new Map();
     this.lastShadowHash = "";
   }
   scheduleLayout() {
@@ -272,20 +274,56 @@ var PageLayout = class {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
     }
-    const docHash = this.computeDocHash();
     const size = this.getContainerSize();
-    if (this.lastResult && this.lastDocHash === docHash && this.lastSize.width === size.width && this.lastSize.height === size.height) {
+    const containerChanged = this.lastSize.width !== size.width || this.lastSize.height !== size.height;
+    const docHash = this.computeDocHash();
+    if (this.lastResult && !containerChanged && this.lastDocHash === docHash) {
       this.resolveAll(this.lastResult);
       return this.lastResult;
     }
     this.prepareShadowLayout();
-    const root = this.element;
-    const blocks = this.measureBlocks(root);
+    const blocks = this.measureBlocks(this.element);
     const availableHeight = this.availableHeight();
-    const pages = this.breaker.computePages(blocks, availableHeight, this.options.maxCharsPerPage);
+    const newBlockHashes = this.computeBlockHashes();
+    const allPages = this.breaker.computePages(blocks, availableHeight, this.options.maxCharsPerPage);
+    let pages;
+    if (this.lastResult && !containerChanged && this.lastBlockHashes.size > 0) {
+      let firstChangedBlockIdx = -1;
+      for (let i = 0; i < blocks.length; i++) {
+        if (newBlockHashes.get(i) !== this.lastBlockHashes.get(i)) {
+          firstChangedBlockIdx = i;
+          break;
+        }
+      }
+      if (firstChangedBlockIdx === -1 && newBlockHashes.size !== this.lastBlockHashes.size) {
+        firstChangedBlockIdx = Math.min(newBlockHashes.size, this.lastBlockHashes.size);
+      }
+      if (firstChangedBlockIdx >= 0) {
+        const firstChangedFrom = blocks[firstChangedBlockIdx]?.from ?? 0;
+        const oldPages = this.lastResult.pages;
+        let affectedPageIdx = oldPages.length;
+        for (let p = 0; p < oldPages.length; p++) {
+          const lastBlock = oldPages[p].blocks[oldPages[p].blocks.length - 1];
+          if (lastBlock && lastBlock.to >= firstChangedFrom) {
+            affectedPageIdx = p;
+            break;
+          }
+        }
+        if (affectedPageIdx > 0 && affectedPageIdx < allPages.length && oldPages[affectedPageIdx - 1]?.to === allPages[affectedPageIdx - 1]?.to) {
+          pages = [...oldPages.slice(0, affectedPageIdx), ...allPages.slice(affectedPageIdx)];
+        } else {
+          pages = allPages;
+        }
+      } else {
+        pages = allPages;
+      }
+    } else {
+      pages = allPages;
+    }
     const result = { pages, invalidatedAt: Date.now() };
     this.lastResult = result;
     this.lastDocHash = docHash;
+    this.lastBlockHashes = newBlockHashes;
     this.lastSize = size;
     this.resolveAll(result);
     return result;
@@ -305,6 +343,18 @@ var PageLayout = class {
     }
     return hash;
   }
+  /** Compute per-block hashes for incremental recalculation. */
+  computeBlockHashes() {
+    const map = /* @__PURE__ */ new Map();
+    let idx = 0;
+    for (const child of Array.from(this.element.children)) {
+      if (child instanceof HTMLElement) {
+        map.set(idx, child.tagName + (child.getAttribute("data-from") ?? "") + (child.getAttribute("data-to") ?? "") + (child.getAttribute("data-node-type") ?? "") + (child.textContent ?? ""));
+      }
+      idx++;
+    }
+    return map;
+  }
   getContainerSize() {
     const rect = this.element.getBoundingClientRect();
     return { width: rect.width, height: rect.height };
@@ -378,9 +428,135 @@ var PageLayout = class {
     return null;
   }
 };
+
+// src/VirtualPageOverlay.ts
+var VirtualPageOverlay = class {
+  pageLayout;
+  config;
+  scrollEl;
+  editorEl;
+  bufferPages;
+  lastResult = null;
+  lastVisible = [];
+  lastScrollTop = -1;
+  scrollHandler = null;
+  rafId = 0;
+  constructor(editor, config, scrollEl, bufferPages = 2) {
+    const ps = typeof config.pageSize === "string" ? getPageSize(config.pageSize) ?? { id: "a4", name: "A4", pageWidth: 794, pageHeight: 1123 } : config.pageSize;
+    this.config = {
+      pageSize: ps,
+      margins: config.margins ?? { top: 20, bottom: 20, left: 50, right: 50 },
+      pageGap: config.pageGap ?? 50,
+      headerLeft: config.headerLeft ?? "",
+      headerRight: config.headerRight ?? "",
+      footerLeft: config.footerLeft ?? "",
+      footerRight: config.footerRight ?? ""
+    };
+    this.scrollEl = scrollEl;
+    this.bufferPages = bufferPages;
+    this.editorEl = editor instanceof HTMLElement ? editor : editor.dom;
+    this.pageLayout = new PageLayout(editor, {
+      pageHeight: ps.pageHeight,
+      pageWidth: ps.pageWidth,
+      margins: this.config.margins
+    }, 150);
+  }
+  /** Run or re-run layout measurement. Resolves with current page data. */
+  async layout() {
+    const result = await this.pageLayout.layout();
+    this.lastResult = result;
+    return this.computeData();
+  }
+  /** Start observing scroll events to track visible pages. */
+  observe() {
+    if (this.scrollHandler) return;
+    this.scrollHandler = () => this.onScroll();
+    this.scrollEl.addEventListener("scroll", this.scrollHandler, { passive: true });
+    this.updateVisible();
+  }
+  /** Stop observing scroll events. */
+  disconnect() {
+    if (this.scrollHandler) {
+      this.scrollEl.removeEventListener("scroll", this.scrollHandler);
+      this.scrollHandler = null;
+    }
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = 0;
+    }
+    this.pageLayout.destroy();
+  }
+  /** Get current page overlay data synchronously (cached). */
+  getData() {
+    return {
+      totalPages: this.lastResult?.pages.length ?? 1,
+      visiblePages: this.lastVisible,
+      config: this.config
+    };
+  }
+  /** Update configuration (page size, margins, etc.) — triggers re-layout. */
+  async updateConfig(config) {
+    if (config.pageSize) {
+      const ps = typeof config.pageSize === "string" ? getPageSize(config.pageSize) ?? this.config.pageSize : config.pageSize;
+      this.config.pageSize = ps;
+      this.pageLayout.destroy();
+      this.pageLayout = new PageLayout(this.editorEl, {
+        pageHeight: ps.pageHeight,
+        pageWidth: ps.pageWidth,
+        margins: this.config.margins
+      }, 150);
+    }
+    if (config.margins) {
+      this.config.margins = { ...this.config.margins, ...config.margins };
+    }
+    if (config.pageGap !== void 0) this.config.pageGap = config.pageGap;
+    if (config.headerLeft !== void 0) this.config.headerLeft = config.headerLeft;
+    if (config.headerRight !== void 0) this.config.headerRight = config.headerRight;
+    if (config.footerLeft !== void 0) this.config.footerLeft = config.footerLeft;
+    if (config.footerRight !== void 0) this.config.footerRight = config.footerRight;
+    return this.layout();
+  }
+  // ── Private ────────────────────────────────────────────────────────────
+  onScroll() {
+    if (this.rafId) return;
+    this.rafId = requestAnimationFrame(() => {
+      this.rafId = 0;
+      this.updateVisible();
+    });
+  }
+  async updateVisible() {
+    const st = this.scrollEl.scrollTop;
+    if (st === this.lastScrollTop) return;
+    this.lastScrollTop = st;
+    if (!this.lastResult) {
+      await this.layout();
+    }
+    this.computeData();
+  }
+  computeData() {
+    const pages = this.lastResult?.pages ?? [];
+    const totalPages = pages.length || 1;
+    const ph = this.config.pageSize.pageHeight + this.config.pageGap;
+    const viewportTop = this.scrollEl.scrollTop;
+    const viewportBottom = viewportTop + this.scrollEl.clientHeight;
+    const visible = [];
+    const startPage = Math.max(0, Math.floor(viewportTop / ph) - this.bufferPages);
+    const endPage = Math.min(totalPages, Math.ceil(viewportBottom / ph) + this.bufferPages);
+    for (let i = startPage; i < endPage; i++) {
+      visible.push({
+        index: i,
+        top: i * ph,
+        height: ph
+      });
+    }
+    this.lastVisible = visible;
+    return { totalPages, visiblePages: visible, config: this.config };
+  }
+};
 export {
   PAGE_SIZES,
   PageBreaker,
   PageLayout,
+  VirtualPageOverlay,
   getPageSize
 };

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@kedataindo/docflow-layout-engine",
-  "version": "0.0.1",
+  "license": "UNLICENSED",
+  "version": "0.0.3",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,7 +22,7 @@
   ],
   "dependencies": {
     "@tiptap/pm": "^2.11.0",
-    "@kedataindo/docflow-core": "0.0.2"
+    "@kedataindo/docflow-core": "0.0.4"
   },
   "devDependencies": {
     "happy-dom": "^20.10.6",