draftwright 0.3.2__tar.gz → 0.3.4__tar.gz

{draftwright-0.3.2 → draftwright-0.3.4}/CHANGELOG.md

@@ -1,5 +1,307 @@
 # Changelog
 
+## Unreleased
+
+## v0.3.4 — 2026-07-20
+
+### Changed
+
+- **Imperative `--script` output defaults to PDF and the modern export form**
+  (#709). **Breaking** for regenerated imperative scripts: without `-f`, a
+  regenerated script now writes `<stem>.pdf` (was SVG+DXF via the deprecated
+  legacy tuple), and the script-visible variables changed from
+  `svg_path, dxf_path` to a `paths` dict printed in the requested-format order.
+  This aligns the imperative flavour with the Sheet flavour and the direct CLI,
+  which have defaulted to PDF since #702/#288. Migration: regenerate with
+  `--format svg,dxf` to keep the old outputs. Previously-generated scripts are
+  unaffected (they carry their own export lines).
+- **`finalize()` drains in the auto-pass's order** (#699 slice b): both build
+  paths now execute the orchestrator's one canonical `_PASS_SEQUENCE` (via the
+  shared `run_stages`), removing the hand-mirrored second orchestration in
+  `Drawing._drain_intents`. For the deferred/finalize path this reorders three
+  things toward auto-pass parity: the turned diameter/step-length set-solves now
+  place *before* the corridor drain (matching the auto-pass's obstacle
+  visibility); slots register after them; and the register-only height-ladder /
+  step-position stages register *after* locations — observable too, since
+  registration order decides corridor key-creation (= drain) order and
+  same-priority tie-breaks (Codex review; the new order is exactly the
+  auto-pass's). Recompose output may shift accordingly; the auto-pass order is
+  unchanged.
+- **`Sheet.export` speaks the modern export API** (#702): it now takes
+  `formats=` (any of svg/dxf/pdf/png, default **PDF** — matching the CLI
+  default) and `dpi=`, and returns the `{format: path}` dict. Previously it
+  rode the deprecated legacy path, could only write SVG+DXF — the flagship
+  facade couldn't produce a PDF — and returned the old `(svg_path, dxf_path)`
+  tuple. **Breaking** for callers unpacking that tuple: use
+  `sheet.export(stem, formats=("svg", "dxf"))` and read the dict.
+
+### Added
+
+- **Solve-trace / explain mode** (#736, from the #733 post-mortem): opt-in
+  observability for strip placement. `build_drawing(trace=…)` or
+  `DRAFTWRIGHT_TRACE=<path-or-dir>` writes ONE JSON file per build (schema v2)
+  with two record types: `solves` — every corridor solve's key, strip bounds,
+  candidate set, the obstacles that carved the strip (with owning annotation
+  names), the free segments, and each candidate's outcome (placed /
+  dropped-with-reason / deduped / promoted / deferred-to-post-drain) — and
+  `pass_events` — the standalone strip passes plus the *immediate* placers
+  (post-drain machined-feature leader callouts, the turned diameter row/column
+  and step-length set-solves), each with per-item placed/dropped outcomes. So
+  "why did X drop" is one `jq` query (`.solves[].outcomes[]` /
+  `.pass_events[].items[]`). A `placement_unsatisfiable` strip-full drop now
+  also names the top occupants in its lint message (`…strip full; occupied
+  by: …`). Recording-only: an unwritable path logs a warning (never aborts a
+  build), writes are atomic, and the recorder joins `finalize()`'s #647
+  rollback. Default off; zero output change, nil cost when off.
+
+- **`draftwright.model.authored_dimension`** (#704): the IR constructor behind
+  `Sheet.dimension()`, extracted so `build_drawing(model=…)` callers can author
+  a pre-measured drafting dimension without the `Sheet` façade.
+
+### Added
+
+- **Object-reference script workflow: docs + an inline tip** (#770/#771): a
+  generated `Sheet` script from a **live-source** input (a `module:attr` /
+  `file.py:attr` object spec, or a build123d object) now carries an inline tip
+  showing how to swap each detected-numbers line for a reference to your object
+  (ADR 0011 declare — the size is read off the object). A STEP-sourced script is
+  unchanged (byte-stable — no object to reference). The README documents the full
+  from-a-part-to-an-object-referenced-script workflow.
+- **Knurl callout verb** (#765): `sheet.diameter(shaft).knurl("0.8")` →
+  `KNURL 0.8 STRAIGHT` (or `.knurl("0.8", "DIAMOND")`). Named sugar over
+  `.note()` with canonical formatting — a knurl is a text callout on a leader,
+  not modelled geometry, so it flows through the existing note path (no new
+  IR/render).
+- **Standing ISO 7200 title-block fields** (#766): `material`, `date`, `revision`,
+  and `company` (legal owner) are now first-class — settable on `build_drawing` /
+  `make_drawing`, the `Sheet(...)` constructor, and the CLI (`--material` /
+  `--date` / `--revision` / `--company`), and emitted into the generated `Sheet`
+  script when non-default so a re-run reproduces them. Defaults preserve the prior
+  output (revision `A`, the rest blank). The `revision`/`legal_owner` cells the
+  renderer previously hardcoded now flow from these. (The imperative `--script`
+  flavour's title-block round-trip of these fields is a follow-up.)
+- **First-class thread/tap callout on a hole** (#764): ``sheet.hole(...).thread("M3x0.5")``
+  (and ``declare.hole(..., thread=)``) folds a tap/thread spec onto the hole's existing
+  compound leader (e.g. ``ø2.5 THRU M3x0.5``) — a structured aspect that round-trips, so
+  ``.thread(...).finish(...)`` yields Ra-on-thread. A declaration-only aspect (ADR 0011
+  side-layer: threads are cosmetic, not modelled geometry — no recogniser). The layout
+  width estimator (``_est_planned_bore_callout_width``) now accounts for the thread text so
+  the wider callout is reserved room and not dropped (the #261 estimator/render agreement).
+
+### Fixed
+
+- **Generated imperative script reconstructs side-drilled hole locations**
+  (#426/#133): an X/Y-axis (side-drilled) bore gets `dim_loc_*` position dims in
+  the direct build, but the `--script` emitter emitted a gap comment instead of a
+  `locate()` for non-Z holes (because `locate()`/`render_locations` are Z-plan
+  only, #133). The emitter now emits `dwg.locate(f)` for holes on any axis;
+  `finalize()` routes by the feature's axis — Z-plan holes drain through
+  `render_locations` as before, side-drilled bores through the whole-model
+  `_locate_off_axis_holes` pass (registered at the auto-pass's own
+  `off_axis_across`/`off_axis_along` stages, placed at the shared drain). The
+  Z-only `locate()` live contract is untouched (side-drilled locates never reach
+  it — they route to the off-axis stages). Closes the last direct-vs-generated
+  script parity gap tracked by #426.
+- **Generated imperative script reconstructs rotational furniture** (#426/#424):
+  a turned/cylindrical part's `dwg.model()` carries a `RotationalFeature`, but the
+  `--script` emitter parked it in the gap-comment list, so an executed
+  reconstruction of e.g. a plain cylinder was missing `dim_od` and the
+  `centerline_front`/`centerline_side` marks the direct build draws. A new
+  `Drawing.rotational(feature)` add-verb records the intent, and `finalize()`
+  drains it through the shared whole-model `render_rotational` at the auto-pass's
+  own `"rotational"` stage — byte-identical to the direct build (no `only=` subset,
+  fixed literal names, so no naming-seam or `⊇`-vs-`==` gap). The emitter now emits
+  `dwg.rotational(f)` for rotational features. Closes the rotational half of the
+  direct-vs-generated-script convergence.
+- **Emitted `Sheet` script now faithfully reproduces the direct CLI drawing**
+  (#707): the divergence reported against 0.3.3 on the Maquetto GRM-03 part was
+  closed by #709 (script `--format` forwarding) + #661 (finalize detail drain).
+  Locked with a vendored-fixture regression that asserts the full invariant the
+  issue named — same views, annotation inventory, page, scale **and** lint
+  between `build_drawing(...)` and the executed emitted `Sheet` — not just the
+  annotation signature the synthetic parity cases check.
+- **`_largest_empty_rect` no longer blows up on crowded detail views** (#661):
+  the largest-empty-rectangle placer enumerated every candidate rectangle
+  (O(N⁴) in the coordinate-cut count) — fine for the iso view's handful of
+  obstacles, but the detail-view placer feeds it *every* placed-annotation
+  footprint, so a two-detail turned part reached ~70 obstacles and spent ~13 s
+  in a single call (multi-minute on the slower Windows CI runners, which tipped
+  some jobs over their wall-clock budget). It now skips candidates that provably
+  can't beat the best found so far (a `bisect` past every too-narrow pair, an
+  early `break` once even the widest is too small): the same exact result and
+  tie-break — verified identical to the naïve search across 3 000 random cases —
+  at ~85× the speed on the pathological input (12.6 s → 0.15 s).
+- **Detail-view height demotion is pin- and provenance-safe** (#661, user
+  review): when a crowded prismatic detail needs the overall-height dim's room it
+  is demoted and the detail retried, but (a) the canonical `dim_height` name was
+  handed to that retry unconditionally — a *pinned* or user-replaced height could
+  be removed; it now passes the same pin/label guards as the generalised
+  `dim_length{n}` path (a pin, ADR 0012, is never demoted), and (b) if the retry
+  also failed, the restore re-added only object/name/view, orphaning the dim from
+  its envelope feature (lost `annotations_of`/`drop`/re-discovery); it now
+  snapshots and restores the feature provenance and pin too.
+- **`finalize()` resolves queued detail requests — detail views now exist on the
+  edit path** (#661): the finalize drain was missing the auto pass's
+  `detail_request`/`details` stages, so a crowded turned head's queued
+  `DetailRequest` died with the per-run context and a prismatic
+  `detail_view=True` build never even queued one — generated scripts silently
+  lost every DETAIL A/B view. `build_drawing(detail_view=…)` is now persisted on
+  the build state so the drain gates the prismatic request exactly as the auto
+  pass does; the details stage re-projects the iso at sheet scale for the
+  free-rectangle search and refits it after (mirroring the auto pass's ordering,
+  where details place before the iso is fitted); and the overall-height demotion
+  retry now finds the height dim by its envelope attribution, not only the
+  auto-pass `dim_height` name. Three script-parity characterisation tests
+  (single detail, two details, turned head) flip from xfail to passing.
+- **Y-turned stepped shafts no longer crash** (#661): `render_step_lengths`
+  projected every step span into the front view, where a Y-axis span is end-on
+  (a point) — `Dimension` then raised "start and end points must be different"
+  on BOTH the direct build and a generated script's finalize. Y-axis steps are
+  now skipped (no step render pipeline consumes Y, #731 — mirroring
+  `render_diameters`' x/z bucketing), the emitter flags the gap as a comment
+  instead of emitting an unreplayable `dimension()` verb, and a hand-written
+  Y step-length intent live-replays (surfacing the verb's own behaviour) rather
+  than vanishing into the routed no-op. The Y-axis script-parity
+  characterisation test flips from xfail to passing.
+- **Boss heights are modeled, rendered, and coverage-checked** (#632): detected
+  and object-declared cylindrical bosses now carry their axial extent through
+  `BossFeature` and the dimension planner. Prismatic bosses receive a linear
+  height dimension in a profile view in addition to their end-on diameter
+  leader. `Drawing.lint()` reconciles that modeled height against the live
+  feature-owned `Dimension`, reporting `boss_height_missing` if it is removed
+  or otherwise absent (demoted to `info` on assembly drawings). This closes the
+  declarative false-negative where a boss's diameter and the overall envelope
+  were documented but its own independent height was not.
+
+- **`--format` now reaches `--script` output** (#709, from the #702 adversarial
+  review): `--script -f svg` used to silently emit a PDF-producing script — the
+  CLI parsed the flag but never forwarded it. Both emitters now thread it
+  through: the Sheet script emits `sheet.export(stem, formats=(…,))` when
+  non-default (bare call for the PDF default), the imperative template embeds
+  the requested tuple and prints in the **requested** order, and
+  `generate_script` / `generate_sheet_script` grow a `formats=` parameter. The
+  dormant script-parity characterisation module
+  (`test_script_detail_parity.py`) is also un-skipped so its strict xfails give
+  the remaining gaps CI signal.
+
+- **Authored fillet, flat, groove, pocket, plate and slot tolerances now render**
+  (#725/#726/#727/#728/#729/#730 / #698): the four leader-callout kinds join
+  `_CONVENTION` and their renderers (`render_fillets`/`render_flats`/
+  `render_grooves`/`render_pockets`) — and the plate-thickness and slot
+  width/length linear passes
+  (`render_plates`/`render_slots`, explicit `"linear"` entries) — consume the
+  planner's `DimensionGroup`s, binding each
+  planned dim explicitly by `(role, kind)` — so a `decorations`-authored ± /
+  limit tolerance reaches the placed callout (`R8 ±0.1`, `17 ±0.2 A/F`,
+  `4 ±0.1 WIDE × ø16 ±0.5`, `18 ±0.2 × 30 ±0.2 × 5 ±0.2 DEEP`, a `10 ±0.1`
+  thickness dim, an `8 ±0.1` slot width; on a
+  multi-value label each suffix rides its own number). Previously all six
+  passes formatted raw feature fields and silently dropped it — the latent #629
+  bug class the ADR 0015 bypass list documents. The fillet `n× R` and flat
+  double-D/hex collapses stay render-side (first-authored tolerance wins, the
+  `render_diameters` precedent); a pocket's three values — and a slot's
+  width + length — share one authored
+  tolerance (all kind `"length"`). The slot's model-derived datum position dim
+  and its corridor/immediate placement mechanics are untouched. Untolerated
+  labels/views/placement are unchanged.
+- **Authored chamfer tolerances now render** (#724 / #698): `render_chamfers`
+  consumes the planner's `DimensionGroup` (chamfer joins `_CONVENTION` as a
+  leader), so a `decorations`-authored ± / limit tolerance on a chamfer leg
+  reaches the placed callout (`C12 ±0.2`). Previously the pass formatted raw
+  feature fields and silently dropped it — the latent #629 bug class the ADR
+  0015 bypass list documents. Untolerated chamfer labels/views are unchanged.
+- **`model.chamfer(face=…)` rejects a non-planar face** (#704): the declared
+  front-end silently accepted a curved face (`normal_at()` does not fail on
+  one) and read garbage legs off it — e.g. a fillet or countersink face became
+  a bogus `ChamferFeature`. It now raises the documented `ValueError`, using
+  the recogniser's own planarity gate (`classify_bevel`), so declared and
+  detected chamfers classify identically by construction.
+
+### Fixed
+
+- **CTC-02/04 no longer drop step-height / overall-height dims** (#733): when
+  the height ladder joined the corridor solve (#689) it silently moved from
+  "places early" to "registers early, places at the drain" — so the immediate
+  machined-feature leader callouts (pockets on CTC-04) filled the front-right
+  strip first and the FORCED principal dims hard-dropped
+  (`placement_unsatisfiable`), a priority inversion the old stage ordering had
+  prevented implicitly. The leader-callout stages (chamfers/fillets/flats/
+  pockets) now sit **after the corridor drain** in `_PASS_SEQUENCE` (joining
+  grooves, which already placed post-drain for exactly this reason): principal
+  dims win by construction, and a callout with no clear room yields with a
+  warning, never a principal-dim error. Callout leaders may shift (they now
+  route around the drained dims); on the `hex_bar` golden this *recovers* a
+  silently starved `m_env_width` envelope dim.
+
+### Removed
+
+- **Three orphaned root exports** (#704): `draftwright.recognise_face_levels`
+  (one recogniser of ~12 — incoherent as a top-level surface; import it from
+  `draftwright.recognition`), `draftwright.dedup_diams` (an analysis internal),
+  and `draftwright.fix_svg_page_size` (still available from `draftwright.export`
+  and the `draftwright.make_drawing` facade). None had any internal or test
+  consumer via the root API.
+
+### Deprecated
+
+- **The seven `Drawing` compat aliases** (`_named`/`_anno_view`/`_pinned`/
+  `_build_issues`/`_pattern_callouts`/`_patterned_holes`/
+  `_dropped_callout_diams`) are formally on notice (#699 slice c, tracked by
+  #720): removal target **0.4.0**, per ADR 0005 §4. Read through the public
+  surface instead — `annotations()`, `iter_annotations()`, `get_annotation()`,
+  `view_of()`, `registry.pinned_names()`/`is_pinned()`, and the new
+  `registry.issues`. All external production and test call sites in this repo
+  are already redirected (`drawing.py` internals ride the aliases until the
+  #720 deletion).
+- **`draftwright.sheet_dsl`** (belated announcement — the alias shim shipped
+  in 0.3.1 when #640 renamed the module to `draftwright.sheet`): importing it
+  warns; it will be removed in **0.4.0**. Import from `draftwright.sheet`, or
+  just `from draftwright import Sheet`.
+
+## v0.3.3 — 2026-07-18
+
+The **layout-quality release**: the occupancy model gets honest about ink shape,
+the last solver-invisible pass joins the corridor solve, and crossed labels shift
+themselves clear. Also completes the #635 consolidation epic (ADR 0005 fully
+executed; ADR 0009's no-invisible-occupant guarantee now holds by construction
+for every auto-pass).
+
+### Added
+
+- **Witness-crossing label shifts** (#690): a dimension label crossed by another
+  dimension's witness stroke now shifts along its own line to clear it — a
+  deterministic post-drain pass using the repair machinery (destination-aware,
+  axis-aligned only, pinned dims exempt).
+
+### Changed
+
+- **L-shaped occupancy** (#685): placement obstacles decompose into per-stroke
+  boxes + label box (helpers ≥0.14 `segments`) instead of one hull, with
+  preset-aware arrowhead pads. View-corner contention between perpendicular
+  strips disappears by construction (a plate-thickness dim returns to its
+  natural strip); packing tightens. The cleanliness ratchet mirrors the model —
+  only transverse stroke crossings are exempt, so parallel overprints and label
+  contacts are detected honestly (twelve hull-artifact allowlist entries burned
+  down; the legitimate shared-datum running-dimension pairs are documented).
+- **Height ladder joins the corridor solve** (#636): step heights + overall
+  height are corridor candidates (the leapfrog witness cursor survives as a
+  deterministic build-time chain; the overall height stacks outermost by
+  construction and packs tighter). An explicitly-requested crowded-step detail
+  view now *deliberately* demotes the overall-height dim when the sheet cannot
+  hold both (previously the carve dropped it silently); a Y-drilled hole's Z
+  location joins the front running ladder per the documented routing.
+- **One typed `BuildState`** (#639): the drawing's build context (analysis,
+  part model, lint geometry caches) consolidates into a single object filled at
+  one builder site, single-writer-guarded; the render passes make zero private
+  `Drawing` reads (fail-closed empty allowlist).
+
+### Fixed
+
+- A prismatic detail view no longer loses both the detail *and* the height dim
+  when space is tight (transactional demotion).
+- The GD&T alternate-strip fallback defers until every corridor has drained, so
+  it can never preempt a sibling strip's reserved corner.
+
 ## v0.3.2 — 2026-07-18
 
 The **performance release**: the #602 perf loop (six PRs) plus the

{draftwright-0.3.2 → draftwright-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: draftwright
-Version: 0.3.2
+Version: 0.3.4
 Summary: Automated technical-drawing generation for build123d
 Project-URL: Homepage, https://github.com/pzfreo/draftwright
 Project-URL: Repository, https://github.com/pzfreo/draftwright
@@ -789,18 +789,47 @@ sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
-sheet.export("plate")                                     # writes plate.svg + plate.dxf
+sheet.export("plate")                                     # writes plate.pdf
 ```
 
 Every aspect the geometry can't carry is a declared verb: `.tolerance(±)` / `.fit("H7")`
 (ISO 286), `.finish("Ra")` (ISO 1302), `sheet.datum(letter, ref)` (ISO 5459), and
 `sheet.control(ref)` with all 14 ISO 1101 characteristics
-(`.position`/`.flatness`/`.perpendicularity`/`.circular_runout`/…), plus `sheet.note(text, ref)`
-/ `.note(text)` for free-text shop callouts (thread specs, `DEBURR`, knurl). A feature verb returns
+(`.position`/`.flatness`/`.perpendicularity`/`.circular_runout`/…), plus `.thread("M3x0.5")`
+(a tap/thread spec folded onto the hole callout), `.knurl("0.8")`, and `sheet.note(text, ref)`
+/ `.note(text)` for any other free-text shop callout (`DEBURR`, chip-relief). A feature verb returns
 a chainable handle (`sheet.hole(bore)`) that the aspect and `control(...)` verbs decorate;
 targets are placed automatically — the view and strip are derived from the referenced
 feature or face, with `view=`/`side=` overrides.
 
+### From a part to an object-referenced script
+
+`draftwright part.step --script` writes an editable `Sheet` script. When you built the part
+yourself (rather than importing a STEP), pass your **live source** as a `module:attr` (or
+`file.py:attr`) object spec, and the script binds `part` back to your real object:
+
+```bash
+draftwright mymodule:thumbwheel --script
+```
+
+The emitted values are *detected* off the geometry — honest, and a good starting point. Since
+you have the objects, swap each numbered line for a reference so the object stays the single
+source of truth (ADR 0011 — the size is read off the object, no numbers restated):
+
+```python
+# generated (detected):
+sheet.step(diameter=8, length=25, at=(0, 0, 12), axis="z")
+
+# edited to reference your objects:
+features = mymodule.thumbwheel_features()
+part = features.part
+sheet.step(features.journal)
+sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on the same hole
+```
+
+An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
+script keeps the detected numbers (there's no object to reference).
+
 ## What it produces
 
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the
@@ -854,14 +883,16 @@ dwg.repair()                # auto-fix mechanically-fixable lint; never worsens
 
 Each `LintIssue` carries a domain-meaningful `code` and, when computable, a
 ready-to-apply `suggestion`. See `docs/adr/` for the design (deterministic
-generation, the lint→repair loop, and the constraint-based layout engine).
+generation, the lint→repair loop, and collect-then-solve placement).
 
 ## Architecture
 
-draftwright is structured as a **part-drawing compiler** (ADR 0008): feature
-detectors → a `PartModel` IR (`Feature`s exposing `DimParameter`s) → a dimensioning
-planner → renderers, feeding a shared layout/projection/export stack. It builds on
-two libraries:
+draftwright is structured as a **part-drawing compiler** (ADR 0015): recognised
+or declared features converge on a `PartModel` IR, then planner-fed and
+sanctioned model-routed render intents feed shared placement, projection, and
+export. Coverage lint independently compares recognised geometry with the
+placed drawing, so an upstream omission cannot hide from verification. It
+builds on two libraries:
 
 ```
 draftwright
@@ -874,8 +905,7 @@ primitives (`Dimension`, `Leader`, etc.) live in `build123d-drafting-helpers` an
 be used independently. The compiler is largely converged in production — turned
 dims/lengths, centre marks, envelope, slots, holes (callouts/locations/grouping),
 the section A–A trigger, the prismatic step-ladder + rotational furniture, and PMI/GD&T
-are all on the IR — the migration is complete (one path; the orchestrator is
-build → plan → render). See
+are all on the IR. See
 [`docs/target-architecture.md`](docs/target-architecture.md) and
 [`docs/layout-algorithm-primer.md`](docs/layout-algorithm-primer.md) for a short walkthrough, plus
 [`docs/adr/`](docs/adr/). The engine handles view layout (strip/zone model), scale

{draftwright-0.3.2 → draftwright-0.3.4}/README.md

@@ -94,18 +94,47 @@ sheet.envelope()
 sheet.datum("A", plate.faces().sort_by()[-1])             # datum A on the top face
 hole = sheet.hole(bore).finish("1.6").note("M3x0.5 TAP")  # ⌀8 bore, Ra 1.6, tapped
 sheet.control(hole).position(0.1, to="A", diameter=True)  # ⌀0.1 position wrt A
-sheet.export("plate")                                     # writes plate.svg + plate.dxf
+sheet.export("plate")                                     # writes plate.pdf
 ```
 
 Every aspect the geometry can't carry is a declared verb: `.tolerance(±)` / `.fit("H7")`
 (ISO 286), `.finish("Ra")` (ISO 1302), `sheet.datum(letter, ref)` (ISO 5459), and
 `sheet.control(ref)` with all 14 ISO 1101 characteristics
-(`.position`/`.flatness`/`.perpendicularity`/`.circular_runout`/…), plus `sheet.note(text, ref)`
-/ `.note(text)` for free-text shop callouts (thread specs, `DEBURR`, knurl). A feature verb returns
+(`.position`/`.flatness`/`.perpendicularity`/`.circular_runout`/…), plus `.thread("M3x0.5")`
+(a tap/thread spec folded onto the hole callout), `.knurl("0.8")`, and `sheet.note(text, ref)`
+/ `.note(text)` for any other free-text shop callout (`DEBURR`, chip-relief). A feature verb returns
 a chainable handle (`sheet.hole(bore)`) that the aspect and `control(...)` verbs decorate;
 targets are placed automatically — the view and strip are derived from the referenced
 feature or face, with `view=`/`side=` overrides.
 
+### From a part to an object-referenced script
+
+`draftwright part.step --script` writes an editable `Sheet` script. When you built the part
+yourself (rather than importing a STEP), pass your **live source** as a `module:attr` (or
+`file.py:attr`) object spec, and the script binds `part` back to your real object:
+
+```bash
+draftwright mymodule:thumbwheel --script
+```
+
+The emitted values are *detected* off the geometry — honest, and a good starting point. Since
+you have the objects, swap each numbered line for a reference so the object stays the single
+source of truth (ADR 0011 — the size is read off the object, no numbers restated):
+
+```python
+# generated (detected):
+sheet.step(diameter=8, length=25, at=(0, 0, 12), axis="z")
+
+# edited to reference your objects:
+features = mymodule.thumbwheel_features()
+part = features.part
+sheet.step(features.journal)
+sheet.hole(features.m3_bore).thread("M3x0.5").finish("1.6")   # tapped + Ra on the same hole
+```
+
+An object-sourced script carries an inline tip pointing at exactly this edit; a STEP-sourced
+script keeps the detected numbers (there's no object to reference).
+
 ## What it produces
 
 - **Three orthographic views** (front, plan, side) sized and scaled automatically to the
@@ -159,14 +188,16 @@ dwg.repair()                # auto-fix mechanically-fixable lint; never worsens
 
 Each `LintIssue` carries a domain-meaningful `code` and, when computable, a
 ready-to-apply `suggestion`. See `docs/adr/` for the design (deterministic
-generation, the lint→repair loop, and the constraint-based layout engine).
+generation, the lint→repair loop, and collect-then-solve placement).
 
 ## Architecture
 
-draftwright is structured as a **part-drawing compiler** (ADR 0008): feature
-detectors → a `PartModel` IR (`Feature`s exposing `DimParameter`s) → a dimensioning
-planner → renderers, feeding a shared layout/projection/export stack. It builds on
-two libraries:
+draftwright is structured as a **part-drawing compiler** (ADR 0015): recognised
+or declared features converge on a `PartModel` IR, then planner-fed and
+sanctioned model-routed render intents feed shared placement, projection, and
+export. Coverage lint independently compares recognised geometry with the
+placed drawing, so an upstream omission cannot hide from verification. It
+builds on two libraries:
 
 ```
 draftwright
@@ -179,8 +210,7 @@ primitives (`Dimension`, `Leader`, etc.) live in `build123d-drafting-helpers` an
 be used independently. The compiler is largely converged in production — turned
 dims/lengths, centre marks, envelope, slots, holes (callouts/locations/grouping),
 the section A–A trigger, the prismatic step-ladder + rotational furniture, and PMI/GD&T
-are all on the IR — the migration is complete (one path; the orchestrator is
-build → plan → render). See
+are all on the IR. See
 [`docs/target-architecture.md`](docs/target-architecture.md) and
 [`docs/layout-algorithm-primer.md`](docs/layout-algorithm-primer.md) for a short walkthrough, plus
 [`docs/adr/`](docs/adr/). The engine handles view layout (strip/zone model), scale

draftwright-0.3.4/docs/adr/README.md

@@ -0,0 +1,51 @@
+# Architecture decision records
+
+This is the front door to draftwright's ADR corpus. Start with the **Current
+architecture** table; open retired or superseded records only for design history.
+
+## Maintenance rules
+
+- Keep the status header to one load-bearing statement.
+- At roughly four amendments, write a successor ADR and freeze the old record.
+  The superseded file remains the historical why-trail; do not rewrite it.
+- Cite symbols and test names, never source line numbers.
+- If an invariant can be checked mechanically, guard it with a test. A claim
+  that something is machine-checked must name the real check.
+- Preserve reversals in the frozen record. The successor compresses each to one
+  line and points back to the history.
+- Update this index whenever an ADR is accepted, retired, or superseded, or when
+  its guarding test changes.
+
+## Current architecture
+
+| ADR | Title | Decision | Status | Representative guards |
+| --- | --- | --- | --- | --- |
+| [0001](0001-deterministic-generation-over-editable-dsl.md) | Deterministic generation and domain-semantic editing over a bespoke editable-code DSL | Prefer deterministic generation and domain-semantic editing over a primitive editable-code DSL. | Accepted | `test_sheet_emit.py`, `test_make_drawing.py` |
+| [0002](0002-iterate-via-lint-critique-and-domain-repair.md) | Iterate via lint critique and domain-semantic repair, not by editing generated code | Refine drawings through machine-readable lint and narrowly allowlisted domain repair. | Accepted | `test_linting.py`, `test_lint_structural.py`, `test_make_drawing.py` |
+| [0004](0004-compose-then-pack-view-blocks.md) | Compose-then-pack: views as blocks carrying their annotation footprint | Compose each view with its annotation footprint, then pack fixed-topology blocks. | Accepted | `test_layout.py`, `test_layout_cleanliness.py`, `test_refactor_golden.py` |
+| [0005](0005-pipeline-architecture-and-state-ownership.md) | Compiler-pipeline module boundaries and single-owner build state | Give compiler stages explicit module homes and build-time state explicit owners. | Accepted; implemented; compatibility aliases tracked by #720 | `test_import_boundaries.py`, `test_drawing_encapsulation.py`, `test_registry.py` |
+| [0006](0006-deterministic-layout-via-bundled-fonts.md) | Deterministic cross-platform layout via bundled, path-pinned fonts | Pin bundled font files so text measurement and layout are cross-platform deterministic. | Accepted | `test_refactor_golden.py`, `test_layout_cleanliness.py` |
+| [0007](0007-own-recognition-and-linting.md) | draftwright owns feature recognition and linting; helpers becomes the rendering library | draftwright owns recognition and linting; helpers remains a rendering library. | Accepted | `test_import_boundaries.py`, `test_recognition.py`, `test_linting.py` |
+| [0010](0010-annotation-provenance-seam.md) | Annotation provenance: record intent → annotation once, at the render seam | Record annotation provenance once at the render/add seam. | Accepted; landed | `test_render_seam.py`, `test_registry.py` |
+| [0011](0011-ir-as-public-input.md) | The IR as a public input: declare features, don't only detect them | Accept the feature IR as public input through declarations and the `Sheet` façade. | Accepted; core landed; #62/#462/#495 remain | `test_declare.py`, `test_object_aspects.py`, `test_sheet_gdt.py` |
+| [0012](0012-edits-as-pinned-priority-candidates-in-the-global-solve.md) | User annotation edits are pinned, priority-ranked corridor candidates | Drain recorded semantic edits through corridor placement with pin and priority. | Accepted; partially landed; full recomposition/parity remains #426/#707 (#661 detail views landed) | `test_make_drawing.py`, `test_sheet_emit.py` |
+| [0013](0013-uniform-recognition-and-shared-package.md) | A uniform recogniser/feature contract (with `b123d-recognisers` as its deferred shared deployment) | Enforce a uniform geometry-only recogniser contract internally; defer package extraction until there is a second consumer. | Accepted; Phase 1 in progress; extraction deferred | `test_recogniser_contract.py`, `test_import_boundaries.py` |
+| [0014](0014-collect-then-solve-annotation-placement.md) | Collect-then-solve annotation placement (as built) | Collect, select, assign, and deterministically solve annotations per corridor before rendering. | Accepted; supersedes 0009 | `test_carve_free_position_callers.py`, `test_strip_layout.py`, `test_layout_property.py`, `test_import_boundaries.py` |
+| [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` |
+
+## Historical records
+
+| ADR | Title | Historical decision | Status | Read instead |
+| --- | --- | --- | --- | --- |
+| [0003](0003-constraint-based-layout.md) | Constraint-based layout: one solver for every placeable | Explored a universal `Placeable`/`LayoutSolver` and page-global constraint solve. | Retired; carrier deleted and #94 closed as unnecessary | [0004](0004-compose-then-pack-view-blocks.md) for outer layout and [0014](0014-collect-then-solve-annotation-placement.md) for inner placement |
+| [0008](0008-unified-feature-model-and-dimensioning-planner.md) | The part-drawing compiler: a Feature/DimParameter IR and a dimensioning planner | Introduced the feature/parameter IR and dimensioning-planner direction. | Superseded by 0015; frozen | [0015](0015-part-drawing-compiler-as-built.md) |
+| [0009](0009-boundary-labeling-strip-placement.md) | Boundary labeling: collect-then-solve per-strip annotation placement | Developed collect-then-solve boundary-label placement through nine amendments. | Superseded by 0014; frozen | [0014](0014-collect-then-solve-annotation-placement.md) |
+
+## Reading paths
+
+- Compiler and state ownership: 0001 → 0005 → 0015.
+- Recognition and public declaration: 0007 → 0013 → 0011 → 0015.
+- Layout and placement: 0004 → 0014 → 0012.
+- Quality and correction: 0002, with provenance from 0010.
+
+Tracking issue: #745.

{draftwright-0.3.2 → draftwright-0.3.4}/pyproject.toml

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

{draftwright-0.3.2 → draftwright-0.3.4}/src/draftwright/__init__.py

@@ -23,15 +23,12 @@ from typing import TYPE_CHECKING
 # 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 = {
-    "recognise_face_levels": "draftwright.recognition",
-    "dedup_diams": "draftwright.analysis",
     "build_drawing": "draftwright.builder",
     "generate_script": "draftwright.builder",
     "make_drawing": "draftwright.builder",
     "Drawing": "draftwright.drawing",
     "FeatureInfo": "draftwright.drawing",
     "Sheet": "draftwright.sheet",
-    "fix_svg_page_size": "draftwright.export",
     "lint_feature_coverage": "draftwright.linting",
     "PmiRecord": "draftwright.pmi",
     "extract_pmi": "draftwright.pmi",
@@ -72,14 +69,11 @@ _sys.modules[__name__].__class__ = _DraftwrightModule
 
 
 if TYPE_CHECKING:  # static analysers / IDEs — no runtime import, no kernel cost
-    from draftwright.analysis import dedup_diams
     from draftwright.builder import build_drawing, generate_script, make_drawing
     from draftwright.compose import choose_scale
     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.recognition import recognise_face_levels
     from draftwright.sheet import Sheet
 
 
@@ -95,12 +89,9 @@ __all__ = [
     "FeatureInfo",
     "PmiRecord",
     "Sheet",
-    "recognise_face_levels",
     "build_drawing",
     "choose_scale",
-    "dedup_diams",
     "extract_pmi",
-    "fix_svg_page_size",
     "generate_script",
     "lint_feature_coverage",
     "make_drawing",