draftwright 0.2.0__tar.gz → 0.2.2__tar.gz

{draftwright-0.2.0 → draftwright-0.2.2}/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 ## Unreleased
 
+## v0.2.2 — 2026-06-30
+
+A patch release of turned-part dimension-placement fixes and a CLI start-up
+speed-up. Drawing output changes for the affected turned/cross-drilled parts.
+
+### Fixed
+
+- **A coaxial bore callout on a *stepped* turned shaft is now lifted off the round
+  view's centre axis** (#305). The earlier fix only triggered for a uniform
+  (`is_rotational`) cylinder; a stepped shaft (e.g. the gramel GRM-03 drive screw)
+  has a turned step profile but isn't classified rotational, so its `⌀… ↓…` bore
+  callout was still leadered straight along the centreline, with the centre mark
+  running through the text. The lift now also fires for a turned-profile part.
+- **A side-drilled hole's location dimension now stacks *inside* the overall
+  envelope dimension** (ISO order — overall dim outermost, feature/location dims
+  nearer the view). It was placed *outside* the envelope, which forced the shorter
+  location dim's arrowheads to flip outward and clash (seen on GRM-01 and GRM-02).
+  The mandatory overall dimension is still guaranteed placement.
+
+### Changed
+
+- **CLI shell completion and `--help` are fast again** (#313). The Typer CLI and
+  the heavy CAD engine are now imported lazily, so tab-completion and `--help` no
+  longer pay a ~6 s engine-import cost; a real drawing run is unaffected.
+
+## v0.2.1 — 2026-06-30
+
+A patch release focused on **turned-part dimensioning legibility**: crowded
+step-length chains and fine turned heads are now drawn legibly instead of crammed.
+Drawing output changes for affected turned parts.
+
+### Added
+
+- **Automatic enlarged detail view for a crowded turned head** (#304). A turned
+  part with a fine cluster of steps near one end and a long shaft (e.g. a thumbwheel
+  drive screw) cannot have its head dimensioned legibly in line at any sensible
+  scale. The head is now located as one block on the main view and broken out into
+  an enlarged **DETAIL A — SCALE n:1** — the textbook treatment — firing
+  automatically when a head's shoulders fall below the page legibility floor.
+
+### Changed
+
+- **Crowded turned step-length chains stagger across two tiers** (#293) instead of
+  cramming or being skipped. When the labels would collide on one line, the ISO
+  129-1 staggered convention alternates them between a near and a far tier so every
+  step length stays legible at the drawing's own scale — no rescale needed. A roomy
+  chain stays on a single tier.
+- **Detail views are now one unified pipeline** (#307). The prismatic step-height
+  detail and the new turned-head detail flow through a single
+  detect → request → render path; several crowded regions become DETAIL A/B/…
+- **Output changes** for turned parts whose step chains were previously crammed, or
+  whose fine heads are now broken out into a detail view.
+
+### Fixed
+
+- **A coaxial bore callout no longer overlaps the round view's centreline** (#305):
+  its leader is angled off the centre axis so the callout text sits in clear space.
+
+### Internal
+
+- A new **layout-cleanliness invariant test** asserts that finished drawings have no
+  view/annotation collisions across representative part archetypes, and the
+  measure-and-repack pass gained a trigger for an annotation growing into a
+  neighbouring view's line-work (so the views spread to make room).
+
 ## v0.2.0 — 2026-06-30
 
 A major release. draftwright took ownership of feature recognition and linting

{draftwright-0.2.0 → draftwright-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.2.0
+Version: 0.2.2
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright

{draftwright-0.2.0 → draftwright-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.2.0"
+version = "0.2.2"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }

draftwright-0.2.2/src/draftwright/__init__.py

@@ -0,0 +1,103 @@
+"""draftwright — automated technical-drawing generation for build123d.
+
+Takes a build123d solid and produces a fully-annotated multi-view technical
+drawing (orthographic views, dimensions, section A–A, title block) ready for
+DXF/SVG export::
+
+    from draftwright import make_drawing
+    make_drawing(my_part, out="drawing")
+
+Requires build123d-drafting-helpers for annotation primitives.
+Licensed under the GNU Affero General Public License v3 (AGPL-3.0).
+"""
+
+import importlib as _importlib
+import sys as _sys
+import types as _types
+from typing import TYPE_CHECKING
+
+# Public API resolved lazily (PEP 562): `import draftwright` — and, crucially,
+# `import draftwright.cli` (which runs this __init__ first) — must NOT eagerly
+# pull in the engine. The engine drags build123d/OCP, ~5 s of CAD-kernel import.
+# The CLI's shell completion, --help and --version import this package but touch
+# none of these names, so they stay sub-second instead of paying for the kernel
+# on every TAB press (#313). Each name maps to the submodule that provides it.
+_LAZY = {
+    "analyse_face_levels": "draftwright.analysis",
+    "dedup_diams": "draftwright.analysis",
+    "build_drawing": "draftwright.builder",
+    "generate_script": "draftwright.builder",
+    "make_drawing": "draftwright.builder",
+    "Drawing": "draftwright.drawing",
+    "FeatureInfo": "draftwright.drawing",
+    "fix_svg_page_size": "draftwright.export",
+    "lint_feature_coverage": "draftwright.linting",
+    "PmiRecord": "draftwright.pmi",
+    "extract_pmi": "draftwright.pmi",
+    "choose_scale": "draftwright.sheet",
+}
+
+
+def _resolve(name):
+    """Import the providing submodule and cache the public object on the package."""
+    value = getattr(_importlib.import_module(_LAZY[name]), name)
+    _types.ModuleType.__setattr__(_sys.modules[__name__], name, value)
+    return value
+
+
+class _DraftwrightModule(_types.ModuleType):
+    def __getattr__(self, name):
+        # PEP 562 miss handler: resolve a public name on first access.
+        if name in _LAZY:
+            return _resolve(name)
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    def __getattribute__(self, name):
+        # `draftwright.make_drawing` must be the FUNCTION even after the compat
+        # SUBMODULE of the same name is imported and shadows it as a package
+        # attribute (importing draftwright.make_drawing binds the module here).
+        if name == "make_drawing":
+            namespace = _types.ModuleType.__getattribute__(self, "__dict__")
+            value = namespace.get("make_drawing")
+            if (
+                isinstance(value, _types.ModuleType)
+                and value.__name__ == "draftwright.make_drawing"
+            ):
+                return _resolve("make_drawing")
+        return _types.ModuleType.__getattribute__(self, name)
+
+
+_sys.modules[__name__].__class__ = _DraftwrightModule
+
+
+if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel cost
+    from draftwright.analysis import analyse_face_levels, dedup_diams
+    from draftwright.builder import build_drawing, generate_script, make_drawing
+    from draftwright.drawing import Drawing, FeatureInfo
+    from draftwright.export import fix_svg_page_size
+    from draftwright.linting import lint_feature_coverage
+    from draftwright.pmi import PmiRecord, extract_pmi
+    from draftwright.sheet import choose_scale
+
+
+def __dir__():
+    # Surface the lazy public names (not in __dict__ until first accessed)
+    # *alongside* the normal module contents — dunders, imported submodules — so
+    # introspection / REPL completion sees the full surface, not a subset.
+    return sorted(set(globals()) | set(__all__))
+
+
+__all__ = [
+    "Drawing",
+    "FeatureInfo",
+    "PmiRecord",
+    "analyse_face_levels",
+    "build_drawing",
+    "choose_scale",
+    "dedup_diams",
+    "extract_pmi",
+    "fix_svg_page_size",
+    "generate_script",
+    "lint_feature_coverage",
+    "make_drawing",
+]

{draftwright-0.2.0 → draftwright-0.2.2}/src/draftwright/_core.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import functools
 import logging
 import re
+from collections.abc import Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 from types import SimpleNamespace
@@ -382,6 +383,48 @@ def _largest_empty_rect(drawable, obstacles):
     return best
 
 
+@dataclass
+class DetailRequest:
+    """A renderer's request for an enlarged detail of a region it could not draw
+    legibly at sheet scale (#307). Renderers append these to ``dwg._detail_requests``
+    instead of building bespoke detail views; ``_resolve_details`` resolves them all
+    through one generic detailer (crop → project → place → caption → marker), then
+    calls ``redraw`` to draw the feature's own dims inside the placed detail view.
+
+    The single ``detect → request → generic render`` path that folds the prismatic
+    step detail (#42) and the turned-head detail (#304) into one, mirroring the
+    section pipeline (``plan_sections``/``SectionPlan``).
+
+    Fields:
+        axis:         part axis the band spans / is cropped along ("x"/"y"/"z").
+        lo, hi:       band bounds along ``axis`` (world mm).
+        scale_needed: detail world→page scale that makes the region legible.
+        redraw:       ``redraw(dwg, view_name, detail_scale) -> int`` — draws the
+                      detail's dimensions in the placed detail view's coordinate system
+                      and returns the count placed (0 → the detailer rolls the view
+                      back rather than leave an empty box). Called once the detail is
+                      placed; the main view always carries the located head/block
+                      inline regardless, so a placement failure loses no coverage (lint
+                      reports the un-located interior instead).
+        pad_top:      page-mm band reserved above the detail view (a horizontal
+                      chain); reserved in the fit + placement.
+        pads:         optional ``pads(detail_scale) -> (pad_right, pad_top)`` for a
+                      footprint that depends on the chosen scale (the prismatic
+                      ladder reserves one rung per *legible-at-that-scale* step, so it
+                      shrinks with the scale during the fit). Overrides ``pad_top``.
+        kind:         short label for logging.
+    """
+
+    axis: str
+    lo: float
+    hi: float
+    scale_needed: float
+    redraw: Callable[..., int]
+    pad_top: float = 0.0
+    pads: Callable[[float], tuple[float, float]] | None = None
+    kind: str = "detail"
+
+
 @dataclass(frozen=True)
 class _Projector:
     """Model → page coordinate projection for the orthographic views.

{draftwright-0.2.0 → draftwright-0.2.2}/src/draftwright/annotations/from_model.py

@@ -27,10 +27,12 @@ from draftwright._core import (
     _DIAM_RE,
     _END_ON,
     _MARGIN,
+    _MIN_STEP_SEP_MM,
     _SLOT_DIM_DEPTH,
     _SLOT_DIM_HEIGHT,
     _SLOT_DIM_STEP,
     _SLOT_DIM_WIDTH,
+    DetailRequest,
     _dim,
     _fmt,
     _greedy_strip_ys,
@@ -530,6 +532,20 @@ def _env_pd(group, role):
     return next((pd for pd in group.dims if pd.param.role == role), None)
 
 
+def envelope_group(groups):
+    """The envelope `DimensionGroup` in *groups*, or None."""
+    return next((g for g in groups if g.feature_kind == "envelope"), None)
+
+
+def env_dim_placed(pd) -> bool:
+    """Whether :func:`render_envelope` will actually place an envelope dim for the
+    PlannedDimension *pd* — present, not suppressed by the planner (square footprint /
+    X-turned, #250), and carrying a span. The single source of truth for that
+    decision, shared with the orchestrator's side-below tier reservation so the two
+    can never drift (#316 review)."""
+    return pd is not None and not pd.suppressed and pd.param.span is not None
+
+
 def render_envelope(dwg, groups, a) -> int:
     """Overall width (plan, below) + depth (side, below) envelope dims via the IR,
     placed through the engine's below-strip zone allocators (the zone-aware render
@@ -537,12 +553,12 @@ def render_envelope(dwg, groups, a) -> int:
     those strips). The **planner** decides suppression (square footprint / X-turned;
     #250); this renderer just skips suppressed dims and places the rest. Returns the
     count placed."""
-    env = next((g for g in groups if g.feature_kind == "envelope"), None)
+    env = envelope_group(groups)
     if env is None:
         return 0
     n = 0
     width = _env_pd(env, "width")
-    if width is not None and not width.suppressed and width.param.span is not None:
+    if env_dim_placed(width):
         (x0, y0, z0), (x1, _, _) = width.param.span
         p1, p2 = dwg.at("plan", x0, y0, z0), dwg.at("plan", x1, y0, z0)
         witness = p1[1] - 2
@@ -562,7 +578,7 @@ def render_envelope(dwg, groups, a) -> int:
             )
             n += 1
     depth = _env_pd(env, "depth")
-    if depth is not None and not depth.suppressed and depth.param.span is not None:
+    if env_dim_placed(depth):
         (x0, y0, z0), (_, y1, _) = depth.param.span
         p1, p2 = dwg.at("side", x0, y0, z0), dwg.at("side", x0, y1, z0)
         witness = p1[1] - 2
@@ -584,52 +600,30 @@ def render_envelope(dwg, groups, a) -> int:
     return n
 
 
-def render_step_lengths(dwg, groups) -> int:
-    """Unified turned step-length chain (ADR 0008 #223) — one IR-driven path that
-    replaces the engine's asymmetric X-chain / Z-ladder. Each `StepFeature`'s length
-    span is projected into the front view; the chain runs *along the projected axis*
-    just outside the view — **horizontal** for an X-turned part, **vertical** for a
-    Z-turned part. Orientation is the projected span direction, not a branch, so X
-    and Z get the same complete chain. Returns the number of step dims placed.
-
-    The chain is collinear (all segments share one offset line) and tiles end to
-    end, so every shoulder is located. Crowded labels are spread along the line by
-    the ADR-0003 strip solve (the primitive the engine's X chain already used)."""
-    segs = []  # (page_lo, page_hi, value), in axis order
-    for g in groups:
-        if g.feature_kind != "step":
-            continue
-        length = next(
-            (pd.param for pd in g.dims if pd.param.kind == "length" and pd.param.span is not None),
-            None,
-        )
-        if length is None or length.span is None:
-            continue
-        a, b = length.span
-        pa, pb = dwg.at("front", *a), dwg.at("front", *b)
-        segs.append((pa, pb, length.value))
+def _draw_step_chain(dwg, view, segs, name_prefix, detail_scale=None, allow_collapse=True) -> int:
+    """Place a turned step-length chain in *view* from *segs* — each ``(pa, pb,
+    value)`` already projected to *view*'s page coords, in axis order. Orientation is
+    data (the projected span direction): horizontal → chain above the view, vertical
+    → chain to the right. A uniform run collapses to one ``N× v`` dim (#230); else a
+    per-segment chain, staggered into a near/far tier only when crowded (ISO 129-1,
+    #293); skipped if even two tiers can't separate the labels, or if any dim would
+    fall off the page. ``detail_scale`` tags the dims for label-vs-measured lint when
+    drawing inside a scaled detail view. ``allow_collapse=False`` disables the ``N× v``
+    collapse — used when the chain mixes a synthetic head-*block* with real steps, where
+    a uniform-staircase representative would be a false claim of N equal steps (#307
+    review). Returns the count placed."""
     if not segs:
         return 0
-    vb = dwg.view_bounds("front")
+    vb = dwg.view_bounds(view)
     if vb is None:
         return 0
     x0, y0, x1, y1 = vb
     draft = dwg.draft
     gap = draft.font_size + 4 * draft.pad_around_text
-    # Orientation is data: the projected span direction. Horizontal → X-turned
-    # (chain above the view); vertical → Z-turned (chain left of the view).
     horizontal = abs(segs[0][1][0] - segs[0][0][0]) >= abs(segs[0][1][1] - segs[0][0][1])
-
-    # Spread crowded labels along a horizontal chain (ADR-0003 strip solve), then
-    # carry each label back to its segment via label_offset_x (the only along-line
-    # offset the Dimension primitive supports). A vertical chain places plain dims.
-    # Uniform staircase → one representative "N× length" dim spanning the whole run
-    # (#230), instead of N identical segment dims. Mirrors the prismatic ladder's
-    # _detect_step_repeat: ≥3 segments, all within 10% of the mean (so a 2-step part
-    # or a mixed chain still dimensions each segment).
     vals = [v for *_, v in segs]
     mean_v = sum(vals) / len(vals)
-    if len(segs) >= 3 and (max(vals) - min(vals)) <= 0.10 * mean_v:
+    if allow_collapse and len(segs) >= 3 and (max(vals) - min(vals)) <= 0.10 * mean_v:
         label = f"{len(segs)}× {_fmt(mean_v)}"
         xs = [p[0] for pa, pb, _ in segs for p in (pa, pb)]
         ys = [p[1] for pa, pb, _ in segs for p in (pa, pb)]
@@ -637,48 +631,47 @@ def render_step_lengths(dwg, groups) -> int:
             dim = _dim((min(xs), y1, 0), (max(xs), y1, 0), "above", gap, draft, label=label)
         else:
             dim = _dim((x1, min(ys), 0), (x1, max(ys), 0), "right", gap, draft, label=label)
-        candidates = [("m_steplen_typ", dim)]
+        candidates = [(f"{name_prefix}_typ", dim)]
     else:
-        offsets = [0.0] * len(segs)
-        # Legibility guard (#293): a too-dense chain must SKIP, not overprint. Placing
-        # an unreadable wall of overlapping dims is worse than none — lint then reports
-        # axial_length_missing, and the user resolves it with a larger scale or a detail
-        # view. The room guard's sibling, for crowding rather than page overflow.
-        gap_min = draft.font_size + 2 * draft.pad_around_text
+        tier_step = draft.font_size + 2 * draft.pad_around_text
+        tiers = [0] * len(segs)
         if horizontal:
-            centers = [(pa[0] + pb[0]) / 2 for pa, pb, _ in segs]
-            half_w = max(len(_fmt(v)) for *_, v in segs) * draft.font_size * 0.62 / 2
-            min_gap = 2 * half_w + 2 * draft.pad_around_text
-            solved = _solve_strip_ys(
-                centers, min_gap, x0 + half_w, x1 - half_w
-            ) or _greedy_strip_ys(centers, min_gap, x0 + half_w, x1 - half_w)
-            placed = sorted(solved) if solved else sorted(centers)
-            if any(b - a < min_gap - 0.01 for a, b in zip(placed, placed[1:])):
-                _log.info("step-length chain skipped: %d labels too dense to space", len(segs))
+            cw = [
+                ((pa[0] + pb[0]) / 2, len(_fmt(v)) * draft.font_size * 0.62) for pa, pb, v in segs
+            ]
+
+            def _clear(items):  # (center, width) pairs in x order — labels don't overlap
+                return all(
+                    c2 - c1 >= (w1 + w2) / 2 + draft.pad_around_text
+                    for (c1, w1), (c2, w2) in zip(items, items[1:])
+                )
+
+            if _clear(cw):
+                pass  # one tier suffices — no needless zig-zag for a roomy chain
+            elif _clear(cw[0::2]) and _clear(cw[1::2]):
+                tiers = [i % 2 for i in range(len(segs))]  # alternate to make room
+            else:
+                _log.info("step-length chain skipped: too dense even when staggered")
                 return 0
-            if solved:
-                offsets = [s - c for s, c in zip(solved, centers)]
         else:
-            # Z-turned chain places plain dims at the shoulders (no along-line spread is
-            # available vertically), so its legibility is the raw shoulder spacing.
             shoulder_ys = sorted({c for pa, pb, _ in segs for c in (pa[1], pb[1])})
-            if any(b - a < gap_min for a, b in zip(shoulder_ys, shoulder_ys[1:])):
+            if any(b - a < tier_step for a, b in zip(shoulder_ys, shoulder_ys[1:])):
                 _log.info("step-length chain skipped: shoulders too close to dimension")
                 return 0
 
         candidates = []
         for i, (pa, pb, value) in enumerate(segs):
-            if horizontal:  # X-turned: chain above the view, witnesses rise from the top
+            if horizontal:
                 p1, p2, side = (pa[0], y1, 0), (pb[0], y1, 0), "above"
-                kw = {"label": _fmt(value), "label_offset_x": offsets[i]}
-            else:  # Z-turned: chain right of the view, witnesses from the right edge
+                dist = gap + tiers[i] * tier_step
+            else:
                 p1, p2, side = (x1, pa[1], 0), (x1, pb[1], 0), "right"
-                kw = {"label": _fmt(value)}
-            candidates.append((f"m_steplen{i}", _dim(p1, p2, side, gap, draft, **kw)))
+                dist = gap
+            candidates.append(
+                (f"{name_prefix}{i}", _dim(p1, p2, side, dist, draft, label=_fmt(value)))
+            )
 
-    # Room guard (the engine's contract): if any dim would fall off the drawable
-    # page, place NONE and let lint report axial_length_missing — never run the
-    # chain off the page edge.
+    # Room guard: if any dim would fall off the drawable page, place NONE.
     page = (_MARGIN, _MARGIN, dwg.page_w - _MARGIN, dwg.page_h - _MARGIN)
     for _, dim in candidates:
         box = _anno_box(dim)
@@ -687,10 +680,93 @@ def render_step_lengths(dwg, groups) -> int:
         ):
             return 0
     for name, dim in candidates:
-        dwg.add(dim, name, view="front")
+        if detail_scale is not None:
+            dim._dw_scale = detail_scale
+        dwg.add(dim, name, view=view)
     return len(candidates)
 
 
+def render_step_lengths(dwg, groups) -> int:
+    """Unified turned step-length chain (ADR 0008 #223): each `StepFeature`'s length
+    span projects into the front view and joins the chain that tiles the turning axis
+    so every shoulder is located. X-turned → horizontal chain above the view;
+    Z-turned → vertical chain to the right.
+
+    A crowded **X-turned head** — a contiguous run of steps too short to dimension
+    legibly even staggered (shoulders below the page arrowhead floor) — is not crammed
+    in line: the main view locates that run as one *block* dim and an enlarged
+    `DetailRequest` (#304/#307) is queued to break it down. If the detail later can't
+    place, the block still locates the head extent and lint reports the un-located
+    interior shoulders — never worse than the prior skip. Returns the count placed on
+    the front view."""
+    rows = []  # (a_world, b_world, value) in axis order
+    for g in groups:
+        if g.feature_kind != "step":
+            continue
+        length = next(
+            (pd.param for pd in g.dims if pd.param.kind == "length" and pd.param.span is not None),
+            None,
+        )
+        if length is None or length.span is None:
+            continue
+        rows.append((length.span[0], length.span[1], length.value))
+    if not rows:
+        return 0
+    draft = dwg.draft
+    fsegs = [(dwg.at("front", *a), dwg.at("front", *b), v) for a, b, v in rows]
+    horizontal = abs(fsegs[0][1][0] - fsegs[0][0][0]) >= abs(fsegs[0][1][1] - fsegs[0][0][1])
+
+    # X-turned crowded-head detour (#307): split off each contiguous *run of ≥2*
+    # sub-floor steps (segment narrower than two arrowheads on the page), locate it as
+    # a block, and queue an enlarged detail. A single isolated thin step is left in the
+    # main chain — a one-step block would just be that step at its sub-floor width
+    # (#307 review). The legible steps + blocks stay as the main chain.
+    if horizontal:
+        floor_pg = 2 * draft.arrow_length
+        sub = [i for i, (pa, pb, _) in enumerate(fsegs) if abs(pb[0] - pa[0]) < floor_pg]
+        runs: list[list[int]] = []
+        for j in sub:
+            (runs[-1].append(j) if runs and j == runs[-1][-1] + 1 else runs.append([j]))
+        heads = [run for run in runs if len(run) >= 2]
+        if heads:
+            blocks = []
+            for run in heads:
+                ra = [rows[i] for i in run]
+                hlo = min(min(a[0], b[0]) for a, b, _ in ra)
+                hhi = max(max(a[0], b[0]) for a, b, _ in ra)
+                minlen = min(v for *_, v in ra)
+                # World→page scale for the detail (no sheet factor — detail_scale is an
+                # absolute world→page scale). (#307 review)
+                scale_needed = _MIN_STEP_SEP_MM / minlen if minlen > 0 else float("inf")
+                blocks.append((dwg.at("front", hlo, 0, 0), dwg.at("front", hhi, 0, 0), hhi - hlo))
+
+                def _redraw(dwg, view, detail_scale, _hw=ra):
+                    # View-scoped name prefix so two detail views never collide (#307 review).
+                    hsegs = [(dwg.at(view, *a), dwg.at(view, *b), v) for a, b, v in _hw]
+                    return _draw_step_chain(dwg, view, hsegs, f"dim_{view}_steplen", detail_scale)
+
+                dwg._detail_requests.append(
+                    DetailRequest(
+                        axis="x",
+                        lo=hlo,
+                        hi=hhi,
+                        scale_needed=scale_needed,
+                        redraw=_redraw,
+                        pad_top=2 * (draft.font_size + 2 * draft.pad_around_text)
+                        + draft.arrow_length,
+                        kind="turned-head",
+                    )
+                )
+            head = {i for run in heads for i in run}
+            main = [fsegs[i] for i in range(len(fsegs)) if i not in head] + blocks
+            main.sort(key=lambda s: s[0][0])
+            # The chain now mixes head-block(s) with real steps — never collapse it to a
+            # uniform "N× v" representative (a block is not a repeated step, #307 review).
+            return _draw_step_chain(dwg, "front", main, "m_steplen", allow_collapse=False)
+
+    return _draw_step_chain(dwg, "front", fsegs, "m_steplen")
+
+
 def _detect_step_repeat(step_zs, bb_min_z, bb_max_z, tol_frac=0.10):
     """Return (n, rise) if *step_zs* form a uniform staircase, else None.