Zotero Plugin Toolkit

https://github.com/windingwind/zotero-plugin-toolkit
Admin
Zotero Plugin Toolkit is an npm package that provides a collection of helpful APIs for Zotero plugin...
Tokens:71,245
Snippets:596
Trust Score:8.1
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install without version constraints

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/pluginBridge.md

Example URI to install a plugin without version constraints. Only the action and url parameters are required.

```text
# Without version constraints
zotero://plugin/?action=install&url=https%3A%2F%2Fexample.com%2Fplugin.xpi
```

--------------------------------

### Install with minVersion

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/pluginBridge.md

Example URI to install a plugin with a minimum Zotero version requirement. The minVersion parameter is compared via Services.vc.compare; if Zotero.version < minVersion, install is aborted.

```text
# Install with a minimum Zotero version requirement
zotero://plugin/?action=install&url=https%3A%2F%2Fgithub.com%2FMuiseDestiny%2Fzotero-style%2Freleases%2Fdownload%2F3.0.5%2Fzotero-style.xpi&minVersion=6.999
```

--------------------------------

### GuideHelper usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Example usage of `GuideHelper` with two steps: the first targets `#plugin-menu` with a title, description, position `after_start`, and a `next` button; the second targets `#settings-button` via a function and shows `prev` and `close` buttons. The guide is shown on the main Zotero window document.

```ts
const guide = new GuideHelper()
  .addStep({
    element: "#plugin-menu",
    title: "Welcome",
    description: "This is your plugin menu.",
    position: "after_start",
    showButtons: ["next"],
  })
  .addStep({
    element: () => document.querySelector("#settings-button"),
    title: "Settings",
    showButtons: ["prev", "close"],
  });

await guide.show(Zotero.getMainWindow().document);
```

--------------------------------

### GuideHelper hooks example with highlight()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Shows how to create a GuideHelper, add a step with hooks (onRender, onExit, onMask), and start the highlight. The onMask hook can focus the mask on a specific part via document.querySelector. The example calls guide.highlight() with the first step.

```typescript
// Hooks example
const guide = new GuideHelper();
guide.addStep({
  element: "#sync-button",
  onRender: ({ config, state }) => {
    // state.controller.moveTo(0) to re-enter the same step, etc.
  },
  onExit: async ({ state }) => {
    Zotero.debug(`Left step ${state.step + 1}`);
  },
  onMask: ({ mask }) => mask(document.querySelector("#specific-part")),
});
await guide.highlight(Zotero.getMainWindow().document, guide._steps[0] as any);
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/docs/contributing.md

Clones the repository, navigates into the folder, and installs dependencies. Requires Node.js and npm to be installed beforehand.

```bash
git clone https://github.com/windingwind/zotero-plugin-toolkit
cd zotero-plugin-toolkit
npm install
```

--------------------------------

### Install zotero-plugin-toolkit with npm, yarn, or pnpm

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/docs/quick-start.md

Install the toolkit using your preferred package manager. The commands are equivalent alternatives for npm, yarn, and pnpm.

```bash
npm install --save zotero-plugin-toolkit
```

```bash
yarn add zotero-plugin-toolkit
```

```bash
pnpm add zotero-plugin-toolkit
```

--------------------------------

### GuideHelper show

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Creates an internal `Guide` bound to `doc.ownerGlobal`, awaits `guide.show(this._steps)`, waits for the `guide-finished` event, and returns the internal `Guide` instance (typed as `any`). Throws `Error("Document is required.")` when `doc` or `doc.ownerGlobal` is falsy.

```ts
async show(doc: Document)
```

--------------------------------

### UITool Usage Example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/configuration.md

Example of creating a UITool instance with UI-specific options. Extends BasicOptions with element recording and logging settings.

```typescript
const ui = new UITool({
  api: { pluginID: "x@y" },
  ui: { enableElementRecord: true, enableElementJSONLog: false, enableElementDOMLog: true },
});
```

--------------------------------

### PromptManager usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Shows how to register a command with the PromptManager and clean up on plugin exit. The example registers a command named 'Hello' that logs 'world' to the Zotero debug console.

```typescript
// Show/hide with Shift+P anywhere in Zotero.
const promptManager = new PromptManager();
promptManager.register([{ name: "Hello", callback: () => Zotero.debug("world") }]);
// plugin exit:
promptManager.unregisterAll();
```

--------------------------------

### start()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/message.md

Creates the message listener (if needed) and attaches it to the target, setting running to true.

```APIDOC
## start()

### Description
Creates the message listener (if needed) and attaches it to `target.addEventListener("message", ...)`, sets `running = true`. Logs `Listener already started for <name>` if already running (and returns).

### Method
start

### Parameters
None.

