margin-docs/tests/export-writes-only-the-pdf.spec.ts

// An export writes the PDF and nothing else.
//
// The claim in src/export/run.ts is a claim about what an export does NOT do: it never calls
// `save`, never dispatches a transaction, and asks the document store for nothing but the path and
// the tree it is already holding. Every other suite reads that off the screen. This one reads it
// off the wire and off the fixture, the way tests/bytes.spec.ts does, because the promise is about
// bytes: choosing to export a document must not turn into writing over a file the user had not
// decided to write yet, and there is no undo for that on disk.
//
// The document exported here has an unsaved edit in it, which is the case that can actually hurt.
// A save on the way into an export would look harmless on a clean buffer and would silently commit
// half a paragraph on a dirty one. Writes are held through `external.pauseWrites` so the buffer
// stays dirty for as long as the export takes rather than racing the 500ms autosave, and the edit
// is let through afterwards to prove it was real: a file that did not change because the edit had
// evaporated would prove nothing at all.
//
// It also carries an image, a table, a formula and a mermaid fence, because those are the four
// blocks the converter does extra work for, and three of them put something in the compile that no
// other block does: the image travels as an absolute path for the backend to open, the diagram is
// drawn to SVG and travels as bytes, and the formula becomes a mitex call. The Typst source and the
// image list handed to `pdf_compile` are asserted here for exactly that reason. An export that
// wrote nothing because it never got past the first paragraph is the shape of green this suite is
// built to refuse.
//
// The export is two gestures now rather than one. Cmd-E opens the preview in
// src/components/ExportPreview.tsx, which compiles and puts the pages on screen; Save PDF is what
// reaches the native panel and the write. That changes the shape of this test and not its subject:
// the promise is still that nothing between the keystroke and the write touches the document, and
// the command log below is still the whole of the evidence. If anything, the window in which a
// stray save could hide got longer, because the buffer now sits dirty behind an open panel for as
// long as the user looks at the pages.
//
// WHAT A BROWSER CANNOT REACH. The command gates on `isDesktop`, which is `isTauri` and not a
// phone. `isTauri` reads `__TAURI_INTERNALS__` off the window and tests/disk.ts puts that there at
// document start, so the gate opens and the whole path runs: convert, draw, compile, preview,
// panel, write. What is behind it is the dev fixture, so `pdf_compile` answers with a PDF header
// instead of a typeset document and `pdf_write` puts nothing anywhere. Eight bytes is not a PDF
// pdf.js can open, so the preview's stage stays empty here and the page count stays at zero: what
// this suite drives is the bar around it, which is live either way because the bytes it saves came
// from the compiler and not from the reader. That the compiler produces a real PDF, that pdf.js
// draws it, and that the write lands where it was pointed are questions for a real build and for
// src-tauri/tests/export_writes_only_the_pdf.rs. The one piece nothing can drive from either side
// is the native save panel itself: it is an AppKit window, so this spec answers the command for it
// and cannot say what a real panel would hand back for a name the user typed. That distinction
// matters, and the Rust suite is where it is followed up.

import { expect, test, type Page } from "@playwright/test";
import { putCaret } from "./caret";
import { ask, change, installTauriShim } from "./disk";

const HANDBOOK = "/Users/you/Documents/Handbook";
const README = `${HANDBOOK}/README.md`;
/** The picture the document points at, which the fixture really has. */
const PICTURE = `${HANDBOOK}/reference/assets/diagram.png`;
/** Where the save panel is pointed: outside the folder, which is the ordinary case. */
const TARGET = "/Users/you/Desktop/README.pdf";

const row = (path: string) => `.tree-row[data-path="${path}"]`;

/** Longer than the 500ms autosave debounce in src/document.ts, with room for the write itself. */
const SAVED = 1500;

/** Mermaid is several megabytes and is fetched on the first diagram, so the first export is slow. */
const EXPORTED = 20_000;

/**
 * One document holding all four of the blocks the converter does extra work for. Built by joining
 * lines rather than as a template literal because a mermaid fence is three backticks.
 */
const SOURCE = [
  "# Quarterly report",
  "",
  "Prose before anything difficult.",
  "",
  "![the diagram](reference/assets/diagram.png)",
  "",
  "| region | total |",
  "| ------ | ----- |",
  "| north | 12 |",
  "| south | 9 |",
  "",
  "$$",
  "E = mc^2",
  "$$",
  "",
  "```mermaid",
  "graph TD",
  "  A[Start] --> B[Finish]",
  "```",
  "",
  "Closing line.",
  "",
].join("\n");

