draftwright 0.4.9__tar.gz → 0.4.10__tar.gz

{draftwright-0.4.9 → draftwright-0.4.10}/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## v0.4.10 — 2026-08-22
+
+**A view-set-aware planning and turned-edge-treatment patch.** Authored view constraints now
+compile into an explicit resolved plan, automatic drawings fail closed when required content is
+lost, AP242 hole tolerances reach their semantic feature owners, and the exact
+`b123d-recognisers` 0.3.0 release supplies turned chamfer and fillet evidence through truthful
+profile-view callouts.
+
+### Added
+
+- `Sheet` can now author a complete or augmenting semantic view set with `authored_views()`,
+  `auto_views()`, `view()`, `section_view()`, `detail_view()`, and their `add_*` forms. Fluent
+  view handles declare relationships, alignment, scale, and whole-view pins without exposing
+  annotation coordinates; unsupported or infeasible constraints fail at their declaration
+  source instead of being silently relaxed. `sheet.view_constraints` exposes the immutable
+  request and `drawing.view_plan` the distinct resolved result (#1260).
+- Drawings now retain their resolved view topology, per-view requirement coverage, and
+  arrangement decision as inspectable values. The engine can build and semantically compare
+  alternative arrangements and requested view sets while keeping projection and page placement
+  derived from the same plan (#1130).
+
+### Changed
+
+- Dimension planning is now aware of the selected principal view set. Requirements supported by
+  another planned view are re-homed before projection; an unsupported set raises one aggregated
+  `ViewPlanIncomplete` naming every unmet requirement rather than failing late or producing a
+  plausible-looking drawing with missing dimensions (#1259).
+- Three sparse corpus drawings now use a `stacked-iso` arrangement and fit A4 instead of A3 at
+  the same scale, with identical annotations, labels, and build issues. An alternative may only
+  compact the scale already selected by the default arrangement and must survive a real compile
+  without semantic loss; otherwise the default is retained (#1130).
+- Updated the exact `b123d-recognisers` production lock from 0.2.9 to 0.3.0.
+  The immutable PyPI wheel/sdist hashes and capability-manifest digest `6645def94cbabaca7b9676fdb029b02e467266d1f020ea536e903b7d86b52685` are
+  recorded in `.github/recogniser-release.json`; focused compatibility evidence and the
+  normal consumer gates run on the generated PR.
+- Accepted the additive Chamfer and Fillet schema-2 recogniser contract alongside schema 1 for
+  the `b123d-recognisers` 0.3.0 cutover; all other record schemas remain fail-closed at version 1
+  (#1276).
+
+- Updated the exact `b123d-recognisers` production lock from 0.2.6 to 0.2.9.
+  The immutable PyPI wheel/sdist hashes and capability-manifest digest `805876905d548fd0ef1301e2cf24427a86d34bc2e592b8d2d0cb43db94e1d3bd` are
+  recorded in `.github/recogniser-release.json`; focused compatibility evidence and the
+  normal consumer gates run on the generated PR. The aggregate now inventories chamfers and
+  fillets on turned parts, and the fixed coaxial-post slot regression retires its downstream
+  strict xfail.
+
+### Fixed
+
+- Automatic builds now apply the same required-outcome gate as explicit-scale builds. A settled
+  drawing that lost required placement outcomes records `plan_incomplete`, reports an
+  `incomplete` scale decision, preserves measurement/hole/source provenance, and fails lint
+  rather than presenting a diagnostic drawing as complete (#1250).
+
+- Supported AP242 diameter tolerances now correlate with their canonical hole or pattern owner at
+  the completed IR boundary and round-trip through emitted `Sheet` declarations with source
+  provenance. Unmatched, ambiguous, conflicting, partial-pattern, and unsupported requirements
+  fail closed to provenance-preserving measured dimensions rather than being duplicated or lost
+  (#1116).
+
+- A declared step shoulder coincident with its datum is now pruned before rendering instead of
+  sending identical endpoints to the border-dimension helper and raising `ValueError`. Valid
+  siblings remain, while the omission is recorded in `Drawing.suppressions()` and reported as
+  `step_position_coincident_with_datum` (#924).
+
+- Turned chamfer and fillet leaders now read in a shaft profile view and land on their physical
+  edge-treatment sites instead of collapsing axial stations in the end view. Cylindrical
+  feature notes, knurl callouts, and surface finishes likewise derive a model-space surface
+  target rather than pointing at the shaft axis; all continue through the shared placement
+  solves, with X/Y/Z parity and declared Sheet round-trip (#1276).
+
+- Toroidal fillets returned for turned parts by the shared recognition inventory now lower into
+  the existing one-feature-per-round IR and render through the common leader solve. Equal radii
+  share one `n× R` callout carrying every physical fillet's measurement provenance, and emitted
+  Sheet programs preserve the full inventory without rescanning geometry (#1281).
+
+- Turned chamfers returned by the shared recognition inventory now lower into the same
+  one-feature-per-edge-treatment IR as prismatic chamfers. Equal specifications render as one
+  `n×` callout carrying every member's measurement provenance; different chamfer forms do not
+  collapse merely because their first legs match, and distinct tolerances split into truthful
+  requirements instead of being lost or applied to untoleranced siblings (#1254).
+
+- Recogniser dependency automation now starts a fresh `Unreleased` section when the previous
+  Draftwright release has finalized the changelog, so a published recogniser can enter through
+  the documented immutable update workflow instead of failing before it opens a PR (#1279).
+
 ## v0.4.9 — 2026-08-21
 
 ### Added

{draftwright-0.4.9 → draftwright-0.4.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: draftwright
-Version: 0.4.9
+Version: 0.4.10
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -684,7 +684,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: <3.15,>=3.10
 Requires-Dist: antlr4-python3-runtime<4.10
-Requires-Dist: b123d-recognisers==0.2.6
+Requires-Dist: b123d-recognisers==0.3.0
 Requires-Dist: build123d-drafting-helpers>=0.14.1
 Requires-Dist: build123d<0.11,>=0.9.0; python_full_version < '3.13'
 Requires-Dist: build123d<0.12,>=0.11; python_full_version >= '3.13'

{draftwright-0.4.9 → draftwright-0.4.10}/docs/adr/README.md

@@ -34,7 +34,7 @@ architecture** table; open retired or superseded records only for design history
 | [0015](0015-part-drawing-compiler-as-built.md) | The part-drawing compiler, as built | Use one detected-or-declared feature IR and planner-fed dimension groups as the compiler waist. | Accepted; supersedes 0008 | `test_part_model.py`, `test_detect_once.py`, `test_import_boundaries.py` |
 | [0016](0016-declared-dimensioning-intent.md) | Declared dimensioning intent: capture what to measure, let the engine place it | Declare which measurements matter as scale-independent intent routed through the planner and corridor solve; never hardcode dimension geometry. | Accepted; epic #867 complete; phase 6 landed (#940) | `test_compiled_plan_boundary.py`, `test_issue_1215_no_approved_tolerance_is_dropped.py`, `test_label_provenance.py`, `test_sheet_emit.py`, `test_add_dimension.py` |
 | [0017](0017-recognition-inventory-correspondence-and-measurement-provenance.md) | One recognition result per run; correspondence is evidence-gated | Produce one external immutable recognition result held by Draftwright's per-run cache; require vertical-slice evidence before generalising correspondence, identity, requirements, outcomes, or reconciliation. | Accepted; external cache ownership clarified, extensions gated by #1018 | `test_external_recognition_boundary.py`, `test_recognition_manifest.py`, `test_declared_recognition_gate.py` |
-| [0018](0018-requirement-driven-view-planning-and-editable-sheet-layout.md) | Requirement-driven view planning and editable sheet layout | Use one `ViewSpec` vocabulary and planner with distinct authored `ViewConstraints` and immutable `ResolvedViewPlan`; jointly validate views, typography, convention, scale, paper and layout against requirement survival. Supersedes ADR 0004's fixed-topology assumption while retaining compose-then-pack. | Accepted 2026-08-16 (nothing implemented yet); tracked by #1130 | Required guards are listed in the ADR |
+| [0018](0018-requirement-driven-view-planning-and-editable-sheet-layout.md) | Requirement-driven view planning and editable sheet layout | Use one `ViewSpec` vocabulary and planner with distinct authored `ViewConstraints` and immutable `ResolvedViewPlan`; jointly validate views, typography, convention, scale, paper and layout against requirement survival. Supersedes ADR 0004's fixed-topology assumption while retaining compose-then-pack. | Accepted 2026-08-16; partially implemented (`ViewSpec`, `ResolvedViewPlan`, `ViewCoverage`, arrangement choice and requirement gate); tracked by #1130/#1259-#1262 | Required guards are listed in the ADR |
 | [0019](0019-display-complete-labels-and-dimension-outcomes.md) | Display-complete labels and a dimension-outcome ledger | The compiled plan carries the full label text (tolerance and collapse wording included) so renderers render and never compose; dimension outcomes reconcile at one seam on both build routes; ladder rungs get per-mark identity. Finishes the ADR 0016 Amdt 1 boundary; supersedes Amdt 6's enforcement mechanism. | Proposed | `test_issue_1215_no_approved_tolerance_is_dropped.py` reduces to plan-equality when implemented |
 
 ## Historical records

{draftwright-0.4.9 → draftwright-0.4.10}/docs/reference/recogniser-capabilities.md

@@ -26,7 +26,9 @@ Validation fails closed and names the family and boundary whenever possible:
   CI instead — adoption is still required, and is enforced where the decision is made. Provide the
   downstream behavior or an explicit non-supported state as before.
 - **record schema mismatch** — a consumed record schema changed. Review the record fields and
-  compatibility notes, update the relevant adapter and tests, then pin the accepted schema version.
+  compatibility notes, update the relevant adapter and tests, then explicitly list the accepted
+  schema version. A bounded dual-readable list may name the current and next additive schemas
+  during a provider-first release; it is never an open-ended range.
 - **stale implementation** — a declared adapter, `Sheet` method, emitter, renderer, or completeness
   function no longer resolves. Repair the implementation reference and its independent behavior
   evidence; do not merely rename the string.
@@ -47,12 +49,19 @@ Validation fails closed and names the family and boundary whenever possible:
 
 ## Adding or changing a recogniser
 
-Land the package record, independent geometry evidence, manifest update, and compatible package
-release first. Then update Draftwright against that immutable release. For each applicable stage,
-add the adapter, declaration, emitted-Sheet round trip, drawing behavior, and completeness evidence;
-for an inapplicable or deferred stage, state why and link its tracking issue. The contract test
-derives package record outputs, converter registries, live `Sheet` methods, and emitter branches
-independently, so copying a new name into the declaration alone cannot make CI pass.
+For an additive field that increments an existing record schema, first land a narrow Draftwright
+declaration accepting both the installed schema and the named candidate schema. The existing adapter
+must remain valid when the new field is ignored, and tests must prove the next schema is accepted
+only by that explicit declaration while later schemas still fail. The package canary then proves
+the real candidate wheel against that committed consumer point. After the package release, the
+Draftwright dependency/behavior PR locks the immutable artifact, adopts the field, and narrows the
+declaration to the new schema.
+
+For each applicable stage, add the adapter, declaration, emitted-Sheet round trip, drawing behavior,
+and completeness evidence; for an inapplicable or deferred stage, state why and link its tracking
+issue. The contract test derives package record outputs, converter registries, live `Sheet` methods,
+and emitter branches independently, so copying a new name into the declaration alone cannot make CI
+pass.
 
 `bosses` is the fully consumed reference family. `repeating-radial-profiles` is the opposite
 reference: it remains geometry-only critique evidence for a separately authored gear declaration,

draftwright-0.4.10/docs/reference/sheet.md

@@ -0,0 +1,71 @@
+# Sheet and fluent handles
+
+`Sheet` is the declared authoring façade. Feature verbs return fluent handles; those handles
+are documented here because they are part of normal use even though their Python names begin
+with an underscore.
+
+## Sheet
+
+::: draftwright.sheet.Sheet
+    options:
+      filters: public
+
+### Authored views and layout
+
+View declarations are semantic constraints. They name projections, relationships and whole-view
+anchors; the layout solve owns the resulting page positions. Authored views must be paired with
+authored dimensions so a deliberately omitted view cannot strand planner-selected annotations:
+
+```python
+s = Sheet(part).authored_dimensions().authored_views()
+front = s.view("front")
+plan = s.view("plan").above(front, gap=4).align_x(front)
+s.view("iso").scale(0.75)
+
+section = s.section_view("A", through=hole)
+detail = s.detail_view("B", around=hole).scale(2)
+dwg = s.build()
+```
+
+`view(...)`, `section_view(...)` and `detail_view(...)` define complete authored sets;
+omission suppresses a view. `add_view(...)`, `add_section_view(...)` and
+`add_detail_view(...)` augment an explicitly selected `auto_views()` source. `row(...)` and
+`column(...)` are shorthand for whole-view relations. A principal-view handle's `pin((x, y))`
+anchors its projection origin in page millimetres; it never positions an annotation.
+
+Principal orthographic views share the sheet scale and reject `.scale(...)`. Detail and
+isometric handles may carry an independent positive factor. Infeasible relations, scales and
+pins raise with their declaration source; unsupported pins on derived or pictorial views are
+refused at declaration and constraints are never silently relaxed. The immutable authored
+snapshot is available as `sheet.view_constraints`, while `drawing.view_plan` is the distinct
+resolved result.
+
+## View handle
+
+::: draftwright.sheet._View
+    options:
+      filters: public
+
+## Hole handle
+
+::: draftwright.sheet._Hole
+    options:
+      filters: public
+
+## Diameter and step handle
+
+::: draftwright.sheet._Dim
+    options:
+      filters: public
+
+## Multi-parameter handle
+
+::: draftwright.sheet._Params
+    options:
+      filters: public
+
+## GD&T control builder
+
+::: draftwright.sheet._Control
+    options:
+      filters: public

{draftwright-0.4.9 → draftwright-0.4.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.4.9"
+version = "0.4.10"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -18,7 +18,7 @@ dependencies = [
     "build123d>=0.9.0,<0.11 ; python_full_version < '3.13'",
     "build123d>=0.11,<0.12 ; python_full_version >= '3.13'",
     "build123d-drafting-helpers>=0.14.1",
-    "b123d-recognisers==0.2.6",
+    "b123d-recognisers==0.3.0",
     "numpy>=1.24",
     # PNG raster export (SVG→PDF→PNG). Both permissively licensed (Pillow HPND; pypdfium2
     # Apache-2.0 wrapping Google PDFium BSD-3) and ship pre-built wheels with NO native system

{draftwright-0.4.9 → draftwright-0.4.10}/src/draftwright/__init__.py

@@ -36,6 +36,9 @@ _LAZY = {
     "extract_pmi": "draftwright.pmi",
     "extract_pmi_report": "draftwright.pmi",
     "choose_scale": "draftwright.compose",
+    "ViewPlanIncomplete": "draftwright.view_plan",
+    "ViewConstraints": "draftwright.view_plan",
+    "ViewSpec": "draftwright.view_plan",
     # A warning category users are told to filter must be importable without reaching into a
     # private module (#1043 review) — and without paying for the CAD kernel. It lives in the
     # dependency-free `_warnings` leaf for that second reason: defined in `_core` it cost ~6 s
@@ -91,6 +94,7 @@ if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel co
         extract_pmi_report,
     )
     from draftwright.sheet import Sheet
+    from draftwright.view_plan import ViewConstraints, ViewPlanIncomplete, ViewSpec
 
 
 def __dir__():
@@ -110,6 +114,9 @@ __all__ = [
     "Sheet",
     "ScaleIncompatibilityError",
     "ScaleCompletenessWarning",
+    "ViewPlanIncomplete",
+    "ViewConstraints",
+    "ViewSpec",
     "build_drawing",
     "choose_scale",
     "extract_pmi",

{draftwright-0.4.9 → draftwright-0.4.10}/src/draftwright/_core.py

@@ -42,7 +42,14 @@ from build123d_drafting.helpers import (
 # now live in the leaf `draftwright._geometry` so the IR waist (`model/`) can use them
 # without importing this stage-level grab-bag (ADR 0008; #584 WP2). Re-exported here for
 # the above-`_core` consumers (annotations/sheet/drawing/linting) that already import them.
-from draftwright._geometry import _END_ON, HoleRef, _axis_letter, _fmt, _xyz  # noqa: F401
+from draftwright._geometry import (  # noqa: F401
+    _EDGE_ON,
+    _END_ON,
+    HoleRef,
+    _axis_letter,
+    _fmt,
+    _xyz,
+)
 from draftwright.fits import FitClass
 from draftwright.fonts import PLEX_MONO, PLEX_SANS_CONDENSED
 from draftwright.layout import _greedy_strip_1d, _solve_strip_1d
@@ -804,8 +811,8 @@ class DetailRequest:
                       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``.
-        source_view:  orthographic direction to preserve in the detail (``"front"``
-                      or ``"side"``). The latter is used for Y-turned axial profiles.
+        source_view:  orthographic direction to preserve in the detail (``"front"``,
+                      ``"plan"`` or ``"side"``).
         crop_lo/crop_hi: optional crop bounds along ``axis`` when the projected
                       detail must include context outside the marked feature band.
                       Prismatic absolute-height details use this to retain their
@@ -823,13 +830,23 @@ class DetailRequest:
     redraw: Callable[..., int]
     pad_top: float = 0.0
     pads: Callable[[float], tuple[float, float]] | None = None
-    source_view: Literal["front", "side"] = "front"
+    source_view: Literal["front", "plan", "side"] = "front"
     crop_lo: float | None = None
     crop_hi: float | None = None
     cross_axis: Literal["x", "y", "z"] | None = None
     cross_lo: float | None = None
     cross_hi: float | None = None
     kind: str = "detail"
+    #: Authored detail identity/label. ``None`` lets the automatic resolver assign A-H.
+    view_name: str | None = None
+    label: str | None = None
+    #: Exact authored multiple of sheet scale; automatic requests keep ``None`` and use the
+    #: legibility-derived preferred series.
+    scale_factor: float | None = None
+    #: An authored orientation crop is defining geometry even when it carries no redrawn
+    #: dimension. Automatic recovery details retain the historical "no dimension, no view" gate.
+    keep_without_annotations: bool = False
+    source: object | None = None
 
 
 @dataclass(frozen=True)
@@ -1021,7 +1038,7 @@ class Analysis:
     step_zs: list[float]
     layout_strips: StripDepths
     layout_n_steps: int
-    layout_section: bool
+    layout_section: int
     layout_table_sizes: tuple[tuple[float, float], ...]
     layout_required_tables: tuple[tuple[tuple[float, float], str], ...]
     sv_right: float
@@ -1090,6 +1107,28 @@ class Analysis:
     # declared a model (ADR 0011) or on a manually-built Analysis — consumers fall
     # back to build_model(a).
     model: object | None = None
+    #: The relational arrangement the sheet was composed under — ADR 0018 §5's fourth
+    #: dimension, decided once by `compose.choose_scale` and carried here so that placement
+    #: and the repack loop compose under the arrangement whose feasibility was actually
+    #: established. They call `_layout_geometry` with MEASURED strip depths where selection
+    #: passed estimates, so a stage that re-derives this instead of reading it can reach a
+    #: different answer for the same sheet and lose dimensions to the mismatch (#1130).
+    #: Defaulted for hand-built `Analysis` objects, which mean the long-standing arrangement.
+    arrangement: str = "columns"
+    #: The principal views this sheet carries, or None for the third-angle three (ADR 0018).
+    #: Decided once alongside scale/page/arrangement and carried, for the same reason: the
+    #: layout must reserve space for exactly the views the builder creates, or dropping one
+    #: costs its annotations without reclaiming its paper.
+    planned_views: tuple[str, ...] | None = None
+    #: Whether the orientation isometric participates in this authored plan. It is separate
+    #: from ``planned_views`` because that tuple is the principal set consumed by the
+    #: requirement compiler.
+    planned_iso: bool = True
+    #: ``None`` lets the orientation iso auto-fit; a number is an authored exact factor.
+    planned_iso_scale: float | None = None
+    #: Immutable ADR 0018 authored input, retained for the resolver/diagnostics without making
+    #: this low-level module depend on the view-planning leaf at runtime.
+    view_constraints: object | None = None
 
     @property
     def pmi(self) -> list:
@@ -1276,6 +1315,11 @@ def _add_zone_grid(dwg, a: Analysis):
 
 def _iso_bbox(dwg):
     """(min_x, min_y, max_x, max_y) of the placed iso view, hidden lines included."""
+    if "iso" not in dwg.views:
+        # A deliberately omitted orientation view contributes no obstacle. Infinity makes
+        # every existing iso-clearance comparison a no-op without teaching annotation passes
+        # a second page-edge convention.
+        return (math.inf, math.inf, math.inf, math.inf)
     return dwg.view_bounds("iso")
 
 

{draftwright-0.4.9 → draftwright-0.4.10}/src/draftwright/_geometry.py

@@ -15,13 +15,133 @@ import logging
 import math
 from dataclasses import dataclass
 
+from b123d_recognisers import full_cylinders
 from build123d import Compound
 
 _log = logging.getLogger(__name__)
 
-# Axis letter -> the orthographic view a feature on that axis reads end-on in.
+# Axis letter -> the orthographic view a feature on that axis reads end-on in: a z-hole is
+# a circle in plan, an x-channel is a cross-section in side.
+#
+# The ONE owner of that routing. It was duplicated as a bare literal at eight sites across
+# six modules, which is ADR 0018's own sentence about itself — "which views should exist is
+# a decision nothing currently owns" — in miniature: a mapping copied eight times cannot be
+# taught that a view is absent, and the engine's answer to a missing view was a `KeyError`
+# raised inside a centermark pass. Route through this, never re-spell it (#1130).
 _END_ON = {"x": "side", "y": "front", "z": "plan"}
 
+# Axis letter -> the orthographic view a planar face with that NORMAL shows as an edge in
+# (prefer front, else side). The companion routing to `_END_ON`, and its second owner: this
+# one was spelled out three times — the groove profile callouts, `declare._EDGE_ON_VIEW` and
+# `planner._PROFILE`, the last of which documented the duplication in a comment rather than
+# resolving it. Same reasoning as above: route through it, never re-spell it (#1130).
+_EDGE_ON = {"x": "front", "y": "side", "z": "front"}
+
+# Model axes retained by each orthographic projection.  Besides documenting the projection
+# convention once, this lets surface-bound annotations choose a radial direction that the
+# requested view can actually show (#1276).
+_VIEW_AXES = {"plan": ("x", "y"), "front": ("x", "z"), "side": ("y", "z")}
+
+
+def _radial_axis_in_view(axis: str, view: str) -> str:
+    """Return a principal radial axis visible in *view* for a shaft along *axis*.
+
+    Profile views contain the shaft axis and exactly one radial axis.  A caller may also
+    explicitly choose the face-on view, where both projected axes are radial; the first is a
+    deterministic, equally physical surface direction.
+    """
+    try:
+        return next(candidate for candidate in _VIEW_AXES[view] if candidate != axis)
+    except (KeyError, StopIteration) as e:
+        raise ValueError(f"no radial axis for shaft axis {axis!r} in view {view!r}") from e
+
+
+def _canonical_profile_site(site, centre, axis: str, view: str) -> tuple[float, float, float]:
+    """Rotate a turned surface *site* about its shaft onto the selected profile plane.
+
+    Conical and toroidal recognisers may return any circumferential point on the same physical
+    edge treatment.  Orthographic projection can discard that point's sole radial component
+    (notably an X-offset site viewed in the Y-Z side view).  Preserve its axial station and
+    radial distance while rotating it to the radial axis visible in *view*.
+    """
+    values = [float(value) for value in site]
+    centre_values = [float(value) for value in centre]
+    axis_i = "xyz".index(axis)
+    radial = [i for i in (0, 1, 2) if i != axis_i]
+    visible_i = "xyz".index(_radial_axis_in_view(axis, view))
+    if visible_i not in radial:
+        raise ValueError(f"view {view!r} is not a profile view of axis {axis!r}")
+    hidden_i = next(i for i in radial if i != visible_i)
+    visible_delta = values[visible_i] - centre_values[visible_i]
+    hidden_delta = values[hidden_i] - centre_values[hidden_i]
+    radius = math.hypot(visible_delta, hidden_delta)
+    direction = visible_delta if abs(visible_delta) > 1e-12 else hidden_delta
+    values[visible_i] = centre_values[visible_i] + math.copysign(radius, direction or 1.0)
+    values[hidden_i] = centre_values[hidden_i]
+    return (values[0], values[1], values[2])
+
+
+def _turned_profile_site(site, axis: str, view: str, cylinders) -> tuple[float, float, float]:
+    """Return *site* rotated onto *view* about its nearest external shaft axis.
+
+    A part may contain several parallel shafts, so the part bounding-box centre is not an
+    axis. Rank the shared cylinder substrate by the site's distance from each finite cylinder
+    patch (radial surface gap plus axial-span gap), then rotate about that cylinder's own
+    ``axis_xyz``.  The finite span matters for compounds: an unrelated cylinder at a remote
+    axial station can coincidentally have the exact radial distance (#1276 review).
+    When no matching external cylinder exists, preserve the physical site: inventing an axis
+    would be worse than retaining a possibly edge-on circumferential anchor.
+    """
+    values = (float(site[0]), float(site[1]), float(site[2]))
+    axis_i = "xyz".index(axis)
+    radial = tuple(i for i in (0, 1, 2) if i != axis_i)
+    candidates = []
+    # ``analyse_cylinders`` is deliberately a complete face inventory: longitudinal blends
+    # and slot caps are cylindrical too.  Only its public substrate filter proves which
+    # records collectively describe a shaft, including an OD split by a keyway/slot.
+    substrates = (full_cylinders(list(group)) for group in cylinders)
+    for cylinder in (item for group in substrates for item in group):
+        if not cylinder.get("external") or cylinder.get("axis") != axis:
+            continue
+        centre = tuple(float(value) for value in cylinder["axis_xyz"])
+        radial_distance = math.hypot(
+            values[radial[0]] - centre[radial[0]],
+            values[radial[1]] - centre[radial[1]],
+        )
+        surface_gap = abs(radial_distance - float(cylinder["diameter"]) / 2)
+        direction = tuple(float(value) for value in cylinder["dir_xyz"])
+        axial_station = sum(value * component for value, component in zip(values, direction))
+        s_lo = float(cylinder["s_lo"])
+        s_hi = float(cylinder["s_hi"])
+        axial_gap = max(s_lo - axial_station, 0.0, axial_station - s_hi)
+        patch_distance = math.hypot(surface_gap, axial_gap)
+        # A complete cylinder elsewhere in a compound is not evidence for this feature.  If
+        # the recogniser's physical point is more than one radius from the finite patch, keep
+        # that point rather than rotating it around an invented remote axis.  This also keeps
+        # a chamfer on a partial OD (for example a D-shaft) safe when ``full_cylinders`` quite
+        # correctly declines to call the partial wall a complete shaft substrate.
+        radius = float(cylinder["diameter"]) / 2
+        if patch_distance > radius:
+            continue
+        candidates.append(
+            (
+                (
+                    patch_distance,
+                    axial_gap,
+                    surface_gap,
+                    radial_distance,
+                    int(cylinder["solid_idx"]),
+                    centre[radial[0]],
+                    centre[radial[1]],
+                ),
+                centre,
+            )
+        )
+    if not candidates:
+        return values
+    _score, centre = min(candidates, key=lambda candidate: candidate[0])
+    return _canonical_profile_site(values, centre, axis, view)
+
 
 def _xyz(loc) -> tuple[float, float, float]:
     """A build123d ``Vector`` (has ``.X/.Y/.Z``) or an ``(x, y, z)`` sequence → an