# DocViewKit

> Browser-local document viewing and source location for software products.

Version: 0.2.58
Updated: 2026-08-23

## Product boundary

DocViewKit is a browser-local, read-only document viewer SDK. It does not provide editing, collaboration, OCR, RAG, embeddings, model calls, or AI answers.

## Documentation

- [What DocViewKit is](https://docviewkit.com/docs/overview/): Product boundary, deployment model, and the problems DocViewKit is designed to solve.
- [Viewer quickstart](https://docviewkit.com/docs/quickstart/): Install the public Viewer, host its assets, and open a local document.
- [React Office Document Viewer](https://docviewkit.com/react-office-viewer/): Open DOCX, XLSX, PPTX, PDF, and other supported documents in React and Next.js without uploading the source file to a conversion service.
- [Vue Office Document Viewer](https://docviewkit.com/vue-office-viewer/): Open DOCX, XLSX, PPTX, PDF, and other supported documents in Vue 3 with one browser-local Web Component and no document-conversion backend.
- [Angular Office Document Viewer](https://docviewkit.com/angular-office-viewer/): Open DOCX, XLSX, PPTX, PDF, and other supported documents in Angular through a browser-local custom element without a server-side conversion service.
- [Viewer API](https://docviewkit.com/docs/viewer-api/): The small cross-format surface for opening, locating, observing, and releasing documents.
- [Source location](https://docviewkit.com/docs/source-location/): Open an original document beside an answer and reveal the authored source region.
- [Supported formats](https://docviewkit.com/docs/supported-formats/): Accepted document families, content-based detection, optional format packs, and explicit support boundaries.
- [Browser compatibility](https://docviewkit.com/docs/browser-compatibility/): The cross-browser contract for Chrome, Edge, Firefox, and Safari, including the checks required before release.
- [Architecture and privacy](https://docviewkit.com/docs/architecture-privacy/): Where document bytes are processed, which runtime assets are loaded, and when network or support flows occur.
- [Accuracy and fidelity](https://docviewkit.com/docs/accuracy-fidelity/): How DocViewKit distinguishes parser success, visible approximation, and native visual acceptance.
- [Performance optimization](https://docviewkit.com/docs/performance/): Configure first-open module loading, preserve on-demand work, reuse the Viewer, and measure browser-local performance reproducibly.
- [Licensing and plans](https://docviewkit.com/docs/licensing/): License-free Viewer usage, commercial plans, and Portal account access.
- [Report a document problem](https://docviewkit.com/docs/issue-reporting/): Create a machine-readable diagnostic bundle without uploading source document content.
- [Security and deployment](https://docviewkit.com/docs/security/): Self-hosted assets, untrusted input boundaries, and support-file isolation.

## Machine-readable resources

- [Complete documentation](https://docviewkit.com/llms-full.txt)
- [Structured documentation JSON](https://docviewkit.com/docs.json)
- [Customer portal](https://docviewkit.com/en/portal/)

Pin the package version, runtime assets, license public key, and documented support boundary together.

# Complete documentation

## What DocViewKit is

Product boundary, deployment model, and the problems DocViewKit is designed to solve.

### A viewer SDK, not an office suite

DocViewKit is a browser-local, read-only document viewer SDK for software vendors. It presents, searches, and locates supported Office, PDF, ODF, iWork, and related documents without sending document bytes to a third-party conversion service.

Deliberate boundary: DocViewKit does not provide document editing, collaboration, OCR, RAG, embeddings, model calls, or AI answers. AI knowledge-base and document-Q&A products are target integrations, not features inside the SDK.

### Why browser-local

- Document bytes stay in the host browser or WebView during normal viewing.
- The host does not need to operate a document-conversion cluster.
- JS, Worker, Wasm, fonts, and codecs can be self-hosted with the application.
- Macros, scripts, launch actions, and active external content are not executed.

Local processing is a deployment property, not a promise of universal pixel identity. Format support is bounded and maturity is published explicitly.

### Delivery artifacts

| Artifact | Access | Purpose |
| --- | --- | --- |
| @docviewkit/viewer | Public | Framework-independent Viewer with the complete supported format set and retained DocViewKit branding. |
| @docviewkit/sdk | Controlled commercial delivery | Engine APIs for custom document experiences. |

The public Viewer and controlled commercial SDK have separate license terms. Engine and white-label production rights require the corresponding signed commercial license.

## Viewer quickstart

Install the public Viewer, host its assets, and open a local document.

### Install

```sh
npm install @docviewkit/viewer
```

The package is designed for customer-hosted static assets. Do not load production Worker or Wasm files from an unpinned public CDN.

### Mount the Web Component

```html
<script type="module">
  import '@docviewkit/viewer';
</script>

<docviewkit-viewer id="document-viewer"></docviewkit-viewer>
```

```ts
const viewer = document.querySelector('#document-viewer');
const file = document.querySelector('input[type=file]').files[0];

try {
  await viewer.open(file);
} catch (error) {
  if (error.code !== 'PDF_PASSWORD_REQUIRED') throw error;
  await viewer.open(file, { password: await requestPassword() });
}
```

### Commercial preview boundary

Not a general production license: The current private package and preview Portal do not grant public production rights. Formats, browsers, deployment, support, and permitted use must be stated in a signed design-customer agreement.

## React Office Document Viewer

Open DOCX, XLSX, PPTX, PDF, and other supported documents in React and Next.js without uploading the source file to a conversion service.

### Use the framework-independent Viewer in React

DocViewKit exposes a native docviewkit-viewer custom element. React renders that element directly and a ref calls its open(), close(), reveal(), and destroy() methods; no React-specific rendering engine or wrapper package is required.

| Concern | React integration |
| --- | --- |
| Document input | Pass a File, Blob, ArrayBuffer, or Uint8Array to open(). |
| Rendering | The Viewer parses and renders in browser JavaScript, Workers, and WebAssembly. |
| Privacy | Normal viewing does not send document bytes to a third-party conversion service. |
| Lifecycle | Call close() when replacing a document and destroy() only when permanently removing the Viewer. |

### React component

```sh
npm install @docviewkit/viewer
```

```jsx
import { useEffect, useRef } from 'react';
import '@docviewkit/viewer';

export function OfficeViewer({ file }) {
  const viewer = useRef(null);

  useEffect(() => {
    if (file) void viewer.current?.open(file);
    return () => { void viewer.current?.close(); };
  }, [file]);

  return <docviewkit-viewer ref={viewer} />;
}
```

Keep the Viewer mounted when switching documents so the host can reuse its initialized runtime. Handle open() errors in the host when the application needs password prompts or task-specific recovery UI.

### Next.js client component

The Viewer depends on browser custom-element APIs. In a Next.js App Router project, register it from a client effect so the module is not evaluated during server rendering.

```jsx
'use client';

import { useEffect, useRef } from 'react';

export function OfficeViewer({ file }) {
  const viewer = useRef(null);

  useEffect(() => {
    let active = true;
    void import('@docviewkit/viewer').then(() => {
      if (active && file) return viewer.current?.open(file);
    });
    return () => {
      active = false;
      void viewer.current?.close();
    };
  }, [file]);

  return <docviewkit-viewer ref={viewer} />;
}
```

Self-host production assets: Pin and deploy the Viewer entry, Worker, Wasm, fonts, codecs, and optional format packs together. Do not depend on an unpinned public CDN for production document processing.

### Verify the complete integration

- [Viewer quickstart](/docs/quickstart/)
- [Supported formats and boundaries](/docs/supported-formats/)
- [Try a real file in the online demo](/en/demo/)
- [React custom HTML elements](https://react.dev/reference/react-dom/components#custom-html-elements)

## Vue Office Document Viewer

Open DOCX, XLSX, PPTX, PDF, and other supported documents in Vue 3 with one browser-local Web Component and no document-conversion backend.

### Use the native custom element in Vue

Vue 3 can consume the docviewkit-viewer custom element directly. Configure the template compiler to treat the tag as a custom element, keep a template ref to the DOM element, and call open() when the host file changes.

The same Viewer package, document model, diagnostics, and browser-local processing path are used in Vue, React, Angular, and vanilla JavaScript.

### Configure Vue and Vite

```sh
npm install @docviewkit/viewer
```

```js
// vite.config.js
import vue from '@vitejs/plugin-vue';

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'docviewkit-viewer'
        }
      }
    })
  ]
};
```

### Vue single-file component

```vue
<script setup lang="ts">
import { ref, watchEffect } from 'vue';
import '@docviewkit/viewer';

type ViewerElement = HTMLElement & {
  open(file: File): Promise<unknown>;
};

const props = defineProps<{ file?: File }>();
const viewer = ref<ViewerElement>();

watchEffect(() => {
  if (props.file && viewer.value) {
    void viewer.value.open(props.file);
  }
});
</script>

<template>
  <docviewkit-viewer ref="viewer" />
</template>
```

SSR boundary: For Nuxt or another server-rendered Vue host, import and register the Viewer only in client code because custom elements, Workers, and Canvas are browser APIs.

### Verify the complete integration

- [Viewer quickstart](/docs/quickstart/)
- [Architecture and privacy](/docs/architecture-privacy/)
- [Try a real file in the online demo](/en/demo/)
- [Vue and Web Components](https://vuejs.org/guide/extras/web-components.html#using-custom-elements-in-vue)

## Angular Office Document Viewer

Open DOCX, XLSX, PPTX, PDF, and other supported documents in Angular through a browser-local custom element without a server-side conversion service.

### Use the Viewer as an Angular custom element

Angular supports Web Platform custom elements through CUSTOM_ELEMENTS_SCHEMA. Register the DocViewKit package once, query the docviewkit-viewer element, and pass the selected document to its open() method.

CUSTOM_ELEMENTS_SCHEMA keeps Angular's normal template validation while allowing dash-named custom elements. NO_ERRORS_SCHEMA is not required.

### Standalone Angular component

```sh
npm install @docviewkit/viewer
```

```ts
import '@docviewkit/viewer';
import {
  AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA,
  ElementRef, Input, ViewChild
} from '@angular/core';

type ViewerElement = HTMLElement & {
  open(file: File): Promise<unknown>;
  close(): Promise<void>;
};

@Component({
  selector: 'app-office-viewer',
  standalone: true,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  template: '<docviewkit-viewer #viewer />'
})
export class OfficeViewerComponent implements AfterViewInit {
  @ViewChild('viewer') viewer?: ElementRef<ViewerElement>;
  #file?: File;

  @Input() set file(file: File | undefined) {
    this.#file = file;
    void this.open();
  }

  ngAfterViewInit() { void this.open(); }

  private async open() {
    if (this.#file && this.viewer) {
      await this.viewer.nativeElement.open(this.#file);
    }
  }
}
```

The host component owns file selection, permissions, error presentation, and business workflow. DocViewKit owns document parsing, viewing, search, navigation, and structured diagnostics.

### Verify the complete integration

- [Viewer quickstart](/docs/quickstart/)
- [Viewer API](/docs/viewer-api/)
- [Try a real file in the online demo](/en/demo/)
- [Angular custom-element schema](https://angular.dev/api/core/CUSTOM_ELEMENTS_SCHEMA)

## Viewer API

The small cross-format surface for opening, locating, observing, and releasing documents.

### Stable surface

```ts
interface DocViewKitViewerElement extends HTMLElement {
  open(source: File | Blob | ArrayBuffer | Uint8Array): Promise<DocumentInfo>;
  reveal(target: ViewerTarget): Promise<RevealResult>;
  close(): Promise<void>;
  destroy(): void;
  readonly state: Readonly<ViewerState>;
}
```

The API uses capability-driven targets instead of separate navigation methods for pages, slides, and worksheets. Framework adapters remain thin wrappers around this element.

### Events

| Event | When to use it |
| --- | --- |
| docviewkit-ready | Assets and runtime are ready for a document. |
| docviewkit-statechange | Navigation, selection, or capability state changed. |
| docviewkit-diagnostic | A bounded, approximate, omitted, or blocked path was observed. |
| docviewkit-error | Opening or rendering cannot continue. |

Do not infer support from file extensions: Use DocumentInfo capabilities and structured diagnostics. A file opening successfully is not proof that every authored feature was rendered.

### Add a text watermark

```ts
viewer.config = {
  ...viewer.config,
  watermark: 'Confidential'
};

await viewer.open(file);
```

The optional 1–256 character watermark is painted into Viewer pages, thumbnails, and print output without modifying the source document, object list, search results, hit testing, or source mapping. Viewer Commercial, SDK, Enterprise, and Evaluation licenses enable this option; unlicensed sessions and Viewer sessions on the Free plan ignore it. Engine integrations can set the same watermark field after passing the existing Engine license gate.

### Customization boundary

```ts
viewer.config = {
  ...viewer.config,
  features: {
    ...viewer.config.features,
    interactionModeSwitcher: true, // false by default
    print: true,
    fullscreen: true
  }
};
```

The Viewer can expose object location, display-only, and text selection as one segmented toolbar control. The switcher is hidden by default; print and fullscreen remain independently configurable, and hidden controls do not leave empty toolbar separators.

- Design tokens control color, typography, spacing, radius, and surface treatment.
- Stable ::part hooks expose bounded regions such as the toolbar and search panel.
- A small slot set supports host actions and business panels.
- Applications that replace the information architecture should use DocViewKit SDK Engine APIs.

## Source location

Open an original document beside an answer and reveal the authored source region.

### Use one target model

```ts
await viewer.reveal({
  kind: 'source',
  unitIndex: 6,
  objectId: 'paragraph-42',
  region: { x: 96, y: 412, width: 510, height: 88 }
});
```

A target may resolve to a page, slide, worksheet, object, or bounded region. When exact object mapping is unavailable, the Viewer uses the most reliable page-level fallback and emits a diagnostic.

### Integration with AI products

The host product owns retrieval, answer generation, permissions, citation choice, and business workflow. DocViewKit owns document presentation and navigation to a source reference.

Keep facts deterministic: Pass the citation target produced by your retrieval pipeline. Do not ask the Viewer to infer which passage an answer used.

## Supported formats

Accepted document families, content-based detection, optional format packs, and explicit support boundaries.

### Accepted inputs

| Family | Accepted file extensions | Runtime path |
| --- | --- | --- |
| OOXML presentations | .pptx, .pptm, .ppsx, .ppsm, .potx, .potm | Core |
| OOXML spreadsheets | .xlsx, .xlsm, .xltx, .xltm | Core |
| OOXML text documents | .docx, .docm, .dotx, .dotm | Core |
| Flat documents | .csv, .rtf | Core |
| OpenDocument | .odp, .otp, .fodp, .odg, .otg, .fodg, .ods, .ots, .fods, .odt, .ott, .fodt | ODF pack |
| iWork single-file packages | .pages, .numbers, .key | iWork pack |
| Legacy Office | .doc, .xls, .ppt | Legacy Office pack |
| WPS Office | .wps, .et, .dps | WPS pack |
| Fixed layout | .pdf, .xps, .oxps | PDF or XPS pack |

TXT, standalone HTML or HTM, XLSB, and unsupported top-level formats return an explicit unsupported-format result rather than being guessed from their file extension.

### Content-based detection

DocViewKit identifies packages from bounded content probes such as OPC content types, ODF mimetype and manifest data, CFB records, PDF headers, XPS relationships, and iWork IWA identity. A filename hint is used only to isolate a structurally recognized WPS-family input.

Extensions are not capability claims: Opening a family does not imply that every authored feature is exact. Applications must read DocumentInfo capabilities and structured diagnostics.

### Read-only and inactive by design

Macro-enabled packages are parsed as their document family, but VBA, scripts, ActiveX, PDF actions, launch targets, and other active content never execute. External resources are blocked unless the host explicitly provides a safe local resource path.

## Browser compatibility

The cross-browser contract for Chrome, Edge, Firefox, and Safari, including the checks required before release.

### One Web Component across major engines

DocViewKit targets current Chrome and Edge Chromium, Firefox Gecko, and Safari WebKit with the same Web Component API. The host supplies a File, Blob, ArrayBuffer, or Uint8Array; the Viewer owns parsing, rendering, search, navigation, and diagnostics.

Compatibility means the documented API and bounded viewing workflow remain available across the supported engines. It does not mean every browser uses identical font shaping, media codecs, color management, canvas limits, or print behavior.

### Release checks

- Open a real document through the public Viewer entry point.
- Verify navigation, search, zoom, close and reopen, diagnostics, and source location.
- Run the same interaction contract in Chromium, Firefox, and WebKit.
- Treat a browser-specific omission or degraded path as a release failure or a published diagnostic boundary.

## Architecture and privacy

Where document bytes are processed, which runtime assets are loaded, and when network or support flows occur.

### Normal viewing stays in the browser

During normal viewing, document bytes are passed to browser JavaScript, Workers, and WebAssembly from the host application. DocViewKit does not send the source document to a third-party conversion service and does not require a document-processing backend.

- The customer hosts the Viewer entry, Worker, Wasm, fonts, codecs, and optional format packs.
- Optional format packs load only when configured and needed by the current document.
- License verification exchanges signed license material, not document content.
- The official support flow excludes source bytes, file names, paths, text, screenshots, and hashes by default.

### The host still owns its security boundary

The embedding application remains responsible for authentication, authorization, upload policy, content security policy, size limits, trusted asset hosting, telemetry choices, and incident response. Browser-local processing does not make untrusted documents harmless.

## Accuracy and fidelity

How DocViewKit distinguishes parser success, visible approximation, and native visual acceptance.

### Three different claims

| Level | What it proves | What it does not prove |
| --- | --- | --- |
| Parser and protocol | The input produces bounded document objects and source references | Native visual fidelity |
| Browser render | The public Viewer draws usable content and interactions | Pixel identity with an Office application |
| Native visual acceptance | Reviewed pages or local regions match a named native application under a recorded environment | Universal fidelity for every producer and feature |

Open is not a fidelity result: A document opening successfully is not proof that every authored object, style, page break, formula, animation, or embedded resource was rendered.

### Best-effort rendering stays observable

An isolated unknown or incompatible resource should not hide otherwise usable document content. Supported fallbacks remain source-mapped and emit approximate or omitted diagnostics; structural corruption, unsafe expansion, or a document with no meaningful output may still fail the open.

## Performance optimization

Configure first-open module loading, preserve on-demand work, reuse the Viewer, and measure browser-local performance reproducibly.

### Warm the configured format dispatcher

Set viewer.config.engine.formatPack before the first open(). Create and memoize the dynamic-import promise when the application knows optional formats are allowed; creating the promise starts the small JavaScript dispatcher download without waiting for the first document.

```ts
import '@docviewkit/viewer';

const formatPack = import('@docviewkit/viewer/extended-formats')
  .then(({ extendedFormatPack }) => extendedFormatPack);

const viewer = document.querySelector('docviewkit-viewer');
viewer.config = {
  engine: {
    formatPack: () => formatPack
  }
};

await viewer.open(file);
```

Dispatcher warm-up is selective: Importing extended-formats does not fetch every Wasm binary. Bounded content detection selects one matching ODF, PDF/iWork, legacy Office/WPS, or XPS module. If the product accepts only WPS or XPS, use the dedicated wps-formats or xps-formats subpath.

### Keep on-demand work out of startup

| Resource or operation | First-open behavior |
| --- | --- |
| Viewer JavaScript and core runtime | Required when the first document opens |
| Optional format dispatcher | May be imported early and memoized |
| Optional family Wasm | Load only after content detection selects that family |
| Pages, slides, sheets, and thumbnails | Materialize or render on demand |
| Document-wide search and all-object queries | Start only when the product needs complete-document results |
| Host fonts | Provide common static faces or a bounded lazy provider; do not fetch the full catalog first |

- Serve versioned Worker, Wasm, codec, and font assets with normal HTTP caching from the same controlled deployment as the Viewer.
- Keep one Viewer instance across documents and call close() between them. destroy() also releases the reusable Engine and is intended for removing the component.
- Do not preload every optional Wasm binary or render every unit before first paint; that defeats the format and unit lazy-loading boundaries.
- Keep authorization and document acquisition ahead of open(), but avoid unrelated application initialization on the critical path.

### Publish measurements with their environment

A reproducible result records the DocViewKit version, browser and version, operating system, hardware, cold or warm cache, input format and bytes, page or unit count, time to open, time to first visible content, peak memory where available, and emitted diagnostics.

No context-free speed claims: A single fastest-file number is not a product guarantee. Compare the same artifact, environment, cache state, and completion boundary.

## Licensing and plans

License-free Viewer usage, commercial plans, and Portal account access.

### Plan boundary

| Plan | What it provides |
| --- | --- |
| Free | Every available document format without a license, with retained DocViewKit branding. |
| Viewer Commercial | White-label Viewer and bounded business UI slots; no Engine API. |
| SDK | Engine API and advanced integration customization. |
| Enterprise | SDK capabilities plus contract-scoped performance customization. A format-specific build can omit unused format modules, reduce delivered assets, and optimize first-open and target-document paths. |
| Evaluation | Thirty-day full-capability technical evaluation; no general production rights. |

### Portal accounts

There is no default administrator account or password. Set DOCVIEWKIT_ADMIN_EMAILS to a comma-separated list of registered email addresses, restart the service, then sign in normally. Matching accounts receive the administrator role; removing an email and restarting revokes it. All other self-registered accounts remain scoped to their own applications and requests.

- Administrators can use GET /api/admin/summary and the Administration view to see stored user profiles and counts plus all commercial requests. Password hashes, password salts, and session tokens are not returned.
- The administrator endpoint requires the same random server-side session token as the Portal plus the configured administrator role; ordinary authenticated users receive HTTP 403.
- Signed-in users can change their password in the Portal or with POST /api/auth/password by providing currentPassword, newPassword, and confirmPassword. A successful change invalidates other sessions and returns a replacement HttpOnly session cookie.
- Portal sessions are stored as SHA-256 hashes and delivered in HttpOnly, SameSite=Strict cookies. Passwords use Node.js scrypt, sign-in attempts are rate limited, and plain-text passwords are never stored or sent by email.
- The Portal can be disabled at deployment with DOCVIEWKIT_ENABLE_PREVIEW_PORTAL unset; production deployment must terminate TLS.

### Realistic protection boundary

Browser-delivered JS and Wasm can be inspected or modified. Signed licenses, controlled commercial distribution, artifact signatures, customer fingerprints, contracts, and support rights deter ordinary copying and preserve provenance; they are not unbreakable DRM.

## Report a document problem

Create a machine-readable diagnostic bundle without uploading source document content.

### Diagnostic bundle

```ts
interface IssueBundle {
  schemaVersion: string;
  issueId: string;
  sdkVersion: string;
  buildHash: string;
  format: string;
  browser: string;
  operatingSystem: string;
  viewerConfig: Record<string, unknown>;
  diagnostics: Diagnostic[];
  currentLocation?: SourceRef;
  reproductionSteps?: string;
  expectedBehavior?: string;
  actualBehavior?: string;
}
```

The default bundle excludes document bytes, file names, paths, text, screenshots, and hashes. Screenshots and source files require explicit user selection.

### Private files are disabled

No source-file upload in commercial preview: Private source-file upload is disabled until isolation, retention expiry, deletion auditing, access control, and incident response are implemented and verified. Share files only through a separately agreed customer channel.

### Submit on GitHub

Submit public bug reports through https://github.com/docviewkit/viewer/issues/new/choose. Do not attach confidential documents or sensitive diagnostics to a public issue; use a separately agreed customer channel when private handling is required.

## Security and deployment

Self-hosted assets, untrusted input boundaries, and support-file isolation.

### Self-host runtime assets

- Pin package, Worker, Wasm, font, and codec versions together.
- Serve assets from the same trusted deployment boundary as the host application.
- Use artifact hashes and signatures from the release manifest.
- Do not place license signing secrets or other application secrets in browser code.

### Treat every document as untrusted

Parsing runs with bounded archive, XML, image, object, render, and time budgets. Active content is blocked rather than executed. Applications should still apply their own upload policy, size limits, authentication, content security policy, and incident response.

### Support files are a separate flow

Explicit support action: Normal viewing is browser-local. The commercial-preview Portal rejects source-file uploads; any future private transfer requires a separately agreed channel and retention policy.