kviewer 0.2.1 → 0.2.2

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[];
@@ -109,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;
@@ -117,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;

package/dist/runtime/components/Viewer.vue

@@ -2,7 +2,11 @@
   <div ref="viewerRoot" class="flex flex-col h-full">
     <!-- Header slot: defaults to ViewerBar -->
     <slot name="header">
-      <ViewerBar :menu-items="props.menuItems" />
+      <ViewerBar :menu-items="props.menuItems" :tools="props.tools">
+        <template v-for="name in toolSlotNames" :key="name" #[name]="scope">
+          <slot :name="name" v-bind="scope" />
+        </template>
+      </ViewerBar>
     </slot>
 
     <div class="flex flex-1 min-h-0">
@@ -61,6 +65,7 @@
                     :page-number="singlePageMeta.pageNumber"
                     :page-meta="singlePageMeta"
                     :scale="pageScale"
+                    :view-window="pageViewWindow(singlePageMeta.pageNumber)"
                   />
                 </div>
               </div>
@@ -89,6 +94,7 @@
                     :page-number="meta.pageNumber"
                     :page-meta="meta"
                     :scale="pageScale"
+                    :view-window="pageViewWindow(meta.pageNumber)"
                   />
                 </div>
               </div>
@@ -122,6 +128,7 @@
                       :page-number="meta.pageNumber"
                       :page-meta="meta"
                       :scale="pageScale"
+                      :view-window="pageViewWindow(meta.pageNumber)"
                     />
                   </div>
                 </div>
@@ -133,6 +140,10 @@
 
       <ClientOnly>
         <FloatingPageIndicator :scroll-container="scrollContainer" />
+        <!-- Debug overlay for on-device profiling; renders only with
+             ?perf in the URL. Gated on `active` so tabbed hosts show a
+             single instance. -->
+        <PerfHud v-if="props.active" />
       </ClientOnly>
       </div>
 
@@ -181,14 +192,17 @@ import {
   nextTick,
   triggerRef,
   onMounted,
-  onBeforeUnmount
+  onBeforeUnmount,
+  useSlots
 } from "vue";
+import { useRuntimeConfig } from "#imports";
 import ViewerBar from "./ViewerBar.vue";
 import PdfPage from "./PdfPage.vue";
 import FreeTextModal from "./modals/FreeTextModal.vue";
 import PlacedFieldSidebar from "./panels/PlacedFieldSidebar.vue";
 import AnnotationToolbar from "./AnnotationToolbar.vue";
 import FloatingPageIndicator from "./FloatingPageIndicator.vue";
+import PerfHud from "./PerfHud.vue";
 import { providePageSettings } from "../composables/usePageSettings";
 import { mapViewModeToFitMode, normalizeZoom, provideViewerState } from "../composables/useViewerState";
 import { provideViewerSearch } from "../composables/useViewerSearch";
@@ -206,11 +220,13 @@ import { createPageProxyCache } from "../composables/usePageProxyCache";
 import { createSearchIndex } from "../composables/useSearchIndex";
 import { createShapeDetection } from "../composables/useShapeDetection";
 import { provideFormFields } from "../composables/useFormFields";
-import { extractCheckboxStyles, extractButtonCaptions } from "../annotation/parsers/extractCheckboxStyles";
+import { extractCheckboxStyles, extractButtonCaptions, extractSignedSignatureNames } from "../annotation/parsers/extractCheckboxStyles";
 import { isIPad } from "../annotation/engine/input-device";
 import { useInertiaPanzoom } from "../composables/useInertiaPanzoom";
 import { createScriptingManager } from "../composables/useScriptingManager";
 import { createScriptingBridge } from "../composables/useScriptingBridge";
