draftwright 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

draftwright/_core.py

@@ -14,7 +14,7 @@ import functools
 import logging
 import re
 from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
 from types import SimpleNamespace
 from typing import TYPE_CHECKING
@@ -166,16 +166,17 @@ def _dim(p1, p2, side, distance, draft, **kwargs):
 class Strip:
     """A one-dimensional annotation band adjacent to an orthographic view.
 
-    Annotations are stacked outward from the view edge by calling
-    :meth:`allocate`.  The cursor starts at ``anchor + direction * gap`` and
-    advances after each successful allocation.
+    A plain geometry record: the collect-then-solve placers (ADR 0009) read its
+    bounds (:func:`~draftwright.annotations._common.strip_free_span`) and carve
+    around the placed annotations. The mutable ``allocate``/``peek`` cursor was
+    retired once every placer moved to the carve (#150).
 
     Attributes:
         anchor:      Page coordinate of the view edge this strip starts from.
         outer_limit: Page coordinate at which the strip ends (page margin,
                      neighbouring view, or title-block boundary).
-        direction:   ``+1`` — cursor moves away from anchor (right/above);
-                     ``-1`` — cursor retreats from anchor (left/below).
+        direction:   ``+1`` — stacks away from anchor (right/above);
+                     ``-1`` — stacks back toward smaller coords (left/below).
         gap:         Clearance between the view edge and the first annotation.
         spacing:     Clearance between successive annotations.
     """
@@ -185,56 +186,12 @@ class Strip:
     direction: float = 1.0
     gap: float = 8.0
     spacing: float = 4.0
-    _cursor: float = field(init=False, compare=False, repr=False)
-
-    def __post_init__(self):
-        self._cursor = self.anchor + self.direction * self.gap
-
-    # ------------------------------------------------------------------
-    # Public API
 
     @property
     def available(self) -> float:
         """Total space available in this strip (mm)."""
         return abs(self.outer_limit - self.anchor)
 
-    @property
-    def depth_used(self) -> float:
-        """How far the cursor has advanced from the anchor (mm)."""
-        return abs(self._cursor - self.anchor)
-
-    def peek(self, size: float) -> float | None:
-        """Return what ``allocate(size)`` would return without advancing the cursor."""
-        if self.direction == 1:
-            start = self._cursor
-            return start if (start + size) <= self.outer_limit else None
-        else:
-            end = self._cursor
-            return end if (end - size) >= self.outer_limit else None
-
-    def allocate(self, size: float) -> float | None:
-        """Reserve *size* mm; return the near-edge page coordinate, or ``None`` if full.
-
-        The returned value is the page coordinate of the annotation's
-        dimension line (or leader elbow).  Convert to a relative offset with::
-
-            distance = abs(page_coord - strip.anchor)
-        """
-        if self.direction == 1:
-            start = self._cursor
-            end = start + size
-            if end > self.outer_limit:
-                return None
-            self._cursor = end + self.spacing
-            return start
-        else:
-            end = self._cursor
-            start = end - size
-            if start < self.outer_limit:
-                return None
-            self._cursor = start - self.spacing
-            return end
-
 
 @dataclass
 class ViewZones:
@@ -626,7 +583,11 @@ _PAGE_SIZES = {
     "A0": (1189.0, 841.0),
 }
 
-_SCALES = [10.0, 5.0, 2.0, 1.0, 0.5, 0.2]
+# ISO 5455 scale series (1-2-5 decades). Enlargements + 1:1 first, then reductions
+# down to 1:10000 so a very large part still gets a scale that FITS rather than an
+# overflowing layout (#350). Ordered largest-scale-first for "least reduction first".
+_SCALES = [10.0, 5.0, 2.0, 1.0]
+_SCALES += [0.5, 0.2, 0.1, 0.05, 0.02, 0.01, 0.005, 0.002, 0.001, 0.0005, 0.0002, 0.0001]
 
 # Horizontal page budget to reserve for the isometric view during scale
 # selection and view placement, as a fraction of bbox_max * scale.  This is a
