draftwright 0.1.10__tar.gz → 0.1.12__tar.gz

{draftwright-0.1.10 → draftwright-0.1.12}/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## Unreleased
+
+## v0.1.12 — 2026-06-21
+
+### Changed
+
+- **Requires `build123d-drafting-helpers>=0.12.0`** (#92, #122). draftwright now
+  consumes the new sub-clustered hole-pattern recognition, the
+  `feature_diameters()` coverage inventory, the persistent `view_edge_cache`,
+  and the `ViewCoordinates.from_viewport()` ISO projection basis.
+- **Grouped hole-pattern callouts** (#92, #111, #114). A recognised perimeter,
+  grid, or bolt circle collapses to a single `n× ⌀ …` callout plus its pattern
+  dimensions instead of a balloon on every hole. A spec group now sub-clusters
+  into multiple patterns (a perimeter → its edge `LinearArray` rows, a filled
+  lattice → one `RectGrid` with a `(rows×cols)` callout and both pitch
+  dimensions); only genuinely unpatterned holes fall back to the per-hole table.
+  On NIST CTC-02 the table shrinks from 61 rows to the unpatterned remainder.
+- **Layout overhaul — compose-then-pack** (#121, #112, ADR 0004). Each view owns
+  the annotations created against it, and the resulting view blocks are packed
+  disjoint with automatic page/scale escalation. This eliminates cross-view
+  overlap — most visibly, plan-view balloons landing on front-view dimensions.
+- **Drawing attribution** (#120). The title block records the author, the SVG
+  and PDF carry a clickable draftwright hyperlink, and a "generated by
+  draftwright" note is written to the SVG/DXF/PDF file metadata.
+- **Gap between wrapped hole-table column blocks** (#123) so a chart that wraps
+  into several blocks reads as distinct columns.
+
+### Fixed
+
+- **Plan-view top balloon ring no longer floats over a phantom corridor** (#125).
+  The hole-table escalation deletes the X-location dimensions but left their
+  stale depth in the strip cursor, so the top balloons were parked far above the
+  view. The ring is now sized to the real dimension stack, so the top-side
+  leaders are short like the other three sides.
+- **No more phantom `feature_not_dimensioned` warnings** on slot-ends and shallow
+  recesses, via the helpers 0.12.0 `feature_diameters()` coverage inventory
+  (#92).
+
+### Internal
+
+- `AnnoBox` box-model footprint foundation and the four-side balloon ring placed
+  in a reserved view halo (#111, #112); the title block is pinned as a
+  first-class layout block (#112).
+
+## v0.1.11 — 2026-06-19
+
+### Changed
+
+- **Feature-coverage lint is assembly-aware.** A general-arrangement drawing of
+  a multi-solid part deliberately omits each part's bores (they belong on detail
+  sheets), so `feature_not_dimensioned` / `feature_count_mismatch` are now
+  emitted at `info` rather than `warning` when the part is multi-solid — out of
+  the warning count and quality score, but still queryable. Auto-detected;
+  override with `build_drawing(..., assembly=True/False)` or
+  `lint_feature_coverage(..., assembly=...)` (#69).
+
+### Fixed
+
+- **`place_dim` now labels the real-world length, not the page distance**, at
+  non-1:1 scale. Previously a dimension placed at a scale other than 1:1 showed
+  the on-page millimetre span instead of the true model dimension (#104).
+
+### Internal
+
+- **`make_drawing.py` decomposed (#98).** The per-view projection math and the
+  analysis namespace were deduplicated and typed (the namespace is now a frozen
+  `Analysis` dataclass), and the annotation passes were extracted into a new
+  `draftwright.annotate` module on top of a shared `draftwright._core`. The
+  module graph is a DAG (`layout → _core → {make_drawing, annotate}`) and
+  `make_drawing.py` shrank from ~5,270 to ~2,930 lines. No public API or
+  behaviour change.
+
 ## v0.1.10 — 2026-06-18
 
 ### Added
@@ -31,6 +103,20 @@
 - Hole-callout and turned-diameter placement is deconflicted through the shared
   `LayoutSolver` instead of ad-hoc per-pass logic (no output change).
 
+### Fixed
+
+- **Exact circles recovered for revolution silhouettes.** `project_to_viewport`'s
+  HLR returns the on-axis silhouette of a turned feature (or a concentric
+  gear-tooth-tip arc) as an approximating spline, not a true circle — splines in
+  the DXF where CAM expects `CIRCLE`/`ARC`, and fitted rather than exact radii.
+  `add_view` now refits any silhouette whose samples are equidistant from a
+  recognised revolution axis back to an exact circle/arc (#67).
+- **Blind-hole depth no longer measured across solid boundaries.** On a
+  multi-solid assembly, coaxial bores in different bodies were merged into one
+  hole, reporting a depth spanning the inter-body gap (the ⌀9.8 ↓111.4 symptom).
+  Fixed upstream in `build123d-drafting-helpers` 0.10.1; the dependency pin is
+  bumped to `>=0.10.1` to pick it up (#68).
+
 ### Docs
 
 - The skill and generated-script header now lead with the domain API

{draftwright-0.1.10 → draftwright-0.1.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.1.10
+Version: 0.1.12
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -679,8 +679,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.10
-Requires-Dist: build123d-drafting-helpers>=0.10.1
+Requires-Python: <3.15,>=3.10
+Requires-Dist: build123d-drafting-helpers>=0.12.0
 Requires-Dist: build123d>=0.9.0
 Requires-Dist: kiwisolver<2,>=1.4
 Requires-Dist: numpy>=1.24
@@ -809,30 +809,15 @@ generation, the lint→repair loop, and the constraint-based layout engine).
 
 ## Architecture
 
-draftwright is a single module (`make_drawing.py`) on top of two Apache 2.0 libraries:
+draftwright is a single module (`make_drawing.py`) on top of two libraries:
 
 ```
-draftwright  (AGPL-3.0)
-    └── build123d-drafting-helpers  (Apache 2.0)  — Dimension, Leader, HoleCallout, …
-    └── build123d  (Apache 2.0)                   — CAD kernel
+draftwright
+    └── build123d-drafting-helpers  — Dimension, Leader, HoleCallout, …
+    └── build123d                   — CAD kernel
 ```
 
 The engine handles view layout (strip/zone model), scale selection, feature recognition
 (holes, bosses, bolt circles), annotation placement, and section view generation.
 Annotation primitives (`Dimension`, `Leader`, `lint_drawing`, etc.) live in
 `build123d-drafting-helpers` and can be used independently.
-
-## License
-
-draftwright is licensed under the **GNU Affero General Public License v3 (AGPL-3.0)**.
-
-This means:
-- You can use, modify, and distribute it freely in open-source projects
-- If you run draftwright as part of a **network service** (e.g. an API that generates
-  drawings), you must make your application's source code available to users
-
-For commercial use without these obligations, contact pzfreo@gmail.com.
-
-The annotation primitives in
-[`build123d-drafting-helpers`](https://github.com/pzfreo/build123d-drafting-helpers)
-are Apache 2.0 and may be embedded in commercial applications without restriction.

{draftwright-0.1.10 → draftwright-0.1.12}/README.md

@@ -119,30 +119,15 @@ generation, the lint→repair loop, and the constraint-based layout engine).
 
 ## Architecture
 
-draftwright is a single module (`make_drawing.py`) on top of two Apache 2.0 libraries:
+draftwright is a single module (`make_drawing.py`) on top of two libraries:
 
 ```
-draftwright  (AGPL-3.0)
-    └── build123d-drafting-helpers  (Apache 2.0)  — Dimension, Leader, HoleCallout, …
-    └── build123d  (Apache 2.0)                   — CAD kernel
+draftwright
+    └── build123d-drafting-helpers  — Dimension, Leader, HoleCallout, …
+    └── build123d                   — CAD kernel
 ```
 
 The engine handles view layout (strip/zone model), scale selection, feature recognition
 (holes, bosses, bolt circles), annotation placement, and section view generation.
 Annotation primitives (`Dimension`, `Leader`, `lint_drawing`, etc.) live in
 `build123d-drafting-helpers` and can be used independently.
-
-## License
-
-draftwright is licensed under the **GNU Affero General Public License v3 (AGPL-3.0)**.
-
-This means:
-- You can use, modify, and distribute it freely in open-source projects
-- If you run draftwright as part of a **network service** (e.g. an API that generates
-  drawings), you must make your application's source code available to users
-
-For commercial use without these obligations, contact pzfreo@gmail.com.
-
-The annotation primitives in
-[`build123d-drafting-helpers`](https://github.com/pzfreo/build123d-drafting-helpers)
-are Apache 2.0 and may be embedded in commercial applications without restriction.

{draftwright-0.1.10 → draftwright-0.1.12}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "draftwright"
-version = "0.1.10"
+version = "0.1.12"
 description = "Automated technical-drawing generation for build123d"
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "Paul Fremantle", email = "pzfreo@gmail.com" }]
-requires-python = ">=3.10"
+requires-python = ">=3.10,<3.15"
 dependencies = [
     "build123d>=0.9.0",
-    "build123d-drafting-helpers>=0.10.1",
+    "build123d-drafting-helpers>=0.12.0",
     "kiwisolver>=1.4,<2",
     "numpy>=1.24",
 ]

draftwright-0.1.12/src/draftwright/_core.py

@@ -0,0 +1,461 @@
+"""Shared low-level primitives for the draftwright drawing engine.
+
+This module sits below :mod:`draftwright.make_drawing` and
+:mod:`draftwright.annotate`: it holds the data structures and small helpers
+both layers depend on (the :class:`Analysis` namespace and its field types,
+the dimension/format helpers, and the layout constants).  It imports only from
+:mod:`draftwright.layout` and third-party libraries -- never from
+``make_drawing`` -- so the module graph stays a DAG (#98 Phase C).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import SimpleNamespace
+
+from build123d import BoundBox, Location, Shape
+from build123d_drafting.helpers import (
+    _TB_COL_FRACTIONS,  # private: title-block column widths — tight coupling, see CLAUDE.md
+    Dimension,
+    TitleBlock,
+    draft_preset,
+    format_drawing_scale,
+)
+
+from draftwright.layout import _greedy_strip_1d, _solve_strip_1d
+
+_log = logging.getLogger(__name__)
+
+
+_MARGIN = 10.0
+
+
+_TB_CLEAR = _MARGIN + 1.0  # title-block inset: one extra mm over _MARGIN for clearance
+
+
+_FONT_SIZE = 3.0  # annotation text height (page-mm); the draft preset is built with this
+
+
+_TB_H = 35.0
+
+
+def _fmt(v: float) -> str:
+    """Format a float as integer string if whole, otherwise 1 dp."""
+    r = round(v)
+    return str(r) if abs(v - r) < 1e-6 else f"{v:.1f}"
+
+
+def _tag_sequence(n):
+    """``A, B, …, Z, AA, AB, …`` — deterministic hole-table tags for *n* rows."""
+    tags = []
+    for i in range(n):
+        s, k = "", i
+        while True:
+            s = chr(ord("A") + k % 26) + s
+            k = k // 26 - 1
+            if k < 0:
+                break
+        tags.append(s)
+    return tags
+
+
+_DIAM_RE = re.compile(r"[øØ⌀]\s*(\d+(?:\.\d+)?)")
+
+
+def _axis_letter(obj) -> str:
+    """Letter (``"x"``/``"y"``/``"z"``) of ``obj.axis``'s dominant component.
+
+    ``obj`` is anything carrying an ``.axis`` 3-vector (a hole or a boss).
+    """
+    return max(zip("xyz", obj.axis, strict=True), key=lambda t: abs(t[1]))[0]
+
+
+_CONCENTRIC_TOL_MM = 0.5
+
+
+def _dim(p1, p2, side, distance, draft, **kwargs):
+    """Build a :class:`Dimension`, tagged with its placement spec.
+
+    Identical to constructing ``Dimension`` directly, but records ``p1``,
+    ``p2``, ``side``, ``distance`` and the label kwargs on the result as
+    ``_dw_spec`` so the #30 repair loop can re-place the dimension (flip the
+    side, widen the offset) without re-deriving any geometry. Only dimensions
+    built this way are re-placeable by :meth:`Drawing.repair`.
+    """
+    d = Dimension(p1, p2, side, distance, draft, **kwargs)
+    d._dw_spec = SimpleNamespace(
+        p1=p1, p2=p2, side=side, distance=abs(distance), draft=draft, kwargs=kwargs
+    )
+    return d
+
+
+@dataclass
+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.
+
+    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).
+        gap:         Clearance between the view edge and the first annotation.
+        spacing:     Clearance between successive annotations.
+    """
+
+    anchor: float
+    outer_limit: float
+    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:
+    """The four annotation strips surrounding one orthographic view.
+
+    The ``right``/``above``/``below`` strips are always present for the three
+    orthographic views; only ``left`` can be ``None`` (a side view's left strip
+    abuts the front view, so it has no usable space).
+    """
+
+    right: Strip
+    above: Strip
+    below: Strip
+    left: Strip | None = None
+
+
+_PAD = draft_preset(font_size=_FONT_SIZE, decimal_precision=1).pad_around_text
+
+
+_SLOT_DIM_WIDTH = 2 * _FONT_SIZE + _PAD  # pv_zones.below: overall width dimension
+
+
+_SLOT_DIM_DEPTH = 2 * _FONT_SIZE + _PAD  # sv_zones.below: overall depth dimension
+
+
+_SLOT_DIM_HEIGHT = 2 * _FONT_SIZE + 2 * _PAD  # fv_zones.right: overall height dim
+
+
+_SLOT_DIM_STEP = 4 * _FONT_SIZE + _PAD  # fv_zones.right: step-height dimension
+
+
+_TABULATE_MIN_HOLES = 16
+
+
+_MIN_STEP_DIM_MM = (
+    _FONT_SIZE
+    + 2 * draft_preset(font_size=_FONT_SIZE, decimal_precision=1).arrow_length
+    + 2 * draft_preset(font_size=_FONT_SIZE, decimal_precision=1).pad_around_text
+)
+
+
+_MIN_STEP_SEP_MM = _FONT_SIZE + 2 * _PAD
+
+
+_MIN_LOC_SEP_MM = draft_preset(font_size=_FONT_SIZE, decimal_precision=1).arrow_length + _PAD
+
+
+def _legible_steps(step_zs, bb_min_z, scale):
+    """Step heights worth dimensioning at *scale*, and how many were too close.
+
+    A step is dimensioned only if it is tall enough from the base to carry a
+    label *and* at least ``_MIN_STEP_SEP_MM`` (page-mm) above the previously
+    kept step — consecutive shoulders closer than that are page-coincident and
+    cannot be told apart (#41). Returns ``(kept_zs, n_too_close)``: the heights
+    to dimension, and the count of tall-enough steps dropped for spacing (the
+    caller surfaces these via lint; the full-fidelity answer is a detail view,
+    #42). Steps too short to carry a label at all are silently omitted — they
+    are simply not dimensionable, not dropped.
+    """
+    kept: list[float] = []
+    n_too_close = 0
+    last = None
+    for z in sorted(step_zs):
+        if (z - bb_min_z) * scale < _MIN_STEP_DIM_MM:
+            continue
+        if last is not None and (z - last) * scale < _MIN_STEP_SEP_MM:
+            n_too_close += 1
+            continue
+        kept.append(z)
+        last = z
+    return kept, n_too_close
+
+
+def _largest_empty_rect(drawable, obstacles):
+    """Largest axis-aligned empty rectangle in *drawable* avoiding *obstacles*.
+
+    *drawable* and each obstacle are ``(x0, y0, x1, y1)`` page-mm boxes.  Returns
+    the empty sub-rectangle of *drawable* (overlapping no obstacle) that maximises
+    the side of the largest square it can hold — i.e. ``min(width, height)`` — so
+    the (near-square) iso view can be scaled up as far as possible.
+
+    The obstacle set is tiny (front/plan/side views + title block), so a
+    gap-based search over candidate edges is both exact enough and cheap: every
+    maximal empty rectangle has edges drawn from the drawable bounds and the
+    obstacle bounds, so enumerating those cut lines finds the optimum.
+    """
+    dx0, dy0, dx1, dy1 = drawable
+    xs = sorted({dx0, dx1, *(c for o in obstacles for c in (o[0], o[2]) if dx0 < c < dx1)})
+    ys = sorted({dy0, dy1, *(c for o in obstacles for c in (o[1], o[3]) if dy0 < c < dy1)})
+
+    best = None
+    best_score = 0.0
+    for i in range(len(xs) - 1):
+        for j in range(i + 1, len(xs)):
+            rx0, rx1 = xs[i], xs[j]
+            for k in range(len(ys) - 1):
+                for m in range(k + 1, len(ys)):
+                    ry0, ry1 = ys[k], ys[m]
+                    if any(
+                        rx0 < o[2] and o[0] < rx1 and ry0 < o[3] and o[1] < ry1 for o in obstacles
+                    ):
+                        continue
+                    score = min(rx1 - rx0, ry1 - ry0)
+                    if score > best_score:
+                        best_score = score
+                        best = (rx0, ry0, rx1, ry1)
+    if best is None:
+        # No empty rectangle exists (obstacles cover the drawable area). This
+        # is unreachable in practice — choose_scale always leaves a gap — but
+        # if it ever happens the iso would render over the other views, so flag
+        # it rather than fail silently.
+        _log.warning(
+            "No empty rectangle found for the iso view; obstacles fill the "
+            "drawable area — iso may overlap other views"
+        )
+        return drawable
+    return best
+
+
+@dataclass(frozen=True)
+class _Projector:
+    """Model → page coordinate projection for the orthographic views.
+
+    Each in-plane view axis projects as ``origin + (value - centroid) * scale``.
+    Built once in :func:`_analyse` and hung off the analysis namespace as
+    ``a.proj`` so the annotation passes share one projector instead of each
+    re-deriving the ``FX``/``FZ``/``SX``/``SZ``/``PX``/``PY`` closures.
+
+    This deliberately mirrors those analysis-phase closures byte-for-byte (an
+    unsigned ``+1`` projection), so the consolidation is provably
+    behaviour-preserving. The helpers library's ``ViewCoordinates.px``/``.py``
+    (already built per view as ``dwg._coords``) computes a *signed* projection
+    from ``view_axes()``; routing through it would couple the annotation passes
+    to render-order ``_coords`` population and could change output where a view
+    axis projects with a negative sign. Unifying onto ``ViewCoordinates`` is
+    therefore tracked as separate follow-up work, not part of this dedup.
+
+    Convention at call sites: bind a short local alias (``FX = a.proj.front_x``)
+    when a function projects repeatedly through its body; call ``a.proj.*()``
+    directly for one-off projections.
+    """
+
+    fv_x: float
+    fv_y: float
+    sv_x: float
+    sv_y: float
+    pv_x: float
+    pv_y: float
+    cx: float
+    cy: float
+    cz: float
+    scale: float
+
+    def front_x(self, x: float) -> float:
+        return self.fv_x + (x - self.cx) * self.scale
+
+    def front_z(self, z: float) -> float:
+        return self.fv_y + (z - self.cz) * self.scale
+
+    def side_x(self, y: float) -> float:
+        return self.sv_x + (y - self.cy) * self.scale
+
+    def side_z(self, z: float) -> float:
+        return self.sv_y + (z - self.cz) * self.scale
+
+    def plan_x(self, x: float) -> float:
+        return self.pv_x + (x - self.cx) * self.scale
+
+    def plan_y(self, y: float) -> float:
+        return self.pv_y + (y - self.cy) * self.scale
+
+
+@dataclass(frozen=True)
+class Analysis:
+    """Typed geometry+layout analysis produced by :func:`_analyse`.
+
+    The single data structure threaded through the whole annotation layer
+    (exposed as ``dwg._analysis`` and passed to the passes as ``a``). It was a
+    ``SimpleNamespace`` — invisible to mypy; making it a frozen dataclass type-
+    checks every ``a.<field>`` access and documents the contract (#98).
+
+    Page-coordinate fields (``FV_X`` … ``SV_Y``, ``ISO_X``/``ISO_Y``, the
+    ``*_limit`` and half-extent fields) are in page mm; ``cx``/``cy``/``cz`` and
+    the size fields are world mm; ``SCALE`` is the page-per-world factor.
+    """
+
+    part: Shape
+    bb: BoundBox
+    x_size: float
+    y_size: float
+    z_size: float
+    cx: float
+    cy: float
+    cz: float
+    bbox_max: float
+    holes: list
+    patterns: list
+    z_diams: list[float]
+    cross_diams: list[float]
+    cyls: tuple[list, list]
+    od_diam: float | None
+    is_rotational: bool
+    step_zs: list[float]
+    sv_right: float
+    iso_right_limit: float
+    SCALE: float
+    PAGE_W: float
+    PAGE_H: float
+    TB_W: float
+    DIM_PAD: float
+    margin: float
+    x_offset: float
+    FV_X: float
+    FV_Y: float
+    PV_X: float
+    PV_Y: float
+    SV_X: float
+    SV_Y: float
+    proj: _Projector
+    ISO_X: float
+    ISO_Y: float
+    iso_left_limit: float
+    iso_bottom_limit: float
+    iso_top_limit: float
+    fv_hw: float
+    fv_hh: float
+    pv_hh: float
+    sv_hw: float
+    fv_zones: ViewZones
+    pv_zones: ViewZones
+    sv_zones: ViewZones
+    step_file: str | Path | Shape
+    title: str
+    number: str
+    tolerance: str
+    drawn_by: str
+    out: str
+    pmi: list
+    pmi_mode: str
+
+
+_greedy_strip_ys = _greedy_strip_1d
+
+
+_solve_strip_ys = _solve_strip_1d
+
+
+_DRAFTWRIGHT_URL = "https://github.com/pzfreo/draftwright"
+
+
+def _attribution_author(drawn_by: str | None) -> str:
+    """ISO 7200 "drawn by" value: the human author and draftwright, or just
+    draftwright when no author was supplied."""
+    author = (drawn_by or "").strip()
+    return f"{author} / draftwright" if author else "draftwright"
+
+
+def _add_title_block(dwg, a: Analysis):
+    """Add the title block annotation."""
+    tb = TitleBlock(
+        a.title,
+        a.number,
+        scale=format_drawing_scale(a.SCALE),
+        general_tolerance=a.tolerance,
+        designed_by=_attribution_author(a.drawn_by),
+        revision="A",
+        legal_owner="",
+        width=a.TB_W,
+        draft=dwg.draft,
+    )
+    # Drawn-by cell geometry, taken from the block itself rather than hardcoded,
+    # so the hyperlink rect tracks any upstream TitleBlock layout change: the
+    # two-row block's bottom row is half the block height, and the cell spans
+    # from the first column divider (_TB_COL_FRACTIONS[0]) to the right edge.
+    cell_h = tb.block_bbox["height"] / 2.0
+    tb = tb.locate(Location((a.PAGE_W - a.TB_W - _TB_CLEAR, _TB_CLEAR, 0)))
+    dwg.add(tb, "title_block")
+
+    # Record that cell's page-space rectangle so export() can place a clickable
+    # draftwright hyperlink over the "… / draftwright" author text. Keeps the
+    # block at its standard two rows — no extra height, no layout impact (a
+    # third row would squeeze the dense-part hole table).
+    bx = a.PAGE_W - a.TB_W - _TB_CLEAR
+    dwg._draftwright_link_rect = (
+        bx + _TB_COL_FRACTIONS[0] * a.TB_W,
+        _TB_CLEAR,
+        bx + a.TB_W,
+        _TB_CLEAR + cell_h,
+    )
+
+
+def _iso_bbox(dwg):
+    """(min_x, min_y, max_x, max_y) of the placed iso view, hidden lines included."""
+    return dwg.view_bounds("iso")