Only cut oversized segments at real gaps between items

The width-budget crop snapped to the nearest blank column, and in rendered text
the gap between two characters is a single column. So a cut routinely landed
inside a word: the cycle showed "Wednesda" and the orphaned "y" turned up as a
lone floating letter in the next cycle, positioned after whatever plugin
happened to precede it.

Measured on the clock-simple segment to confirm: its blank runs are
[1, 1, 1, 1, 1, 8, 8] — five single-column letter gaps, every one of which
find_blank_cut would happily have chosen.

Cuts now only land in a run of at least min_cut_gap blank columns (default 6),
which excludes letter spacing while still finding the gaps plugins put between
items (the stocks ticker uses 32px, baseball 48px). Where no boundary falls
inside the budget the cut waits for the next one and overruns, because
splitting an item is worse than a slightly long segment.

Continuous content is treated differently on purpose: an image with no internal
gaps is a map or a chart, where any column is as good as another, so it is still
cut to the budget exactly. The gap rule protects discrete items; letting a solid
image escape the cap in its name would be wrong.

blank_runs() is vectorised — 48ms for a 17,000px strip, against seconds for a
per-column Python loop.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KEZK1P1Q1fu5pcuVrkrCFZ

src/vegas_mode/config.py

@@ -64,6 +64,14 @@ class VegasModeConfig:
     # per cycle, so a 20-plugin install took seven cycles to come around.
     plugins_per_cycle: int = 6
 
+    # Minimum run of blank columns that counts as a boundary between items when
+    # an oversized segment has to be narrowed. Measured on rendered text, the
+    # gaps between characters are a single column while gaps between items are
+    # 8px and up, so anything above 1 stops a cut landing inside a word. Cutting
+    # mid-word orphaned the tail into the next cycle, which showed up as a lone
+    # letter floating between two unrelated plugins.
+    min_cut_gap: int = 6
+
     # Cap on one plugin's share of a cycle, as a multiple of display width.
     # A single ticker returning 7,000px would otherwise hold the panel for over
     # two minutes. Overflow is deferred to later cycles rather than discarded.
@@ -108,6 +116,7 @@ class VegasModeConfig:
             render_width_pct=int(vegas_config.get('render_width_pct', 100)),
             min_content_separation=int(
                 vegas_config.get('min_content_separation', 24)),
+            min_cut_gap=int(vegas_config.get('min_cut_gap', 6)),
             auto_trim=vegas_config.get('auto_trim', True),
             trim_threshold=int(vegas_config.get('trim_threshold', 10)),
             content_padding=int(vegas_config.get('content_padding', 8)),
@@ -136,6 +145,7 @@ class VegasModeConfig:
             'intra_plugin_gap': self.intra_plugin_gap,
             'render_width_pct': self.render_width_pct,
             'min_content_separation': self.min_content_separation,
+            'min_cut_gap': self.min_cut_gap,
             'auto_trim': self.auto_trim,
             'trim_threshold': self.trim_threshold,
             'content_padding': self.content_padding,
@@ -238,6 +248,11 @@ class VegasModeConfig:
                 "min_content_separation must be between 0 and 256, "
                 f"got {self.min_content_separation}")
 
+        if not 1 <= self.min_cut_gap <= 128:
+            errors.append(
+                "min_cut_gap must be between 1 and 128, "
+                f"got {self.min_cut_gap}")
+
         if self.intra_plugin_gap < 0:
             errors.append(
                 f"intra_plugin_gap must be >= 0, got {self.intra_plugin_gap}")
@@ -305,6 +320,8 @@ class VegasModeConfig:
         if 'min_content_separation' in vegas_config:
             self.min_content_separation = int(
                 vegas_config['min_content_separation'])
+        if 'min_cut_gap' in vegas_config:
+            self.min_cut_gap = int(vegas_config['min_cut_gap'])
         if 'auto_trim' in vegas_config:
             self.auto_trim = vegas_config['auto_trim']
         if 'trim_threshold' in vegas_config:

src/vegas_mode/geometry.py

