Page Manipulation

Use `pageManipulation` when the host needs to edit the active PDF at the page level. The viewer handles the underlying document state and returns `pageManipulationResult` with success or failure details.

Different actions require different payload fields, so it is easier to think about them in groups instead of one large generic form.

These action groups map cleanly to the payloads your host application needs to build.

• Reorder / Rotate / Extract / Delete: `move-top`, `move-bottom`, `move-up`, `move-down`, `rotate-r`, `rotate-l`, `page-extract`, `page-extract-delete`, `page-delete` use `pageRange`.
• Clipboard: `page-copy` uses `pageRange`, and `page-paste` uses `targetPageIndex` with the viewer-local clipboard.
• Source-file actions: `page-insert` and `page-replace` use `pageRange`, `file`, and `selectedPages`.
• Blank pages: `page-insert-blank` uses `pageRange`, `count`, `width`, and `height`.

Copy and paste use the viewer internal page clipboard. The parent application does not pass page bytes, base64, or file objects between the two actions.

The flow is always two-step: first send `page-copy` with the selected page range, then send `page-paste` with the destination index in the same viewer session.

• Use `page-copy` when the host already knows which pages the user selected.
• Use `page-paste` only after a successful copy in the same iframe session.
• For paste, `targetPageIndex` is required. `pageRange` is not the paste target.
• If nothing was copied first, the payload can be valid and paste can still fail because the viewer clipboard is empty.

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'copy-1',
    action: 'page-copy',
    pageRange: [[1, 3]]
  }
}, '*');

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'paste-1',
    action: 'page-paste',
    targetPageIndex: 5
  }
}, '*');

Insert and replace are source-file workflows. The parent provides another PDF file object plus the source pages that should be imported from that file.

For both actions, `pageRange` points at the target location in the current PDF, while `selectedPages` identifies which pages should be taken from the source file.

• page-insert: Adds source PDF pages at the target location in the current file.
• page-replace: Swaps the target pages in the current file with pages from the source file.
• The required fields are `pageRange`, `file`, and `selectedPages`.
• Do not send a document URL here. The viewer expects a browser `File` object from the parent.

const file = input.files[0];

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'insert-1',
    action: 'page-insert',
    pageRange: [[2]],
    file,
    selectedPages: [[0, 1]]
  }
}, '*');

const file = input.files[0];

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'replace-1',
    action: 'page-replace',
    pageRange: [[4]],
    file,
    selectedPages: [[0]]
  }
}, '*');

Blank page insertion is simpler than source-file insertion because the parent does not provide another PDF. Instead, it defines how many blank pages should be created and the size of those pages.

The required size values are document pixel units used by the viewer blank-page insertion path.

• Use `pageRange` to define where the blank pages should be inserted.
• Use `count` for how many blank pages to create.
• Use `width` and `height` for the blank page dimensions.

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'blank-1',
    action: 'page-insert-blank',
    pageRange: [[3]],
    count: 2,
    width: 816,
    height: 1056
  }
}, '*');

Page manipulation results should be surfaced directly in the host UI. Success payloads confirm the action and can include page metadata. Failure payloads explain what was missing or invalid.

{
  type: 'pageManipulationResult',
  payload: {
    success: true,
    requestId: 'rotate-1',
    action: 'rotate-r',
    pageRange: [[0, 2]],
    pages: [0, 1, 2],
    currentPage: 0,
    pageCount: 12
  }
}

{
  success: false,
  error: 'Missing file'
}

{
  success: false,
  error: 'Missing page-insert:selectedPages'
}

{
  success: false,
  error: 'Missing targetPageIndex'
}

Start from a single action group and build only the fields that action requires.

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'rotate-1',
    action: 'rotate-r',
    pageRange: [[0, 2]]
  }
}, '*');

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'paste-1',
    action: 'page-paste',
    targetPageIndex: 1
  }
}, '*');

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'insert-1',
    action: 'page-insert',
    pageRange: [[2]],
    file,
    selectedPages: [[0, 1]]
  }
}, '*');

viewerWindow.postMessage({
  type: 'pageManipulation',
  payload: {
    requestId: 'blank-1',
    action: 'page-insert-blank',
    pageRange: [[3]],
    count: 2,
    width: 816,
    height: 1056
  }
}, '*');

Always pair the action request with a `pageManipulationResult` listener so your host can show errors, update UI state, and refresh the page panel if needed.

A practical flow is: send the action, wait for `pageManipulationResult`, show any failure reason, and then refresh or re-render your page UI from the latest viewer page state.

• Log the returned error string instead of showing a generic failed state.
• Keep `requestId` values unique so the host can match result events to the action that triggered them.
• Refresh your page UI after successful operations that change page order or page count.

window.addEventListener('message', (event) => {
  if (event.data?.type !== 'pageManipulationResult') return;

  const result = event.data.payload;
  if (!result.success) {
    console.error(result.error);
    return;
  }

  console.log(result.action, result.pageCount);
});

This example shows a simple host-side PDF workflow: render the page list, navigate on page click, copy a page, and paste it at another location.

const viewerWindow = iframe.contentWindow;
let latestPages = [];

window.addEventListener('message', (event) => {
  const data = event.data;
  if (!data) return;

  if (data.type === 'pageList') {
    latestPages = data.payload.pages;
    renderPages(latestPages);
    return;
  }

  if (data.type === 'selectPageResult') {
    console.log('Selected page:', data.payload);
    return;
  }

  if (data.type === 'pageManipulationResult') {
    if (!data.payload.success) {
      console.error('Page action failed:', data.payload.error);
      return;
    }

    console.log('Page action complete:', data.payload.action);
  }
});

function renderPages(pages) {
  const container = document.getElementById('pages');
  container.innerHTML = '';

  pages.forEach((page) => {
    const button = document.createElement('button');
    button.textContent = page.label;
    button.className = page.isSelected ? 'page active' : 'page';
    button.addEventListener('click', () => selectPage(page.index));
    container.appendChild(button);
  });
}

function selectPage(pageIndex) {
  viewerWindow.postMessage({
    type: 'selectPage',
    payload: { pageIndex }
  }, '*');
}

function copyPage(pageIndex) {
  viewerWindow.postMessage({
    type: 'pageManipulation',
    payload: {
      requestId: 'copy-' + pageIndex,
      action: 'page-copy',
      pageRange: [[pageIndex]]
    }
  }, '*');
}

function pasteAt(targetPageIndex) {
  viewerWindow.postMessage({
    type: 'pageManipulation',
    payload: {
      requestId: 'paste-' + targetPageIndex,
      action: 'page-paste',
      targetPageIndex
    }
  }, '*');
}

function rotateCurrentRange() {
  viewerWindow.postMessage({
    type: 'pageManipulation',
    payload: {
      requestId: 'rotate-range-1',
      action: 'rotate-r',
      pageRange: [[0, 2]]
    }
  }, '*');
}