kviewer 0.2.0 → 0.2.1

package/README.md

@@ -20,6 +20,7 @@ A Nuxt module for viewing, annotating, and exporting PDFs. Built on pdfjs-dist,
 - ↩️ Undo/redo history
 - 🗂️ Multi-tab document support (`KViewerTabs`)
 - 🎨 Customizable header and footer slots
+- 👁️ Read tracking — `allPagesRead()` + `all-pages-read` event to gate "must read all pages" signing
 
 ## Quick Setup
 
@@ -112,6 +113,9 @@ const isEditing = viewerRef.value?.formEditMode.value
 | `formEditMode` | `Ref<boolean>` |
 | `setFormEditMode(enabled)` | `void` |
 | `toggleFormEditMode()` | `boolean` (the new state) |
+| `allPagesRead()` | `boolean` |
+| `getViewedPages()` | `number[]` |
+| `resetViewedPages()` | `void` |
 
 `exportPdf` options default to `{ flatten: false, download: false, preserveOriginalAnnotations: false }`.
 
@@ -138,6 +142,30 @@ Or imperatively from the ref API (`setFormEditMode`, `toggleFormEditMode`, react
 
 When native PDF annotations are auto-imported into Konva, exporting with `preserveOriginalAnnotations: true` may duplicate annotations. Prefer `preserveOriginalAnnotations: false` in that workflow.
 
+### Read tracking
+
+For "must read all pages before signing" flows, `KViewer` tracks which pages have entered the viewport. Gate your sign action on the `all-pages-read` event (push) or the `allPagesRead()` ref method (pull):
+
+```vue
+<template>
+  <KViewer
+    :source="pdfUrl"
+    @all-pages-read="canSign = true"
+    @update:viewed-pages="(pages) => (readCount = pages.length)"
+  />
+  <button :disabled="!canSign">Sign</button>
+</template>
+
+<script setup lang="ts">
+const canSign = ref(false)
+const readCount = ref(0)
+</script>
+```
+
+A page counts as read once its top edge scrolls into view (computed from geometry, so a fast scroll to the bottom still marks every page it passed). The viewer deliberately does not enforce that the user dwelled on each page — skipping is the signer's choice. The host app owns the policy (e.g. an extra "I have read all pages" checkbox); the viewer only reports the status. Call `resetViewedPages()` to restart tracking; loading a new `source` resets it automatically.
+
+The same surface is available over the [embed bridge](src/runtime/embed): `client.allPagesRead()`, `client.getViewedPages()`, `client.resetViewedPages()`, and the `all-pages-read` / `viewedPages-changed` events via `client.on(...)`.
+
 ## Development
 
 <details>

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "kviewer",
   "configKey": "kviewer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/Viewer.d.vue.ts

@@ -84,12 +84,24 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     setFormEditMode: (enabled: boolean) => void;
     /** Flip form-edit mode. Returns the new state. */
     toggleFormEditMode: () => boolean;
+    /** True once the user has viewed every page — each page has entered the
+     *  viewport at least once. Use to gate a "must read all pages" sign action.
+     *  See also the `all-pages-read` event for a push-style signal. */
+    allPagesRead: () => boolean;
+    /** Page numbers viewed so far, ascending. */
+    getViewedPages: () => number[];
+    /** Clear viewed-page tracking, e.g. to restart a signing session. */
+    resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "all-pages-read": () => any;
     "update:formEditMode": (value: boolean) => any;
     "update:activeRoleId": (value: string | null) => any;
+    "update:viewedPages": (pages: number[]) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onAll-pages-read"?: (() => any) | undefined;
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
     "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
+    "onUpdate:viewedPages"?: ((pages: number[]) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;

package/dist/runtime/components/Viewer.vue

@@ -229,7 +229,7 @@ const props = defineProps({
   scripting: { type: Boolean, required: false, default: false },
   menuItems: { type: Array, required: false, default: void 0 }
 });
-const emit = defineEmits(["update:formEditMode", "update:activeRoleId"]);
+const emit = defineEmits(["update:formEditMode", "update:activeRoleId", "update:viewedPages", "all-pages-read"]);
 const viewerRoot = ref(null);
 const scrollContainer = ref(null);
 const { state: viewerState, setScrollToPageFn, setDownloadPdfFn } = provideViewerState();
@@ -306,6 +306,31 @@ watch(
     viewerState.currentPage.value = page;
   }
 );
+watch(
+  () => viewerState.currentPage.value,
+  (page) => virtualization.markPageViewed(page),
+  { immediate: true }
+);
+watch(
+  () => pageMetas.value.length,
+  (len) => {
+    if (len > 0 && !isSinglePageMode.value) {
+      nextTick(() => virtualization.updateCurrentPageByRect());
+    }
+  }
+);
+watch(
+  virtualization.allPagesRead,
+  (read, prev) => {
+    if (read && !prev) emit("all-pages-read");
+  }
+);
+watch(
+  virtualization.viewedPages,
+  (pages) => {
+    emit("update:viewedPages", [...pages].sort((a, b) => a - b));
+  }
+);
 function onPageRef(pageNumber, el) {
   if (el) {
     virtualization.observePage(pageNumber, el);
@@ -892,7 +917,15 @@ defineExpose({
     const next = !viewerState.formEditMode.value;
     viewerState.setFormEditMode(next);
     return next;
-  }
+  },
+  /** True once the user has viewed every page — each page has entered the
+   *  viewport at least once. Use to gate a "must read all pages" sign action.
+   *  See also the `all-pages-read` event for a push-style signal. */
+  allPagesRead: () => virtualization.allPagesRead.value,
+  /** Page numbers viewed so far, ascending. */
+  getViewedPages: () => [...virtualization.viewedPages.value].sort((a, b) => a - b),
+  /** Clear viewed-page tracking, e.g. to restart a signing session. */
+  resetViewedPages: () => virtualization.resetViewedPages()
 });
 </script>
 

package/dist/runtime/components/Viewer.vue.d.ts

@@ -84,12 +84,24 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     setFormEditMode: (enabled: boolean) => void;
     /** Flip form-edit mode. Returns the new state. */
     toggleFormEditMode: () => boolean;
+    /** True once the user has viewed every page — each page has entered the
+     *  viewport at least once. Use to gate a "must read all pages" sign action.
+     *  See also the `all-pages-read` event for a push-style signal. */
+    allPagesRead: () => boolean;
+    /** Page numbers viewed so far, ascending. */
+    getViewedPages: () => number[];
+    /** Clear viewed-page tracking, e.g. to restart a signing session. */
+    resetViewedPages: () => void;
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "all-pages-read": () => any;
     "update:formEditMode": (value: boolean) => any;
     "update:activeRoleId": (value: string | null) => any;
+    "update:viewedPages": (pages: number[]) => any;
 }, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    "onAll-pages-read"?: (() => any) | undefined;
     "onUpdate:formEditMode"?: ((value: boolean) => any) | undefined;
     "onUpdate:activeRoleId"?: ((value: string | null) => any) | undefined;
