kviewer 0.1.0 → 0.1.1

package/dist/module.d.mts

@@ -1,5 +1,5 @@
 import * as _nuxt_schema from '@nuxt/schema';
-export { AddFormFieldPayload, CheckboxStyle, ExportPdfOptions, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, SignatureData, SignatureHandlers, ViewMode } from '../dist/runtime/public-types.js';
+export { AddFormFieldPayload, CheckboxStyle, ExportPdfOptions, FormFieldDefinition, FormFieldOrigin, FormFieldType, FormFieldValue, KVIEWER_EMBED_PROTOCOL_VERSION, KViewerApi, KViewerEmbedBridgeOptions, KViewerEmbedClient, KViewerEmbedClientOptions, KViewerEmbedEventName, KViewerEmbedEventPayloads, KViewerEmbedMethodName, SignatureData, SignatureHandlers, ViewMode, ViewerMenuButtonItem, ViewerMenuCheckboxItem, ViewerMenuItem, ViewerMenuSeparatorItem, useKViewerEmbedBridge } from '../dist/runtime/public-types.js';
 
 interface ModuleOptions {
     /**

package/dist/module.json

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

package/dist/module.mjs

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import { defineNuxtModule, createResolver, addPlugin, addComponentsDir } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, addPlugin, addComponentsDir, addImports } from '@nuxt/kit';
+export { KVIEWER_EMBED_PROTOCOL_VERSION, KViewerEmbedClient, useKViewerEmbedBridge } from '../dist/runtime/public-types.js';
 
 const module$1 = defineNuxtModule({
   meta: {
@@ -27,6 +28,11 @@ const module$1 = defineNuxtModule({
       prefix: options.prefix,
       ignore: ["color-mode/**", "content/**", "prose/**"]
     });
+    addImports([
+      { name: "useKViewerEmbedBridge", from: resolve("./runtime/embed/bridge-host") },
+      { name: "KViewerEmbedClient", from: resolve("./runtime/embed/bridge-client") },
+      { name: "KVIEWER_EMBED_PROTOCOL_VERSION", from: resolve("./runtime/embed/protocol") }
+    ]);
     const require_ = createRequire(import.meta.url);
     const pdfjsDir = dirname(require_.resolve("pdfjs-dist/package.json"));
     nuxt.hook("nitro:config", (nitroConfig) => {
@@ -41,6 +47,15 @@ const module$1 = defineNuxtModule({
           dir: join(pdfjsDir, "cmaps"),
           baseURL: "/_kviewer/cmaps",
           maxAge: 60 * 60 * 24 * 365
+        },
+        // PDF.js scripting sandbox bundle. Required when the viewer's
+        // `scripting` prop is enabled — the sandbox is a QuickJS WASM
+        // module that executes embedded PDF JavaScript (field AA scripts,
+        // calculate/format/validate, document/page-open actions).
+        {
+          dir: join(pdfjsDir, "legacy/build"),
+          baseURL: "/_kviewer/pdfjs",
+          maxAge: 60 * 60 * 24 * 365
         }
       );
     });

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

@@ -1,6 +1,7 @@
 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';
 type __VLS_Props = {
     source: string | Uint8Array | object;
     textLayer?: boolean;
@@ -31,6 +32,19 @@ type __VLS_Props = {
      *  drives this — typically by binding it to a role picker in its own
      *  UI. Supports v-model via `v-model:active-role-id`. */
     activeRoleId?: string | null;
+    /** Execute embedded JavaScript inside the PDF — field-level AA scripts
+     *  (Mouse Up, Calculate, Format, Validate, Keystroke), document-level
+     *  open actions, and page-level scripts. Powered by pdf.js's QuickJS
+     *  WASM sandbox (no DOM/network/host-JS escape), but arbitrary JS from
+     *  untrusted PDFs is still real attack surface — default is `false`.
+     *  Treated as read-once per document; toggling at runtime requires
+     *  changing the `source` prop or remounting the component. */
+    scripting?: boolean;
+    /** Extra items appended to the default burger menu (after Download
+     *  and the form-field-detection toggle). Use this to expose app-level
+     *  toggles or actions without replacing the entire header. Ignored
+     *  when the host supplies a custom `#header` slot. */
+    menuItems?: ViewerMenuItem[];
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -82,6 +96,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     zoom: number;
     readonly: boolean;
     active: boolean;
+    menuItems: ViewerMenuItem[];
+    scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;

package/dist/runtime/components/Viewer.vue

@@ -2,7 +2,7 @@
   <div ref="viewerRoot" class="flex flex-col h-full">
     <!-- Header slot: defaults to ViewerBar -->
     <slot name="header">
-      <ViewerBar />
+      <ViewerBar :menu-items="props.menuItems" />
     </slot>
 
     <div class="flex flex-1 min-h-0">
@@ -209,6 +209,8 @@ import { provideFormFields } from "../composables/useFormFields";
 import { extractCheckboxStyles, extractButtonCaptions } 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";
 const props = defineProps({
   source: { type: null, required: true },
   textLayer: { type: Boolean, required: false },
@@ -223,7 +225,9 @@ const props = defineProps({
   freehandGroupingDelay: { type: Number, required: false, default: 1e3 },
   formEditMode: { type: Boolean, required: false, default: void 0 },
   roleColors: { type: Object, required: false, default: void 0 },
-  activeRoleId: { type: [String, null], 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 }
 });
 const emit = defineEmits(["update:formEditMode", "update:activeRoleId"]);
 const viewerRoot = ref(null);
@@ -292,6 +296,8 @@ const searchIndex = createSearchIndex();
 const shapeDetectionCache = createShapeDetection();
 const doc = shallowRef(null);
 let painter = null;
+let scriptingManager = null;
+let scriptingBridge = null;
 const pageMetas = virtualization.pageMetas;
 const { isPageRendered } = virtualization;
 watch(
@@ -499,6 +505,33 @@ async function loadDocument() {
         totalPages: pdfDoc.numPages
       });
     });
+    if (props.scripting) {
+      try {
+        if (!scriptingManager) {
+          scriptingManager = await createScriptingManager({
+            viewerState: {
+              currentPage: viewerState.currentPage,
+              totalPages: viewerState.totalPages,
+              scale: viewerState.scale,
+              setScale: viewerState.setScale,
+              scrollToPage: viewerState.scrollToPage
+            },
+            virtualization: { isPageRendered: virtualization.isPageRendered },
+            proxyCache: { getPageSync: proxyCache.getPageSync }
+          });
+        }
+        await scriptingManager.setDocument(pdfDoc);
+        scriptingBridge = createScriptingBridge({
+          formFields: formFieldsState,
+          scripting: scriptingManager,
+          pdfDoc
+        });
+      } catch (err) {
+        console.warn("[KViewer] Failed to initialize PDF scripting sandbox:", err);
+        scriptingBridge?.destroy();
+        scriptingBridge = null;
+      }
+    }
   } catch (err) {
     viewerState.error.value = "Failed to load document";
     console.error("[KViewer] Document load error:", err);
@@ -776,6 +809,9 @@ onMounted(() => {
 watch(
   () => props.source,
   () => {
+    scriptingBridge?.destroy();
+    scriptingBridge = null;
+    scriptingManager?.setDocument(null);
     viewerSearch.reset();
     formFieldsState.reset();
     shapeDetectionCache.clearAllShapeCache();
@@ -817,6 +853,11 @@ onBeforeUnmount(() => {
   scrollContainer.value?.removeEventListener("wheel", onWheel);
   inertiaPanzoom.detach();
   resizeObserver?.disconnect();
+  scriptingBridge?.destroy();
+  scriptingBridge = null;
+  scriptingManager?.destroy().catch(() => {
+  });
+  scriptingManager = null;
   viewerSearch.reset();
   shapeDetectionCache.clearAllShapeCache();
   searchIndex.destroy();

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

@@ -1,6 +1,7 @@
 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';
 type __VLS_Props = {
     source: string | Uint8Array | object;
     textLayer?: boolean;
@@ -31,6 +32,19 @@ type __VLS_Props = {
      *  drives this — typically by binding it to a role picker in its own
      *  UI. Supports v-model via `v-model:active-role-id`. */
     activeRoleId?: string | null;
+    /** Execute embedded JavaScript inside the PDF — field-level AA scripts
+     *  (Mouse Up, Calculate, Format, Validate, Keystroke), document-level
+     *  open actions, and page-level scripts. Powered by pdf.js's QuickJS
+     *  WASM sandbox (no DOM/network/host-JS escape), but arbitrary JS from
+     *  untrusted PDFs is still real attack surface — default is `false`.
+     *  Treated as read-once per document; toggling at runtime requires
+     *  changing the `source` prop or remounting the component. */
+    scripting?: boolean;
+    /** Extra items appended to the default burger menu (after Download
+     *  and the form-field-detection toggle). Use this to expose app-level
+     *  toggles or actions without replacing the entire header. Ignored
+     *  when the host supplies a custom `#header` slot. */
+    menuItems?: ViewerMenuItem[];
 };
 declare function exportPdf(options?: ExportPdfOptions): Promise<Uint8Array>;
 type ImportMode = 'replace' | 'merge';
@@ -82,6 +96,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
     zoom: number;
     readonly: boolean;
     active: boolean;
+    menuItems: ViewerMenuItem[];
+    scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;

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

@@ -1,3 +1,9 @@
-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>;
+import type { ViewerMenuItem } from '../menu-items.js';
+type __VLS_Props = {
+    /** Extra items appended to the burger menu after the built-ins.
+     *  See {@link ViewerMenuItem}. Pure forwarding from `<KViewer>`. */
+    menuItems?: ViewerMenuItem[];
+};
+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 const _default: typeof __VLS_export;
 export default _default;

package/dist/runtime/components/ViewerBar.vue

@@ -26,6 +26,39 @@
               data-testid="viewer-toggle-shape-detection"
               @click="state.shapeDetection.value = !state.shapeDetection.value"
             />
+            <!-- Host-supplied menu items appended after the built-ins.
+                 A small separator visually marks the boundary; we only
+                 render it when there is at least one custom item. -->
+            <template v-if="props.menuItems && props.menuItems.length > 0">
+              <div class="my-1 border-t border-default" />
+              <template v-for="item in props.menuItems" :key="item.key">
+                <div v-if="item.type === 'separator'" class="my-1 border-t border-default" />
+                <UButton
+                  v-else-if="item.type === 'button'"
+                  :icon="item.icon"
+                  :label="item.label"
+                  :disabled="item.disabled"
+                  variant="ghost"
+                  color="neutral"
+                  size="xs"
+                  class="w-full justify-start"
+                  :data-testid="`viewer-menu-${item.key}`"
+                  @click="item.onSelect()"
+                />
+                <UButton
+                  v-else-if="item.type === 'checkbox'"
+                  :icon="item.icon ?? (item.checked ? 'i-lucide-check-square' : 'i-lucide-square')"
+                  :label="item.label"
+                  :variant="item.checked ? 'soft' : 'ghost'"
+                  :color="item.checked ? 'primary' : 'neutral'"
+                  :disabled="item.disabled"
+                  size="xs"
+                  class="w-full justify-start"
+                  :data-testid="`viewer-menu-${item.key}`"
+                  @click="item.onUpdate(!item.checked)"
+                />
+              </template>
+            </template>
           </div>
         </template>
       </UPopover>
@@ -89,6 +122,9 @@ import ActionTools from "./tools/ActionTools.vue";
 import PageInfo from "./tools/PageInfo.vue";
 import SearchTool from "./tools/SearchTool.vue";
 import ToolProperties from "./tools/ToolProperties.vue";
+const props = defineProps({
+  menuItems: { type: Array, required: false }
+});
 const state = useViewerState();
 const styleVersion = ref(0);
 function bumpStyleVersion() {

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

@@ -1,3 +1,9 @@
-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>;
+import type { ViewerMenuItem } from '../menu-items.js';
+type __VLS_Props = {
+    /** Extra items appended to the burger menu after the built-ins.
+     *  See {@link ViewerMenuItem}. Pure forwarding from `<KViewer>`. */
+    menuItems?: ViewerMenuItem[];
+};
+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 const _default: typeof __VLS_export;
 export default _default;

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

@@ -1,6 +1,7 @@
 import { type ComponentPublicInstance } from 'vue';
 import type { ViewMode } from '../composables/useViewerState.js';
 import type { StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { ViewerMenuItem } from '../menu-items.js';
 export interface ViewerTabItem {
     /** Unique identifier for the tab. */
     id: string;
@@ -18,6 +19,9 @@ export interface ViewerTabItem {
     zoom?: number;
     /** Enable shape detection for this document. */
     shapeDetection?: boolean;
+    /** Execute embedded PDF JavaScript for this document. See KViewer's
+     *  `scripting` prop — default false, opt-in per tab. */
+    scripting?: boolean;
 }
 export interface AddTabOptions {
     /** Insert at specific index. Defaults to end. */
@@ -53,6 +57,11 @@ type __VLS_Props = {
     /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
      *  Supports v-model via `v-model:active-role-id`. */
     activeRoleId?: string | null;
+    /** Forwarded to every Viewer instance — see KViewer's `scripting`.
+     *  Per-tab override via `ViewerTabItem.scripting` wins when set. */
+    scripting?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's `menuItems`. */
+    menuItems?: ViewerMenuItem[];
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -158,6 +167,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     };
 }, __VLS_35: {
     tab: {
@@ -257,6 +267,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     };
 }, __VLS_37: {};
 type __VLS_Slots = {} & {
@@ -373,6 +384,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeRoleId": (value: string | null) => any;
@@ -389,6 +401,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }>, {
     userName: string;
     zoom: number;
+    menuItems: ViewerMenuItem[];
+    scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;

package/dist/runtime/components/ViewerTabs.vue

@@ -59,6 +59,8 @@
           :zoom="activeTab.zoom ?? zoom"
           :readonly="readonly"
           :shape-detection="activeTab.shapeDetection ?? shapeDetection"
+          :scripting="activeTab.scripting ?? scripting"
+          :menu-items="menuItems"
           :role-colors="roleColors"
           :active-role-id="activeRoleId"
           @update:active-role-id="(v) => emit('update:activeRoleId', v)"
@@ -96,7 +98,9 @@ const props = defineProps({
   zoom: { type: Number, required: false, default: 1 },
   minTabs: { type: Number, required: false, default: 0 },
   roleColors: { type: Object, required: false, default: void 0 },
-  activeRoleId: { type: [String, null], 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 }
 });
 const emit = defineEmits(["update:activeTab", "tab-added", "tab-close", "tab-removed", "update:activeRoleId"]);
 let idCounter = 0;

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

@@ -1,6 +1,7 @@
 import { type ComponentPublicInstance } from 'vue';
 import type { ViewMode } from '../composables/useViewerState.js';
 import type { StampDefinition, SignatureHandlers } from '../annotation/engine/types.js';
+import type { ViewerMenuItem } from '../menu-items.js';
 export interface ViewerTabItem {
     /** Unique identifier for the tab. */
     id: string;
@@ -18,6 +19,9 @@ export interface ViewerTabItem {
     zoom?: number;
     /** Enable shape detection for this document. */
     shapeDetection?: boolean;
+    /** Execute embedded PDF JavaScript for this document. See KViewer's
+     *  `scripting` prop — default false, opt-in per tab. */
+    scripting?: boolean;
 }
 export interface AddTabOptions {
     /** Insert at specific index. Defaults to end. */
@@ -53,6 +57,11 @@ type __VLS_Props = {
     /** Forwarded to every Viewer instance — see KViewer's `activeRoleId`.
      *  Supports v-model via `v-model:active-role-id`. */
     activeRoleId?: string | null;
+    /** Forwarded to every Viewer instance — see KViewer's `scripting`.
+     *  Per-tab override via `ViewerTabItem.scripting` wins when set. */
+    scripting?: boolean;
+    /** Forwarded to every Viewer instance — see KViewer's `menuItems`. */
+    menuItems?: ViewerMenuItem[];
 };
 declare function addTab(item: Omit<ViewerTabItem, 'id'> & {
     id?: string;
@@ -158,6 +167,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     };
 }, __VLS_35: {
     tab: {
@@ -257,6 +267,7 @@ declare var __VLS_7: {}, __VLS_21: {}, __VLS_32: {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     };
 }, __VLS_37: {};
 type __VLS_Slots = {} & {
@@ -373,6 +384,7 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
         viewMode?: ViewMode | undefined;
         zoom?: number | undefined;
         shapeDetection?: boolean | undefined;
+        scripting?: boolean | undefined;
     }[];
 }, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
     "update:activeRoleId": (value: string | null) => any;
@@ -389,6 +401,8 @@ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {
 }>, {
     userName: string;
     zoom: number;
+    menuItems: ViewerMenuItem[];
+    scripting: boolean;
     stamps: StampDefinition[];
     signatureHandlers: SignatureHandlers;
     viewMode: ViewMode;

package/dist/runtime/components/form-fields/FormFieldWrapper.vue

@@ -7,6 +7,7 @@
   'kviewer-form-field--selected': props.selected
 }"
     :style="[positionStyle, { '--kvw-field-color': chromeColor }]"
+    :data-element-id="props.field.id"
   >
     <div
       class="kviewer-form-field__body"

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

@@ -67,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

@@ -31,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) {
@@ -112,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) {
@@ -445,6 +464,7 @@ export function provideFormFields() {
     selectedPlacedFieldId.value = null;
     checkboxStyleMap = null;
     buttonCaptionMap = null;
+    valueWriteSink = null;
     triggerRef(fieldDefinitions);
     triggerRef(fieldValues);
   }
@@ -472,6 +492,8 @@ export function provideFormFields() {
     isFieldLocked,
     resetValues,
     reset,
+    setValueWriteSink,
+    applyFieldValueFromExternal,
     activeRoleId,
     setActiveRole,
     roleColors,

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;