Fix Zotero 8+ compatibility: file picker crash and ChromeUtils.import errors (#41)

* Fix Save As crash on Zotero 8+ by using Zotero's FilePicker module

Firefox 128+ (Zotero 8) changed nsIFilePicker.init() to take a
BrowsingContext instead of a window, so the raw nsIFilePicker code in
promptSavePath() threw NS_ERROR_XPC_BAD_CONVERT_JS on Zotero 8/9 and the
markdown .zip export never showed a save dialog.

Route the dialog through the toolkit's FilePickerHelper, which delegates
to Zotero's own FilePicker module (chrome://zotero/content/modules/
filePicker.mjs). Zotero's wrapper passes window.browsingContext on new
platforms and keeps working on Zotero 7, so the plugin no longer touches
the changing XPCOM signature directly.

Fixes #39

https://claude.ai/code/session_01KUFXvTTsWqrPNDJ8Vi1oPL

* Silence ChromeUtils.import() errors on Zotero 8+ via build-time toolkit patch

zotero-plugin-toolkit (through at least 5.1.2) detects the legacy JSM
loader with `typeof ChromeUtils.import === "undefined"`. On Zotero 8+
(Firefox 140) ChromeUtils.import still exists but only throws
"ChromeUtils.import() has been removed. Use importESModule()", so the
toolkit rewrote Console.sys.mjs back to Console.jsm and the import threw
once per helper constructed at startup — 16 console errors on every
launch.

Add an esbuild plugin that patches the bundled toolkit's _importESModule
to try ChromeUtils.importESModule first (available since Firefox 106, so
on every supported Zotero) and keep the legacy loader as a fallback for
Zotero 7. The patch is an exact-match string replacement that fails the
build loudly if the toolkit source changes, so a future toolkit upgrade
cannot silently un-apply it; once the toolkit fixes its feature
detection upstream, the plugin block can simply be deleted.

Fixes #40

https://claude.ai/code/session_01KUFXvTTsWqrPNDJ8Vi1oPL

* README: add a novice-friendly quick start and smooth the install path

Getting-started editing pass aimed at first-time users:

- Add a Quick start section that spells out the two-part setup (local
  docling-serve + plugin) and walks the happy path end to end, with a
  heads-up about the first-run model download.
- Link installation guides for uv and pipx, and point readers without
  Python tooling at the container option.
- Add a browser-based sanity check (the /ui playground) alongside curl.
- Turn plugin installation into numbered steps, drop the stale "(when
  available)" hedge, and warn about Firefox auto-installing the .xpi.
- Mark the from-source path as development-oriented (Node 20+) and scope
  the macOS .env note to the npm start workflow.
- Fix the "within seconds" promise that contradicted the 2-10 minute
  first-run download, and de-emoji the model-weights heading so section
  anchors stay stable.

https://claude.ai/code/session_01KUFXvTTsWqrPNDJ8Vi1oPL

* Add an Exclude images option for text-and-tables-only markdown

docling-serve defaults image_export_mode to "embedded", which inlines
every figure as a base64 data URI and can grow a paper's .md by tens of
megabytes. A new opt-in "Exclude images" checkbox in Settings → Output
sends image_export_mode=placeholder instead, so each image becomes a
tiny <!-- image --> comment and the markdown keeps only text and tables.

The plugin now always sends image_export_mode explicitly ("embedded"
when the box is unticked — identical to the previous server-default
behavior), and the advancedJson escape hatch still overrides it for
users who want "referenced" or other modes. Wired through prefs.js
defaults, generated pref typings, the preferences pane (+ en-US
strings), reset-to-defaults, buildConvertForm and its unit tests, and
the README feature list.

https://claude.ai/code/session_01KUFXvTTsWqrPNDJ8Vi1oPL

* Add a Remove-images utility for existing docling markdown

Markdown converted before the Exclude-images option (or with it off)
carries every figure as an embedded base64 data URI, so a single paper's
.md can be tens of megabytes. This adds a retroactive cleanup: select
items and right-click "Remove images from markdown" (or Tools → Docling:
Remove images from markdown…) to rewrite their .md attachments in place,
replacing each markdown image or raw <img> tag with the same
<!-- image --> placeholder docling emits in image_export_mode=placeholder.

The pure transform lives in utils/stripImages.ts: line-based so fenced
code blocks are skipped (image syntax shown in a code sample isn't an
image), inline-safe so images inside table cells keep the table shape,
and idempotent. The orchestrator in modules/removeImages.ts resolves
selections the same way the zip export does (md attachments directly,
PDFs via their matching .md sibling, parents via their PDF children),
guards the destructive rewrite behind a confirm dialog, refuses to run
while a conversion batch is in flight, and reports replaced-image count
and bytes saved (new formatBytes helper) in the completion toast.