/** One command as it crossed the boundary, with the fields worth keeping off the ones that have them. */
interface Sent {
  command: string;
  /** The destination, for the two commands that name one: `file_write` and `pdf_write`. */
  path: string | null;
  /** The Typst source, for the one command that carries it. */
  source: string | null;
  /** What the compile was handed to open, and whether the bytes came with it or are on disk. */
  images: { path: string; inline: boolean }[] | null;
}

/** One `listen` the app has registered: which event, and the callback id the shim gave it. */
interface Listen {
  event: string;
  id: number;
}

interface Internals {
  invoke: (command: string, args?: Record<string, unknown>) => unknown;
  runCallback: (id: number, data: unknown) => void;
}

declare global {
  interface Window {
    __sent: Sent[];
    __listens: Listen[];
    /** What the save panel answers with. `null` is the user pressing Cancel. */
    __savePanel: string | null;
    __TAURI_INTERNALS__: Internals;
  }
}

/**
 * Records every command the app sends, and answers the one a browser has no window for.
 *
 * Added after `installTauriShim`, which puts `__TAURI_INTERNALS__` on the window synchronously.
 * Wrapping that object's `invoke` rather than the app's own wrapper is what makes this a
 * measurement of what was sent rather than of what src/api/pdf.ts meant to send: a `file_write`
 * from anywhere in the app, on any path, lands in this list.
 */
function recordIpc(): void {
  window.__sent = [];
  window.__listens = [];
  window.__savePanel = null;
  const internals = window.__TAURI_INTERNALS__;
  const real = internals.invoke;
  internals.invoke = (command, args) => {
    const images = (args?.images as { path: string; data: string | null }[] | undefined) ?? null;
    window.__sent.push({
      command,
      path: (args?.path as string) ?? null,
      source: (args?.source as string) ?? null,
      images: images === null ? null : images.map((i) => ({ path: i.path, inline: i.data !== null })),
    });
    if (command === "plugin:event|listen") {
      window.__listens.push({ event: args?.event as string, id: args?.handler as number });
    }
    // The save panel is an AppKit window. This is the one thing in the whole path a browser cannot
    // have, so it is answered here and everything either side of it is the running program.
    if (command === "plugin:dialog|save") return Promise.resolve(window.__savePanel);
    return real(command, args);
  };
}

/** Opens the README with the given bytes in it and waits for them to be on screen. */
async function open(page: Page, source: string): Promise<void> {
  await page.addInitScript(installTauriShim);
  await page.addInitScript(recordIpc);
  await page.addInitScript(() => {
    localStorage.clear();
    localStorage.setItem("margindocs-recents", JSON.stringify(["/Users/you/Documents/Handbook"]));
  });
  await page.goto("/");
  await expect(page.locator(row(HANDBOOK))).toBeVisible();
  await page.locator(row(README)).click();
  await expect(page.locator(".prose")).toBeVisible();

  // Written from outside rather than typed, so the app has not registered a self-write and this is
  // a file it has only ever read.
  await change(page, "write", README, source);
  await expect.poll(() => ask<string>(page, "read", README)).toBe(source);
}

/** What is on disk now. */
const disk = (page: Page, path = README): Promise<string> => ask<string>(page, "read", path);

const sent = (page: Page): Promise<Sent[]> => page.evaluate(() => window.__sent);

const commands = async (page: Page): Promise<string[]> =>
  (await sent(page)).map((call) => call.command);

const toast = (page: Page) => page.locator(".toast");

/**
 * The gesture, which is the File menu and not a call to `exportPdf`.
 *
 * The same route tests/writing-tools.spec.ts takes and for the same reason: src-tauri/src/lib.rs
 * answers its own row by emitting `menu-action` with the command id, App.tsx has a `listen` on that
 * event, and src/keys/menu.ts turns the payload into a command. Everything from the event on is the
 * running program.
 */
