3D Layer integration — follows the Footprint (Template carry-over + EasyEDA fallback)

[theautomatist]

What to build

Die 3D-Layer folgt jetzt dem Footprint (ADR-0005), nicht mehr stur EasyEDA. Drei Pfade, ein gemeinsamer Copy-/Reference-Mechanismus.

3D Resolution Order (Phase 2)

1. Footprint = Template: parse Template .kicad_mod für (model "...")-References.
   • Pfad löst innerhalb Template-Lib auf → Carry-Over: kopiere File nach <ActiveLib>.3dshapes/<basename> (idempotent, content-hash-dedupliziert — shared 3D-Files zwischen mehreren Template-FPs landen nur einmal); rewrite Reference auf ${KIPRJMOD}/<ActiveLib>.3dshapes/....
   • Pfad ist KiCad-System-Variable (${KICAD9_3DMODEL_DIR}, ${KISYS3DMOD}) oder absoluter System-Pfad → Reference 1:1 belassen, kein File-Copy.
2. Footprint = Template, aber keine (model ...)-Ref im Template-FP: Fallback auf EasyEDA-3D (alte V2-Logik). EasyEDA-3D wird geladen, in <ActiveLib>.3dshapes/ abgelegt, Reference an Template-FP angehängt.
3. Footprint = EasyEDA: EasyEDA-3D wie in V2, in <ActiveLib>.3dshapes/X.step, Reference applied.
4. Keine 3D-Quelle: no 3D progress message, Footprint ohne Model-Reference geschrieben, kein Fehler.

Implementation notes

• Multiple (model ...)-References pro Footprint sind möglich (KiCad erlaubt das). Alle behandeln, nicht nur die erste.
• Content-Hash-Dedup heißt: vor dem Copy SHA-256 des Source-Files berechnen; wenn <ActiveLib>.3dshapes/<basename> schon existiert UND gleiches Hash → skip. Wenn existiert aber anderes Hash → fail (verhindert stilles Überschreiben). User-actionable error.
• Template-Lib-Pfad-Auflösung: ${KIPRJMOD} im Template-FP referenziert die Template-Lib-Root, nicht die Active-Lib. Resolver muss das wissen.

Acceptance criteria

• Footprint=EasyEDA + EasyEDA hat 3D: .step in <ActiveLib>.3dshapes/, korrekte (model ...)-Ref im Footprint. (V2-Verhalten)
• Footprint=Template + Template-FP hat 3D-Ref auf Template-internen Pfad: File wird kopiert nach <ActiveLib>.3dshapes/, Ref rewritten auf ${KIPRJMOD}/<ActiveLib>.3dshapes/....
• Footprint=Template, zwei FPs sharen dasselbe 3D-File: beide Imports → File liegt nur einmal in <ActiveLib>.3dshapes/, beide Footprints referenzieren es korrekt (content-hash-dedup).
• Footprint=Template + System-Variable-Ref (${KICAD9_3DMODEL_DIR}/...): Reference 1:1 im geschriebenen Footprint, kein File-Copy.
• Footprint=Template ohne 3D-Ref + EasyEDA hat 3D: Fallback greift, EasyEDA-3D wird auf Template-FP angehängt.
• Footprint=Template ohne 3D-Ref + EasyEDA hat kein 3D: no 3D progress, Footprint ohne Model-Ref geschrieben, kein Fehler.
• Hash-Collision: Same basename, anderes Hash → klarer User-actionable Error.
• Pytest gegen alle 6 Fälle mit Sample-Parts + Template-Fixture; manueller KiCad-Smoke-Test (pcbnew öffnet das Footprint und zeigt das 3D-Modell).

Blocked by

• Phase 2 Conversion — default-path (EasyEDA, no overrides) #4 (Phase 2 Conversion default-path)

V3 context

• ADR-0005 (3D Layer follows the Footprint)
• V3-SPEC.md §2 (refined: 3D resolution order)
• CONTEXT.md terms: 3D Layer, Template-3D Carry-Over
• Memory: project_v3_3d_layer.md (updated)

[theautomatist]

Implementation PR: #22

[theautomatist]

Sandcastle iteration (branch sandcastle/sequential-reviewer/1780062598721) hit a hard blocker before it could commit anything: the workspace 9p mount (D:\ → /home/agent/workspace) went stale mid-session — ls /home/agent/workspace returns No such file or directory even though the mount is still listed in /proc/mounts. The .git file (mounted separately via C:\) stayed readable, but every path under workspace/ became inaccessible after the first few file writes, so the three_d_resolver.py + pytest module I'd drafted couldn't be re-read, the test suites couldn't run, and no commit / push / PR was possible.

No competing PR is being opened against #22 — this iteration produced nothing usable. The next AFK pass should be fine once the worktree mount is re-established.