@@ -16,7 +16,7 @@ All column scans go through numpy: a Python-level per-column loop over a
 path.
 """
 
-from typing import NamedTuple, Optional, Tuple
+from typing import List, NamedTuple, Optional, Tuple
 
 import numpy as np
 from PIL import Image
@@ -192,6 +192,83 @@ def separation_gap(
     return max(minimum, target - existing, 0)
 
 
+def blank_runs(
+    img: Image.Image,
+    min_run: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> List[Tuple[int, int]]:
+    """
+    Find maximal runs of blank columns at least ``min_run`` wide.
+
+    Distinguishes item boundaries from letter spacing. Measured on real
+    rendered text, the gaps *between characters* are a single column, while the
+    gaps a plugin puts *between items* are 8px and up (the stocks ticker uses
+    32px, baseball 48px). Treating any blank column as a cut point therefore
+    slices words in half; requiring a run excludes letter spacing.
+
+    Args:
+        img: Image to scan
+        min_run: Minimum consecutive blank columns to qualify
+        threshold: Ink threshold
+
+    Returns:
+        List of (start, end) half-open column ranges, in left-to-right order
+    """
+    blank = ~column_has_ink(img, threshold)
+    if not blank.any():
+        return []
+
+    # Vectorised run detection: pad with False so runs touching either edge get
+    # a boundary, then read starts and ends off the first difference. A Python
+    # loop here would be far too slow on a 17,000px ticker strip.
+    padded = np.concatenate(([False], blank, [False]))
+    diff = np.diff(padded.astype(np.int8))
+    starts = np.flatnonzero(diff == 1)
+    ends = np.flatnonzero(diff == -1)
+
+    long_enough = (ends - starts) >= max(1, min_run)
+    return list(zip(starts[long_enough].tolist(), ends[long_enough].tolist()))
+
+
+def find_item_boundary(
+    img: Image.Image,
+    target: int,
+    min_run: int,
+    threshold: int = DEFAULT_INK_THRESHOLD,
+) -> Optional[int]:
+    """
+    Find the column nearest ``target`` that sits inside a gap between items.
+
+    Used to narrow an oversized segment without cutting through a word. Only
+    runs of at least ``min_run`` blank columns are considered, so the
+    single-column gaps between characters are never chosen — cutting there
+    orphaned the tail of a word into the following cycle, which is how a lone
+    "y" from "Wednesday" ended up floating between two unrelated plugins.
+
+    Args:
+        img: Image to cut
+        target: Preferred cut column
+        min_run: Minimum blank-run width that counts as an item boundary
+        threshold: Ink threshold
+
+    Returns:
+        A column inside a qualifying gap, or None when the image has no such
+        gap at all — in which case the caller must not cut it.
+    """
+    runs = blank_runs(img, min_run, threshold)
+    if not runs:
+        return None
+
+    # Nearest point of the nearest run. For a run left of target that is its
+    # end (content resumes just after), for a run right of target its start
+    # (content stopped just before) — the right choice in both directions.
+    def clamp_to_run(run: Tuple[int, int]) -> int:
+        start, end = run
+        return max(start, min(target, end - 1))
+
+    return min((clamp_to_run(r) for r in runs), key=lambda c: abs(c - target))
+
+
 def find_blank_cut(
     img: Image.Image,
     target: int,

src/vegas_mode/plugin_adapter.py

@@ -13,7 +13,7 @@ from typing import Optional, List, Any, Tuple, Union, TYPE_CHECKING
 from PIL import Image
 
 from src.vegas_mode.geometry import (
-    find_blank_cut,
+    blank_runs,
     separation_gap,
     trim_to_content,
 )
@@ -386,22 +386,48 @@ class PluginAdapter:
         if offset >= img.width:
             offset = 0
 
-        # Snap both edges to blank columns. The search radius is generous
-        # enough to clear a wide glyph but small enough not to distort the
-        # requested budget much.
-        snap = max(8, self.display_width // 16)
-        start = find_blank_cut(img, offset, snap, self.config.trim_threshold)
-        end = find_blank_cut(
-            img, min(start + budget, img.width), snap, self.config.trim_threshold)
-        if end <= start:
-            end = min(start + budget, img.width)
+        # Cut only where the plugin left a real gap between items. Snapping to
+        # any blank column used to pick the single-column gaps between
+        # characters, splitting a word and orphaning its tail into the next
+        # cycle — a lone "y" from "Wednesday" floating between two unrelated
+        # plugins. Overshooting the budget is the lesser evil.
+        min_run = max(2, self.config.min_cut_gap)
+        gaps = blank_runs(img, min_run, self.config.trim_threshold)
+
+        if not gaps:
+            # No internal gaps means continuous content — a map, a chart, a
+            # photo — where any column is as good as any other, so cut to the
+            # budget exactly. The gap rule exists to protect discrete items
+            # (words, ticker entries); it would be wrong to let a solid image
+            # escape the cap in its name.
+            end = min(offset + budget, img.width)
+            self._item_offsets[plugin_id] = 0 if end >= img.width else end
+            logger.info(
+                "[%s] Width budget %dpx: cropped continuous %dpx image to "
+                "[%d:%d] (no item gaps of %dpx+ to align to)",
+                plugin_id, budget, img.width, offset, end, min_run
+            )
+            return img.crop((offset, 0, end, img.height))
+
+        # Cut mid-gap so the content either side keeps some breathing room.
+        cuts = sorted({0, img.width} | {(a + b) // 2 for a, b in gaps})
+
+        start = max((c for c in cuts if c <= offset), default=0)
+        later = [c for c in cuts if c > start]
+        if not later:
+            end = img.width
+        else:
+            within = [c for c in later if c <= start + budget]
+            # No boundary inside the budget: take the next one and overrun,
+            # because the alternative is cutting through an item.
+            end = max(within) if within else min(later)
 
         # Next cycle resumes where this one stopped; wrap when the strip ends.
         self._item_offsets[plugin_id] = 0 if end >= img.width else end
 
         logger.info(
             "[%s] Width budget %dpx: cropped single %dpx image to [%d:%d] "
-            "(%dpx), window advances next cycle",
+            "(%dpx) at item boundaries, window advances next cycle",
             plugin_id, budget, img.width, start, end, end - start
         )
         return img.crop((start, 0, end, img.height))