### Returns
void
```

--------------------------------

### makeHelperTool usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/basic.md

Example usage of makeHelperTool to create a Clipboard helper bound to the current ZoteroToolkit instance.

```ts
Clipboard = makeHelperTool(ClipboardHelper, this);
```

--------------------------------

### start() method

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/message.md

Creates the message listener and attaches it to target.addEventListener("message", ...). Sets running = true. Logs 'Listener already started for <name>' if already running.

```typescript
start()
```

--------------------------------

### PromptManager.register usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Example of registering commands with the PromptManager. Shows a command with a when condition and a submenu command.

```typescript
const prompt = new PromptManager();
prompt.register([
  {
    name: "Split Horizontally",
    label: "Zotero",
    when: () => !!getReader(),
    callback: (p) => getReader().menuCmd("splitHorizontally"),
  },
  {
    name: "Submenu demo",
    callback: [
      { name: "Sub 1", callback: () => Zotero.debug("1") },
      { name: "Sub 2", callback: () => Zotero.debug("2") },
    ],
  },
]);
```

--------------------------------

### Create and open a dialog with data binding

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/dialog.md

Example of creating a dialog with `DialogHelper`, adding cells and a button, setting initial data, and opening it. The `open` method returns `this`, and the window is available as `this.window`. The example waits for the load lock and checks the bound data after user interaction.

```ts
const dialog = new DialogHelper(1, 2);

dialog
  .addCell(0, 0, {
    tag: "label",
    properties: { innerText: "Name:" },
  })
  .addCell(0, 1, {
    tag: "input",
    id: "name-input",
    attributes: { "data-bind": "name" },
  })
  .addButton("OK", undefined, {
    callback: () => Zotero.debug("OK clicked"),
  });

dialog.setDialogData({ name: "Ada" }).open("My Settings");
await dialog.dialogData.loadLock.promise; // wait for the window body
if (dialog.dialogData.name) {
  // name changed by the user, data binding wrote it back
}
```

--------------------------------

### Create and show progress window

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Example of creating a progress window with a success line and showing it.

```ts
const popup = new ProgressWindowHelper("My Addon")
  .createLine({ type: "success", text: "Finished", progress: 100 })
  .show();
```

--------------------------------

### Usage example with import and Prompt registration

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/ztoolkit.md

Shows importing ZoteroToolkit from 'zotero-plugin-toolkit/ztoolkit', instantiating it, logging the version, and registering a Prompt command. Note that constructing outside Zotero throws on missing globals.

```typescript
import ZoteroToolkit from "zotero-plugin-toolkit/ztoolkit";

const ztoolkit = new ZoteroToolkit();

ztoolkit.log("Toolkit version", ztoolkit._version);
ztoolkit.Prompt.register([
  {
    name: "Do something",
    callback: () => ztoolkit.log("hi"),
  },
]);
```

--------------------------------

### SettingsDialogHelper complete example with error path

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/settingsDialog.md

Complete example of using SettingsDialogHelper to create a settings dialog with various input types (text, checkbox, select), a static row, and an auto-save button. The error path shows that calling saveAllSettings without handlers logs a warning and returns without throwing.

```ts
import { SettingsDialogHelper } from "zotero-plugin-toolkit";

function openSettings() {
  const dlg = new SettingsDialogHelper().setSettingHandlers(
    (key) => Zotero.Prefs.get(`extensions.demo.${key}`, true),
    (key, value) => Zotero.Prefs.set(`extensions.demo.${key}`, value, true),
  );

  dlg.addSetting("Name", "name", {
    tag: "input",
    attributes: { type: "text", placeholder: "Your name" },
  });
  dlg.addSetting("Notifications", "notify", {
    tag: "input",
    attributes: { type: "checkbox" },
  }, { valueType: "boolean" });
  dlg.addSetting("Interval", "interval", {
    tag: "select",
    children: [
      { tag: "option", properties: { value: "60" }, properties: undefined },
    ],
  }, { valueType: "number" });
  dlg.addStaticRow("About", {
    tag: "p",
    properties: { textContent: "Demo plugin v1.0" },
  });
  dlg.addAutoSaveButton("Save", "save", { validate: () => true });

  dlg.open("Demo Settings");
}

// Error path: missing handlers
const dlg = new SettingsDialogHelper();
dlg.addSetting("k", "a", { tag: "input" });
try {
  dlg.saveAllSettings(); // console.warn, no throw (guard returns)
} catch (e) { /* not reached */ }
```

--------------------------------

### BasicTool Usage Example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/configuration.md

Example of creating a BasicTool instance with custom options. The same object shape is accepted by updateOptions and manager constructors.

```typescript
const basic = new BasicTool({
  log: { _type: "toolkitlog", disableConsole: false, disableZLog: false, prefix: "[MyPlugin] " },
  api: { pluginID: "myplugin@example.com" },
  debug: { disableDebugBridgePassword: false, password: "" },
  listeners: {
    callbacks: {
      onMainWindowLoad: new Set(),
      onMainWindowUnload: new Set(),
      onPluginUnload: new Set(),
    },
  },
});
```

--------------------------------

### Import individual modules (BasicTool, ClipboardHelper, UITool)

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/docs/quick-start.md

Import only the modules you need to reduce plugin size. This example imports BasicTool, ClipboardHelper, and UITool.

```ts
import { BasicTool, ClipboardHelper, UITool } from "zotero-plugin-toolkit";

const basic = new BasicTool();
const ui = new UITool();
```

--------------------------------

### zotero://plugin

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/endpoints.md

This custom URI-scheme handler is triggered by opening `zotero://plugin` links. It initiates a plugin installation from a downloaded XPI. Deprecated.

