Integrate Measured ESP32 PCB Geometry

- Add measured F.Fab bounds and USB mouth markers
- Add guarded preservation and regression validation
- Refresh review exports and remove draft presentation labels

docs/devel/hardware/PCB/footprint-notes.md

@@ -78,10 +78,38 @@ centre (pad 1), **not a PCB corner**.
 - Numbering follows the project's explicit convention, not a generic dual-row
   connector's alternating or counterclockwise numbering. Physical numbers do
   **not** establish GPIO, supply, or ground assignments.
-- Only pads and annotation text are present. **No PCB outline, antenna keepout,
-  courtyard, USB envelope, mounting holes, or 3D model is guessed.** Text positions
-  are annotations, not dimensional evidence. Outline registration, antenna extent,
-  connector offsets/overhang, and assembly height remain unknown.
+- User-measured planar geometry is now drawn on `F.Fab`, relative to pad 1:
+
+  | Feature | Start (X, Y), mm | End (X, Y), mm |
+  |---|---|---|
+  | Main PCB rectangle | (-1.365, -1.365) | (26.725, 54.705) |
+  | Projecting antenna rectangle | (4.045, -8.255) | (21.675, -1.365) |
+  | Left USB-C shell mouth span | (2.795, 54.705) | (11.665, 54.705) |
+  | Right USB-C shell mouth span | (14.195, 54.705) | (23.065, 54.705) |
+
+  Main PCB is 28.09 mm wide × 56.07 mm long; antenna projection adds 6.89 mm,
+  giving 62.96 mm overall. Antenna left/right insets are 5.41/5.05 mm, giving
+  17.63 mm width and a centre 0.18 mm right of the PCB centre. Both shell widths
+  are 8.87 mm, with outer-edge offsets 4.16 mm left / 3.66 mm right; mouths are
+  flush with the bottom PCB edge. Lines indicate mouth spans, not shell depth.
+- User accepted approximate 1.365 mm top/bottom pin-centre offsets and supplied
+  approximately the same left offset. Nominal pin pitch/row spacing are retained;
+  resulting right margin is 1.325 mm. This 0.04 mm asymmetry follows the selected
+  modelling datum, not a precision measurement of header asymmetry.
+- **No RF keepout, courtyard, full USB envelope, mounting holes or 3D model is
+  inferred.** Shell depth/height, component/underside heights and plug clearances
+  remain unknown. The antenna rectangle is physical geometry, not RF guidance.
+- Routed embedded U1 now contains the four measured F.Fab shapes and the two
+  antenna/USB measurement-limit annotations. Generic library captions are omitted
+  to avoid overlapping existing board labels. Existing footprint fields (including
+  the historical hidden status/description), reference/value positions, pads,
+  nets and UUIDs are deliberately retained; this is not a full footprint replacement.
+  The library is authoritative for measured geometry, not those old status strings.
+- Measured board-local silkscreen and PDF/SVG/PNG/3D previews are refreshed.
+  `update_u1_graphics.py` synchronizes only owned graphics, with deterministic new
+  UUIDs and lock/concurrent-change guards; `validate_u1_update.py` checks exact
+  preservation against the pre-update A1 snapshot. A physical 1:1 fit check is
+  still pending; USB mouths sit 2.295 mm inside the carrier bottom edge.
 
 ## Validation and release gates
 
@@ -89,7 +117,9 @@ Validation performed with KiCad 10.0.6 `pcbnew.FootprintLoad`: both footprints
 parsed successfully. Assertions passed for pad counts, all numbered pad positions,
 pad shapes/types/sizes/drills, OLED NPTH positions and diameters, both OLED `F.Fab`
 rectangle bounds, and absence of courtyards, `Edge.Cuts`, and keepout zones.