@@ -677,6 +638,19 @@ _LADDER = [
     (0.2, 841.0, 594.0, 150.0),  # A1 1:5
     (0.5, 1189.0, 841.0, 150.0),  # A0 1:2
     (0.2, 1189.0, 841.0, 150.0),  # A0 1:5
+    # Past 1:5 keep reducing on A0 (the largest sheet) through the rest of the ISO 5455
+    # series, so a part too big for A0 1:5 still gets a scale that FITS rather than an
+    # overflowing layout (#350). A0 1:10000 holds anything up to ~8.4 m of drawn height.
+    (0.1, 1189.0, 841.0, 150.0),  # A0 1:10
+    (0.05, 1189.0, 841.0, 150.0),  # A0 1:20
+    (0.02, 1189.0, 841.0, 150.0),  # A0 1:50
+    (0.01, 1189.0, 841.0, 150.0),  # A0 1:100
+    (0.005, 1189.0, 841.0, 150.0),  # A0 1:200
+    (0.002, 1189.0, 841.0, 150.0),  # A0 1:500
+    (0.001, 1189.0, 841.0, 150.0),  # A0 1:1000
+    (0.0005, 1189.0, 841.0, 150.0),  # A0 1:2000
+    (0.0002, 1189.0, 841.0, 150.0),  # A0 1:5000
+    (0.0001, 1189.0, 841.0, 150.0),  # A0 1:10000
 ]
 
 

draftwright/annotations/_common.py

@@ -7,6 +7,50 @@ and an AABB overlap test (`_box_hits`). Bottom of the annotations DAG.
 
 from __future__ import annotations
 
