From 93c7754b7b2e2cec89873129952f314fa6b30397 Mon Sep 17 00:00:00 2001
From: seveibar <seveibar@gmail.com>
Date: Sat, 29 Aug 2026 15:25:06 -0700
Subject: [PATCH] feat: deprecate pinheader invert option

---
 src/footprinter.ts               |  7 ++++++-
 src/helpers/zod/base_def.ts      |  4 ++--
 tests/invert-deprecation.test.ts | 11 +++++++++++
 3 files changed, 19 insertions(+), 3 deletions(-)
 create mode 100644 tests/invert-deprecation.test.ts

diff --git a/src/footprinter.ts b/src/footprinter.ts
index cafa8f6b..248f966a 100644
--- a/src/footprinter.ts
+++ b/src/footprinter.ts
@@ -19,7 +19,6 @@ type BaseOptionKey =
   | "cathodepin"
   | "origin"
   | "norefdes"
-  | "invert"
   | "faceup"
   | "nosilkscreen"
   | "rounded"
@@ -36,6 +35,12 @@ export type FootprinterParamsBuilder<K extends string> = {
       : P extends "rounded"
         ? (radius: number | string) => FootprinterParamsBuilder<K>
         : (v?: number | string | boolean) => FootprinterParamsBuilder<K>
+} & {
+  /**
+   * @deprecated For pin headers, use `connectsFromAbove` or
+   * `connectsFromBelow` on `<pinheader />`.
+   */
+  invert: (v?: number | string | boolean) => FootprinterParamsBuilder<K>
 }
 
 type CommonPassiveOptionKey =
diff --git a/src/helpers/zod/base_def.ts b/src/helpers/zod/base_def.ts
index e1c5d041..d3c03570 100644
--- a/src/helpers/zod/base_def.ts
+++ b/src/helpers/zod/base_def.ts
@@ -11,13 +11,13 @@ export const base_def = z.object({
     .boolean()
     .optional()
     .describe(
-      "install the part backwards: for a pin header, the LONG pins pass through the board instead of the short ones. It does not change which side of the board the part is on — that is the component's `layer`",
+      "DEPRECATED. For pin headers, use the explicit `connectsFromAbove` or `connectsFromBelow` prop on `<pinheader />`. This option remains supported for backward compatibility.",
     ),
   faceup: z
     .boolean()
     .optional()
     .describe(
-      "DEPRECATED, and a no-op for through-hole parts. It meant 'the male pin header should face upwards, out of the top layer', which is what a correctly mounted header does by default; its other effect was to delete the pins below the board, leaving a through-hole part that cannot be soldered into its own plated holes. Use `layer` for which side of the board a part is on, and `invert` to install it backwards",
+      "DEPRECATED, and a no-op for through-hole parts. Use the component's `layer` for its board side. For pin headers, use `connectsFromAbove` or `connectsFromBelow` on `<pinheader />`.",
     ),
   nosilkscreen: z
     .boolean()
diff --git a/tests/invert-deprecation.test.ts b/tests/invert-deprecation.test.ts
new file mode 100644
index 00000000..1f27f8f7
--- /dev/null
+++ b/tests/invert-deprecation.test.ts
@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test"
+import { base_def } from "../src/helpers/zod/base_def"
+
+test("invert remains parseable but points to explicit pin-header props", () => {
+  expect(base_def.parse({ invert: true }).invert).toBe(true)
+
+  const description = base_def.shape.invert.description
+  expect(description).toContain("DEPRECATED")
+  expect(description).toContain("connectsFromAbove")
+  expect(description).toContain("connectsFromBelow")
+})