Documentation

Developer guide

Everything you need to embed Luma PDF, drive it from JavaScript, and deploy the whole thing on static hosting.

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.

Browsers enforce cross-origin rules. A PDF hosted on another domain only loads if that server sends 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
Unknown parameters are ignored, never fatal. Invalid values fall back to defaults and the viewer reports them on the console.

Parameters

Boolean parameters accept 1/0, true/false, yes/no, on/off, show/hide.

ParameterTypeDefaultWhat it does
fileURL—Absolute or same-origin URL of the PDF. Required.
pageint1Page to open on load.
zoomenum / intpage-widthpage-width, page-fit, actual, or 50–500.
fitenum—width, page or auto; alias for zoom fitting.
toolbarbool1Show the control bar.
sidebarbool0Show the thumbnails/outline panel.
navigationbool1Show page navigation.
searchbool1Enable in-document search.
downloadbool1Show the download button.
printbool1Show the print button.
fullscreenbool1Show the fullscreen button.
controlsenumautoauto, always, never for touch chrome.
mobileToolbarbool1Use the compact bottom bar on phones.
themeenumautolight, dark, auto.
backgroundenumlightlight, dark, sepia, slate, paper.
pageModeenumverticalsingle, vertical, horizontal, spread, book.
scrollenum—vertical or horizontal shortcut.
spreadbool0Shortcut for a two-page spread.
directionenumltrltr or rtl reading direction.
languagestringenSets the document language for assistive tech.
annotationsbool0Enable viewer-side annotation tools.
outlinebool0Show the outline tab in the sidebar.
readonlybool0Disables download, print and annotations.
minimalbool0Compact chrome, no sidebar or print.
hideLogobool0Hide the small Luma PDF mark.
watermarkstring—Faint text overlaid on the reading area.
originlistsame originExtra origins allowed to send commands, comma separated.
Hiding a download button is not DRM. Anyone who can read the PDF in a browser can save it. Use server-side authentication for genuinely restricted documents.

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');
CommandPayloadResult
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:

EventDetail
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:documentInfoDocument 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

  • .js must be served as text/javascript (modules fail otherwise).
  • The PDF.js worker must be reachable at vendor/pdfjs/pdf.worker.min.js.
  • sw.js must 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.
Luma PDF deliberately ships no public CORS proxy. Proxies of that kind break origin security for everyone and are routinely abused.

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 textContent or 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.

ProfileCanvas budgetDPR capConcurrent rendersCached pages
Eco1.6 MP1.012
Balanced4.2 MP1.524
Performance12 MP2.038

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 setPage from 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.