-HW678 was also checked to contain no graphical shapes. The local Python binding
+The HW678 regression now checks the two measured rectangles and two USB mouth
+spans, while retaining exact pad geometry checks and prohibiting guessed
+courtyards, zones and 3D models. The local Python binding
 emitted three startup `PROPERTY_ENUM` assertions (also seen on a version-only
 import); these did not prevent loading or the checks from passing.
 

docs/devel/hardware/PCB/pcb-draft-notes.md

@@ -7,6 +7,26 @@ Open **`../../../../hardware/PCB/serial-carrier.kicad_pcb`** in KiCad 10. The ro
 existing `../../../../hardware/PCB/serial-carrier.kicad_pro` / `../../../../hardware/PCB/serial-carrier.kicad_sch` project. **Not for fabrication.**
 No Gerbers, production drills or manufacturing archive were generated.
 
+## Measurement update — embedded U1, silkscreen and exports
+
+The user has now supplied ESP32 main-PCB, antenna and USB mouth geometry; see
+`footprint-notes.md` and the hardware README. The library HW678 footprint contains
+these measured F.Fab bounds. Embedded U1 now has the same four shapes and two
+measurement-limit annotations; generic library captions are omitted to avoid
+colliding with existing board labels. Silkscreen, PDF and SVG/PNG/3D previews are
+refreshed. Existing footprint fields, all existing non-generated UUIDs, pads/nets,
+placement, routing, edges, RF reserve and project settings are unchanged. Old
+hidden U1 status/description fields are retained historical metadata, not evidence
+that planar measurements are missing. RF requirements, full USB envelopes and
+assembly heights remain pending; the antenna rectangle is not an RF keepout.
+
+At unchanged A1 U1 placement, the measured main PCB occupies carrier-local
+X=6.635…34.725, Y=21.635…77.705 mm; the projecting antenna occupies
+X=12.045…29.675, Y=14.745…21.635 mm. USB mouths are at Y=77.705 mm,
+**2.295 mm inside the carrier bottom edge**, so flush-with-module USB does not
+mean flush-with-carrier access. Review mating-plug clearance before accepting
+placement; no relocation, rerouting or RF sign-off is implied by this update.
+
 ## Size and placement
 
 - **Carrier bounding dimensions: 82 × 80 mm**, within the requested 100 × 100 mm.
@@ -14,8 +34,8 @@ No Gerbers, production drills or manufacturing archive were generated.
 - Proposed **1.6 mm** carrier thickness; fabrication stackup/process not selected.
 - Stepped outline: a **36 × 19 mm top-left antenna cutaway** fits within a simple
   rectangular/square case. The lower edge is now straight, with ESP32 USB toward
-  the bottom and RS-232 toward the top. U1 moved down by 19 mm; its exact USB/body
-  registration remains provisional pending the user's measured ESP32 geometry.
+  the bottom and RS-232 toward the top. A1 moved U1 down by 19 mm; this measurement
+  integration retains that placement and uses the user-accepted approximate header datum.
 - Module and mating-plug overhangs are not included in the carrier dimensions.
   The final complete assembly/enclosure envelope still needs measurement.
 
@@ -80,8 +100,8 @@ allocation, **not a measured antenna envelope or a manufacturer RF keepout**.
 The module itself may span the rule area; footprint placement is not forbidden.
 No carrier copper enters the reserve, but copper runs close to its boundary.
 
-U1's exact PCB/antenna/USB offsets are still unmeasured. The intended antenna
-overhang and USB access must be checked with the actual board and a printed
+U1's planar PCB/antenna/USB-mouth offsets are now recorded. Antenna clearance
+and USB access must still be checked with the actual board and a printed
 placement template. Move U1, change the edge or enlarge the reserve if required.
 Missing RF clearance cannot be signed off from the current footprint alone.
 
@@ -147,11 +167,13 @@ RS-232's visible rounded corners retain true arcs. Small gaps clear pad/mask
 openings, vias and adjacent resistor markings; the original full F.Fab geometry
 remains unchanged.
 
