kviewer 0.2.0 → 0.2.2

package/dist/runtime/components/PdfPage.vue

@@ -16,6 +16,15 @@
       ref="canvasRef"
       :style="{ display: 'block', width: cssWidth + 'px', height: cssHeight + 'px' }"
     />
+    <!-- Crisp viewport-window raster: when the full page would blow the
+         canvas budget at high zoom, the base canvas above is only a
+         low-res fallback and this canvas renders just the visible region
+         (plus margin) at full resolution. -->
+    <canvas
+      v-show="windowCanvasVisible"
+      ref="windowCanvasRef"
+      :style="windowCanvasStyle"
+    />
     <div
       ref="textLayerRef"
       class="kviewer-text-layer textLayer"
@@ -33,6 +42,16 @@
       :pointer-events="formFieldPointerEvents"
       :z-index="formFieldZIndex"
     />
+    <!-- transform: translateZ(0) isolates the Konva canvases in their own
+         compositing layer: per-frame canvas updates during annotation
+         drags then only re-upload the (budget-capped) Konva texture
+         instead of triggering an iPadOS re-rasterization of the subtree
+         containing the much larger PDF canvases. -->
+    <!-- overflow: hidden — between a zoom commit and the async Konva
+         re-init the old (differently sized) stage briefly overflows this
+         div; unclipped it inflates the zoom wrapper's scrollHeight and
+         the panzoom clamps against phantom bounds, leaving the page
+         resting out of position. -->
     <div
       ref="annotationRef"
       class="kviewer-annotation-layer"
@@ -43,7 +62,9 @@
   width: cssWidth + 'px',
   height: cssHeight + 'px',
   zIndex: 3,
-  pointerEvents: annotationPointerEvents
+  pointerEvents: annotationPointerEvents,
+  transform: 'translateZ(0)',
+  overflow: 'hidden'
 }"
     />
   </div>
@@ -58,21 +79,35 @@ import { usePageProxyCache } from "../composables/usePageProxyCache";
 import { useFormFields } from "../composables/useFormFields";
 import { useShapeDetection } from "../composables/useShapeDetection";
 import { AnnotationType } from "../annotation/engine/types";
+import { isIPad } from "../annotation/engine/input-device";
+import { extractSignedSignatureAppearancesForPage } from "../annotation/pdf-import/extract_stamp_appearance";
+import { pageTransformFromProxy } from "../annotation/pdf-import/transform";
+import {
+  clampRenderScale,
+  DEFAULT_MAX_CANVAS_PIXELS,
+  IOS_MAX_CANVAS_PIXELS
+} from "../composables/canvas-limits";
 import FormFieldLayer from "./FormFieldLayer.vue";
 const PDFJS_ANNOTATION_MODE_DISABLE = 0;
 const props = defineProps({
   pageNumber: { type: Number, required: true },
   pageMeta: { type: Object, required: true },
   scale: { type: Number, required: true },
-  renderQuality: { type: Number, required: false, default: 1 }
+  renderQuality: { type: Number, required: false, default: 1 },
+  viewWindow: { type: [Object, null], required: false, default: null }
 });
 const canvasRef = ref(null);
+const windowCanvasRef = ref(null);
+const windowCanvasVisible = ref(false);
+const windowCanvasStyle = ref({});
 const textLayerRef = ref(null);
 const annotationRef = ref(null);
 const runtimeConfig = useRuntimeConfig();
 const minRenderPixelRatio = Number(
   runtimeConfig.public.kviewer?.minRenderPixelRatio ?? 2
 );
+const isAppleMobile = typeof navigator !== "undefined" && (isIPad() || /iPhone|iPod/.test(navigator.userAgent));
+const maxCanvasPixels = isAppleMobile ? IOS_MAX_CANVAS_PIXELS : DEFAULT_MAX_CANVAS_PIXELS;
 const state = useViewerState();
 const search = useViewerSearch();
 const proxyCache = usePageProxyCache();
@@ -80,6 +115,11 @@ const formFields = useFormFields();
 const shapeDetection = useShapeDetection();
 const pageProxy = shallowRef(null);
 let currentRenderTask = null;