async function runFromMenu(page: Page, command: string): Promise<void> {
  const delivered = await page.evaluate((id) => {
    let count = 0;
    for (const subscription of window.__listens) {
      if (subscription.event !== "menu-action") continue;
      window.__TAURI_INTERNALS__.runCallback(subscription.id, {
        event: "menu-action",
        id: subscription.id,
        payload: id,
      });
      count += 1;
    }
    return count;
  }, command);
  // An event nobody is subscribed to is the shape of test that passes because nothing happened.
  expect(delivered, "the app has no menu-action listener to fire at").toBeGreaterThan(0);
}

const preview = (page: Page) => page.locator(".preview-panel");
const savePdf = (page: Page) => preview(page).locator(".btn-primary");

/**
 * Opens the preview and waits for the compile behind it to finish.
 *
 * Save is disabled until there are bytes to save, so a live button is the signal that `pdf_compile`
 * has answered. Waiting on that rather than on the pages is deliberate: the fixture's eight bytes
 * never become pages, and a test that waited for a canvas would be waiting for the compiler this
 * build does not have.
 */
async function openPreview(page: Page): Promise<void> {
  await runFromMenu(page, "export-pdf");
  await expect(preview(page)).toBeVisible();
  await expect(savePdf(page)).toBeEnabled({ timeout: EXPORTED });
}

/**
 * Types a character into the first paragraph and holds the save that would follow, so the buffer is
 * dirty and the file is not, for as long as the caller needs. Answers with the log as it stood the
 * moment the buffer settled, which is the line everything after it is measured from.
 */
async function dirtyWithHeldSave(page: Page): Promise<number> {
  await ask(page, "pauseWrites");

  const paragraph = page.locator(".prose p").first();
  await paragraph.click();
  await putCaret(paragraph, "end");
  await page.keyboard.type("Z");

  await expect(page.locator(".dirty-dot")).toBeVisible();
  // The autosave has fired and is sitting in the gate. Waiting for it rather than for a timeout is
  // what makes the count below a line the export is measured against instead of a race with it.
  await expect
    .poll(async () => (await commands(page)).filter((c) => c === "file_write").length)
    .toBe(1);

  return (await sent(page)).length;
}

