Skip to main content

ZotFlow 1.6.0

This release updates ZotFlow's embedded reader to the Zotero 10 codebase and adds Reading Mode for PDFs and saved web snapshots. Reading Mode is powered by an optional companion plugin, ZotFlow Enhancement Pack, so its larger offline resources do not have to ship inside the main ZotFlow plugin.

Updating ZotFlow itself requires no data migration or settings reset. Normal PDF, EPUB and snapshot reading, annotations, source notes and sync continue to work without the Enhancement Pack.

Enhancement Pack is optional

Install ZotFlow Enhancement Pack from Obsidian's Community Plugins only if you want to use Reading Mode. The Pack can remain disabled after installation: ZotFlow reads its offline resource container directly and never executes it as a plugin.

Highlights​

  • Reading Mode is available for PDFs and saved web snapshots. It presents the document as a reflowable, structured reading view while retaining links back to the source document.
  • Reading Mode works offline after the optional Pack is installed. There are no runtime model or resource downloads.
  • The embedded reader now follows Zotero 10.0.0. Its PDF integration has also moved to Zotero's current Document Worker architecture.
  • External PDF annotations update safely and incrementally. A failed extraction no longer removes the last good annotation snapshot.
  • Local Source Notes now respect ?? frontmatter defaults. Template defaults no longer overwrite values you maintain yourself.
  • Search ignores common Latin diacritics. A plain-letter query can match accented titles, creators, tags, collections and library names.
  • Reopening an existing reader is reliable on Android. ZotFlow now leaves the already-open reader as the final focused tab after removing a duplicate.

Reading Mode and ZotFlow Enhancement Pack​

The Zotero 10 reader adds a Reading Mode button for PDFs and saved web snapshots. When enabled, ZotFlow generates Structured Document Text (SDT) from the exact document snapshot already open in the reader and displays a reflowable semantic view of its headings, paragraphs, lists, tables, images, math and other recognized structure.

SDT generation needs resources that are much larger than the normal plugin. They now live in the separate ZotFlow Enhancement Pack:

  • The Pack uses a passive offline resource-container protocol (version 2.0), with no runtime resource API or global registry.
  • Merely opening a document does not load the Pack, generate SDT or show an installation prompt. ZotFlow waits until Reading Mode is actually requested.
  • If the Pack is missing, ZotFlow explains what is needed and links directly to its Community Plugins page. Install it, leave it disabled, then try again.
  • Generation runs locally in ZotFlow's existing worker. The Reading Mode button shows progress while the current document is processed.
  • The Pack is checked against the exact Document Worker and SDT versions expected by this ZotFlow build. Requested resources are size-limited and verified before use; incompatible or damaged Packs fail explicitly.
  • Concurrent requests share the same in-flight work and resource snapshot. Closing or reconnecting a reader discards late progress and results, and releases the associated resources.
  • Updating the installed Pack cannot replace resources underneath a running reader session. A new request uses the newly installed generation.

SDT is currently generated on demand rather than persisted to the vault, so the first Reading Mode request in a newly opened reader can take time, especially for a long or complex PDF.

Zotero 10 reader and Document Worker​

The embedded reader has been rebased onto Zotero Reader 10.0.0. ZotFlow's PDF operations now use Zotero's Document Worker instead of the previous PDF-processing worker. The shared service handles external annotation import and export, page rotation, recognizer data, and rendering image or ink annotations for Source Notes.

The Document Worker build and its resources are pinned together in a lock file. The plugin build also checks that the reader's SDT format matches the Enhancement Pack contract, preventing independently updated components from silently producing incompatible data.

Safer external PDF annotations​

External annotations embedded directly in a PDF remain read-only in ZotFlow, but their latest extracted state is now stored as a local database snapshot. On the next extraction, the Document Worker receives that snapshot and returns only the annotations to add, update or delete.

  • Annotation changes and the PDF content hash are committed in one database transaction only after extraction succeeds.
  • If the worker fails, ZotFlow keeps both the previous annotations and the previous successful hash, so the file can be retried without losing data.
  • A worker can delete only rows already identified as external annotations; normal Zotero annotations are protected from a malformed result.
  • Changed external annotations trigger a Source Note refresh so the note and reader see the same revision.
  • For local or linked files, ZotFlow trusts the hash of the bytes it actually read rather than stale server metadata when deciding whether to re-extract.
  • Newly extracted IDs avoid collisions with every annotation already stored under the attachment.
  • Image and ink annotations are marked as rendered only after their PNG has been saved successfully.

Local Source Note frontmatter defaults​

Local Source Notes now use the same frontmatter merge rule as Library Source Notes. Prefix a template key with ?? to provide a default without replacing an existing value:

---
??rating: unrated
status: reviewed
---

On the first render this writes rating: unrated. If the note already has a rating value—including false, 0, an empty string or null—that value is preserved. The ?? prefix itself is not written into the Source Note. Keys without the prefix keep their existing behavior and are refreshed from the template on every render.

Previously, Local Source Notes treated ??rating as a literal key and could overwrite the user-maintained rating. This fix makes templates portable between the two Source Note types.

Search and reader navigation fixes​

  • Free-text search now folds common Latin diacritics in both the query and the searchable text. For example, Lammermann matches Lämmermann, and an accented query can also match plain text.
  • The same behavior applies to creator:, tag:, collection:, library: and type: filters, including negated filters. Stored and displayed text is not changed, and non-Latin queries continue to work normally.
  • When a document is already open, ZotFlow now removes the newly created duplicate before revealing and focusing the existing reader. This ordering fixes Android selecting an unrelated fallback tab after duplicate cleanup and is shared by local and Zotero attachment entry points.

Startup diagnostics and internal maintenance​

  • Opening an ordinary reader no longer prefetches SDT, reads Enhancement Pack data or prompts for Pack installation. Pack resources are loaded and decoded only when the feature needs them.
  • Activity Center debug logs now include timing breakdowns for main-thread startup, worker initialization, bundled reader-resource decoding, background tree/CSL work and Enhancement Pack loading. These entries make slow-startup reports easier to diagnose; they do not add telemetry or network reporting.
  • The release workflow now verifies that the Git tag, package.json, manifest.json and versions.json agree, performs the full CI build, attaches build provenance, and creates a draft GitHub release with the three Obsidian release files.
  • The version-bump script now records every released version in versions.json, even when several releases share the same minimum Obsidian version. The missing 1.5.2 mapping has been restored.
  • Document Worker updates are pinned by archive and resource metadata and can notify the Enhancement Pack repository to prepare a matching update.
  • The unused note-editor submodule has been removed and replaced in the repository layout by the Enhancement Pack submodule. Internal design notes are no longer tracked as release source.
  • Focused regression coverage was added for Pack parsing and lifecycle, Document Worker resources, SDT requests, external annotation transactions, reader-tab navigation, frontmatter defaults and diacritic-insensitive search.