-U1 instead has **header-row guides**, labelled `HEADER GUIDES`: guide edges are
-1.20 mm outside the outer pin centres. These are graphic alignment aids, **not
-claimed socket-body dimensions or an inferred ESP32 PCB outline**. The actual
-U1 body/antenna/USB outline still requires measured offsets. Existing button and
-resistor silkscreen remains unchanged.
+U1 now has **measured body/antenna outlines**, replacing the header-row guides
+and `HEADER GUIDES` label. Silkscreen is clipped inside the stepped carrier with
+0.22 mm additional edge/mask clearance; the off-carrier antenna projection remains
+visible only on F.Fab. Two **0.30 mm strokes** mark the 8.87 mm USB mouth spans,
+replacing coincident 0.12 mm body-edge strokes. Wider strokes receive correspondingly
+wider clearance. No USB depth or RF keepout is inferred. Existing button/resistor
+silkscreen remains unchanged.
 
 These are board-local drawings, not edits to the footprint libraries. If the
 module placement or routing changes, close PCB Editor and refresh them with:
@@ -160,7 +182,8 @@ module placement or routing changes, close PCB Editor and refresh them with:
 /usr/bin/python3 -B hardware/PCB/add_device_silkscreen.py
 ```
 
-The script requires pcbnew and Shapely, replaces only its own generated graphics,
+The script first verifies the saved U1 measured graphics against the library.
+It requires pcbnew and Shapely, replaces only its own generated graphics,
 and refuses an open PCB or concurrent board change. It leaves project settings,
 copper, pads and source F.Fab outlines unchanged. Run it **after** placement or
 routing regeneration; moving a footprint does not move these board-local drawings.
@@ -174,6 +197,21 @@ warning. PDF and both previews have been refreshed.
 
 ## Review outputs
 
+PCB presentation labels have been removed: title suffix `draft`, revision suffix
+`DRAFT`, front-silkscreen `DRAFT - NOT FOR FAB`, and the title-comment prefix
+`NOT FOR FABRICATION -` (including the PDF exporter). The generator no longer
+emits these labels. Specific technical cautions, dimensions, geometry, hidden
+metadata and footprint identifiers remain; artifact filenames are unchanged.
+This is a presentation change, **not fabrication approval**. The schematic and
+its exports are outside this PCB-only cleanup.
+
+`remove_draft_markers.py` performs the guarded, idempotent cleanup and audits
+that no other parsed board content or project settings change. The U1 regression
+now permits exactly these label edits against its unchanged historical baseline,
+without relaxing geometry/pad/net/routing checks. Fresh PCB DRC, U1/silkscreen
+regressions and both footprint tests pass; the expected U2 parity warning remains.
+PDF/SVG/PNG/3D outputs were regenerated and visually reviewed after cleanup.
+
 - `../../../../hardware/PCB/validation/pcb-draft.svg` / `../../../../hardware/PCB/validation/pcb-draft.png`: combined copper/outline/fab review.
 - `../../../../hardware/PCB/validation/pcb-draft-3d.png`: KiCad render of the carrier and available standard
   component models. **ESP32, OLED and RS-232 assembled module models are absent**;
@@ -181,7 +219,35 @@ warning. PDF and both previews have been refreshed.
 - `../../../../hardware/PCB/pcb-placement-draft.pdf`: **1:1** front placement/pad/outline drawing. Print at
   100%, disable fit-to-page, and confirm the outer width is 82 mm before use.
   It includes the known module outlines and nominal STEP-derived DE-9 metal
-  bounding projections; no guessed U1 body or case-wall geometry.
+  bounding projections and measured U1 planar geometry; no guessed USB depth,
+  RF keepout or case-wall geometry.
+
+Refresh the embedded measurement graphics and PDF without replacing the footprint:
+
+```sh
+/usr/bin/python3 -B hardware/PCB/update_u1_graphics.py
+/usr/bin/python3 -B hardware/PCB/add_device_silkscreen.py
+/usr/bin/python3 -B hardware/PCB/export_placement_pdf.py
+```
+
+Both board-writing helpers refuse PCB Editor locks and concurrent board changes,
+use `SaveBoard(..., True)`, and check unchanged project settings. The PDF exporter
+verifies embedded geometry instead of overlaying the library; only review captions
+change on its temporary plotting board. Print at 100%, not fit-to-page.
+
+Preview refresh commands (repository root, KiCad and Inkscape installed):
+
+```sh
+kicad-cli pcb export svg --mode-single --layers F.Cu,B.Cu,F.SilkS,F.Fab,Dwgs.User,Edge.Cuts --sketch-pads-on-fab-layers --page-size-mode 2 --output hardware/PCB/validation/pcb-draft.svg hardware/PCB/serial-carrier.kicad_pcb
+inkscape hardware/PCB/validation/pcb-draft.svg --export-type=png --export-width=1800 --export-filename=hardware/PCB/validation/pcb-draft.png
+kicad-cli pcb render --width 1600 --height 1200 --side top --quality high --output hardware/PCB/validation/pcb-draft-3d.png hardware/PCB/serial-carrier.kicad_pcb
+```
+
+KiCad's SVG trailing whitespace was normalized after export (`git diff --check`
+passes); the rendered geometry is unchanged. PDF and previews were visually reviewed.
+
+The board-area SVG crop omits outside-board review captions/parts of the DE-9
+projection; use the full-page PDF for the complete placement drawing.
 
 ## Validation and limits
 
@@ -190,6 +256,9 @@ Run from the repository root with the system Python containing KiCad bindings:
 ```sh
 /usr/bin/python3 -B hardware/PCB/validate_pcb_draft.py
 /usr/bin/python3 -B hardware/PCB/validation/pcb-routing-check.py