```APIDOC
## [Custom URI Scheme] [zotero://plugin]

### Description
This endpoint is a custom URI-scheme handler triggered by opening `zotero://plugin` links inside Zotero. It initiates a plugin installation from a downloaded XPI. Deprecated.

### Method
Custom URI Scheme (handled via `doAction(uri)`)

### Endpoint
`zotero://plugin`

### Request Query Parameters
- **action** (string, "install") - Required - Only `install` is implemented; other values are ignored.
- **url** (string) - Required - Download URL of the plugin XPI.
- **minVersion** (string) - Optional - Minimum allowed Zotero version (`Services.vc.compare`).
- **maxVersion** (string) - Optional - Maximum allowed Zotero version.

### Request Example
`zotero://plugin/?action=install&url=<uri-encoded xpi URL>[&minVersion=<v>][&maxVersion=<v>]`

### Response
None (empty content). Feedback is visual: on success or failure, a `Zotero.ProgressWindow` titled "Plugin Toolkit" shows "Plugin installed successfully." (tick icon) or the error message (cross icon), auto-closing after 5 seconds. Errors also go through `Zotero.logError`.

### Failure Cases
- No `action=install` or no `url` - No-op.
- `Zotero.version < minVersion` (or `> maxVersion`) - `Error("Plugin is not compatible with Zotero version ...")` → logged + hint.
- Addon state ≠ `STATE_AVAILABLE` - `Error(\`Plugin ${url} is not available.\`)` → logged + hint.
- Any other exception during install - Caught, `Zotero.logError(e)`, hint shown.