test("an export of a document with unsaved edits writes nothing but the PDF", async ({ page }) => {
  test.setTimeout(60_000);
  await open(page, SOURCE);

  // All four of the blocks the converter does extra work for are really on screen, so the export
  // below is the export this test is about and not a page of prose that happens to be green.
  // Not every `img` under `.prose` is the document's: prosemirror-view puts a zero width
  // `ProseMirror-separator` after an inline node that ends a textblock, and it is one too.
  await expect(page.locator(".prose img:not(.ProseMirror-separator)")).toHaveCount(1);
  await expect(page.locator(".prose table")).toHaveCount(1);
  await expect(page.locator(".prose [data-math-block]")).toHaveCount(1);
  await expect(page.locator(".prose .mermaid-block")).toHaveCount(1);

  const line = await dirtyWithHeldSave(page);
  const before = await page.locator(".prose").innerHTML();
  await page.evaluate((target) => {
    window.__savePanel = target;
  }, TARGET);

  await openPreview(page);

  // The compile happened on the way into the preview and nothing has been written yet, which is
  // the half of this flow that did not exist before. A panel that had reached for the save dialog
  // on its own would show up here.
  const compiled = (await sent(page)).slice(line).map((call) => call.command);
  expect(compiled).toEqual(["plugin:event|listen", "pdf_compile", "plugin:event|unlisten"]);

  await savePdf(page).click();
  await expect(toast(page)).toContainText("Exported README.pdf", { timeout: EXPORTED });
  // A written file is the end of the preview's job, so it closes behind the toast.
  await expect(preview(page)).toHaveCount(0);

  const during = (await sent(page)).slice(line);

  // 1. Exactly these commands crossed the boundary, in this order, and no other. `file_write` is
  //    not among them, and neither is `file_read`: the export asked the document store for the
  //    tree it was already holding and went to the compiler with it.
  expect(during.map((call) => call.command)).toEqual([
    "plugin:event|listen",
    "pdf_compile",
    "plugin:event|unlisten",
    "plugin:dialog|save",
    "pdf_write",
  ]);

  // 2. The bytes went where the panel pointed, and nowhere else.
  expect(during.find((call) => call.command === "pdf_write")?.path).toBe(TARGET);

  // 3. The file on disk is the one that was read, byte for byte. This is the whole test.
  expect(await disk(page)).toBe(SOURCE);

  // 4. And the buffer is still dirty, which is the other half of it: an export that had quietly
  //    saved on the way past would leave a clean buffer and an unchanged-looking file, and the
  //    unchanged-looking file would be the one with the edit in it. The document on screen is the
  //    one that went in, too: `documentToTypst` is handed the live tree rather than a copy, so a
  //    converter that mutated it, or a transaction that changed the document on the way past,
  //    would show up here as a paragraph that is not the one that was exported.
  await expect(page.locator(".dirty-dot")).toBeVisible();
  expect(await page.locator(".prose").innerHTML()).toBe(before);

  // 5. The four paths did their extra work. The image travels as the absolute path the backend
  //    opens under the root guard; the diagram was drawn and travels as bytes because it has no
  //    file behind it; the formula is a mitex call; the table is a Typst table. A compile handed
  //    none of that would have written nothing either, and would have proved nothing.
  const compile = during.find((call) => call.command === "pdf_compile");
  expect(compile?.images).toEqual([
    { path: PICTURE, inline: false },
    { path: "/inline/diagram-1.svg", inline: true },
  ]);
  expect(compile?.source).toContain(PICTURE);
  expect(compile?.source).toContain("#table(");
  expect(compile?.source).toContain("mitex");

  // 6. The edit was real all along. Letting the held save through writes the character that was
  //    typed, so the file that did not move during the export was a file with a pending edit
  //    against it rather than a buffer that had lost one.
  await ask(page, "resumeWrites");
  await expect.poll(() => disk(page)).toContain("difficult.Z");
  expect(await disk(page)).not.toBe(SOURCE);

  // 7. One write for the whole session, which is the autosave's, and it went out before the export
  //    started rather than because of it.
  //
  //    What this cannot see, said plainly rather than left for the next person to assume. Holding
  //    the write is what keeps the buffer dirty for the length of an export, and it is also the
  //    one state in which a fire and forget `void save()` inside `exportPdf` would leave no trace:
  //    `saveNow` in src/document.ts folds a request that arrives while a write is on the wire into
  //    a single next lap, and by the time the gate opens that lap finds the buffer clean and skips.
  //    Measured, by putting that line into the module and watching this test stay green. An
  //    `await`ed one is caught, loudly, because the export then never reaches the panel at all.
  //    The reason the gap is narrow rather than alarming is the debounce itself: the buffer can
  //    only be dirty while a save is pending or in flight, so an export that saved would be
  //    writing the bytes the debounce was about to write anyway. What is worth proving is that the
  //    export adds no write of its own, and that is what steps 1 to 6 are.
  await page.waitForTimeout(SAVED);
  expect((await commands(page)).filter((c) => c === "file_write")).toEqual(["file_write"]);
});

test("cancelling the save panel leaves the document exactly where it was", async ({ page }) => {
  // The branch that returns halfway through, after a compile and before a write. It is worth its
  // own test because it is the one place an export ends without a toast to say so, and a tidy-up
  // on that path that reached for `save` would be invisible on screen and permanent on disk.
  test.setTimeout(60_000);
  await open(page, SOURCE);
  await expect(page.locator(".prose .mermaid-block")).toHaveCount(1);

  const line = await dirtyWithHeldSave(page);
  // `__savePanel` is left as null, which is what the panel answers when the user presses Cancel.

  await openPreview(page);
  await savePdf(page).click();
  await expect
    .poll(async () => (await commands(page)).filter((c) => c === "plugin:dialog|save").length, {
      timeout: EXPORTED,
    })
    .toBe(1);

  const during = (await sent(page)).slice(line);
  expect(during.map((call) => call.command)).toEqual([
    "plugin:event|listen",
    "pdf_compile",
    "plugin:event|unlisten",
    "plugin:dialog|save",
  ]);

  expect(await disk(page)).toBe(SOURCE);
  await expect(page.locator(".dirty-dot")).toBeVisible();
  await expect(toast(page)).toHaveCount(0);

  // And the preview is still up, holding the bytes it already compiled. Cancelling the save panel
  // is somebody deciding not to write this file yet, not somebody finished looking at it, so a
  // second Save must not cost a second compile.
  await expect(preview(page)).toBeVisible();
  await expect(savePdf(page)).toBeEnabled();
});