+/usr/bin/python3 -B hardware/PCB/validate_footprints.py
+/usr/bin/python3 -B hardware/PCB/validate_u1_update.py
+/usr/bin/python3 -B hardware/PCB/reference/db9-cad/validate.py
 ```
 
 The first script exports a **fresh saved-schematic netlist** and checks the actual
@@ -204,7 +273,25 @@ placement/net/UUID preservation against the initial unrouted snapshot. It needs
 locally installed NumPy and Shapely in addition to pcbnew. It is not a substitute
 for current-schematic net validation and is specific to this initial layout.
 
-Results with KiCad **10.0.6**:
+Measurement-integration validation with KiCad **10.0.6**:
+
+- All five commands above pass. New `validate_u1_update.py` compares the complete
+  parsed board against `validation/pcb-before-u1-measured.kicad_pcb`, excluding
+  only owned silk and six new U1 graphics. Snapshot and project hashes are pinned;
+  full pad/net/UUID/placement/routing/edge/zone/settings preservation passes.
+- Measured embedded/library geometry, silk regeneration idempotence, carrier/notch
+  clipping, two exact USB mouth markers and a stale-geometry negative control pass;
+  **91 generated silk items**. U1 refresh byte-idempotence also passed; an already
+  current U1 now returns without writing. Evidence: `hardware/PCB/validation/pcb-u1-update.json`.
+- The historical A0 `pcb-routing-preservation.py` does **not** pass: it stops on
+  its historical `serial-carrier.kicad_prl` protected hash, already stale for this
+  working state. Its older exact-footprint contract also predates measured U1
+  additions. Historical script/reports were not weakened or rebaselined; the new
+  A1 pre-update comparison is the preservation evidence for this change.
+- PCB, project and schematic retain their existing content except the authorized
+  board graphics. No firmware/assets, reroute, upload, erase or hardware test.
+
+Current results:
 
 - **0 physical DRC errors/warnings; 0 unconnected items.**
 - All saved-schematic pad nets match the PCB; **1 expected U2 footprint parity warning**.