Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
// @vitest-environment happy-dom
/**
* The viewer boot sequence and the save plumbing it installs, driven against a real
* `PDFDocumentProxy` and pdf.js' real event bus. See {@link ./test/fixture_pdf}.
*
* `manageSave` is the reason this file exists: it decides when Trilium is told the document is
* dirty, and most of that logic is heuristic — pdf.js gives no single reliable "annotation
* changed" signal, so the save is nudged from pointer and keyboard activity as well.
*/
import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { applyMinPixelRatio, configurePdfViewerOptions, hideSidebar, main, manageParentCommands, manageSave } from "./bootstrap";
import { setAnnotationEditorUIManager } from "./editing";
import { allFeaturesPdf } from "./test/fixture_pdf";
import { InstalledViewer, installViewerApp, uninstallViewerApp } from "./test/viewer_app";
let viewer: InstalledViewer;
beforeEach(() => {
window.TRILIUM_NOTE_ID = "note-1";
window.TRILIUM_NTX_ID = "ntx-1";
});
afterEach(() => {
setAnnotationEditorUIManager(null);
delete (globalThis as any).pdfjsLib;
uninstallViewerApp();
});
/** Marks an annotation-editing tool as active, as pdf.js does while a tool is selected. */
function startEditing(mode = 15) {
setAnnotationEditorUIManager({ getMode: () => mode, getActive: () => null, hasSelection: false, unselectAll: vi.fn() });
}
/** Adds the `.page` element pdf.js renders each page into, and returns a child of it. */
function renderPage() {
const page = document.createElement("div");
page.className = "page";
const target = document.createElement("span");
page.append(target);
viewer.viewerEl.append(page);
return target;
}
describe("boot sequence", () => {
/** `main()` reads the viewer's configuration off the iframe URL Trilium builds. */
function bootWith(query: string) {
window.history.replaceState({}, "", `/web/viewer.html?${query}`);
return main();
}
// Booting editable installs the localStorage interception, which patches the prototype
// globally and has no uninstall; put the real methods back so it cannot leak sideways.
const realGetItem = Storage.prototype.getItem;
const realSetItem = Storage.prototype.setItem;
afterEach(() => {
Storage.prototype.getItem = realGetItem;
Storage.prototype.setItem = realSetItem;
window.history.replaceState({}, "", "/");
document.body.className = "";
delete window.TRILIUM_HIDE_SIDEBAR;
});
it("marks the document read-only and wires up nothing that can modify it", async () => {
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=0");
expect(document.body.classList.contains("read-only-document")).toBe(true);
viewer.eventBus.dispatch("documentloaded", { source: null });
// Annotations are still listed — they are readable — but nothing that reports the
// document as modified may be installed, or a read-only note would start saving.
await vi.waitFor(() => expect(viewer.messagesOfType("pdfjs-viewer-annotations")).toHaveLength(1));
(viewer.pdfDocument.annotationStorage as any).onSetModified?.();
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
expect(viewer.messagesOfType("pdfjs-viewer-toc")).toHaveLength(0);
});
it("brings up the full editable feature set once the document loads", async () => {
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=1");
expect(document.body.classList.contains("read-only-document")).toBe(false);
viewer.eventBus.dispatch("documentloaded", { source: null });
// Each sidebar panel is fed by its own setup call; a missing one shows as an empty
// panel rather than an error, so assert they all reported.
for (const type of [
"pdfjs-viewer-annotations",
"pdfjs-viewer-toc",
"pdfjs-viewer-page-info",
"pdfjs-viewer-attachments",
"pdfjs-viewer-layers"
]) {
await vi.waitFor(() => expect(viewer.messagesOfType(type).length).toBeGreaterThan(0));
}
// And the save plumbing is live: dirtying the storage reaches the parent.
(viewer.pdfDocument.annotationStorage as any).setValue("field-1", { value: "typed" });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("addresses every message to the viewer that sent it", async () => {
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=1");
viewer.eventBus.dispatch("documentloaded", { source: null });
await vi.waitFor(() => expect(viewer.messagesOfType("pdfjs-viewer-annotations").length).toBeGreaterThan(0));
// Drive the senders that boot alone does not reach.
viewer.eventBus.dispatch("pagechanging", { source: null, pageNumber: 2 });
viewer.sendFromParent({ type: "trilium-request-thumbnail", pageNumber: 1 });
(viewer.pdfDocument.annotationStorage as any).setValue("field-1", { value: "typed" });
await vi.waitFor(() => expect(viewer.messagesOfType("pdfjs-viewer-current-page").length).toBeGreaterThan(0));
// A second open PDF posts onto the same parent window, so what each message carries is the
// only thing telling the two apart. One that says nothing is applied by whichever viewer
// happens to receive it — listing one document's annotations against another's pages.
expect(viewer.messages.length).toBeGreaterThan(0);
for (const message of viewer.messages) {
expect(message).toMatchObject({ type: expect.any(String), noteId: "note-1", ntxId: "ntx-1" });
}
});
it("takes the note and context it reports to from the URL, before the frame has loaded", async () => {
// The parent assigns nothing until the frame's `load` event, which a small document can beat.
delete (window as Partial<Window>).TRILIUM_NOTE_ID;
delete (window as Partial<Window>).TRILIUM_NTX_ID;
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=1¬eId=note-2&ntxId=ntx-2");
viewer.eventBus.dispatch("documentloaded", { source: null });
await vi.waitFor(() => expect(viewer.messagesOfType("pdfjs-viewer-page-info").length).toBeGreaterThan(0));
for (const message of viewer.messages) {
expect(message).toMatchObject({ noteId: "note-2", ntxId: "ntx-2" });
}
});
it("applies the toolbar and sidebar switches from the URL", async () => {
document.body.innerHTML = `
<div id="viewsManagerToggleButton"></div>
<div class="other"></div>
<div class="toolbarButtonSpacer"></div>`;
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=0&toolbar=0&sidebar=0");
expect(document.body.classList.contains("no-toolbar")).toBe(true);
expect(window.TRILIUM_HIDE_SIDEBAR).toBe(true);
});
it("waits for pdf.js to publish its application object before wiring anything", async () => {
vi.useFakeTimers();
// main() is loaded from a script tag that can run before viewer.mjs has created
// PDFViewerApplication, so it polls rather than assuming it is there.
const booted = vi.fn();
const pending = main().then(booted);
await vi.advanceTimersByTimeAsync(200);
expect(booted).not.toHaveBeenCalled();
viewer = await installViewerApp(allFeaturesPdf());
await vi.advanceTimersByTimeAsync(100);
await pending;
expect(booted).toHaveBeenCalled();
vi.useRealTimers();
});
it("adopts the editing manager pdf.js rebuilds for each document", async () => {
viewer = await installViewerApp(allFeaturesPdf());
await bootWith("editable=1");
manageSave();
// Until the manager is announced, input-driven saves cannot tell whether a tool is
// active, so they stay silent.
const target = renderPage();
target.dispatchEvent(new Event("pointerdown", { bubbles: true }));
window.dispatchEvent(new Event("pointerup"));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
viewer.eventBus.dispatch("annotationeditoruimanager", {
source: null,
uiManager: { getMode: () => 15, getActive: () => null, unselectAll: vi.fn() }
});
target.dispatchEvent(new Event("pointerdown", { bubbles: true }));
window.dispatchEvent(new Event("pointerup"));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
});
describe("reporting the document as modified", () => {
it("tells the parent on the signals pdf.js gives for a real change", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const storage = viewer.pdfDocument.annotationStorage as any;
const resetModified = vi.spyOn(storage, "resetModified");
manageSave();
// The primary hook: pdf.js dirties annotationStorage, as filling in a form field does.
storage.setValue("field-1", { value: "typed" });
// Deletions and undo/redo only surface here, and only when there is something to undo.
// Left unconditional: the first stroke of an ink session flips hasSomethingToUndo while
// the drawing is still outside annotationStorage, so there is nothing to compare against.
viewer.eventBus.dispatch("editingstateschanged", { source: null, details: { hasSomethingToUndo: true } });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(2);
expect(viewer.lastMessageOfType("pdfjs-viewer-document-modified"))
.toEqual({ type: "pdfjs-viewer-document-modified", noteId: "note-1", ntxId: "ntx-1" });
// Without the reset pdf.js keeps reporting the same change on every later edit.
expect(resetModified).toHaveBeenCalledTimes(2);
});
it("stays quiet while pdf.js registers the annotations already in the document", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const storage = viewer.pdfDocument.annotationStorage as any;
const resetModified = vi.spyOn(storage, "resetModified");
manageSave();
// Entering an editing mode turns every stored annotation on a rendered page into an
// editor, and registering each one dirties annotationStorage. Nothing about the document
// changed, so pressing a toolbar button — or scrolling another annotated page into view —
// must not schedule a save, let alone one per annotation (#11059).
storage.onSetModified();
storage.onSetModified();
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
// The flag still has to be cleared, or pdf.js' one-shot would never raise the next
// real change.
expect(resetModified).toHaveBeenCalledTimes(2);
// Which it does: an actual edit is still reported.
storage.setValue("field-1", { value: "typed" });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("treats a document that cannot be serialized as unchanged, then catches up", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const storage = viewer.pdfDocument.annotationStorage as any;
// pdf.js stores an editor before it is finished: "Add signature" leaves one with no
// outlines in annotationStorage until the dialog resolves, and serializing it throws.
// That is a state pdf.js passes through, not a change to report — and not a reason to
// let the throw out of the storage hook, or out of the setup, either.
const serializable = vi.spyOn(storage, "serializable", "get").mockImplementation(() => {
throw new Error("outlines are not set yet");
});
expect(() => manageSave()).not.toThrow();
expect(() => storage.setValue("sig-1", { value: "pending" })).not.toThrow();
viewer.eventBus.dispatch("switchannotationeditorparams", { source: null });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
// The interaction nudges still report blind, and cope with the same state.
startEditing();
renderPage().dispatchEvent(new Event("keyup", { bubbles: true }));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
// Once the editor is complete the document serializes again, and the change it made is
// reported against the last hash that could be read — not swallowed.
serializable.mockRestore();
storage.setValue("sig-1", { value: "signed" });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(2);
});
it("stays quiet when a tool's parameters leave the document alone", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
// With nothing selected, the colour picker in a tool's parameter toolbar only sets what
// the next annotation will be drawn in.
viewer.eventBus.dispatch("switchannotationeditorparams", { source: null });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
});
it("reports a parameter change that does alter an annotation", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const storage = viewer.pdfDocument.annotationStorage as any;
manageSave();
// Recolouring a selected annotation rewrites what the document serializes to, and this
// event is the only notice of it — pdf.js updates the editor in place rather than going
// back through onSetModified. Detaching the hook reproduces that: the content changes,
// nothing else reports it.
const hook = storage.onSetModified;
storage.onSetModified = null;
storage.setValue("18R", { value: "recoloured" });
storage.onSetModified = hook;
viewer.eventBus.dispatch("switchannotationeditorparams", { source: null });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("survives an editor pdf.js has stored before finishing it", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const storage = viewer.pdfDocument.annotationStorage as any;
manageSave();
// Pressing "Add signature" adds a SignatureEditor to annotationStorage — its own
// isEmpty() returns false unconditionally — while its outlines are still null, and only
// fills them in when the signature dialog resolves. Serializing the document in between
// throws out of the storage hook, from where it reaches the console uncaught.
Object.defineProperty(storage, "serializable", {
configurable: true,
get() {
throw new TypeError("can't access property \"serialize\", this[#drawOutlines] is null");
}
});
expect(() => storage.onSetModified()).not.toThrow();
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
// The hash the failed read fell back to has to be the one from before, or the finished
// signature would look unchanged and never be saved.
delete storage.serializable;
storage.setValue("field-1", { value: "typed" });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("stays quiet when the editing state changes with nothing to undo", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
// Selecting an existing annotation raises this too; saving on it would mark the note
// dirty just for a click.
viewer.eventBus.dispatch("editingstateschanged", { source: null, details: { hasSomethingToUndo: false } });
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
});
});
describe("nudging the save from input activity", () => {
it("reports a change when a stroke that began on a page ends", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
startEditing();
const target = renderPage();
// Only the first stroke of an ink session flips hasSomethingToUndo; later strokes
// accumulate in the uncommitted session, so the end of each one has to nudge the save.
target.dispatchEvent(new Event("pointerdown", { bubbles: true }));
window.dispatchEvent(new Event("pointerup"));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("still reports when a stroke starts on a page but ends outside it", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
startEditing();
const target = renderPage();
// pdf.js tracks strokes window-wide, so drawing off the edge of the page is normal;
// what matters is where the interaction began.
target.dispatchEvent(new Event("pointerdown", { bubbles: true }));
document.body.dispatchEvent(new Event("pointercancel", { bubbles: true }));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
it("ignores input while no annotation tool is active", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
const target = renderPage();
// Selecting text or scrolling must not mark the note dirty.
target.dispatchEvent(new Event("pointerdown", { bubbles: true }));
window.dispatchEvent(new Event("pointerup"));
target.dispatchEvent(new Event("keyup", { bubbles: true }));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(0);
});
it("reports typing on a page while a tool is active", async () => {
viewer = await installViewerApp(allFeaturesPdf());
manageSave();
startEditing();
const target = renderPage();
target.dispatchEvent(new Event("keyup", { bubbles: true }));
// Typing outside any page (the toolbar, the sidebar) is not an edit.
document.body.dispatchEvent(new Event("keyup", { bubbles: true }));
expect(viewer.messagesOfType("pdfjs-viewer-document-modified")).toHaveLength(1);
});
});
describe("producing the saved document", () => {
it("commits pending edits, returns the bytes, and refreshes the annotations", async () => {
viewer = await installViewerApp(allFeaturesPdf());
(globalThis as any).pdfjsLib = { getDocument };
const unselectAll = vi.fn();
setAnnotationEditorUIManager({ getMode: () => 15, getActive: () => null, hasSelection: false, unselectAll });
manageSave();
viewer.sendFromParent({ type: "trilium-request-blob" });
await vi.waitFor(() => expect(viewer.messagesOfType("pdfjs-viewer-blob")).toHaveLength(1));
// An in-progress edit is not in annotationStorage yet, so saving without committing
// first would silently drop it.
expect(unselectAll).toHaveBeenCalled();
const blob = viewer.lastMessageOfType("pdfjs-viewer-blob");
expect(blob).toMatchObject({ noteId: "note-1", ntxId: "ntx-1" });
expect(blob.data.length).toBeGreaterThan(0);
// The bytes must be a real PDF the viewer can reopen, not a partial write.
await expect(getDocument({ data: blob.data }).promise).resolves.toBeTruthy();
});
it("does not save on a request from another origin", async () => {
viewer = await installViewerApp(allFeaturesPdf());
const saveDocument = vi.spyOn(viewer.pdfDocument, "saveDocument");
manageSave();
window.dispatchEvent(new MessageEvent("message", {
data: { type: "trilium-request-blob" },
origin: "https://evil.example"
}));
await new Promise((resolve) => setTimeout(resolve, 10));
expect(saveDocument).not.toHaveBeenCalled();
});
});
describe("commands forwarded from the parent", () => {
it("prints and opens the find bar on request, and ignores other origins", async () => {
viewer = await installViewerApp(allFeaturesPdf());
// happy-dom does not implement print(), so there is nothing to spy on.
const print = vi.fn();
window.print = print;
const open = vi.fn();
const app = window.PDFViewerApplication;
if (app) {
app.findBar = { open, close: vi.fn(), toggle: vi.fn() };
}
manageParentCommands();
viewer.sendFromParent({ type: "trilium-print" });
viewer.sendFromParent({ type: "trilium-find" });
window.dispatchEvent(new MessageEvent("message", {
data: { type: "trilium-print" },
origin: "https://evil.example"
}));
await new Promise((resolve) => setTimeout(resolve, 10));
expect(print).toHaveBeenCalledTimes(1);
expect(open).toHaveBeenCalledTimes(1);
});
});
describe("viewer configuration", () => {
afterEach(() => {
// applyMinPixelRatio redefines this getter on the window.
Object.defineProperty(window, "devicePixelRatio", { configurable: true, value: 1 });
});
it("raises the device pixel ratio only when it would sharpen rendering", () => {
Object.defineProperty(window, "devicePixelRatio", { configurable: true, value: 1 });
applyMinPixelRatio(new URLSearchParams("minPixelRatio=2"));
// pdf.js reads devicePixelRatio at render time to size the page canvas, so raising it
// supersamples the output on a standard-DPI display.
expect(window.devicePixelRatio).toBe(2);
// A display that already exceeds the minimum must be left alone rather than downgraded.
applyMinPixelRatio(new URLSearchParams("minPixelRatio=1.5"));
expect(window.devicePixelRatio).toBe(2);
});
it("ignores a missing or nonsensical pixel ratio", () => {
Object.defineProperty(window, "devicePixelRatio", { configurable: true, value: 1 });
for (const query of [ "", "minPixelRatio=0", "minPixelRatio=-3", "minPixelRatio=nope" ]) {
applyMinPixelRatio(new URLSearchParams(query));
expect(window.devicePixelRatio).toBe(1);
}
});
it("applies the viewer options once pdf.js announces itself", () => {
const set = vi.fn();
window.PDFViewerApplicationOptions = { set };
configurePdfViewerOptions();
// pdf.js fires this on the document when the viewer script has loaded; the options
// have to be set in that window, before it reads its own preferences.
document.dispatchEvent(new CustomEvent("webviewerloaded", { detail: { source: window } }));
expect(Object.fromEntries(set.mock.calls)).toMatchObject({
disablePreferences: true,
enableHighlightFloatingButton: true,
enableComment: true,
enableSignatureEditor: true
});
delete window.PDFViewerApplicationOptions;
});
it("hides the sidebar toggle along with the spacer that follows it", () => {
document.body.innerHTML = `
<div id="viewsManagerToggleButton"></div>
<div class="other"></div>
<div class="toolbarButtonSpacer"></div>`;
hideSidebar();
// Leaving the spacer behind would show a gap where the button used to be.
expect(window.TRILIUM_HIDE_SIDEBAR).toBe(true);
expect(document.getElementById("viewsManagerToggleButton")?.style.display).toBe("none");
expect(document.querySelector(".toolbarButtonSpacer")).toBeNull();
});
});