# @doc-preview/core

Framework-neutral document preview engine — renderer registry, preview phase machine, DOM rendering, and document loaders. Powers [`@doc-preview/react`](https://www.npmjs.com/package/@doc-preview/react), [`@doc-preview/angular`](https://www.npmjs.com/package/@doc-preview/angular), and [`@doc-preview/js`](https://www.npmjs.com/package/@doc-preview/js).

**Current release: 1.2.0** — See [CHANGELOG](./CHANGELOG.md).

### What's new in 1.2.0

- **True PDF redaction** — redacted pages rasterized to PNG via PDF.js; text content stream permanently discarded; applies to both Export button and annotate toolbar Download
- **Image redaction** — `attachImageRedaction()` drag-to-draw black boxes on image previews; burned into downloaded pixel data; correct print positioning at any scale
- **`dpIcons.redact()`** — filled black bar icon added to the icon set

**Repository:** [github.com/rajkishorsahu89/doc-preview](https://github.com/rajkishorsahu89/doc-preview)

**Demo:** [docpreview.stackkitlabs.com](https://docpreview.stackkitlabs.com/) — [tool](https://docpreview.stackkitlabs.com/tool) · [demo](https://docpreview.stackkitlabs.com/demo) · [guide](https://docpreview.stackkitlabs.com/guide)

**Keywords:** `doc-preview` `document-viewer` `file-preview` `pdf` `typescript` `renderer-registry`

## Install

```bash
npm install @doc-preview/core @doc-preview/themes
```

Most apps should use a framework adapter instead of core alone. Use core directly for custom hosts, tests, or headless loaders.

## Supported file types (Community — built into core)

Register with `registerBuiltinPreviewRenderers()`. Use `config.upload.accept` or the constant below for file pickers.

**Upload accept string:** `.pdf,.doc,.docx,.docm,.dotx,.odt,.ods,.odp,.xls,.xlsx,.xlsm,.xltx,.ppt,.pptx,.pptm,.potx,.png,.jpg,.jpeg,.gif,.webp,.bmp,.svg,.tif,.tiff,.mp4,.webm,.mov,.mp3,.wav,.m4a,.txt,.md,.html,.htm,.csv,.tsv,.json,.xml,.log`

| Category | Extensions | Renderer |
| --- | --- | --- |
| **PDF** | `.pdf` | PDF.js — zoom, thumbnails, page nav |
| **Images** | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.svg`, `.tif`, `.tiff` | Native `<img>` |
| **Word** | `.docx`, `.docm`, `.dotx` | `docx-preview` (macros not executed) |
| **Text** | `.txt`, `.md`, `.log` | Plain text |
| **Structured data** | `.json`, `.xml` | Syntax-highlighted text |
| **CSV / TSV** | `.csv`, `.tsv` | Table — frozen header row, column resize |
| **HTML** | `.html`, `.htm` | Sandboxed iframe (sanitize by default) |
| **Video** | `.mp4`, `.webm`, `.mov` | HTML5 `<video>` |
| **Audio** | `.mp3`, `.wav`, `.m4a` | HTML5 `<audio>` |

### Optional — [`@doc-preview/office`](https://www.npmjs.com/package/@doc-preview/office)

Add `registerOfficePreviewRenderers()` for the rows below (plus cloud embed for public HTTPS URLs).

| Category | Extensions | Notes |
| --- | --- | --- |
| **Excel** | `.xlsx`, `.xlsm`, `.xltx`, `.xls`, `.ods` | Multi-sheet tabs; frozen header; column resize |
| **PowerPoint** | `.pptx`, `.pptm`, `.potx`, `.ppt`, `.odp` | Slide deck UI (PPTX/ODP); legacy `.ppt` text |
| **Word (legacy)** | `.doc` | OLE text or HTML (`legacyDocPreview`) |
| **OpenDocument text** | `.odt` | HTML extraction |
| **Cloud viewer** | `.doc`, `.ppt`, `.pptx`, `.xlsx`, `.pdf`, `.odt`, `.ods`, `.odp` | Public HTTPS URL only — Microsoft / Google iframe |

### Optional — [`@doc-preview/enterprise`](https://www.npmjs.com/package/@doc-preview/enterprise)

Licence-gated features (annotations, watermark, split view, print, search, redaction, compare/diff) apply on top of any supported preview format where the feature is implemented — see the [Enterprise guide](https://docpreview.stackkitlabs.com/guide/enterprise).

## Usage — preview API

```ts
import {
  createPreviewApi,
  mountPreviewTree,
  createPreviewDocumentFromBlob,
  createPreviewDocumentFromBase64,
  registerBuiltinPreviewRenderers
} from "@doc-preview/core";

registerBuiltinPreviewRenderers();

const api = createPreviewApi({
  documents: [{ uri: "/sample.pdf", fileName: "sample.pdf" }],
  onPhaseChange: (e) => console.log(e.phase)
});

await mountPreviewTree({
  host: document.getElementById("viewer")!,
  engine: api.engine
});
```

## Document sources

```ts
// URL
{ uri: "/api/files/1", fileName: "report.pdf" }

// Blob / File
createPreviewDocumentFromBlob(file, { fileName: file.name })

// Base64 / data URL
createPreviewDocumentFromBase64({
  base64: "data:application/pdf;base64,...",
  fileName: "report.pdf"
})

// Authenticated fetch
createPreviewApi({
  documents: [{ uri: "https://api.example.com/doc" }],
  requestHeaders: { Authorization: "Bearer …" }
});
```

## Custom renderers

```ts
import { registerPreviewRenderer } from "@doc-preview/core";

registerPreviewRenderer({
  id: "my-format",
  fileTypes: ["custom"],
  supports: (doc) => doc.detectedType === "custom",
  load: async (ctx) => ({ text: "Hello" }),
  render: (container, ctx) => {
    container.textContent = ctx.loaded.text ?? "";
    return () => {};
  }
});
```

## Enterprise integration

Enterprise features (annotations, watermark, split view, print, search, redaction, diff, password PDF) are gated by flags from [`@doc-preview/enterprise`](https://www.npmjs.com/package/@doc-preview/enterprise). Pass `enterpriseFlags` to `mountPreviewTree` / `renderPreviewTree`, or use a framework adapter with `enterpriseLicenseKey`.

## Print

```ts
import { printPreviewElement } from "@doc-preview/core";

printPreviewElement(document.getElementById("doc-preview-root")!, "DRAFT");
```

## Related packages

- [`@doc-preview/themes`](https://www.npmjs.com/package/@doc-preview/themes) — required CSS
- [`@doc-preview/react`](https://www.npmjs.com/package/@doc-preview/react)
- [`@doc-preview/angular`](https://www.npmjs.com/package/@doc-preview/angular)
- [`@doc-preview/js`](https://www.npmjs.com/package/@doc-preview/js)
- [`@doc-preview/enterprise`](https://www.npmjs.com/package/@doc-preview/enterprise)
- [`@doc-preview/office`](https://www.npmjs.com/package/@doc-preview/office)

## License

[MIT](./LICENSE)