kviewer 0.0.11 → 0.1.1

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

@@ -1,5 +1,5 @@
 import { type Ref, type ShallowRef } from 'vue';
-import type { CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload } from '../annotation/engine/types.js';
+import type { AddFormFieldPayload, CheckboxStyle, DetectedShape, FormFieldDefinition, FormFieldValue, PlaceFieldPayload } from '../annotation/engine/types.js';
 export interface FormFieldsState {
     /** Field definitions grouped by page number */
     fieldDefinitions: ShallowRef<Map<number, FormFieldDefinition[]>>;
@@ -23,10 +23,16 @@ export interface FormFieldsState {
     registerDetectedCheckboxes: (pageNumber: number, shapes: DetectedShape[], scale: number, pageHeight: number) => void;
     /** Add a user-placed form field (from the placement tool). Returns the created def. */
     addPlacedField: (payload: PlaceFieldPayload) => FormFieldDefinition;
-    /** Update a placed field's rect, name, or flags. */
+    /** Add a form field programmatically. Public API counterpart to
+     *  `addPlacedField` with full control over the field's properties.
+     *  Returns the created definition. */
+    addFormField: (payload: AddFormFieldPayload) => FormFieldDefinition;
+    /** Update a form field's rect, name, or flags. */
     updatePlacedField: (id: string, patch: Partial<FormFieldDefinition>) => void;
-    /** Remove a placed field and its value. */
+    /** Remove a form field and its value. */
     removePlacedField: (id: string) => void;
+    /** All form-field definitions, flattened across pages. */
+    getAllFields: () => FormFieldDefinition[];
     /** All user-placed field definitions (used by export). */
     getPlacedFields: () => FormFieldDefinition[];
     /** Look up a field definition by id (any origin). */
@@ -35,6 +41,19 @@ export interface FormFieldsState {
     selectedPlacedFieldId: Ref<string | null>;
     /** Select or deselect a placed field. Pass null to deselect. */
     selectPlacedField: (id: string | null) => void;
+    /** Opaque role id new placements are auto-tagged with. The host owns
+     *  what roles exist; the editor only carries the active id forward to
+     *  newly placed fields and looks up its color via roleColors. */
+    activeRoleId: Ref<string | null>;
+    /** Set or clear the active role for upcoming placements. */
+    setActiveRole: (id: string | null) => void;
+    /** Map from roleId → CSS color, supplied by the host via the KViewer
+     *  `roleColors` prop. Reading this drives the chrome and placement
+     *  preview color. The editor never mutates role definitions itself. */
+    roleColors: ShallowRef<Record<string, string>>;
+    /** Replace the host-provided color map. Called by KViewer when the
+     *  prop changes. */
+    setRoleColors: (colors: Record<string, string>) => void;
     /** Apply checkbox-style hints (extracted from `/MK /CA` in the source PDF)
      *  to existing parsed checkbox defs and store the map for any defs
      *  parsed afterwards. Keyed by checkbox fieldName. */
@@ -48,8 +67,26 @@ export interface FormFieldsState {
      *  that calls this re-runs when any signature is signed or its lock
      *  rule changes. */
     isFieldLocked: (fieldId: string) => boolean;
+    /** Install a sink that is invoked synchronously for every field-value
+     *  write driven by user interaction. Used by the scripting bridge to
+     *  forward changes into `pdfDoc.annotationStorage` and dispatch into
+     *  the JS sandbox. The sink is NOT called for inbound updates from
+     *  [[applyFieldValueFromExternal]] (those originate from the sandbox
+     *  itself, so re-firing would create a ping-pong loop). */
+    setValueWriteSink: (sink: ValueWriteSink | null) => void;
+    /** Apply a value coming from outside Vue's reactive flow (e.g. the
+     *  PDF scripting sandbox dispatching `updatefromsandbox`). Updates
+     *  `fieldValues` and triggers rerender. Idempotent: a write that
+     *  matches the current value is a no-op (prevents redundant renders
+     *  from the sandbox's own sibling-mirror events). Skips non-parsed
+     *  fields (placed/detected don't exist in the PDF object model so
+     *  the sandbox can't legitimately address them). */
+    applyFieldValueFromExternal: (fieldId: string, value: string | boolean | string[]) => void;
     /** Clear all values and definitions (for document change) */
     reset: () => void;
 }
+/** Sink signature used by [[setValueWriteSink]]. Receives every user-driven
+ *  field value write (the primary id AND each mirrored sibling). */
+export type ValueWriteSink = (fieldId: string, value: string | boolean | string[]) => void;
 export declare function provideFormFields(): FormFieldsState;
 export declare function useFormFields(): FormFieldsState;

package/dist/runtime/composables/useFormFields.js

@@ -12,6 +12,14 @@ export function provideFormFields() {
   const fieldDefinitions = shallowRef(/* @__PURE__ */ new Map());
   const fieldValues = shallowRef(/* @__PURE__ */ new Map());
   const selectedPlacedFieldId = ref(null);
+  const activeRoleId = ref(null);
+  const roleColors = shallowRef({});
+  function setActiveRole(id) {
+    activeRoleId.value = id;
+  }
+  function setRoleColors(colors) {
+    roleColors.value = colors;
+  }
   function selectPlacedField(id) {
     selectedPlacedFieldId.value = id;
   }
@@ -23,6 +31,10 @@ export function provideFormFields() {
     }
     return void 0;
   }
+  let valueWriteSink = null;
+  function setValueWriteSink(sink) {
+    valueWriteSink = sink;
+  }
   let checkboxStyleMap = null;
   let buttonCaptionMap = null;
   function applyCheckboxStyles(styles) {
@@ -104,22 +116,37 @@ export function provideFormFields() {
     const existing = fieldValues.value.get(fieldId);
     if (!existing) return;
     existing.value = value;
+    const sinkWrites = [[fieldId, value]];
     const { fieldName, fieldType } = existing;
     if (fieldName) {
       if (fieldType === "radio" && typeof value === "string" && value !== "") {
         for (const [id, fv] of fieldValues.value.entries()) {
           if (id !== fieldId && fv.fieldName === fieldName && fv.fieldType === "radio") {
             fv.value = "";
+            sinkWrites.push([id, ""]);
           }
         }
       } else if (fieldType !== "radio") {
         for (const [id, fv] of fieldValues.value.entries()) {
           if (id !== fieldId && fv.fieldName === fieldName && fv.fieldType === fieldType) {
             fv.value = value;
+            sinkWrites.push([id, value]);
           }
         }
       }
     }
+    if (valueWriteSink) {
+      for (const [id, v] of sinkWrites) valueWriteSink(id, v);
+    }
+    triggerRef(fieldValues);
+  }
+  function applyFieldValueFromExternal(fieldId, value) {
+    const existing = fieldValues.value.get(fieldId);
+    if (!existing) return;
+    const def = getFieldById(fieldId);
+    if (def && def.origin !== "parsed") return;
+    if (existing.value === value) return;
+    existing.value = value;
     triggerRef(fieldValues);
   }
   function getFieldValue(fieldId) {
@@ -231,6 +258,9 @@ export function provideFormFields() {
       required: false,
       origin: "placed"
     };
+    if (activeRoleId.value) {
+      def.roleId = activeRoleId.value;
+    }
     if (payload.fieldType === "radio") {
       def.buttonValue = nextRadioOptionValue(fieldName);
     }
@@ -256,6 +286,67 @@ export function provideFormFields() {
     }
     return def;
   }
+  function addFormField(payload) {
+    const id = `placed-${generateUUID()}`;
+    const fieldName = payload.fieldName ?? nextPlacedFieldName(payload.fieldType);
+    const def = {
+      id,
+      pageNumber: payload.pageNumber,
+      fieldType: payload.fieldType,
+      fieldName,
+      rect: [...payload.rect],
+      readOnly: payload.readOnly ?? false,
+      required: payload.required ?? false,
+      origin: "placed"
+    };
+    if (payload.roleId !== void 0) def.roleId = payload.roleId;
+    if (payload.defaultValue !== void 0) def.defaultValue = payload.defaultValue;
+    if (payload.fontSize !== void 0) def.fontSize = payload.fontSize;
+    if (payload.fontName !== void 0) def.fontName = payload.fontName;
+    if (payload.color !== void 0) def.color = payload.color;
+    if (payload.backgroundColor !== void 0) def.backgroundColor = payload.backgroundColor;
+    if (payload.textAlignment !== void 0) def.textAlignment = payload.textAlignment;
+    if (payload.fieldType === "radio") {
+      def.buttonValue = payload.buttonValue ?? nextRadioOptionValue(fieldName);
+    }
+    if (payload.fieldType === "checkbox") {
+      def.checkboxStyle = payload.checkboxStyle ?? "check";
+    }
+    if (payload.fieldType === "dropdown") {
+      def.combo = payload.combo ?? true;
+      def.options = payload.options ?? [{ exportValue: "Option 1", displayValue: "Option 1" }];
+      if (payload.multiSelect !== void 0) def.multiSelect = payload.multiSelect;
+    }
+    if (payload.fieldType === "text") {
+      if (payload.multiLine !== void 0) def.multiLine = payload.multiLine;
+      if (payload.password !== void 0) def.password = payload.password;
+      if (payload.comb !== void 0) def.comb = payload.comb;
+      if (payload.maxLen !== void 0) def.maxLen = payload.maxLen;
+    }
+    if (payload.fieldType === "signature") {
+      if (payload.promptText !== void 0) def.promptText = payload.promptText;
+      if (payload.lockAction !== void 0) def.lockAction = payload.lockAction;
+      if (payload.lockFieldNames !== void 0) def.lockFieldNames = payload.lockFieldNames;
+    }
+    const existingDefs = fieldDefinitions.value.get(payload.pageNumber) ?? [];
+    fieldDefinitions.value.set(payload.pageNumber, [...existingDefs, def]);
+    triggerRef(fieldDefinitions);
+    fieldValues.value.set(id, {
+      fieldId: id,
+      fieldName: def.fieldName,
+      fieldType: def.fieldType,
+      value: getDefaultValue(def)
+    });
+    triggerRef(fieldValues);
+    return def;
+  }
+  function getAllFields() {
+    const out = [];
+    for (const defs of fieldDefinitions.value.values()) {
+      for (const d of defs) out.push(d);
+    }
+    return out;
+  }
   function nextRadioOptionValue(groupName) {
     const used = /* @__PURE__ */ new Set();
     for (const defs of fieldDefinitions.value.values()) {
@@ -373,6 +464,7 @@ export function provideFormFields() {
     selectedPlacedFieldId.value = null;
     checkboxStyleMap = null;
     buttonCaptionMap = null;
+    valueWriteSink = null;
     triggerRef(fieldDefinitions);
     triggerRef(fieldValues);
   }
@@ -387,8 +479,10 @@ export function provideFormFields() {
     setFieldValueByName,
     registerDetectedCheckboxes,
     addPlacedField,
+    addFormField,
     updatePlacedField,
     removePlacedField,
+    getAllFields,
     getPlacedFields,
     getFieldById,
     selectedPlacedFieldId,
@@ -397,7 +491,13 @@ export function provideFormFields() {
     applyButtonCaptions,
     isFieldLocked,
     resetValues,
-    reset
+    reset,
+    setValueWriteSink,
+    applyFieldValueFromExternal,
+    activeRoleId,
+    setActiveRole,
+    roleColors,
+    setRoleColors
   };
   provide(FORM_FIELDS_KEY, state);
   return state;

package/dist/runtime/composables/useInertiaPanzoom.js

@@ -281,6 +281,7 @@ export function useInertiaPanzoom(options = {}) {
     }
     function onDown(e) {
       if (e.pointerType === "pen") return;
+      if (e.pointerType === "mouse") return;
       if (!gesturesEnabled) return;
       stopMomentum();
       setWillChangeActive(true);

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

@@ -2,6 +2,10 @@ import type { PDFDocumentProxy, PDFPageProxy } from 'pdfjs-dist';
 export interface PageProxyCache {
     setDocument: (doc: PDFDocumentProxy) => void;
     getPage: (pageNumber: number) => Promise<PDFPageProxy>;
+    /** Return a cached page proxy synchronously, or undefined if not resolved yet.
+     *  Used by the scripting viewer-adapter where PDFScriptingManager calls
+     *  `getPageView(idx).pdfPage` synchronously during page-open dispatch. */
+    getPageSync: (pageNumber: number) => PDFPageProxy | undefined;
     clear: () => void;
 }
 export declare function createPageProxyCache(maxSize?: number): PageProxyCache;

package/dist/runtime/composables/usePageProxyCache.js

@@ -60,7 +60,10 @@ export function createPageProxyCache(maxSize = DEFAULT_MAX_SIZE) {
     inflight.clear();
     doc = null;
   }
-  const cacheInstance = { setDocument, getPage, clear };
+  function getPageSync(pageNumber) {
+    return cache.get(pageNumber);
+  }
+  const cacheInstance = { setDocument, getPage, getPageSync, clear };
   provide(PAGE_PROXY_CACHE_KEY, cacheInstance);
   return cacheInstance;
 }

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

@@ -0,0 +1,29 @@
+import type { PDFDocumentProxy } from 'pdfjs-dist';
+import type { FormFieldsState } from './useFormFields.js';
+import { type ScriptingManager } from './useScriptingManager.js';
+export interface ScriptingBridge {
+    destroy: () => void;
+}
+export interface ScriptingBridgeOptions {
+    formFields: FormFieldsState;
+    scripting: ScriptingManager;
+    pdfDoc: PDFDocumentProxy;
+}
+/** Bridge between kviewer's reactive form-state, the PDF document's
+ *  AnnotationStorage (which the sandbox reads/writes), and the scripting
+ *  manager's event bus. Ownership rules:
+ *
+ *  - Outbound (user → sandbox): every `setFieldValue` write hits the
+ *    `valueWriteSink` we install. We mirror into AnnotationStorage AND
+ *    dispatch an `'Action'` (and `'Validate'` for text) event into the
+ *    sandbox so any field-AA script runs.
+ *
+ *  - Inbound (sandbox → UI): we subscribe to `updatefromsandbox` on the
+ *    event bus, translate the per-field-type payload back into kviewer's
+ *    primitive shape, and call `applyFieldValueFromExternal` (which is
+ *    sink-blind, so no ping-pong).
+ *
+ *  We also seed AnnotationStorage from current fieldValues at boot so
+ *  any pre-bridge user input survives the sandbox handshake.
+ */
+export declare function createScriptingBridge(opts: ScriptingBridgeOptions): ScriptingBridge;

package/dist/runtime/composables/useScriptingBridge.js

@@ -0,0 +1,74 @@
+import { getEventBus } from "./useScriptingManager.js";
+export function createScriptingBridge(opts) {
+  const { formFields, scripting, pdfDoc } = opts;
+  const storage = pdfDoc.annotationStorage;
+  const eventBus = getEventBus(scripting);
+  for (const fv of formFields.getAllFieldValues()) {
+    const def = formFields.getFieldById(fv.fieldId);
+    if (!def || def.origin !== "parsed") continue;
+    storage.setValue(fv.fieldId, toStorageShape(def.fieldType, fv.value));
+  }
+  formFields.setValueWriteSink((fieldId, value) => {
+    const def = formFields.getFieldById(fieldId);
+    if (!def || def.origin !== "parsed") return;
+    storage.setValue(fieldId, toStorageShape(def.fieldType, value));
+    scripting.dispatchFieldEvent(fieldId, "Action", value);
+    if (def.fieldType === "checkbox" || def.fieldType === "radio" || def.fieldType === "button") {
+      scripting.dispatchFieldEvent(fieldId, "Mouse Up", value);
+    }
+    if (def.fieldType === "text") {
+      scripting.dispatchFieldEvent(fieldId, "Validate", value);
+    }
+  });
+  const onUpdate = (evt) => {
+    const detail = evt?.detail;
+    if (!detail) return;
+    const primaryId = detail.id ?? evt?.id;
+    if (!primaryId) return;
+    const siblings = Array.isArray(detail.siblings) ? detail.siblings : [];
+    const ids = [primaryId, ...siblings];
+    for (const id of ids) {
+      const def = formFields.getFieldById(id);
+      if (!def || def.origin !== "parsed") continue;
+      const kviewerValue = fromStorageShape(def.fieldType, detail);
+      if (kviewerValue === void 0) continue;
+      formFields.applyFieldValueFromExternal(id, kviewerValue);
+      storage.setValue(id, toStorageShape(def.fieldType, kviewerValue));
+    }
+  };
+  eventBus.on("kviewer-updatefromsandbox", onUpdate);
+  return {
+    destroy() {
+      eventBus.off("kviewer-updatefromsandbox", onUpdate);
+      formFields.setValueWriteSink(null);
+    }
+  };
+}
+function toStorageShape(fieldType, value) {
+  if (fieldType === "checkbox") return { value: Boolean(value) };
+  if (fieldType === "radio") return { value: typeof value === "string" ? value : "" };
+  if (fieldType === "dropdown") {
+    return { value };
+  }
+  if (fieldType === "text") return { value: String(value ?? "") };
+  if (fieldType === "signature") return { value: String(value ?? "") };
+  return { value };
+}
+function fromStorageShape(fieldType, detail) {
+  const value = detail?.value;
+  if (value === void 0) return void 0;
+  if (fieldType === "checkbox") {
+    if (typeof value === "boolean") return value;
+    return value !== "Off" && value !== "" && value != null;
+  }
+  if (fieldType === "radio") {
+    if (typeof value === "string") return value;
+    if (value == null) return "";
+    return String(value);
+  }
+  if (fieldType === "dropdown") {
+    if (Array.isArray(value)) return value.map(String);
+    return value == null ? "" : String(value);
+  }
+  return value == null ? "" : String(value);
+}

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

@@ -0,0 +1,65 @@
+import type { PDFDocumentProxy, PDFPageProxy } from 'pdfjs-dist';
+import type { Ref } from 'vue';
+/** Minimal viewer surface PDFScriptingManager calls into. The official
+ *  PDFViewer is large; we mock the slice the manager actually touches
+ *  (verified in pdfjs-dist/web/pdf_viewer.mjs lines 7548-7691 and 7639). */
+export interface ScriptingViewerAdapter {
+    currentPageNumber: number;
+    pagesCount: number;
+    pagesPromise: Promise<void>;
+    nextPage: () => void;
+    previousPage: () => void;
+    currentScaleValue: number | string;
+    increaseScale: () => void;
+    decreaseScale: () => void;
+    spreadMode: number;
+    readonly isInPresentationMode: boolean;
+    readonly isChangingPresentationMode: boolean;
+    getPageView: (idx: number) => {
+        renderingState: number;
+        pdfPage: PDFPageProxy;
+    } | undefined;
+}
+export interface ScriptingManagerDeps {
+    viewerState: {
+        currentPage: Ref<number>;
+        totalPages: Ref<number>;
+        scale: Ref<number>;
+        setScale: (v: number) => void;
+        scrollToPage: (n: number) => void;
+    };
+    virtualization: {
+        isPageRendered: (pageNumber: number) => boolean;
+    };
+    proxyCache: {
+        getPageSync: (pageNumber: number) => PDFPageProxy | undefined;
+    };
+}
+export interface ScriptingManager {
+    /** Pump a user-interaction event into the sandbox for a given field. */
+    dispatchFieldEvent: (fieldId: string, name: 'Action' | 'Validate' | 'Focus' | 'Blur' | 'Mouse Up' | 'Mouse Down' | 'Mouse Enter' | 'Mouse Exit' | 'Keystroke', value: string | boolean | string[], extra?: Record<string, unknown>) => void;
+    /** Notify the sandbox that a page finished rendering, so any deferred
+     *  PageOpen action can fire (pdf_viewer.mjs:7441). */
+    notifyPageRendered: (pageNumber: number) => void;
+    /** Bind a document to the sandbox. Safe to call repeatedly — pass
+     *  null to detach (e.g. before swapping documents). */
+    setDocument: (pdfDoc: PDFDocumentProxy | null) => Promise<void>;
+    /** Tear down the manager, sandbox worker, and event listeners.
+     *  Idempotent. */
+    destroy: () => Promise<void>;
+    /** True once the sandbox has booted for the current document. */
+    isReady: () => boolean;
+}
+/** Construct the scripting manager. ONE instance per `<Viewer>` lifetime —
+ *  reuse `setDocument(null)` then `setDocument(newDoc)` across document
+ *  swaps. PDFScriptingManagerComponents attaches a window-level
+ *  `updatefromsandbox` listener in its constructor (pdf_viewer.mjs:7733)
+ *  with no removal path; constructing it per-document would leak. */
+export declare function createScriptingManager(deps: ScriptingManagerDeps): Promise<ScriptingManager>;
+/** Cast helper used by the bridge — keeps the eventBus access narrowly
+ *  typed without exporting an extra interface. */
+export declare function getEventBus(manager: ScriptingManager): {
+    on: (name: string, handler: (...args: unknown[]) => void) => void;
+    off: (name: string, handler: (...args: unknown[]) => void) => void;
+    dispatch: (name: string, payload: unknown) => void;
+};

package/dist/runtime/composables/useScriptingManager.js

@@ -0,0 +1,123 @@
+export async function createScriptingManager(deps) {
+  const pdfViewer = await import("pdfjs-dist/web/pdf_viewer.mjs");
+  const { PDFScriptingManager, EventBus, RenderingStates } = pdfViewer;
+  const eventBus = new EventBus();
+  const onSandboxWindowEvent = (event) => {
+    const d = event.detail ?? {};
+    eventBus.dispatch("kviewer-updatefromsandbox", {
+      source: window,
+      detail: {
+        ...d,
+        // Re-attach id and siblings explicitly (spread preserves them now,
+        // but is defensive against future mutations between our snapshot
+        // and the bridge's handler).
+        id: d.id,
+        siblings: d.siblings
+      }
+    });
+  };
+  window.addEventListener("updatefromsandbox", onSandboxWindowEvent);
+  const sandboxBundleSrc = new URL("/_kviewer/pdfjs/pdf.sandbox.mjs", window.location.origin).href;
+  const adapter = {
+    get currentPageNumber() {
+      return deps.viewerState.currentPage.value;
+    },
+    set currentPageNumber(n) {
+      const clamped = Math.min(Math.max(1, n), deps.viewerState.totalPages.value);
+      deps.viewerState.scrollToPage(clamped);
+    },
+    get pagesCount() {
+      return deps.viewerState.totalPages.value;
+    },
+    // Pages are virtualized — there's no global "all pages loaded" gate
+    // analogous to the official viewer's `pagesPromise`. Resolve immediately;
+    // the manager only awaits it before dispatching 'print'.
+    pagesPromise: Promise.resolve(),
+    nextPage() {
+      const cur = deps.viewerState.currentPage.value;
+      if (cur < deps.viewerState.totalPages.value) deps.viewerState.scrollToPage(cur + 1);
+    },
+    previousPage() {
+      const cur = deps.viewerState.currentPage.value;
+      if (cur > 1) deps.viewerState.scrollToPage(cur - 1);
+    },
+    get currentScaleValue() {
+      return deps.viewerState.scale.value;
+    },
+    set currentScaleValue(v) {
+      const n = typeof v === "number" ? v : Number.parseFloat(v);
+      if (Number.isFinite(n)) deps.viewerState.setScale(n);
+    },
+    increaseScale() {
+      deps.viewerState.setScale(deps.viewerState.scale.value * 1.1);
+    },
+    decreaseScale() {
+      deps.viewerState.setScale(deps.viewerState.scale.value / 1.1);
+    },
+    spreadMode: 0,
+    isInPresentationMode: false,
+    isChangingPresentationMode: false,
+    getPageView(idx) {
+      const pageNumber = idx + 1;
+      const pdfPage = deps.proxyCache.getPageSync(pageNumber);
+      if (!pdfPage) return void 0;
+      return {
+        pdfPage,
+        renderingState: deps.virtualization.isPageRendered(pageNumber) ? RenderingStates.FINISHED : 0
+      };
+    }
+  };
+  const manager = new PDFScriptingManager({
+    eventBus,
+    sandboxBundleSrc,
+    // Required: PDFScriptingManager passes the result into the sandbox's
+    // docInfo. The official viewer assembles a rich metadata blob; we
+    // provide the minimum the sandbox needs to boot. Fields are read by
+    // PDF scripts via `this.<key>` (e.g. `this.numPages`).
+    docProperties: async (pdfDoc) => ({
+      numPages: pdfDoc.numPages,
+      URL: "",
+      baseURL: "",
+      filesize: 0,
+      filename: "",
+      metadata: "",
+      authors: ""
+    })
+  });
+  manager.setViewer(adapter);
+  return {
+    dispatchFieldEvent(fieldId, name, value, extra) {
+      eventBus.dispatch("dispatcheventinsandbox", {
+        source: window,
+        detail: {
+          id: fieldId,
+          name,
+          value,
+          willCommit: true,
+          commitKey: 1,
+          ...extra
+        }
+      });
+    },
+    notifyPageRendered(pageNumber) {
+      eventBus.dispatch("pagerendered", { source: window, pageNumber });
+    },
+    async setDocument(pdfDoc) {
+      await manager.setDocument(pdfDoc);
+    },
+    async destroy() {
+      window.removeEventListener("updatefromsandbox", onSandboxWindowEvent);
+      await manager.setDocument(null);
+      const dp = manager.destroyPromise;
+      if (dp) await dp;
+    },
+    isReady() {
+      return manager.ready;
+    },
+    // Expose for the bridge.
+    ...{ _eventBus: eventBus }
+  };
+}
+export function getEventBus(manager) {
+  return manager._eventBus;
+}

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

@@ -0,0 +1,58 @@
+import type { ExportPdfOptions } from '../annotation/pdf-export/export.js';
+import type { AddFormFieldPayload, FormFieldDefinition, FormFieldValue, IAnnotationStore } from '../annotation/engine/types.js';
+import { type EventName, type EventPayloads, type ImportAnnotationsMode } from './protocol.js';
+export interface KViewerEmbedClientOptions {
+    /**
+     * Origin of the iframe — used for postMessage `targetOrigin` AND as
+     * the inbound origin allowlist (responses/events from any other origin
+     * are dropped). Pass `'*'` for development only; production should pin
+     * a single origin.
+     */
+    iframeOrigin: string;
+    /**
+     * Optional override for the parent's window. Defaults to `window`.
+     * Useful for tests.
+     */
+    windowRef?: Window;
+}
+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()`.
+ */
+export declare class KViewerEmbedClient {
+    private readonly iframe;
+    private readonly options;
+    private readonly win;
+    private readonly allowAny;
+    private readonly pending;
+    private readonly handlers;
+    private disposed;
+    constructor(iframe: HTMLIFrameElement, options: KViewerEmbedClientOptions);
+    /** Tear down the message listener and reject any in-flight requests. */
+    dispose(): void;
+    /** Subscribe to an iframe-emitted event. Returns an unsubscribe fn. */
+    on<E extends EventName>(name: E, handler: EventHandler<E>): () => void;
+    getAnnotations(): Promise<IAnnotationStore[]>;
+    importAnnotations(annotations: IAnnotationStore[], options?: {
+        mode?: ImportAnnotationsMode;
+    }): Promise<{
+        loaded: number;
+        skipped: number;
+    }>;
+    exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
+    getFormFieldValues(): Promise<FormFieldValue[]>;
+    setFormFieldValue(fieldName: string, value: string | boolean | string[]): Promise<void>;
+    addFormField(payload: AddFormFieldPayload): Promise<FormFieldDefinition>;
+    updateFormField(id: string, patch: Partial<FormFieldDefinition>): Promise<void>;
+    removeFormField(id: string): Promise<void>;
+    getFormFields(): Promise<FormFieldDefinition[]>;
+    getFormEditMode(): Promise<boolean>;
+    setFormEditMode(enabled: boolean): Promise<void>;
+    toggleFormEditMode(): Promise<boolean>;
+    private call;
+    private handleMessage;
+}
+export {};