+let windowRenderTask = null;
+let windowed = false;
+let renderedWindowKey = null;
+const FALLBACK_MAX_CANVAS_PIXELS = 4e6;
+const WINDOW_MAX_CANVAS_PIXELS = 8e6;
 let textLayer = null;
 const baseWidth = props.pageMeta.width;
 const baseHeight = props.pageMeta.height;
@@ -109,8 +149,8 @@ onMounted(async () => {
   await renderTextLayer();
   initKonva();
   if (pageProxy.value) {
-    const rawAnnotations = await pageProxy.value.getAnnotations();
-    formFields.parsePageFields(props.pageNumber, rawAnnotations);
+    rawPageAnnotations = await pageProxy.value.getAnnotations();
+    formFields.parsePageFields(props.pageNumber, rawPageAnnotations);
   }
   if (state.shapeDetection.value && pageProxy.value) {
     const viewport = pageProxy.value.getViewport({ scale: props.scale });
@@ -129,6 +169,27 @@ onMounted(async () => {
     }
   }
 });
+let rawPageAnnotations = null;
+const attemptedSignatureSeedIds = /* @__PURE__ */ new Set();
+const pendingSignedSignatureKey = computed(() => formFields.getFieldsForPage(props.pageNumber).filter((def) => def.fieldType === "signature" && def.signedInSource && formFields.getFieldValue(def.id)?.value === "").map((def) => def.id).join(","));
+watch(pendingSignedSignatureKey, (key) => {
+  if (key !== "") void seedSignedSignatureAppearances();
+});
+async function seedSignedSignatureAppearances() {
+  if (!pageProxy.value || !rawPageAnnotations) return;
+  const pending = formFields.getFieldsForPage(props.pageNumber).filter((def) => def.fieldType === "signature" && def.signedInSource && formFields.getFieldValue(def.id)?.value === "" && !attemptedSignatureSeedIds.has(def.id));
+  if (pending.length === 0) return;
+  for (const def of pending) attemptedSignatureSeedIds.add(def.id);
+  const appearances = await extractSignedSignatureAppearancesForPage(
+    pageProxy.value,
+    pageTransformFromProxy(pageProxy.value),
+    rawPageAnnotations
+  );
+  for (const def of pending) {
+    const appearance = appearances.get(def.id);
+    if (appearance) formFields.setFieldValue(def.id, appearance.dataUrl);
+  }
+}
 watch(
   () => state.shapeDetection.value,
   async (enabled) => {
@@ -151,10 +212,22 @@ watch(
 );
 watch(
   () => props.scale,
-  async () => {
+  async (newScale, oldScale) => {
     if (!pageProxy.value) return;
+    if (windowCanvasVisible.value && oldScale && newScale !== oldScale) {
+      const r = newScale / oldScale;
+      const s = windowCanvasStyle.value;
+      windowCanvasStyle.value = {
+        ...s,
+        left: Number.parseFloat(s.left ?? "0") * r + "px",
+        top: Number.parseFloat(s.top ?? "0") * r + "px",
+        width: Number.parseFloat(s.width ?? "0") * r + "px",
+        height: Number.parseFloat(s.height ?? "0") * r + "px"
+      };
+      renderedWindowKey = null;
+    }
     shapeDetection.clearShapeCache(props.pageNumber);
-    await renderCanvas();
+    await renderCanvas({ doubleBuffer: true });
     updateTextLayer();
     if (state.painter.value) {
       state.painter.value.destroyCanvasForPage(props.pageNumber);
@@ -183,9 +256,16 @@ async function renderCanvas(opts) {
   }
   const dpr = Math.max(window.devicePixelRatio || 1, minRenderPixelRatio);
   const quality = props.renderQuality ?? 1;
-  const viewport = proxy.getViewport({
-    scale: props.scale * quality * dpr
-  });
+  const desiredScale = props.scale * quality * dpr;
+  const fullScale = clampRenderScale(desiredScale, baseWidth, baseHeight, maxCanvasPixels);
+  windowed = fullScale < desiredScale * 0.999;
+  const renderScale = windowed ? clampRenderScale(
+    desiredScale,
+    baseWidth,
+    baseHeight,
+    Math.min(FALLBACK_MAX_CANVAS_PIXELS, maxCanvasPixels)
+  ) : fullScale;
+  const viewport = proxy.getViewport({ scale: renderScale });
   if (opts?.doubleBuffer) {
     const tmp = document.createElement("canvas");
     tmp.width = viewport.width;
@@ -225,7 +305,84 @@ async function renderCanvas(opts) {
       currentRenderTask = null;
     }
   }
+  if (windowed) {
+    void renderWindowCanvas();
+  } else {
+    hideWindowCanvas();
+  }
+}
+function hideWindowCanvas() {
+  windowCanvasVisible.value = false;
+  renderedWindowKey = null;
+  const c = windowCanvasRef.value;
+  if (c && c.width > 0) {
+    c.width = 0;
+    c.height = 0;
+  }
 }
+async function renderWindowCanvas() {
+  const proxy = pageProxy.value;
+  const canvas = windowCanvasRef.value;
+  const win = props.viewWindow;
+  if (!proxy || !canvas || !win || !windowed) return;
+  const x = Math.max(0, Math.min(win.x, cssWidth.value));
+  const y = Math.max(0, Math.min(win.y, cssHeight.value));
+  const w = Math.min(win.x + win.width, cssWidth.value) - x;
+  const h = Math.min(win.y + win.height, cssHeight.value) - y;
+  if (w <= 0 || h <= 0) return;
+  const key = [x, y, w, h, props.scale].map((n) => Math.round(n)).join(",");
+  if (key === renderedWindowKey && windowCanvasVisible.value) return;
+  const dpr = window.devicePixelRatio || 1;
+  const renderScale = clampRenderScale(
+    props.scale * dpr,
+    w / props.scale,
+    h / props.scale,
+    Math.min(WINDOW_MAX_CANVAS_PIXELS, maxCanvasPixels)
+  );
+  const k = renderScale / props.scale;
+  const viewport = proxy.getViewport({ scale: renderScale });
+  windowRenderTask?.cancel();
+  await currentRenderTask?.promise.catch(() => {
+  });
+  const tmp = document.createElement("canvas");
+  tmp.width = Math.floor(w * k);
+  tmp.height = Math.floor(h * k);
+  try {
+    windowRenderTask = proxy.render({
+      canvasContext: tmp.getContext("2d"),
+      viewport,
+      transform: [1, 0, 0, 1, -x * k, -y * k],
+      annotationMode: PDFJS_ANNOTATION_MODE_DISABLE
+    });
+    await windowRenderTask.promise;
+    canvas.width = tmp.width;
+    canvas.height = tmp.height;
+    canvas.getContext("2d").drawImage(tmp, 0, 0);
+    windowCanvasStyle.value = {
+      position: "absolute",
+      left: x + "px",
+      top: y + "px",
+      width: w + "px",
+      height: h + "px"
+    };
+    windowCanvasVisible.value = true;
+    renderedWindowKey = key;
+  } catch (e) {
+    if (e instanceof Error && e.message?.includes("Rendering cancelled")) return;
+    console.warn("[KViewer] Window render failed:", e);
+  } finally {
+    windowRenderTask = null;
+    tmp.width = 0;
+    tmp.height = 0;
+  }
+}
+watch(
+  () => props.viewWindow,
+  (win) => {
+    if (windowed) void renderWindowCanvas();
+    state.painter.value?.setStageWindow(props.pageNumber, win ?? null);
+  }
+);
 function initKonva() {
   if (!annotationRef.value || !state.painter.value) return;
   state.painter.value.initCanvasForPage(
@@ -235,6 +392,9 @@ function initKonva() {
     baseHeight,
     props.scale
   );
+  if (props.viewWindow) {
+    state.painter.value.setStageWindow(props.pageNumber, props.viewWindow);
+  }
 }
 async function renderTextLayer() {
   const container = textLayerRef.value;
@@ -279,6 +439,7 @@ function updateTextLayer() {
 }
 onBeforeUnmount(() => {
   currentRenderTask?.cancel();
+  windowRenderTask?.cancel();
   textLayer?.cancel();
   textLayer = null;
   search.unregisterPageLayer(props.pageNumber);

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

@@ -6,9 +6,25 @@ type __VLS_Props = {
     /** Canvas internal resolution multiplier (CSS size unchanged).
      *  Used by panzoom to sharpen the PDF when visually zoomed in. */
     renderQuality?: number;
+    /** Visible region of this page in page-CSS coordinates (already
+     *  includes margin), supplied by the viewer's panzoom. Drives the
+     *  viewport-window raster at high zoom. Null = unknown/inapplicable
+     *  (e.g. rotated pages), full-page rendering only. */
+    viewWindow?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
 };
 declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     renderQuality: number;
+    viewWindow: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const _default: typeof __VLS_export;
 export default _default;

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

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/PerfHud.vue

@@ -0,0 +1,97 @@
+<template>
+  <div v-if="enabled" class="perf-hud">
+    <div>fps {{ fps }} | p95 {{ p95 }}ms | max {{ maxGap }}ms</div>
+    <div>evt/s {{ evtRate }} | konva {{ drawPerSec }}ms/s | long {{ longSupported ? longMs + "ms/s" : "n/a" }}</div>
+    <div>{{ canvasInfo }}</div>
+    <button class="perf-hud-btn" @pointerdown.stop @click="noDraw = !noDraw">
+      konva draw: {{ noDraw ? "OFF" : "on" }}
+    </button>
+  </div>
+</template>
+
+<script setup>
+import { ref, onMounted, onBeforeUnmount } from "vue";
+import Konva from "konva";
+const enabled = ref(false);
+const fps = ref(0);
+const p95 = ref(0);
+const maxGap = ref(0);
+const evtRate = ref(0);
+const drawPerSec = ref(0);
+const longMs = ref(0);
+const longSupported = ref(false);
+const canvasInfo = ref("");
+const noDraw = ref(false);
+let raf = 0;
+let interval = 0;
+let last = 0;
+let gaps = [];
+let evtCount = 0;
+let drawMs = 0;
+let longTaskMs = 0;
+let po = null;
+let origDraw = null;
+function onAnyMove() {
+  evtCount++;
+}
+onMounted(() => {
+  enabled.value = new URLSearchParams(window.location.search).has("perf");
+  if (!enabled.value) return;
+  origDraw = Konva.Layer.prototype.drawScene;
+  Konva.Layer.prototype.drawScene = function(...args) {
+    if (noDraw.value) return this;
+    const t0 = performance.now();
+    const r = origDraw.apply(this, args);
+    drawMs += performance.now() - t0;
+    return r;
+  };
+  window.addEventListener("pointermove", onAnyMove, { capture: true, passive: true });
+  window.addEventListener("touchmove", onAnyMove, { capture: true, passive: true });
+  try {
+    po = new PerformanceObserver((list) => {
+      for (const e of list.getEntries()) longTaskMs += e.duration;
+    });
+    po.observe({ type: "longtask" });
+    longSupported.value = true;
+  } catch {
+    longSupported.value = false;
+  }
+  const tick = (t) => {
+    if (last) gaps.push(t - last);
+    last = t;
+    raf = requestAnimationFrame(tick);
+  };
+  raf = requestAnimationFrame(tick);
+  interval = window.setInterval(() => {
+    const sorted = [...gaps].sort((a, b) => a - b);
+    const total = gaps.reduce((s, g) => s + g, 0);
+    fps.value = total > 0 ? Math.round(gaps.length / total * 1e3) : 0;
+    p95.value = Math.round(sorted[Math.floor(sorted.length * 0.95)] ?? 0);
+    maxGap.value = Math.round(sorted[sorted.length - 1] ?? 0);
+    evtRate.value = evtCount;
+    drawPerSec.value = Math.round(drawMs);
+    longMs.value = Math.round(longTaskMs);
+    gaps = [];
+    evtCount = 0;
+    drawMs = 0;
+    longTaskMs = 0;
+    const pageEl = document.querySelector(".kviewer-page");
+    if (pageEl) {
+      canvasInfo.value = [...pageEl.querySelectorAll(":scope > canvas, .konvajs-content canvas")].map((c) => `${c.width}x${c.height}`).join(" | ");
+    }
+  }, 1e3);
+});
+onBeforeUnmount(() => {
+  if (!enabled.value) return;
+  cancelAnimationFrame(raf);
+  clearInterval(interval);
+  window.removeEventListener("pointermove", onAnyMove, { capture: true });
+  window.removeEventListener("touchmove", onAnyMove, { capture: true });
+  po?.disconnect();
+  if (origDraw) Konva.Layer.prototype.drawScene = origDraw;
+});
+</script>
+
+<style scoped>
+.perf-hud{background:rgba(0,0,0,.8);border-radius:6px;color:#4ade80;font:11px/1.4 ui-monospace,monospace;left:50%;padding:4px 8px;pointer-events:none;position:fixed;text-align:center;top:4px;transform:translateX(-50%);white-space:nowrap;z-index:99999}.perf-hud-btn{background:#333;border:1px solid #666;border-radius:4px;color:#fff;font:inherit;margin-top:2px;padding:2px 8px;pointer-events:auto}
+</style>

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

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/runtime/components/ToolButton.vue

@@ -3,7 +3,8 @@
     v-if="tool"
     class="relative flex items-center justify-center w-8 h-8 rounded-md transition-colors cursor-pointer"
     :class="active ? 'bg-default text-highlighted' : 'text-muted hover:bg-default/50 hover:text-highlighted'"
-    :title="tool.name"
+    :title="toolLabel(tool.name)"
+    :data-testid="`tool-${tool.name}`"
     @click="$emit('click')"
   >
     <UIcon :name="tool.icon" class="text-lg" />
@@ -17,6 +18,8 @@
 </template>
 
 <script setup>
+import { useKviewerI18n } from "../composables/useKviewerI18n";
+const { toolLabel } = useKviewerI18n();
 defineProps({
   tool: { type: null, required: true },
   active: { type: Boolean, required: true },

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

@@ -2,6 +2,9 @@ import { type ViewMode } from '../composables/useViewerState.js';
 import type { AddFormFieldPayload, FormFieldDefinition, IAnnotationStore, StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
 import { type ExportPdfOptions } from '../annotation/pdf-export/export.js';
 import type { ViewerMenuItem } from '../menu-items.js';
+import type { ViewerToolEntry } from '../toolbar-tools.js';
+import { type KviewerMessageOverrides } from '../composables/useKviewerI18n.js';
+import { type KviewerLocale } from '../i18n/messages.js';
 type __VLS_Props = {
     source: string | Uint8Array | object;
     textLayer?: boolean;
@@ -45,6 +48,19 @@ type __VLS_Props = {
      *  toggles or actions without replacing the entire header. Ignored
      *  when the host supplies a custom `#header` slot. */
     menuItems?: ViewerMenuItem[];
+    /** Configures which toolbar tools render and in what order. Entries are
+     *  built-in tool IDs (strings) or `{ type: 'slot', ... }` objects that
+     *  inject a custom button via a `#tool-<name>` slot. When omitted, the
+     *  default toolbar is rendered unchanged. Ignored when the host supplies
+     *  a custom `#header` slot. See {@link ViewerToolEntry}. */
+    tools?: ViewerToolEntry[];
+    /** UI language for built-in viewer strings (toolbar, search, modals,
+     *  form sidebar). Defaults to the `kviewer.locale` module option, then
+     *  'en'. Hosts with their own i18n just bind their active locale. */
+    locale?: KviewerLocale;
+    /** Per-string overrides for built-in messages — wins over the locale
+     *  catalog. Useful for app-specific wording without forking locales. */
+    messages?: KviewerMessageOverrides;
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -55,11 +71,15 @@ declare function importAnnotations(annotations: IAnnotationStore[], options?: {
     skipped: number;
 }>;
 declare function getKonvaCanvasState(): Record<number, string>;
-declare var __VLS_1: {}, __VLS_51: {};
+declare var __VLS_1: {}, __VLS_11: string, __VLS_12: {
+    state: import("../composables/useViewerState.js").ViewerState;
+}, __VLS_62: {};
 type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_11>]?: (props: typeof __VLS_12) => any;
+} & {
     header?: (props: typeof __VLS_1) => any;
 } & {
-    footer?: (props: typeof __VLS_51) => any;
+    footer?: (props: typeof __VLS_62) => any;
 };
 declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     getAnnotations: () => IAnnotationStore[];
@@ -84,12 +104,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;
@@ -97,6 +129,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     readonly: boolean;
     active: boolean;
     menuItems: ViewerMenuItem[];
+    tools: ViewerToolEntry[];
     scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
@@ -105,6 +138,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     formEditMode: boolean;
     roleColors: Record<string, string>;
     activeRoleId: string | null;
+    locale: KviewerLocale;
+    messages: KviewerMessageOverrides;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;