### Authentication
None — anyone able to open the URI can trigger an addon install (subject to Zotero's own addon-install confirmations).
```

--------------------------------

### waitUntil usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/wait.md

Example usage of waitUntil: polls until a reader tab exists, then logs 'reader ready'. Uses 50 ms interval and 3000 ms timeout.

```ts
waitUntil(
  () => Zotero.Reader.getByTabID(tabID) !== undefined,
  () => Zotero.debug("reader ready"),
  50,
  3000,
);
```

--------------------------------

### ProgressWindowHelper

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Complete API reference for the ProgressWindowHelper class, including constructor, methods, and usage examples.

```APIDOC
## ProgressWindowHelper

### Description
Displays non-blocking Zotero progress windows with icon/text/progress lines.

### Constructor

```ts
constructor(
  header: string,
  options: {
    window?: Window;
    closeOnClick?: boolean;
    closeTime?: number;
    closeOtherProgressWindows?: boolean;
  } = {
    closeOnClick: true,
    closeTime: 5000,
  },
)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| header | `string` | — | Window headline text. |
| options.window | `Window` | — | Passed through to `Zotero.ProgressWindow`'s constructor. |
| options.closeOnClick | `boolean` | `true` | Close when the user clicks the popup. |
| options.closeTime | `number` | `5000` | Auto-close delay in ms. |
| options.closeOtherProgressWindows | `boolean` | — | When true, calls `Zotero.ProgressWindowSet.closeAll()` first. |

Creates `Zotero.ProgressWindow`, sets the headline, and stores an internal `closeTime` default of 5000.

### Static custom icons

```ts
const icons: { [key: string | number]: string } = {
  success: "chrome://zotero/skin/tick.png",
  fail: "chrome://zotero/skin/cross.png",
};
```

### `static setIconURI`

```ts
static setIconURI(key: string, uri: string)
```

Registers/replaces a named icon used by the `type` option of `createLine`/`changeLine`.

```ts
ProgressWindowHelper.setIconURI("warn", "chrome://myplugin/skin/warn.png");
```

### `createLine`

```ts
createLine(options: {
  type?: string;
  icon?: string;
  text?: string;
  progress?: number;
  idx?: number;
})
```

Appends a new `ItemProgress` line. `icon` is resolved as `getIcon(options.type, options.icon)` (named icon wins over the raw `icon` URI). If `progress` is a number, `line.setProgress(progress)` is called. Returns `this`.

### `changeLine`

```ts
changeLine(options: {
  type?: string;
  icon?: string;
  text?: string;
  progress?: number;
  idx?: number;
})
```

Updates an existing line. `idx` is clamped to `[0, lines.length)` and defaults to `0`. When an icon resolves, `setItemTypeAndIcon(icon)` is applied; `text` and `progress` are applied when given. Returns `this` (no-op when no lines exist).

### `show`

```ts
show(closeTime: number | undefined = undefined)
```

Shows the window; when `closeTime` is given it replaces the internal value, and when it is truthy and `> 0`, `win.startCloseTimer(closeTime)` runs. Asynchronously refreshes the icons once the first line exists. Returns `this`.

### `changeHeadline`

```ts
changeHeadline(text: string, icon?: string, postText?: string)
```

Delegates to `win.changeHeadline(...)`. Returns `this`.

### `addLines`

```ts
addLines(
  labels: string | { [key: string | number | symbol]: string },
  icons: string | { [key: string | number | symbol]: string },
)
```

Delegates to `win.addLines(labels, icons)`. Returns `this`.

### `addDescription`

```ts
addDescription(text: string)
```

Delegates to `win.addDescription(text)`. Returns `this`.

### `startCloseTimer`

```ts
startCloseTimer(ms: number, requireMouseOver?: boolean)
```

Delegates to `win.startCloseTimer(...)`. Returns `this`.

### `close`

```ts
close()
```

Closes the window. Returns `this`.

### Examples

```ts
const popup = new ProgressWindowHelper("My Addon")
  .createLine({ type: "success", text: "Finished", progress: 100 })
  .show();
```

Updating a line later:

```ts
const tool = new ProgressWindowHelper("Import")
  .createLine({ text: "Loading", progress: 50 })
  .show(8000);

setTimeout(() => {
  tool.changeLine({ text: "Finished", progress: 100 });
  tool.close();
}, 3000);
```

### Notes

- `ProgressWindowHelper` deliberately does **not** extend `BasicTool`; its `win` field exposes the raw `Zotero.ProgressWindow` instance.
- `updateIcons()` waits for each line's `_image` to load, then applies the `data-set.itemType` background (guarded; failures are ignored), mimicking Zotero's own progress-window icon handling.
- `changeLine`'s item-type/icon call uses `@ts-expect-error` because `setItemTypeAndIcon` is not yet in `zotero-types`.
```

--------------------------------

### call(), get(), set(), eval()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/message.md

Convenience wrappers over the built-in handlers.

```APIDOC
## call(), get(), set(), eval()

### Description
Convenience wrappers over the built-in handlers. `get`/`set` support dotted paths (`"self.firstName"`); only primitive/serializable values are supported. `get` throws `TypeError("Property <path> not found")` on the remote side when a path segment is undefined.

### Methods
- **call(func: string, args: any[])** - async - Executes `exec("_call", [func, args])`.
- **get(key: string)** - async - Executes `exec("_get", [key])`.
- **set(key: string, value: any)** - async - Executes `exec("_set", [key, value])`.
- **eval(code: string)** - async - Executes `exec("_eval", [code])`.

### Parameters
- **func** (string) - Required - Function name to call.
- **args** (any[]) - Required - Arguments to pass.
- **key** (string) - Required - Property key (dotted path supported).
- **value** (any) - Required - Value to set.
- **code** (string) - Required - Code to evaluate.

### Returns
Promise<any>
```

--------------------------------

### GuideHelper addSteps

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Appends multiple steps to the guide and returns `this` for chaining.

```ts
addSteps(steps: GuideStep[])
```

--------------------------------

### Example: Using the singleton to share state

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/toolkitGlobal.md

Managers use the singleton to share state across instantiations. Checks if the prompt module is not ready, then sets _ready to true and creates a new Prompt instance.

```typescript
// Managers use the singleton to share state across instantiations
const prompt = ToolkitGlobal.getInstance();
if (prompt && !prompt.prompt._ready) {
  prompt.prompt._ready = true;
  prompt.prompt.instance = new Prompt();
}
```

--------------------------------

### UITool constructor

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/tools/ui.md

Initializes a new UITool instance with optional base options. If the UI options are not set, it installs default UI options for element recording and logging.

```APIDOC
## UITool constructor

### Description
Initializes a new UITool instance with optional base options. If the UI options are not set, it installs default UI options for element recording and logging.

### Method
constructor

### Signature
constructor(base?: BasicTool | BasicOptions)

### Parameters
- **base** (BasicTool | BasicOptions) - Optional - Options source. Default is undefined.

### Behavior
When _basicOptions.ui is unset, installs the default UI options: { enableElementRecord: true, enableElementJSONLog: false, enableElementDOMLog: true }.
```

--------------------------------

### GuideHelper addStep

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Appends a single step to the guide and returns `this` for chaining.

```ts
addStep(step: GuideStep)
```

--------------------------------

### Basic MarkDown file open example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/filePicker.md

Opens a MarkDown file using FilePickerHelper with a custom filter. If the user cancels, path is false and the file is not read.

```typescript
// Basic: open a MarkDown file
const path = await new FilePickerHelper(
  `${Zotero.getString("fileInterface.import")} MarkDown Document`,
  "open",
  [["MarkDown File(*.md)", "*.md"]],
).open();
if (path !== false) {
  await Zotero.File.getContentsAsync(path);
}
```

--------------------------------

### initializeModules function

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/toolkitGlobal.md

Internal function that logs initialization, sets the prompt module with _ready false and instance undefined, and calls DebugBridge.setModule and PluginBridge.setModule to install or update modules.

```typescript
function initializeModules(instance: ToolkitGlobal) {
  new BasicTool().log("Initializing ToolkitGlobal modules");
  setModule(instance, "prompt", { _ready: false, instance: undefined });
  DebugBridge.setModule(instance);
  PluginBridge.setModule(instance);
}
```

--------------------------------

### Combined addText and addImage usage

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/clipboard.md

Example of chaining addText and addImage to copy multiple flavors in one shot, then calling copy().

```ts
// Copy text + rich text + image in one shot, then copy to clipboard
new ClipboardHelper()
  .addText("plain", "text/unicode")
  .addText("<h1>rich text</h1>", "text/html")
  .addImage("data:image/png;base64,...")
  .copy();
```

--------------------------------

### DebugBridge URI examples

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/debugBridge.md

URI templates for the DebugBridge protocol handler. Use ?run= for URI-encoded JavaScript source and ?file= for a file:/// path; the app parameter identifies the requesting external app. The password parameter is required unless bypassed.

```text
# Run script directly (URI-encoded source)
zotero://ztoolkit-debug/?run=Zotero.getMainWindow().alert(%22HelloWorld!%22)&app=developer

# Load a script from a file
zotero://ztoolkit-debug/?file=file%3A%2F%2F%2FC%3A%2FUsers%2Fw_xia%2FDesktop%2Frun.js&app=developer
```

--------------------------------

### Install zotero-types dev dependency

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/docs/quick-start.md

Install zotero-types as a dev dependency to get full TypeScript support for Zotero APIs.

```bash
npm install --save-dev zotero-types
```

--------------------------------

### setSettingHandlers usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/settingsDialog.md

Example usage of setSettingHandlers with Zotero.Prefs get/set callbacks. The get callback reads a preference with a default of true, and the set callback writes the value with a global flag.

```ts
const dialog = new SettingsDialogHelper();
dialog.setSettingHandlers(
  (key) => Zotero.Prefs.get(`extensions.myplugin.${key}`, true),
  (key, value) => Zotero.Prefs.set(`extensions.myplugin.${key}`, value, true),
);
```

--------------------------------

### getSelectedText usage

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/tools/reader.md

Usage example for getSelectedText: creates a ReaderTool, gets the reader, retrieves the selected text, and if non-empty, passes it to Zotero.File.getContentsAsync.

```ts
const tool = new ReaderTool();
const reader = await tool.getReader();
if (reader) {
  const text = tool.getSelectedText(reader);
  if (text) {
    await tool.getGlobal("Zotero").File.getContentsAsync(text);
  }
}
```

--------------------------------

### GuideHelper highlight

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/guide.md

Same as `show` but renders a single step. Throws the same `Error("Document is required.")` on a missing document.

```ts
async highlight(doc: Document, step: GuideStep)
```

--------------------------------

### Prompt.initializeUI()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Initializes the UI by appending styles, building the DOM, binding input events, and registering the Shift+P shortcut.

```APIDOC
## Method: initializeUI

### Description
Initializes the UI by appending the stylesheet, building the DOM, binding input events, and registering the Shift+P document-level shortcut. Safe to call multiple times; re-appends the same nodes.

### Method
initializeUI

### Endpoint
N/A

### Parameters
None

### Request Example
```ts
prompt.initializeUI();
```

### Response
#### Success Response
No return value.

#### Response Example
```ts
prompt.initializeUI();
```
```

--------------------------------

### constructor()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/settingsDialog.md

Initializes the SettingsDialogHelper, setting up the CSS-grid layout with a settings grid and bottom button bar.

```APIDOC
## constructor()

### Description
Initializes the SettingsDialogHelper, setting up the CSS-grid layout with a settings grid and bottom button bar.

### Method
constructor

### Signature
```ts
constructor()
```

### Parameters
None

### Returns
- **SettingsDialogHelper** - The new instance.

### Example
```ts
const dialog = new SettingsDialogHelper();
```
```

--------------------------------

### new Prompt()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Creates a new Prompt instance, initializing its own BasicTool and UITool instances and calling initializeUI().

```APIDOC
## Constructor: Prompt

### Description
Creates a new Prompt instance, initializing its own BasicTool and UITool instances and calling initializeUI().

### Method
Constructor

### Endpoint
N/A

### Parameters
None

### Request Example
```ts
const prompt = new Prompt();
```

### Response
#### Success Response
- **prompt** (Prompt) - The created Prompt instance.

#### Response Example
```ts
const prompt = new Prompt();
```
```

--------------------------------

### waitForReader usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/wait.md

Example usage of waitForReader: waits for the reader to be fully initialized before attaching a keydown listener to its iframe window.

```ts
await wait.waitForReader(reader);
reader._iframeWindow.addEventListener("keydown", handler);
```

--------------------------------

### addText usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/clipboard.md

Example of adding plain and rich text flavors to a ClipboardHelper instance. The addText method returns this for chaining.

```ts
const clip = new ClipboardHelper();
clip.addText("plain text", "text/unicode").addText("<h1>rich</h1>", "text/html");
```

--------------------------------

### addImage usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/clipboard.md

Example of adding an image via a base64 data URI and copying to the clipboard. The addImage method returns this for chaining.

```ts
new ClipboardHelper()
  .addImage("data:image/png;base64,iVBORw0KGgo...")
  .copy();
```

--------------------------------

### waitUntilAsync usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/wait.md

Example usage of waitUntilAsync: awaits until a DOM element with id 'root' exists, then logs. On timeout, catches the Error('timeout') and logs a failure message.

```ts
try {
  await wait.waitUntilAsync(() => !!window.document.getElementById("root"));
  Zotero.debug("root exists");
} catch (e) {
  // Error("timeout")
  Zotero.debug("root never appeared", e);
}
```

--------------------------------

### Prompt.initializeUI

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Initializes the UI by appending styles, building the DOM, binding input events, and registering the Shift+P shortcut. Calling again re-appends the same nodes.

```ts
public initializeUI()
```

--------------------------------

### addAutoSaveButton usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/settingsDialog.md

Example usage of addAutoSaveButton with a validate function that returns true if the 'name' field is present, otherwise a string error message, and a callback that logs 'saved!' via Zotero.debug.

```ts
dialog.addAutoSaveButton("Save", "save-btn", {
  validate: (data) => data["name"] ? true : "Name is required",
  callback: () => Zotero.debug("saved!"),
});
```

--------------------------------

### call, get, set, eval wrappers

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/message.md

Convenience wrappers over built-in handlers. get/set support dotted paths; only primitive/serializable values are supported. get throws TypeError on remote side when a path segment is undefined.

```typescript
async call(func: string, args: any[])  // exec("_call", [func, args])
async get(key: string)                 // exec("_get", [key])
async set(key: string, value: any)     // exec("_set", [key, value])
async eval(code: string)               // exec("_eval", [code])
```

--------------------------------

### loadAllSettings()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/settingsDialog.md

Pushes handler values into the live DOM controls. No-op without handlers or window.

```APIDOC
## loadAllSettings()

### Description
Pushes handler values into the live DOM controls. No-op without handlers or window.

### Method
loadAllSettings

### Signature
```ts
loadAllSettings()
```

### Parameters
None

### Returns
- **void** - No return value.

### Example
```ts
dialog.loadAllSettings();
```
```

--------------------------------

### Basic usage: log and access globals with ZoteroToolkit

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/docs/quick-start.md

Basic usage example: create a ZoteroToolkit instance, log with context-aware output, and access global objects like Zotero and ZoteroPane. getGlobal provides proper type hints for Zotero, window, document, and other globals.

```ts
const ztoolkit = new ZoteroToolkit();

// Logging with context-aware output
ztoolkit.log("This is Zotero:", ztoolkit.getGlobal("Zotero"));

// Accessing a global object
const ZoteroPane = ztoolkit.getGlobal("ZoteroPane");
```

--------------------------------

### constructor(base?: BasicTool | BasicOptions)

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/prompt.md

Constructs a new PromptManager instance. Throws an error if the global prompt is not initialized. Lazily creates and stores the shared Prompt singleton.

```APIDOC
## constructor(base?: BasicTool | BasicOptions)

### Description
Constructs a new PromptManager instance. Throws an error if the global prompt is not initialized. Lazily creates and stores the shared Prompt singleton.

### Method
constructor

### Parameters
- **base** (BasicTool | BasicOptions) - Optional - The base tool or options for initialization.

### Throws
- **Error** - "Prompt is not initialized." when `ToolkitGlobal.getInstance()?.prompt` is missing.

### Example
```ts
const prompt = new PromptManager();
```
```

--------------------------------

### ZoteroToolkit Constructor

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/ztoolkit.md

Creates all sub-tools eagerly. Requires a Zotero runtime; constructing outside Zotero will throw on missing globals.

```APIDOC
## ZoteroToolkit Constructor

### Description
Creates all sub-tools eagerly. Requires a Zotero runtime; constructing outside Zotero will throw on missing globals.

### Method
Constructor

### Endpoint
`new ZoteroToolkit()`

### Parameters
None

### Request Example
```ts
const ztoolkit = new ZoteroToolkit();
```

### Response
#### Success Response
- **ztoolkit** (ZoteroToolkit) - The initialized toolkit instance with all sub-tools.

#### Response Example
```ts
ZoteroToolkit {
  UI: UITool,
  Reader: ReaderTool,
  ExtraField: ExtraFieldTool,
  FieldHooks: FieldHookManager,
  Keyboard: KeyboardManager,
  Prompt: PromptManager,
  Clipboard: ClipboardHelper,
  FilePicker: FilePickerHelper,
  Patch: PatchHelper,
  ProgressWindow: ProgressWindowHelper,
  VirtualizedTable: VirtualizedTableHelper,
  Dialog: DialogHelper,
  LargePrefObject: LargePrefHelper,
  Guide: GuideHelper
}
```
```

--------------------------------

### FilePickerHelper

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/filePicker.md

Documentation for the FilePickerHelper class, including constructor parameters and the open() method.

```APIDOC
## FilePickerHelper

### Description
Wraps Zotero's native file-picker module in a typed, awaitable API. Extends `BasicTool`.

### Constructor

```ts
constructor(
  title: string,
  mode: MODE,
  filters?: [string, string][],
  suggestion?: string,
  window?: Window,
  filterMask?: "all" | "html" | "text" | "images" | "xml" | "apps" | "urls" | "audio" | "video",
  directory?: string,
)
```

#### Parameters
- **title** (string) - Required - Window title.
- **mode** ("open" | "save" | "folder" | "multiple") - Required - Picker mode: open file, save file, choose folder, open multiple files.
- **filters** ([string, string][]) - Optional - Extensions, e.g. `[["MarkDown File(*.md)", "*.md"]]` (hint, filter).
- **suggestion** (string) - Optional - Default file/folder name (sets `fp.defaultString`).
- **window** (Window) - Optional - Parent window; defaults to the main window.
- **filterMask** ("all" | "html" | "text" | "images" | "xml" | "apps" | "urls" | "audio" | "video") - Optional - Built-in filter constants (e.g. `"images"` → `fp.filterImages`).
- **directory** (string) - Optional - Directory the picker opens in (`fp.displayDirectory`).

### open

```ts
async open(): Promise<(MODE extends "multiple" ? string[] : string) | false>
```

#### Description
Shows the picker and resolves when the user makes a choice.

#### Returns
- **Success** (string) - Selected path when `MODE` is "open", "save", or "folder".
- **Success** (string[]) - All selected files when `MODE` is "multiple".
- **Cancel** (false) - Returned when the user cancels (any mode).

#### Example
```ts
// Basic: open a MarkDown file
const path = await new FilePickerHelper(
  `${Zotero.getString("fileInterface.import")} MarkDown Document`,
  "open",
  [["MarkDown File(*.md)", "*.md"]],
).open();
if (path !== false) {
  await Zotero.File.getContentsAsync(path);
}
```

Multiple selection with filter masks and error handling:

```ts
const helper = new FilePickerHelper<string[]>(
  "Select images",
  "multiple",
  undefined, // no custom filters
  undefined, // no suggestion
  undefined, // parent = main window
  "images",  // built-in image filter
  Zotero.getHomeDirectory(),
);

try {
  const files = await helper.open();
  if (files === false) {
    Zotero.debug("User cancelled");
    return;
  }
  files.forEach((f) => Zotero.debug(`Selected: ${f}`));
} catch (e) {
  // Native picker failures propagate as-is from fp.show()
  Zotero.debug(e);
}
```

### Notes
- `open()` never throws on user cancel — it returns `false`.
- The result check is `case fp.returnOK: case fp.returnReplace:`; everything else (i.e. `returnCancel`) becomes `false`.
- `MODE` is a string generic, so instantiate as `FilePickerHelper<"multiple">` to get `string[]` typing without `as` casts.
```

--------------------------------

### Getting Zotero globals

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/basic.md

Retrieves the Zotero and ZoteroPane global objects using getGlobal.

```typescript
const Zotero = ztoolkit.getGlobal("Zotero");
const pane = ztoolkit.getGlobal("ZoteroPane");
```

--------------------------------

### setExtraField with error handling

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/tools/extraField.md

Example of using setExtraField with try/catch to handle failures from item.setField or item.saveTx.

```ts
// Round-trip with error handling
try {
  await tool.setExtraField(item, "url", "https://example.org");
} catch (e) {
  // item.setField / item.saveTx failures propagate
  Zotero.debug(e);
}
```

--------------------------------

### ProgressWindowHelper constructor

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Constructor signature for ProgressWindowHelper. Accepts a header string and optional options object with defaults closeOnClick: true and closeTime: 5000. Creates a Zotero.ProgressWindow and sets the headline.

```ts
constructor(
  header: string,
  options: {
    window?: Window;
    closeOnClick?: boolean;
    closeTime?: number;
    closeOtherProgressWindows?: boolean;
  } = {
    closeOnClick: true,
    closeTime: 5000,
  },
)
```

--------------------------------

### constructor()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/clipboard.md

Creates an nsITransferable instance and fetches the nsIClipboard service. The transferable is initialized empty; call add* methods to populate it, then copy().

```APIDOC
## constructor()

### Description
Creates an nsITransferable instance and fetches the nsIClipboard service via Components.classes. The transferable is initialized empty; call the add* methods to populate it, then copy().

### Method
constructor

### Parameters
None

### Returns
- **ClipboardHelper** - The constructed instance.

### Example
```ts
const clip = new ClipboardHelper();
```
```

--------------------------------

### Register custom icon

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Example call to register a custom icon named 'warn' with a URI.

```ts
ProgressWindowHelper.setIconURI("warn", "chrome://myplugin/skin/warn.png");
```

--------------------------------

### Enable/disable usage example

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/patch.md

Shows disabling the patch to temporarily route calls to the original, then re-enabling it.

```typescript
patch.disable(); // temporarily route calls to the original
// ... do unpatched work ...
patch.enable();
```

--------------------------------

### startCloseTimer signature

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Method signature for starting the close timer. Delegates to win.startCloseTimer(...). Returns this.

```ts
startCloseTimer(ms: number, requireMouseOver?: boolean)
```

--------------------------------

### show signature

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/progressWindow.md

Method signature for showing the window. When closeTime is given it replaces the internal value, and when truthy and > 0, win.startCloseTimer(closeTime) runs. Asynchronously refreshes icons once the first line exists. Returns this.

```ts
show(closeTime: number | undefined = undefined)
```

--------------------------------

### open

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/helpers/dialog.md

Opens the dialog via `openDialog(...)`. Configures window features, applies Zotero custom widgets and data binding, and returns the dialog instance.

```APIDOC
## open

### Description
Opens the dialog via `openDialog(...)`. Configures window features, applies Zotero custom widgets and data binding, and returns the dialog instance.

### Method
open

### Signature
```ts
open(
  title: string,
  windowFeatures: {
    width?: number;
    height?: number;
    left?: number;
    top?: number;
    centerscreen?: boolean;
    resizable?: boolean;
    fitContent?: boolean;
    noDialogMode?: boolean;
    alwaysRaised?: boolean;
  } = {
    centerscreen: true,
    resizable: true,
    fitContent: true,
  },
)
```

### Parameters
#### title
- **Type**: `string`
- **Required**: Yes
- **Description**: Window title (also used as `data-l10n-id`).

#### windowFeatures
- **Type**: `object`
- **Required**: No
- **Default**: `{ centerscreen: true, resizable: true, fitContent: true }`
- **Description**: Configuration for the dialog window.

##### windowFeatures.width / height
- **Type**: `number`
- **Required**: No
- **Description**: Size; ignored when `fitContent` is true.

##### windowFeatures.left / top
- **Type**: `number`
- **Required**: No
- **Description**: Position.

##### windowFeatures.centerscreen
- **Type**: `boolean`
- **Required**: No
- **Default**: `true`
- **Description**: Center on screen.

##### windowFeatures.resizable
- **Type**: `boolean`
- **Required**: No
- **Default**: `true`
- **Description**: Resizable window.

##### windowFeatures.fitContent
- **Type**: `boolean`
- **Required**: No
- **Default**: `true`
- **Description**: Call `sizeToContent()` 300 ms after load.

##### windowFeatures.noDialogMode
- **Type**: `boolean`
- **Required**: No
- **Description**: Show minimize/maximize buttons (`dialog=no`).

##### windowFeatures.alwaysRaised
- **Type**: `boolean`
- **Required**: No
- **Description**: Keep window on top.

### Returns
- **Type**: `this`
- **Description**: The dialog instance (the window is available as `this.window`).

### Behavior
Internally it: generates lock promises; creates the window with the feature string; appends title/l10n links/global stylesheets; replaces `select` and `a` elements with Zotero-compatible custom widgets (see `replaceElement`); applies data-binding; fires load/unload callbacks.

### Example
```ts
const dialog = new DialogHelper(1, 2);

dialog
  .addCell(0, 0, {
    tag: "label",
    properties: { innerText: "Name:" },
  })
  .addCell(0, 1, {
    tag: "input",
    id: "name-input",
    attributes: { "data-bind": "name" },
  })
  .addButton("OK", undefined, {
    callback: () => Zotero.debug("OK clicked"),
  });

dialog.setDialogData({ name: "Ada" }).open("My Settings");
await dialog.dialogData.loadLock.promise; // wait for the window body
if (dialog.dialogData.name) {
  // name changed by the user, data binding wrote it back
}
```

### Error Handling
```ts
try {
  new DialogHelper(0, 2); // throws
} catch (e) {
  // "row and column must be positive integers."
}
```
```

--------------------------------

### replaceExtraFields usage

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/tools/extraField.md

Usage example for replaceExtraFields: replaces the extra field with a map containing a DOI key.

```ts
await tool.replaceExtraFields(item, new Map([["DOI", ["10.1000/1"]]]), { save: true });
```

--------------------------------

### ToolkitGlobal.getInstance()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/toolkitGlobal.md

Returns the unique ToolkitGlobal instance, stored as Zotero._toolkitGlobal. If Zotero cannot be resolved, returns undefined. On first creation or when the current window changes, window-dependent modules are reset and reinitialized.

```APIDOC
## `ToolkitGlobal.getInstance()`

### Description
Returns the unique instance of the ToolkitGlobal singleton. If Zotero cannot be resolved, returns undefined. On first creation or when the current window changes, window-dependent modules are reset and reinitialized.

### Method
`static getInstance()`

### Returns
- `Required<ToolkitGlobal> | undefined` - The singleton instance, or undefined if Zotero is unavailable.

### Example
```ts
import ToolkitGlobal from "zotero-plugin-toolkit/dist/managers/toolkitGlobal.js";
const g = ToolkitGlobal.getInstance();
if (g) {
  // Reset the prompt singleton across windows
  g.prompt.instance = undefined;
}
```
```

--------------------------------

### PluginBridge.setModule

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/utils/pluginBridge.md

Installs a fresh PluginBridge on the ToolkitGlobal when the stored module's version is older than 1. Called by ToolkitGlobal.initializeModules.

```ts
public static setModule(instance: ToolkitGlobal)
```

--------------------------------

### Import and use ToolkitGlobal.getInstance()

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/managers/toolkitGlobal.md

Imports ToolkitGlobal via deep import and retrieves the singleton instance. If the instance exists, the prompt singleton's instance is reset to undefined across windows.

```typescript
import ToolkitGlobal from "zotero-plugin-toolkit/dist/managers/toolkitGlobal.js";
const g = ToolkitGlobal.getInstance();
if (g) {
  // Reset the prompt singleton across windows
  g.prompt.instance = undefined;
}
```

--------------------------------

### setExtraField append and delete

Source: https://github.com/windingwind/zotero-plugin-toolkit/blob/main/_autodocs/api-reference/tools/extraField.md

Usage examples for setExtraField: appending a tag and deleting a key by passing an empty string.

```ts
// Append a tag
await tool.setExtraField(item, "tags", "reviewed", { append: true });
// Delete a key
await tool.setExtraField(item, "DOI", "");
```
Tokens:
Raw