Covered by unit tests for the transform (embedded/table/HTML/fence/
idempotence cases plus fast-check properties) and formatBytes.

https://claude.ai/code/session_01KUFXvTTsWqrPNDJ8Vi1oPL

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: brianckeegan

README.md

@@ -1,8 +1,9 @@
 # zotero-docling
 
-A Zotero 7+/9 plugin that converts PDF attachments to structured Markdown using
-the [Docling](https://github.com/docling-project/docling) document-understanding
-pipeline, and attaches the resulting `.md` file back to the same parent item.
+A Zotero plugin (Zotero 7 or later) that converts PDF attachments to structured
+Markdown using the [Docling](https://github.com/docling-project/docling)
+document-understanding pipeline, and attaches the resulting `.md` file back to
+the same parent item.
 
 [![Release](https://img.shields.io/github/v/release/max3925vats/zotero-docling?style=flat-square)](https://github.com/max3925vats/zotero-docling/releases/latest)
 [![License](https://img.shields.io/github/license/max3925vats/zotero-docling?style=flat-square)](LICENSE)
@@ -13,9 +14,44 @@ pipeline, and attaches the resulting `.md` file back to the same parent item.
 
 ---
 
-Structured markdown makes a clean upstream for note apps, RAG pipelines,
-citation extraction, summarisation, literature reviews, and any downstream
-tool that prefers plain text over PDFs.
+Markdown is plain text, so converted papers drop straight into note apps like
+Obsidian, AI/RAG pipelines, citation extraction, summarisation, literature
+reviews — anything that prefers text over PDFs.
+
+---
+
+## Quick start
+
+The setup has two halves: a small **local server**
+([docling-serve](https://github.com/docling-project/docling-serve)) does the
+actual PDF → Markdown conversion, and this **plugin** connects Zotero to it.
+You need both.
+
+1. **Start the converter server.** The quickest path uses
+   [uv](https://docs.astral.sh/uv/getting-started/installation/) (a Python
+   tool installer); see [Install the server](#install-the-server-docling-serve)
+   for pipx and Docker alternatives that may suit you better.
+
+   ```bash
+   uv tool install "docling-serve[ui]"   # one-time install
+   docling-serve run                     # leave this terminal open
+   ```
+
+2. **Install the plugin.** Download the latest `.xpi` file from the
+   [Releases page](https://github.com/max3925vats/zotero-docling/releases/latest)
+   (if your browser tries to install it itself, right-click the link and
+   choose "Save Link As…"). Then in Zotero: **Tools → Plugins → ⚙ →
+   Install Plugin From File…** → pick the `.xpi`.
+
+3. **Connect them.** In Zotero, open **Settings → zotero-docling** and click
+   **Test Connection** — it should turn green. Then right-click any PDF in
+   your library → **Convert with Docling**.
+
+> [!NOTE]
+> Your very first conversion downloads model weights and can take 2–10
+> minutes while appearing to hang — that's normal, and later conversions
+> take seconds. See
+> [First conversion downloads model weights](#first-conversion-downloads-model-weights).
 
 ---
 
@@ -34,6 +70,14 @@ tool that prefers plain text over PDFs.
 - **Full Docling options surfaced**: pipeline (standard / VLM), OCR + language,
   table mode, formula / code / chart / picture enrichments, VLM presets, plus
   an Advanced JSON escape hatch for anything not in the UI.
+- **Exclude images** (opt-in): keep the markdown text-and-tables only — each
+  figure becomes a tiny placeholder comment instead of megabytes of embedded
+  base64 image data. Tick **Exclude images** in **Settings → Output**.
+- **Remove images from existing markdown**: right-click already-converted
+  items (or **Tools → Docling: Remove images from markdown…**) to rewrite
+  their `.md` attachments in place, swapping every embedded image for a
+  `<!-- image -->` placeholder — the retroactive version of Exclude images,
+  no re-conversion needed.
 - **Per-parent status tags**: parents get tagged `docling/done`,
   `docling/incomplete`, or `docling/error` so you can filter your library by
   conversion status.
@@ -61,7 +105,8 @@ tool that prefers plain text over PDFs.
 ## Install the server (docling-serve)
 
 Pick one of the three paths below — they all yield a `docling-serve` you can
-point the plugin at. Roughly:
+point the plugin at. If you've never touched Python tooling, the container
+path avoids it entirely. Roughly:
 
 | Option        | Best for                                                        | Needs                |
 | ------------- | --------------------------------------------------------------- | -------------------- |
@@ -71,13 +116,19 @@ point the plugin at. Roughly:
 
 ### Option A — uv (recommended)
 
+Don't have `uv` yet? It's a one-line install — see the
+[uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
+
 ```bash
 uv tool install "docling-serve[ui]"   # one-time install
 docling-serve run                      # leave this terminal open
 ```
 
 ### Option B — pipx
 
+Don't have `pipx` yet? See the
+[pipx installation guide](https://pipx.pypa.io/stable/installation/).
+
 ```bash
 pipx install "docling-serve[ui]"      # one-time install
 docling-serve run
@@ -99,13 +150,16 @@ docker run --gpus all -p 5001:5001 \
 
 ### Sanity check (any option)
 
+Open <http://localhost:5001/ui> in your browser — the docling-serve
+playground page should load. Or, from a terminal:
+
 ```bash
 curl http://localhost:5001/health    # → {"status":"ok"}
 ```
 
-### ⚠️ First conversion downloads model weights
+### First conversion downloads model weights
 
-The first time you convert a PDF, `docling-serve` downloads the model files
+⚠️ The first time you convert a PDF, `docling-serve` downloads the model files
 from Hugging Face. Expect **2–10 minutes** for the standard pipeline and
 **significantly longer** (multi-GB) for VLM presets. Subsequent conversions
 are fast. The Zotero progress window will appear to hang during the
@@ -123,13 +177,18 @@ docling-serve run
 
 ## Install the plugin
 
-### From a release (when available)
+### From a release (recommended)
+
+1. Download the latest `.xpi` from the
+   [Releases page](https://github.com/max3925vats/zotero-docling/releases/latest).
+   If your browser tries to install the file itself (Firefox does this),
+   right-click the link and choose **Save Link As…** instead.
+2. In Zotero: **Tools → Plugins** → click the gear icon (⚙) →
+   **Install Plugin From File…** → pick the downloaded `.xpi`.
 
-Download the latest `.xpi` from the [Releases page](https://github.com/max3925vats/zotero-docling/releases),
-then in Zotero: **Tools → Plugins → ⚙ → Install Plugin From File…** → pick the
-`.xpi`.
+### From source (for development)
 
-### From source
+Requires [Node.js](https://nodejs.org/) 20 or later:
 
 ```bash
 git clone https://github.com/max3925vats/zotero-docling.git
@@ -140,7 +199,8 @@ npm run build       # outputs .scaffold/build/*.xpi
 
 Then install the `.xpi` via **Tools → Plugins** as above.
 
-> **macOS note**: profile paths that contain spaces (for example
+> **macOS note** (for the `npm start` development workflow): profile paths
+> that contain spaces (for example
 > `~/Library/Application Support/Zotero/...`) must be written literally in
 > `.env` — **no** backslash escapes. See [`.env.example`](.env.example) for
 > the exact format.
@@ -151,9 +211,12 @@ Then install the `.xpi` via **Tools → Plugins** as above.
 
 1. **Settings**: open Zotero → **Settings → zotero-docling**.
 2. Verify the server URL (default `http://localhost:5001`) and click **Test
-   Connection** — it should turn green.
+   Connection** — it should turn green. If it doesn't, make sure the
+   `docling-serve` terminal from the install step is still running.
 3. Right-click a PDF (or parent item) in your library → **Convert with
-   Docling**. Within seconds you'll see a `.md` child appear under the parent.
+   Docling**. A `.md` child appears under the parent — within seconds once
+   the [first-run model download](#first-conversion-downloads-model-weights)
+   is out of the way.
 4. (Optional) tick **Auto-convert new PDF attachments** in Behavior to run
    conversion automatically as you import new PDFs.
 
@@ -183,6 +246,24 @@ hasn't assigned a citation key). When a parent has multiple converted
 PDFs, the second and subsequent get `.1.md`, `.2.md`, … suffixes to
 prevent collisions.
 
+### Removing images from already-converted markdown
+
+Markdown converted without the **Exclude images** option embeds every
+figure as base64 data, which can make a single paper's `.md` tens of
+megabytes. To slim down existing files without re-converting:
+
+1. Select the items (parents, PDF attachments, or `.md` attachments) in
+   your library.
+2. **Right-click → Remove images from markdown**, or open
+   **Tools → Docling: Remove images from markdown…**.
+3. Confirm the dialog. Each `.md` attachment is rewritten in place with
+   every image replaced by a `<!-- image -->` placeholder; a toast reports
+   how many images were removed and how much space was saved.
+
+The image data is gone for good after this — re-convert the PDF if you
+ever need the figures back. Code blocks inside the markdown are left
+untouched.
+
 ---
 
 ## Known limitations

addon/content/preferences.xhtml

@@ -157,6 +157,12 @@
       data-l10n-id="pref-add-frontmatter"
     />
     <description data-l10n-id="pref-frontmatter-help"></description>
+    <checkbox
+      id="zotero-docling-exclude-images"
+      preference="excludeImages"
+      data-l10n-id="pref-exclude-images"
+    />
+    <description data-l10n-id="pref-exclude-images-help"></description>
     <hbox align="center">
       <html:label
         for="zotero-docling-export-folder"

addon/locale/en-US/addon.ftl

@@ -2,4 +2,6 @@ menuitem-convert = Convert with Docling
 menuitem-reconvert = Re-convert with Docling (replace)
 menuitem-export-md-zip = Export markdown to .zip
 menuitem-tools-export-md-zip = Docling: Export markdown to .zip…
+menuitem-remove-images = Remove images from markdown
+menuitem-tools-remove-images = Docling: Remove images from markdown…
 pref-pane-label = zotero-docling

addon/locale/en-US/preferences.ftl

@@ -37,6 +37,9 @@ pref-attach-to-item =
 pref-add-frontmatter =
     .label = Prepend YAML frontmatter with Zotero metadata
 pref-frontmatter-help = Adds title, authors, year, doi, url, zotero_key, citation_key to every .md output as a YAML --- block at the top.
+pref-exclude-images =
+    .label = Exclude images — keep only text and tables
+pref-exclude-images-help = By default every figure is embedded in the .md as base64 data, which can grow a paper's markdown by tens of megabytes. When enabled, each image is replaced with a tiny <!-- image --> placeholder comment instead.
 pref-export-folder = Export folder
 pref-export-folder-help = Absolute path. If set, every converted .md is ALSO written here. Filename uses the item's citation key when available, otherwise the Zotero item key. Leave empty to disable.
 

addon/prefs.js

@@ -16,6 +16,10 @@ pref("pipeline", "standard"); // "standard" | "vlm"
 pref("doOcr", true); // do_ocr
 pref("forceOcr", false); // force_ocr
 pref("tableMode", "accurate"); // table_mode: "accurate" | "fast"
+// image_export_mode: false → "embedded" (server default, base64 images
+// inline); true → "placeholder" (each image becomes a tiny <!-- image -->
+// comment, so the .md keeps text and tables only).
+pref("excludeImages", false);
 
 // Tier 2: enrichments
 pref("doFormulaEnrichment", false); // do_formula_enrichment

src/modules/convert.ts

@@ -185,6 +185,17 @@ export function buildConvertForm(
   form.append("force_ocr", String(getPref("forceOcr") ?? false));
   form.append("table_mode", String(getPref("tableMode") ?? "accurate"));
 
+  // Markdown image handling. "embedded" (the server default) inlines every
+  // figure as a base64 data URI, which can bloat a paper's .md by tens of
+  // megabytes. excludeImages swaps in "placeholder" — each image becomes a
+  // tiny <!-- image --> comment, leaving text and tables only.
+  form.append(
+    "image_export_mode",
+    ((getPref("excludeImages") ?? false) as boolean)
+      ? "placeholder"
+      : "embedded",
+  );
+
   // --- Tier 2: enrichments ---
   form.append(
     "do_formula_enrichment",

src/modules/markdownZipExport.ts

@@ -201,48 +201,34 @@ function promptMissingMd(missing: number, total: number): MissingMdChoice {
 }
 
 // ---------------------------------------------------------------------------
-//  Native file-save dialog (nsIFilePicker)
+//  Native file-save dialog
 // ---------------------------------------------------------------------------
 
 /**
  * Show a Save As dialog and return the chosen absolute path, or null if
  * the user cancelled.
+ *
+ * Goes through Zotero's FilePicker module (via the toolkit helper) rather
+ * than raw nsIFilePicker: Firefox 128+ (Zotero 8) requires a
+ * BrowsingContext as the first argument to nsIFilePicker.init, and
+ * Zotero's wrapper absorbs that difference across supported versions.
  */
 async function promptSavePath(defaultName: string): Promise<string | null> {
-  const Cc = (globalThis as any).Components?.classes;
-  const Ci = (globalThis as any).Components?.interfaces;
-  if (!Cc || !Ci || !Ci.nsIFilePicker) return null;
-  const fp = Cc["@mozilla.org/filepicker;1"].createInstance(Ci.nsIFilePicker);
-  const win =
-    (Zotero as any).getMainWindow?.() ??
-    (Zotero as any).getActiveZoteroPane?.()?.document?.defaultView ??
-    null;
-  fp.init(win, "Save markdown .zip", Ci.nsIFilePicker.modeSave);
-  fp.defaultString = defaultName;
-  fp.appendFilter("Zip archive", "*.zip");
-
-  const result: number = await new Promise((resolve) => {
-    try {
-      fp.open((rv: number) => resolve(rv));
-    } catch {
-      // Some platform builds expose open() as a sync return.
-      try {
-        resolve(fp.show());
-      } catch {
-        resolve(Ci.nsIFilePicker.returnCancel);
-      }
-    }
-  });
-  if (
-    result !== Ci.nsIFilePicker.returnOK &&
-    result !== Ci.nsIFilePicker.returnReplace
-  ) {
+  let picked: string | false;
+  try {
+    picked = await new ztoolkit.FilePicker(
+      "Save markdown .zip",
+      "save",
+      [["Zip archive", "*.zip"]],
+      defaultName,
+    ).open();
+  } catch (e) {
+    log(`save dialog failed: ${(e as Error).message}`);
     return null;
   }
-  const path: string | null = fp.file?.path ?? null;
-  if (!path) return null;
+  if (!picked) return null;
   // Force the .zip extension if the user typed one without it.
-  return /\.zip$/i.test(path) ? path : `${path}.zip`;
+  return /\.zip$/i.test(picked) ? picked : `${picked}.zip`;
 }
 
 // ---------------------------------------------------------------------------

src/modules/menu.ts

@@ -38,12 +38,15 @@ import { notifyOnBatchComplete } from "../utils/notification";
 import { ConcurrencyLimiter } from "../utils/concurrencyLimiter";
 import { truncateMiddle, formatDuration } from "../utils/format";
 import { onExportMarkdownZipClick } from "./markdownZipExport";
+import { onRemoveImagesClick, resolveMdTargets } from "./removeImages";
 
 const LOG = "[Docling/menu]";
 const MENU_CONVERT_ID = "zotero-docling-convert";
 const MENU_RECONVERT_ID = "zotero-docling-reconvert";
 const MENU_EXPORT_MD_ZIP_ID = "zotero-docling-export-md-zip";
 const TOOLS_EXPORT_MD_ZIP_ID = "zotero-docling-tools-export-md-zip";
+const MENU_REMOVE_IMAGES_ID = "zotero-docling-remove-images";
+const TOOLS_REMOVE_IMAGES_ID = "zotero-docling-tools-remove-images";
 
 // Re-exports — used by other modules (markdownZipExport.ts) that need to
 // resolve a Zotero selection in the same way the right-click handlers do.
@@ -412,6 +415,8 @@ const ALL_MENU_IDS = [
   MENU_RECONVERT_ID,
   MENU_EXPORT_MD_ZIP_ID,
   TOOLS_EXPORT_MD_ZIP_ID,
+  MENU_REMOVE_IMAGES_ID,
+  TOOLS_REMOVE_IMAGES_ID,
 ];
 
 export function registerMenu(): void {
@@ -472,6 +477,30 @@ export function registerMenu(): void {
     },
   });
 
+  // Item right-click: Remove images from markdown — only when the selection
+  // resolves to ≥1 markdown attachment to rewrite. The handler re-confirms
+  // before touching any file.
+  ztoolkit.Menu.register("item", {
+    tag: "menuitem",
+    id: MENU_REMOVE_IMAGES_ID,
+    label: getString("menuitem-remove-images"),
+    commandListener: () => {
+      void onRemoveImagesClick("selection");
+    },
+    getVisibility: () => resolveMdTargets(getSelectedItems()).length > 0,
+  });
+
+  // Tools → Docling: Remove images from markdown…. Same handler as the
+  // right-click; toasts a hint when nothing usable is selected.
+  ztoolkit.Menu.register("menuTools", {
+    tag: "menuitem",
+    id: TOOLS_REMOVE_IMAGES_ID,
+    label: getString("menuitem-tools-remove-images"),
+    commandListener: () => {
+      void onRemoveImagesClick("tools");
+    },
+  });
+
   log(`registerMenu: registered ${ALL_MENU_IDS.join(", ")}`);
 }
 

src/modules/preferenceScript.ts

@@ -26,6 +26,7 @@ const ALL_PREF_KEYS: ReadonlyArray<string> = [
   "doOcr",
   "forceOcr",
   "tableMode",
+  "excludeImages",
   "doFormulaEnrichment",
   "doCodeEnrichment",
   "doChartExtraction",