+import { provideKviewerI18n } from "../composables/useKviewerI18n";
+import { KVIEWER_LOCALES } from "../i18n/messages";
 const props = defineProps({
   source: { type: null, required: true },
   textLayer: { type: Boolean, required: false },
@@ -227,12 +243,19 @@ const props = defineProps({
   roleColors: { type: Object, required: false, default: void 0 },
   activeRoleId: { type: [String, null], required: false, default: void 0 },
   scripting: { type: Boolean, required: false, default: false },
-  menuItems: { type: Array, required: false, default: void 0 }
+  menuItems: { type: Array, required: false, default: void 0 },
+  tools: { type: Array, required: false, default: void 0 },
+  locale: { type: null, required: false, default: void 0 },
+  messages: { type: Object, required: false, default: void 0 }
 });
+const slots = useSlots();
+const toolSlotNames = computed(
+  () => Object.keys(slots).filter((name) => name.startsWith("tool-"))
+);
 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();
+const { state: viewerState, setScrollToPageFn, setDownloadPdfFn, setApplyScaleFn } = provideViewerState();
 watchEffect(() => {
   viewerState.readonly.value = props.readonly ?? false;
 });
@@ -255,6 +278,14 @@ watch(
 );
 const viewerSearch = provideViewerSearch();
 const formFieldsState = provideFormFields();
+const kviewerPublicConfig = useRuntimeConfig().public.kviewer;
+provideKviewerI18n(
+  computed(() => {
+    const candidate = props.locale ?? kviewerPublicConfig?.locale ?? "en";
+    return KVIEWER_LOCALES.includes(candidate) ? candidate : "en";
+  }),
+  computed(() => props.messages ?? {})
+);
 watch(
   () => props.roleColors,
   (v) => {
@@ -295,6 +326,7 @@ const proxyCache = createPageProxyCache();
 const searchIndex = createSearchIndex();
 const shapeDetectionCache = createShapeDetection();
 const doc = shallowRef(null);
+let destroyActiveDoc = null;
 let painter = null;
 let scriptingManager = null;
 let scriptingBridge = null;
@@ -353,6 +385,116 @@ const isRotatedSideways = computed(() => {
 });
 const zoomWrapper = ref(null);
 const inertiaPanzoom = useInertiaPanzoom({ minScale: 0.5, maxScale: 4 });
+const MIN_ZOOM = 0.25;
+const MAX_ZOOM = 4;
+let suppressScaleReset = false;
+async function commitZoom(target) {
+  const s0 = viewerState.scale.value;
+  target = Math.min(Math.max(MAX_ZOOM, s0), Math.max(Math.min(MIN_ZOOM, s0), target));
+  const viewportEl = zoomWrapper.value?.parentElement ?? null;
+  const anchor = virtualization.getPageElement(viewerState.currentPage.value);
+  const visual = inertiaPanzoom.getScale();
+  if (target === viewerState.scale.value && Math.abs(visual - 1) < 5e-3) return;
+  if (!viewportEl || !anchor || !anchor.isConnected) {
+    viewerState.fitMode.value = "custom";
+    viewerState.scale.value = target;
+    return;
+  }
+  const vpRect = viewportEl.getBoundingClientRect();
+  const fx = vpRect.width / 2;
+  const fy = vpRect.height / 2;
+  const aRect = anchor.getBoundingClientRect();
+  const qx = (vpRect.left + fx - aRect.left) / aRect.width;
+  const qy = (vpRect.top + fy - aRect.top) / aRect.height;
+  suppressScaleReset = target !== viewerState.scale.value;
+  viewerState.fitMode.value = "custom";
+  viewerState.scale.value = target;
+  await nextTick();
+  const t = inertiaPanzoom.getTransform();
+  const vp2 = viewportEl.getBoundingClientRect();
+  const a2 = anchor.getBoundingClientRect();
+  const layoutLeft = (a2.left - vp2.left - t.tx) / t.scale;
+  const layoutTop = (a2.top - vp2.top - t.ty) / t.scale;
+  const layoutW = a2.width / t.scale;
+  const layoutH = a2.height / t.scale;
+  inertiaPanzoom.setTransform({
+    scale: 1,
+    tx: fx - (layoutLeft + qx * layoutW),
+    ty: fy - (layoutTop + qy * layoutH)
+  });
+  viewWindows.value = {};
+  computeViewWindows();
+}
+setApplyScaleFn((value) => {
+  void commitZoom(value);
+});
+watch(
+  () => viewerState.scale.value,
+  (s) => inertiaPanzoom.setScaleLimits(
+    Math.min(1, MIN_ZOOM / s),
+    Math.max(1, MAX_ZOOM / s)
+  ),
+  { immediate: true }
+);
+inertiaPanzoom.onZoomEnd((visual) => {
+  if (Math.abs(visual - 1) < 5e-3) return;
+  void commitZoom(viewerState.scale.value * visual);
+});
+const viewWindows = shallowRef({});
+const VIEW_WINDOW_MARGIN = 0.25;
+function computeViewWindows() {
+  const viewportEl = zoomWrapper.value?.parentElement;
+  if (!viewportEl) return;
+  const vpRect = viewportEl.getBoundingClientRect();
+  if (vpRect.width === 0 || vpRect.height === 0) return;
+  const prev = viewWindows.value;
+  const next = {};
+  let changed = false;
+  for (const meta of pageMetas.value) {
+    const el = virtualization.getPageElement(meta.pageNumber);
+    if (!el) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width === 0 || el.offsetWidth === 0) continue;
+    const k = r.width / el.offsetWidth;
+    const vx = (Math.max(vpRect.left, r.left) - r.left) / k;
+    const vy = (Math.max(vpRect.top, r.top) - r.top) / k;
+    const vr = (Math.min(vpRect.right, r.right) - r.left) / k;
+    const vb = (Math.min(vpRect.bottom, r.bottom) - r.top) / k;
+    if (vr <= vx || vb <= vy) continue;
+    const old = prev[meta.pageNumber];
+    if (old && vx >= old.x && vy >= old.y && vr <= old.x + old.width && vb <= old.y + old.height) {
+      next[meta.pageNumber] = old;
+      continue;
+    }
+    const mx = vpRect.width / k * VIEW_WINDOW_MARGIN;
+    const my = vpRect.height / k * VIEW_WINDOW_MARGIN;
+    next[meta.pageNumber] = {
+      x: vx - mx,
+      y: vy - my,
+      width: vr - vx + 2 * mx,
+      height: vb - vy + 2 * my
+    };
+    changed = true;
+  }
+  if (changed || Object.keys(next).length !== Object.keys(prev).length) {
+    viewWindows.value = next;
+  }
+}
+let viewWindowTimer = 0;
+let lastViewWindowUpdate = 0;
+inertiaPanzoom.onChange(() => {
+  const now = performance.now();
+  const wait = Math.max(0, 250 - (now - lastViewWindowUpdate));
+  clearTimeout(viewWindowTimer);
+  viewWindowTimer = window.setTimeout(() => {
+    lastViewWindowUpdate = performance.now();
+    computeViewWindows();
+  }, wait);
+});
+function pageViewWindow(pageNumber) {
+  if (pageSettings.rotation.value !== 0) return null;
+  return viewWindows.value[pageNumber] ?? null;
+}
 function pageSlotStyle(meta) {
   const s = pageScale.value;
   if (isRotatedSideways.value) {
@@ -449,26 +591,36 @@ async function loadDocument() {
     }
     const source = props.source;
     const baseParams = source instanceof Uint8Array || typeof source === "string" ? { url: typeof source === "string" ? source : void 0, data: source instanceof Uint8Array ? source : void 0 } : { ...source };
+    if (baseParams.data instanceof Uint8Array) {
+      baseParams.data = baseParams.data.slice();
+    } else if (baseParams.data instanceof ArrayBuffer) {
+      baseParams.data = baseParams.data.slice(0);
+    }
     const docParams = {
       ...baseParams,
       standardFontDataUrl: "/_kviewer/standard_fonts/",
       cMapUrl: "/_kviewer/cmaps/",
       cMapPacked: true,
-      useSystemFonts: true
+      useSystemFonts: true,
+      wasmUrl: "/_kviewer/wasm/",
+      iccUrl: "/_kviewer/iccs/"
     };
     const loadingTask = pdfjs.getDocument(docParams);
+    destroyActiveDoc = () => loadingTask.destroy();
     const pdfDoc = await loadingTask.promise;
     doc.value = pdfDoc;
     viewerState.doc.value = pdfDoc;
     viewerState.totalPages.value = pdfDoc.numPages;
     proxyCache.setDocument(pdfDoc);
     pdfDoc.getData().then(async (bytes) => {
-      const [styles, captions] = await Promise.all([
+      const [styles, captions, signedSigs] = await Promise.all([
         extractCheckboxStyles(bytes),
-        extractButtonCaptions(bytes)
+        extractButtonCaptions(bytes),
+        extractSignedSignatureNames(bytes)
       ]);
       if (styles.size > 0) formFieldsState.applyCheckboxStyles(styles);
       if (captions.size > 0) formFieldsState.applyButtonCaptions(captions);
+      if (signedSigs.size > 0) formFieldsState.applySignedSignatures(signedSigs);
     }).catch((err) => console.warn("[KViewer] Failed to read MK data from source PDF:", err));
     if (!scrollContainer.value) {
       await nextTick();
@@ -819,10 +971,18 @@ onMounted(() => {
       { immediate: true }
     );
     watch(() => viewerState.scale.value, async () => {
+      if (suppressScaleReset) {
+        suppressScaleReset = false;
+        return;
+      }
       await nextTick();
       inertiaPanzoom.reset();
+      viewWindows.value = {};
+      computeViewWindows();
+    });
+    watch(() => viewerState.currentPage.value, () => {
+      if (isSinglePageMode.value) inertiaPanzoom.reset();
     });
-    watch(() => viewerState.currentPage.value, () => inertiaPanzoom.reset());
   }
   if (isIPad()) {
     viewerState.setStylusMode(true);
@@ -843,7 +1003,7 @@ watch(
     searchIndex.destroy();
     virtualization.destroy();
     proxyCache.clear();
-    doc.value?.destroy();
+    void destroyActiveDoc?.();
     loadDocument();
   }
 );
@@ -875,6 +1035,7 @@ watch(
 );
 onBeforeUnmount(() => {
   window.removeEventListener("keydown", onGlobalKeydown);
+  clearTimeout(viewWindowTimer);
   scrollContainer.value?.removeEventListener("wheel", onWheel);
   inertiaPanzoom.detach();
   resizeObserver?.disconnect();
@@ -889,7 +1050,8 @@ onBeforeUnmount(() => {
   virtualization.destroy();
   proxyCache.clear();
   painter?.destroy();
-  doc.value?.destroy();
+  void destroyActiveDoc?.();
+  destroyActiveDoc = null;
 });
 defineExpose({
   getAnnotations: () => painter?.getData() ?? [],

package/dist/runtime/components/Viewer.vue.d.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[];
@@ -109,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;
@@ -117,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;

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

@@ -1,9 +1,29 @@
 import type { ViewerMenuItem } from '../menu-items.js';
+import { type ViewerToolEntry } from '../toolbar-tools.js';
 type __VLS_Props = {
     /** Extra items appended to the burger menu after the built-ins.
      *  See {@link ViewerMenuItem}. Pure forwarding from `<KViewer>`. */
     menuItems?: ViewerMenuItem[];
+    /** Configures which toolbar tools render and in what order. When
+     *  omitted, the default toolbar is rendered. See {@link ViewerToolEntry}. */
+    tools?: ViewerToolEntry[];
 };
-declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare var __VLS_109: string, __VLS_110: {
+    state: import("../composables/useViewerState.js").ViewerState;
+}, __VLS_154: string, __VLS_155: {
+    state: import("../composables/useViewerState.js").ViewerState;
+};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_109>]?: (props: typeof __VLS_110) => any;
+} & {
+    [K in NonNullable<typeof __VLS_154>]?: (props: typeof __VLS_155) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
 declare const _default: typeof __VLS_export;
 export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};