+import logging
+from dataclasses import dataclass, field
+
+from build123d_drafting.helpers import Dimension, SafeDimension
+
+from draftwright.layout import StripCandidate, plan_strip
+
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Escalation:
+    """A first-class "could not place this here" signal (ADR 0009 Amendment 1, P5-strand-2).
+
+    Placers *collect* one of these into ``dwg._escalations`` at the point of failure —
+    instead of recording a stringly-typed ``*_dropped`` lint code and letting the escalators
+    grep for it — and one later resolver pass groups them by ``(view, feature-or-pattern)``,
+    picks a remedy per group (ISO pattern-grouped balloon / table / detail / drop), and emits
+    the ``*_dropped`` lint codes only for what stays unresolved (so coverage lint + the
+    cleanliness ratchet keep working). See the ADR / epic #351.
+
+    The hole callout/location placers emit these (#351 PR-2); the resolver in
+    ``annotations/orchestrator.py`` (``_maybe_tabulate_holes``) consumes them, including
+    the ISO pattern-grouped balloon fallback for a dropped pattern callout (#351 PR-3).
+
+    Attributes:
+        kind:     what could not be placed — ``"callout" | "location" | "slot" | "step" | "pmi"``.
+        view:     the owning orthographic view (``None`` for drawing-level).
+        feature:  reference to the IR feature / ``HoleRef`` / key it belongs to — carries the
+                  pattern membership the resolver groups on (a ``"callout"`` escalation's
+                  feature is the dropped group's ``PatternFeature`` when it is a
+                  fully-surviving recognised pattern, else ``None``). Left untyped to keep
+                  this module a leaf (no dependency on ``model.ir``).
+        reason:   why placement failed — ``"strip_full" | "illegible" | "corridor_blocked" | "no_room"``.
+        remedies: ranked candidate remedies the resolver may pick, e.g.
+                  ``("group_balloon", "table", "detail", "drop")``. Empty = resolver's default ladder.
+    """
+
+    kind: str
+    view: str | None
+    feature: object
+    reason: str
+    remedies: tuple[str, ...] = field(default_factory=tuple)
+
 
 def _anno_box(o):
     """Page-space bbox ``(x0, y0, x1, y1)`` of an annotation — its text
@@ -38,6 +82,139 @@ def _occupied_boxes(dwg):
     return boxes
 
 
+def _geom_box(o):
+    """Full rendered-geometry bbox ``(x0, y0, x1, y1)`` of an annotation — leader
+    shafts and arrow tips, dimension witness/extension lines, centrelines, hatch —
+    *not* just its label box. ``None`` if it does not bbox cleanly (logged at
+    debug: a silently dropped occupant is the wrong failure mode for an occupancy
+    model, so the omission is at least observable)."""
+    try:
+        b = o.bounding_box()
+        return (b.min.X, b.min.Y, b.max.X, b.max.Y)
+    except Exception as exc:  # noqa: BLE001 — not every annotation bbox-es cleanly
+        _log.debug("strip occupancy: %s did not bbox (%s); omitted", type(o).__name__, exc)
+        return None
+
+
+CROSSABLE_TYPES = frozenset({"Centerline", "CenterlineCircle", "CenterMark"})
+"""Annotation types a *dimension* may legitimately cross (ISO 128): centre lines
+and centre marks. A **leader**, by contrast, must avoid them (#305) — so this is a
+per-consumer choice, passed as ``crossable`` to :func:`strip_obstacles`."""
+
+
+def strip_obstacles(dwg, view=None, *, crossable=()):
+    """The COMPLETE occupancy for strip placement (ADR 0009): every placed
+    annotation's full rendered footprint, optionally restricted to *view*, minus
+    any annotation whose type name is in *crossable* (things this particular
+    consumer may legitimately overlap — e.g. a location dim crosses a centre line
+    but a leader does not; see :data:`CROSSABLE_TYPES`).
+
+    Unlike :func:`_occupied_boxes` (label boxes only, with bare centrelines
+    excluded), this captures the geometry a label box hides — leader shafts and
+    arrow tips, dimension witness/extension lines, centrelines, and the section
+    hatch. That hidden geometry is the 'invisible occupant' class behind the
+    recurring strip overlaps (#133/#225/#305): a placer that consults only label
+    boxes commits a callout into space a leader or extension line already crosses.
+
+    *view* scoping keeps this view's own annotations **and** drawing-level obstacles
+    that no orthographic view owns (the section hatch, title block, …) — those a
+    strip placer must still avoid — and drops only the *other* ortho views' blocks
+    (which compose-then-pack keeps disjoint, ADR 0004). The section hatch
+    (``view_of`` ``None``) is therefore present in every per-view query, the way
+    :func:`_occupied_boxes` special-cased it; restricting it to ``view=None`` would
+    re-open the very blind spot this closes.
+
+    Boxes are AABBs ``(x0, y0, x1, y1)`` (use with :func:`_box_hits`) — intentionally
+    conservative: a diagonal leader's box over-claims its empty triangle (ADR 0009
+    notes angled leaders weaken the bound), which only ever over-avoids, never
+    under-avoids.
+
+    The occupancy source for the collect-then-solve carve — every migrated renderer's
+    ``place_strip_candidates`` call wires this in (#321/#150/P3)."""
+    boxes = []
+    for name, o in dwg.iter_annotations():
+        if view is not None:
+            owner = dwg.view_of(name)
+            if owner is not None and owner != view:
+                continue  # owned by a different ortho view → its own (disjoint) block
+        if type(o).__name__ in crossable:
+            continue  # this consumer may cross it (centre lines/marks for a dim)
+        bb = _geom_box(o)
+        if bb is not None:
+            boxes.append(bb)
+    return boxes
+
+
+def strip_free_span(strip):
+    """``(lo, hi, inner)`` page coords of *strip* along its stacking axis, where
+    *inner* is the end nearest the view edge (the first tier a dim fills). Reads the
+    live ``outer_limit`` so an orchestrator reservation (#133) stays honoured. The
+    cursor-free counterpart of :meth:`Strip.allocate` — a collect-then-solve pass
+    (ADR 0009) reads these bounds and carves, rather than advancing a mutable cursor."""
+    near = strip.anchor + strip.direction * strip.gap
+    if strip.direction == 1:
+        return near, strip.outer_limit, near  # lo, hi, inner (=lo)
+    return strip.outer_limit, near, near  # lo, hi, inner (=hi)
+
+
+def carve_free_segments(lo, hi, intervals, pad):
+    """``[lo, hi]`` minus every obstacle interval inflated by *pad*, merged and
+    complemented — the option-(c) occupancy carve (ADR 0009 / #321). A dim is then
+    spaced only WITHIN a clear segment, so it can never overprint a placed occupant
+    (a leader shaft, the section hatch, a location-dim tier): the old per-tier
+    ``allocate`` + post-hoc ``_box_hits`` retry becomes structural. *intervals* are
+    ``(a, b)`` pairs along the strip's stacking axis (e.g. ``(box_y0, box_y1)`` for a
+    below strip). Returns a list of ``(seg_lo, seg_hi)`` free segments, lo→hi."""
+    blocked = []
+    for a0, b0 in intervals:
+        a1, b1 = max(lo, a0 - pad), min(hi, b0 + pad)
+        if b1 > a1:
+            blocked.append((a1, b1))
+    blocked.sort()
+    merged: list[list[float]] = []
+    for a0, b0 in blocked:
+        if merged and a0 <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], b0)
+        else:
+            merged.append([a0, b0])
+    free, cur = [], lo
+    for a0, b0 in merged:
+        if a0 > cur:
+            free.append((cur, a0))
+        cur = b0
+    if cur < hi:
+        free.append((cur, hi))
+    return free
+
+
+def corridor_blockers(dwg, view):
+    """Boxes of annotations a dimension's *witness corridor* (the span from the view
+    edge out to its dim line) must not cross — leaders/callouts, the section hatch, the
+    title block: everything that is neither a datum-chained ``Dimension`` nor a
+    crossable centre line/mark (:data:`CROSSABLE_TYPES`).
+
+    :func:`strip_obstacles` carves the 1-D strip so a dim *line* clears every occupant,
+    but a right/below dim also occupies the 2-D corridor back to the view — and a bore
+    callout's leader sitting in that corridor is crossed however far out the line is
+    placed (the #133/#225/#305 leader class, in its witness-corridor form). A dim whose
+    full footprint hits one of these must route to another view, not overprint it (ISO
+    128). Sibling location/envelope dims are excluded: they chain off the shared datum
+    and legitimately share the corridor. View scoping mirrors :func:`strip_obstacles`
+    (this view's own annotations + drawing-level occupants that no ortho view owns)."""
+    boxes = []
+    for name, o in dwg.iter_annotations():
+        if view is not None:
+            owner = dwg.view_of(name)
+            if owner is not None and owner != view:
+                continue
+        if isinstance(o, (Dimension, SafeDimension)) or type(o).__name__ in CROSSABLE_TYPES:
+            continue  # datum-chained dims share the corridor; centre lines are crossable
+        bb = _geom_box(o)
+        if bb is not None:
+            boxes.append(bb)
+    return boxes
+
+
 def _box_hits(bb, boxes):
     """True when ``bb`` overlaps any box in ``boxes`` (strict AABB test). Slightly
     more conservative than the within-view label lint (which tolerates a 0.5 mm
@@ -49,3 +226,315 @@ def _box_hits(bb, boxes):
         if min(bb[2], c[2]) > max(bb[0], c[0]) and min(bb[3], c[3]) > max(bb[1], c[1]):
             return True
     return False
+
+
+def _segment_hits_box(p1, p2, box) -> bool:
+    """True when line segment *p1*-*p2* intersects axis-aligned *box*
+    ``(x0, y0, x1, y1)`` — the precise counterpart of :func:`_box_hits` for a
+    genuinely diagonal shaft (ADR 0009 P4/#318, #305: "a diagonal leader's box
+    over-claims its empty triangle"). Boxing an angled segment for a coarse
+    reject is correct and cheap; boxing it for the final accept/reject decision
+    over-avoids free space a real diagonal never crosses. Endpoint-in-box and
+    the 4 edge-crossing cases (a standard segment/AABB test).
+
+    The crossing test uses strict inequality deliberately, not an inclusive
+    ``<= 0`` — an inclusive test also treats a segment merely COLLINEAR with
+    one of the box's (infinite) edge lines as a hit, regardless of whether it
+    is anywhere near the box along that line (verified: a vertical segment at
+    ``x == box.x0`` but far outside ``[y0, y1]`` false-hits under `<=`). That
+    false-positive class is common (any axis-aligned shaft sharing an X or Y
+    coordinate with an edge), unlike the strict form's own known gap — a
+    segment passing exactly through two opposite corners is a measure-zero
+    event for the continuous, non-integer leader positions this computes over
+    (review finding, #351 P5 strand 3: tried the inclusive form, reverted)."""
+    x0, y0, x1, y1 = box
+
+    def _inside(p):
+        return x0 <= p[0] <= x1 and y0 <= p[1] <= y1
+
+    if _inside(p1) or _inside(p2):
+        return True
+
+    def _cross(o, a, b):
+        return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+    def _seg_seg(a1, a2, b1, b2):
+        d1, d2 = _cross(b1, b2, a1), _cross(b1, b2, a2)
+        d3, d4 = _cross(a1, a2, b1), _cross(a1, a2, b2)
+        return ((d1 > 0 and d2 < 0) or (d1 < 0 and d2 > 0)) and (
+            (d3 > 0 and d4 < 0) or (d3 < 0 and d4 > 0)
+        )
+
+    corners = ((x0, y0), (x1, y0), (x1, y1), (x0, y1))
+    return any(_seg_seg(p1, p2, corners[i], corners[(i + 1) % 4]) for i in range(4))
+
+
+@dataclass
+class CorridorCandidate:
+    """One datum-referenced linear dim collected for a shared corridor's single solve
+    (ADR 0009 end state, #345/#346). Multiple render passes (`render_locations`,
+    `render_slots`) feed the SAME above-view strip; committing per-pass interleaves the
+    dims and cannot dedup coincident spans. Each pass instead registers a candidate here;
+    one :func:`solve_corridor` per strip dedups, orders, and places the whole set.
+
+    Attributes:
+        name/build: the ``(name, pos->Dimension)`` pair :func:`place_strip_candidates`
+            consumes — unchanged.
+        order:      sort key placing the candidate in the corridor ladder. Location dims
+            key on datum distance (the monotonic ISO ladder); size dims form a separate
+            contiguous run so a slot length never lands mid-ladder (#346).
+        dedup:      coincidence key ``(view, meas-origin, meas-endpoint)`` on the MEASURED
+            axis, or ``None`` to never dedup (size dims). Two candidates with equal keys are
+            the same physical dimension; the higher-``precedence`` one survives (#345).
+        precedence: dedup survivor rank — a hole *location* dim (feeds coverage/table
+            escalation) outranks a coincident slot *position* line.
+        on_place/on_drop: the pass's own post-placement bookkeeping — coverage
+            registration / drop lint + `Escalation`, or a slot's below-side fallthrough.
+        force:      policy-B force-keep after the corridor-respecting pass (locations have
+            no alternate view); size/position slot dims fall through instead (``on_drop``).
+    """
+
+    name: str
+    build: object
+    order: tuple
+    on_place: object
+    on_drop: object
+    dedup: tuple | None = None
+    precedence: int = 0
+    force: bool = False
+
+
+def solve_corridor(dwg, strip, view, axis, cands, tier):
+    """One collect-then-solve over every :class:`CorridorCandidate` a shared strip
+    accumulated across passes (ADR 0009 end state). Dedup → order → one non-force
+    :func:`place_strip_candidates` pass → a force pass for the force-eligible leftovers →
+    dispatch each candidate's ``on_place``/``on_drop``. This is what removes the duplicate
+    span (#345) and the interleaved ladder (#346) by construction: a single solve sees the
+    full set, so coincident spans collapse and the order is one monotonic chain."""
+    if not cands:
+        return
+    # Dedup: keep the highest-precedence candidate per coincidence key (tie-break on name,
+    # deterministic — ADR 0001). A displaced duplicate is a *loser*: while its winner is
+    # drawn it is silently dropped (never starved, so firing its pass's drop lint would be a
+    # false report) — but if the winner itself fails to place, the top loser is promoted so
+    # the measurement still gets its pass's fallthrough/drop handling (no silent vanish).
+    winners: dict = {}
+    for c in cands:
+        if c.dedup is None:
+            continue
+        prev = winners.get(c.dedup)
+        # Winner: highest precedence, ties broken by the lexicographically smaller name.
+        if (
+            prev is None
+            or c.precedence > prev.precedence
+            or (c.precedence == prev.precedence and c.name < prev.name)
+        ):
+            winners[c.dedup] = c
+    kept = [c for c in cands if c.dedup is None or winners.get(c.dedup) is c]
+    losers: dict = {}  # dedup key → its displaced candidates (highest precedence first)
+    for c in cands:
+        if c.dedup is not None and winners.get(c.dedup) is not c:
+            losers.setdefault(c.dedup, []).append(c)
+    for group in losers.values():
+        group.sort(key=lambda c: (-c.precedence, c.name))
+    kept.sort(key=lambda c: c.order)
+
+    def _promote_losers(dropped_winner):
+        # The winner did not place → hand its measurement to the best surviving loser
+        # (e.g. the slot position's below-strip fallthrough), then stop.
+        for loser in losers.get(dropped_winner.dedup, ()):
+            loser.on_drop(loser.name)
+            break
+
+    if strip is None:  # no such strip on this drawing — every candidate drops
+        for c in kept:
+            c.on_drop(c.name)
+            if c.dedup is not None:
+                _promote_losers(c)
+        return
+    pairs = [(c.name, c.build) for c in kept]
+    left = {n for n, _ in place_strip_candidates(dwg, strip, view, axis, pairs, tier)}
+    force_pairs = [(c.name, c.build) for c in kept if c.name in left and c.force]
+    still = (
+        {
+            n
+            for n, _ in place_strip_candidates(
+                dwg, strip, view, axis, force_pairs, tier, force=True
+            )
+        }
+        if force_pairs
+        else set()
+    )
+    for c in kept:
+        placed = c.name not in left or (c.force and c.name not in still)
+        if placed:
+            c.on_place(c.name)  # placed in the corridor-respecting pass or the force pass
+        else:
+            c.on_drop(c.name)  # dropped / not force-kept — the pass's drop handler runs
+            if c.dedup is not None:  # a deduped winner failed → promote its top loser
+                _promote_losers(c)
+
+
+def register_corridor(dwg, key, strip, view, axis, tier, cand):
+    """Queue a :class:`CorridorCandidate` under a shared corridor *key* so one
+    :func:`drain_corridors` places the whole cross-pass set together (ADR 0009 end state).
+    The first registration for a key fixes its ``(strip, view, axis, tier)``."""
+    b = dwg._corridor_batch.setdefault(
+        key, {"strip": strip, "view": view, "axis": axis, "tier": tier, "cands": []}
+    )
+    b["cands"].append(cand)
+
+
+def drain_corridors(dwg):
+    """Solve every registered corridor (one :func:`solve_corridor` per strip), then clear
+    the batch. Called once, after all corridor-feeding passes have registered."""
+    for b in dwg._corridor_batch.values():
+        solve_corridor(dwg, b["strip"], b["view"], b["axis"], b["cands"], b["tier"])
+    dwg._corridor_batch = {}
+
+
+def place_strip_candidates(dwg, strip, view, axis, cands, tier, *, force=False):
+    """Collect-then-solve placement of location/feature dims on one strip (ADR 0009).
+    The single shared strip placer that retires the ``Strip.allocate`` cursor (#150,
+    P3): each candidate in *cands* — an ``(name, build(pos)->dim)`` pair — is spaced by
+    one :func:`plan_strip` solve per free segment of the CARVED strip (`strip` carved
+    around :func:`strip_obstacles`), replacing the per-dim ``allocate`` + ``_box_hits``
+    tier-retry. *tier* is the label height (sets the inter-dim gap ``tier + spacing``).
+
+    Occupancy is THIS view's own placed annotations plus the drawing-level obstacles no
+    ortho view owns (the section hatch), recomputed per call so a dim placed earlier in
+    the pass is avoided; other ortho views are disjoint (ADR 0004) and excluded so their
+    rows never over-carve this strip. This makes the old post-hoc collision retry
+    structural: a dim can never land on a bore-callout leader shaft the label-only
+    occupancy missed (#133/#225/#305).
+
+    A right/below dim also occupies the 2-D corridor back to the view edge, which the
+    1-D strip carve cannot represent: a leader in that corridor is crossed no matter how
+    far out the dim line lands. By default such a placement is rejected so the caller can
+    route the dim to the other view (its disjoint block cannot cross this leader).
+    ``force=True`` skips that corridor check — the caller's last resort when no view took
+    the dim cleanly: keep it on its natural view and accept the (same-feature) leader
+    crossing rather than drop a real dimension (policy B). Candidates that find no strip
+    tier AT ALL are still returned (a physically full strip — the caller records the
+    genuine drop)."""
+    if strip is None or not cands:
+        return list(cands)
+    lo, hi, inner = strip_free_span(strip)
+    # Reserve the outermost label's height at the strip boundary. plan_strip bounds the
+    # dim-LINE position, but the label extends `tier` OUTWARD from it — so without this
+    # the last tier's label overshoots outer_limit (into the iso view / page margin),
+    # unlike the old Strip.allocate which checked `start + tier <= outer_limit` (#338
+    # review). The strip edge is not an obstacle (obstacles carry their own footprint +
+    # pad), so only the boundary needs it; obstacle-bounded segments are unaffected.
+    if inner == lo:
+        hi -= tier
+    else:
+        lo += tier
+    idx = 1 if axis == "y" else 0
+    perp = 0 if axis == "y" else 1  # the axis the dims do NOT stack along
+    pad = tier + strip.spacing  # min separation between stacked dim lines
+    # Perpendicular band of these candidates. The 1-D carve projects obstacles onto the
+    # stacking axis only, so an obstacle on ANOTHER strip of this view — disjoint in the
+    # perpendicular axis, never actually touching — would falsely block (e.g. the overall
+    # width dim below the view blocking a slot-width dim on the right strip). Filter such
+    # obstacles out first. The perpendicular extent is independent of the tier position,
+    # so a single probe build per candidate suffices; the corridor check below already
+    # uses the full 2-D box, so it needs no such filter.
+    pbands = [
+        (b[perp], b[perp + 2]) for _n, build in cands if (b := _geom_box(build(lo))) is not None
+    ]
+    occupied = strip_obstacles(dwg, view=view, crossable=CROSSABLE_TYPES)
+    if pbands:
+        band_lo, band_hi = min(p[0] for p in pbands), max(p[1] for p in pbands)
+        occupied = [b for b in occupied if b[perp] < band_hi and b[perp + 2] > band_lo]
+    blockers = () if force else corridor_blockers(dwg, view)
+    segs = carve_free_segments(lo, hi, [(b[idx], b[idx + 2]) for b in occupied], pad)
+    # Fill innermost-first (nearest the view), matching the old cursor's stack order.
+    segs.sort(key=lambda s: abs((s[0] if inner == lo else s[1]) - inner))
+    todo = list(cands)
+    for seg_lo, seg_hi in segs:
+        if not todo:
+            break
+        cap = int((seg_hi - seg_lo) / pad) + 1
+        take, todo = todo[:cap], todo[cap:]
+        nat = seg_lo if inner == lo else seg_hi
+        anch = (0.0, nat) if axis == "y" else (nat, 0.0)
+        # Keys order the tiers so the FIRST candidate lands on the inner tier: for an
+        # inner=lo strip that is the lowest position (ascending keys); for a below strip
+        # (inner=hi) it is the highest, so the keys reverse.
+        triples = [
+            (
+                StripCandidate(
+                    f"{(k if inner == lo else len(take) - 1 - k):04d}", anch, (tier, tier)
+                ),
+                nb,
+            )
+            for k, nb in enumerate(take)
+        ]
+        res = plan_strip([sc for sc, _ in triples], seg_lo, seg_hi, pad, axis=axis)
+        for sc, (name, build) in triples:
+            pos = res.placed.get(sc.key)
+            if pos is None:  # segment over its estimated capacity (shouldn't occur)
+                todo.append((name, build))
+                continue
+            dim = build(pos)
+            if not force and _box_hits(_geom_box(dim), blockers):  # corridor crosses a leader
+                todo.append((name, build))
+                continue
+            dwg.add(dim, name, view=view)
+    return todo
+
+
+def carve_free_position(dwg, strip, view, axis, tier, perp_span, *, outermost=False):
+    """The single free tier POSITION on *strip* at which a dim of height *tier* spanning
+    *perp_span* ``(lo, hi)`` on the perpendicular axis clears every placed obstacle in
+    *view* — the innermost (nearest the view) tier by default, or the outermost fitting
+    one when *outermost*. Returns the dim-line page coord, or None if the strip is full.
+
+    The position-returning counterpart of :func:`place_strip_candidates` (which batches,
+    builds and adds): a caller that needs a dim's assigned position BEFORE building the
+    next — the height-ladder leapfrog chain, where each step dim's witness base is the
+    previous dim's line — uses this. Same carve: outer-label tier reservation, the
+    perpendicular-band filter (*perp_span* drops obstacles disjoint from this dim's own
+    perpendicular extent), and innermost-first fill.
+
+    **No corridor check, by construction — not just omission.** This avoids obstacle
+    *tiers* on the strip but does not reject a position whose witness *corridor* (feature
+    → dim line, across *perp_span*) crosses a leader/callout. Crucially, a single-position
+    return *cannot* fix a corridor crossing by choosing a different tier: every tier on
+    one side shares that corridor, and a farther tier's corridor is a **superset** of a
+    nearer one's, so the innermost free tier this already returns has the shortest
+    corridor and the fewest crossings — moving outward only adds crossings. Corridor
+    avoidance is therefore inherently a **relocation** problem (reject this position →
+    place on another view/side), which is :func:`place_strip_candidates`' job and out of
+    scope for a position return. Per caller: the height-ladder chain has no alternate
+    view (correct to omit); public ``Drawing.place_dim`` takes the view AND side from the
+    caller, so it cannot relocate; the PMI dim helpers already fall through sides
+    (``_try_above(...) or _try_below(...)``) and are where a corridor-reject would go if
+    ever wanted. Left as a documented known-limitation — the crossing is unobserved on
+    the corpus (the cleanliness ratchet would catch it)."""
+    if strip is None:
+        return None
+    lo, hi, inner = strip_free_span(strip)
+    idx = 1 if axis == "y" else 0
+    perp = 0 if axis == "y" else 1
+    pad = tier + strip.spacing
+    band_lo, band_hi = perp_span
+    occ = [
+        b
+        for b in strip_obstacles(dwg, view=view, crossable=CROSSABLE_TYPES)
+        if b[perp] < band_hi and b[perp + 2] > band_lo
+    ]
+    segs = carve_free_segments(lo, hi, [(b[idx], b[idx + 2]) for b in occ], pad)
+    # A segment holds the dim iff it is at least `tier` wide (the label height). This IS
+    # the outer-label reservation — inclusive at the boundary (a strip exactly `gap+tier`
+    # wide fits one dim, as the old `allocate` did) — so it must NOT be combined with a
+    # separate `hi -= tier` pull-in, which would double-reserve and drop that dim.
+    fitting = [s for s in segs if s[1] - s[0] >= tier - 1e-9]
+    if not fitting:
+        return None
+    if inner == lo:  # inner edge = seg lo; outermost = the segment reaching furthest out
+        seg = max(fitting, key=lambda s: s[1]) if outermost else min(fitting, key=lambda s: s[0])
+        return seg[0]
+    seg = min(fitting, key=lambda s: s[0]) if outermost else max(fitting, key=lambda s: s[1])
+    return seg[1]