+    "onUpdate:viewedPages"?: ((pages: number[]) => any) | undefined;
 }>, {
     userName: string;
     freehandGroupingDelay: number;

package/dist/runtime/composables/usePageVirtualization.d.ts

@@ -21,6 +21,17 @@ export interface PageVirtualization {
     pageMetas: ShallowRef<PageMeta[]>;
     currentPage: Ref<number>;
     renderedPages: ComputedRef<Set<number>>;
+    /** Pages that have entered the viewport at least once since the document
+     *  loaded (or since the last `resetViewedPages()`). Marked from scroll/pan
+     *  geometry — not render state — so a fast fling that skips rendering the
+     *  middle pages still counts them as viewed. */
+    viewedPages: ShallowRef<Set<number>>;
+    /** True once every page has been viewed. */
+    allPagesRead: ComputedRef<boolean>;
+    /** Mark a single page as viewed (used by single-page navigation). */
+    markPageViewed: (pageNumber: number) => void;
+    /** Clear the viewed-pages set, e.g. to start a fresh signing session. */
+    resetViewedPages: () => void;
     isPageRendered: (pageNumber: number) => boolean;
     observePage: (pageNumber: number, element: HTMLElement) => void;
     unobservePage: (pageNumber: number) => void;

package/dist/runtime/composables/usePageVirtualization.js

@@ -5,6 +5,30 @@ export function createPageVirtualization() {
   const pageMetas = shallowRef([]);
   const currentPage = ref(1);
   const visiblePages = shallowRef(/* @__PURE__ */ new Set());
+  const viewedPages = shallowRef(/* @__PURE__ */ new Set());
+  const allPagesRead = computed(() => {
+    const total = pageMetas.value.length;
+    return total > 0 && viewedPages.value.size >= total;
+  });
+  function markPageViewed(pageNumber) {
+    if (viewedPages.value.has(pageNumber)) return;
+    const next = new Set(viewedPages.value);
+    next.add(pageNumber);
+    viewedPages.value = next;
+  }
+  function markPagesViewed(pageNumbers) {
+    let next = null;
+    for (const n of pageNumbers) {
+      if (viewedPages.value.has(n) || next?.has(n)) continue;
+      if (!next) next = new Set(viewedPages.value);
+      next.add(n);
+    }
+    if (next) viewedPages.value = next;
+  }
+  function resetViewedPages() {
+    if (viewedPages.value.size === 0) return;
+    viewedPages.value = /* @__PURE__ */ new Set();
+  }
   let observer = null;
   let scrollRoot = null;
   let scrollListener = null;
@@ -88,12 +112,19 @@ export function createPageVirtualization() {
     if (bestPage !== currentPage.value) {
       currentPage.value = bestPage;
     }
+    const viewportBottom = rootTop + scrollRoot.clientHeight;
+    const reached = [];
+    for (const [pageNum, el] of pageToElement) {
+      if (el.offsetTop < viewportBottom) reached.push(pageNum);
+    }
+    markPagesViewed(reached);
   }
   function scrollToPage(pageNumber) {
     const element = pageToElement.get(pageNumber);
     if (element && scrollRoot) {
       element.scrollIntoView({ block: "start", behavior: "instant" });
       currentPage.value = pageNumber;
+      markPageViewed(pageNumber);
     }
   }
   function getPageElement(pageNumber) {
@@ -103,8 +134,10 @@ export function createPageVirtualization() {
     if (!scrollRoot) return;
     const rootRect = scrollRoot.getBoundingClientRect();
     const rootMid = rootRect.top + rootRect.height / 2;
+    const rootBottom = rootRect.top + rootRect.height;
     let bestPage = currentPage.value;
     let bestDist = Infinity;
+    const reached = [];
     for (const [pageNum, el] of pageToElement) {
       const rect = el.getBoundingClientRect();
       const dist = rootMid < rect.top ? rect.top - rootMid : rootMid > rect.bottom ? rootMid - rect.bottom : 0;
@@ -112,7 +145,9 @@ export function createPageVirtualization() {
         bestDist = dist;
         bestPage = pageNum;
       }
+      if (rect.top < rootBottom) reached.push(pageNum);
     }
+    markPagesViewed(reached);
     if (bestPage !== currentPage.value) {
       currentPage.value = bestPage;
     }
@@ -221,6 +256,7 @@ export function createPageVirtualization() {
     elementToPage.clear();
     pageToElement.clear();
     visiblePages.value = /* @__PURE__ */ new Set();
+    viewedPages.value = /* @__PURE__ */ new Set();
     pageMetas.value = [];
     scrollRoot = null;
   }
@@ -228,6 +264,10 @@ export function createPageVirtualization() {
     pageMetas,
     currentPage,
     renderedPages,
+    viewedPages,
+    allPagesRead,
+    markPageViewed,
+    resetViewedPages,
     isPageRendered,
     observePage,
     unobservePage,

package/dist/runtime/embed/bridge-client.d.ts

@@ -20,7 +20,8 @@ type EventHandler<E extends EventName> = (payload: EventPayloads[E]) => void;
  * Parent-page client that drives a `<KViewer>` instance running inside
  * an iframe. Wraps `postMessage` into a Promise-based RPC mirroring the
  * viewer's exposed methods, and surfaces iframe-emitted events
- * (`ready`, `formEditMode-changed`) via `on()`.
+ * (`ready`, `formEditMode-changed`, `viewedPages-changed`, `all-pages-read`)
+ * via `on()`.
  */
 export declare class KViewerEmbedClient {
     private readonly iframe;
@@ -52,6 +53,13 @@ export declare class KViewerEmbedClient {
     getFormEditMode(): Promise<boolean>;
     setFormEditMode(enabled: boolean): Promise<void>;
     toggleFormEditMode(): Promise<boolean>;
+    /** True once the user has viewed every page. For a push-style signal,
+     *  subscribe via `on('all-pages-read', …)` / `on('viewedPages-changed', …)`. */
+    allPagesRead(): Promise<boolean>;
+    /** Page numbers viewed so far, ascending. */
+    getViewedPages(): Promise<number[]>;
+    /** Clear viewed-page tracking, e.g. to restart a signing session. */
+    resetViewedPages(): Promise<void>;
     private call;
     private handleMessage;
 }

package/dist/runtime/embed/bridge-client.js

@@ -87,6 +87,19 @@ export class KViewerEmbedClient {
   toggleFormEditMode() {
     return this.call("toggleFormEditMode");
   }
+  /** True once the user has viewed every page. For a push-style signal,
+   *  subscribe via `on('all-pages-read', …)` / `on('viewedPages-changed', …)`. */
+  allPagesRead() {
+    return this.call("allPagesRead");
+  }
+  /** Page numbers viewed so far, ascending. */
+  getViewedPages() {
+    return this.call("getViewedPages");
+  }
+  /** Clear viewed-page tracking, e.g. to restart a signing session. */
+  resetViewedPages() {
+    return this.call("resetViewedPages");
+  }
   // ── internals ──────────────────────────────────────────────────────────
   call(method, ...args) {
     if (this.disposed) {

package/dist/runtime/embed/bridge-host.d.ts

@@ -26,6 +26,9 @@ export interface KViewerApi {
     formEditMode: Ref<boolean>;
     setFormEditMode: (enabled: boolean) => void;
     toggleFormEditMode: () => boolean;
+    allPagesRead: () => boolean;
+    getViewedPages: () => number[];
+    resetViewedPages: () => void;
 }
 export interface KViewerEmbedBridgeOptions {
     /**

package/dist/runtime/embed/bridge-host.js

@@ -75,6 +75,13 @@ export function useKViewerEmbedBridge(viewerRef, options) {
       }
       case "toggleFormEditMode":
         return viewer.toggleFormEditMode();
+      case "allPagesRead":
+        return viewer.allPagesRead();
+      case "getViewedPages":
+        return viewer.getViewedPages();
+      case "resetViewedPages":
+        viewer.resetViewedPages();
+        return void 0;
       default:
         throw new Error(`Unknown KViewer embed method: ${req.method}`);
     }
@@ -110,17 +117,32 @@ export function useKViewerEmbedBridge(viewerRef, options) {
     target.postMessage(reply, event.origin === "" ? options.parentOrigin : event.origin);
   }
   win.addEventListener("message", handleMessage);
-  let stopFormEditWatch = null;
+  let stopViewerStateWatches = [];
   const stopViewerWatch = watch(
     viewerRef,
     (viewer) => {
-      stopFormEditWatch?.();
-      stopFormEditWatch = null;
+      for (const stop of stopViewerStateWatches) stop();
+      stopViewerStateWatches = [];
       if (!viewer) return;
       postEvent("ready", { protocolVersion: KVIEWER_EMBED_PROTOCOL_VERSION });
-      stopFormEditWatch = watch(
-        viewer.formEditMode,
-        (enabled) => postEvent("formEditMode-changed", { enabled })
+      stopViewerStateWatches.push(
+        watch(
+          viewer.formEditMode,
+          (enabled) => postEvent("formEditMode-changed", { enabled })
+        ),
+        // Read-tracking. The getters touch the viewer's reactive viewed-pages
+        // state, so watch re-runs them whenever a page is viewed or tracking
+        // is reset.
+        watch(
+          () => viewer.allPagesRead(),
+          (read, prev) => {
+            if (read && !prev) postEvent("all-pages-read", {});
+          }
+        ),
+        watch(
+          () => viewer.getViewedPages(),
+          (pages) => postEvent("viewedPages-changed", { pages, allRead: viewer.allPagesRead() })
+        )
       );
     },
     { immediate: true }
@@ -128,8 +150,8 @@ export function useKViewerEmbedBridge(viewerRef, options) {
   function unmount() {
     win.removeEventListener("message", handleMessage);
     stopViewerWatch();
-    stopFormEditWatch?.();
-    stopFormEditWatch = null;
+    for (const stop of stopViewerStateWatches) stop();
+    stopViewerStateWatches = [];
   }
   onScopeDispose(unmount);
   return { unmount };

package/dist/runtime/embed/protocol.d.ts

@@ -59,6 +59,18 @@ export interface MethodSignatures {
         args: [];
         result: boolean;
     };
+    allPagesRead: {
+        args: [];
+        result: boolean;
+    };
+    getViewedPages: {
+        args: [];
+        result: number[];
+    };
+    resetViewedPages: {
+        args: [];
+        result: undefined;
+    };
 }
 export type MethodName = keyof MethodSignatures;
 export interface RequestMessage<M extends MethodName = MethodName> {
@@ -91,6 +103,15 @@ export interface EventPayloads {
     'formEditMode-changed': {
         enabled: boolean;
     };
+    /** The set of viewed pages changed. `allRead` is true once every page has
+     *  been viewed. */
+    'viewedPages-changed': {
+        pages: number[];
+        allRead: boolean;
+    };
+    /** Fires once when the final unseen page is viewed. Re-arms after
+     *  `resetViewedPages()` or a new document. */
+    'all-pages-read': Record<string, never>;
 }
 export type EventName = keyof EventPayloads;
 export interface EventMessage<E extends EventName = EventName> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kviewer",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Kabema PDF Editor",
   "repository": "kabema/kviewer",
   "license": "MIT",