Overview
Luma PDF is a static, browser-only PDF workspace. It has three surfaces:
- Viewer (
viewer.html) — reading, search, annotations, export. - Tools (
tools.html) — 33 utilities built on pdf-lib and PDF.js. - Embed (
embed.html) — a chrome-light viewer configured entirely by URL parameters.
There is no server component. Rendering uses PDF.js (Apache-2.0), editing uses pdf-lib (MIT), and both are vendored in vendor/ so the app works offline and needs no CDN.
Access-Control-Allow-Origin. No client-side app can override this — see CORS.Quick start
Deploy the folder to any static host, then embed a PDF:
<iframe src="https://your-domain.example/embed.html?file=https://your-domain.example/report.pdf" width="100%" height="700" style="border:0" loading="lazy" allowfullscreen title="Luma PDF Viewer" ></iframe>
Or generate the snippet interactively with the Embed Generator.
Embed endpoint
embed.html?file=PDF_URL&…
The embed loads the document immediately, keeps no branding beyond a small optional mark, and never navigates to the homepage. It is responsive, touch-friendly and independent of the main site layout.
Minimal
embed.html?file=/files/whitepaper.pdf
Configured
embed.html?file=/files/whitepaper.pdf&page=3&zoom=page-fit &toolbar=1&sidebar=1&search=1&download=0&print=0 &theme=dark&background=dark&pageMode=spread&direction=rtl
Parameters
Boolean parameters accept 1/0, true/false, yes/no, on/off, show/hide.
| Parameter | Type | Default | What it does |
|---|---|---|---|
file | URL | — | Absolute or same-origin URL of the PDF. Required. |
page | int | 1 | Page to open on load. |
zoom | enum / int | page-width | page-width, page-fit, actual, or 50–500. |
fit | enum | — | width, page or auto; alias for zoom fitting. |
toolbar | bool | 1 | Show the control bar. |
sidebar | bool | 0 | Show the thumbnails/outline panel. |
navigation | bool | 1 | Show page navigation. |
search | bool | 1 | Enable in-document search. |
download | bool | 1 | Show the download button. |
print | bool | 1 | Show the print button. |
fullscreen | bool | 1 | Show the fullscreen button. |
controls | enum | auto | auto, always, never for touch chrome. |
mobileToolbar | bool | 1 | Use the compact bottom bar on phones. |
theme | enum | auto | light, dark, auto. |
background | enum | light | light, dark, sepia, slate, paper. |
pageMode | enum | vertical | single, vertical, horizontal, spread, book. |
scroll | enum | — | vertical or horizontal shortcut. |
spread | bool | 0 | Shortcut for a two-page spread. |
direction | enum | ltr | ltr or rtl reading direction. |
language | string | en | Sets the document language for assistive tech. |
annotations | bool | 0 | Enable viewer-side annotation tools. |
outline | bool | 0 | Show the outline tab in the sidebar. |
readonly | bool | 0 | Disables download, print and annotations. |
minimal | bool | 0 | Compact chrome, no sidebar or print. |
hideLogo | bool | 0 | Hide the small Luma PDF mark. |
watermark | string | — | Faint text overlaid on the reading area. |
origin | list | same origin | Extra origins allowed to send commands, comma separated. |
Platform recipes
Blogger
In the post editor switch to HTML view and paste the iframe. Blogger strips some attributes, so keep it simple:
<iframe src="https://your-domain.example/embed.html?file=https://example.com/report.pdf" width="100%" height="640" style="border:0"></iframe>
WordPress
Use a Custom HTML block (not the paragraph block, which escapes iframes). Self-hosted sites can also add it to a page template.
GitHub Pages
Put the PDF next to the HTML and use a relative URL. GitHub Pages serves PDFs with Content-Type: application/pdf and allows same-origin reads, so no CORS setup is needed:
<iframe src="/embed.html?file=/docs/report.pdf" width="100%" height="700" style="border:0"></iframe>
Cloudflare Pages / Netlify / Vercel
Upload the folder as a static site. Nothing else is required; the included deployment/ files add sensible headers.
Responsive pattern
<div style="position:relative;padding-top:min(75vh,720px)">
<iframe src="https://your-domain.example/embed.html?file=/report.pdf"
style="position:absolute;inset:0;width:100%;height:100%;border:0"
loading="lazy" allowfullscreen title="Report"></iframe>
</div>postMessage API
Commands are only accepted from the parent window, and only from the same origin unless you list extra origins with the origin parameter. Messages are never evaluated as code.
Two message shapes are accepted:
iframe.contentWindow.postMessage(
{ type: 'luma', command: 'setPage', payload: { page: 4 } },
'https://your-domain.example'
);
// Legacy shorthand
iframe.contentWindow.postMessage({ type: 'luma:setPage', page: 4 }, 'https://your-domain.example');| Command | Payload | Result |
|---|---|---|
setPage | { page } | { page } |
setZoom | { zoom } | { zoom } percent |
nextPage / previousPage | — | { page } |
searchText | { text } | { term }, then a luma:searchCompleted event |
print | — | { ok } |
download | — | { ok } |
toggleSidebar | — | { sidebar } |
toggleFullscreen | — | { fullscreen } |
getDocumentInfo | — | { pages, page, title, author, … } |
setTheme | { theme } | { theme } |
open | { url } | Loads another PDF in the same frame |
Every command answers with { type: 'luma:response', command, ok, result | error }.
Viewer events
The embed posts these to the parent window:
| Event | Detail |
|---|---|
luma:ready | { version, config } — frame is listening, commands can be queued |
luma:loaded | { pages, page, title, author, … } |
luma:error | { code, message } — NETWORK_CORS, PASSWORD_REQUIRED, INVALID_PDF, NOT_PDF |
luma:pageChanged | { page, total } |
luma:zoomChanged | { percent, scale } |
luma:searchCompleted | { term, matches, page } |
luma:fullscreenChanged | { fullscreen } |
luma:annotationChanged | { count } |
luma:documentInfo | Document metadata after a getDocumentInfo request |
Parent-side helper
js/embed/api.js wraps the protocol if you prefer methods and promises:
<iframe id="pdf" src="/embed.html?file=/report.pdf" width="100%" height="700" style="border:0"></iframe>
<script type="module">
import { createLumaBridge } from './js/embed/api.js';
const luma = createLumaBridge(document.getElementById('pdf'), {
origin: location.origin
});
luma.on('luma:pageChanged', ({ page }) => console.log('page', page));
luma.on('luma:loaded', async () => {
const info = await luma.getDocumentInfo();
console.log(info.pages, 'pages');
luma.setPage(4);
});
</script>Available methods: open, setPage, setZoom, nextPage, previousPage, search, print, download, toggleSidebar, toggleFullscreen, setTheme, getDocumentInfo, on, off, destroy.
Deployment
The project is static. Copy the folder to any host that serves files over HTTPS.
What the host must get right
.jsmust be served astext/javascript(modules fail otherwise).- The PDF.js worker must be reachable at
vendor/pdfjs/pdf.worker.min.js. sw.jsmust be served from the site root (or the sub-folder root) so its scope covers the app.- HTTPS is required for the service worker, installation and clipboard access.
Netlify
# deployment/netlify.toml
[build]
publish = "."
[[headers]]
for = "/*"
[headers.values]
X-Content-Type-Options = "nosniff"
Referrer-Policy = "strict-origin-when-cross-origin"
X-Frame-Options = "SAMEORIGIN"Vercel
{
"cleanUrls": true,
"trailingSlash": false,
"headers": [
{ "source": "/(.*)", "headers": [{ "key": "X-Content-Type-Options", "value": "nosniff" }] }
]
}Apache
AddType text/javascript .js AddType application/pdf .pdf <IfModule mod_headers.c> Header set X-Content-Type-Options "nosniff" </IfModule>
Nginx
types { text/javascript js mjs; application/pdf pdf; }
location / { try_files $uri $uri/ /index.html; }
location = /sw.js { add_header Cache-Control "no-cache"; }The app uses plain file names (viewer.html, embed.html), so no SPA rewrite rules are required. If you enable clean URLs, keep the .html fallback working.
CORS & remote PDFs
A browser will not let JavaScript read a file from another origin unless that server opts in. PDF.js fetches bytes (and uses HTTP Range requests when available), so the PDF host must send:
Access-Control-Allow-Origin: https://your-domain.example Access-Control-Allow-Headers: Range Access-Control-Expose-Headers: Content-Length, Content-Range, Accept-Ranges
If you control neither the host nor the headers, these alternatives work:
- Download the PDF and open it from your device (no network involved).
- Host a copy yourself, or serve it through your own domain.
- Ask the publisher to enable CORS for PDF responses.
Security
- PDF content is parsed by PDF.js with
isEvalSupported: false; embedded JavaScript in a PDF is never executed. - postMessage handlers accept only known commands, only from the parent window, and only from permitted origins.
- Received payloads are reduced to primitives and never evaluated.
- User text is inserted with
textContentor escaped before templating; URLs are validated against an http(s) allow-list. - No analytics, no third-party requests, no hidden uploads.
A reasonable CSP for the app (adjust for your host):
Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self' https: blob:; frame-src 'self' https:; worker-src 'self' blob:; object-src 'none'; base-uri 'none'
'unsafe-inline' in style-src is needed because the viewer positions text spans and annotation nodes with inline styles.
Performance
Three profiles cap rendering cost; the app picks one from navigator.deviceMemory, hardwareConcurrency, connection type and pixel ratio, and you can force one in Settings.
| Profile | Canvas budget | DPR cap | Concurrent renders | Cached pages |
|---|---|---|---|---|
| Eco | 1.6 MP | 1.0 | 1 | 2 |
| Balanced | 4.2 MP | 1.5 | 2 | 4 |
| Performance | 12 MP | 2.0 | 3 | 8 |
Only visible pages (plus a small margin) are rendered; off-screen canvases are released, and thumbnails reuse the on-screen bitmap when possible. Page sizes are measured after the first paint, so a 500-page document opens as fast as a 5-page one.
Testing
A manual checklist that matches what was verified during development:
- Open a local PDF, a same-origin URL and a cross-origin URL that allows CORS.
- Trigger a CORS failure on purpose: the viewer must explain it and offer retry.
- Search for a word present on several pages; step through matches with Enter and Shift+Enter.
- Zoom to 400%, switch to spread and book mode, rotate, then return to fit width.
- Highlight text, draw with the pen, add a note, then export the annotated copy and reopen it.
- Run Merge, Split, Rotate, Watermark and Compress on the same file and open every output.
- In the embed: toggle the sidebar, change theme, and drive it with
setPagefrom the parent. - Install the PWA, go offline, and reopen a saved document from the Library.
- Resize from 320 px to 1920 px: no horizontal scrolling, no clipped toolbars.
Limitations
- Encrypted PDFs can be read with a password, but the editing tools refuse them.
- Signed PDFs lose their signature validity when re-saved.
- OCR is not bundled: the OCR path is an optional add-on and scanned pages have no text layer without it.
- Compression re-renders pages as images, so text stops being selectable.
- Huge files (hundreds of megabytes) are limited by browser memory, not by the app.
- Digital signatures are drawn images, not cryptographic signatures.
Luma PDF v1.0.0 · PDF.js and pdf-lib are used under their respective licences.