Testing instructions

[jtrachtenberg]

Install (testing)

Decant is packaged for the Web Store, but for testing please use the current testing build. To run locally:

git clone --branch v0.3.2-alpha https://github.com/jtrachtenberg/decant.git
cd decant
npm install
npm run build      # emits the unpacked Chromium extension to dist/

Then load it in Chrome (or Brave/Edge — all load the dist/ build unmodified):

1. Go to chrome://extensions (brave://extensions, edge://extensions)
2. Enable Developer mode (top right)
3. Click Load unpacked and select the dist/ folder

Firefox is built from the same source and supported too:

npm run build:firefox   # emits to dist-firefox/

1. Go to about:debugging → This Firefox
2. Click Load Temporary Add-on and select dist-firefox/manifest.json
   (temporary add-ons are cleared when Firefox restarts)

Known limitations

• Drag-and-drop / paste: Claude, ChatGPT, and Perplexity support the file
  picker, drag-and-drop, and paste. On Gemini, use the file picker —
  its uploader rejects synthetic drops, so drag-and-drop and paste deliberately
  send the original file unconverted rather than lose it. Other platforms —
  please report your findings.
• Enabled by default: Claude, ChatGPT, Gemini, and Perplexity are on by
  default. For other sites, use the extension options page to enable them
  (enabling a host asks Chrome for permission to run there).

---

Fidelity QA — checking a conversion for information loss

Decant converts to Markdown to save tokens. The risk is silent loss —
the Markdown looks fine but dropped data that was in the original. This is a
lightweight way for a tester to catch that: use an LLM as a fidelity judge,
feeding it the original and Decant's Markdown and asking, in a structured
way, what (if anything) was lost. The output doubles as a bug report we can
triage.

---

When to run it

Only for files Decant converted. Check the page console after attaching a
file:

• converted … → there is a Markdown version to audit. Run this.
• passthrough … (scan / no usable text) → the original file was sent
  unchanged, so there is nothing to compare. Skip.
• ambiguous … — prompting → you were asked to choose. If you picked a
  Convert option, it logs a converted line afterward — audit that. If you
  chose to send the original, skip.

---

Setup (read before you start)

• Send the true original to the judge. The judge must see the real PDF,
  not a converted one. Before you upload the original for comparison, press the
  passthrough hotkey (Alt+Shift+O by default) — it arms the next upload
  to be sent untouched, so the judge gets the unaltered file. (Alternatively,
  run the comparison in a chat or on a site where Decant isn't active.)
• Privacy first. These are your own documents. The report below is plain
  text, so you can either use a version that removes PII or share the findings
  without sending us the file. Do not submit confidential PDFs. If the
  document is sensitive, send only the report and a redacted description.
• The judge isn't infallible. It reads the PDF via its own rendering and can
  miss things or over-flag. Treat its report as a strong signal, not proof; for
  important documents, run it twice.

---

Steps (for testers)

1. Convert a file with Decant as normal. Download the converted
   .md attachment, and copy the [decant] converted … line from the console.
2. Arm passthrough with the hotkey (Alt+Shift+O by default), then upload
   the original file so the judge receives it unconverted.
3. Paste the prompt below and send.
4. Copy the result, paste the [decant] console line above it, and send it to us
   as a bug report (omit the PDF if it's sensitive).

---

The prompt

You are auditing a tool that converts PDFs to Markdown to save tokens. I will give you:
1. The ORIGINAL file.
2. The MARKDOWN the tool produced from it.

Determine whether any MEANINGFUL information was lost in the conversion. Compare
them carefully, page by page.

Classify each problem you find:

CATEGORY (one of):
- TEXT      words/sentences/paragraphs missing or garbled
- HEADING   section structure lost or mislabeled
- TABLE     tabular data missing, or present but mis-structured (wrong rows/cols)
- COLUMNS   multi-column text merged/interleaved out of reading order
- FIGURE    data that exists only in an image/chart is missing or unusable
- NUMBERS   figures, statistics, or values dropped or altered
- ORDER     content present but in the wrong order

SEVERITY (one of):
- CRITICAL  changes/loses meaning; a reader would draw wrong conclusions
- MAJOR     notable information lost but the gist survives
- MINOR     cosmetic only (formatting/decorative)

Rules:
- Only report REAL losses you can verify against the file. Do not invent issues.
- Ignore acceptable losses: running headers/footers, page numbers, logos, purely
  decorative elements.
- Quote the specific lost content and cite the page where you can.
- If the Markdown faithfully captures the content, say so plainly.
- Flag your own uncertainty where the file is hard to read.

Respond in EXACTLY this format:

VERDICT: <FAITHFUL | MINOR LOSS | MAJOR LOSS | CRITICAL LOSS>
SUMMARY: <2-3 sentences>

ISSUES:
- [SEVERITY] [CATEGORY] (page N): <description with quoted/located evidence>
(if none: "No information loss found.")

OVERALL FIDELITY: <0-100>% — <one-line justification>

---

What a bug report should include

Paste these together:

1. Decant's console line — e.g. [decant] converted report.pdf → report.md (4p, 1224 chars) [text]. Tells us the decision, page count, size, and reason.
2. The judge's report — the VERDICT … OVERALL FIDELITY block above.
3. Environment — browser + OS, and the Decant version (manifest.json, currently 0.3.0).
4. The File only if it isn't sensitive; otherwise a short description of its
   layout (single/multi-column, tables, charts, scanned pages).