Release Notes: v2.4.4 — Span Annotation Fixes & UX Improvements

Bug-fix release that resolves span overlay misalignment issues affecting all span annotation tasks, plus a small UX improvement for single-label span schemas.

Bug Fixes

Span Overlay Positioning Fix

  • Fixed overlays rendering on the wrong line of text. The root cause was white-space: pre-wrap on #text-content being inherited by the #span-overlays container. Template whitespace inside #span-overlays was rendered as real content, causing absolutely-positioned overlays (which lacked explicit top/left) to use a "hypothetical static position" shifted ~30px down — exactly one line height. On multi-line text, overlays appeared on a completely different line than the selected text.
  • Fixed collectTextNodes walking into overlay containers. The text-node walker in getPositionsFromOffsets, getTextPositions, and getOffsetsFromSelection recursed into #span-overlays children, causing overlay label text ("News", delete button "x") to inflate cumulative character offsets. Each successive span rendered at a progressively worse position.
  • Fixed createSpanWithAlgorithm using fragile indexOf-based positioning. The initial span overlay was positioned using getTextPositions() which ignored the provided character offsets and searched data-original-text with indexOf(text) instead. When data-original-text differed from DOM text (e.g., after loadAnnotations overwrites it with normalized API text), the indexOf result pointed to wrong positions. Now uses getPositionsFromOffsets() (offset-based DOM walk) consistently, matching the reload rendering path.

Python Compatibility

  • Fixed Python 3.9 compatibility: replaced match/case with if/elif in ai_cache.py

Other Fixes

  • Added __main__.py to enable python -m potato execution
  • Fixed marker registry, conversation-tree bug, and KeyError scope (PR #142)

New Features

Auto-Select Single Span Label

When a span schema has exactly one label, it is now automatically selected on page load. Annotators can immediately start highlighting text without needing to click the label checkbox first. Multi-label span schemas are unaffected and still require explicit selection. The checkbox remains visible and can be unchecked to disable span annotation mode.

Upgrade

pip install --upgrade potato-annotation==2.4.4