diff --git a/package-lock.json b/package-lock.json
index f64ab473299..e1a20075c25 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -589,14 +589,18 @@
       }
     },
     "node_modules/@babel/helper-string-parser": {
-      "version": "7.27.1",
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.7.tgz",
+      "integrity": "sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==",
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
       }
     },
     "node_modules/@babel/helper-validator-identifier": {
-      "version": "7.28.5",
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz",
+      "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==",
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -633,10 +637,12 @@
       }
     },
     "node_modules/@babel/parser": {
-      "version": "7.29.2",
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.7.tgz",
+      "integrity": "sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==",
       "license": "MIT",
       "dependencies": {
-        "@babel/types": "^7.29.0"
+        "@babel/types": "^7.29.7"
       },
       "bin": {
         "parser": "bin/babel-parser.js"
@@ -1826,11 +1832,13 @@
       }
     },
     "node_modules/@babel/types": {
-      "version": "7.29.0",
+      "version": "7.29.7",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.7.tgz",
+      "integrity": "sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==",
       "license": "MIT",
       "dependencies": {
-        "@babel/helper-string-parser": "^7.27.1",
-        "@babel/helper-validator-identifier": "^7.28.5"
+        "@babel/helper-string-parser": "^7.29.7",
+        "@babel/helper-validator-identifier": "^7.29.7"
       },
       "engines": {
         "node": ">=6.9.0"
@@ -1916,6 +1924,10 @@
       "resolved": "packages/craftcms-cp",
       "link": true
     },
+    "node_modules/@craftcms/garnish": {
+      "resolved": "packages/craftcms-garnish",
+      "link": true
+    },
     "node_modules/@craftcms/graphiql": {
       "resolved": "packages/craftcms-graphiql",
       "link": true
@@ -5163,6 +5175,22 @@
         "node": "^20.19.0 || >=22.12.0"
       }
     },
+    "node_modules/@rolldown/binding-darwin-arm64": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz",
+      "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
     "node_modules/@rolldown/binding-darwin-x64": {
       "version": "1.0.0-rc.17",
       "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz",
@@ -5425,168 +5453,557 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@selectize/selectize": {
-      "version": "0.15.2",
-      "resolved": "git+ssh://git@github.com/selectize/selectize.js.git#e6ca6d3ba8f902c38da157f2caf7962c38e82095",
-      "license": "Apache-2.0",
-      "engines": {
-        "node": "*"
-      },
-      "peerDependencies": {
-        "jquery": "^1.7.0 || ^2 || ^3",
-        "jquery-ui": "^1.13.2"
-      },
-      "peerDependenciesMeta": {
-        "jquery-ui": {
-          "optional": true
-        }
-      }
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.62.0.tgz",
+      "integrity": "sha512-IPIQ55ythEHkfEd9jMEi32OQ7SxURsGA43JI22lj01OLZNt2NUbJX8YUHxkVWyQ6daHPNn0truF5nSj3DQp6YQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
     },
-    "node_modules/@shoelace-style/animations": {
-      "version": "1.2.0",
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.62.0.tgz",
+      "integrity": "sha512-M6s9cr10MibETyo8JsOkq+Lo1+lU6hcvb1MApnUql5qte/5hMEgzlN8/ReIKNfRV8rrqX50W1BX9zoUhC192RA==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "funding": {
-        "type": "individual",
-        "url": "https://github.com/sponsors/claviska"
-      }
+      "optional": true,
+      "os": [
+        "android"
+      ]
     },
-    "node_modules/@shoelace-style/localize": {
-      "version": "3.2.2",
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.62.0.tgz",
+      "integrity": "sha512-BqCoMoIbn0keKys+dEAdBa70EtOwV1bEsQCUgU9FdiZmmMge/Zk7LlkYGqbrdHR+Frnt0E1FOanly+rlwvvQzw==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
     },
-    "node_modules/@shoelace-style/shoelace": {
-      "version": "2.20.1",
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.62.0.tgz",
+      "integrity": "sha512-SIMzST3VFNXDAbeIWDWiFCNM5qncUBDWaEV7NfE7oZbDt2mgfW4MvbKdbYiGOLoM32gbTv608UMd0XktEYSD7w==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@ctrl/tinycolor": "^4.1.0",
-        "@floating-ui/dom": "^1.6.12",
-        "@lit/react": "^1.0.6",
-        "@shoelace-style/animations": "^1.2.0",
-        "@shoelace-style/localize": "^3.2.1",
-        "composed-offset-position": "^0.0.6",
-        "lit": "^3.2.1",
-        "qr-creator": "^1.0.0"
-      },
-      "engines": {
-        "node": ">=14.17.0"
-      },
-      "funding": {
-        "type": "individual",
-        "url": "https://github.com/sponsors/claviska"
-      }
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
     },
-    "node_modules/@simplewebauthn/browser": {
-      "version": "13.3.0",
-      "license": "MIT"
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.62.0.tgz",
+      "integrity": "sha512-ezjfSQMP7ArdUsbBwbQIfwAlhE84I2iVnzQNCFSveqV42q+BmKlzVpf7mxv5EchLcoWU4y6/heFzVg1F+hodUQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
     },
-    "node_modules/@sinclair/typebox": {
-      "version": "0.27.8",
-      "license": "MIT"
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.62.0.tgz",
+      "integrity": "sha512-9+qTWGW9AZRhnUgwtTwzNwcPlL87ngkeN0LA+q1bADvmY9aNvWaF2TFW8BZgnQPYxpDI7+rMVLivcd4V737TAQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
     },
-    "node_modules/@sindresorhus/is": {
-      "version": "4.6.0",
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.62.0.tgz",
+      "integrity": "sha512-T1dMEQhXA/jkJ/jyMIw9IovK8bSUq7A8kLIlvZTb/6YIVsp2zLavr4F3oyllHWo7eIVJRyE5n3tUjQJEbE1IuQ==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sindresorhus/is?sponsor=1"
-      }
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@sindresorhus/merge-streams": {
-      "version": "2.3.0",
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.62.0.tgz",
+      "integrity": "sha512-2as0LgT7qQpyceQq6VUJYnumUMUrgGQCWIiDIN9DE0/tglsk6o66uCB4f3djRawAltvfCNLyZZrsqbPA6inCsA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
-      "engines": {
-        "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@standard-schema/spec": {
-      "version": "1.1.0",
-      "license": "MIT"
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.62.0.tgz",
+      "integrity": "sha512-bVURMg+6eNN9C/yc0aVjooZcwTTtYF4YW3xta5pP0//r3o1V8gXEHXWCndj47w/HhwsFroZrFhR+6uQP5T0n0g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@storybook/addon-a11y": {
-      "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@storybook/addon-a11y/-/addon-a11y-10.4.1.tgz",
-      "integrity": "sha512-MGft/IXjJ20a9KbaSVG9bHTAAoanbucKrgEiJJRNqpim8DsXA01+XTdSk17LmiOCB203Rrq9mWgdQ6+79cc8iA==",
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.62.0.tgz",
+      "integrity": "sha512-Ful8pM/2yYI83PViWdFdpZhdI8HJ5qsXANe5atypbHDf+KIBBDsZsbyy8hbXnULVvW9NsTh5DHwbcBftyLTfiw==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
-      "dependencies": {
-        "@storybook/global": "^5.0.0",
-        "axe-core": "^4.2.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/storybook"
-      },
-      "peerDependencies": {
-        "storybook": "^10.4.1"
-      }
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@storybook/addon-docs": {
-      "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@storybook/addon-docs/-/addon-docs-10.4.1.tgz",
-      "integrity": "sha512-IYqUdjoZe4VO2LFZlKL/gwy7DsQSWCq6hX+zc1MBmZo04yycDASk1tte57n9pdlW3ajw9yYMF/+lVBi+xQjyvw==",
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.62.0.tgz",
+      "integrity": "sha512-9Gp/DgrkzfUBmNPVTyPTvay+4xEP7M/clXpj3efXBcm6uTIVIgDg4rqUpqKXvLEuFRVuEpSAOkhgNeecvaZ4Cg==",
+      "cpu": [
+        "loong64"
+      ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
-      "dependencies": {
-        "@mdx-js/react": "^3.0.0",
-        "@storybook/csf-plugin": "10.4.1",
-        "@storybook/icons": "^2.0.2",
-        "@storybook/react-dom-shim": "10.4.1",
-        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-        "ts-dedent": "^2.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/storybook"
-      },
-      "peerDependencies": {
-        "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
-        "storybook": "^10.4.1"
-      },
-      "peerDependenciesMeta": {
-        "@types/react": {
-          "optional": true
-        }
-      }
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@storybook/addon-themes": {
-      "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@storybook/addon-themes/-/addon-themes-10.4.1.tgz",
-      "integrity": "sha512-nxNskZwpgptCUWyci+jiM5IrKY6xSaTpv3xzgkL6NCU+5PyCxyp0Z6jE8NDvew9jolzOC9pBhGJAW26A/jbFqg==",
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.62.0.tgz",
+      "integrity": "sha512-m9tsJz54LUXkSYM8+8PG81B9IKK5r+2T0clMq4QrS16xFosufU7firBDAZEsDheDs7wTlP7h3++S7lMsU955HA==",
+      "cpu": [
+        "loong64"
+      ],
       "dev": true,
+      "libc": [
+        "musl"
+      ],
       "license": "MIT",
-      "dependencies": {
-        "ts-dedent": "^2.0.0"
-      },
-      "funding": {
-        "type": "opencollective",
-        "url": "https://opencollective.com/storybook"
-      },
-      "peerDependencies": {
-        "storybook": "^10.4.1"
-      }
+      "optional": true,
+      "os": [
+        "linux"
+      ]
     },
-    "node_modules/@storybook/addon-vitest": {
-      "version": "10.4.1",
-      "resolved": "https://registry.npmjs.org/@storybook/addon-vitest/-/addon-vitest-10.4.1.tgz",
-      "integrity": "sha512-ymrX9EOou1x3d21iDhjP3j3XfhOAiflhlPZWKcipULBoJCq/aZPbV68EghzovkJNuGRl9ezMYxbbKxwrMmCmGg==",
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.62.0.tgz",
+      "integrity": "sha512-3UvJ5PNVU16aJf6M3tFI24pWzAl2/ynfbyRN3ICyQajK1lSkrnVYNnLz3v04J32qKa0FczJc22zeToc0lr2A3w==",
+      "cpu": [
+        "ppc64"
+      ],
       "dev": true,
+      "libc": [
+        "glibc"
+      ],
       "license": "MIT",
-      "dependencies": {
-        "@storybook/global": "^5.0.0",
-        "@storybook/icons": "^2.0.2"
-      },
-      "funding": {
-        "type": "opencollective",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.62.0.tgz",
+      "integrity": "sha512-vRWUAbYLGHBZS6Q8Msb2sfnf1fvJf+47t8l/TwOerM2qArzy+IeNMTHrYLHXh95h8MoatPHI5hhSZNs+mGXKPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.62.0.tgz",
+      "integrity": "sha512-c00T5SYENHAt86cfW47URaP3Us5vLC/4QO7GYud1G5VNRffCwwCuBspwqYrriuJB+5m0WFzClCn9wed0FBjKvg==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.62.0.tgz",
+      "integrity": "sha512-krrCDilhXOwFkSkO3Wm9I/f9H0L92XHHwy2fwxjukxIbh0dem8gZqOW5Y8BsHrpJv5qwlRBV+Wl4ZFyRWhUpwg==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.62.0.tgz",
+      "integrity": "sha512-7pfYFSTc4/rUC/FtAI0Qp6QthDBCIi6/AuP1xYqFk5vanI6KnL5dWKP60OM/05LOsbwTmIcvr6eXC4CJuJ75IA==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.62.0.tgz",
+      "integrity": "sha512-7SDIalKeIpG0Ifogbbdn58HmSotYMlf23K3dCJEmiVd9Fg36Vmni82iPQec27N3wY4Bvbxftkxz6vSx9OcouTg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "glibc"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.62.0.tgz",
+      "integrity": "sha512-eRZevouTH2i1HeAVLqJuLnt256krQkGY0TN6WsTmsIhuzbh457HuWDMakKwmi0Cjadux983CoSr8Lim2QhUIFw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "libc": [
+        "musl"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.62.0.tgz",
+      "integrity": "sha512-3oVS7FLGa4U1qcvao9ylGxrjXZyUQqR8UwxEcnUEyPX53O/C/mKDZegNXTdHCP+h3e6ta/f1EN38Yif1mmZHYg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.62.0.tgz",
+      "integrity": "sha512-yTB9TgfWj5wHe5QgktAgXTLLot1gvEjl1NiPPAUiCs4oPrIWFl5V4nC3GrkNdj9LaAU4s94nVrGbGOCqUpyWsg==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.62.0.tgz",
+      "integrity": "sha512-5LOhoaesY3doG1c+ac/2JtgREpKoJr5bUHH8tKY0V8di7+uSV6BwLs2PlR0/yzefGOkR+wE7ZolZphHCsyG5Rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.62.0.tgz",
+      "integrity": "sha512-yYkWHhmbhRTWTnWos5HC4GcPQfjlzzCNbM9e/+GXrLuaBXYA3qSDR9f0Vgufd5S8yX81U8jPKp7ZnAjZFMtRnw==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.62.0.tgz",
+      "integrity": "sha512-SoTb6lPg25xZlA2ibwQ++ahCCnH+FP0qmEuafMJ4gznZKOlXioKEAeJLgCrqjM98ACziXM9V1amFjICVL4IFoA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.62.0.tgz",
+      "integrity": "sha512-5L+T1fMX4RIEBoZzT0+sQ0PhTS36NULFmMXtl1TZo44TMAROIMHbZufSOjVWt/Y622BtxgxtaNOokbTDvfsrZA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@selectize/selectize": {
+      "version": "0.15.2",
+      "resolved": "git+ssh://git@github.com/selectize/selectize.js.git#e6ca6d3ba8f902c38da157f2caf7962c38e82095",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "*"
+      },
+      "peerDependencies": {
+        "jquery": "^1.7.0 || ^2 || ^3",
+        "jquery-ui": "^1.13.2"
+      },
+      "peerDependenciesMeta": {
+        "jquery-ui": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@shoelace-style/animations": {
+      "version": "1.2.0",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "type": "individual",
+        "url": "https://github.com/sponsors/claviska"
+      }
+    },
+    "node_modules/@shoelace-style/localize": {
+      "version": "3.2.2",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@shoelace-style/shoelace": {
+      "version": "2.20.1",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@ctrl/tinycolor": "^4.1.0",
+        "@floating-ui/dom": "^1.6.12",
+        "@lit/react": "^1.0.6",
+        "@shoelace-style/animations": "^1.2.0",
+        "@shoelace-style/localize": "^3.2.1",
+        "composed-offset-position": "^0.0.6",
+        "lit": "^3.2.1",
+        "qr-creator": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=14.17.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://github.com/sponsors/claviska"
+      }
+    },
+    "node_modules/@simplewebauthn/browser": {
+      "version": "13.3.0",
+      "license": "MIT"
+    },
+    "node_modules/@sinclair/typebox": {
+      "version": "0.27.8",
+      "license": "MIT"
+    },
+    "node_modules/@sindresorhus/is": {
+      "version": "4.6.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sindresorhus/is?sponsor=1"
+      }
+    },
+    "node_modules/@sindresorhus/merge-streams": {
+      "version": "2.3.0",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "license": "MIT"
+    },
+    "node_modules/@storybook/addon-a11y": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-a11y/-/addon-a11y-10.4.1.tgz",
+      "integrity": "sha512-MGft/IXjJ20a9KbaSVG9bHTAAoanbucKrgEiJJRNqpim8DsXA01+XTdSk17LmiOCB203Rrq9mWgdQ6+79cc8iA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/global": "^5.0.0",
+        "axe-core": "^4.2.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^10.4.1"
+      }
+    },
+    "node_modules/@storybook/addon-docs": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-docs/-/addon-docs-10.4.1.tgz",
+      "integrity": "sha512-IYqUdjoZe4VO2LFZlKL/gwy7DsQSWCq6hX+zc1MBmZo04yycDASk1tte57n9pdlW3ajw9yYMF/+lVBi+xQjyvw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@mdx-js/react": "^3.0.0",
+        "@storybook/csf-plugin": "10.4.1",
+        "@storybook/icons": "^2.0.2",
+        "@storybook/react-dom-shim": "10.4.1",
+        "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "@types/react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+        "storybook": "^10.4.1"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@storybook/addon-themes": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-themes/-/addon-themes-10.4.1.tgz",
+      "integrity": "sha512-nxNskZwpgptCUWyci+jiM5IrKY6xSaTpv3xzgkL6NCU+5PyCxyp0Z6jE8NDvew9jolzOC9pBhGJAW26A/jbFqg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ts-dedent": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/storybook"
+      },
+      "peerDependencies": {
+        "storybook": "^10.4.1"
+      }
+    },
+    "node_modules/@storybook/addon-vitest": {
+      "version": "10.4.1",
+      "resolved": "https://registry.npmjs.org/@storybook/addon-vitest/-/addon-vitest-10.4.1.tgz",
+      "integrity": "sha512-ymrX9EOou1x3d21iDhjP3j3XfhOAiflhlPZWKcipULBoJCq/aZPbV68EghzovkJNuGRl9ezMYxbbKxwrMmCmGg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@storybook/global": "^5.0.0",
+        "@storybook/icons": "^2.0.2"
+      },
+      "funding": {
+        "type": "opencollective",
         "url": "https://opencollective.com/storybook"
       },
       "peerDependencies": {
@@ -6306,7 +6723,9 @@
       }
     },
     "node_modules/@types/estree": {
-      "version": "1.0.8",
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
       "license": "MIT"
     },
     "node_modules/@types/express": {
@@ -6404,6 +6823,8 @@
     },
     "node_modules/@types/jsesc": {
       "version": "2.5.1",
+      "resolved": "https://registry.npmjs.org/@types/jsesc/-/jsesc-2.5.1.tgz",
+      "integrity": "sha512-9VN+6yxLOPLOav+7PwjZbxiID2bVaeq0ED4qSQmdQTdjnXJSaCVKTR58t15oqH1H5t8Ng2ZX1SabJVoN9Q34bw==",
       "dev": true,
       "license": "MIT"
     },
@@ -8205,6 +8626,74 @@
         "node": ">=12"
       }
     },
+    "node_modules/ast-kit": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/ast-kit/-/ast-kit-3.0.0.tgz",
+      "integrity": "sha512-8OG92q3R35qjC/4i6BLBMg8IB+fClWu/1PEwg2Z9Rn+BuNaiEgJzpzn+pxWOdHJWDCAwu2JP0wCDTozAM4QirQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^8.0.0",
+        "estree-walker": "^3.0.3",
+        "pathe": "^2.0.3"
+      },
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sxzz"
+      }
+    },
+    "node_modules/ast-kit/node_modules/@babel/helper-string-parser": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-8.0.0.tgz",
+      "integrity": "sha512-6mJgmFFFIIO82vvoLt9XtRC7/TkzXfts1t/SpRX4IHSzMgqoPYCWesVu1udUPUWioAE/2fcG6WuI8zrkE1gwrg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      }
+    },
+    "node_modules/ast-kit/node_modules/@babel/helper-validator-identifier": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-8.0.0.tgz",
+      "integrity": "sha512-kXxQVZHNOctSJJsqzmcbPSCEkM6oHNnDIkua7g9RCO9xRHj2eCiKvRx2KPdfWR9QxcGWnK/oArrtunmie3rL9g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      }
+    },
+    "node_modules/ast-kit/node_modules/@babel/parser": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-8.0.0.tgz",
+      "integrity": "sha512-aLxAE+imI9bCcyaPrUDjBv3uSkWieifjLe0kuFOZF0zli0L6GCsTmsePnTr55adbIAgYz2zhN1vnFimCBUYcRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^8.0.0"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      }
+    },
+    "node_modules/ast-kit/node_modules/@babel/types": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-8.0.0.tgz",
+      "integrity": "sha512-K8ponJDxBwDHigkeFqaqT5wLGl4bTlwMafR8k7b5CPxr6Ww+UG9ls8Yx6Tcpboxu97eeGVEEyKcHmEyOwN1vSw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^8.0.0",
+        "@babel/helper-validator-identifier": "^8.0.0"
+      },
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      }
+    },
     "node_modules/ast-types": {
       "version": "0.16.1",
       "license": "MIT",
@@ -8215,6 +8704,25 @@
         "node": ">=4"
       }
     },
+    "node_modules/ast-v8-to-istanbul": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-1.0.4.tgz",
+      "integrity": "sha512-0bC0/4bTSrnwdhU3IsZDwEdojvuPrSg59OYZfKsLRtJZ0u8VBx9DebfqqG8bRdCC0I7vjgxmPi41P0lpkhJHtA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.31",
+        "estree-walker": "^3.0.3",
+        "js-tokens": "^10.0.0"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul/node_modules/js-tokens": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-10.0.0.tgz",
+      "integrity": "sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/astral-regex": {
       "version": "2.0.0",
       "dev": true,
@@ -8688,6 +9196,16 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/cac": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/cac/-/cac-7.0.0.tgz",
+      "integrity": "sha512-tixWYgm5ZoOD+3g6UTea91eow5z6AAHaho3g0V9CNSNb45gM8SmflpAc+GRd1InC4AqN/07Unrgp56Y94N9hJQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20.19.0"
+      }
+    },
     "node_modules/cacache": {
       "version": "16.1.3",
       "license": "ISC",
@@ -13036,6 +13554,13 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/hookable": {
+      "version": "6.1.1",
+      "resolved": "https://registry.npmjs.org/hookable/-/hookable-6.1.1.tgz",
+      "integrity": "sha512-U9LYDy1CwhMCnprUfeAZWZGByVbhd54hwepegYTK7Pi5NvqEj63ifz5z+xukznehT7i6NIZRu89Ay1AZmRsLEQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/hookified": {
       "version": "1.15.0",
       "dev": true,
@@ -15228,6 +15753,18 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
+    "node_modules/magicast": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.3.tgz",
+      "integrity": "sha512-pVKE4UdSQ7DvHzivsCIFx2BJn1mHG6KsyrFcaxFx6tONdneEuThrDx0Cj3AMg58KyN4pzYT+LHOotxDQDjNvkw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.3",
+        "@babel/types": "^7.29.0",
+        "source-map-js": "^1.2.1"
+      }
+    },
     "node_modules/make-dir": {
       "version": "4.0.0",
       "dev": true,
@@ -18697,6 +19234,204 @@
       "version": "3.0.3",
       "license": "Unlicense"
     },
+    "node_modules/rolldown": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz",
+      "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==",
+      "license": "MIT",
+      "dependencies": {
+        "@oxc-project/types": "=0.127.0",
+        "@rolldown/pluginutils": "1.0.0-rc.17"
+      },
+      "bin": {
+        "rolldown": "bin/cli.mjs"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "optionalDependencies": {
+        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
+        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
+        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
+        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
+        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
+        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
+        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
+      }
+    },
+    "node_modules/rolldown-plugin-dts": {
+      "version": "0.23.2",
+      "resolved": "https://registry.npmjs.org/rolldown-plugin-dts/-/rolldown-plugin-dts-0.23.2.tgz",
+      "integrity": "sha512-PbSqLawLgZBGcOGT3yqWBGn4cX+wh2nt5FuBGdcMHyOhoukmjbhYAl8NT9sE4U38Cm9tqLOIQeOrvzeayM0DLQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/generator": "8.0.0-rc.3",
+        "@babel/helper-validator-identifier": "8.0.0-rc.3",
+        "@babel/parser": "8.0.0-rc.3",
+        "@babel/types": "8.0.0-rc.3",
+        "ast-kit": "^3.0.0-beta.1",
+        "birpc": "^4.0.0",
+        "dts-resolver": "^2.1.3",
+        "get-tsconfig": "^4.13.7",
+        "obug": "^2.1.1",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=20.19.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sxzz"
+      },
+      "peerDependencies": {
+        "@ts-macro/tsc": "^0.3.6",
+        "@typescript/native-preview": ">=7.0.0-dev.20260325.1",
+        "rolldown": "^1.0.0-rc.12",
+        "typescript": "^5.0.0 || ^6.0.0",
+        "vue-tsc": "~3.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@ts-macro/tsc": {
+          "optional": true
+        },
+        "@typescript/native-preview": {
+          "optional": true
+        },
+        "typescript": {
+          "optional": true
+        },
+        "vue-tsc": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/rolldown-plugin-dts/node_modules/@babel/generator": {
+      "version": "8.0.0-rc.3",
+      "resolved": "https://registry.npmjs.org/@babel/generator/-/generator-8.0.0-rc.3.tgz",
+      "integrity": "sha512-em37/13/nR320G4jab/nIIHZgc2Wz2y/D39lxnTyxB4/D/omPQncl/lSdlnJY1OhQcRGugTSIF2l/69o31C9dA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^8.0.0-rc.3",
+        "@babel/types": "^8.0.0-rc.3",
+        "@jridgewell/gen-mapping": "^0.3.12",
+        "@jridgewell/trace-mapping": "^0.3.28",
+        "@types/jsesc": "^2.5.0",
+        "jsesc": "^3.0.2"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/rolldown-plugin-dts/node_modules/@babel/helper-string-parser": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-8.0.0.tgz",
+      "integrity": "sha512-6mJgmFFFIIO82vvoLt9XtRC7/TkzXfts1t/SpRX4IHSzMgqoPYCWesVu1udUPUWioAE/2fcG6WuI8zrkE1gwrg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^22.18.0 || >=24.11.0"
+      }
+    },
+    "node_modules/rolldown-plugin-dts/node_modules/@babel/helper-validator-identifier": {
+      "version": "8.0.0-rc.3",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-8.0.0-rc.3.tgz",
+      "integrity": "sha512-8AWCJ2VJJyDFlGBep5GpaaQ9AAaE/FjAcrqI7jyssYhtL7WGV0DOKpJsQqM037xDbpRLHXsY8TwU7zDma7coOw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/rolldown-plugin-dts/node_modules/@babel/parser": {
+      "version": "8.0.0-rc.3",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-8.0.0-rc.3.tgz",
+      "integrity": "sha512-B20dvP3MfNc/XS5KKCHy/oyWl5IA6Cn9YjXRdDlCjNmUFrjvLXMNUfQq/QUy9fnG2gYkKKcrto2YaF9B32ToOQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^8.0.0-rc.3"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/rolldown-plugin-dts/node_modules/@babel/types": {
+      "version": "8.0.0-rc.3",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-8.0.0-rc.3.tgz",
+      "integrity": "sha512-mOm5ZrYmphGfqVWoH5YYMTITb3cDXsFgmvFlvkvWDMsR9X8RFnt7a0Wb6yNIdoFsiMO9WjYLq+U/FMtqIYAF8Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^8.0.0-rc.3",
+        "@babel/helper-validator-identifier": "^8.0.0-rc.3"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
+    "node_modules/rolldown/node_modules/@rolldown/pluginutils": {
+      "version": "1.0.0-rc.17",
+      "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz",
+      "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==",
+      "license": "MIT"
+    },
+    "node_modules/rollup": {
+      "version": "4.62.0",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.62.0.tgz",
+      "integrity": "sha512-nc72Wgq62I7rtDV4izT5/aaS0zxy3kttkinf9586ApknY3jZO9NYsmtc24fUckA0X7Q2v+ML4a15pdUlV5V/jA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "1.0.9"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.62.0",
+        "@rollup/rollup-android-arm64": "4.62.0",
+        "@rollup/rollup-darwin-arm64": "4.62.0",
+        "@rollup/rollup-darwin-x64": "4.62.0",
+        "@rollup/rollup-freebsd-arm64": "4.62.0",
+        "@rollup/rollup-freebsd-x64": "4.62.0",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.62.0",
+        "@rollup/rollup-linux-arm-musleabihf": "4.62.0",
+        "@rollup/rollup-linux-arm64-gnu": "4.62.0",
+        "@rollup/rollup-linux-arm64-musl": "4.62.0",
+        "@rollup/rollup-linux-loong64-gnu": "4.62.0",
+        "@rollup/rollup-linux-loong64-musl": "4.62.0",
+        "@rollup/rollup-linux-ppc64-gnu": "4.62.0",
+        "@rollup/rollup-linux-ppc64-musl": "4.62.0",
+        "@rollup/rollup-linux-riscv64-gnu": "4.62.0",
+        "@rollup/rollup-linux-riscv64-musl": "4.62.0",
+        "@rollup/rollup-linux-s390x-gnu": "4.62.0",
+        "@rollup/rollup-linux-x64-gnu": "4.62.0",
+        "@rollup/rollup-linux-x64-musl": "4.62.0",
+        "@rollup/rollup-openbsd-x64": "4.62.0",
+        "@rollup/rollup-openharmony-arm64": "4.62.0",
+        "@rollup/rollup-win32-arm64-msvc": "4.62.0",
+        "@rollup/rollup-win32-ia32-msvc": "4.62.0",
+        "@rollup/rollup-win32-x64-gnu": "4.62.0",
+        "@rollup/rollup-win32-x64-msvc": "4.62.0",
+        "fsevents": "~2.3.2"
+      }
+    },
     "node_modules/rs-module-lexer": {
       "version": "2.8.0",
       "dev": true,
@@ -21732,58 +22467,6 @@
         }
       }
     },
-    "node_modules/unrun/node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.0-rc.17",
-      "cpu": [
-        "arm64"
-      ],
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "node_modules/unrun/node_modules/@rolldown/pluginutils": {
-      "version": "1.0.0-rc.17",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/unrun/node_modules/rolldown": {
-      "version": "1.0.0-rc.17",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@oxc-project/types": "=0.127.0",
-        "@rolldown/pluginutils": "1.0.0-rc.17"
-      },
-      "bin": {
-        "rolldown": "bin/cli.mjs"
-      },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      },
-      "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
-        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
-        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
-      }
-    },
     "node_modules/update-browserslist-db": {
       "version": "1.1.4",
       "funding": [
@@ -22084,68 +22767,19 @@
       },
       "peerDependenciesMeta": {
         "typescript": {
-          "optional": true
-        }
-      }
-    },
-    "node_modules/vite/node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.0-rc.17",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      }
-    },
-    "node_modules/vite/node_modules/@rolldown/pluginutils": {
-      "version": "1.0.0-rc.17",
-      "license": "MIT"
-    },
-    "node_modules/vite/node_modules/fsevents": {
-      "version": "2.3.3",
-      "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "engines": {
-        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
-      }
-    },
-    "node_modules/vite/node_modules/rolldown": {
-      "version": "1.0.0-rc.17",
-      "license": "MIT",
-      "dependencies": {
-        "@oxc-project/types": "=0.127.0",
-        "@rolldown/pluginutils": "1.0.0-rc.17"
-      },
-      "bin": {
-        "rolldown": "bin/cli.mjs"
-      },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
-      },
-      "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
-        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
-        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vite/node_modules/fsevents": {
+      "version": "2.3.3",
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
     "node_modules/vitest": {
@@ -23738,631 +24372,1127 @@
         "lit": "3.x"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/generator": {
-      "version": "8.0.0-rc.3",
+    "packages/craftcms-cp/node_modules/@types/jquery": {
+      "version": "4.0.0",
+      "dev": true,
+      "license": "MIT"
+    },
+    "packages/craftcms-cp/node_modules/@vitest/coverage-v8": {
+      "version": "4.1.5",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.2",
+        "@vitest/utils": "4.1.5",
+        "ast-v8-to-istanbul": "^1.0.0",
+        "istanbul-lib-coverage": "^3.2.2",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.2",
+        "obug": "^2.1.1",
+        "std-env": "^4.0.0-rc.1",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@vitest/browser": "4.1.5",
+        "vitest": "4.1.5"
+      },
+      "peerDependenciesMeta": {
+        "@vitest/browser": {
+          "optional": true
+        }
+      }
+    },
+    "packages/craftcms-cp/node_modules/@vitest/pretty-format": {
+      "version": "4.1.5",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-cp/node_modules/@vitest/utils": {
+      "version": "4.1.5",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.5",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-cp/node_modules/@wc-toolkit/storybook-helpers": {
+      "version": "10.3.0",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "lit": "^2.0.0 || ^3.0.0",
+        "storybook": ">=10.1.11-0 <11.0.0-0"
+      }
+    },
+    "packages/craftcms-cp/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "packages/craftcms-cp/node_modules/brace-expansion": {
+      "version": "5.0.5",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "packages/craftcms-cp/node_modules/chalk": {
+      "version": "5.6.2",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.17.0 || ^14.13 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "packages/craftcms-cp/node_modules/cli-spinners": {
+      "version": "3.3.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/del": {
+      "version": "8.0.1",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "globby": "^14.0.2",
+        "is-glob": "^4.0.3",
+        "is-path-cwd": "^3.0.0",
+        "is-path-inside": "^4.0.0",
+        "p-map": "^7.0.2",
+        "presentable-error": "^0.0.1",
+        "slash": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/dom-accessibility-api": {
+      "version": "0.7.1",
+      "dev": true,
+      "license": "MIT"
+    },
+    "packages/craftcms-cp/node_modules/glob": {
+      "version": "13.0.6",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "minimatch": "^10.2.2",
+        "minipass": "^7.1.3",
+        "path-scurry": "^2.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "packages/craftcms-cp/node_modules/globby": {
+      "version": "14.1.0",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@sindresorhus/merge-streams": "^2.1.0",
+        "fast-glob": "^3.3.3",
+        "ignore": "^7.0.3",
+        "path-type": "^6.0.0",
+        "slash": "^5.1.0",
+        "unicorn-magic": "^0.3.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/is-interactive": {
+      "version": "2.0.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/is-path-cwd": {
+      "version": "3.0.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/is-path-inside": {
+      "version": "4.0.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/is-unicode-supported": {
+      "version": "2.1.0",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/log-symbols": {
+      "version": "7.0.1",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-unicode-supported": "^2.0.0",
+        "yoctocolors": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/minimatch": {
+      "version": "10.2.5",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.5"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "packages/craftcms-cp/node_modules/ora": {
+      "version": "9.4.0",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@babel/parser": "^8.0.0-rc.3",
-        "@babel/types": "^8.0.0-rc.3",
-        "@jridgewell/gen-mapping": "^0.3.12",
-        "@jridgewell/trace-mapping": "^0.3.28",
-        "@types/jsesc": "^2.5.0",
-        "jsesc": "^3.0.2"
+        "chalk": "^5.6.2",
+        "cli-cursor": "^5.0.0",
+        "cli-spinners": "^3.2.0",
+        "is-interactive": "^2.0.0",
+        "is-unicode-supported": "^2.1.0",
+        "log-symbols": "^7.0.1",
+        "stdin-discarder": "^0.3.2",
+        "string-width": "^8.1.0"
       },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/generator/node_modules/@babel/helper-validator-identifier": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-cp/node_modules/p-map": {
+      "version": "7.0.4",
       "dev": true,
       "license": "MIT",
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/generator/node_modules/@babel/parser": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-cp/node_modules/path-scurry": {
+      "version": "2.0.2",
       "dev": true,
-      "license": "MIT",
+      "license": "BlueOak-1.0.0",
       "dependencies": {
-        "@babel/types": "^8.0.0-rc.4"
-      },
-      "bin": {
-        "parser": "bin/babel-parser.js"
+        "lru-cache": "^11.0.0",
+        "minipass": "^7.1.2"
       },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/generator/node_modules/@babel/types": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-cp/node_modules/path-type": {
+      "version": "6.0.0",
       "dev": true,
       "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "packages/craftcms-cp/node_modules/rimraf": {
+      "version": "6.1.3",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
       "dependencies": {
-        "@babel/helper-string-parser": "^8.0.0-rc.4",
-        "@babel/helper-validator-identifier": "^8.0.0-rc.4"
+        "glob": "^13.0.3",
+        "package-json-from-dist": "^1.0.1"
+      },
+      "bin": {
+        "rimraf": "dist/esm/bin.mjs"
       },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": "20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/helper-string-parser": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-cp/node_modules/semver": {
+      "version": "7.7.4",
       "dev": true,
-      "license": "MIT",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=10"
       }
     },
-    "packages/craftcms-cp/node_modules/@babel/helper-validator-identifier": {
-      "version": "8.0.0-rc.3",
+    "packages/craftcms-cp/node_modules/slash": {
+      "version": "5.1.0",
       "dev": true,
       "license": "MIT",
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.0.0-rc.17",
-      "cpu": [
-        "arm64"
-      ],
+    "packages/craftcms-cp/node_modules/tinyrainbow": {
+      "version": "3.1.0",
       "dev": true,
       "license": "MIT",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=14.0.0"
       }
     },
-    "packages/craftcms-cp/node_modules/@rolldown/pluginutils": {
-      "version": "1.0.0-rc.17",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/craftcms-cp/node_modules/@types/jquery": {
-      "version": "4.0.0",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/craftcms-cp/node_modules/@vitest/coverage-v8": {
-      "version": "4.1.5",
+    "packages/craftcms-cp/node_modules/tsdown": {
+      "version": "0.21.10",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@bcoe/v8-coverage": "^1.0.2",
-        "@vitest/utils": "4.1.5",
-        "ast-v8-to-istanbul": "^1.0.0",
-        "istanbul-lib-coverage": "^3.2.2",
-        "istanbul-lib-report": "^3.0.1",
-        "istanbul-reports": "^3.2.0",
-        "magicast": "^0.5.2",
+        "ansis": "^4.2.0",
+        "cac": "^7.0.0",
+        "defu": "^6.1.7",
+        "empathic": "^2.0.0",
+        "hookable": "^6.1.1",
+        "import-without-cache": "^0.3.3",
         "obug": "^2.1.1",
-        "std-env": "^4.0.0-rc.1",
-        "tinyrainbow": "^3.1.0"
+        "picomatch": "^4.0.4",
+        "rolldown": "1.0.0-rc.17",
+        "rolldown-plugin-dts": "^0.23.2",
+        "semver": "^7.7.4",
+        "tinyexec": "^1.1.1",
+        "tinyglobby": "^0.2.16",
+        "tree-kill": "^1.2.2",
+        "unconfig-core": "^7.5.0",
+        "unrun": "^0.2.37"
+      },
+      "bin": {
+        "tsdown": "dist/run.mjs"
+      },
+      "engines": {
+        "node": ">=20.19.0"
       },
       "funding": {
-        "url": "https://opencollective.com/vitest"
+        "url": "https://github.com/sponsors/sxzz"
       },
       "peerDependencies": {
-        "@vitest/browser": "4.1.5",
-        "vitest": "4.1.5"
+        "@arethetypeswrong/core": "^0.18.1",
+        "@tsdown/css": "0.21.10",
+        "@tsdown/exe": "0.21.10",
+        "@vitejs/devtools": "*",
+        "publint": "^0.3.0",
+        "typescript": "^5.0.0 || ^6.0.0",
+        "unplugin-unused": "^0.5.0"
       },
       "peerDependenciesMeta": {
-        "@vitest/browser": {
+        "@arethetypeswrong/core": {
+          "optional": true
+        },
+        "@tsdown/css": {
+          "optional": true
+        },
+        "@tsdown/exe": {
+          "optional": true
+        },
+        "@vitejs/devtools": {
+          "optional": true
+        },
+        "publint": {
+          "optional": true
+        },
+        "typescript": {
+          "optional": true
+        },
+        "unplugin-unused": {
           "optional": true
         }
       }
     },
-    "packages/craftcms-cp/node_modules/@vitest/pretty-format": {
-      "version": "4.1.5",
-      "dev": true,
+    "packages/craftcms-garnish": {
+      "name": "@craftcms/garnish",
+      "version": "0.0.0",
       "license": "MIT",
-      "dependencies": {
-        "tinyrainbow": "^3.1.0"
+      "devDependencies": {
+        "@total-typescript/tsconfig": "^1.0.4",
+        "@types/node": "^25.6.0",
+        "@vitest/coverage-v8": "^4.1.5",
+        "happy-dom": "^20.9.0",
+        "tsdown": "^0.21.10",
+        "typescript": "^6.0.3",
+        "vite": "^7.1.5",
+        "vitest": "^4.1.5"
       },
-      "funding": {
-        "url": "https://opencollective.com/vitest"
+      "peerDependencies": {
+        "jquery": "^3.5.0"
+      },
+      "peerDependenciesMeta": {
+        "jquery": {
+          "optional": true
+        }
       }
     },
-    "packages/craftcms-cp/node_modules/@vitest/utils": {
-      "version": "4.1.5",
+    "packages/craftcms-garnish/node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@vitest/pretty-format": "4.1.5",
-        "convert-source-map": "^2.0.0",
-        "tinyrainbow": "^3.1.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/vitest"
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/@wc-toolkit/storybook-helpers": {
-      "version": "10.3.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
       "license": "MIT",
-      "peerDependencies": {
-        "lit": "^2.0.0 || ^3.0.0",
-        "storybook": ">=10.1.11-0 <11.0.0-0"
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ast-kit": {
-      "version": "3.0.0-beta.1",
+    "packages/craftcms-garnish/node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@babel/parser": "^8.0.0-beta.4",
-        "estree-walker": "^3.0.3",
-        "pathe": "^2.0.3"
-      },
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
       "engines": {
-        "node": ">=20.19.0"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sxzz"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ast-kit/node_modules/@babel/helper-validator-identifier": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-garnish/node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ast-kit/node_modules/@babel/parser": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-garnish/node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@babel/types": "^8.0.0-rc.4"
-      },
-      "bin": {
-        "parser": "bin/babel-parser.js"
-      },
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ast-kit/node_modules/@babel/types": {
-      "version": "8.0.0-rc.4",
+    "packages/craftcms-garnish/node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@babel/helper-string-parser": "^8.0.0-rc.4",
-        "@babel/helper-validator-identifier": "^8.0.0-rc.4"
-      },
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ast-v8-to-istanbul": {
-      "version": "1.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@jridgewell/trace-mapping": "^0.3.31",
-        "estree-walker": "^3.0.3",
-        "js-tokens": "^10.0.0"
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/balanced-match": {
-      "version": "4.0.4",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "cpu": [
+        "arm"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "18 || 20 || >=22"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/brace-expansion": {
-      "version": "5.0.5",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "balanced-match": "^4.0.2"
-      },
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "18 || 20 || >=22"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/cac": {
-      "version": "7.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "cpu": [
+        "ia32"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": ">=20.19.0"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/chalk": {
-      "version": "5.6.2",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "cpu": [
+        "loong64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "^12.17.0 || ^14.13 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/chalk/chalk?sponsor=1"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/cli-spinners": {
-      "version": "3.3.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "cpu": [
+        "mips64el"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": ">=18.20"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/del": {
-      "version": "8.0.1",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "cpu": [
+        "ppc64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "globby": "^14.0.2",
-        "is-glob": "^4.0.3",
-        "is-path-cwd": "^3.0.0",
-        "is-path-inside": "^4.0.0",
-        "p-map": "^7.0.2",
-        "presentable-error": "^0.0.1",
-        "slash": "^5.1.0"
-      },
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/dom-accessibility-api": {
-      "version": "0.7.1",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/craftcms-cp/node_modules/glob": {
-      "version": "13.0.6",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "cpu": [
+        "riscv64"
+      ],
       "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "minimatch": "^10.2.2",
-        "minipass": "^7.1.3",
-        "path-scurry": "^2.0.2"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/globby": {
-      "version": "14.1.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "cpu": [
+        "s390x"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@sindresorhus/merge-streams": "^2.1.0",
-        "fast-glob": "^3.3.3",
-        "ignore": "^7.0.3",
-        "path-type": "^6.0.0",
-        "slash": "^5.1.0",
-        "unicorn-magic": "^0.3.0"
-      },
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/hookable": {
-      "version": "6.1.1",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/craftcms-cp/node_modules/is-interactive": {
-      "version": "2.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/linux-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
       "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/is-path-cwd": {
-      "version": "3.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
       "engines": {
-        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/is-path-inside": {
-      "version": "4.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
       "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/is-unicode-supported": {
-      "version": "2.1.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/js-tokens": {
-      "version": "10.0.0",
-      "dev": true,
-      "license": "MIT"
-    },
-    "packages/craftcms-cp/node_modules/log-symbols": {
-      "version": "7.0.1",
+    "packages/craftcms-garnish/node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "is-unicode-supported": "^2.0.0",
-        "yoctocolors": "^2.1.1"
-      },
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/magicast": {
-      "version": "0.5.2",
+    "packages/craftcms-garnish/node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "@babel/parser": "^7.29.0",
-        "@babel/types": "^7.29.0",
-        "source-map-js": "^1.2.1"
-      }
-    },
-    "packages/craftcms-cp/node_modules/minimatch": {
-      "version": "10.2.5",
-      "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "brace-expansion": "^5.0.5"
-      },
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
       "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/ora": {
-      "version": "9.4.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
-      "dependencies": {
-        "chalk": "^5.6.2",
-        "cli-cursor": "^5.0.0",
-        "cli-spinners": "^3.2.0",
-        "is-interactive": "^2.0.0",
-        "is-unicode-supported": "^2.1.0",
-        "log-symbols": "^7.0.1",
-        "stdin-discarder": "^0.3.2",
-        "string-width": "^8.1.0"
-      },
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
       "engines": {
-        "node": ">=20"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/p-map": {
-      "version": "7.0.4",
+    "packages/craftcms-garnish/node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "cpu": [
+        "arm64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/path-scurry": {
-      "version": "2.0.2",
+    "packages/craftcms-garnish/node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "cpu": [
+        "ia32"
+      ],
       "dev": true,
-      "license": "BlueOak-1.0.0",
-      "dependencies": {
-        "lru-cache": "^11.0.0",
-        "minipass": "^7.1.2"
-      },
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
       "engines": {
-        "node": "18 || 20 || >=22"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/path-type": {
-      "version": "6.0.0",
+    "packages/craftcms-garnish/node_modules/@esbuild/win32-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "cpu": [
+        "x64"
+      ],
       "dev": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
       "engines": {
         "node": ">=18"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
       }
     },
-    "packages/craftcms-cp/node_modules/rimraf": {
-      "version": "6.1.3",
+    "packages/craftcms-garnish/node_modules/@vitest/coverage-v8": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.9.tgz",
+      "integrity": "sha512-G9/lgqibheLVBDRuya45EbsEXTYcWoSG+TLg7i2axuzx0Eq62eXn+aWXyaVdV5vKvFSWd6ywcX8hA7la9Pvu8g==",
       "dev": true,
-      "license": "BlueOak-1.0.0",
+      "license": "MIT",
       "dependencies": {
-        "glob": "^13.0.3",
-        "package-json-from-dist": "^1.0.1"
+        "@bcoe/v8-coverage": "^1.0.2",
+        "@vitest/utils": "4.1.9",
+        "ast-v8-to-istanbul": "^1.0.0",
+        "istanbul-lib-coverage": "^3.2.2",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.2",
+        "obug": "^2.1.1",
+        "std-env": "^4.0.0-rc.1",
+        "tinyrainbow": "^3.1.0"
       },
-      "bin": {
-        "rimraf": "dist/esm/bin.mjs"
+      "funding": {
+        "url": "https://opencollective.com/vitest"
       },
-      "engines": {
-        "node": "20 || >=22"
+      "peerDependencies": {
+        "@vitest/browser": "4.1.9",
+        "vitest": "4.1.9"
       },
-      "funding": {
-        "url": "https://github.com/sponsors/isaacs"
+      "peerDependenciesMeta": {
+        "@vitest/browser": {
+          "optional": true
+        }
       }
     },
-    "packages/craftcms-cp/node_modules/rolldown": {
-      "version": "1.0.0-rc.17",
+    "packages/craftcms-garnish/node_modules/@vitest/expect": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.9.tgz",
+      "integrity": "sha512-vl/rYsUKcBr3SnQn166+XR5ZQcgMx3DQhFWdfli/cWpLnLUmbxZvyrJZotLFUryib+LtArYMSTJ5RbQ57ZqrlA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@oxc-project/types": "=0.127.0",
-        "@rolldown/pluginutils": "1.0.0-rc.17"
-      },
-      "bin": {
-        "rolldown": "bin/cli.mjs"
-      },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "@standard-schema/spec": "^1.1.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "chai": "^6.2.2",
+        "tinyrainbow": "^3.1.0"
       },
-      "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-darwin-x64": "1.0.0-rc.17",
-        "@rolldown/binding-freebsd-x64": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17",
-        "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17",
-        "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17",
-        "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17",
-        "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17",
-        "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17"
+      "funding": {
+        "url": "https://opencollective.com/vitest"
       }
     },
-    "packages/craftcms-cp/node_modules/rolldown-plugin-dts": {
-      "version": "0.23.2",
+    "packages/craftcms-garnish/node_modules/@vitest/mocker": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.9.tgz",
+      "integrity": "sha512-EVkXzBjrPGM+cK8/ANWgBrkUCfJfb38/EfTSO8h7pWvKkyPkpWxvR7BkD2MyItMF62C97zAEoqdpUixwR/e+Rw==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@babel/generator": "8.0.0-rc.3",
-        "@babel/helper-validator-identifier": "8.0.0-rc.3",
-        "@babel/parser": "8.0.0-rc.3",
-        "@babel/types": "8.0.0-rc.3",
-        "ast-kit": "^3.0.0-beta.1",
-        "birpc": "^4.0.0",
-        "dts-resolver": "^2.1.3",
-        "get-tsconfig": "^4.13.7",
-        "obug": "^2.1.1",
-        "picomatch": "^4.0.4"
-      },
-      "engines": {
-        "node": ">=20.19.0"
+        "@vitest/spy": "4.1.9",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
       },
       "funding": {
-        "url": "https://github.com/sponsors/sxzz"
+        "url": "https://opencollective.com/vitest"
       },
       "peerDependencies": {
-        "@ts-macro/tsc": "^0.3.6",
-        "@typescript/native-preview": ">=7.0.0-dev.20260325.1",
-        "rolldown": "^1.0.0-rc.12",
-        "typescript": "^5.0.0 || ^6.0.0",
-        "vue-tsc": "~3.2.0"
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
       },
       "peerDependenciesMeta": {
-        "@ts-macro/tsc": {
-          "optional": true
-        },
-        "@typescript/native-preview": {
-          "optional": true
-        },
-        "typescript": {
+        "msw": {
           "optional": true
         },
-        "vue-tsc": {
+        "vite": {
           "optional": true
         }
       }
     },
-    "packages/craftcms-cp/node_modules/rolldown-plugin-dts/node_modules/@babel/parser": {
-      "version": "8.0.0-rc.3",
+    "packages/craftcms-garnish/node_modules/@vitest/pretty-format": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.9.tgz",
+      "integrity": "sha512-s0iufns3iIFitdgm+YR7g1whCAaGtXz459VS9/PqyKDEEFgYIhsHOQmXgIgDuYCt7DeQmiZT0Qe2OA2p4ZPu5A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@babel/types": "^8.0.0-rc.3"
+        "tinyrainbow": "^3.1.0"
       },
-      "bin": {
-        "parser": "bin/babel-parser.js"
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/@vitest/runner": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.9.tgz",
+      "integrity": "sha512-KXLMDtc7oe70+3mJfGrPUWPesswH+3sTxAMAMl8DG7I8IUQT4XW718dY5ID3vPUcmlu27CcKfY4P3h3I29SLJg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.1.9",
+        "pathe": "^2.0.3"
       },
-      "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+      "funding": {
+        "url": "https://opencollective.com/vitest"
       }
     },
-    "packages/craftcms-cp/node_modules/rolldown-plugin-dts/node_modules/@babel/types": {
-      "version": "8.0.0-rc.3",
+    "packages/craftcms-garnish/node_modules/@vitest/snapshot": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.9.tgz",
+      "integrity": "sha512-Jc7RKGNBo8Z28WYIm0Niej4xdSPByRf6mU58VpHQkd6Zh05rlnA+twjbK5HyeIGHxrzsc3mJgS43uM0CZKzaIA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "@babel/helper-string-parser": "^8.0.0-rc.3",
-        "@babel/helper-validator-identifier": "^8.0.0-rc.3"
+        "@vitest/pretty-format": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/@vitest/spy": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.9.tgz",
+      "integrity": "sha512-fHpsS6mIi+PiEW+vcRVOMkX1oSaPKne3VOclSFICPcGOmfKgXPU5iAah+wcNcj2xPrCCmfq99IDGf+EojhhvhA==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/@vitest/utils": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.9.tgz",
+      "integrity": "sha512-A51o8ymO5PpqlWNnBP9ZHPXDIpuMtTLlGSjN7la4US+LJzoUMyhwjA5QXlm39JexgwHKW4Xjs8Z2d3dLCXOeuA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.1.9",
+        "convert-source-map": "^2.0.0",
+        "tinyrainbow": "^3.1.0"
       },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
       "engines": {
-        "node": "^20.19.0 || >=22.12.0"
+        "node": ">=18"
       }
     },
-    "packages/craftcms-cp/node_modules/semver": {
-      "version": "7.7.4",
+    "packages/craftcms-garnish/node_modules/es-module-lexer": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.1.0.tgz",
+      "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==",
       "dev": true,
-      "license": "ISC",
+      "license": "MIT"
+    },
+    "packages/craftcms-garnish/node_modules/esbuild": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
       "bin": {
-        "semver": "bin/semver.js"
+        "esbuild": "bin/esbuild"
       },
       "engines": {
-        "node": ">=10"
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.7",
+        "@esbuild/android-arm": "0.27.7",
+        "@esbuild/android-arm64": "0.27.7",
+        "@esbuild/android-x64": "0.27.7",
+        "@esbuild/darwin-arm64": "0.27.7",
+        "@esbuild/darwin-x64": "0.27.7",
+        "@esbuild/freebsd-arm64": "0.27.7",
+        "@esbuild/freebsd-x64": "0.27.7",
+        "@esbuild/linux-arm": "0.27.7",
+        "@esbuild/linux-arm64": "0.27.7",
+        "@esbuild/linux-ia32": "0.27.7",
+        "@esbuild/linux-loong64": "0.27.7",
+        "@esbuild/linux-mips64el": "0.27.7",
+        "@esbuild/linux-ppc64": "0.27.7",
+        "@esbuild/linux-riscv64": "0.27.7",
+        "@esbuild/linux-s390x": "0.27.7",
+        "@esbuild/linux-x64": "0.27.7",
+        "@esbuild/netbsd-arm64": "0.27.7",
+        "@esbuild/netbsd-x64": "0.27.7",
+        "@esbuild/openbsd-arm64": "0.27.7",
+        "@esbuild/openbsd-x64": "0.27.7",
+        "@esbuild/openharmony-arm64": "0.27.7",
+        "@esbuild/sunos-x64": "0.27.7",
+        "@esbuild/win32-arm64": "0.27.7",
+        "@esbuild/win32-ia32": "0.27.7",
+        "@esbuild/win32-x64": "0.27.7"
       }
     },
-    "packages/craftcms-cp/node_modules/slash": {
-      "version": "5.1.0",
+    "packages/craftcms-garnish/node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
       "dev": true,
+      "hasInstallScript": true,
       "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
       "engines": {
-        "node": ">=14.16"
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "packages/craftcms-garnish/node_modules/semver": {
+      "version": "7.8.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz",
+      "integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
       },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
+      "engines": {
+        "node": ">=10"
       }
     },
-    "packages/craftcms-cp/node_modules/tinyrainbow": {
+    "packages/craftcms-garnish/node_modules/tinyrainbow": {
       "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.1.0.tgz",
+      "integrity": "sha512-Bf+ILmBgretUrdJxzXM0SgXLZ3XfiaUuOj/IKQHuTXip+05Xn+uyEYdVg0kYDipTBcLrCVyUzAPz7QmArb0mmw==",
       "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=14.0.0"
       }
     },
-    "packages/craftcms-cp/node_modules/tsdown": {
+    "packages/craftcms-garnish/node_modules/tsdown": {
       "version": "0.21.10",
+      "resolved": "https://registry.npmjs.org/tsdown/-/tsdown-0.21.10.tgz",
+      "integrity": "sha512-3wk73yBhZe/wX7REqSdivNQ84TDs1mJ+IlnzrrEREP70xlJ/AEIzqaI04l/TzMKVIdkTdC3CPaADn2Lk/0SkdA==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -24425,6 +25555,171 @@
         }
       }
     },
+    "packages/craftcms-garnish/node_modules/vite": {
+      "version": "7.3.5",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.5.tgz",
+      "integrity": "sha512-KuOaNhcnGFN2zIPGA7wRmzF+lJA1sea7rHq17aiJ++9lzY1WWG6Jpwqwe1KNbRVPIqHmr8GLYx7jbrQcN/7/ww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "^0.27.0",
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3",
+        "postcss": "^8.5.6",
+        "rollup": "^4.43.0",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "lightningcss": "^1.21.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "packages/craftcms-garnish/node_modules/vitest": {
+      "version": "4.1.9",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.9.tgz",
+      "integrity": "sha512-nE3/LEyc0z87uHYLZebqCUOaJr2hdtuPp7BQ4BosVFnfltxgAvMG08NyrSGlPpOUWvR27c5flSmYFTNr78L9GQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.1.9",
+        "@vitest/mocker": "4.1.9",
+        "@vitest/pretty-format": "4.1.9",
+        "@vitest/runner": "4.1.9",
+        "@vitest/snapshot": "4.1.9",
+        "@vitest/spy": "4.1.9",
+        "@vitest/utils": "4.1.9",
+        "es-module-lexer": "^2.0.0",
+        "expect-type": "^1.3.0",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^4.0.0-rc.1",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.1.0",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.1.9",
+        "@vitest/browser-preview": "4.1.9",
+        "@vitest/browser-webdriverio": "4.1.9",
+        "@vitest/coverage-istanbul": "4.1.9",
+        "@vitest/coverage-v8": "4.1.9",
+        "@vitest/ui": "4.1.9",
+        "happy-dom": "*",
+        "jsdom": "*",
+        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/coverage-istanbul": {
+          "optional": true
+        },
+        "@vitest/coverage-v8": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        },
+        "vite": {
+          "optional": false
+        }
+      }
+    },
     "packages/craftcms-graphiql": {
       "name": "@craftcms/graphiql",
       "version": "1.0.0",
diff --git a/packages/craftcms-garnish/.gitignore b/packages/craftcms-garnish/.gitignore
new file mode 100644
index 00000000000..5a2cce0d039
--- /dev/null
+++ b/packages/craftcms-garnish/.gitignore
@@ -0,0 +1,4 @@
+/dist
+/node_modules
+/coverage
+/storybook-static
diff --git a/packages/craftcms-garnish/.nvmrc b/packages/craftcms-garnish/.nvmrc
new file mode 100644
index 00000000000..53d1c14db37
--- /dev/null
+++ b/packages/craftcms-garnish/.nvmrc
@@ -0,0 +1 @@
+v22
diff --git a/packages/craftcms-garnish/.storybook/main.ts b/packages/craftcms-garnish/.storybook/main.ts
new file mode 100644
index 00000000000..151f9aee0c9
--- /dev/null
+++ b/packages/craftcms-garnish/.storybook/main.ts
@@ -0,0 +1,34 @@
+import type {StorybookConfig} from '@storybook/html-vite';
+
+import {dirname} from 'path';
+import {fileURLToPath} from 'url';
+
+/**
+ * Resolve the absolute path of a package. Needed in monorepos so Storybook finds
+ * the hoisted addons/framework regardless of where node_modules ends up.
+ */
+function getAbsolutePath(value: string): string {
+  return dirname(fileURLToPath(import.meta.resolve(`${value}/package.json`)));
+}
+
+/**
+ * Storybook config for @craftcms/garnish.
+ *
+ * Garnish widgets are imperative (`new Modal(container)`, `new DisclosureMenu(trigger)`)
+ * operating on plain DOM — NOT web components — so we use the `html-vite` renderer
+ * (cp uses `web-components-vite`). Each story's `render()` returns an `HTMLElement`
+ * in which the Garnish class is instantiated against the REAL source under `../src`.
+ */
+const config: StorybookConfig = {
+  stories: ['../stories/**/*.stories.@(ts|mdx)'],
+  addons: [
+    getAbsolutePath('@storybook/addon-docs'),
+    getAbsolutePath('@storybook/addon-a11y'),
+    getAbsolutePath('@storybook/addon-themes'),
+  ],
+  framework: {
+    name: getAbsolutePath('@storybook/html-vite'),
+    options: {},
+  },
+};
+export default config;
diff --git a/packages/craftcms-garnish/.storybook/preview.css b/packages/craftcms-garnish/.storybook/preview.css
new file mode 100644
index 00000000000..bf0e582561e
--- /dev/null
+++ b/packages/craftcms-garnish/.storybook/preview.css
@@ -0,0 +1,673 @@
+/**
+ * Global demo styles for @craftcms/garnish stories.
+ *
+ * Migrated from the old `playground/styles.css`. Stories reuse the same `.pg-*`
+ * class names so the imperative widgets (which the package itself renders into
+ * `.modal-shade`, `.hud .tip`, `.menu--disclosure`, etc.) look identical to the
+ * playground. The only structural change from the playground: the event-log
+ * panel is mounted INSIDE each story (`.pg-story` flex layout) instead of being
+ * a single page-fixed panel, so it scopes to the story canvas.
+ */
+
+:root {
+  --bg: #f4f5f7;
+  --surface: #ffffff;
+  --border: #d6d9de;
+  --text: #1c1f24;
+  --muted: #5c636e;
+  --accent: #1f6feb;
+  --accent-text: #ffffff;
+  --good: #1a7f37;
+  --bad: #b42318;
+  --radius: 6px;
+  --shadow: 0 6px 24px rgba(0, 0, 0, 0.18);
+}
+
+/* --- Story layout ------------------------------------------------------- */
+/* Events surface in Storybook's Actions panel, so the canvas is just the demo. */
+.pg-story {
+  font-family:
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    Roboto,
+    sans-serif;
+  color: var(--text);
+  line-height: 1.5;
+  max-width: 60ch;
+}
+
+.pg-story > p {
+  margin: 0 0 1rem;
+  color: var(--muted);
+}
+
+.pg-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.pg-story button {
+  font: inherit;
+  cursor: pointer;
+  padding: 0.45rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  color: var(--text);
+  transition: background 0.12s ease;
+}
+
+.pg-story button:hover {
+  background: #eef0f3;
+}
+
+.pg-story button:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.pg-story code,
+.pg-story kbd {
+  font-family: ui-monospace, 'SFMono-Regular', Menlo, monospace;
+  font-size: 0.85em;
+}
+
+.pg-story code {
+  background: #eef0f3;
+  padding: 0.05rem 0.3rem;
+  border-radius: 4px;
+}
+
+.pg-story kbd {
+  background: #2a2f37;
+  color: #fff;
+  padding: 0.05rem 0.35rem;
+  border-radius: 4px;
+}
+
+/* --- Focusable sample --------------------------------------------------- */
+.pg-focus-sample {
+  margin-top: 1rem;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  padding: 1rem;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+}
+
+.pg-focus-sample > * {
+  padding: 0.35rem 0.6rem;
+  border: 1px solid var(--border);
+  border-radius: 4px;
+  background: #fafbfc;
+  margin: 0;
+}
+
+.pg-focus-sample a {
+  color: var(--accent);
+}
+
+.pg-highlight-focusable {
+  outline: 2px solid var(--good) !important;
+  outline-offset: 1px;
+  background: #e7f6ec !important;
+}
+
+.pg-highlight-keyboard {
+  box-shadow: 0 0 0 2px var(--accent);
+}
+
+/* --- Modal + shade (the part the package itself renders) ---------------- */
+.modal-shade {
+  position: fixed;
+  inset: 0;
+  background: rgba(15, 18, 22, 0.55);
+  z-index: 100;
+  display: none;
+  opacity: 0;
+}
+
+.pg-modal {
+  position: fixed;
+  z-index: 101;
+  display: none;
+  opacity: 0;
+  background: var(--surface);
+  color: var(--text);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  padding: 1.5rem;
+  min-width: 320px;
+  max-width: 90vw;
+  overflow: auto;
+}
+
+.pg-modal h3 {
+  margin-top: 0;
+}
+
+.pg-modal .pg-modal-actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 1rem;
+  flex-wrap: wrap;
+}
+
+.pg-modal button {
+  font: inherit;
+  cursor: pointer;
+  padding: 0.45rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--surface);
+  color: var(--text);
+}
+
+.pg-modal-primary {
+  background: var(--accent) !important;
+  color: var(--accent-text) !important;
+  border-color: var(--accent) !important;
+}
+
+.pg-modal-primary:hover {
+  background: #1a5fce !important;
+}
+
+body.no-scroll {
+  overflow: hidden;
+}
+
+/* Draggable modal: give it a draggable look + a grabbable header. */
+.pg-modal.pg-modal--draggable {
+  cursor: grab;
+  /* Handles must opt out of browser touch gestures so pointer drags work on
+     touch devices (doc 08 §4). */
+  touch-action: none;
+}
+
+.pg-modal-drag-handle {
+  margin: -1.5rem -1.5rem 1rem;
+  padding: 0.75rem 1.5rem;
+  background: #11151b;
+  color: #e6e9ee;
+  border-radius: var(--radius) var(--radius) 0 0;
+  cursor: grab;
+  touch-action: none;
+  user-select: none;
+}
+
+/* The resize handle Modal injects (.resizehandle) — give it a visible target. */
+.pg-modal .resizehandle {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  width: 20px;
+  height: 20px;
+  cursor: nwse-resize;
+  touch-action: none;
+  color: var(--muted);
+  display: flex;
+  align-items: flex-end;
+  justify-content: flex-end;
+  padding: 2px;
+}
+
+.pg-modal .resizehandle svg {
+  width: 14px;
+  height: 14px;
+}
+
+/* --- Standalone drag arena --------------------------------------------- */
+.pg-drag-arena {
+  position: relative;
+  margin-top: 1rem;
+  height: 280px;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+  background: repeating-linear-gradient(
+    45deg,
+    #fafbfc,
+    #fafbfc 10px,
+    #f2f4f7 10px,
+    #f2f4f7 20px
+  );
+  overflow: hidden;
+}
+
+.pg-drag-box {
+  position: absolute;
+  width: 130px;
+  min-height: 56px;
+  padding: 0.5rem;
+  border-radius: var(--radius);
+  font-size: 0.8rem;
+  font-weight: 600;
+  color: #fff;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  box-shadow: var(--shadow);
+  cursor: grab;
+  user-select: none;
+  /* Required so pointer drags aren't eaten by touch scrolling/panning. */
+  touch-action: none;
+}
+
+.pg-drag-box:active {
+  cursor: grabbing;
+}
+
+.pg-drag-box--move {
+  background: var(--good);
+}
+
+.pg-drag-box--xlock {
+  background: #0a6d2f;
+}
+
+.pg-drag-box--base {
+  background: var(--accent);
+}
+
+.pg-drag-box--scroll {
+  background: #b85c00;
+}
+
+/* --- Auto-scroll container ---------------------------------------------- */
+.pg-scroll-container {
+  position: relative;
+  margin-top: 1rem;
+  height: 260px;
+  overflow: auto;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: #fafbfc;
+}
+
+.pg-scroll-tall {
+  position: relative;
+  height: 1100px;
+  padding: 1rem;
+}
+
+.pg-scroll-filler {
+  margin: 0;
+  padding: 8rem 0;
+  text-align: center;
+  color: var(--muted);
+}
+
+.pg-scroll-container .pg-drag-box--scroll {
+  position: absolute;
+  top: 20px;
+  left: 20px;
+}
+
+/* --- Drag with helpers -------------------------------------------------- */
+.pg-helper-list {
+  margin-top: 1rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.pg-helper-item {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  padding: 0.65rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: #fafbfc;
+  font-weight: 600;
+  font-size: 0.85rem;
+  cursor: grab;
+  user-select: none;
+  /* Required so pointer drags aren't eaten by touch scrolling/panning. */
+  touch-action: none;
+}
+
+.pg-helper-item:active {
+  cursor: grabbing;
+}
+
+.pg-helper-grip {
+  color: var(--muted);
+  font-size: 1.1rem;
+  line-height: 1;
+  letter-spacing: -0.15em;
+}
+
+/* The clone Drag creates gets the .draghelper class; give it a lifted look. */
+.draghelper {
+  box-shadow: var(--shadow);
+  opacity: 0.92;
+  border-color: var(--accent) !important;
+  cursor: grabbing;
+}
+
+/* --- DragDrop / drop targets -------------------------------------------- */
+.pg-dragdrop-layout {
+  margin-top: 1rem;
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 1rem;
+  align-items: start;
+}
+
+.pg-dragdrop-chips {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+  background: #fafbfc;
+}
+
+.pg-dragdrop-chip {
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--radius);
+  background: var(--accent);
+  color: var(--accent-text);
+  font-weight: 600;
+  font-size: 0.85rem;
+  text-align: center;
+  cursor: grab;
+  user-select: none;
+  /* Required so pointer drags aren't eaten by touch scrolling/panning. */
+  touch-action: none;
+}
+
+.pg-dragdrop-chip:active {
+  cursor: grabbing;
+}
+
+.pg-dragdrop-zones {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.pg-dropzone {
+  padding: 1.1rem 0.75rem;
+  border: 2px dashed var(--border);
+  border-radius: var(--radius);
+  text-align: center;
+  font-weight: 600;
+  font-size: 0.85rem;
+  color: var(--muted);
+  background: var(--surface);
+  transition:
+    background 0.12s ease,
+    border-color 0.12s ease,
+    color 0.12s ease;
+}
+
+/* DragDrop toggles `activeDropTargetClass` (default: 'active') on hover. */
+.pg-dropzone.active {
+  border-color: var(--good);
+  border-style: solid;
+  background: #e7f6ec;
+  color: var(--good);
+}
+
+/* Briefly flashed by the demo when a drop lands on a zone. */
+.pg-dropzone.pg-dropzone--hit {
+  border-color: var(--accent);
+  background: #e6f0ff;
+  color: var(--accent);
+}
+
+/* --- DragSort / reorderable list ---------------------------------------- */
+.pg-sort-list {
+  margin-top: 1rem;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+}
+
+.pg-sort-item {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  padding: 0.65rem 0.9rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: #fafbfc;
+  font-weight: 600;
+  font-size: 0.85rem;
+  cursor: grab;
+  user-select: none;
+  /* Required so pointer drags aren't eaten by touch scrolling/panning. */
+  touch-action: none;
+}
+
+.pg-sort-item:active {
+  cursor: grabbing;
+}
+
+.pg-sort-grip {
+  color: var(--muted);
+  font-size: 1.1rem;
+  line-height: 1;
+  letter-spacing: -0.15em;
+}
+
+/* The placeholder DragSort inserts at the landing spot. */
+.pg-sort-insertion {
+  list-style: none;
+  height: 2.5rem;
+  border: 2px dashed var(--accent);
+  border-radius: var(--radius);
+  background: #e6f0ff;
+}
+
+/* --- HUD / anchored popover -------------------------------------------- */
+.pg-hud-arena {
+  position: relative;
+  margin-top: 1rem;
+  height: 360px;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+  background: repeating-linear-gradient(
+    -45deg,
+    #fafbfc,
+    #fafbfc 10px,
+    #f2f4f7 10px,
+    #f2f4f7 20px
+  );
+}
+
+.pg-hud-trigger {
+  position: absolute;
+}
+
+/* The HUD container — the HUD JS sets display/position/left/top inline. */
+.hud {
+  z-index: 102;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+}
+
+.hud .body {
+  margin: 0;
+}
+
+.hud .main-container {
+  overflow: hidden;
+}
+
+.hud .main {
+  padding: 0.9rem 1.1rem;
+  min-width: 200px;
+  max-width: 260px;
+}
+
+/* The tip/arrow. The JS positions it along the relevant edge (the perpendicular
+   offset), and the orientation class (tip-top/-bottom/-left/-right) pins it to
+   the correct edge. */
+.hud .tip {
+  position: absolute;
+  width: 30px;
+  height: 30px;
+  pointer-events: none;
+}
+
+.hud .tip::after {
+  content: '';
+  position: absolute;
+  left: 8px;
+  top: 8px;
+  width: 14px;
+  height: 14px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  transform: rotate(45deg);
+}
+
+.hud .tip-top {
+  top: -15px;
+}
+
+.hud .tip-bottom {
+  bottom: -15px;
+}
+
+.hud .tip-left {
+  left: -15px;
+}
+
+.hud .tip-right {
+  right: -15px;
+}
+
+.pg-hud-content h4 {
+  margin: 0 0 0.4rem;
+  font-size: 0.95rem;
+}
+
+.pg-hud-content p {
+  margin: 0 0 0.75rem;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.hud-shade {
+  position: fixed;
+  inset: 0;
+  z-index: 100;
+  background: rgba(15, 18, 22, 0.25);
+  display: none;
+}
+
+/* --- DisclosureMenu / dropdown menu ------------------------------------ */
+.pg-disc-trigger {
+  font-weight: 600;
+}
+
+/* The menu panel — the JS sets display/top/left/right/opacity inline. */
+.menu.menu--disclosure {
+  position: absolute;
+  display: none;
+  z-index: 102;
+  min-width: 180px;
+  padding: 4px;
+  background: var(--surface);
+  color: var(--text);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow: var(--shadow);
+  opacity: 0;
+}
+
+.menu.menu--disclosure.visible {
+  display: block;
+}
+
+.menu--disclosure ul {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.menu--disclosure h3 {
+  margin: 0.4rem 0 0.2rem;
+  padding: 0 0.6rem;
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--muted);
+}
+
+.menu--disclosure hr {
+  margin: 0.35rem 0;
+  border: none;
+  border-top: 1px solid var(--border);
+}
+
+.menu--disclosure .menu-item {
+  display: block;
+  width: 100%;
+  text-align: left;
+  padding: 0.4rem 0.6rem;
+  border: 0;
+  border-radius: 5px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.menu--disclosure .menu-item:hover,
+.menu--disclosure .menu-item:focus {
+  background: var(--accent-soft, #eef2ff);
+  outline: none;
+}
+
+.menu--disclosure .menu-item.sel {
+  font-weight: 600;
+}
+
+.menu--disclosure .menu-item.error {
+  color: #c0392b;
+}
+
+.menu--disclosure .menu-item.disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+.menu--disclosure .search-container {
+  padding: 0.25rem 0.25rem 0.5rem;
+}
+
+.menu--disclosure .search-container input {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 0.35rem 0.5rem;
+  border: 1px solid var(--border);
+  border-radius: 5px;
+  font: inherit;
+}
+
+.menu--disclosure .clear-btn {
+  display: none;
+}
+
+/* Hidden / filtered items + their empty groups/separators collapse. */
+.menu--disclosure li.hidden,
+.menu--disclosure li.filtered,
+.menu--disclosure ul.hidden,
+.menu--disclosure hr.hidden,
+.menu--disclosure h3.hidden {
+  display: none;
+}
diff --git a/packages/craftcms-garnish/.storybook/preview.ts b/packages/craftcms-garnish/.storybook/preview.ts
new file mode 100644
index 00000000000..e7ec2d44b9d
--- /dev/null
+++ b/packages/craftcms-garnish/.storybook/preview.ts
@@ -0,0 +1,45 @@
+import type {HtmlRenderer, Preview} from '@storybook/html-vite';
+import {withThemeByDataAttribute} from '@storybook/addon-themes';
+import './preview.css';
+
+/**
+ * Global Storybook config for @craftcms/garnish.
+ *
+ * The global demo styles (modal/shade, drag arena/boxes, HUD tip, menu panel,
+ * the event-log panel) are migrated from the old `playground/styles.css` into
+ * `preview.css`, imported here so every story shares them.
+ */
+const preview: Preview = {
+  parameters: {
+    controls: {
+      expanded: true,
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+    options: {
+      storySort: {
+        method: 'alphabetical',
+      },
+    },
+    a11y: {
+      // 'todo' surfaces a11y violations in the UI without failing the build —
+      // these are imperative widget demos, not production-accessible markup.
+      test: 'todo',
+    },
+  },
+  decorators: [
+    withThemeByDataAttribute<HtmlRenderer>({
+      themes: {
+        light: 'light',
+        dark: 'dark',
+      },
+      defaultTheme: 'light',
+      attributeName: 'data-theme',
+    }),
+  ],
+  tags: ['autodocs'],
+};
+
+export default preview;
diff --git a/packages/craftcms-garnish/README.md b/packages/craftcms-garnish/README.md
new file mode 100644
index 00000000000..fe68277bc03
--- /dev/null
+++ b/packages/craftcms-garnish/README.md
@@ -0,0 +1,368 @@
+# @craftcms/garnish
+
+Modern, tree-shakeable TypeScript rewrite of Craft CMS's Garnish UI library.
+
+It ships **two surfaces from one package**:
+
+- A **modern**, jQuery-free, ESM-only API of native `class`es, native events, and
+  tree-shakeable utilities — the preferred surface for new code.
+- An opt-in **compat** layer (`@craftcms/garnish/compat`) that restores the legacy
+  `Garnish.Base.extend()` / `this.base()` / jQuery authoring contract on top of the
+  same modern core, so existing Craft plugins can adopt it with (near) zero changes
+  and migrate incrementally.
+
+## Features
+
+- jQuery-free modern core (the `.` entry never imports or touches jQuery)
+- Native ES classes with a real `extends` / `super` model
+- Object pub/sub + namespaced DOM listeners that preserve the legacy event grammar
+- Accessible, animated `Modal` (focus trapping, ARIA backgrounding, Web Animations
+  API fades that respect `prefers-reduced-motion`)
+- A broad utility surface (DOM, focus, ARIA, forms, animation, environment helpers)
+- Full TypeScript types
+- An opt-in compat layer that wraps every class so `.extend()` / `init` /
+  `this.base()` / jQuery args keep working, and installs a legacy-shaped
+  `window.Garnish`
+
+## Installation
+
+```bash
+npm install @craftcms/garnish
+```
+
+jQuery is an **optional peer dependency** — required only by the `compat` entry, and
+only at runtime. The modern `.` entry never needs it.
+
+## Usage
+
+### Mode A — Modern (recommended for new code)
+
+Import named exports. ES classes, native events, no jQuery. Anything you don't
+import is tree-shaken away.
+
+```ts
+import {Modal} from '@craftcms/garnish';
+
+const el = document.querySelector('#my-modal')!;
+const modal = new Modal(el, {
+  closeOtherModals: true,
+  hideOnEsc: true,
+  onShow: () => console.log('shown'),
+});
+
+// Subscribe to events with the native emitter:
+modal.on('hide', () => console.log('hidden'));
+modal.on('fadeOut.myPlugin', () => cleanup());
+modal.off('.myPlugin'); // remove everything in that namespace
+
+// Later:
+modal.hide();
+modal.destroy();
+```
+
+Subclass with plain `class extends` and `super`:
+
+```ts
+import {Modal, type ModalSettings} from '@craftcms/garnish';
+
+class ConfirmModal extends Modal {
+  constructor(container: Element, settings?: Partial<ModalSettings>) {
+    super(container, settings);
+    // ...your setup...
+  }
+
+  override onShow(): void {
+    super.onShow(); // preserves the `show` event + onShow callback
+    // ...custom behavior...
+  }
+}
+```
+
+Utilities are individual named exports — import only what you use:
+
+```ts
+import {trapFocusWithin, releaseFocusWithin, getPostData} from '@craftcms/garnish';
+```
+
+#### Dragging — `BaseDrag` / `DragMove`
+
+`BaseDrag` is the jQuery-free drag foundation (Pointer Events, native auto-scroll).
+`DragMove` is a thin subclass that positions the dragged element under the cursor.
+Drag handles need `touch-action: none` so the browser doesn't eat the gesture on
+touch devices.
+
+```ts
+import {DragMove} from '@craftcms/garnish';
+
+const box = document.querySelector('#draggable')!;
+box.style.touchAction = 'none'; // required for touch/pen
+
+const dragger = new DragMove(box, {
+  // axis: 'x',                 // optionally lock to one axis
+  // handle: '.drag-handle',    // drag only by a child selector
+  onDragStart: () => console.log('start'),
+  onDrag: () => console.log('moving'),
+  onDragStop: () => console.log('stop'),
+});
+
+dragger.on('drag', () => {/* same events are also emitted */});
+// later: dragger.destroy();
+```
+
+For full control, use `BaseDrag` directly and position the element yourself in
+`onDrag` (read `mouseX/mouseY`/`mouseOffsetX/mouseOffsetY` off the dragger).
+
+#### Helpers &amp; drop targets — `Drag` / `DragDrop`
+
+`Drag` picks up the selected element(s): on drag start it builds floating
+*helper* clones that trail the cursor with lag, and on drop you choose what
+happens — animate them back to their source (`returnHelpersToDraggees()`, a Web
+Animations API tween that respects `prefers-reduced-motion`) or fade them out
+(`fadeOutHelpers()`). `DragDrop` adds drop targets on top: while dragging, the
+target under the cursor is highlighted (its `activeDropTargetClass` is toggled)
+and `onDropTargetChange` fires; there is no separate `drop` event — read
+`$activeDropTarget` inside your own `dragStop` handler to perform the drop.
+
+```ts
+import {DragDrop} from '@craftcms/garnish';
+
+const dd = new DragDrop({
+  dropTargets: '.dropzone', // selector, element(s), or a () => elements fn
+  onDropTargetChange: (active) => console.log('over:', active),
+  onDragStop() {
+    if (dd.$activeDropTarget) {
+      // a raw HTMLElement | null — NOT a jQuery object (drop the `[0]`)
+      console.log('dropped on', dd.$activeDropTarget);
+    }
+    dd.returnHelpersToDraggees(); // send the helper clone home
+  },
+});
+dd.addItems(document.querySelectorAll('.chip')); // items added after construction
+```
+
+As with `BaseDrag`, draggable items and handles need `touch-action: none`.
+
+#### Sortable lists — `DragSort`
+
+`DragSort` is the sortable-list dragger built on `Drag`: drag an item to reorder it
+within its container, with **live insertion feedback** — as the cursor moves, the
+dragged item (and an optional `insertion` placeholder) is re-inserted into the DOM at
+the spot it will land, so the surrounding items reflow in real time. On drop the new
+order is committed and `sortChange` fires if anything moved. `insertionPointChange`
+fires whenever the landing spot moves.
+
+```ts
+import {DragSort} from '@craftcms/garnish';
+
+const list = document.querySelector('#sortable')!;
+const sort = new DragSort(list.querySelectorAll('li'), {
+  container: list, // the sort is constrained to this (heighted) container
+  axis: 'y', // single-column list
+  insertion: () => {
+    const ph = document.createElement('li');
+    ph.className = 'insertion';
+    return ph; // a placeholder shown at the landing spot
+  },
+  onInsertionPointChange: () => console.log('insertion moved'),
+  onSortChange: () => console.log('new order committed'),
+  // gate where items may land:
+  // canInsertBefore: (item) => !item.classList.contains('locked'),
+});
+sort.on('sortChange', () => persistOrder());
+```
+
+`magnetStrength > 1` rubber-bands the helper toward the dragged item's home;
+`moveTargetItemToFront` keeps a multi-select drag's target leading the block. As with
+`BaseDrag`, the sortable items / handles need `touch-action: none`.
+
+#### Anchored popovers — `HUD`
+
+`HUD` is the anchored popover/bubble. It attaches to a trigger element, picks one of
+four orientations (`bottom` / `top` / `right` / `left`) from the available clearance
+around the trigger, draws a tip pointing back at it, follows the trigger on
+scroll/resize, traps `Tab` focus between the trigger and the body, and registers a
+UI layer + Escape shortcut (the same `UiLayerManager` `Modal` uses). Append your
+content into `hud.$main` — a raw `HTMLElement`, not a jQuery object.
+
+```ts
+import {HUD} from '@craftcms/garnish';
+
+const addBtn = document.querySelector('#add-btn')!;
+const hud = new HUD(addBtn, {
+  hudClass: 'hud fld-library-hud',
+  orientations: ['right', 'bottom', 'left'],
+  showOnInit: false,
+});
+
+hud.on('show', () => hud.$main!.append(library)); // $main is an HTMLElement
+hud.on('hide', () => addBtn.focus());
+addBtn.addEventListener('click', () => hud.show());
+// hud.toggle();  hud.updateSizeAndPosition();  hud.destroy();
+```
+
+The constructor mirrors the legacy shape — `new HUD(trigger, bodyContents?, settings?)`,
+with a `new HUD(trigger, settings)` param shift — so a legacy
+`new Garnish.HUD($addBtn, {...})` call ports across unchanged.
+
+#### Dropdown menus — `DisclosureMenu`
+
+`DisclosureMenu` is the disclosure dropdown/menu: a trigger button (carrying
+`aria-controls` / `aria-expanded`) paired with a menu panel referenced by that id.
+It anchors the panel below the trigger (flipping above when there's no room),
+aligns it left/center/right, manages full keyboard navigation + type-ahead search
+and focus, registers a UI layer + Escape shortcut, dismisses on an outside click,
+and exposes item/group builders (`addItem` / `addGroup` / `addHr`) consumers use to
+populate it. An optional `withSearchInput` filters items live.
+
+```ts
+import {DisclosureMenu} from '@craftcms/garnish';
+
+// <button aria-controls="actions" aria-expanded="false">Actions ▾</button>
+// <div id="actions" class="menu menu--disclosure"><ul>…</ul></div>
+const menu = new DisclosureMenu(document.querySelector('button')!);
+
+menu.addItem({label: 'Rename', onActivate: (el) => rename(el)});
+const group = menu.addGroup('Danger zone');
+menu.addItem({label: 'Delete', destructive: true, onActivate: () => remove()}, group);
+
+menu.on('show', () => console.log('opened'));
+// menu.show();  menu.hide();  menu.isExpanded();  menu.destroy();
+```
+
+Selection is per-item: each item's `onActivate` / `callback` runs on activation,
+then the menu hides. `DisclosureMenu.getInstance(triggerOrContainer)` is the native
+replacement for the legacy `$el.data('disclosureMenu')`. A legacy
+`new Garnish.DisclosureMenu($trigger, settings)` call ports across unchanged.
+
+**No-jQuery guarantee:** importing from `@craftcms/garnish` (the `.` entry) never
+pulls in jQuery, never reads `window.jQuery`/`$`, and never assigns
+`window.Garnish`. Those behaviors live exclusively in the `compat` entry.
+
+### Mode B — Compat / upgrade path (for existing plugins)
+
+The compat entry restores the legacy authoring contract: a `window.Garnish` global,
+`.extend()`-able classes, `init()` as the constructor, `this.base()` super-dispatch,
+and jQuery-collection constructor arguments.
+
+#### How to ADD the compat layer
+
+Add a single side-effecting import at your bundle entry point:
+
+```ts
+import '@craftcms/garnish/compat';
+
+// `window.Garnish` is now populated. Existing code keeps working unchanged:
+Craft.MyModal = Garnish.Modal.extend({
+  init(container) {
+    this.base(container, {closeOtherModals: true}); // calls Modal's constructor
+  },
+  onShow() {
+    this.base(); // calls Modal.prototype.onShow
+    // ...custom behavior...
+  },
+});
+
+new Craft.MyModal($('#my-modal')); // jQuery collection args are unwrapped for you
+```
+
+That import installs `window.Garnish` (guarded by
+`if (typeof window.Garnish === 'undefined')`, so it never clobbers an existing
+legacy-bundle global). jQuery must be present on the global scope for the
+jQuery-shaped parts (`$container` args, `$win`/`$doc`/`$bod`, `isJquery`,
+`$.fn.activate/textchange/resize` sugar); the layer throws a clear, actionable
+error if a jQuery-only feature is used while jQuery is absent.
+
+For programmatic (non-auto-install) use, call `installGarnishCompat()` or work with
+the named `compatify` / `GarnishCompat` exports directly:
+
+```ts
+import {installGarnishCompat, compatify} from '@craftcms/garnish/compat';
+import {Modal} from '@craftcms/garnish';
+
+const Garnish = installGarnishCompat();
+const LegacyModal = compatify(Modal); // one class, without the global
+```
+
+#### How to DROP the compat layer
+
+The compat layer is **opt-in and tree-shakeable** — you remove it by removing its
+import. Migrate one class at a time:
+
+1. Convert a `Garnish.X.extend({init(){…}})` subclass to
+   `class extends X { constructor(){ super(); … } }`, replacing `this.base(...)`
+   with `super.method(...)` and importing the modern named export
+   (`import {Modal} from '@craftcms/garnish'`). Modern and compat code can coexist
+   in the same bundle during the transition.
+2. Once nothing depends on `window.Garnish` or the legacy affordances, **delete the
+   `import '@craftcms/garnish/compat'` line.** Tree-shaking then drops all of the
+   compat code, the `window.Garnish` global, and the jQuery peer requirement.
+
+## Documentation
+
+- [`docs/06-api-reference.md`](docs/06-api-reference.md) — the public API cheat sheet
+  (signatures + one-liners) for `Base`, `Modal`, the drag classes (`BaseDrag`,
+  `DragMove`, `Drag`, `DragDrop`), the `Garnish` namespace utilities, and the compat
+  exports.
+- [`docs/00-migration-plan.md`](docs/00-migration-plan.md) §2 — the compat design and
+  upgrade-path rationale.
+- [`docs/01-core-design.md`](docs/01-core-design.md) — core architecture and the
+  utility-by-utility port plan.
+- [`docs/03-modal-slice.md`](docs/03-modal-slice.md) — the Modal PoC contract.
+
+Public API symbols carry TSDoc — your editor's IntelliSense is the fastest reference.
+
+## Development
+
+```bash
+npm run dev          # Storybook dev server at http://localhost:6006
+npm run storybook    # alias of `npm run dev`
+npm run build:storybook  # static Storybook build
+npm run build        # production build (dual `.` + `/compat` entries)
+npm run build:watch  # tsdown watch build
+npm run test         # Vitest suite
+npm run check:types  # tsc --noEmit (includes stories)
+npm run format       # Prettier (writes ./src ./tests ./stories ./.storybook)
+```
+
+Interactive component demos live in **Storybook** (`npm run dev` or
+`npm run storybook` → http://localhost:6006), with one story file per component
+under `stories/`. Stories import the real source from `../src`, so edits
+hot-reload instantly. See [`docs/17-storybook-notes.md`](docs/17-storybook-notes.md)
+for how stories are organized, the Actions-panel event logger, and how to add a story
+when porting a new component.
+
+## Status
+
+This is the vertical-slice proof of concept. The modern core, `Base`, `Modal`, the
+drag foundation, and the compat layer are complete and tested.
+
+- **`BaseDrag` / `DragMove`** are implemented (Pointer Events, native auto-scroll)
+  and available as named exports.
+- **`Drag` / `DragDrop` / `DragSort`** are **supported** and available as named
+  exports. `Drag` adds helper clones + return-to-source / fade-out (Web Animations
+  API, reduced-motion aware); `DragDrop` adds drop targets + hit detection; `DragSort`
+  adds sortable lists with live insertion feedback (the `_getClosestItem` spatial
+  hit-test + midpoint caching, the `insertion` placeholder, and `sortChange` /
+  `insertionPointChange` events).
+- **`Modal` `draggable` / `resizable`** are **supported** (still `false` by default).
+  A draggable modal uses `DragMove` on its container — or on the element matched by
+  `dragHandleSelector` for a header-only handle — and a resizable modal uses
+  `BaseDrag` on a generated corner handle. (They previously threw; that limitation
+  is gone.)
+- **`HUD`** is **supported** (Phase 3): the anchored popover with smart 4-way
+  positioning, a tip/arrow, scroll-follow, focus trapping, and `UiLayerManager`
+  layer + Escape integration. This was the last `FieldLayoutDesigner` overlay
+  blocker.
+- **`DisclosureMenu`** is **supported** (Phase 3): the disclosure dropdown/menu
+  with above/below + left/center/right positioning, full keyboard navigation +
+  type-ahead search, focus management, `UiLayerManager` layer + Escape, an
+  optional search input, and the item/group builder surface (~19 CP sites depend
+  on it). It was the largest remaining component (~1,008 LOC).
+
+The **drag cluster is COMPLETE** — `BaseDrag`, `DragMove`, `Drag`, `DragDrop`, and
+`DragSort` are all ported, with no drag modules pending. The overlay/menu set
+(`Modal` + `HUD` + `DisclosureMenu`) is ported too.
+
+## License
+
+MIT © Pixel & Tonic, Inc.
diff --git a/packages/craftcms-garnish/docs/00-migration-plan.md b/packages/craftcms-garnish/docs/00-migration-plan.md
new file mode 100644
index 00000000000..a4a2f38cb5e
--- /dev/null
+++ b/packages/craftcms-garnish/docs/00-migration-plan.md
@@ -0,0 +1,318 @@
+# Garnish Migration Plan & Effort Estimate
+
+> **Status: Authoritative plan — read this first.** This document is the go/no-go reference for converting the entire
+> legacy Garnish library (`packages/craftcms-legacy/garnish/`) to the modern, jQuery-free TypeScript/ESM package
+> (`packages/craftcms-garnish/`, published as `@craftcms/garnish`). It synthesizes the four design docs in this folder
+> (01 core design, 02 dependency graph, 03 Modal slice, 04 scaffold) plus a source sanity-check of the hard modules,
+> and turns them into a phased plan, a per-module effort table, and a cutover strategy.
+>
+> Companion docs: **01** is the core contract, **02** is the dependency/jQuery analysis, **03** is the Modal PoC
+> template, **04** is the package toolchain. This doc references them rather than repeating them.
+
+---
+
+## 1. Executive summary
+
+We are rebuilding Garnish as two layers shipped from one package. The **modern core + components** (`@craftcms/garnish`)
+is a clean ESM/TypeScript rewrite: native `class extends` instead of Dean Edwards `Base.extend()`, a hand-written
+emitter instead of `jQuery.on/off/trigger`, native DOM APIs instead of jQuery collections, and the Web Animations API
+instead of Velocity. It is tree-shakeable, zero-runtime-dependency, and the surface every new Craft feature should
+target. A **separate, opt-in compatibility layer** (`@craftcms/garnish/compat`) restores the entire legacy authoring
+contract — `Garnish.Base.extend(instance, static)`, `init()`-as-constructor, `this.base()` super-calls, jQuery-collection
+arguments (`$container`), namespaced jQuery-style events, `window.Garnish`, and `isJquery` — by mechanically wrapping the
+modern classes. A plugin author keeps working unchanged by importing compat; they "drop it" by moving to the modern
+constructor/`extends` API at their own pace. Nothing forces a flag-day rewrite of the ~107 consumer files.
+
+The two packages **coexist**: the legacy `garnish` webpack bundle keeps shipping the jQuery library to the legacy CP
+surface until the modern package reaches parity, and the modern package is adopted incrementally — first by the Inertia/Vue
+CP and new code, then by legacy modules wrapped through compat. The legacy webpack `garnish` build is retired only at the
+final cutover, once every consumer resolves `Garnish` from the new package (directly or via compat) and visual-regression
+parity is proven on the real CP.
+
+The strategy is deliberately **leaves-first** (per doc 02's topological order): foundation core first, then the drag
+system and overlays, then selection/menus, then form inputs, then cutover. The two load-bearing risks are (a) the compat
+layer faithfully reproducing `.extend()` + `this.base()`, and (b) the focusable-element matcher and animation parity. Both
+are addressed below with explicit mitigations and test budgets.
+
+---
+
+## 2. The compat layer design (`@craftcms/garnish/compat`)
+
+The compat layer is the single biggest determinant of "easy upgrade path." It must let an unmodified legacy module —
+`Craft.DeleteUserModal = Garnish.Modal.extend({ init, onShow, destroy }, { defaults })` — run against the modern
+`class Modal`. It is **opt-in**: importing it has side effects (it populates `window.Garnish` and wraps every class), and
+not importing it gives you the clean modern surface with zero legacy weight.
+
+### 2.1 How a plugin author adds or drops it
+
+| Scenario | What they do |
+| --- | --- |
+| **Legacy plugin, no changes** | `import '@craftcms/garnish/compat';` once at bundle entry. This assigns `window.Garnish` with `.extend()`-able, jQuery-shaped classes. All existing `Garnish.X.extend({...})` and `$container` code keeps working. (Or: keep consuming the legacy webpack `garnish` global until it is retired — see §5.) |
+| **Incremental migration** | Author migrates one class at a time from `Garnish.Modal.extend({init(){...}})` to `class extends Modal { constructor(){ super(); ... } }`, importing the modern named export `import {Modal} from '@craftcms/garnish'`. Compat and modern can be mixed in the same bundle during transition. |
+| **Fully modern** | Drop the `import '@craftcms/garnish/compat'` line entirely. Tree-shaking then removes the compat code and the `window.Garnish` global. |
+
+### 2.2 The wrapping mechanism — `compatify(ModernClass)`
+
+The core of the compat layer is a single higher-order function that takes a modern ES class and returns a legacy-shaped
+constructor that supports `.extend(instance, static)`. Per doc 01 §1.3, the modern core keeps plain constructors and
+stable method names precisely so this can be mechanical.
+
+```ts
+// compat/extend.ts  (sketch — illustrative, not final code)
+type ModernCtor = abstract new (...args: any[]) => object;
+
+interface LegacyCtor {
+  new (...args: any[]): any;
+  extend(instance?: object, statics?: object): LegacyCtor;
+}
+
+function compatify(Modern: ModernCtor): LegacyCtor { /* returns Base-shaped ctor */ }
+```
+
+It restores each legacy behavior as follows:
+
+- **`.extend(instance, static)` → a subclass.** `compatify` returns a constructor exposing a static `extend(instance,
+  static)` that builds a new subclass of the modern class. `instance` members are copied onto the subclass prototype;
+  `static` members onto the constructor. This reproduces Dean Edwards `lib/Base.js` semantics (the version-1.1a file we
+  inspected) but backed by a real prototype chain instead of `new this()` prototype cloning.
+
+- **`init` → constructor.** Legacy `Garnish.Base`'s constructor calls `this.init.apply(this, arguments)`. The modern core
+  dropped that trampoline (doc 01 §1.2). The compat subclass therefore defines a `constructor(...args)` that calls
+  `super(...args)` and then, if the `instance` object supplied an `init`, invokes `this.init(...args)`. Subclass authors
+  keep writing `init`, never `constructor`.
+
+- **`this.base(...)` synthesis.** This is the subtle part. In `lib/Base.js` the `extend` wrapper detects `/\bbase\b/` in a
+  method's source and, at call time, sets `this.base = <ancestor method>`, runs the override, then restores the previous
+  `this.base`. The compat layer reproduces this exactly: when copying an `instance` method that references `base`, wrap it
+  so that on entry it sets `this.base` to the **prototype method it is overriding** (found by walking the modern prototype
+  chain, i.e. `Object.getPrototypeOf(subclassProto)[name]`), bound to `this`, and restores the prior `this.base` on exit
+  (try/finally for re-entrancy). The `/\bbase\b/` source-sniff and the save/restore dance are copied verbatim — they are
+  observable and re-entrant (nested super-calls rely on the restore). For TypeScript-authored migrators we recommend
+  `super.method()` instead; `this.base` is a compat-only affordance.
+
+- **jQuery-collection args (`$container`, `$trigger`, `items`).** Modern constructors accept `Element | EventTarget |
+  string | null`. Compat wraps the constructor to coerce any incoming jQuery collection (or selector string) to the native
+  input the modern class expects (`jq[0]` / `Array.from(jq)`), and conversely exposes legacy `$`-prefixed properties
+  (`this.$container`, `this.$trigger`, `this.$shade`) as jQuery wrappers around the modern native references via a getter.
+  This requires jQuery as a **peer dependency of the compat entry only** (declared per doc 04 in `package.json`
+  `peerDependencies` and `tsdown` `deps.neverBundle`); the modern entry stays jQuery-free.
+
+- **`window.Garnish`.** Compat builds the legacy-shaped global by taking the modern `Garnish` namespace object (doc 01
+  §6.1), running `compatify` over each class (`Base`, `Modal`, `HUD`, ...), re-adding the jQuery-only members (`$win`,
+  `$doc`, `$bod`, `$scrollContainer`, `isJquery`, the `$.fn.activate/textchange/resize` chaining sugar, the deprecated
+  `Menu`/`ShortcutManager` aliases), calling `initGarnish()` to attach the manager singletons, and assigning the result to
+  `window.Garnish` under the same guard the legacy code uses (`if (typeof window.Garnish === 'undefined')`).
+
+- **`isJquery`.** Dropped from core (doc 01 §4.B); restored in compat as `(v) => v instanceof jQuery`.
+
+- **jQuery-style namespaced events.** The modern emitter already preserves the legacy event-string grammar verbatim
+  (doc 01 §2.1 — space-split for pub/sub, comma-split for `addListener`, first-`.` namespace split) and the trigger-object
+  key precedence (§2.3). So `on('show.myns', fn)` / `off('.myns')` and `addListener(el, 'click.foo', fn)` already behave
+  identically; compat does **not** need to special-case them. Compat only adds the jQuery `$.event.special`
+  `activate/textchange/resize` chaining sugar (`$el.activate(fn)`), routing it to the core `install*` functions (§3 of
+  doc 01).
+
+### 2.3 Compat layer effort
+
+Treat compat as one substantial deliverable, not free. It needs its own Vitest suite asserting `.extend()`, `this.base()`
+re-entrancy, `init` mapping, and `$`-property coercion against representative real subclasses (`Craft.CpModal`,
+`BaseElementSelectorModal`). Budgeted at **8 dev-days** in the table (§4), front-loaded so the Modal PoC can be validated
+through it.
+
+---
+
+## 3. Phased migration sequence
+
+Ordered leaves-first using doc 02's topological order. Each phase is independently shippable (the package builds and the
+already-migrated modules are usable) so we get continuous integration value rather than a big-bang merge.
+
+### Phase 0 — Scaffold (DONE)
+
+Package, tsdown dual-entry build, Vitest+happy-dom, Prettier all green (doc 04). `src/compat.ts` is a placeholder.
+
+### Phase 1 — Core foundation + Modal PoC (the vertical slice)
+
+The PoC proves the whole strategy end-to-end before we commit to the long tail.
+
+| Module | Difficulty | Key jQuery removals | Risks | Deps |
+| --- | --- | --- | --- | --- |
+| `lib/Base.js` | n/a | none — replaced wholesale by native `class` (doc 01 §1) | none | — |
+| `Base.js` → `base.ts` + `events.ts` + `dom-listeners.ts` | MED | `$.noop`/`$.extend`/`$.trim`/`$.proxy` trivial; **rebuild dual event system + namespaced DOM listeners without jQuery** | emitter/`off`-matching/`once`-wrapper parity; namespaced `.off` without jQuery namespaces | core |
+| `Garnish.js` → `globals.ts`/`utils/*`/`custom-events/*`/`constants.ts` | HIGH | `$.event.special`→installers; `$win/$doc/$bod`→native; `.velocity()`→WAAPI; `.scrollParent()`→finder; `:focusable`→matcher; `$.data`→WeakMap | **focusable matcher fidelity**, animation parity, the 40+ util surface | Base |
+| `focusable.ts` matcher (§4.E doc 01) | HIGH | reimplement jQuery-UI `:focusable`/`:visible` | accessibility correctness; underpins all focus traps | — |
+| `EscManager.js`, `UiLayerManager.js` | LOW | `$.isPlainObject`, basic selectors, `$.each` | minimal | Base |
+| `icons/ResizeHandle.js` | n/a | none (SVG string) | none | — |
+| `Modal.js` → `modal.ts` | MED | per doc 03 §2: element creation/insertion/class/dims trivial; **Velocity fade → WAAPI** | size/position math; focus trap; defaults parity | Base, UiLayerManager, (DragMove/BaseDrag deferred) |
+| **compat layer (initial)** | HIGH | `compatify`, `init`/`this.base`, `$`-coercion, `window.Garnish`, `isJquery`, event sugar (§2) | re-entrant `this.base`; jQuery peer wiring | core + jQuery |
+
+PoC defers `draggable`/`resizable` Modal (defaults are `false` per doc 03 §1 Tier 2), so `BaseDrag` is **not** required for
+the slice. **"PoC done"** = modern `Modal` + core build, plus an unmodified `Craft.*Modal` subclass running through compat
+on the real CP with visual + a11y parity.
+
+### Phase 2 — Drag system
+
+The drag cluster is self-contained below `Base`/`Garnish` and feeds Modal's resizable/draggable mode, DragSort, DragDrop.
+Do it as a unit; the `.scrollParent()` + auto-scroll machinery (BaseDrag lines ~83–210, a `setInterval` window-scroll loop
+keyed off `_scrollProperty`/`_scrollAxis`/`_scrollDist`) is shared and must be ported once into a reusable scroll-parent +
+auto-scroll helper.
+
+| Module | Difficulty | Key jQuery removals | Risks | Deps |
+| --- | --- | --- | --- | --- |
+| `BaseDrag.js` | HIGH | `.scrollParent()` ×2, `.offset()`, `$.data/removeData` (→WeakMap), `$.makeArray/inArray`, `.index()`, auto-scroll `setInterval` loop | scroll-parent finder correctness; pointer math; drag perf | Base, Garnish |
+| `DragMove.js` | LOW | none (already pure) | none | BaseDrag |
+| `Drag.js` | MED | `.clone()`→`cloneNode(true)`, `.velocity()` return-to-source, `.outerWidth/Height`, `.offset()` | helper-clone positioning; return animation parity | BaseDrag |
+| `DragDrop.js` | LOW | `$(el)`, class methods, `$.extend`, `$.noop` | minimal | Drag |
+| `DragSort.js` | HIGH | `.insertBefore/After/prependTo`, `.offset()`, `.index()`, `.find/not/filter`, `$.contains` | `_getClosestItem` hit-detection algorithm + midpoint caching (perf-critical, large lists); insertion visual feedback | Drag |
+
+### Phase 3 — Overlays & menus
+
+| Module | Difficulty | Key jQuery removals | Risks | Deps |
+| --- | --- | --- | --- | --- |
+| `HUD.js` | MED-HIGH | `.scrollParent()`, `.offset/outerW/H`, `.velocity()`, insertion, `:focusable` | smart 4-way positioning/orientation logic; scroll-follow | Base, UiLayerManager, focusable |
+| `CustomSelect.js` | MED | `.velocity()`, `.offset/scrollTop/Left`, positioning, `$.data` | anchor-relative positioning (`_alignLeft/Right/Center`) | Base, UiLayerManager |
+| `SelectMenu.js` | LOW | `$.extend` | thin `.sel` wrapper | CustomSelect |
+| `MenuBtn.js` | LOW-MED | `.data/.attr`, class, `.contains`, MutationObserver | keyboard search/nav | Base, CustomSelect |
+| `ContextMenu.js` | MED | `$('<div/>')` etc. DOM creation, `.css`, `.mousedown`, `.show/.hide` | dynamic menu build | Base, UiLayerManager |
+| `DisclosureMenu.js` | HIGH | `.velocity()` show/fadeOut, `:focusable` (6 sites), `.scrollParent()`, `.find/closest/filter/parent`, search `data('searchText')` | 1,008 LOC; complex focus + type-ahead search + positioning | Base, UiLayerManager, focusable |
+
+### Phase 4 — Selection & form inputs
+
+| Module | Difficulty | Key jQuery removals | Risks | Deps |
+| --- | --- | --- | --- | --- |
+| `Select.js` | HIGH | 41 jQuery sites: `.find/filter/index/not/eq/slice`, `.offset/outerW/H`, `$.data` (`select`/`select-handle`/`select-item`), `$.inArray/makeArray`, `:focusable` | highest coupling; `getClosestItem` spatial query; shift-range + Ctrl+A + keyboard; `$.data` item-back-references → WeakMap | Base, Garnish, focusable |
+| `NiceText.js` | LOW-MED | `.val/.attr/.css`, `.height/.width`, `.velocity()` fade, insertion | text-measurement `getHeightForValue`; `textchange` event | Base, custom-events |
+| `MixedInput.js` | LOW | `.attr/.val/.css/.prop`, insertion, `$.inArray` | caret positioning; nested `TextElement` | Base |
+| `CheckboxSelect.js` | LOW | `.find/filter/not`, `.prop` | minimal | Base |
+| `MultiFunctionBtn.js` | LOW | `.data/.find`, class | minimal; ARIA live region | Base |
+
+### Phase 5 — Integration, cutover, retire legacy build
+
+Wire `index.js` equivalent (`initGarnish()`), finalize the compat `window.Garnish`, run full visual-regression + a11y +
+the existing legacy Garnish test suite against the new package, then retire the legacy webpack `garnish` bundle (§5).
+
+---
+
+## 4. Per-module effort estimate
+
+Estimates are **dev-days for an engineer fluent in the codebase**, including unit tests but **excluding** the cross-cutting
+visual-regression/QA pass (counted once in Phase 5). "Size" is legacy LOC. Difficulty drivers are honest about the hard
+ones: the focusable matcher, Velocity→WAAPI, `.scrollParent()`/auto-scroll, `$.event.special`, and the two spatial hit-test
+algorithms (`Select.getClosestItem`, `DragSort._getClosestItem`).
+
+| Module | LOC | Difficulty | Est. (dev-days) | Notes |
+| --- | --- | --- | --- | --- |
+| `lib/Base.js` | 160 | — | 0 | Deleted; replaced by native class |
+| `Base.js` (→ base/events/dom-listeners) | 193 | MED | 4 | Dual event system + namespaced DOM listeners are the real work, not the `$.x` swaps |
+| `Garnish.js` (utils/globals/constants) | 1,211 | HIGH | 6 | 40+ utils; excludes matcher + custom-events (separate rows) |
+| **focusable matcher** (§4.E) | — | HIGH | 3 | Single biggest reimplementation risk; heavy test budget |
+| **custom-events** (activate/textchange/resize) | — | HIGH | 3 | `$.event.special`→installers + shared ResizeObserver |
+| **animation utils** (shake, scrollContainerToElement) | — | MED | 2 | Velocity→WAAPI; scroll-parent finder lives here too |
+| `EscManager.js` | 55 | LOW | 0.5 | Pure JS already |
+| `UiLayerManager.js` | 181 | LOW | 1.5 | Light jQuery |
+| `icons/ResizeHandle.js` | 4 | — | 0 | SVG string |
+| `Modal.js` | 451 | MED | 4 | PoC reference; Velocity→WAAPI is the only hard bit |
+| `BaseDrag.js` | 583 | HIGH | 6 | `.scrollParent()` + auto-scroll loop + WeakMap data; foundational for drag |
+| `DragMove.js` | 15 | LOW | 0.25 | Trivial |
+| `Drag.js` | 462 | MED | 3.5 | Clone helpers + return animation |
+| `DragDrop.js` | 116 | LOW | 1 | — |
+| `DragSort.js` | 697 | HIGH | 6 | `_getClosestItem` perf + insertion feedback |
+| `HUD.js` | 764 | MED-HIGH | 5 | 4-way positioning |
+| `CustomSelect.js` | 333 | MED | 3 | Anchor positioning |
+| `SelectMenu.js` | 83 | LOW | 0.5 | Thin wrapper |
+| `MenuBtn.js` | 444 | LOW-MED | 3 | Keyboard search |
+| `ContextMenu.js` | 171 | MED | 2 | DOM creation |
+| `DisclosureMenu.js` | 1,008 | HIGH | 7 | Largest UI component; focus + type-ahead + positioning |
+| `Select.js` | 1,018 | HIGH | 8 | Highest jQuery coupling + spatial query |
+| `NiceText.js` | 343 | LOW-MED | 2.5 | Text measurement |
+| `MixedInput.js` | 424 | LOW | 3 | Caret handling |
+| `CheckboxSelect.js` | 97 | LOW | 1 | — |
+| `MultiFunctionBtn.js` | 125 | LOW | 1 | — |
+| **Compat layer** (`compatify`, `window.Garnish`, jQuery coercion) | — | HIGH | 8 | The load-bearing upgrade-path risk (§2) |
+| **Integration + cutover** (init wiring, legacy-build retirement, full QA/visual-regression/a11y) | — | HIGH | 10 | Counted once; covers all phases |
+| **Total** | ~9k | — | **~104 dev-days** | ≈ 21 engineer-weeks; ~5 calendar months solo, ~2.5–3 months for a pair |
+
+Add **15–20% contingency** for parity surprises (drag pointer math, animation timing, focus edge cases), giving a planning
+range of **~120–125 dev-days**.
+
+---
+
+## 5. Consumer migration & cutover
+
+There are **~107 consumer files** using `Garnish.X.extend(...)` / `new Garnish.X(...)` across `packages/craftcms-legacy/`
+and `resources/js/`. `Garnish.Base` alone has ~96 subclass usages (doc 02), so the consumer story *is* the compat story.
+
+### 5.1 Two consumer paths
+
+| Path | Who | What they do | Effort |
+| --- | --- | --- | --- |
+| **Do nothing (compat shim)** | The ~107 existing legacy modules | Resolve `Garnish` from compat (`import '@craftcms/garnish/compat'`, or keep the legacy global until retirement). `.extend()`, `this.base()`, `$container`, namespaced events all keep working unchanged. | ~0 per file |
+| **Opt-in to modern API** | New code; modules being actively touched | Use named modern imports + `class extends` + `super()`; native element args; `super.method()` instead of `this.base()`. | Per-file, voluntary, incremental |
+
+The contract is: **no consumer is forced to change to keep working.** Migration to the modern API is opportunistic
+(touch-it-fix-it), not a scheduled mass rewrite.
+
+### 5.2 Retiring the legacy webpack `garnish` build
+
+1. **Coexist (Phases 1–4).** Legacy webpack keeps bundling the jQuery `garnish` library and assigning `window.Garnish`.
+   The modern package is consumed by the Vue/Inertia CP and new code. Two `Garnish` implementations may briefly exist;
+   they must not both claim `window.Garnish` — the legacy guard (`if (typeof window.Garnish === 'undefined')`) and the
+   compat guard ensure last-write-wins is controlled, and during overlap **only one** owns the global (start with legacy,
+   flip to compat at step 3).
+2. **Parity gate.** Once all 23 modules are ported and the compat suite is green, stand up the compat `window.Garnish` in a
+   branch and point the legacy CP at it instead of the webpack bundle.
+3. **Flip the global.** Make `@craftcms/garnish/compat` the sole provider of `window.Garnish`; stop emitting the webpack
+   `garnish` entry. Run the full regression battery (§5.3).
+4. **Delete.** Remove `packages/craftcms-legacy/garnish/` source and its webpack entry. jQuery remains only as the compat
+   peer dep until the long-tail consumers themselves drop jQuery.
+
+### 5.3 Testing strategy
+
+- **Unit (Vitest + happy-dom):** Per-module, written alongside each port. Heaviest budget on the focusable matcher, the
+  emitter (`off`/`once`/precedence parity), and the two spatial algorithms. Compat gets its own suite asserting
+  `.extend()`/`this.base()`/`init`/`$`-coercion against real subclasses.
+- **Existing legacy Garnish test suite:** Run it against the compat layer as a behavioral oracle — it encodes current
+  expected behavior and is the cheapest parity check we have.
+- **Visual regression on the real CP:** The decisive gate. Drive the actual control panel (modals, HUDs, disclosure menus,
+  drag-sort matrix fields, selection) and diff against legacy. Animation, positioning, and drag feedback are not unit-testable
+  with confidence.
+- **Accessibility:** Manual + automated keyboard/focus-trap/ARIA checks on every overlay and menu (focus management is the
+  top a11y risk — §6).
+
+---
+
+## 6. Risks & mitigations
+
+| Risk | Why it matters | Mitigation |
+| --- | --- | --- |
+| **Focusable matcher fidelity** (§4.E) | Underpins every focus trap, modal, menu. jQuery-UI `:focusable` has subtle rules (href links, disabled controls, contenteditable, tabindex, visibility). Divergence = broken keyboard a11y. | Model on the published jQuery-UI `:focusable` algorithm; dedicated exhaustive unit suite; manual keyboard QA on all overlays. Build it in Phase 1 so everything downstream shares one tested implementation. |
+| **Animation parity (Velocity → WAAPI)** | 6 modules use `.velocity()` (Garnish shake, Modal/HUD/Drag/CustomSelect/DisclosureMenu fades + return-to-source). Timing/easing mismatches read as "feels off." `.velocity('stop')` semantics. | Standardize on `element.animate()`; match legacy durations (shade ~50ms, container ~`FX_DURATION` 200ms, doc 03 §2); `stop`→`anim.cancel()`; gate all on `prefersReducedMotion`. Visual-regression catches drift. |
+| **Drag system complexity** | BaseDrag's `.scrollParent()` + `setInterval` auto-scroll loop and the `_getClosestItem`/`_updateInsertion` hit-detection are the most algorithmically dense, perf-sensitive code. WeakMap replaces `$.data` back-references. | Port scroll-parent + auto-scroll into one shared, tested helper. Preserve the midpoint-caching optimization. Perf-test DragSort on large matrix fields. |
+| **Dual event systems** | Object pub/sub (incl. class-level `Garnish.on(Target,...)`) *and* namespaced DOM listeners must both be reproduced without jQuery, with exact `off`/`once`/precedence semantics (doc 01 §2). | The core spec already pins the grammar and precedence as compatibility warts; replicate `once`-as-wrapper and backward-splice `off`. Emitter is the most-tested unit. |
+| **`this.base()` re-entrancy** (compat) | Nested super-calls rely on save/restore of `this.base`; getting it wrong silently breaks deep subclass chains (`Craft.CpModal` etc.). | Copy the `lib/Base.js` save/restore-in-try/finally verbatim; test multi-level `extend` chains explicitly. |
+| **RTL** | `rtl`/`ltr` derive from `body.classList` and affect positioning (HUD, CustomSelect, DisclosureMenu). | Keep `rtl`/`ltr` flags in core globals; include RTL cases in positioning visual-regression. |
+| **Accessibility (focus/ARIA)** | Modal background-layer hiding, focus trap/release, `setFocusWithin`'s `.field:visible` heuristic (cms#15245) are correctness-critical and easy to regress. | Preserve the documented heuristics verbatim; manual a11y QA gate before cutover. |
+| **jQuery peer in compat** | Compat needs jQuery for `$`-coercion and `isJquery`; must not leak into the modern entry. | jQuery is a peer dep of the `./compat` entry only; tsdown `deps.neverBundle` (doc 04); verify modern `index.js` bundle has zero jQuery. |
+
+---
+
+## 7. Recommended milestones
+
+| Milestone | Scope | "Done" means |
+| --- | --- | --- |
+| **M1 — PoC (vertical slice)** | Core foundation (Base/events/dom-listeners/globals/constants), focusable matcher, custom-events, EscManager, UiLayerManager, Modal, initial compat layer | Modern `Modal` builds and runs; an **unmodified** real `Craft.*Modal` subclass works through `@craftcms/garnish/compat` on the live CP with visual + a11y parity. Emitter + matcher unit suites green. This is the go/no-go gate. |
+| **M2 — Core GA** | Harden core surface; full util parity; compat `window.Garnish` stands up the full namespace; legacy Garnish test suite passes against compat | New code can target modern API; compat is a drop-in for any module that uses only ported classes. Core API frozen. |
+| **M3 — Component wave 1 (drag + overlays)** | BaseDrag, DragMove, Drag, DragDrop, DragSort, HUD, CustomSelect, SelectMenu, MenuBtn, ContextMenu, DisclosureMenu | Each ships with parity tests; DragSort perf-validated on large lists; overlays pass positioning + a11y visual-regression. |
+| **M4 — Component wave 2 (selection + inputs)** | Select, NiceText, MixedInput, CheckboxSelect, MultiFunctionBtn | All 23 modules ported; full compat namespace complete; entire legacy test suite green against the new package. |
+| **M5 — Cutover** | Flip `window.Garnish` to compat as sole provider; retire legacy webpack `garnish` bundle; delete legacy source | Legacy bundle removed; full CP visual-regression + a11y battery green; jQuery present only as the compat peer dep. Long-tail consumers migrate off compat opportunistically thereafter. |
+
+---
+
+## 8. Bottom line for the go/no-go
+
+The strategy is sound and de-risked by the existing core design: the modern core deliberately preserves the legacy event
+grammar, precedence, and method names so the compat layer can wrap classes **mechanically** rather than re-implementing
+each one twice. The upgrade path for the ~107 consumers is genuinely "do nothing or migrate at will," which is the whole
+point. The real cost and risk concentrate in a handful of places — the focusable matcher, animation parity, the drag
+algorithms, and the `this.base()` synthesis — all called out above with explicit budgets and mitigations. Total effort is
+**~104 dev-days (~120–125 with contingency)**, sequenced so the Modal PoC validates the entire approach before the long
+tail is committed.
diff --git a/packages/craftcms-garnish/docs/01-core-design.md b/packages/craftcms-garnish/docs/01-core-design.md
new file mode 100644
index 00000000000..c2065a7d8aa
--- /dev/null
+++ b/packages/craftcms-garnish/docs/01-core-design.md
@@ -0,0 +1,669 @@
+# Garnish Core — Modern Design Spec (`garnish-core`)
+
+> Status: **Design contract.** This document is the spec the implementation team builds against. It covers the
+> foundation layer (`garnish-core`) that every other Garnish module depends on: the class system, the event system,
+> the utility surface, the settings system, and the module layout.
+>
+> Scope boundary: This is the **modern, jQuery-free, ESM/TypeScript** core. The legacy `Base.extend()` contract,
+> jQuery-collection arguments, and the legacy global `window.Garnish` object are **out of scope** here — they will be
+> restored by a separate, opt-in **compat layer** (`garnish-compat`). Wherever a legacy behavior is mentioned, it is
+> only to define the boundary the compat layer will bridge.
+
+---
+
+## 0. Source-of-truth inventory (what the legacy core actually is)
+
+The legacy core is four files:
+
+| File | Role |
+| --- | --- |
+| `src/lib/Base.js` | Dean Edwards `Base.js` 1.1a — the `.extend(instance, static)` class/prototype system with `this.base()` super-call support. |
+| `src/Base.js` | `Garnish.Base` — extends Dean Edwards Base. Settings system, instance-level pub/sub events (`on`/`off`/`once`/`trigger`), namespaced DOM listeners (`addListener`/`removeListener`/`removeAllListeners`), `disable`/`enable`, `destroy`. |
+| `src/Garnish.js` | The `Garnish` singleton object — ~40 utilities + constants, the class-level event bus (`Garnish.on/off/once`), `_normalizeEvents`, jQuery `$.event.special` registrations (`activate`, `textchange`, `resize`), focus/ARIA helpers, animation helpers, browser/mobile detection, form/post-data helpers. |
+| `src/EscManager.js`, `src/UiLayerManager.js` | Singleton-ish managers attached to the core (`Garnish.escManager`, `Garnish.uiLayerManager`). They are `Base` subclasses and exercise the event + listener API. |
+
+Two distinct event systems coexist in the legacy code and **must both be reproduced**:
+
+1. **Pub/sub object events** — `Garnish.Base.prototype.on/off/once/trigger`, plus a **class-level** variant
+   `Garnish.on/off/once`. These are *not* DOM events; they are an in-memory observer registry. `trigger` dispatches to
+   instance handlers **and** to class-level handlers whose `target` the instance `instanceof`-matches.
+2. **DOM listeners** — `Garnish.Base.prototype.addListener/removeListener/removeAllListeners`, which today are thin
+   wrappers over `jQuery.on/off` with a per-instance namespace and a `_disabled` gate.
+
+The modern core keeps both, expressed as one coherent emitter design (§2).
+
+---
+
+## 1. Class system
+
+### 1.1 What legacy does
+
+`lib/Base.js` implements Dean Edwards inheritance:
+
+- `Klass = Base.extend(instanceMembers, staticMembers)` returns a constructor.
+- Inside any method, `this.base(...)` calls the overridden ancestor method (re-bound per call via the `extend`
+  wrapper that detects `/\bbase\b/` in the function source).
+- `Garnish.Base` adds a `constructor` that initializes `_eventHandlers`, `_namespace`, `_listeners`, then calls
+  `this.init.apply(this, arguments)`. Subclasses override `init`, **not** `constructor`.
+
+### 1.2 Modern replacement: native `class extends`
+
+The modern core uses native ES classes. The `init()` indirection is **dropped**; subclasses use a real
+`constructor` and call `super(...)`. `this.base()` is replaced by `super.method()`.
+
+```ts
+// base.ts
+export interface GarnishBaseSettings {
+  [key: string]: unknown;
+}
+
+export abstract class Base<S extends GarnishBaseSettings = GarnishBaseSettings> {
+  /** Resolved settings (defaults <- passed settings). Null until setSettings runs. */
+  settings: S | null = null;
+
+  protected _disabled = false;
+
+  /** Pub/sub registry (see §2). */
+  protected readonly _emitter = new EventEmitter(this);
+
+  /** Tracked DOM listener bindings for bulk teardown (see §2.4). */
+  protected readonly _domListeners = new DomListenerRegistry();
+
+  constructor() {
+    // No init() trampoline. Subclasses do their own setup after super().
+  }
+
+  // ... on/off/once/trigger/addListener/... delegate to _emitter / _domListeners (§2)
+
+  disable(): void { this._disabled = true; }
+  enable(): void { this._disabled = false; }
+  get disabled(): boolean { return this._disabled; }
+
+  destroy(): void {
+    this.trigger('destroy');
+    this._domListeners.removeAll();
+    this._emitter.clear();
+  }
+}
+```
+
+**Subclass shape (modern):**
+
+```ts
+export class EscManager extends Base {
+  private handlers: Array<{ obj: unknown; func: EscHandler }> = [];
+
+  constructor() {
+    super();
+    this.addListener(document.body, 'keyup', (ev) => {
+      if ((ev as KeyboardEvent).key === 'Escape') this.escapeLatest(ev as KeyboardEvent);
+    });
+  }
+}
+```
+
+### 1.3 Boundary with the compat layer
+
+The compat layer is responsible — and the modern core is explicitly **not** — for:
+
+- A `Base.extend(instance, static)` shim that produces a class wrapping the modern `Base`.
+- The `init()` trampoline (compat `extend` maps a passed `init` member to post-`super()` invocation).
+- `this.base(...)` super dispatch (compat synthesizes it; modern code uses `super.`).
+- Re-exposing every class on `window.Garnish`.
+
+The modern core MUST keep its constructors plain and its method names stable so the compat layer can wrap them
+mechanically. No modern core method should depend on the `init()` indirection existing.
+
+### 1.4 Key decisions
+
+- `Base` is `abstract`. It is never instantiated directly.
+- Settings are generic (`Base<S>`) so subclasses get typed `this.settings`.
+- Constants that were prototype members in legacy (none of significance) become real fields.
+- Getters (e.g. `UiLayerManager.layer`, `currentLayer`) become native `get` accessors — already legal in legacy via
+  Dean Edwards descriptor copying, so this is a 1:1 move.
+
+---
+
+## 2. Event system
+
+This is the load-bearing part. The modern emitter must reproduce three legacy behaviors:
+
+- **A. Object pub/sub** (`on('foo.ns', data, handler)`, `trigger('foo', data)`) — in-memory, not DOM.
+- **B. Class-level pub/sub** (`Garnish.on(TargetClass, 'foo', handler)`) — dispatched on `trigger` to any instance
+  that is `instanceof TargetClass`.
+- **C. Namespaced DOM delegation** (`addListener(el, 'click.ns', fn)`) — currently `jQuery.on`, including delegated
+  selectors and a per-instance namespace for bulk `.off`.
+
+### 2.1 Event-string grammar (preserved exactly)
+
+Legacy `_normalizeEvents`:
+
+- `on`/`off`/`trigger` strings split on **spaces** → multiple events.
+- Each event splits on the **first** `.` → `[type, namespace]`. (`'click.foo'` → `type='click'`, `ns='foo'`.)
+- `addListener` additionally splits the events arg on **commas** (`_splitEvents`) and appends the instance
+  `_namespace` to each before handing to jQuery (`_formatEvents`).
+
+Modern core keeps the same grammar so call sites are unchanged. Canonical parser:
+
+```ts
+// events.ts
+export interface ParsedEvent {
+  type: string;          // '' is invalid for on/trigger; '' with a namespace is the "remove by namespace" form for off
+  namespace: string | null;
+}
+
+/** 'click.ns mousedown' -> [{type:'click',namespace:'ns'},{type:'mousedown',namespace:null}] */
+export function parseEvents(events: string | string[], splitOn: ' ' | ',' = ' '): ParsedEvent[];
+
+/** Format for DOM binding: appends instance namespace. 'click,drag' + '.Garnish123' -> 'click.Garnish123 drag.Garnish123' */
+export function formatDomEvents(events: string | string[], namespace: string): string;
+```
+
+Note the legacy split-character inconsistency (`on` uses space, `addListener` uses comma). The modern API
+**preserves both**: `parseEvents(..., ' ')` for pub/sub, `parseEvents(..., ',')` for `addListener`. This is a
+deliberate compatibility wart, documented so the compat layer needn't special-case it.
+
+### 2.2 Public types
+
+```ts
+// events.ts
+
+/** Payload an emitted event carries to handlers. */
+export interface GarnishEvent<T = unknown, Target = unknown> {
+  type: string;
+  target: Target;          // the emitting object (legacy: the Base instance)
+  data: Record<string, unknown>;   // per-registration data, merged with trigger-time data
+  originalEvent?: Event;   // present when re-emitting a DOM event (legacy 'activate' etc.)
+  [extra: string]: unknown; // trigger-time payload is spread on (legacy $.extend behavior)
+}
+
+export type GarnishEventHandler<E extends GarnishEvent = GarnishEvent> = (event: E) => void;
+
+interface Registration {
+  type: string;
+  namespace: string | null;
+  data: Record<string, unknown>;
+  handler: GarnishEventHandler;
+  once: boolean;
+}
+```
+
+### 2.3 Object pub/sub — `EventEmitter`
+
+Backs `Base.on/off/once/trigger`. One instance per `Base` object, owns `this` as the event target.
+
+```ts
+// events.ts
+export class EventEmitter<Target = unknown> {
+  constructor(private readonly target: Target) {}
+
+  on(events: string, handler: GarnishEventHandler): void;
+  on(events: string, data: Record<string, unknown>, handler: GarnishEventHandler): void;
+
+  once(events: string, handler: GarnishEventHandler): void;
+  once(events: string, data: Record<string, unknown>, handler: GarnishEventHandler): void;
+
+  /** Remove by (type [+ namespace] [+ handler]). Omitting handler removes all of that type/namespace. */
+  off(events: string, handler?: GarnishEventHandler): void;
+
+  /** Dispatch. `data` is merged onto the event object after the per-registration `data`. */
+  trigger(type: string, data?: Record<string, unknown>): void;
+
+  /** Remove every registration (used by destroy). */
+  clear(): void;
+}
+```
+
+**Semantics that must match legacy:**
+
+- `on`/`once` argument overload: if arg 2 is a function, it's the handler and `data = {}`.
+- `trigger` builds `{ type, target: this }`, and for each matching handler constructs the event as
+  `{ data: registration.data, ...triggerData, type, target }`. In legacy this is
+  `$.extend({data: handler.data}, data, ev)` — i.e. trigger-time `data` keys win over registration `data`, and
+  `type`/`target` always win. **Preserve this precedence exactly** (it is observable; some call sites pass `target`
+  overrides in `data`, which legacy `$.extend` lets the `ev` object override last).
+- `off` matching: a registration matches when `type` matches **and** (the parsed namespace is empty **or** namespaces
+  match) **and** (handler is omitted **or** handler is `===`). Iterate **backwards** and splice, like legacy.
+- `once` is implemented as a self-removing wrapper registered via `on`; `off(events, wrapper)` removes it. Modern impl
+  uses the `once: boolean` flag on `Registration` instead of a wrapper closure, but `off` by original handler must
+  still work — so store the original handler reference for `once` matching too. (Simplest faithful approach: keep the
+  wrapper-closure approach exactly as legacy does, with `off(events, onceler)`.)
+
+> **Decision:** keep the legacy wrapper-closure `once` to guarantee identical `off` behavior, rather than the flag.
+> The flag is a footgun for `off`-by-handler.
+
+### 2.4 Class-level pub/sub — `ClassEventBus`
+
+Backs `Garnish.on/off/once`. Legacy stores these in `Garnish._eventHandlers` (a flat array) and `Base.trigger`
+walks it filtering on `this instanceof handler.target`.
+
+```ts
+// events.ts
+type Constructor<T = object> = abstract new (...args: any[]) => T;
+
+export class ClassEventBus {
+  private readonly registrations: Array<Registration & { target: Constructor }> = [];
+
+  on(target: Constructor, events: string, handler: GarnishEventHandler): void;
+  on(target: Constructor, events: string, data: Record<string, unknown>, handler: GarnishEventHandler): void;
+
+  once(target: Constructor, events: string, handler: GarnishEventHandler): void;
+  once(target: Constructor, events: string, data: Record<string, unknown>, handler: GarnishEventHandler): void;
+
+  off(target: Constructor, events: string, handler?: GarnishEventHandler): void;
+
+  /** Called by Base.trigger: dispatch class-level handlers whose target the instance is an instanceof. */
+  dispatch(instance: object, type: string, data: Record<string, unknown>, baseEvent: GarnishEvent): void;
+}
+```
+
+**Wiring:** `Base.trigger(type, data)` does two passes (exactly like legacy):
+
+1. Its own `_emitter.trigger(type, data)`.
+2. `garnishClassBus.dispatch(this, type, data, baseEvent)`.
+
+The single shared `ClassEventBus` instance lives in the core module (`garnishClassBus`) and is exposed as
+`Garnish.on/off/once` on the namespace object (§5.3). Legacy guards `on/once` against `undefined` target with a
+`console.warn`; **preserve** the warning.
+
+### 2.5 DOM listeners — `DomListenerRegistry`
+
+Replaces `addListener`/`removeListener`/`removeAllListeners`. Legacy leans on jQuery for: element coercion
+(`$(elem)`), namespaced binding, delegated binding (the `data` arg can carry a selector via jQuery's
+`(events, selector, data, handler)` overloads — though Garnish's own `addListener` only uses `(events, data, handler)`
+with a plain-object `data`), and the `_disabled` gate.
+
+Modern, jQuery-free contract:
+
+```ts
+// dom-listeners.ts
+export type ElementInput = EventTarget | EventTarget[] | NodeListOf<Element> | string | null | undefined;
+
+export interface DomListenerOptions {
+  /** Delegated target selector; handler fires only when event.target matches/closest this selector. */
+  delegate?: string;
+  /** Debounce/throttle hooks used by textchange etc. (see §3 custom events). */
+  data?: Record<string, unknown>;
+  capture?: boolean;
+  passive?: boolean;
+}
+
+export class DomListenerRegistry {
+  constructor(private readonly host: Base) {}
+
+  /** Bind. `events` uses the comma/space grammar (§2.1). Handler is invoked with the host's `this`
+   *  and short-circuited while host.disabled is true (legacy _disabled gate). */
+  add(
+    elements: ElementInput,
+    events: string,
+    handler: GarnishEventHandler,
+    options?: DomListenerOptions,
+  ): void;
+
+  /** Remove specific event(s) previously bound by this host on the element. */
+  remove(elements: ElementInput, events: string): void;
+
+  /** Remove all listeners this host bound on the element (legacy removeAllListeners). */
+  removeAllOn(elements: ElementInput): void;
+
+  /** Remove everything this host bound anywhere (used by destroy). */
+  removeAll(): void;
+}
+```
+
+**`Base` thin wrappers (signature-compatible with legacy):**
+
+```ts
+addListener(elem: ElementInput, events: string, dataOrHandler: object | GarnishEventHandler | string, handler?: GarnishEventHandler | string): void;
+removeListener(elem: ElementInput, events: string): void;
+removeAllListeners(elem: ElementInput): void;
+```
+
+Legacy `addListener` quirks to reproduce:
+
+- Bails silently if no elements resolve.
+- Param mapping: `(elem, events, func)` vs `(elem, events, data, func)`; if `func` is undefined and `data` is not a
+  plain object, treat `data` as `func`.
+- `func` may be a **method name string** (`this[func].bind(this)`) — preserve, since `UiLayerManager` uses
+  `addListener(..., 'triggerShortcut')`.
+- Handler is invoked only when `!this._disabled`.
+- Tracks bound elements so `destroy` can clean them all up.
+
+**Implementation note (no jQuery):** Native `addEventListener` has no namespace concept. The registry must store
+`{element, type, namespace, wrappedHandler, capture}` tuples so it can replicate jQuery's namespaced `.off`. Delegation
+is implemented with `event.target.closest(selector)` inside the wrapped handler. The per-instance `_namespace` is kept
+as a bookkeeping string but is **internal only** in the modern path (it exists in legacy purely to drive jQuery
+namespaced removal; here the registry array does that job). The namespace string is still parsed from the event string
+for API compatibility and for `removeAllListeners` semantics.
+
+### 2.6 `_namespace`
+
+Legacy: `'.Garnish' + Math.floor(Math.random()*1e9)`, used only to scope jQuery DOM listeners. Modern core keeps a
+`protected readonly _namespace: string` for compat-layer parity and debugging, but the registry's tuple list is the
+real removal mechanism. Generation should use `crypto.randomUUID?.()` with a `Garnish` prefix, falling back to the
+legacy random scheme.
+
+---
+
+## 3. Custom DOM events (`activate`, `textchange`, `resize`)
+
+Legacy registers these through `$.event.special` and adds `$.fn.activate/textchange/resize` chaining sugar. These are
+**core-owned custom events** and must move into `garnish-core` (other modules and the legacy CP depend on them
+heavily, especially `activate`).
+
+The modern core cannot use `$.event.special`. Design: a small **custom-event installer** that, given a real
+`EventTarget`, wires the underlying native listeners and re-dispatches a synthetic `CustomEvent`.
+
+```ts
+// custom-events/index.ts
+export interface ActivateOptions { /* none today */ }
+export interface TextchangeOptions { delay?: number | null; }
+
+/** Attach Garnish 'activate' semantics to an element (mousedown/click/keydown -> 'activate' CustomEvent).
+ *  Returns a disposer. */
+export function installActivate(el: HTMLElement): () => void;
+
+/** Attach 'textchange': fires a 'textchange' CustomEvent when the input's value changes
+ *  (keypress/keyup/change/blur), with optional debounce via options.delay. */
+export function installTextchange(el: HTMLElement & { value: string }, options?: TextchangeOptions): () => void;
+
+/** Attach 'resize' via a shared ResizeObserver; window uses native 'resize'. Returns a disposer. */
+export function installResize(el: HTMLElement): () => void;
+```
+
+Behaviors to preserve from legacy:
+
+- **activate:** `mousedown` on `<button>`/`role=button` calls `preventDefault` (no focus-on-click). `click` and
+  `keydown(Space/Enter)` dispatch `activate` unless the element is `.disabled` or `Garnish.activateEventsMuted`.
+  Ctrl/⌘-click on an `<a href>` (non-`#`/non-empty) is ignored. Sets `tabindex="0"` on non-disabled, non-body
+  elements; removes `tabindex` on disabled (unless `.read-only`). `keydown` ignores bubbled events
+  (`this === target`).
+- **textchange:** stores last value, compares on each event, dispatches `textchange` only on change. Supports a
+  `delay` debounce (legacy reads delay from `data.delay` or `ev.data.delay`).
+- **resize:** window → native `resize`. Other elements → shared `ResizeObserver` keyed by stored
+  `{width,height}`; only dispatch when dimensions actually change and `Garnish.resizeEventsMuted` is false. The
+  observer is lazily created and shared (one per core).
+
+The shared `Garnish.activateEventsMuted` / `Garnish.resizeEventsMuted` flags (and `muteResizeEvents(cb)`) stay on the
+namespace object (§4 / §5.3).
+
+> The `DomListenerRegistry.add` recognizes these synthetic event types and routes binding through the matching
+> `install*` so that `addListener(el, 'activate', fn)` keeps working. Installation is idempotent per element/type.
+
+---
+
+## 4. Utilities inventory (every public member of `Garnish`)
+
+Legend for jQuery dependency: **none** (no jQuery), **trivial** (only `$(elem)` coercion / `.attr` / `.css` — mechanical
+to port), **deep** (jQuery semantics like `:focusable`, `.velocity()`, `.scrollParent()`, `$.event`, `$.data` that need
+real reimplementation or a decision).
+
+### 4.A Keep as-is (pure JS, no jQuery)
+
+| Member | Signature | Behavior |
+| --- | --- | --- |
+| `getDist` | `(x1,y1,x2,y2: number) => number` | Euclidean distance. **none.** |
+| `within` | `(num,min,max: number) => number` | Clamp. **none.** |
+| `isString` | `(val) => boolean` | `typeof === 'string'`. **none.** |
+| `isArray` | `(val) => boolean` | `Array.isArray`. **none.** *(deprecate, §4.D)* |
+| `isTextNode` | `(elem) => boolean` | `nodeType === 3`. **none.** |
+| `isPrimaryClick` | `(ev) => boolean` | `ev.which === 1 && !ctrl && !meta`. **none** (but `which` → see note). |
+| `isCtrlKeyPressed` | `(ev) => boolean` | ⌘ on Mac else Ctrl. **none.** |
+| `prefersReducedMotion` | `() => boolean` | `matchMedia('(prefers-reduced-motion: reduce)')`. **none.** |
+| `getUserPreferredAnimationDuration` | `(duration) => number\|string` | `0` if reduced motion else `duration`. **none.** |
+| `getBodyScrollTop` | `() => number` | Clamped body scrollTop. **trivial** (`$bod.outerHeight`, `$win.height` → `document.body.offsetHeight`, `window.innerHeight`). |
+| `requestAnimationFrame` / `cancelAnimationFrame` | `(fn)` / `(id)` | Vendor-prefixed RAF shims. **none** — modern: just re-export native `requestAnimationFrame`/`cancelAnimationFrame` (prefixes long dead). |
+| `isMobileBrowser` | `(detectTablets?: boolean) => boolean` | UA regex + memoized `_isMobileBrowser`/`_isMobileOrTabletBrowser`. **none.** Keep, but flag for review (UA sniffing). |
+| `log` | `(msg) => void` | `console.log`. **none.** *(deprecate, §4.D)* |
+| `muteResizeEvents` | `(cb) => void` | Set flag, run cb, restore. **none.** |
+| `_normalizeEvents` | `(events) => ParsedEvent[]` | Event-string parser. **none.** Becomes `parseEvents` (§2.1); kept as `_normalizeEvents` alias for compat. |
+
+> Note on `isPrimaryClick`: `ev.which` is deprecated in the DOM. Modern impl should read `ev.button === 0` (primary)
+> while accepting the legacy `which` shape for compat. Keep `PRIMARY_CLICK`/`SECONDARY_CLICK` constants for the compat
+> layer but document that native code should use `MouseEvent.button`.
+
+### 4.B Needs rewrite without jQuery
+
+| Member | Signature | Behavior | jQuery dep |
+| --- | --- | --- | --- |
+| `isJquery` | `(val) => boolean` | `val instanceof $`. | **deep** — meaningless without jQuery. Modern: move to compat layer; core may keep a stub returning `false`, or drop. **Decision: drop from core, provide in compat.** |
+| `hasAttr` | `(elem, attr) => boolean` | attr present and not `false`. | **trivial** — `el.hasAttribute(attr)`. |
+| `getOffset` | `(elem) => {top,left}` | Element offset, adjusted for non-window scroll container. | **trivial** — `getBoundingClientRect()` + `window.scrollX/Y`; drop the cached `_offset` field. |
+| `hitTest` | `(x,y,elem) => boolean` | Point-in-bounds test using offset + outer size. | **trivial** — `getBoundingClientRect()`; uses page coords so add `scrollX/Y`. Drop the `_$elem/_offset/_x1...` instance-cache fields. |
+| `isCursorOver` | `(ev, elem) => boolean` | `hitTest(ev.pageX, ev.pageY, elem)`. | **trivial.** |
+| `copyTextStyles` | `(source, target) => void` | Copies 10 font/text CSS props. | **trivial** — `getComputedStyle` + assign to `target.style`. |
+| `addModalAttributes` | `(container) => void` | Sets `aria-modal=true`, `role=dialog`. | **trivial** — `setAttribute`. |
+| `ariaHide` | `(element) => void` | Sets `aria-hidden=true`, stores prior value in a class. | **trivial.** |
+| `hasJsAriaClass` | `(element) => boolean` | Has any of 3 JS_ARIA classes. | **trivial** — `classList.contains`. |
+| `isScriptOrStyleElement` | `(element) => boolean` | tagName SCRIPT/STYLE. | **trivial.** |
+| `hideModalBackgroundLayers` | `() => void` | aria-hide body children except notifications/topmost layer. | **deep** — depends on `uiLayerManager.currentLayer.$container` + body children iteration. Rewrite with `document.body.children` + `el.closest`. |
+| `resetModalBackgroundLayerVisibility` | `() => void` | Restore aria-hidden after modal close. | **deep** — class-selector queries + uiLayerManager. Rewrite with `querySelectorAll`. |
+| `focusIsInside` | `(container) => boolean` | container contains `:focus`. | **trivial** — `container.contains(document.activeElement)`. |
+| `firstFocusableElement` | `(container) => Element` | First `:focusable`. | **deep** — `:focusable` is a jQuery-UI selector. Needs a real focusable-element matcher (see §4.E). |
+| `getKeyboardFocusableElements` | `(container) => Element[]` | `:focusable` filtered by `isKeyboardFocusable`. | **deep** — same matcher dependency. |
+| `isKeyboardFocusable` | `(element) => boolean` | `:focusable` and tabindex !== -1. | **deep** — focusable matcher. |
+| `trapFocusWithin` | `(container) => void` | Tab/Shift+Tab cycles focus inside container; binds `keydown.focus-trap`. | **deep** — `:focusable` + namespaced `.off('.focus-trap')`. Rewrite using the matcher + `DomListenerRegistry` with a `focus-trap` namespace. |
+| `releaseFocusWithin` | `(container) => void` | `off('.focus-trap')`. | **deep** — pairs with above. |
+| `setFocusWithin` | `(container) => void` | Focus first sensible focusable, else container with tabindex -1. Includes the `.field:visible` heuristic (cms#15245). | **deep** — `:focusable` + `:visible` + `.field` traversal. Needs matcher + visibility check. |
+| `getFocusedElement` | `() => Element\|null` | `document.activeElement`. | **trivial** — return `document.activeElement` (legacy returned a `$(':focus')` collection; modern returns the element). |
+| `scrollContainerToElement` | `(container, elem?) => void` | Scrolls container so elem is in view. | **deep** — `.scrollParent()`, `.velocity('scroll')`, offset math. Rewrite with `Element.scrollIntoView`/manual `scrollTop` + a real scroll-parent finder; drop Velocity. |
+| `shake` | `(elem, prop?='margin-left') => void` | 10-step shake animation via Velocity. | **deep** — Velocity. Rewrite with Web Animations API (`element.animate`) or rAF loop; respect `prefersReducedMotion`. |
+| `getElement` | `(elem) => Element` | First element of array/collection. | **trivial** — `$.makeArray(elem)[0]` → normalize input then `[0]`. |
+| `getInputBasename` | `(elem) => string\|null` | `name` attr with `[...]` stripped. | **trivial** — `el.getAttribute('name')`. |
+| `getInputPostVal` | `($input) => string\|string[]\|null` | POST value (unchecked checkbox/radio → null, non-`[]` multiselect → last, null select → ''). | **trivial** — read `type`/`checked`/`value`/`tagName`; `value` for multiselect needs `Array.from(select.selectedOptions)`. |
+| `findInputs` | `(container) => Element[]` | `input,text,textarea,select,button` within. | **trivial** — `querySelectorAll`. (Note: `text` is not a real tag — legacy bug, preserve selector string but it matches nothing.) |
+| `getPostData` | `(container) => Record<string,string>` | Serialize inputs to a flat POST map, handling `name[]` array indexing. | **trivial** once `findInputs`/`getInputPostVal` are ported. Pure logic otherwise. |
+| `copyInputValues` | `(source, target) => void` | Copy values input-by-input, skipping file inputs. | **trivial.** |
+| `handleActivatingKeypress` | `(event, callback) => void` | Space/Enter → preventDefault + callback. | **none** logic; **deprecate** (`activate` event supersedes it) — §4.D. |
+
+### 4.C Constants & shared state (keep as-is on the namespace)
+
+DOM objects `$win`/`$doc`/`$bod` and `$scrollContainer` are **jQuery collections** in legacy. Modern core replaces
+them with native references and exposes both:
+
+| Legacy | Modern core |
+| --- | --- |
+| `$win` (`$(window)`) | `win = window` (compat exposes `$win`). |
+| `$doc` (`$(document)`) | `doc = document`. |
+| `$bod` (`$(document.body)`) | `bod = document.body`. |
+| `$scrollContainer` | `scrollContainer: EventTarget = window`. |
+
+Plain constants (keep verbatim, **none**): all key codes (`BACKSPACE_KEY`…`META_KEY`), `JS_ARIA_CLASS`,
+`JS_ARIA_TRUE_CLASS`, `JS_ARIA_FALSE_CLASS`, `PRIMARY_CLICK`, `SECONDARY_CLICK`, `X_AXIS`, `Y_AXIS`, `FX_DURATION`,
+`TEXT_NODE`, `SHAKE_STEPS`, `SHAKE_STEP_DURATION`. Mutable flags: `activateEventsMuted`, `resizeEventsMuted`, `rtl`,
+`ltr`. Internal memo fields `_isMobileBrowser`, `_isMobileOrTabletBrowser`, `_eventHandlers` (→ `ClassEventBus`
+internals).
+
+`rtl`/`ltr` derive from `document.body.classList.contains('rtl')` at init.
+
+### 4.D Candidates for deprecation
+
+Keep them working (compat) but mark `@deprecated` and prefer the alternative:
+
+| Member | Reason / replacement |
+| --- | --- |
+| `log` | Already `@deprecated`. Use `console` directly. |
+| `isArray` | Use `Array.isArray`. |
+| `handleActivatingKeypress` | Already `@deprecated`. Use the `activate` event. |
+| `isMobileBrowser` | UA sniffing; prefer feature/pointer media queries. Flag, don't remove yet (call sites exist). |
+| `isJquery` | jQuery-only concept → compat layer, not core. |
+| `Menu` (alias of `CustomSelect`), `ShortcutManager` (alias of `UiLayerManager`) | Already `@deprecated` aliases — compat-only. |
+| `$win`/`$doc`/`$bod`/`$scrollContainer` (jQuery forms) | Native `win`/`doc`/`bod`/`scrollContainer` in core; jQuery forms are compat-only. |
+
+### 4.E New core primitive required: focusable-element matcher
+
+Several focus helpers depend on jQuery-UI's `:focusable`/`:focusable:visible`. The modern core must ship a native
+equivalent, since this has no built-in DOM counterpart:
+
+```ts
+// utils/focusable.ts
+export function isFocusable(el: Element): boolean;          // visible + not disabled + naturally/explicitly focusable
+export function isKeyboardFocusable(el: Element): boolean;  // isFocusable && tabindex !== '-1'
+export function getFocusableElements(container: Element): HTMLElement[];
+export function isVisible(el: Element): boolean;            // offsetParent / getClientRects / visibility check
+```
+
+This is the single biggest reimplementation risk. The matcher must cover: links/areas with `href`, form controls not
+`disabled`, `[contenteditable]`, `[tabindex]` (incl. negative for `isFocusable` but excluded for keyboard), and
+visibility (`display:none`/`visibility:hidden`/zero-size). Recommend modeling on the well-known
+jQuery-UI `:focusable` algorithm to preserve behavior.
+
+---
+
+## 5. Settings system
+
+### 5.1 Legacy
+
+```js
+setSettings(settings, defaults) {
+  const base = typeof this.settings === 'undefined' ? {} : this.settings;
+  this.settings = $.extend({}, base, defaults, settings);
+}
+```
+
+`$.extend({}, a, b, c)` is a **shallow** left-to-right merge into a fresh object: `c` wins over `b` wins over `a`.
+Precedence: existing `this.settings` (lowest) < `defaults` < `settings` (highest).
+
+### 5.2 Modern (no jQuery)
+
+`$.extend` shallow is exactly `Object.assign` for plain objects. **Decision: shallow merge** (matching legacy; do
+**not** silently deep-merge — call sites rely on shallow semantics, e.g. replacing a whole nested options object).
+
+```ts
+setSettings<S extends GarnishBaseSettings>(settings?: Partial<S>, defaults?: Partial<S>): void {
+  const base = this.settings ?? {};
+  this.settings = Object.assign({}, base, defaults, settings) as S;
+}
+```
+
+Notes:
+
+- `null`/`undefined` args are skipped by `Object.assign` (matches `$.extend` ignoring them).
+- Legacy guards `typeof this.settings === 'undefined'`; modern uses `?? {}` (covers both `null` initial value and
+  unset).
+- A typed `defineSettings<S>(defaults: S)` helper is **recommended** so subclasses declare defaults once and get a
+  typed `this.settings`. Optional sugar, not required for parity.
+
+---
+
+## 6. Proposed module layout & export surface
+
+```
+packages/craftcms-garnish/src/
+  index.ts                 # public barrel; assembles the Garnish namespace object
+  base.ts                  # abstract Base<S> class
+  events.ts                # parseEvents/formatDomEvents, GarnishEvent, EventEmitter, ClassEventBus
+  dom-listeners.ts         # DomListenerRegistry, ElementInput coercion
+  custom-events/
+    index.ts               # installActivate/installTextchange/installResize + shared ResizeObserver
+    activate.ts
+    textchange.ts
+    resize.ts
+  managers/
+    esc-manager.ts         # EscManager (Base subclass)
+    ui-layer-manager.ts    # UiLayerManager (Base subclass)
+  utils/
+    index.ts               # re-export
+    dom.ts                 # coerceElement(s), hasAttr, getOffset, hitTest, isCursorOver, getElement, copyTextStyles
+    focusable.ts           # isFocusable/isKeyboardFocusable/getFocusableElements/isVisible (§4.E)
+    focus.ts               # focusIsInside, first/setFocusWithin, trap/releaseFocusWithin, getFocusedElement
+    aria.ts                # addModalAttributes, ariaHide, hasJsAriaClass, isScriptOrStyleElement, modal-bg layer helpers
+    forms.ts               # getInputBasename, getInputPostVal, findInputs, getPostData, copyInputValues
+    animation.ts           # shake, scrollContainerToElement, raf/caf, prefersReducedMotion, getUserPreferredAnimationDuration
+    env.ts                 # isMobileBrowser, isPrimaryClick, isCtrlKeyPressed, getBodyScrollTop
+    misc.ts                # getDist, within, isString, isArray(dep), isTextNode, log(dep), handleActivatingKeypress(dep)
+  constants.ts             # key codes, ARIA classes, axis/click/node/FX/shake constants
+  types.ts                 # GarnishBaseSettings, ElementInput, shared types
+  globals.ts               # win/doc/bod/scrollContainer refs, rtl/ltr, mute flags, shared ClassEventBus instance
+```
+
+### 6.1 Public exports (`index.ts`)
+
+The core exports **named symbols** (tree-shakeable, the modern preference) **and** assembles a `Garnish` namespace
+object that mirrors the legacy shape for incremental migration and for the compat layer to extend.
+
+```ts
+// Named exports (preferred for new code)
+export { Base } from './base';
+export type { GarnishBaseSettings } from './types';
+export {
+  EventEmitter, ClassEventBus, parseEvents, formatDomEvents,
+  type GarnishEvent, type GarnishEventHandler,
+} from './events';
+export { DomListenerRegistry, type ElementInput, type DomListenerOptions } from './dom-listeners';
+export { installActivate, installTextchange, installResize } from './custom-events';
+export { EscManager } from './managers/esc-manager';
+export { UiLayerManager } from './managers/ui-layer-manager';
+export * from './utils';
+export * from './constants';
+
+// Namespace object (legacy-shaped; what compat re-exposes as window.Garnish)
+export const Garnish = {
+  // constants & globals
+  ...constants, win, doc, bod, scrollContainer, rtl, ltr,
+  activateEventsMuted: false, resizeEventsMuted: false,
+  // classes
+  Base, EscManager, UiLayerManager, /* + other modules as ported */
+  // class-level event bus (bound to shared instance)
+  on: (...a) => garnishClassBus.on(...a),
+  off: (...a) => garnishClassBus.off(...a),
+  once: (...a) => garnishClassBus.once(...a),
+  // utilities (all of §4 that survive in core)
+  getDist, within, hitTest, getOffset, /* ... */
+  // managers are attached at init time:
+  escManager: undefined as EscManager | undefined,
+  uiLayerManager: undefined as UiLayerManager | undefined,
+};
+
+export function initGarnish(): typeof Garnish {
+  Garnish.escManager = new EscManager();
+  Garnish.uiLayerManager = new UiLayerManager();
+  return Garnish;
+}
+
+export default Garnish;
+```
+
+### 6.2 Manager singletons
+
+Legacy attaches `Garnish.escManager` / `Garnish.uiLayerManager` during init (other modules read them, e.g.
+`hideModalBackgroundLayers` uses `Garnish.uiLayerManager`). Modern core exposes `initGarnish()` to instantiate them
+once and assign onto the namespace, instead of the implicit global-singleton-on-import side effect. The compat layer
+calls `initGarnish()` and binds the result to `window.Garnish` (guarded like legacy's
+`if (typeof window.Garnish === 'undefined')`).
+
+### 6.3 What the core deliberately omits
+
+- No `window.Garnish` assignment in core (compat does it).
+- No `$.fn.activate/textchange/resize` chaining sugar (jQuery-only; compat re-adds).
+- No `$.event.special` (replaced by §3 installers).
+- No `isJquery` (compat).
+- Velocity.js is removed entirely; animation helpers use WAAPI/rAF.
+
+---
+
+## 7. Compatibility wart register (for the compat layer)
+
+Behaviors the modern core preserves *as quirks* so the compat layer doesn't have to special-case them:
+
+1. Event split inconsistency: pub/sub splits on space, `addListener` on comma (§2.1).
+2. `trigger` event-object key precedence: `{data} <- triggerData <- {type,target}` (§2.3).
+3. `findInputs` selector includes the bogus `text` tag (§4.B) — preserved verbatim.
+4. `getInputPostVal` returns `''` (not `null`) for a null-valued `<select>`.
+5. `_namespace` random scheme kept (UUID with fallback) for parity/debugging.
+6. `once` implemented as wrapper-closure so `off(events, handler)` removes it (§2.3).
+7. `Garnish.on/once` `console.warn` on undefined target (§2.4).
+
+---
+
+## 8. Open decisions flagged for the team
+
+- **`isMobileBrowser`**: keep UA-sniffing port verbatim, or replace with pointer/media-query detection? Recommend keep
+  for now (call-site parity), schedule replacement.
+- **`getFocusedElement` return type**: legacy returns a jQuery collection; modern returns `Element | null`. Confirm no
+  core call site relies on collection methods (compat returns `$(...)`).
+- **Focusable matcher fidelity** (§4.E): must match jQuery-UI `:focusable` closely; budget test coverage here — it
+  underpins focus traps and modal accessibility.
+- **`shake`/`scrollContainerToElement`** animation backend: WAAPI vs rAF. Recommend WAAPI (`element.animate`) for
+  shake, manual `scrollTop` tween (or `scrollIntoView({behavior})`) for scroll, both gated by
+  `prefersReducedMotion`.
diff --git a/packages/craftcms-garnish/docs/02-dependency-graph.md b/packages/craftcms-garnish/docs/02-dependency-graph.md
new file mode 100644
index 00000000000..2cb1e0c67a5
--- /dev/null
+++ b/packages/craftcms-garnish/docs/02-dependency-graph.md
@@ -0,0 +1,823 @@
+# Garnish Library Dependency Graph & jQuery Migration Analysis
+
+## Executive Summary
+
+This document provides a comprehensive mapping of the Garnish JavaScript library's internal module dependencies, jQuery coupling levels, and external API usage. It serves as a foundation for planning the jQuery → vanilla JavaScript migration.
+
+**Key Findings:**
+- **23 modules total** (excluding lib/ and index/entry files)
+- **Core foundation cluster**: Base, BaseDrag, Base.js, Garnish.js
+- **High jQuery coupling** (26+ uses): Select (41), DragSort (21), BaseDrag (28), HUD (15)
+- **Most-used public APIs**: Base, Modal, DragSort, HUD, DisclosureMenu
+- **Leaf modules** (easier to migrate first): EscManager, DragMove, CheckboxSelect, MultiFunctionBtn
+
+---
+
+## Module Inventory & Analysis
+
+### Foundation Layer
+
+#### 1. **lib/Base.js** - Prototypal Inheritance System
+- **Lines:** 160 (relatively small)
+- **jQuery Coupling:** 0 uses
+- **Difficulty to Remove jQuery:** N/A (no jQuery)
+- **Role:** Provides the `.extend()` mechanism for all class definitions; foundational metaprogramming
+- **Key Exports:** `Base.extend()`, `Base.implement()`
+- **Consumers:** All other modules that extend Base
+- **Migration Notes:** This is pure JavaScript and requires no changes.
+
+---
+
+#### 2. **Base.js** - Garnish Base Class
+- **Lines:** 193
+- **jQuery Coupling:** 10 uses
+  - `$.noop` (default callbacks)
+  - `$.extend` (merge settings)
+  - `$.trim` (string utilities)
+  - `$.proxy` (function binding)
+  - jQuery event triggering utilities
+- **DOM Manipulation:** NO
+- **Event Handling:** YES (custom events via `trigger()`, instance-level event handlers)
+- **Difficulty to Remove jQuery:** **LOW**
+  - `$.noop` → Replace with `() => {}`
+  - `$.extend` → Replace with `Object.assign()` or spread operator
+  - `$.trim` → Replace with `String.trim()`
+  - `$.proxy` → Replace with `.bind()`
+- **Critical Methods:**
+  - `constructor()` - Unique namespace assignment for events
+  - `on()`, `off()`, `once()`, `trigger()` - Custom event system
+  - `addListener()`, `removeListener()` - jQuery event delegation wrappers
+  - `setSettings()` - Configuration merging
+- **Dependencies:** `lib/Base.js`, Garnish (for constants)
+- **Downstream:** ALL other modules
+- **Migration Priority:** **TIER 1** (foundational)
+
+---
+
+#### 3. **Garnish.js** - Global Namespace & Utilities
+- **Lines:** 1,212 (largest single module)
+- **jQuery Coupling:** Extensive
+  - `$(window)`, `$(document)`, `$(document.body)` - Global references
+  - `$.extend` - Configuration merging
+  - `$.event.special` - Custom event registration (jQuery internals)
+  - `$.each` - Iteration
+  - `$.makeArray` - Array conversion
+  - `$.inArray` - Array searching
+  - `$.data` - Element data storage
+  - `.velocity()` - Animation library (external)
+- **DOM Manipulation:** YES
+  - jQuery selectors throughout (`.find()`, `.filter()`, etc.)
+  - CSS operations (`.css()`, `.addClass()`, `.removeClass()`)
+  - Attribute manipulation (`.attr()`, `.prop()`)
+  - Focus/scroll management
+- **Event Handling:** YES
+  - Custom events: `activate`, `textchange`, `resize`
+  - `$.event.special` hooks (deep jQuery integration)
+  - Global event delegation
+- **Difficulty to Remove jQuery:** **HIGH**
+  - `.velocity()` → Requires replacement with CSS transitions or another animation library
+  - `$.event.special` → Requires native event system rearchitecture
+  - Global caching of `$win`, `$doc`, `$bod` → Straightforward but widespread
+  - Selector utilities heavily rely on jQuery
+- **Critical Public API:**
+  - **Constants:** All keycode constants (RETURN_KEY, ESC_KEY, etc.), axis constants, CSS classes
+  - **Global References:** `$win`, `$doc`, `$bod`, `$scrollContainer`
+  - **Utility Methods:** `getOffset()`, `hitTest()`, `isCursorOver()`, `scrollContainerToElement()`, `shake()`
+  - **DOM Utilities:** `copyTextStyles()`, `hasAttr()`, `getElement()`
+  - **Input Utilities:** `findInputs()`, `getPostData()`, `getInputPostVal()`
+  - **ARIA/A11y:** `addModalAttributes()`, `hideModalBackgroundLayers()`, `trapFocusWithin()`, focus management
+  - **Animation:** `requestAnimationFrame`, `cancelAnimationFrame` wrappers
+  - **Accessibility:** `isKeyboardFocusable()`, `firstFocusableElement()`, `setFocusWithin()`
+  - **Event Listener Management:** `on()`, `off()`, `once()` (class-level, not instance)
+- **Dependencies:** Base (for constants)
+- **Downstream:** ALL modules (used globally)
+- **Migration Priority:** **TIER 1** (foundational, but complex)
+
+---
+
+#### 4. **index.js** - Entry Point & Initialization
+- **Lines:** 18
+- **jQuery Coupling:** 0 uses directly
+- **Role:** Initializes singleton instances (escManager, uiLayerManager) and re-exports Garnish
+- **Critical:** Re-assigns `Garnish.escManager` and `Garnish.uiLayerManager` to avoid circular dependencies
+- **Migration Priority:** **TIER 2** (depends on UiLayerManager, EscManager)
+
+---
+
+## Component Modules Analysis
+
+### UI Container & Overlay Management
+
+#### 5. **UiLayerManager.js** - Layer & Focus Management
+- **Lines:** 181
+- **jQuery Coupling:** 6 uses
+  - `$.isPlainObject` - Parameter type checking
+  - `$(container)` - jQuery wrapper
+  - `$.each` - Iteration
+  - jQuery selectors for layer finding
+- **DOM Manipulation:** Minimal (mostly reference storage)
+- **Event Handling:** YES - Keyboard shortcuts/keydown events
+- **Difficulty to Remove jQuery:** **LOW**
+- **Key Methods:**
+  - `addLayer()`, `removeLayer()` - Layer stack management
+  - `registerShortcut()`, `unregisterShortcut()` - Keyboard shortcut system
+  - `triggerShortcut()` - Event dispatch
+- **Dependencies:** Base, Garnish
+- **Downstream:** Modal, HUD, DisclosureMenu, CustomSelect, ContextMenu
+- **Public API Usage:** `new Garnish.UiLayerManager()` (instantiated once), `.registerShortcut()`, `.addLayer()`, `.removeLayer()`
+- **Migration Priority:** **TIER 2**
+
+---
+
+#### 6. **Modal.js** - Centered Modal Dialog
+- **Lines:** 451
+- **jQuery Coupling:** 13 uses
+  - `$('<div/>')` - Element creation
+  - `.find()`, `.data()`, `.appendTo()` - DOM traversal
+  - `.offset()`, `.outerWidth()`, `.outerHeight()` - Dimension queries
+  - `.velocity()` - Fade in/out animations
+  - `.hasClass()`, `.addClass()`, `.removeClass()` - Class manipulation
+- **DOM Manipulation:** YES (creates modal container, shade, resizing elements)
+- **Event Handling:** YES - Window resize, drag interactions
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - `.velocity()` animations → CSS transitions
+  - Dimension calculations → `getBoundingClientRect()`
+  - Element creation → `document.createElement()`
+- **Key Methods:**
+  - `show()`, `hide()`, `quickShow()`, `quickHide()` - Visibility toggling
+  - `updateSizeAndPosition()` - Responsive sizing
+  - `getWidth()`, `getHeight()` - Dimension getters
+- **Dependencies:** Base, Garnish, DragMove (optional, if resizable), BaseDrag (for resize handle)
+- **Downstream:** Many utilities and feature modules
+- **Public API Usage:** `new Garnish.Modal()` (13 usages)
+- **Migration Priority:** **TIER 2** (high usage, medium complexity)
+
+---
+
+#### 7. **HUD.js** - Floating Popover/Tooltip
+- **Lines:** 764
+- **jQuery Coupling:** 15 uses
+  - `.offset()`, `.scrollParent()`, `.outerWidth/Height()` - Layout calculations
+  - `.find()`, `.filter()`, `.not()` - DOM queries
+  - `.appendTo()`, `.insertBefore()`, `.insertAfter()` - DOM insertion
+  - `.css()` - Inline styling
+  - `.velocity()` - Animations
+- **DOM Manipulation:** YES (creates HUD container, form, header/footer)
+- **Event Handling:** YES - Window resize, scroll, focus trap
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - Similar to Modal (animations, layout calculations)
+  - Layout logic (orientation detection) is core complexity
+- **Key Methods:**
+  - `show()`, `hide()`, `toggle()` - Visibility
+  - `updateBody()` - Content updates
+  - `updateSizeAndPosition()` - Smart positioning (bottom/top/left/right)
+  - `submit()` - Form submission callback
+- **Dependencies:** Base, Garnish, UiLayerManager
+- **Downstream:** Dashboard, tablesettings, and many feature modules
+- **Public API Usage:** `new Garnish.HUD()` (5 direct instantiations, but 21 total references)
+- **Migration Priority:** **TIER 2** (high usage, medium complexity)
+
+---
+
+#### 8. **DisclosureMenu.js** - Dropdown/Popover Menu
+- **Lines:** 1,008 (largest UI component)
+- **jQuery Coupling:** 20 uses
+  - `.css()`, `.velocity()` - Animations and styling
+  - `.find()`, `.closest()`, `.filter()`, `.parent()` - DOM traversal
+  - `.attr()` - Attribute manipulation
+  - `.hasClass()`, `.addClass()`, `.removeClass()` - Class toggling
+- **DOM Manipulation:** YES (creates menu structure, search input, items)
+- **Event Handling:** YES - Click, keydown (arrow keys, search), focus management
+- **Difficulty to Remove jQuery:** **MEDIUM-HIGH**
+  - Complex focus and visibility logic
+  - Search functionality with DOM filtering
+  - `.velocity()` animations
+  - Deep DOM manipulation for item creation
+- **Key Methods:**
+  - `show()`, `hide()` - Visibility
+  - `addItem()`, `addGroup()`, `removeItem()` - Content management
+  - `createItem()` - Dynamic item creation
+  - `setContainerPosition()` - Smart positioning
+  - `handleKeypress()` - Keyboard navigation
+- **Dependencies:** Base, Garnish, UiLayerManager
+- **Downstream:** High-level UI features
+- **Public API Usage:** `new Garnish.DisclosureMenu()` (12 usages)
+- **Migration Priority:** **TIER 2-3** (high usage, complex)
+
+---
+
+### Drag & Drop System
+
+#### 9. **BaseDrag.js** - Base Drag Handler
+- **Lines:** 583
+- **jQuery Coupling:** 28 uses (high)
+  - `.scrollParent()`, `.offset()`, `.outerWidth/Height()` - Layout info
+  - `.find()`, `.filter()`, `.index()` - DOM traversal
+  - `.data()`, `.removeData()` - Element data storage
+  - `$.inArray`, `$.makeArray` - Array utilities
+  - `$.isPlainObject` - Type checking
+- **DOM Manipulation:** NO (only reads properties)
+- **Event Handling:** YES - mousedown, mousemove, mouseup
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - `.scrollParent()` → Manual parent traversal with scroll checks
+  - `.offset()` → `getBoundingClientRect()` + scroll offset
+  - `.data()` → `WeakMap` or element properties
+  - Everything else is straightforward
+- **Key Methods:**
+  - `startDragging()`, `stopDragging()`, `drag()` - Lifecycle
+  - `addItems()`, `removeItems()` - Item management
+  - `allowDragging()` - Override hook
+  - `getPrevItem()`, `getNextItem()` - Item navigation
+- **Dependencies:** Base, Garnish
+- **Downstream:** Drag, DragSort, DragDrop, Modal (resize handle)
+- **Migration Priority:** **TIER 1-2** (foundational for drag system)
+
+---
+
+#### 10. **Drag.js** - Element Dragging with Helpers
+- **Lines:** 462
+- **jQuery Coupling:** 8 uses
+  - `.outerWidth/Height()` - Dimension queries
+  - `.clone()`, `.addClass()`, `.appendTo()` - Helper element creation
+  - `.offset()` - Position calculation
+  - `.velocity()` - Animation for return-to-source
+- **DOM Manipulation:** YES (creates helper clones)
+- **Event Handling:** NO (delegated to BaseDrag)
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - `.velocity()` → CSS transitions
+  - `.clone()` → `element.cloneNode(true)`
+  - Layout calculations → Native APIs
+- **Key Methods:**
+  - `setDraggee()`, `appendDraggee()` - Draggee management
+  - `returnHelpersToDraggees()`, `fadeOutHelpers()` - Animation
+  - `findDraggee()`, `getHelperTarget*()` - Helper positioning
+- **Dependencies:** Base, BaseDrag, Garnish
+- **Downstream:** DragSort, DragDrop, Modal (resize)
+- **Migration Priority:** **TIER 2**
+
+---
+
+#### 11. **DragDrop.js** - Drag with Drop Targets
+- **Lines:** 116
+- **jQuery Coupling:** 5 uses
+  - `$(element)` - jQuery wrapper
+  - `.addClass()`, `.removeClass()` - Class manipulation
+  - `$.extend` - Settings merging
+  - `$.noop` - Default callback
+- **DOM Manipulation:** Minimal
+- **Event Handling:** NO (delegated to Drag)
+- **Difficulty to Remove jQuery:** **LOW**
+- **Key Methods:**
+  - `onDrag()` - Override to check drop targets
+  - `updateDropTargets()` - Target list refresh
+- **Dependencies:** Drag, Garnish
+- **Downstream:** Feature modules
+- **Migration Priority:** **TIER 2**
+
+---
+
+#### 12. **DragSort.js** - Sortable List Reordering
+- **Lines:** 697
+- **jQuery Coupling:** 21 uses
+  - `.insertBefore()`, `.insertAfter()`, `.prependTo()` - DOM insertion
+  - `.offset()`, `.outerWidth/Height()` - Layout calculations
+  - `.index()` - Position finding
+  - `.find()`, `.not()`, `.filter()` - DOM traversal
+  - `.contains()` - Element containment checks
+- **DOM Manipulation:** YES (moves items during drag)
+- **Event Handling:** NO (delegated to Drag)
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - Layout calculations → Native APIs
+  - DOM insertion → Native APIs
+  - Coordinate calculations → Pure math
+- **Key Methods:**
+  - `onDragStart()`, `onDrag()`, `onDragStop()` - Lifecycle
+  - `_getClosestItem()` - Hit detection (complex algorithm)
+  - `_updateInsertion()` - Visual feedback
+  - `_getItemMidpoint()` - Layout calculations (with caching optimization)
+- **Dependencies:** Drag, Garnish
+- **Downstream:** Component lists, matrix fields
+- **Public API Usage:** `new Garnish.DragSort()` (12 usages)
+- **Migration Priority:** **TIER 2** (high usage)
+
+---
+
+#### 13. **DragMove.js** - Simple Drag-to-Move
+- **Lines:** 15
+- **jQuery Coupling:** 0 uses
+- **DOM Manipulation:** YES (sets `left`, `top` CSS)
+- **Event Handling:** NO (delegated to BaseDrag)
+- **Difficulty to Remove jQuery:** N/A
+- **Role:** Trivial subclass that just applies mouse deltas to element position
+- **Dependencies:** BaseDrag
+- **Downstream:** Modal (if draggable), windows
+- **Migration Priority:** **TIER 3** (minimal code, no jQuery)
+
+---
+
+### Menu & Selection Systems
+
+#### 14. **Select.js** - Multi-Item Selection Interface
+- **Lines:** 1,018 (largest module besides Garnish.js)
+- **jQuery Coupling:** 41 uses (highest)
+  - `.find()`, `.filter()`, `.index()`, `.not()`, `.eq()`, `.slice()` - DOM traversal
+  - `.offset()`, `.outerWidth/Height()` - Layout calculations
+  - `.addClass()`, `.removeClass()`, `.attr()` - DOM attribute manipulation
+  - `$.inArray`, `$.makeArray` - Array utilities
+  - `.data()` - Element data storage
+- **DOM Manipulation:** Minimal (only class/attribute manipulation)
+- **Event Handling:** YES - Click, shift-click, keyboard (arrows, Ctrl+A, space)
+- **Difficulty to Remove jQuery:** **MEDIUM-HIGH**
+  - Extensive DOM traversal logic that depends on jQuery
+  - Layout calculations → Native APIs
+  - Array utilities → Native alternatives
+  - Event system remains jQuery-delegated
+- **Key Methods:**
+  - `selectItem()`, `selectRange()`, `selectAll()` - Selection operations
+  - `addItems()`, `removeItems()` - Item management
+  - `getClosestItem()` - Spatial querying (complex algorithm)
+  - `focusItem()`, `setFocusableItem()` - Focus management
+  - `onMouseDown()`, `onMouseUp()`, `onKeyDown()` - Event handlers
+- **Dependencies:** Base, Garnish
+- **Downstream:** CustomSelect, SelectMenu, MenuBtn, and form inputs
+- **Public API Usage:** `new Garnish.Select()` (6 usages)
+- **Migration Priority:** **TIER 2-3** (high usage, high coupling)
+
+---
+
+#### 15. **CustomSelect.js** - Dropdown Menu Interface
+- **Lines:** 333
+- **jQuery Coupling:** 5 uses
+  - `.find()`, `.attr()`, `.data()` - DOM queries
+  - `.appendTo()` - DOM insertion
+  - `.offset()`, `.outerWidth/Height()`, `.scrollLeft/Top()` - Layout
+  - `.css()` - Styling
+  - `.velocity()` - Animations
+- **DOM Manipulation:** YES (menu positioning and layout)
+- **Event Handling:** YES - Click, hover state management
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - Layout calculations → Native APIs
+  - `.velocity()` → CSS transitions
+- **Key Methods:**
+  - `addOptions()` - Option registration
+  - `show()`, `hide()` - Visibility
+  - `setPositionRelativeToAnchor()` - Smart positioning logic
+  - `selectOption()` - Selection callback
+  - `_alignLeft/Right/Center()` - Positioning helpers
+- **Dependencies:** Base, Garnish, UiLayerManager
+- **Downstream:** MenuBtn, form controls
+- **Public API Usage:** Referenced as `.Menu` (deprecated alias), extends to SelectMenu
+- **Migration Priority:** **TIER 2-3**
+
+---
+
+#### 16. **SelectMenu.js** - Extends CustomSelect
+- **Lines:** 83
+- **jQuery Coupling:** 2 uses
+  - `$.extend` - Settings merging
+- **DOM Manipulation:** NO (delegated to CustomSelect)
+- **Event Handling:** NO
+- **Difficulty to Remove jQuery:** **LOW**
+- **Role:** Thin wrapper adding `.sel` class management for radio-button-style selections
+- **Dependencies:** CustomSelect, Garnish
+- **Migration Priority:** **TIER 3**
+
+---
+
+#### 17. **MenuBtn.js** - Button That Opens Menu
+- **Lines:** 444
+- **jQuery Coupling:** 5 uses
+  - `.data()`, `.attr()` - Element data/attributes
+  - `.addClass()`, `.removeClass()`, `.filter()` - Class manipulation
+  - `.contains()` - Element containment
+  - MutationObserver usage
+- **DOM Manipulation:** Minimal
+- **Event Handling:** YES - Click, keydown (search, navigation)
+- **Difficulty to Remove jQuery:** **LOW**
+  - Most operations are straightforward replacements
+- **Key Methods:**
+  - `showMenu()`, `hideMenu()` - Menu visibility
+  - `onKeyDown()` - Keyboard navigation & search
+  - `focusOption()`, `moveFocusUp/Down()` - Focus management
+  - `onMouseDown()` - Toggle menu
+- **Dependencies:** Base, Garnish, CustomSelect (composed)
+- **Downstream:** Feature modules
+- **Public API Usage:** `new Garnish.MenuBtn()` (6 usages)
+- **Migration Priority:** **TIER 2**
+
+---
+
+#### 18. **ContextMenu.js** - Right-Click Context Menu
+- **Lines:** 171
+- **jQuery Coupling:** 8 uses
+  - `$('<div/>')`, `$('<ul/>')`, `$('<li/>')`, `$('<a/>')` - Element creation
+  - `.appendTo()` - DOM insertion
+  - `.css()` - Positioning
+  - `.mousedown()` - Event binding (not `.on()`, direct method)
+  - `.hide()`, `.show()` - Visibility
+- **DOM Manipulation:** YES (builds menu structure dynamically)
+- **Event Handling:** YES - contextmenu and mousedown
+- **Difficulty to Remove jQuery:** **MEDIUM**
+  - DOM creation → `document.createElement()`
+  - Event binding → `.addEventListener()`
+- **Key Methods:**
+  - `buildMenu()` - Dynamic menu construction
+  - `showMenu()`, `hideMenu()` - Visibility
+  - `enable()`, `disable()` - Toggle event listeners
+- **Dependencies:** Base, Garnish, UiLayerManager
+- **Downstream:** Specialized feature modules
+- **Migration Priority:** **TIER 3**
+
+---
+
+### Form & Text Input Components
+
+#### 19. **NiceText.js** - Textarea with Auto-Height & Char Count
+- **Lines:** 343
+- **jQuery Coupling:** 7 uses
+  - `.val()` - Input value access
+  - `.attr()`, `.removeAttr()` - Attribute manipulation
+  - `.css()` - Styling
+  - `.insertBefore()`, `.appendTo()` - DOM insertion
+  - `.height()`, `.width()` - Dimension queries
+  - `.velocity()` - Fade animations
+- **DOM Manipulation:** YES (creates hint container, char counter)
+- **Event Handling:** YES - textchange (custom event), keydown
+- **Difficulty to Remove jQuery:** **LOW-MEDIUM**
+  - Layout calculations → Native APIs
+  - `.velocity()` → CSS transitions
+- **Key Methods:**
+  - `initialize()` - Setup (called lazily on first visibility)
+  - `updateHeight()` - Auto-resize logic
+  - `showHint()`, `hideHint()` - Hint visibility
+  - `updateCharsLeft()` - Character counter update
+  - `getHeightForValue()` - Complex text measurement
+- **Dependencies:** Base, Garnish
+- **Downstream:** Forms, content editors
+- **Public API Usage:** `new Garnish.NiceText()` (3 usages)
+- **Migration Priority:** **TIER 2-3**
+
+---
+
+#### 20. **MixedInput.js** - Hybrid Text/Tag Input
+- **Lines:** 424
+- **jQuery Coupling:** 5 uses
+  - `.attr()`, `.val()`, `.css()`, `.prop()` - Element properties
+  - `.insertBefore()`, `.append()`, `.remove()` - DOM manipulation
+  - `$.inArray` - Array searching
+- **DOM Manipulation:** YES (creates text input elements dynamically)
+- **Event Handling:** YES - Click, focus, keydown (navigation)
+- **Difficulty to Remove jQuery:** **LOW**
+  - Mostly straightforward element operations
+- **Key Methods:**
+  - `addElement()`, `addTextElement()` - Add input elements
+  - `removeElement()` - Remove elements
+  - `setFocus()`, `focusPreviousElement()`, `focusNextElement()` - Focus management
+  - `setCaretPos()` - Cursor positioning
+- **Nested Class:** `TextElement` - Helper for text input lifecycle
+- **Dependencies:** Base, Garnish
+- **Downstream:** Advanced form inputs
+- **Public API Usage:** `new Garnish.MixedInput()` (1 usage)
+- **Migration Priority:** **TIER 3**
+
+---
+
+### Specialized Components
+
+#### 21. **CheckboxSelect.js** - "Select All" Checkbox Group
+- **Lines:** 97
+- **jQuery Coupling:** 2 uses
+  - `.find()`, `.filter()`, `.not()` - DOM selection
+  - `.prop()` - Property manipulation
+- **DOM Manipulation:** NO
+- **Event Handling:** YES - Change events
+- **Difficulty to Remove jQuery:** **LOW**
+- **Key Methods:**
+  - `onAllChange()` - Toggle all items when master checkbox changes
+  - `isAllChecked()` - State query
+- **Dependencies:** Base, Garnish
+- **Downstream:** Filter UIs
+- **Public API Usage:** `new Garnish.CheckboxSelect()` (2 usages)
+- **Migration Priority:** **TIER 3**
+
+---
+
+#### 22. **MultiFunctionBtn.js** - Button with Loading/Success States
+- **Lines:** 125
+- **jQuery Coupling:** 2 uses
+  - `.data()`, `.find()` - DOM queries
+  - `.addClass()`, `.removeClass()` - Class toggling
+- **DOM Manipulation:** Minimal
+- **Event Handling:** NO
+- **Difficulty to Remove jQuery:** **LOW**
+- **Key Methods:**
+  - `busyEvent()`, `successEvent()`, `failureEvent()` - State changes
+  - `updateMessages()` - ARIA live region updates
+- **Dependencies:** Base, Garnish
+- **Downstream:** Action buttons
+- **Public API Usage:** `new Garnish.MultiFunctionBtn()` (1 usage)
+- **Migration Priority:** **TIER 3**
+
+---
+
+#### 23. **EscManager.js** - ESC Key Handler (Deprecated)
+- **Lines:** 55
+- **jQuery Coupling:** 0 uses
+- **DOM Manipulation:** NO
+- **Event Handling:** YES - Keyup for ESC key
+- **Difficulty to Remove jQuery:** N/A
+- **Role:** Legacy handler for ESC key (superseded by UiLayerManager)
+- **Status:** Deprecated; use UiLayerManager instead
+- **Dependencies:** Base, Garnish
+- **Migration Priority:** **TIER 4** (deprecated, minimal usage)
+
+---
+
+#### 24. **icons/ResizeHandle.js** - SVG Icon
+- **Lines:** 4
+- **jQuery Coupling:** 0 uses
+- **Role:** Simple SVG string export
+- **Migration Priority:** **TIER 4** (no migration needed)
+
+---
+
+## Dependency Graph (Topological Ordering)
+
+### Leaves First (Easiest to Migrate First)
+
+```
+TIER 4 (No dependencies, no jQuery):
+  - lib/Base.js
+  - icons/ResizeHandle.js
+  - EscManager.js
+  - DragMove.js
+
+TIER 3 (Leaf components, low jQuery):
+  - SelectMenu.js (extends CustomSelect)
+  - CheckboxSelect.js
+  - MultiFunctionBtn.js
+  - MixedInput.js
+  - ContextMenu.js
+  - DragDrop.js
+
+TIER 2 (Mid-complexity, moderate jQuery):
+  - NiceText.js
+  - UiLayerManager.js
+  - MenuBtn.js
+  - CustomSelect.js
+  - Modal.js
+  - HUD.js
+  - Drag.js
+  - BaseDrag.js
+  - DragSort.js
+  - DisclosureMenu.js
+
+TIER 1 (Foundational, highest priority):
+  - Base.js (used by all others)
+  - Garnish.js (global utilities, constants, event system)
+```
+
+### Dependency Graph (Text Form)
+
+```
+lib/Base.js
+  ↓
+Base.js (→ Garnish constants)
+  ↓
+├─→ UiLayerManager.js
+│     ↓
+│     ├─→ Modal.js
+│     ├─→ HUD.js
+│     ├─→ CustomSelect.js
+│     │     ├─→ SelectMenu.js
+│     │     └─→ MenuBtn.js
+│     └─→ ContextMenu.js
+│
+├─→ BaseDrag.js (→ Garnish constants)
+│     ├─→ Drag.js
+│     │     ├─→ DragSort.js (uses DragSort-specific logic)
+│     │     └─→ DragDrop.js
+│     ├─→ DragMove.js (trivial)
+│     └─→ Modal.js (for resize handle)
+│
+├─→ Select.js (high jQuery coupling)
+│
+├─→ NiceText.js
+│
+├─→ MixedInput.js (→ Base utility)
+│
+├─→ CheckboxSelect.js
+│
+└─→ MultiFunctionBtn.js
+
+Garnish.js (entry point, includes all above)
+  ↓
+index.js (instantiates singletons, re-exports)
+```
+
+---
+
+## jQuery Coupling Summary Table
+
+| Module | Lines | jQuery Uses | Difficulty | Key Issues |
+|--------|-------|------------|------------|-----------|
+| lib/Base.js | 160 | 0 | **NONE** | Pure JS, foundation |
+| Base.js | 193 | 10 | **LOW** | $.noop, $.extend, $.trim, $.proxy |
+| Garnish.js | 1,212 | ~50 | **HIGH** | $.event.special, .velocity(), selectors |
+| index.js | 18 | 0 | **NONE** | Entry point only |
+| UiLayerManager.js | 181 | 6 | **LOW** | $.isPlainObject, basic selectors |
+| Modal.js | 451 | 13 | **MEDIUM** | .velocity(), offset(), dimension queries |
+| HUD.js | 764 | 15 | **MEDIUM** | .velocity(), smart positioning, layout |
+| DisclosureMenu.js | 1,008 | 20 | **MEDIUM-HIGH** | Complex DOM, .velocity(), filtering |
+| BaseDrag.js | 583 | 28 | **MEDIUM** | .scrollParent(), .offset(), .data() |
+| Drag.js | 462 | 8 | **MEDIUM** | .clone(), .velocity() animations |
+| DragDrop.js | 116 | 5 | **LOW** | Basic utilities |
+| DragSort.js | 697 | 21 | **MEDIUM** | Layout calculations, DOM insertion |
+| DragMove.js | 15 | 0 | **NONE** | Trivial subclass |
+| Select.js | 1,018 | 41 | **MEDIUM-HIGH** | Most jQuery-heavy; extensive DOM ops |
+| CustomSelect.js | 333 | 5 | **MEDIUM** | Layout, .velocity() |
+| SelectMenu.js | 83 | 2 | **LOW** | Thin wrapper |
+| MenuBtn.js | 444 | 5 | **LOW** | Mostly native-friendly ops |
+| ContextMenu.js | 171 | 8 | **MEDIUM** | DOM creation, event binding |
+| NiceText.js | 343 | 7 | **LOW-MEDIUM** | Dimension queries, .velocity() |
+| MixedInput.js | 424 | 5 | **LOW** | Straightforward DOM ops |
+| CheckboxSelect.js | 97 | 2 | **LOW** | Minimal jQuery usage |
+| MultiFunctionBtn.js | 125 | 2 | **LOW** | Class manipulation only |
+| EscManager.js | 55 | 0 | **NONE** | Deprecated, pure JS |
+| icons/ResizeHandle.js | 4 | 0 | **NONE** | SVG string constant |
+
+---
+
+## External API Consumer Analysis
+
+### Highest-Priority Modules (Most Used by Consumers)
+
+**Rank 1: `Garnish.Base` (96 usages)**
+- Used as the superclass for virtually all Craft feature modules
+- Consumer pattern: `Craft.SomeFeature = Garnish.Base.extend({...})`
+- **Criticality:** ABSOLUTE (cannot remove without breaking everything)
+
+**Rank 2: `Garnish.Modal` (35 usages)**
+- Modals for settings, confirmations, editors
+- Usage: `new Garnish.Modal(container, settings)`
+- **Criticality:** VERY HIGH
+
+**Rank 3: `Garnish.DragSort` (16+ instantiations, 36+ references)**
+- Sortable lists, matrix fields, component reordering
+- Usage: `new Garnish.DragSort(items, settings)`
+- **Criticality:** VERY HIGH
+
+**Rank 4: `Garnish.HUD` (5+ instantiations, 21+ references)**
+- Floating popovers for quick edits, widget managers
+- Usage: `new Garnish.HUD(trigger, content, settings)`
+- **Criticality:** HIGH
+
+**Rank 5: `Garnish.DisclosureMenu` (12+ instantiations, 19+ references)**
+- Dropdown menus for navigation, actions
+- Usage: `new Garnish.DisclosureMenu(trigger, settings)`
+- **Criticality:** HIGH
+
+**Rank 6: `Garnish.Select` (6+ instantiations, 9+ references)**
+- Item selection UI for lists, filters
+- Usage: `new Garnish.Select(container, items, settings)`
+- **Criticality:** HIGH
+
+**Rank 7: `Garnish.MenuBtn` (6 instantiations)**
+- Action buttons with dropdown menus
+- Usage: `new Garnish.MenuBtn(button, menu, settings)`
+- **Criticality:** MEDIUM-HIGH
+
+### Key Constants Used by Consumers
+
+- **Keycodes:** `ESC_KEY`, `RETURN_KEY`, `TAB_KEY`, `SPACE_KEY`, `UP_KEY`, `DOWN_KEY`, `LEFT_KEY`, `RIGHT_KEY`, `HOME_KEY`, `END_KEY`, `BACKSPACE_KEY`, `DELETE_KEY`, `S_KEY`, `PAGE_UP_KEY`, `PAGE_DOWN_KEY`, `SHIFT_KEY`
+- **Axes:** `X_AXIS`, `Y_AXIS`
+- **ARIA Classes:** `JS_ARIA_CLASS`, `JS_ARIA_TRUE_CLASS`, `JS_ARIA_FALSE_CLASS`
+- **Timing:** `FX_DURATION`
+
+### Key Utility Methods Used
+
+- `Garnish.hitTest(x, y, elem)` - Hit detection for drag operations
+- `Garnish.scrollContainerToElement(container, elem)` - Scroll to view
+- `Garnish.shake(elem)` - Error shake animation
+- `Garnish.getOffset(elem)` - Position relative to scroll container
+- `Garnish.copyTextStyles(source, target)` - Style copying for text inputs
+- `Garnish.getPostData(container)` - Form serialization
+- Focus management: `setFocusWithin()`, `trapFocusWithin()`, `getKeyboardFocusableElements()`
+- `Garnish.uiLayerManager` - Global singleton for modal management and shortcuts
+
+---
+
+## Migration Strategy Recommendation
+
+### Phase 1: Foundation (Weeks 1-2)
+1. **lib/Base.js** - No changes needed
+2. **Base.js** - Replace jQuery utilities
+   - `$.noop` → `() => {}`
+   - `$.extend` → `Object.assign()`
+   - `$.trim` → `.trim()`
+   - `$.proxy` → `.bind()`
+3. **EscManager.js** - No changes needed
+4. **DragMove.js** - No changes needed
+
+### Phase 2: Core Infrastructure (Weeks 2-3)
+1. **Garnish.js** - LARGEST effort
+   - Refactor `$.event.special` custom events to native CustomEvent
+   - Replace global `$(window)`, `$(document)`, `$(document.body)` with direct references
+   - Replace `.scrollParent()` with manual traversal
+   - Replace `.velocity()` calls with CSS transitions or Animate API
+   - Refactor DOM utility methods to use native APIs
+2. **UiLayerManager.js** - Relatively light refactoring
+3. **index.js** - No changes (depends on above)
+
+### Phase 3: Drag System (Weeks 3-4)
+1. **BaseDrag.js** - Replace jQuery offset/dimension methods
+2. **Drag.js** - Update for BaseDrag changes, replace `.velocity()`
+3. **DragDrop.js** - Light refactoring
+4. **DragSort.js** - Update for Drag changes
+5. **DragMove.js** - Already pure
+
+### Phase 4: Modal & Overlay (Weeks 4-5)
+1. **Modal.js** - Replace layout calculations, animations
+2. **HUD.js** - Similar to Modal, plus positioning logic
+3. **UiLayerManager.js** (if not done in Phase 2)
+
+### Phase 5: Menu & Selection (Weeks 5-6)
+1. **Select.js** - MOST jQuery-heavy; careful refactoring
+2. **CustomSelect.js** - Update for Garnish changes
+3. **SelectMenu.js** - Light updates
+4. **MenuBtn.js** - Update for CustomSelect, Base changes
+5. **ContextMenu.js** - Replace DOM creation
+
+### Phase 6: Text & Utility (Weeks 6-7)
+1. **NiceText.js** - Replace dimension queries, .velocity()
+2. **MixedInput.js** - Update for Base changes
+3. **CheckboxSelect.js** - Minimal changes
+4. **MultiFunctionBtn.js** - Minimal changes
+
+### Phase 7: Integration & Testing (Week 8)
+1. Update all entry points (index.js, Garnish.js exports)
+2. Integration tests with consumer code
+3. Accessibility testing (focus management is critical)
+4. Performance testing (drag operations are compute-intensive)
+
+---
+
+## Critical Dependencies to Watch
+
+1. **`.scrollParent()` Usage** - Appears in BaseDrag, Select, HUD, Modal
+   - No native equivalent; requires manual DOM traversal
+   - Need to implement/share utility function
+
+2. **`.velocity()` Animations** - Appears in Garnish, Modal, HUD, Drag, CustomSelect, NiceText
+   - Replace with CSS transitions or requestAnimationFrame
+   - Consider animation library (Animate.css, WAAPI)
+
+3. **`$.event.special` Custom Events** - Only in Garnish.js (activate, textchange, resize)
+   - Replace with native CustomEvent
+   - Consider using native events directly if semantics match
+
+4. **Element `.data()` Storage** - Used in BaseDrag, Select, Modal, CustomSelect
+   - Replace with WeakMap or element properties
+   - Use `element._garnish` namespace to avoid conflicts
+
+5. **Array Utilities** - `$.inArray`, `$.makeArray`, `$.contains`
+   - `.indexOf()` and `.includes()`
+   - `Array.from()`
+   - `.contains()` → Manual check or native `.closest()`
+
+6. **Focus Management** - Critical for accessibility
+   - Select.js, MenuBtn.js, HUD.js, Modal.js
+   - Native focus API exists but jQuery's `:focusable` selector has custom logic
+   - Need shared utility for finding focusable elements
+
+---
+
+## Additional Notes
+
+### Performance Considerations
+- DragSort's `_getClosestItem()` is performance-critical (large datasets)
+- Already has optimization for pre-calculated midpoints
+- Pure JavaScript may be faster than jQuery for this algorithm
+
+### Accessibility
+- Multiple modules handle focus trapping and management
+- ARIA attributes are set/read extensively
+- Careful testing needed post-migration
+
+### Browser Compatibility
+- Code uses modern JavaScript features (arrow functions, Object.assign, const/let)
+- Assume modern browser baseline (ES6+)
+- No need to support IE11
+
+---
+
+## Document Metadata
+
+- **Generated:** 2025-06-17
+- **Framework Version:** Craft 6 (ES6 modules)
+- **jQuery Baseline:** 3.x
+- **Scope:** `/packages/craftcms-legacy/garnish/src/` (23 modules)
+- **External Consumer Directories:**
+  - `/packages/craftcms-legacy/` (feature modules)
+  - `/resources/js/` (CP interface)
+
diff --git a/packages/craftcms-garnish/docs/03-modal-slice.md b/packages/craftcms-garnish/docs/03-modal-slice.md
new file mode 100644
index 00000000000..f8466d74cba
--- /dev/null
+++ b/packages/craftcms-garnish/docs/03-modal-slice.md
@@ -0,0 +1,79 @@
+# Modal Slice — Dependency Footprint & PoC Contract
+
+> Modal is the chosen representative component for the vertical-slice PoC. It is medium-complexity: focus management,
+> sizing, animation, accessibility — but no recursive dependencies. This doc tells the build team exactly what core
+> must provide, what jQuery removals Modal needs, and the public contract consumers rely on.
+
+## 1. What core must provide for Modal (build checklist)
+
+**Tier 1 — required:**
+- `Base` class: constructor, `setSettings`, `on/off/once/trigger`, `addListener/removeListener/removeAllListeners`, `enable/disable`, `destroy()`, `_disabled` gate.
+- Event system: instance pub/sub + DOM listener registry (per design doc 01 §2).
+- Globals: `Garnish.bod`/`$bod`, `Garnish.win`/`$win`.
+- Constants: `ESC_KEY` (27), `FX_DURATION` (200), `ltr`/`rtl` flags.
+- `UiLayerManager` singleton: `addLayer(container)`, `removeLayer()`, `registerShortcut(keyCode, cb)`, `currentLayer`.
+- ARIA/focus helpers: `addModalAttributes`, `hideModalBackgroundLayers`, `resetModalBackgroundLayerVisibility`,
+  `trapFocusWithin`, `setFocusWithin`, `getFocusedElement`, `getKeyboardFocusableElements`.
+- Focusable-element matcher (design doc 01 §4.E).
+- `ResizeHandle` SVG export (trivial, from `icons/ResizeHandle.js`).
+
+**Tier 2 — needed only for draggable/resizable modals:**
+- `DragMove` (≈15-line `BaseDrag` subclass; updates `left`/`top` on drag).
+- `BaseDrag` (large, ~580 lines). **PoC decision: default `draggable:false`/`resizable:false`; stub or omit BaseDrag
+  for the slice.** Modal works fully without it at defaults.
+
+## 2. jQuery removals inside Modal (13 sites)
+
+| Use case | jQuery | Native replacement | Difficulty |
+| --- | --- | --- | --- |
+| Element creation | `$('<div/>')` | `document.createElement` | trivial |
+| Insertion | `.appendTo()`, `.insertBefore()`, `.append(svg)` | `appendChild`/`insertBefore`/`innerHTML` | trivial |
+| Class/attr/style | `.addClass/.removeClass/.attr/.css` | `classList`/`setAttribute`/`.style` | trivial |
+| Dimensions | `.outerWidth/.outerHeight` | `offsetWidth`/`offsetHeight` | trivial |
+| Window size | `Garnish.$win.width()/.height()` | `window.innerWidth/innerHeight` | trivial |
+| Display | `.show()/.hide()` | `.style.display = 'block'/'none'` | trivial |
+| Data storage | `.data('modal', this)` | WeakMap or `el._garnishModal` | trivial |
+| Type check | `$.isPlainObject(container)` | plain-object check / `nodeType` test | trivial |
+| **Animation** | **`.velocity('fadeIn'/'fadeOut'/'stop')`** | **CSS transitions or WAAPI (`el.animate`)** | **MEDIUM** |
+
+**Animation decision:** Replace Velocity with the Web Animations API (`element.animate([{opacity:0},{opacity:1}], {duration})`)
+or CSS `opacity` transitions + `transitionend`. Gate on `prefersReducedMotion`. `.velocity('stop')` becomes a no-op /
+`anim.cancel()`. Shade fade ≈ 50ms, container fade ≈ `FX_DURATION` (200ms), matching legacy.
+
+## 3. Public API contract (must stay identical for consumers)
+
+**Constructor:** `new Garnish.Modal(container?, settings?)` — also accepts `new Garnish.Modal(settings)` (param shift
+when first arg is a plain object).
+
+**Default settings:** `autoShow:true, draggable:false, dragHandleSelector:null, resizable:false, minGutter:10,
+onShow, onHide, onFadeIn, onFadeOut, closeOtherModals:false, hideOnEsc:true, hideOnShadeClick:true,
+triggerElement:null, shadeClass:'modal-shade'`.
+
+**Methods:** `show()`, `hide(ev?)`, `quickShow()`, `quickHide()`, `updateSizeAndPosition()`, `getWidth()`,
+`getHeight()`, `destroy()`, `addLiveRegion()`, and overridable hooks `onShow/onHide/onFadeIn/onFadeOut`.
+
+**Properties:** `visible`, `settings`, `desiredWidth`, `desiredHeight`, `$triggerElement`, `$container`, `$shade`,
+`dragger`, `resizeDragger`. **Statics:** `Garnish.Modal.instances`, `Garnish.Modal.visibleModal`.
+
+**Events triggered:** `show`, `hide`, `fadeIn`, `fadeOut`, `updateSizeAndPosition`, `escape`, `destroy`.
+
+## 4. Real consumer usage (validate against these)
+
+- Direct instantiation with settings (e.g. `new Garnish.Modal($container, {closeOtherModals:false})`).
+- Subclassing via `Garnish.Modal.extend({ init, onShow, destroy }, { defaults })` — e.g. `Craft.DeleteUserModal`,
+  `Craft.CpModal`, `BaseElementSelectorModal`, `PreviewFileModal`, `AssetImageEditor`. These rely on `this.base(...)`
+  super-calls → **the compat layer must make `.extend()` + `this.base()` work against the modern `class Modal`.**
+- Callback settings (`onShow`/`onHide`) and `.on('show'|'hide'|custom)` event binding.
+- `draggable`/`resizable`/`dragHandleSelector` (Tier 2 — defer to post-PoC).
+
+## 5. Modal's internal Garnish-class dependencies
+
+- `DragMove` — only when `draggable:true`. Trivial subclass.
+- `BaseDrag` — only when `resizable:true`. Large; defer for PoC.
+- `UiLayerManager` singleton — required (ESC shortcut + layer stacking).
+
+## 6. Flags for core team
+
+- `getFocusedElement()` returns a DOM element in modern core (legacy returned a jQuery collection); compat wraps with `$()`.
+- Focus trap + focusable matcher accessibility is the highest-risk area — budget tests.
+- The `.field:visible` heuristic in `setFocusWithin` (cms#15245) must be preserved.
diff --git a/packages/craftcms-garnish/docs/04-scaffold-notes.md b/packages/craftcms-garnish/docs/04-scaffold-notes.md
new file mode 100644
index 00000000000..c6c9e277f8c
--- /dev/null
+++ b/packages/craftcms-garnish/docs/04-scaffold-notes.md
@@ -0,0 +1,95 @@
+# Scaffold notes — `@craftcms/garnish`
+
+This package is the modern, tree-shakeable TypeScript rewrite of Craft CMS's
+Garnish UI library: TypeScript, ESM-only, no jQuery. This document covers the
+tooling/config scaffold (no library source yet — the implementation team adds
+that next).
+
+## Toolchain
+
+The toolchain mirrors the modern `@craftcms/cp` package so the monorepo stays
+consistent.
+
+| Concern        | Choice                                  | Why                                                                                  |
+| -------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
+| Bundler        | **tsdown** (Rolldown-based)             | Same bundler `@craftcms/cp` uses; native ESM, multi-entry code-splitting, built-in `.d.ts` emit. |
+| Output         | ESM only, `.d.ts` declarations, sourcemaps | Tree-shakeable library output; matches cp's `format: ['esm']` + `dts: true`.       |
+| Type config    | `@total-typescript/tsconfig/bundler/dom` | Same base preset the repo root tsconfig uses. Strict, ES2022, `moduleResolution: bundler`. |
+| Test runner    | **Vitest** + `happy-dom`                | Same as cp. `happy-dom` gives a DOM without a browser for fast unit tests.           |
+| Coverage       | `@vitest/coverage-v8`                   | Matches cp.                                                                           |
+| Format         | **Prettier**                            | Repo-wide convention (root `prettier`).                                              |
+| Workspace      | npm workspaces (`packages/*`)           | Auto-included by the root `package.json` `workspaces` glob — no manual registration needed. |
+
+No jQuery anywhere. The package is zero-dependency by design (only
+devDependencies). Peer deps, when they appear, go in `tsdown.config.ts` under
+`deps.neverBundle` and in `package.json` `peerDependencies`.
+
+## Entry points
+
+Two build entries, mapped in `package.json` `exports`:
+
+- `.` → `./dist/index.js` (+ `index.d.ts`) — modern core + components.
+- `./compat` → `./dist/compat.js` (+ `compat.d.ts`) — reserved opt-in legacy
+  compatibility layer. `src/compat.ts` is a placeholder (`export {}`) so the
+  build resolves; the implementation team populates it later.
+
+tsdown/Rolldown code-splits shared chunks between these two entries
+automatically.
+
+## Files
+
+```
+packages/craftcms-garnish/
+├── package.json          # @craftcms/garnish, type: module, exports map, scripts
+├── tsconfig.json         # extends @total-typescript bundler/dom preset, strict
+├── tsdown.config.ts      # ESM library build, dual entry (index + compat), dts
+├── vitest.config.ts      # globals + happy-dom
+├── .gitignore            # /dist /node_modules /coverage
+├── .nvmrc                # v22
+├── docs/                 # (pre-existing — untouched)
+└── src/
+    ├── index.ts          # exports VERSION const (placeholder)
+    ├── compat.ts         # export {} placeholder (TODO: legacy compat layer)
+    └── index.test.ts     # smoke test
+```
+
+## Commands
+
+Run from the repo root with the workspace flag, or from inside the package dir.
+
+```bash
+# Install (run once at repo root — picks up the new workspace)
+npm install
+
+# Build ESM + declarations into dist/
+npm run build -w @craftcms/garnish
+
+# Watch-mode build
+npm run dev -w @craftcms/garnish
+
+# Type-check only (no emit)
+npm run check:types -w @craftcms/garnish      # alias: typecheck
+
+# Run tests once / watch / with coverage
+npm run test -w @craftcms/garnish
+npm run test:dev -w @craftcms/garnish
+npm run test:coverage -w @craftcms/garnish
+
+# Formatting
+npm run format -w @craftcms/garnish           # write
+npm run check:format -w @craftcms/garnish     # check
+
+# Combined gate (typecheck + format check)
+npm run lint -w @craftcms/garnish
+```
+
+## Verification (scaffold)
+
+The skeleton was proven green:
+
+- `npm install` (repo root) — workspace picked up, deps installed.
+- `npm run check:types -w @craftcms/garnish` — passes.
+- `npm run build -w @craftcms/garnish` — emits `dist/index.js`,
+  `dist/index.d.ts`, `dist/compat.js`, `dist/compat.d.ts`, `dist/index.js.map`.
+- `npm run test -w @craftcms/garnish` — 2 tests pass.
+- `npm run lint -w @craftcms/garnish` — typecheck + Prettier both clean.
diff --git a/packages/craftcms-garnish/docs/05-core-impl-notes.md b/packages/craftcms-garnish/docs/05-core-impl-notes.md
new file mode 100644
index 00000000000..c7478830819
--- /dev/null
+++ b/packages/craftcms-garnish/docs/05-core-impl-notes.md
@@ -0,0 +1,117 @@
+# Garnish Core — Implementation Notes
+
+> Status: **Implemented.** This documents what was actually built against the
+> `01-core-design.md` contract: deviations, decisions, and the exact exported
+> surface the Modal and compat engineers will consume. All three gates are green:
+> `check:types`, `test` (70 tests), `build`.
+
+## Module layout (as built)
+
+Matches doc 01 §6, with two additions:
+
+- `src/managers/registry.ts` — a tiny manager-singleton registry. Breaks the
+  circular import between `utils/aria.ts` (needs the active UI layer manager) and
+  `managers/ui-layer-manager.ts`. `initGarnish()` calls `setUiLayerManager()`.
+- `src/icons/resize-handle.ts` — `ResizeHandle` SVG export (doc 03 §1 Tier 1).
+
+## Exact exported names / signatures (for Modal + compat)
+
+### Classes
+
+- `abstract class Base<S extends GarnishBaseSettings = GarnishBaseSettings>`
+  - `settings: S | null` (null until `setSettings`)
+  - `setSettings(settings?: Partial<S>, defaults?: Partial<S>): void` — **shallow** `Object.assign({}, base, defaults, settings)`.
+  - `on(events, handler)` / `on(events, data, handler)`
+  - `once(...)`, `off(events, handler?)`
+  - `trigger(type, data?)` — two-pass: instance emitter THEN `garnishClassBus.dispatch`.
+  - `addListener(elem, events, dataOrHandler, handler?)` — `dataOrHandler`/`handler` may be a **method-name string** resolved against `this`.
+  - `removeListener(elem, events)`, `removeAllListeners(elem)`
+  - `enable()`, `disable()`, `get disabled()`, `destroy()`
+  - protected: `_disabled`, `_namespace` (`.Garnish<uuid>`), `_emitter`, `_domListeners`.
+- `class EscManager extends Base` — `register(obj, fn|methodName)`, `unregister(obj)`, `escapeLatest(ev)`.
+- `class UiLayerManager extends Base` — `layers`, getters `layer`/`currentLayer`/`modalLayers`/`highestModalLayer`,
+  `addLayer(container?|options, options?)`, `removeLayer(layer?)`, `getLayerIndex`, `removeLayerAtIndex`,
+  `registerShortcut(keyCode|def, cb, layer?)`, `unregisterShortcut`, `triggerShortcut(ev, layerIndex?)`.
+  **Layer shape:** `{$container: Element|null, shortcuts, isModal?, options:{bubble}}` — `$container` is a **native
+  Element** (NOT a jQuery collection). The compat layer must wrap it with `$()` where consumers expect `.get(0)` etc.
+
+### Event system (`events.ts`)
+
+- `parseEvents(events, splitOn=' '|',')` → `{type, namespace}[]`. Splits on first `.`. `''` type allowed for the
+  namespace-only `off` form.
+- `formatDomEvents(events, namespace)` → space-joined string with namespace appended (comma-split input).
+- `class EventEmitter<Target>` — `on/once/off/trigger/clear`. Trigger precedence: `{data: regData} <- triggerData <- {type, target}`.
+- `class ClassEventBus` — `on/once/off(target, events, [data], handler)`, `dispatch(instance, type, data)`, `clear()`.
+  `console.warn` on `undefined` target (wart #7). `dispatch` filters by `instance instanceof reg.target`.
+- The single shared instance is `garnishClassBus` (in `globals.ts`); `Garnish.on/off/once` proxy to it.
+
+### DOM listeners (`dom-listeners.ts`)
+
+- `class DomListenerRegistry` ctor takes `host: { readonly disabled: boolean }` (structural — `Base` satisfies it).
+  Methods: `add(elements, events, handler, options?)`, `remove(elements, events)`, `removeAllOn(elements)`, `removeAll()`.
+- `DomListenerOptions`: `{delegate?, data?, capture?, passive?}`. Delegation uses `event.target.closest(selector)` +
+  `container.contains`. The delegated match is exposed on the event as `garnishTarget` (we cannot overwrite the native
+  read-only `currentTarget`/`target`).
+- `ElementInput` coercion lives in `utils/dom.ts` `coerceElements()` (string → `querySelectorAll`, node/window → `[node]`,
+  array/NodeList → flattened, null → `[]`).
+
+### Custom events (`custom-events/`)
+
+- `installActivate(el)`, `installTextchange(el, {delay?})`, `installResize(el)` — each returns a **ref-counted disposer**
+  (idempotent per element/type). `addListener(el, 'activate'|'textchange'|'resize', fn)` auto-routes through these.
+- Synthetic events are dispatched as native `CustomEvent`s on the element; `activate` carries `originalEvent`.
+- `installResize` shares one lazily-created `ResizeObserver`; `window` uses native `resize` (install is a no-op).
+
+### Globals (`globals.ts`)
+
+- Named exports `win` (= `window`), `doc` (= `document`), `bod` (= `document.body`), `garnishClassBus`.
+- `globals` object holds mutable `scrollContainer`, `activateEventsMuted`, `resizeEventsMuted`, `rtl`, `get ltr`.
+  The `Garnish` namespace exposes these via get/set accessors so flag mutations stay live.
+
+### `Garnish` namespace object + `initGarnish()`
+
+`index.ts` exports the legacy-shaped `Garnish` object (constants spread, `win/doc/bod`, accessor-backed flags, classes,
+`on/off/once`, `_normalizeEvents` alias, all `utils/*`, `muteResizeEvents`, `ResizeHandle`, plus `escManager`/
+`uiLayerManager` slots). `initGarnish()` instantiates the two managers (idempotent) and registers the layer manager.
+**The core never assigns `window.Garnish`** — that's the compat layer's job.
+
+## Deviations & decisions (read these)
+
+1. **`once` removal-by-handler is wrapper-closure (legacy wart #6).** `off(events, originalHandler)` does **NOT** remove
+   a `once` registration — only the internal `onceler` wrapper matches. Remove a pending `once` by type/namespace.
+   (Contract §2.3 mandated the wrapper-closure approach for identical `off` behavior.)
+2. **Event objects are the native DOM event, augmented.** For DOM listeners we pass the real `Event` through and
+   `Object.defineProperty` only the **missing** Garnish fields (`data`, `garnishTarget`). We never write `type`/`target`
+   (read-only native getters; writing throws in happy-dom and real browsers). Pub/sub (`EventEmitter`) events are plain
+   objects as specified.
+3. **`getOffset`/`hitTest` drop the legacy instance-cache fields** (`_offset`, `_$elem`, `_x1`…) and use
+   `getBoundingClientRect()` + `scrollX/Y`. Behaviorally equivalent.
+4. **`shake` uses WAAPI** (`element.animate`) over a single keyframe ramp instead of the legacy 11× `setTimeout`+Velocity
+   loop; gated by `prefersReducedMotion` (no-op). `scrollContainerToElement` uses instant `scrollTop`/`window.scrollTo`
+   (Velocity removed) — no smooth-scroll tween.
+5. **`isPrimaryClick`** reads `ev.button === 0` for native events but honors legacy `ev.which === 1` when present.
+6. **`getFocusedElement()` returns `Element | null`** (not a jQuery collection) — compat wraps with `$()` (doc 03 §6).
+7. **Focusable matcher** (`utils/focusable.ts`) models jQuery-UI `:focusable`: `<a>/<area>` with href, non-disabled form
+   controls, anything with a numeric tabindex, plus a visibility gate (`offsetWidth/Height || getClientRects().length`,
+   and no `visibility:hidden/collapse` on self or ancestors). `getFocusableElements` excludes the container itself
+   (matches `.find()`). **Note for tests in happy-dom:** there is no layout, so `offsetWidth/Height` are 0 — tests stub
+   `getClientRects` to assert focusability. Real browsers don't need this.
+8. **`findInputs` keeps the bogus `text` tag** in its selector (wart #3) — matches nothing, preserved verbatim.
+9. **`getInputPostVal`** returns `''` (not `null`) for a null-valued `<select>` (wart #4); multi-selects read
+   `select.selectedOptions`.
+10. **`_namespace`** uses `crypto.randomUUID()` with a `Math.random` fallback (wart #5). It is bookkeeping only — the
+    registry's tuple array is the real removal mechanism, so namespaced `.off` works without it.
+
+## What's intentionally NOT here (compat layer's job)
+
+- No `window.Garnish` assignment, no `$.fn.activate/textchange/resize` sugar, no `$.event.special`, no `isJquery`.
+- No `Base.extend()` / `this.base()` / `init()` trampoline — subclasses use native `constructor` + `super()`.
+- No jQuery anywhere; no Velocity.
+
+## For the Modal engineer specifically (doc 03 §1 checklist — all satisfied)
+
+`Base`, instance pub/sub + DOM registry, `win`/`doc`/`bod`, constants (`ESC_KEY`/`FX_DURATION`/`rtl`/`ltr`),
+`UiLayerManager` (`addLayer`/`removeLayer`/`registerShortcut`/`currentLayer`), ARIA/focus helpers
+(`addModalAttributes`, `hideModalBackgroundLayers`, `resetModalBackgroundLayerVisibility`, `trapFocusWithin`,
+`setFocusWithin`, `getFocusedElement`, `getKeyboardFocusableElements`), the focusable matcher, and `ResizeHandle` are
+all exported. `BaseDrag`/`DragMove` are out of scope (PoC defaults `draggable:false`/`resizable:false`).
diff --git a/packages/craftcms-garnish/docs/06-api-reference.md b/packages/craftcms-garnish/docs/06-api-reference.md
new file mode 100644
index 00000000000..9d9c39384ab
--- /dev/null
+++ b/packages/craftcms-garnish/docs/06-api-reference.md
@@ -0,0 +1,694 @@
+# 06 — Public API Reference
+
+A concise "what can I call" cheat sheet for the current public surface of
+`@craftcms/garnish`. Signatures are simplified for readability; the source TSDoc
+(and your editor's IntelliSense) is authoritative. Members marked **PoC** are not
+yet implemented and throw, or behave as noted.
+
+Two entry points:
+
+| Import | Surface |
+| --- | --- |
+| `@craftcms/garnish` | Modern, jQuery-free named exports + the `Garnish` namespace object. |
+| `@craftcms/garnish/compat` | Side-effecting: installs `window.Garnish`, restores `.extend()`/`this.base()`/jQuery args. |
+
+---
+
+## `Base`
+
+`abstract class Base<S extends GarnishBaseSettings = GarnishBaseSettings>` — the
+base class every component extends. Native `class` + `super`; no `init`/`this.base`
+(those are compat-only).
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `settings` | `S \| null` | Resolved settings; `null` until `setSettings` runs. |
+| `disabled` | `get => boolean` | Whether the instance is disabled. |
+| `setSettings` | `(settings?, defaults?) => void` | Shallow-merge defaults ← overrides into `settings`. |
+| `on` | `(events, [data,] handler) => void` | Subscribe to instance event(s); supports `.namespace`s. |
+| `once` | `(events, [data,] handler) => void` | Like `on`, auto-removed after first fire. |
+| `off` | `(events, handler?) => void` | Unsubscribe (namespaced, by type, and/or by handler ref). |
+| `trigger` | `(type, data?) => void` | Emit an event to instance + class-level handlers. |
+| `addListener` | `(elem, events, [data,] handler) => void` | Bind tracked DOM listener(s); `handler` may be a method-name string. |
+| `removeListener` | `(elem, events) => void` | Remove specific DOM listener(s). |
+| `removeAllListeners` | `(elem) => void` | Remove all DOM listeners on an element. |
+| `enable` / `disable` | `() => void` | Toggle the DOM-listener gate. |
+| `destroy` | `() => void` | Emit `destroy`, remove all listeners, clear handlers. |
+
+Event objects passed to handlers are `GarnishEvent` (for DOM events, the native
+`Event` augmented with `data`/`target`).
+
+---
+
+## `Modal`
+
+`class Modal extends Base<ModalSettings>` — accessible, animated modal dialog.
+
+**Constructor:** `new Modal(container?, settings?)` — also `new Modal(settings)`
+(param shift when the first arg is a plain object).
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `Modal.instances` | `Modal[]` | All live modals. |
+| `Modal.visibleModal` | `Modal \| null` | The currently visible modal. |
+| `Modal.defaults` | `ModalSettings` | Default settings (below). |
+| `Modal.relativeElemPadding` | `number` (`8`) | Legacy parity constant. |
+
+### Settings (`ModalSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `autoShow` | `true` | Show immediately on construction (when a container is given). |
+| `draggable` | `false` | Make the modal draggable (via `DragMove` on its container). |
+| `dragHandleSelector` | `null` | Restrict dragging to this selector within the container (e.g. a header). |
+| `resizable` | `false` | Add a corner resize handle (via `BaseDrag`). |
+| `minGutter` | `10` | Min px between modal and viewport edge. |
+| `onShow` / `onHide` | no-op | Show/hide callbacks. |
+| `onFadeIn` / `onFadeOut` | no-op | Post-fade callbacks. |
+| `closeOtherModals` | `false` | Hide any other visible modal on show. |
+| `hideOnEsc` | `true` | Hide on Escape. |
+| `hideOnShadeClick` | `true` | Hide on backdrop click. |
+| `triggerElement` | `null` | Focus-restore target (defaults to focus at construction). |
+| `shadeClass` | `'modal-shade'` | CSS class for the shade/backdrop. |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `show` / `hide` | `() => void` / `(ev?) => void` | Show / hide with fade. |
+| `quickShow` / `quickHide` | `() => void` | Show / hide without fade. |
+| `onShow` / `onHide` / `onFadeIn` / `onFadeOut` | `() => void` | Overridable hooks (emit the event + run the callback). |
+| `updateSizeAndPosition` | `() => void` | Re-center and re-fit; emits `updateSizeAndPosition`. |
+| `getWidth` / `getHeight` | `() => number` | Measure the container (throws if unset). |
+| `setContainer` | `(container) => void` | Assign/replace the container. |
+| `addLiveRegion` | `() => void` | Append the live region to the container. |
+| `destroy` | `() => void` | Remove DOM, drop from `instances`, base teardown. |
+| `$container` / `$shade` / `$liveRegion` / `$triggerElement` | `HTMLElement \| Element \| null` | Element refs. |
+| `visible` | `boolean` | Whether currently shown. |
+| `desiredWidth` / `desiredHeight` | `number \| null` | Optional fixed dimensions. |
+| `dragger` | `DragMove \| null` | The `DragMove` driving `draggable` (when enabled), else `null`. |
+| `resizeDragger` | `BaseDrag \| null` | The `BaseDrag` driving `resizable` (on the resize handle), else `null`. |
+
+**Events:** `show`, `hide`, `fadeIn`, `fadeOut`, `updateSizeAndPosition`, `escape`,
+`destroy`.
+
+---
+
+## `HUD`
+
+`class HUD extends Base<HUDSettings>` — an anchored, accessible popover/bubble with
+smart 4-way positioning and scroll-follow. Attaches to a trigger element, picks the
+best of four orientations from the available clearance, draws a tip pointing back at
+the trigger, traps Tab focus between trigger and body, and registers a UI layer +
+Escape shortcut (via the shared `UiLayerManager`, like `Modal`). Show/hide are
+display toggles — legacy HUD does not animate.
+
+**Constructor:** `new HUD(trigger, bodyContents?, settings?)` — also
+`new HUD(trigger, settings)` (param shift when the 2nd arg is a plain object). This
+is exactly the `FieldLayoutDesigner` call shape: `new HUD($addBtn, {...})`.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `HUD.instances` | `HUD[]` | All live HUDs. |
+| `HUD.activeHUDs` | `Record<string, HUD>` | Open HUDs by namespace (powers `closeOtherHUDs`). |
+| `HUD.tipClasses` | `Record<HUDOrientation, string>` | Orientation → tip-class suffix. |
+| `HUD.defaults` | `HUDSettings` | Default settings (below). |
+
+### Settings (`HUDSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `hudClass` | `'hud'` | Class(es) for the HUD container (multi-class string OK). |
+| `tipClass` | `'tip'` | Base class for the tip; orientation suffix appended. |
+| `shadeClass` | `'hud-shade'` | Class for the shade/backdrop. |
+| `bodyClass` / `mainContainerClass` / `mainClass` | `'body'` / `'main-container'` / `'main'` | Body / scroll-wrapper / content classes. |
+| `headerClass` / `footerClass` | `'hud-header'` / `'hud-footer'` | Header/footer hoisted out of the body content. |
+| `orientations` | `['bottom','top','right','left']` | Sides to try, in order of preference. |
+| `triggerSpacing` / `windowSpacing` | `10` / `10` | Gap to the trigger / viewport edge (px). |
+| `tipWidth` | `30` | Tip/arrow width (px). |
+| `minBodyWidth` / `minBodyHeight` | `200` / `0` | Min body dimensions (px). |
+| `withShade` | `true` | Render a shade behind the HUD. |
+| `onShow` / `onHide` / `onSubmit` | no-op | Registered as `show`/`hide`/`submit` handlers. |
+| `closeBtn` | `null` | Element whose `activate` hides the HUD. |
+| `listenToMainResize` | `true` | Reposition on the main element's `resize`. |
+| `showOnInit` | `true` | Show immediately on construction. |
+| `closeOtherHUDs` | `true` | Hide every other open HUD on show. |
+| `hideOnEsc` | `true` | Hide on Escape. |
+| `hideOnShadeClick` | `true` | Hide on shade click. |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `show` / `hide` | `(ev?) => void` / `() => void` | Show / hide (display toggle); no-op if already in that state. |
+| `toggle` | `() => void` | Flip visibility. |
+| `showContainer` / `hideContainer` | `() => void` | The raw display toggles (overridable). |
+| `updateBody` | `(contents) => void` | Replace body content; re-extract header/footer. |
+| `updateRecords` | `() => boolean` | Re-measure; returns whether anything changed. |
+| `updateSizeAndPosition` | `(force?) => void` | Schedule a RAF reposition. |
+| `updateSizeAndPositionInternal` | `() => void` | The 4-way positioning pass. |
+| `submit` | `() => void` | Fire the `submit` flow. |
+| `onShow` / `onHide` / `onSubmit` | `() => void` | Overridable hooks (emit the event). |
+| `destroy` | `() => void` | Remove DOM, drop from `instances`/`activeHUDs`, base teardown. |
+| `$trigger` / `$hud` / `$tip` / `$body` / `$main` / `$mainContainer` / `$header` / `$footer` / `$shade` | `HTMLElement \| null` | Element refs (`$main` is where consumers append content). |
+| `showing` | `boolean` | Whether currently shown. |
+| `orientation` | `HUDOrientation \| null` | The chosen side after positioning. |
+
+**Events:** `show`, `hide`, `submit`, `updateSizeAndPosition`, `destroy`.
+
+```ts
+import {HUD} from '@craftcms/garnish';
+
+const hud = new HUD(addBtn, {
+  hudClass: 'hud fld-library-hud',
+  orientations: ['right', 'bottom', 'left'],
+  showOnInit: false,
+});
+hud.on('show', () => populate(hud.$main!)); // $main is a raw HTMLElement
+hud.on('hide', () => addBtn.focus());
+addBtn.addEventListener('click', () => hud.show());
+```
+
+---
+
+## `DisclosureMenu`
+
+`class DisclosureMenu extends Base<DisclosureMenuSettings>` — the disclosure
+dropdown/menu. Pairs a trigger button (`aria-controls` / `aria-expanded`) with a
+pre-existing menu panel: anchors it below the trigger (flipping above when there's
+no room) and aligns it left/center/right, manages keyboard nav + type-ahead
+search and focus, registers a UI layer + Escape shortcut (via the shared
+`UiLayerManager`, like `Modal`/`HUD`), dismisses on outside click, and exposes
+item/group builders. Show is instant; hide fades out (WAAPI, reduced-motion aware).
+
+**Constructor:** `new DisclosureMenu(trigger, settings?)` — `trigger` is an
+`ElementInput` (coerced via `getElement`) carrying `aria-controls` (or with the
+panel as its next sibling). No param shift (legacy `init(trigger, settings)` has no
+body arg). This is the CP call shape: `new DisclosureMenu($trigger, {...})`.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `DisclosureMenu.instances` | `DisclosureMenu[]` | All live menus. |
+| `DisclosureMenu.defaults` | `DisclosureMenuSettings` | Default settings (below). |
+| `DisclosureMenu.getInstance(el)` | `(Element \| null) => DisclosureMenu \| undefined` | The menu registered for a trigger/container (native `$el.data('disclosureMenu')`). |
+
+### Settings (`DisclosureMenuSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `position` | `null` | `'below'` forces the panel below; else clearance picks above/below. |
+| `windowSpacing` | `5` | Min gap (px) to the viewport edge. |
+| `withSearchInput` | `false` | Render a live item-filtering search input (also via `data-with-search-input`). |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `show` / `hide` | `() => void` | Show / hide; no-op if already in that state (show also no-ops on a `.disabled` trigger). |
+| `handleTriggerClick` | `() => void` | Toggle (re-captures the alignment element). |
+| `isExpanded` | `() => boolean` | Whether `aria-expanded === 'true'`. |
+| `setContainerPosition` | `() => void` | Above/below + left/center/right positioning (also the scroll/resize handler). |
+| `focusElement` | `(el \| 'prev' \| 'next') => void` | Focus an element, or move within the menu's focusables. |
+| `addItem` / `addItems` | `(item(s), ul?, prepend?) => HTMLElement \| void` | Build + insert item(s); returns the item's element. |
+| `createItem` | `(item) => HTMLLIElement` | Build an item `<li>` from a config (or pass an element through). |
+| `addGroup` / `addList` / `addHr` | — | Add a group (`<h3>` + `<ul>`) / a bare `<ul>` / an `<hr>`. |
+| `toggleItem` / `showItem` / `hideItem` / `removeItem` | `(el, show?) => void` | Item visibility. |
+| `updateVisibility` / `hasVisibleItems` / `getFirstDestructiveGroup` / `isPadded` | — | Visibility/query helpers. |
+| `clearSearchStr` | `() => void` | Reset the type-ahead buffer + timeout. |
+| `destroy` | `() => void` | Drop registrations, remove from `instances`, base teardown. |
+| `$trigger` / `$container` / `$alignmentElement` / `$searchInput` / `$nextFocusableElement` | `HTMLElement \| null` | Element refs. |
+| `searchStr` | `string` | The current type-ahead buffer. |
+
+**Events:** `beforeShow`, `show`, `hide`, `destroy`. Item selection is per-item
+(`onActivate` / `callback` on `activate`, then the menu hides).
+
+```ts
+import {DisclosureMenu} from '@craftcms/garnish';
+
+const menu = new DisclosureMenu(trigger); // trigger has aria-controls="#panel"
+menu.addItem({label: 'Rename', onActivate: (el) => rename(el)});
+menu.addItem({label: 'Delete', destructive: true, onActivate: () => remove()});
+menu.on('show', () => console.log('opened'));
+```
+
+---
+
+## `BaseDrag`
+
+`class BaseDrag<S extends BaseDragSettings = BaseDragSettings> extends Base<S>` —
+the jQuery-free drag foundation. Uses the Pointer Events API (mouse + touch + pen)
+and a native RAF auto-scroll loop. Subclasses (`DragMove`, and later `Drag` /
+`DragSort`) override the drag hooks to manipulate the dragged element(s).
+
+**Constructor:** `new BaseDrag(items?, settings?)` — `items` is a selector,
+element, or list of elements made draggable immediately; `settings` overrides the
+defaults. Also `new BaseDrag(settings)` (param shift when the first arg is a plain
+object).
+
+> Drag handles require `touch-action: none` (CSS or inline) so the browser doesn't
+> consume the gesture on touch devices. `Modal` sets this on its generated resize
+> handle; for your own handles you must set it.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `BaseDrag.minMouseDist` | `number` (`1`) | Fallback when `settings.minMouseDist === null`. |
+| `BaseDrag.windowScrollTargetSize` | `number` (`25`) | px edge band that triggers auto-scroll. |
+| `BaseDrag.defaults` | `BaseDragSettings` | Default settings (below). |
+| `getItemDragger(item)` | `(Element) => BaseDrag \| undefined` | Named export: read the dragger that owns an item. |
+
+### Settings (`BaseDragSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `minMouseDist` | `null` | Min px the pointer must travel before a drag starts (`null` → `BaseDrag.minMouseDist`, i.e. `1`). |
+| `handle` | `null` | Drag handle: element(s), a selector resolved within each item, a `(item) => handle` function, or `null` (the item itself). |
+| `axis` | `null` | Restrict movement to `X_AXIS` (`'x'`), `Y_AXIS` (`'y'`), or `null` (both). |
+| `ignoreHandleSelector` | `'input, textarea, button, select, .btn'` | Pointer-down on a descendant matching this is ignored (unless it IS the handle). |
+| `onBeforeDragStart` / `onDragStart` / `onDrag` / `onDragStop` | no-op | Lifecycle callbacks (fire alongside the matching events). |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `$items` | `Element[]` | The draggable items (native elements; legacy held a jQuery collection). |
+| `$targetItem` | `HTMLElement \| null` | The element currently being dragged, or `null`. |
+| `dragging` | `boolean` | Whether a drag is in progress. |
+| `mouseX` / `mouseY` | `number \| null` | Axis-constrained pointer page coords (what subclasses read). |
+| `realMouseX` / `realMouseY` | `number \| null` | Unconstrained pointer page coords (before axis lock). |
+| `mousedownX` / `mousedownY` | `number \| null` | Pointer-down page coords. |
+| `mouseDistX` / `mouseDistY` | `number \| null` | `mouseX/Y - mousedownX/Y` (read by `Modal._handleResize`). |
+| `mouseOffsetX` / `mouseOffsetY` | `number \| null` | Grab offset: pointer-down page coord minus the target's offset. |
+| `scrollProperty` / `scrollAxis` / `scrollDist` / `scrollFrame` | `… \| null` | Auto-scroll loop state. |
+| `addItems` / `removeItems` | `(items) => void` | Add/remove draggable items (binds/unbinds the handle listener). |
+| `removeAllItems` | `() => void` | Stop tracking every item. |
+| `getPrevItem` / `getNextItem` | `(item) => Element \| null` | Neighbor in `$items`. |
+| `allowDragging` | `() => boolean` | Default `true`; override to gate dragging. |
+| `startDragging` / `drag` / `stopDragging` | overridable | Drag lifecycle (subclasses call via `super`). |
+| `setScrollContainer` / `isScrollingWindow` | `() => void` / `() => boolean` | Resolve / query the scroll container. |
+| `onBeforeDragStart` | `() => void` | **Sync** hook: emits `beforeDragStart` + runs the callback. |
+| `onDragStart` / `onDrag` / `onDragStop` | `() => void` | **RAF-deferred** hooks: emit the event + run the callback. |
+| `destroy` | `() => void` | `removeAllItems()` then base teardown. |
+
+**Events:** `beforeDragStart`, `dragStart`, `drag`, `dragStop`, plus inherited
+`destroy`.
+
+---
+
+## `DragMove`
+
+`class DragMove extends BaseDrag` — a trivial subclass whose only job is to set the
+dragged element's `left`/`top` so it follows the cursor (minus the grab offset).
+Used by `Modal`'s `draggable` option. Same constructor and surface as `BaseDrag`.
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `onDrag` | `() => void` | Sets `$targetItem.style.left/top` synchronously, then calls `super.onDrag()` (so `DragMove` also emits the `drag` event — a deliberate improvement over legacy). |
+
+---
+
+## `Drag`
+
+`class Drag<S extends DragSettings = DragSettings> extends BaseDrag<S>` — "picks
+up" the selected element(s): snapshots the target geometry + draggee set, builds
+floating *helper* clones that follow the cursor with lag, and animates them back
+home (or fades them out) when the drag ends. It does **not** decide what to do with
+a dragged element — that's `DragDrop` / `DragSort`.
+
+**Constructor:** `new Drag(items?, settings?)` — same `items` shapes as `BaseDrag`;
+also `new Drag(settings)` (param shift when the first arg is a plain object).
+
+> Like `BaseDrag`, the dragged items / handles need `touch-action: none`.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `Drag.defaults` | `DragSettings` | Default settings (below). |
+
+### Settings (`DragSettings`, extends `BaseDragSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `filter` | `null` | Which item(s) to drag: a `() => elements` fn, a selector that filters `$items`, or `null` → just `$targetItem`. |
+| `singleHelper` | `false` | Build one helper for the whole draggee set instead of one per draggee. |
+| `collapseDraggees` | `false` | Collapse the other draggees into the target (hide the rest). |
+| `removeDraggee` | `false` | Hide every draggee (`display:none`) while dragging. |
+| `hideDraggee` | `true` | Hide draggees via `visibility:hidden` while dragging. |
+| `copyDraggeeInputValuesToHelper` | `false` | Copy `<input>`/`<select>`/`<textarea>` values from source into the clone. |
+| `helperOpacity` | `1` | Helper opacity (`1` → no override). |
+| `moveHelperToCursor` | `false` | Put the helper's top-left at the cursor instead of the grab offset. |
+| `helper` | `null` | Helper wrapper: `(helper, index) => wrapped`, an element/markup to wrap into, or `null` (bare clone). |
+| `helperBaseZindex` | `1000` | Base z-index for helpers. |
+| `helperLagBase` | `3` | Base follow-lag divisor. |
+| `helperLagIncrementDividend` | `1.5` | Per-helper lag increment dividend. |
+| `helperSpacingX` / `helperSpacingY` | `5` / `5` | Per-index helper offset (px). |
+| `onReturnHelpersToDraggees` | no-op | Callback fired (RAF-deferred) when helpers finish returning. |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `$draggee` | `HTMLElement[]` | The dragged element(s); target item is always index 0. |
+| `otherItems` / `totalOtherItems` | `Element[]` / `number \| null` | Items not in `$draggee`, and their count. |
+| `helpers` | `HTMLElement[]` | The floating helper clones (native, not jQuery). |
+| `helperTargets` / `helperPositions` | `Array<{left, top}>` | Per-helper target / current positions. |
+| `targetItemWidth` / `targetItemHeight` / `targetItemPositionInDraggee` | `number \| null` | Snapshotted target geometry / index. |
+| `draggeeVirtualMidpointX` / `draggeeVirtualMidpointY` | `number \| null` | Virtual midpoint of the draggee (read by `DragSort`). |
+| `findDraggee` | `() => HTMLElement[]` | Resolve which items are dragged (`filter`/selector/`$targetItem`). |
+| `setDraggee` / `appendDraggee` | `(draggee) => void` | Set / append the draggee set (creates helpers, applies hide/collapse). |
+| `getHelperTargetX` / `getHelperTargetY` | `(real?) => number` | Helper target coord (`real` skips the `moveHelperToCursor` snap). |
+| `returnHelpersToDraggees` | `() => void` | Animate every helper back to its source's offset, then show + remove (WAAPI, reduced-motion aware). |
+| `fadeOutHelpers` | `() => void` | Fade each helper out and remove it (no return tween). |
+| `allowDragging` | `() => boolean` | `false` while helpers are returning, else `true`. |
+| `startDragging` / `drag` / `stopDragging` | overridable | Drag lifecycle (snapshot + helper build + lag loop). |
+| `onReturnHelpersToDraggees` | `() => void` | **RAF-deferred** hook: emits `returnHelpersToDraggees` + runs the callback. |
+| `destroy` | `() => void` | Cancel the lag loop + return anims, remove helpers, base teardown. |
+
+**Events:** `returnHelpersToDraggees`, plus all inherited `BaseDrag` events
+(`beforeDragStart`, `dragStart`, `drag`, `dragStop`, `destroy`).
+
+> `Drag` does **not** auto-return helpers on drop — the consumer calls
+> `returnHelpersToDraggees()` or `fadeOutHelpers()` from its own `dragStop`/
+> `onDragStop` handler (legacy contract).
+
+---
+
+## `DragDrop`
+
+`class DragDrop<S extends DragDropSettings = DragDropSettings> extends Drag<S>` —
+adds drop targets + hit detection on top of `Drag`. Hit-testing reuses the
+`hitTest` util (page coords), so this layer is thin.
+
+**Constructor:** `new DragDrop(settings?)` — **settings only** (no positional
+`items`); add draggable items afterwards with `addItems(...)`.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `DragDrop.defaults` | `DragDropSettings` | Default settings (below). |
+
+### Settings (`DragDropSettings`, extends `DragSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `dropTargets` | `null` | Drop-target element(s), a selector, or a `() => elements` resolver. |
+| `onDropTargetChange` | no-op | Called with the new active target (or `null`) whenever it changes. |
+| `activeDropTargetClass` | `'active'` | Class toggled on the active drop target. |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `$dropTargets` | `HTMLElement[] \| null` | Resolved drop targets (`null` when none). |
+| `$activeDropTarget` | `HTMLElement \| null` | The element the cursor is over — a **raw `HTMLElement`, not jQuery** (no `[0]`). |
+| `updateDropTargets` | `() => void` | Re-resolve `settings.dropTargets` into `$dropTargets`. |
+| `onDragStart` / `onDrag` / `onDragStop` | overridable | Resolve targets / first-match hit-detect + class toggle / strip active class. |
+
+**Hit detection:** first-match wins (iterate `$dropTargets` in order, `break` on the
+first hit). `onDropTargetChange` fires only on a *change* (incl. target↔null).
+**There is no `drop` event** — read `$activeDropTarget` in your own `dragStop`/
+`onDragStop` handler to perform the drop. `DragDrop` inherits `Drag`'s helper/return
+machinery and all `BaseDrag` events.
+
+---
+
+## `DragSort`
+
+`class DragSort<S extends DragSortSettings = DragSortSettings> extends Drag<S>` — the
+sortable-list dragger: drag items to reorder them within their container, with **live
+insertion feedback** (the draggee is re-inserted into the DOM at the closest landing
+spot as the cursor moves, and an optional `insertion` placeholder marks it). On drop
+the new order is committed and `sortChange` fires if anything moved.
+
+**Constructor:** `new DragSort(items?, settings?)` — same `items` shapes + plain-object
+param-shift as `Drag`.
+
+> Like `Drag`, the sortable items / handles need `touch-action: none`.
+
+### Statics
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `DragSort.defaults` | `DragSortSettings` | Default settings (below). |
+
+### Settings (`DragSortSettings`, extends `DragSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `container` | `null` | The list container (element / selector / list). Walked up at drag start to the nearest ancestor that has a height; the drag only sorts while the cursor is over it. |
+| `insertion` | `null` | Placeholder shown at the landing spot: a `(draggee) => element \| markup` fn, an element, an HTML string, or `null`. |
+| `moveTargetItemToFront` | `false` | Move the target to the front of the draggee block at drag start (and leave it there on drop). |
+| `magnetStrength` | `1` | Divides the helper's pull toward the cursor. `1` → exact tracking; `>1` → rubber-band toward the draggee's home. |
+| `onInsertionPointChange` | no-op | Fired (RAF-deferred) whenever the insertion point moves. |
+| `onSortChange` | no-op | Fired (RAF-deferred) on drop when the order actually changed. |
+| `canInsertBefore` | `() => true` | Gate: may the draggee be inserted *before* this item? |
+| `canInsertAfter` | `() => true` | Gate: may the draggee be inserted *after* this item? |
+
+### Methods & properties
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `$heightedContainer` | `HTMLElement \| null` | Resolved heighted container (the sort bounds). |
+| `$insertion` | `HTMLElement \| null` | The placeholder element (raw, not jQuery). |
+| `insertionVisible` | `boolean` | Whether the placeholder is in the DOM. |
+| `closestItem` | `HTMLElement \| null` | The item the draggee is currently closest to. |
+| `oldDraggeeIndexes` / `newDraggeeIndexes` | `number[] \| null` | Draggee indexes (into `$items`) at drag start / drop. |
+| `createInsertion` | `() => HTMLElement \| null` | Build the placeholder from `settings.insertion`. |
+| `canInsertBefore` / `canInsertAfter` | `(item) => boolean` | Insertion gates (delegate to settings). |
+| `getHelperTargetX` / `getHelperTargetY` | `(real?) => number` | Helper target coord; applies `magnetStrength` rubber-banding. |
+| `onInsertionPointChange` / `onSortChange` | `() => void` | **RAF-deferred** hooks: emit the event + run the callback. |
+| `onDragStart` / `onDrag` / `onDragStop` | overridable | Record order + create insertion / closest-item detect + reflow / commit + return + `sortChange`. |
+
+**Events:** `insertionPointChange`, `sortChange`, plus all inherited `Drag`/`BaseDrag`
+events (`returnHelpersToDraggees`, `beforeDragStart`, `dragStart`, `drag`, `dragStop`,
+`destroy`).
+
+**Spatial hit-test (`_getClosestItem`):** distances are measured from the draggee's
+virtual midpoint (axis-aware: `x`/`y`/Euclidean), walking outward from the draggee with
+a monotonic-distance early-skip and `canInsertBefore`/`canInsertAfter` gating. Midpoints
+are cached once per drag (`_precalculateMidpoints`) and only the moved item + neighbors
+are recomputed per insertion; lists `> 200` items use a viewport filter. Unlike
+`DragDrop`, `DragSort` **auto-returns** the helpers on drop.
+
+---
+
+## `UiLayerManager`
+
+`class UiLayerManager extends Base` — manages the stack of UI layers (document,
+modals, HUDs, menus) and their scoped keyboard shortcuts. The active instance is a
+singleton at `Garnish.uiLayerManager` (created by `initGarnish()`).
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `layers` | `Layer[]` | The layer stack (index `0` = base document). |
+| `layer` | `get => number` | Topmost layer index. |
+| `currentLayer` | `get => Layer` | The active layer. |
+| `modalLayers` / `highestModalLayer` | getters | Modal layers / the highest one. |
+| `addLayer` | `(container?, options?) => this` | Push a layer; `{bubble}` opt-in for shortcut fall-through. |
+| `removeLayer` | `(layer?) => this \| undefined` | Pop the top, or remove a specific layer. |
+| `registerShortcut` | `(keyCode \| def, cb, layer?) => this` | Register a keyboard shortcut. |
+| `unregisterShortcut` | `(keyCode \| def, layer?) => this` | Remove a shortcut. |
+| `triggerShortcut` | `(ev, layerIndex?) => void` | Dispatch a matching shortcut (used internally). |
+
+## `EscManager` — _deprecated_
+
+`class EscManager extends Base` — legacy Escape-key dispatcher. **Deprecated**; use
+`UiLayerManager`. `register(obj, fn)`, `unregister(obj)`, `escapeLatest(ev)`.
+
+---
+
+## The `Garnish` namespace object
+
+`import {Garnish} from '@craftcms/garnish'` (also the default export). A single
+object carrying every class, constant, utility, and flag — the legacy-shaped
+singleton, for incremental migration. **Prefer the tree-shakeable named exports in
+new code.**
+
+- **Classes:** `Base`, `Modal`, `BaseDrag`, `Drag`, `DragDrop`, `DragSort`,
+  `DragMove`, `UiLayerManager`, `EscManager`, `ShortcutManager` (_deprecated_ alias
+  of `UiLayerManager`).
+- **Globals/flags:** `win`, `doc`, `bod`, `scrollContainer` (get/set), `rtl`, `ltr`,
+  `activateEventsMuted` (get/set), `resizeEventsMuted` (get/set).
+- **Class-level events:** `on(Class, …)`, `off(Class, …)`, `once(Class, …)`.
+- **Managers (after `initGarnish()`):** `escManager`, `uiLayerManager`.
+- **Custom-event installers:** `installActivate`, `installTextchange`, `installResize`.
+- **Icons:** `ResizeHandle` (SVG string).
+- Plus every constant and utility listed below, and `muteResizeEvents(cb)`.
+
+`initGarnish(): typeof Garnish` — lazily create + attach the manager singletons
+(idempotent).
+
+`muteResizeEvents(callback): void` — run `callback` with `resize` events suppressed.
+
+---
+
+## Utilities (named exports, also on `Garnish`)
+
+### DOM (`utils/dom`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `coerceElements` | `(input) => EventTarget[]` | jQuery-free `$(x)` coercion. |
+| `getElement` | `(input) => EventTarget \| undefined` | First coerced element. |
+| `hasAttr` | `(elem, attr) => boolean` | Whether the attribute is present. |
+| `getOffset` | `(elem) => {top, left}` | Document-relative offset. |
+| `hitTest` | `(x, y, elem) => boolean` | Whether a page point is inside the element. |
+| `isCursorOver` | `(ev, elem) => boolean` | Whether the cursor is over the element. |
+| `copyTextStyles` | `(source, target) => void` | Copy font/text CSS props. |
+
+### Focusable matcher (`utils/focusable`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `isFocusable` | `(el) => boolean` | Visible + focusable (incl. `tabindex="-1"`). |
+| `isKeyboardFocusable` | `(el) => boolean` | Focusable and Tab-reachable. |
+| `getFocusableElements` | `(container) => HTMLElement[]` | Focusable descendants, in order. |
+| `isVisible` | `(el) => boolean` | jQuery-`:visible` equivalent. |
+
+### Focus management (`utils/focus`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `focusIsInside` | `(container) => boolean` | Whether focus is within. |
+| `firstFocusableElement` | `(container) => HTMLElement \| null` | First focusable child. |
+| `getKeyboardFocusableElements` | `(container) => HTMLElement[]` | Tab-reachable descendants. |
+| `getFocusedElement` | `() => Element \| null` | `document.activeElement`. |
+| `trapFocusWithin` | `(container) => void` | Install a Tab focus trap. |
+| `releaseFocusWithin` | `(container) => void` | Remove the focus trap. |
+| `setFocusWithin` | `(container) => void` | Focus the first sensible element (or the container). |
+
+### ARIA (`utils/aria`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `addModalAttributes` | `(container) => void` | Add `aria-modal`/`role="dialog"`. |
+| `ariaHide` | `(element) => void` | `aria-hidden="true"` (restorable). |
+| `hideModalBackgroundLayers` | `() => void` | Hide background siblings from AT. |
+| `resetModalBackgroundLayerVisibility` | `() => void` | Reverse the above. |
+| `isScriptOrStyleElement` | `(element) => boolean` | `<script>`/`<style>` test. |
+| `hasJsAriaClass` | `(element) => boolean` | Whether it carries the bookkeeping class. |
+
+### Forms (`utils/forms`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `getInputBasename` | `(elem) => string \| null` | `name` with `[brackets]` stripped. |
+| `getInputPostVal` | `(input) => string \| string[] \| null` | Value as it would POST. |
+| `findInputs` | `(container) => HTMLElement[]` | Inputs within (legacy selector wart preserved). |
+| `getPostData` | `(container) => Record<string,string>` | Serialize inputs to a POST map. |
+| `copyInputValues` | `(source, target) => void` | Copy values input-by-input (skips files). |
+
+### Animation / scroll (`utils/animation`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `requestAnimationFrame` / `cancelAnimationFrame` | native | Re-exported native RAF. |
+| `prefersReducedMotion` | `() => boolean` | Reduced-motion preference. |
+| `getUserPreferredAnimationDuration` | `(duration) => number \| string` | `0` if reduced-motion, else the value. |
+| `scrollContainerToElement` | `(container, elem?) => void` | Scroll an element into view. |
+| `shake` | `(elem, prop?) => void` | WAAPI shake (no-op under reduced-motion). |
+
+### Environment (`utils/env`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `isMobileBrowser` | `(detectTablets?) => boolean` | UA sniff. **Deprecated** (prefer feature queries). |
+| `isPrimaryClick` | `(ev) => boolean` | Primary click, no Ctrl/Meta. |
+| `isCtrlKeyPressed` | `(ev) => boolean` | Platform Ctrl/⌘ pressed. |
+| `getBodyScrollTop` | `() => number` | Clamped body scrollTop. |
+
+### Misc (`utils/misc`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `getDist` | `(x1,y1,x2,y2) => number` | Euclidean distance. |
+| `within` | `(num,min,max) => number` | Clamp into range. |
+| `isString` | `(val) => boolean` | String type guard. |
+| `isArray` | `(val) => boolean` | **Deprecated** — use `Array.isArray`. |
+| `isTextNode` | `(elem) => boolean` | Text-node test. |
+| `log` | `(msg) => void` | **Deprecated** — use `console`. |
+| `handleActivatingKeypress` | `(event, cb) => void` | **Deprecated** — use the `activate` event. |
+
+### Custom-event installers (`custom-events`)
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `installActivate` | `(el) => () => void` | Install unified click/keyboard `activate`; returns a disposer. |
+| `installTextchange` | `(el, {delay?}) => () => void` | Install debounced `textchange`; returns a disposer. |
+| `installResize` | `(el) => () => void` | Install dimension-change `resize`; returns a disposer. |
+
+Reached transparently via `addListener(el, 'activate' | 'textchange' | 'resize', fn)`.
+
+### Event system primitives (`events`, `dom-listeners`)
+
+Mostly used through `Base`, but exported for advanced use:
+
+- `EventEmitter` — per-instance object pub/sub (backs `Base.on/off/once/trigger`).
+- `ClassEventBus` — class-level pub/sub (backs `Garnish.on/off/once`).
+- `DomListenerRegistry` — namespaced DOM-listener registry (backs `addListener`).
+- `parseEvents(events, splitOn?)`, `formatDomEvents(events, namespace)` — event-string helpers.
+- Types: `GarnishEvent`, `GarnishEventHandler`, `DomListenerOptions`, `ElementInput`,
+  `GarnishBaseSettings`, `ActivateOptions`, `TextchangeOptions`.
+
+### Constants (`constants`)
+
+Key codes (`ESC_KEY`, `TAB_KEY`, `RETURN_KEY`, `SPACE_KEY`, `A_KEY`, arrows, …),
+mouse buttons (`PRIMARY_CLICK`, `SECONDARY_CLICK`), axes (`X_AXIS`, `Y_AXIS`),
+durations (`FX_DURATION`, `SHAKE_STEPS`, `SHAKE_STEP_DURATION`), node types
+(`TEXT_NODE`), and ARIA classes (`JS_ARIA_CLASS`, `JS_ARIA_TRUE_CLASS`,
+`JS_ARIA_FALSE_CLASS`). Also `VERSION`.
+
+### Globals (`globals`)
+
+`win` (`window`), `doc` (`document`), `bod` (`document.body`) — native refs. The
+jQuery-wrapped forms (`$win`/`$doc`/`$bod`/`$scrollContainer`) are **compat-only**.
+
+---
+
+## Compat exports (`@craftcms/garnish/compat`)
+
+Importing the module is **side-effecting**: it builds the legacy-shaped namespace
+and assigns `window.Garnish`.
+
+| Export | Signature | Description |
+| --- | --- | --- |
+| `GarnishCompat` | object (default export) | The assembled legacy-shaped namespace (built on import). |
+| `installGarnishCompat` | `() => GarnishCompatNamespace` | Build + install onto `window.Garnish` (guarded, idempotent). |
+| `buildGarnishCompat` | `() => GarnishCompatNamespace` | Build the namespace **without** touching `window`. |
+| `compatify` | `(ModernClass) => LegacyCtor` | Wrap a modern class so `.extend()` / `init` / `this.base()` work. |
+| `resolveJQuery` | `() => JQueryLike \| null` | Detect global jQuery. |
+| `isJquery` | `(val) => boolean` | Whether a value is a jQuery collection. |
+| `toJq` | `(value) => JQueryCollection` | `$(value)` (throws if jQuery absent). |
+| `unwrapJq` | `(value) => unknown` | jQuery collection → first native element. |
+
+**`.extend()` shape:** `LegacyClass.extend(instanceMembers?, staticMembers?)` returns
+a real subclass. Inside instance methods, `this.base(...)` calls the ancestor
+implementation; `init(...)` runs as the constructor on the most-derived class.
+Constructor arguments that are jQuery collections (or selectors) are unwrapped to
+native elements before reaching the modern class.
+
+**jQuery-only namespace members** restored by the compat layer: `isJquery`,
+`$win`/`$doc`/`$bod`/`$scrollContainer` (lazy getters), a jQuery-wrapped
+`getFocusedElement()`, the `$.fn.activate/textchange/resize` chaining sugar, and the
+deprecated `Menu` (→ `CustomSelect`, when ported) / `ShortcutManager` (→
+`UiLayerManager`) aliases. jQuery is required (and detected) at runtime for these;
+absent jQuery, jQuery-only features throw a clear error and the rest degrades
+gracefully.
+
+---
+
+## Everything ported
+
+The full drag cluster (`BaseDrag`, `DragMove`, `Drag`, `DragDrop`, `DragSort`),
+`Modal` (incl. `draggable`/`resizable`), and `HUD` (Phase 3 — anchored popover with
+4-way positioning + scroll-follow) are implemented and supported — no drag modules
+are pending, and the last `FieldLayoutDesigner` overlay blocker (`HUD`) is done.
diff --git a/packages/craftcms-garnish/docs/07-drag-foundation-design.md b/packages/craftcms-garnish/docs/07-drag-foundation-design.md
new file mode 100644
index 00000000000..afec141cfbc
--- /dev/null
+++ b/packages/craftcms-garnish/docs/07-drag-foundation-design.md
@@ -0,0 +1,660 @@
+# 07 — Drag Foundation Design (`BaseDrag`, `DragMove`, auto-scroll)
+
+> **Status:** design contract only. This document specifies the TypeScript surface
+> the implementation engineer should build. No implementation code is written here.
+>
+> **Scope:** port the legacy `BaseDrag.js` (~580 LOC) and the trivial `DragMove.js`
+> subclass to the modern, jQuery-free core, and re-wire `Modal`'s `draggable` /
+> `resizable` options so they stop throwing. The design also reserves the
+> subclass-override surface that `Drag` and `DragSort` will need later, so we do
+> not paint ourselves into a corner.
+
+---
+
+## 0. Reuse inventory — what already exists in the modern core
+
+Before designing anything new, here is what the modern core already provides that
+`BaseDrag` should reuse (do **not** duplicate these):
+
+| Need | Already exists | Location |
+| --- | --- | --- |
+| `Base` lifecycle / settings / events / DOM listeners | `Base` | `src/base.ts` |
+| Namespaced DOM listener add/remove | `addListener` / `removeListener` / `removeAllListeners` | `src/base.ts` → `src/dom-listeners.ts` |
+| Object + class pub/sub (`trigger`) | `EventEmitter` / `ClassEventBus` | `src/events.ts` |
+| `requestAnimationFrame` / `cancelAnimationFrame` | re-exported native | `src/utils/animation.ts` |
+| Euclidean distance | `getDist(x1,y1,x2,y2)` | `src/utils/misc.ts` |
+| Primary-click test | `isPrimaryClick(ev)` | `src/utils/env.ts` |
+| Page-relative offset | `getOffset(elem): {top,left}` | `src/utils/dom.ts` |
+| Element coercion (`$(x)` → `EventTarget[]`) | `coerceElements` | `src/utils/dom.ts` |
+| `window` / `document` / `body` refs | `win` / `doc` / `bod` | `src/globals.ts` |
+| Mutable feature flags (`activateEventsMuted`, `rtl`/`ltr`) | `globals` | `src/globals.ts` |
+| Axis constants | `X_AXIS` / `Y_AXIS` | `src/constants.ts` |
+| `ResizeHandle` SVG markup | `ResizeHandle` | `src/icons/resize-handle.ts` |
+
+**Gaps that must be filled (new code):**
+
+1. **A scroll-parent finder.** `animation.ts` has a *private* `getScrollParent(el)`
+   but it (a) is not exported, (b) only checks `overflow-y`, and (c) does not
+   replicate `BaseDrag.setScrollContainer`'s axis-aware walk. The drag foundation
+   needs a *shared, exported, axis-aware* finder. **Decision:** create
+   `src/utils/scroll.ts`, move/generalize the finder there, and have
+   `animation.ts` import it (so there is one implementation). See §4.
+2. **`outerWidth` / `outerHeight` helpers.** `Drag` (downstream) reads
+   `this.$targetItem.outerWidth()`. There is no native helper yet. Add
+   `getOuterWidth(el)` / `getOuterHeight(el)` to `src/utils/dom.ts` returning
+   `offsetWidth` / `offsetHeight` (border-box). `BaseDrag` itself does not need
+   these, but reserving them now keeps the `Drag` port clean.
+3. **A per-element drag registry** to replace `$.data(item, 'drag')` — a
+   module-level `WeakMap<Element, BaseDrag>` (see §2).
+
+---
+
+## 1. `BaseDrag` public contract
+
+### 1.1 Constructor
+
+Legacy signature: `init(items, settings)` with a param-shift — if `settings` is
+omitted and `items` is a plain object, `items` is treated as `settings`.
+
+Modern signature (mirrors how `Modal` already does its param-shift):
+
+```ts
+export class BaseDrag<S extends BaseDragSettings = BaseDragSettings> extends Base<S> {
+  constructor(
+    items?: DragItemsInput | Partial<S> | null,
+    settings?: Partial<S>
+  ) {
+    super();
+    // param-shift: new BaseDrag(settings) when first arg is a plain object
+    this.setSettings(resolvedSettings, BaseDrag.defaults);
+    this.items = [];
+    if (resolvedItems) this.addItems(resolvedItems);
+  }
+}
+```
+
+Where:
+
+```ts
+/** Anything addItems/removeItems accepts: a selector, element, or list. */
+export type DragItemsInput = ElementInput; // reuse the core ElementInput union
+```
+
+> **Subclass note:** `Drag`/`DragSort` override `startDragging`/`drag`/`stopDragging`
+> and call `super.startDragging()` etc. Because the modern `Base` uses native
+> `class extends` (no `init()` trampoline, no `this.base()`), these subclasses use a
+> real `constructor` + `super(...)` and `super.method()`. The compat layer is what
+> bridges any legacy `extend()/init()/base()` callers — `BaseDrag` itself stays
+> native.
+
+### 1.2 Settings (every setting + default)
+
+```ts
+export interface BaseDragSettings extends GarnishBaseSettings {
+  /** Min px the pointer must travel before a drag starts. `null` → static default (1). */
+  minMouseDist: number | null;
+  /**
+   * The drag handle. Element(s), a selector resolved within each item, or a
+   * function `(item) => handleElement`. `null` → the item itself is the handle.
+   */
+  handle: ElementInput | ((item: Element) => ElementInput) | null;
+  /** Restrict movement to one axis. `X_AXIS`, `Y_AXIS`, or `null` (both). */
+  axis: typeof X_AXIS | typeof Y_AXIS | null;
+  /** Pointer-down on a descendant matching this selector is ignored (unless it IS the handle). */
+  ignoreHandleSelector: string | null;
+
+  onBeforeDragStart: () => void;
+  onDragStart: () => void;
+  onDrag: () => void;
+  onDragStop: () => void;
+}
+
+static readonly defaults: BaseDragSettings = {
+  minMouseDist: null,
+  handle: null,
+  axis: null,
+  ignoreHandleSelector: 'input, textarea, button, select, .btn',
+  onBeforeDragStart: () => {},
+  onDragStart: () => {},
+  onDrag: () => {},
+  onDragStop: () => {},
+};
+```
+
+Static tunables (legacy class-statics):
+
+```ts
+static readonly minMouseDist = 1;            // fallback when settings.minMouseDist === null
+static readonly windowScrollTargetSize = 25; // px edge band that triggers auto-scroll
+```
+
+### 1.3 Public properties consumers/subclasses read
+
+These are the API `Drag`/`DragSort`/`DragMove`/`Modal` depend on — keep names and
+semantics exact. **Important rename:** legacy exposes `$items` / `$targetItem` as
+jQuery collections. Modern uses native element arrays/elements but keeps the
+`$`-prefixed names for consumer parity (same convention `Modal` already uses with
+`$container` etc.).
+
+```ts
+// Items + current target
+$items: Element[] = [];                 // legacy this.$items (jQuery → array)
+$targetItem: HTMLElement | null = null; // the element currently being dragged (or null)
+
+// State
+dragging = false;
+
+// Pointer coordinates (page coords)
+mousedownX: number | null = null;
+mousedownY: number | null = null;
+realMouseX: number | null = null; // unconstrained, before axis lock
+realMouseY: number | null = null;
+mouseX: number | null = null;     // axis-constrained; what subclasses use
+mouseY: number | null = null;
+mouseDistX: number | null = null; // mouseX - mousedownX
+mouseDistY: number | null = null;
+mouseOffsetX: number | null = null; // pointerdown page X minus target's left offset
+mouseOffsetY: number | null = null;
+
+// Scroll-loop state (set by drag(), read by the scroll frame)
+scrollProperty: 'scrollTop' | 'scrollLeft' | null = null;
+scrollAxis: 'X' | 'Y' | null = null;
+scrollDist: number | null = null;
+scrollFrame: number | null = null;  // RAF handle
+```
+
+> `Modal._handleResize` reads `this.resizeDragger.mouseDistX` / `.mouseDistY` — so
+> `mouseDistX/Y` must be populated **before** `onDrag` fires (it already is in the
+> legacy flow: `_handleMouseMove` sets them, then calls `drag()` → `onDrag()`).
+
+> **Reserved for `Drag` (not implemented in `BaseDrag`, but the property names must
+> not collide):** `targetItemWidth`, `targetItemHeight`, `otherItems`,
+> `draggeeDisplay`, `$draggee`, `helpers`. `BaseDrag` should leave these to
+> subclasses. Document this so the `Drag` port can declare them.
+
+### 1.4 Public methods
+
+```ts
+// Item management
+addItems(items: DragItemsInput): void;
+removeItems(items: DragItemsInput): void;
+removeAllItems(): void;
+getPrevItem(item: Element): Element | null;
+getNextItem(item: Element): Element | null;
+
+// Drag lifecycle (overridable by Drag/DragSort via super-dispatch)
+allowDragging(): boolean;     // default true; subclasses gate dragging
+startDragging(): void;
+drag(didMouseMove: boolean): void;
+stopDragging(): void;
+
+// Scroll-container resolution
+setScrollContainer(): void;
+isScrollingWindow(): boolean;
+
+// Lifecycle
+override destroy(): void;      // removeAllItems() + super.destroy()
+```
+
+### 1.5 Overridable hooks (event emitters)
+
+Each hook **triggers an object event AND calls the `settings.on*` callback**.
+`onDragStart`/`onDrag`/`onDragStop` defer their body inside a single
+`requestAnimationFrame` (legacy parity — coalesces rapid mousemoves);
+`onBeforeDragStart` fires synchronously.
+
+```ts
+onBeforeDragStart(): void; // sync:  trigger('beforeDragStart'); settings.onBeforeDragStart()
+onDragStart(): void;       // RAF:   trigger('dragStart');       settings.onDragStart()
+onDrag(): void;            // RAF:   trigger('drag');            settings.onDrag()
+onDragStop(): void;        // RAF:   trigger('dragStop');        settings.onDragStop()
+```
+
+> `onReturnHelpersToDraggees` is **not** part of `BaseDrag` — it lives in `Drag`.
+> Listed in the brief for completeness; do not add it here.
+
+### 1.6 Events triggered
+
+`beforeDragStart`, `dragStart`, `drag`, `dragStop`, plus the inherited
+`destroy` (from `Base`). Subscribe via `instance.on('drag', ...)` or
+`Garnish.on(BaseDrag, 'drag', ...)`.
+
+---
+
+## 2. jQuery removals — every usage → native replacement
+
+| # | Legacy (BaseDrag.js) | Native replacement |
+| --- | --- | --- |
+| 1 | `$.extend({}, defaults, settings)` (init) | `this.setSettings(settings, BaseDrag.defaults)` (already on `Base`) |
+| 2 | `$.isPlainObject(items)` param-shift | local `isPlainObject()` (same helper `modal.ts` uses; factor into `utils` if not already) |
+| 3 | `this.$items = $()` + `.add()` | `this.$items: Element[]`, `push` / dedupe |
+| 4 | `this.$targetItem.scrollParent()` (×2: `setScrollContainer`) | new `getScrollParent(el, axis)` in `src/utils/scroll.ts` (§4) |
+| 5 | `Garnish.$doc[0]` / `Garnish.$bod[0]` / `Garnish.$win[0]` comparisons | compare against `doc.documentElement` / `bod` / `win` from `globals` |
+| 6 | `this._.$scrollContainer.offset().top/.left` | `getOffset(container)` (`utils/dom.ts`) — but see §3/§4 note on `getBoundingClientRect` for fixed containers |
+| 7 | `.outerHeight()` / `.outerWidth()` on scroll container | `el.clientHeight` for the *inner* edge math; `el.scrollHeight`/`scrollWidth` for max. (Legacy used `outerHeight`; for the scroll container the correct value is `clientHeight`/`clientWidth` — call this out as a behavior fix, see §4 risks.) |
+| 8 | `Garnish.$win.scrollTop()/scrollLeft()/height()/width()` | `win.scrollY` / `win.scrollX` / `win.innerHeight` / `win.innerWidth` |
+| 9 | `this.$targetItem.offset()` (pointer-down offset) | `getOffset(this.$targetItem)` (`utils/dom.ts`) |
+| 10 | `$.makeArray(items)` (addItems/removeItems) | `coerceElements(items)` (`utils/dom.ts`) → `Element[]` |
+| 11 | `$.data(item, 'drag')` / `$.data(item, 'drag', this)` / `$.removeData(item, 'drag')` | module-level `const dragRegistry = new WeakMap<Element, BaseDrag>()` (mirrors `modal.ts`'s `containerModals`) |
+| 12 | `$.inArray(item, this.$items)` | `this.$items.indexOf(item)` |
+| 13 | `this.$items.splice(index, 1)` | unchanged (already an array op once `$items` is native) |
+| 14 | `this.$items.eq(index ± 1)` (getPrev/getNextItem) | `this.$items[index ± 1] ?? null` |
+| 15 | `item instanceof jQuery` (getPrev/getNext) | drop — modern API takes a raw `Element`. (Compat layer can unwrap jQuery if needed.) |
+| 16 | `$(item)` handle resolution + `$(selector, item)` + `:first` munging | resolve via `coerceElements` / `item.querySelector(selector)`; see §2.1 |
+| 17 | `Craft.ensureEndsWith(s, ':first')` in `_getItemHandle` | drop the `:first` hack — `querySelector` already returns the first match. See §2.1. |
+| 18 | `$(ev.target)` + `.is(sel)` / `.closest(sel).length` (ignoreHandleSelector) | `(ev.target as Element).closest(selector)` (covers both `.is` and `.closest`) |
+| 19 | `this.addListener(handle, 'mousedown', fn)` | `this.addListener(handle, 'mousedown', fn)` — same `Base.addListener`, but see §3 (pointer events) |
+| 20 | `this.addListener(Garnish.$doc, 'mousemove'/'mouseup', '_handle…')` | `this.addListener(doc, 'pointermove'/'pointerup', '_handle…')` (§3) |
+| 21 | `this.removeAllListeners(Garnish.$doc)` on mouseup | `this.removeAllListeners(doc)` |
+| 22 | `Garnish.requestAnimationFrame` / `cancelAnimationFrame` | import from `utils/animation.ts` |
+| 23 | `Garnish.activateEventsMuted = true/false` | `globals.activateEventsMuted = true/false` |
+| 24 | `$.noop` (default callbacks) | `() => {}` |
+| 25 | auto-scroll `setInterval`/RAF loop touching `Garnish.$win[prop]()` | `utils/scroll.ts` scroll helpers (§4); the loop itself stays RAF-based |
+
+### 2.1 Handle resolution (`_getItemHandle`)
+
+```ts
+private _getItemHandle(item: Element): Element[] {
+  const {handle} = this.settings!;
+  if (!handle) return [item];
+
+  if (typeof handle === 'function') return coerceElements(handle(item));
+
+  if (typeof handle === 'string') {
+    // Legacy split commas and forced `:first` per selector to dodge
+    // craftcms/cms#12896. Native querySelector already returns the first match,
+    // so resolve each comma-part with item.querySelector and collect non-null.
+    return handle
+      .split(',')
+      .map((s) => item.querySelector(s.trim()))
+      .filter((el): el is Element => el !== null);
+  }
+
+  // Element / list of elements passed directly (Modal passes the container).
+  return coerceElements(handle);
+}
+```
+
+> The legacy `:first` munging existed only because jQuery selectors can return
+> multiple nodes; `querySelector` is inherently first-match, so the hack is dropped.
+
+---
+
+## 3. Pointer / touch model
+
+Legacy binds **`mousedown`** on each handle, then `mousemove`/`mouseup` on
+`document`, and separately wires touch via Garnish's global touch→mouse shims. It
+reads `ev.pageX/pageY` and gates on `Garnish.isPrimaryClick(ev)`.
+
+**Recommendation: use the Pointer Events API** (`pointerdown` / `pointermove` /
+`pointerup`), which unifies mouse + touch + pen and is universally supported in
+every browser Craft 6 targets. This removes the entire legacy touch-shim surface.
+
+Concretely:
+
+- **Bind `pointerdown`** on the handle (replaces `mousedown`).
+- On pointerdown, **`setPointerCapture(ev.pointerId)`** is *not* needed because we
+  listen on `document` for move/up (capture-by-document is the legacy model and
+  keeps delegation simple). Track `this._pointerId = ev.pointerId` and ignore
+  move/up events from other pointer IDs (multi-touch safety).
+- **Bind `pointermove` / `pointerup` on `doc`** (replaces the document
+  mousemove/mouseup). Also bind **`pointercancel`** → treat as `pointerup`
+  (touch interruption; legacy had no equivalent and could leak a stuck drag).
+- **Primary-click gate:** `isPrimaryClick(ev)` already accepts `MouseEvent.button`;
+  `PointerEvent` extends `MouseEvent`, so `ev.button === 0` works unchanged. Keep
+  the existing `isPrimaryClick` call.
+- **`touch-action`:** to stop the browser from scroll-panning while dragging, the
+  handle should get `style.touchAction = 'none'` (or the consumer sets it via CSS).
+  Note this in the Modal wiring and playground.
+
+**Coordinates without jQuery `.offset()`:**
+
+- `ev.pageX` / `ev.pageY` exist on `PointerEvent` — use them directly for
+  `mousedownX/Y`, `mouseX/Y`, `realMouseX/Y` (parity with legacy).
+- The target offset (for `mouseOffsetX/Y`) uses the existing
+  `getOffset(this.$targetItem)` helper:
+  ```ts
+  const offset = getOffset(this.$targetItem); // {top, left} page-relative
+  this.mouseOffsetX = ev.pageX - offset.left;
+  this.mouseOffsetY = ev.pageY - offset.top;
+  ```
+- Axis locking is unchanged: only assign `mouseX` when `axis !== Y_AXIS`, only
+  assign `mouseY` when `axis !== X_AXIS`; `realMouseX/Y` are always assigned.
+
+**Method renames (private):** `_handleMouseDown` → `_handlePointerDown`,
+`_handleMouseMove` → `_handlePointerMove`, `_handleMouseUp` → `_handlePointerUp`.
+Keep the same body logic. (If the compat layer needs the old names it can alias.)
+
+> **Risk:** the modern `addListener` wrapper builds a Garnish event object over the
+> native event. `pageX/pageY/pointerId/button` are native props that pass straight
+> through (the wrapper only *adds* `data`/`garnishTarget`), so reading them in the
+> handlers is safe. Confirmed against `dom-listeners.ts::toGarnishEvent`.
+
+---
+
+## 4. Auto-scroll machinery → `src/utils/scroll.ts`
+
+This is foundational and shared (Drag/DragSort reuse it), so it lives in a reusable
+module, **not** inside `base-drag.ts`.
+
+### 4.1 New module `src/utils/scroll.ts`
+
+```ts
+/** Axis-aware nearest-scrollable-ancestor finder (replaces jQuery .scrollParent()). */
+export function getScrollParent(
+  el: Element,
+  axis?: 'x' | 'y' | null
+): Element | Window;
+
+/** True if the resolved scroll container is the window. */
+export function isWindowScrollContainer(container: Element | Window): boolean;
+```
+
+`getScrollParent` reproduces `BaseDrag.setScrollContainer`'s walk:
+
+1. Start at `el`'s nearest scroll parent (overflow auto/scroll/overlay ancestor).
+2. If that is `documentElement` or `body`, return `win`.
+3. Otherwise, if the container is scrollable **on the relevant axis**
+   (`axis !== X_AXIS && scrollHeight > clientHeight`, or
+   `axis !== Y_AXIS && scrollWidth > clientWidth`), it is the container.
+4. Else, climb to the next scroll parent and repeat.
+
+The existing private `getScrollParent` in `animation.ts` should be **deleted and
+re-imported from here** so there is a single implementation. (Its current version
+only checks `overflow-y`; the generalized one checks both axes — a strict superset,
+so `scrollContainerToElement` keeps working.)
+
+### 4.2 The drag-edge auto-scroll loop
+
+Keep this **inside `base-drag.ts`** (it is drag-specific control flow), but have it
+call the `scroll.ts` primitives for the actual scrolling. The loop:
+
+- In `drag(didMouseMove)`, when `didMouseMove`, compute whether the pointer is
+  within `windowScrollTargetSize` (25px) of a scrollable edge:
+  - Vertical (unless `axis === X_AXIS`): edges from
+    `isWindowScrollContainer` ? `[win.scrollY, win.scrollY + win.innerHeight]`
+    : `[getOffset(container).top, +container.clientHeight]`. Inset both by 25px.
+    If `mouseY` is outside the inset band → set `scrollProperty='scrollTop'`,
+    `scrollAxis='Y'`, `scrollDist=round((mouseY - edge)/2)`.
+  - Horizontal mirror (unless `axis === Y_AXIS`), only if vertical didn't already
+    claim the scroll.
+- If a scroll property is set and we weren't already scrolling, start a RAF loop
+  `_scrollWindow()`. Cache `scrollProperty/Axis/Dist`. Else `_cancelWindowScroll()`.
+
+`_scrollWindow()` each frame:
+
+- Read current scroll pos: window → `win.scrollY/scrollX`; element → `el.scrollTop/scrollLeft`.
+- Target = current + `scrollDist`, clamped to `[0, scrollMax]` where
+  `scrollMax = scrollHeight - clientHeight` (Y) or `scrollWidth - clientWidth` (X).
+
+  > **Behavior fix:** legacy used `outerHeight()` (border-box, includes border) for
+  > the subtrahend, which is subtly wrong for a scroll container. The correct
+  > value is `clientHeight`/`clientWidth`. Use `clientHeight`/`clientWidth`. Flag in
+  > §9 as a deliberate deviation to validate in the playground.
+- Apply: window → `win.scrollTo({top|left})`; element → assign `el.scrollTop/Left`.
+- **Window-only correction:** when scrolling the window, adjust `mouseX/realMouseX`
+  (or Y) by the delta so the dragged helper keeps tracking the cursor (legacy
+  `this['mouse'+axis] -= scrollPos - newScrollPos`).
+- Re-schedule itself via RAF and call `this.drag(true)` again.
+
+`_cancelWindowScroll()` cancels the RAF and nulls `scrollProperty/Axis/Dist`.
+
+> Store the resolved container on a private field (e.g. `this._scrollContainer:
+> Element | Window`) instead of the legacy `this._.$scrollContainer` bag.
+
+---
+
+## 5. `DragMove`
+
+Trivial subclass. Replaces the throwing stub in `src/drag-move.ts`. On each drag
+frame it positions the target's top-left at the cursor minus the grab offset:
+
+```ts
+import {BaseDrag, type BaseDragSettings} from './drag/base-drag';
+
+export class DragMove extends BaseDrag {
+  override onDrag(): void {
+    if (this.$targetItem) {
+      this.$targetItem.style.left = `${this.mouseX! - this.mouseOffsetX!}px`;
+      this.$targetItem.style.top = `${this.mouseY! - this.mouseOffsetY!}px`;
+    }
+    super.onDrag(); // preserve the trigger('drag') + settings.onDrag() (RAF) behavior
+  }
+}
+
+export default DragMove;
+```
+
+> **Subtlety:** legacy `DragMove.onDrag` *replaced* `BaseDrag.onDrag` entirely and
+> did **not** call super — so it set CSS but did **not** trigger the `drag` event or
+> `settings.onDrag`. Decide:
+> - **Option A (recommended):** call `super.onDrag()` so `DragMove` also emits the
+>   `drag` event (strictly more capable; nothing legacy depended on the omission).
+> - **Option B (strict parity):** don't call super (no event). Modal's draggable
+>   path passes no `onDrag`, so either works for Modal.
+>
+> Recommend **A** and note the deviation. The CSS write must happen *synchronously*
+> on each drag (not deferred), so write `left/top` before delegating to the RAF'd
+> `super.onDrag()`.
+
+---
+
+## 6. Modal wiring — stop throwing, support `draggable` / `resizable`
+
+`Modal.setContainer` currently throws for both options. Replace the two `throw`
+blocks (`modal.ts` lines ~276–286) with the real wiring, mirroring legacy
+`Modal.js` lines 79–96.
+
+### 6.1 `draggable`
+
+```ts
+if (this.settings!.draggable) {
+  this.dragger = new DragMove(this.$container, {
+    handle: this.settings!.dragHandleSelector
+      ? this.$container.querySelector(this.settings!.dragHandleSelector)
+      : this.$container,
+  });
+}
+```
+
+- Type `dragger` as `DragMove | null` (currently `unknown`).
+- `handle` accepts an `Element` (the container or the resolved handle) — matches the
+  `BaseDragSettings.handle` union.
+
+### 6.2 `resizable`
+
+```ts
+if (this.settings!.resizable) {
+  const handle = document.createElement('div');
+  handle.className = 'resizehandle';
+  handle.innerHTML = ResizeHandle;          // import from ./icons/resize-handle
+  this.$container.appendChild(handle);
+
+  this.resizeDragger = new BaseDrag(handle, {
+    onDragStart: () => this._handleResizeStart(),
+    onDrag: () => this._handleResize(),
+  });
+}
+```
+
+- Type `resizeDragger` as `BaseDrag | null`.
+- The two handlers already exist conceptually but need porting into `modal.ts`
+  (they are not currently present — only the `resizeStartWidth/Height` fields are):
+
+```ts
+private _handleResizeStart(): void {
+  this.resizeStartWidth = this.getWidth();
+  this.resizeStartHeight = this.getHeight();
+}
+
+private _handleResize(): void {
+  if (globals.ltr) {
+    this.desiredWidth = this.resizeStartWidth! + this.resizeDragger!.mouseDistX! * 2;
+  } else {
+    this.desiredWidth = this.resizeStartWidth! - this.resizeDragger!.mouseDistX! * 2;
+  }
+  this.desiredHeight = this.resizeStartHeight! + this.resizeDragger!.mouseDistY! * 2;
+  this.updateSizeAndPosition();
+}
+```
+
+- `globals.ltr` already exists (`globals.ts`).
+- `desiredWidth/Height` are already fields on `Modal` and feed
+  `updateSizeAndPosition` (`modal.ts` lines 485–490) — no change needed there.
+
+### 6.3 Destroy
+
+`Modal.destroy` must tear down both draggers (legacy lines 407–413):
+
+```ts
+this.dragger?.destroy();
+this.resizeDragger?.destroy();
+```
+
+Add these to the existing `override destroy()` before `super.destroy()`.
+
+### 6.4 Core/BaseDrag surface Modal calls
+
+| Modal call | Provided by |
+| --- | --- |
+| `new DragMove(container, {handle})` | `DragMove` ctor + `BaseDragSettings.handle` |
+| `new BaseDrag(handle, {onDragStart, onDrag})` | `BaseDrag` ctor + settings callbacks |
+| `this.resizeDragger.mouseDistX` / `.mouseDistY` | `BaseDrag` public props (§1.3) |
+| `dragger.destroy()` / `resizeDragger.destroy()` | `BaseDrag.destroy()` (§1.4) |
+| `globals.ltr` | `globals.ts` |
+| `ResizeHandle` | `icons/resize-handle.ts` |
+
+> Remove the `dragger: unknown` / `resizeDragger: unknown` placeholder typings and
+> the two `throw` blocks. Update the class doc comment that says draggable/resizable
+> are unsupported.
+
+---
+
+## 7. Testing strategy (happy-dom — no layout, no real pointer)
+
+happy-dom returns `0` for `getBoundingClientRect`/`offsetWidth` and does not
+synthesize pointer geometry, so split coverage:
+
+**Unit-testable (Vitest, mock where noted):**
+
+- **Settings/defaults merge** — construct with/without overrides; assert
+  `settings` and the param-shift (`new BaseDrag(settingsObj)`).
+- **Item management** — `addItems`/`removeItems`/`removeAllItems`/`getPrev`/`getNextItem`
+  against a fake DOM; assert the `$items` array and the `WeakMap` registry
+  (dedupe + "added to more than one dragger" warn path via a spy on `console.warn`).
+- **Event wiring** — spy on `trigger` and the `settings.on*` callbacks; directly
+  invoke `onBeforeDragStart/onDragStart/onDrag/onDragStop` (drive the RAF with a
+  fake timer or by stubbing `requestAnimationFrame` to call synchronously) and
+  assert event names + callback invocation order.
+- **Pointer-down gating** — dispatch a synthetic `PointerEvent` (or a plain object
+  with `button/pageX/pageY/ctrlKey`) and assert: secondary click ignored,
+  `ignoreHandleSelector` match ignored, `$targetItem` captured, `mousedownX/Y` and
+  `mouseOffsetX/Y` computed (mock `getOffset`/`getBoundingClientRect` to return a
+  known rect).
+- **Coordinate math** — feed scripted `pointermove` events with mocked `pageX/pageY`;
+  assert axis locking (`X_AXIS`/`Y_AXIS`/both), `mouseDistX/Y`, and the
+  `minMouseDist` threshold gate to `startDragging`.
+- **`getScrollParent` logic** (`scroll.ts`) — build an ancestor chain with mocked
+  `getComputedStyle` + `scrollHeight/clientHeight`; assert it returns the right node
+  vs. `window`, and that `axis` narrows correctly.
+- **Auto-scroll decision math** — call a small extracted helper (recommend
+  factoring the "is the pointer in the edge band, and how far" computation into a
+  pure function the loop calls) with mocked rects/scroll metrics; assert
+  `scrollProperty/Axis/Dist`. This avoids needing a live RAF/scroll.
+- **`DragMove.onDrag`** — set `mouseX/Y` + `mouseOffsetX/Y` + a fake `$targetItem`,
+  call `onDrag`, assert `style.left/top`.
+- **Modal `_handleResize`** — set a fake `resizeDragger` with `mouseDistX/Y`, stub
+  `getWidth/getHeight`, assert `desiredWidth/Height` (both `ltr` and `rtl` via
+  `globals.rtl`) and that `updateSizeAndPosition` is called.
+
+**Manual (Vite playground) only — needs real layout/pointer:**
+
+- End-to-end drag of a `DragMove` element following the cursor.
+- Modal `draggable` (drag by handle / by container) and `resizable` (resize handle
+  grows/shrinks symmetrically; RTL mirroring).
+- The live auto-scroll loop near container/window edges (window correction keeping
+  the helper under the cursor).
+- `touch-action: none` behavior on touch devices.
+- `pointercancel` cleanup (no stuck drag after a touch interruption).
+
+> Provide a playground page (`playground/drag.html` or similar) with: a free
+> `DragMove` box, a draggable+resizable Modal, and a tall scroll container, so all
+> of the above can be eyeballed.
+
+---
+
+## 8. Proposed file layout & exports
+
+```
+src/
+  drag/
+    base-drag.ts        # BaseDrag class + BaseDragSettings + static defaults/tunables
+  drag-move.ts          # REPLACE the throwing stub with `class DragMove extends BaseDrag`
+  utils/
+    scroll.ts           # getScrollParent(el, axis), isWindowScrollContainer()  (NEW)
+    dom.ts              # + getOuterWidth/getOuterHeight (for downstream Drag)
+```
+
+- New folder `src/drag/` anticipates `drag/drag.ts` and `drag/drag-sort.ts` later;
+  `BaseDrag` lives there. `DragMove` stays at `src/drag-move.ts` (its current path,
+  already exported from the barrel) to avoid churn in `index.ts`.
+- **`index.ts` named exports:** add `BaseDrag` and `BaseDragSettings`; `DragMove` is
+  already exported. Re-export `getScrollParent` (and `getOuterWidth/Height`) through
+  `src/utils/index.ts` → the barrel's `export * from './utils'`.
+- **`Garnish` namespace object** (legacy-shaped, lower half of `index.ts`): add
+  `BaseDrag` and `DragMove` properties so `new Garnish.BaseDrag(...)` /
+  `new Garnish.DragMove(...)` resolve (this is exactly what legacy `Modal.js`
+  calls, and what the compat layer relies on). `DragMove` is presumably already
+  on the namespace given the stub export — verify and add `BaseDrag` alongside it.
+- **`scroll.ts` ↔ `animation.ts`:** `animation.ts` deletes its private
+  `getScrollParent` and imports from `scroll.ts` (single source of truth).
+
+---
+
+## 9. Hard-to-reproduce legacy behavior / risks
+
+1. **Touch parity vs. Pointer Events.** Recommending Pointer Events drops the entire
+   legacy touch-shim path. This is *better*, but it is a behavioral change: legacy
+   synthesized mouse coords from `touchstart/move/end`. Pointer Events give us
+   `pageX/pageY` natively, but anything in the legacy global touch shim that other
+   code relied on is out of scope here. **Risk: low** for drag itself; validate on a
+   touch device in the playground. Also requires `touch-action: none` on handles to
+   prevent the browser eating the gesture — this is a new requirement consumers
+   (incl. Modal) must honor.
+
+2. **`scrollParent` edge cases.** jQuery's `.scrollParent()` has quirky rules
+   (position:fixed handling, `overflow: hidden` ancestors, the `body`/`html`
+   normalization). The native finder in §4.1 checks `overflow` auto/scroll/overlay +
+   axis scrollability, which covers the common cases but is **not** byte-for-byte
+   identical to jQuery UI's algorithm. **Risk: medium** for deeply nested scroll
+   containers; the `Modal` use case (window scroll) is unaffected. Validate with the
+   tall-scroll-container playground case.
+
+3. **`clientHeight` vs legacy `outerHeight()` in scroll math (§4.2).** Deliberate
+   correction. The legacy border-box value was subtly wrong; we use `clientHeight`/
+   `clientWidth`. **Risk: low**, but eyeball the auto-scroll clamp at container
+   bottoms to confirm it doesn't over/under-scroll.
+
+4. **Window-scroll cursor correction.** The `mouseX -= scrollPos - newScrollPos`
+   adjustment during window auto-scroll is fiddly and untestable in happy-dom
+   (no real scroll). **Risk: medium** — must be validated live; a regression here
+   manifests as the dragged helper drifting away from the cursor while edge-scrolling.
+
+5. **RAF coalescing of hooks.** `onDragStart/onDrag/onDragStop` defer inside a RAF.
+   If a subclass (or Modal's resize) expects the `onDrag` body to have run *before*
+   the next pointermove, the deferral could reorder. Legacy had the same deferral,
+   so parity is preserved — but `Modal._handleResize` reads `mouseDistX/Y`, which are
+   set *synchronously* in `_handlePointerMove` before `drag()`/`onDrag()`, so the
+   resize math stays correct. **Risk: low** (called out so it isn't "fixed" by
+   accident).
+
+6. **`DragMove` not calling `super.onDrag` in legacy (§5).** Choosing Option A
+   (call super → also emit `drag`) is a minor behavioral addition. **Risk: trivial.**
+
+7. **`$items` semantics change (jQuery collection → `Element[]`).** Downstream
+   `Drag`/`DragSort` read `this.$items` and currently treat it as a jQuery object
+   (`.length`, `.eq()`, `$.inArray`). When those are ported they must move to array
+   indexing. The `BaseDrag` contract here uses `Element[]`; flag this so the `Drag`
+   port doesn't assume a jQuery collection. The compat layer is the place to expose
+   a jQuery-wrapped `$items` if any external plugin needs it.
+```
diff --git a/packages/craftcms-garnish/docs/08-drag-impl-notes.md b/packages/craftcms-garnish/docs/08-drag-impl-notes.md
new file mode 100644
index 00000000000..042c0d28bfa
--- /dev/null
+++ b/packages/craftcms-garnish/docs/08-drag-impl-notes.md
@@ -0,0 +1,217 @@
+# 08 — Drag Foundation Implementation Notes (`BaseDrag`, `DragMove`, Modal wiring)
+
+> Status: **Implemented.** Built against the `07-drag-foundation-design.md` contract.
+> All four gates are green in the worktree:
+> `check:types`, `check:format`, `test` (162 tests, was 121), `build`.
+
+## What shipped
+
+| File | Change |
+| --- | --- |
+| `src/utils/scroll.ts` | **NEW.** Exported, axis-aware `getScrollParent(el, axis)` + `isWindowScrollContainer(container)`. Single source of truth. |
+| `src/utils/animation.ts` | Deleted its private `getScrollParent`; now imports from `scroll.ts`. |
+| `src/utils/dom.ts` | Added `getOuterWidth(el)` / `getOuterHeight(el)` (reserved for the `Drag` port). |
+| `src/utils/index.ts` | Re-exports `getScrollParent`, `isWindowScrollContainer`, `getOuterWidth`, `getOuterHeight`. |
+| `src/drag/base-drag.ts` | **NEW.** `class BaseDrag extends Base` — the full §1 contract, Pointer Events, WeakMap registry, native auto-scroll. |
+| `src/drag-move.ts` | Replaced the throwing stub with the real `class DragMove extends BaseDrag`. |
+| `src/modal.ts` | Removed both `throw` blocks; wired `draggable`→`DragMove`, `resizable`→`BaseDrag`; ported `_handleResizeStart`/`_handleResize`; typed `dragger`/`resizeDragger`; added dragger teardown to `destroy()`. |
+| `src/index.ts` | Exports `BaseDrag` + `BaseDragSettings` (named) and adds `BaseDrag` to the `Garnish` namespace (alongside the now-real `DragMove`). |
+| `tests/drag.test.ts` | **NEW.** 36 tests. |
+| `tests/modal.test.ts` | Replaced the "PoC unsupported" block with draggable/resizable wiring + resize-math tests (7 tests). |
+
+## Exact exported public API
+
+### `src/drag/base-drag.ts`
+
+```ts
+export type DragItemsInput = ElementInput;
+export type DragHandle =
+  | ElementInput
+  | ((item: Element) => ElementInput)
+  | null;
+
+export interface BaseDragSettings extends GarnishBaseSettings {
+  minMouseDist: number | null;
+  handle: DragHandle;
+  axis: 'x' | 'y' | null;            // X_AXIS | Y_AXIS | null
+  ignoreHandleSelector: string | null;
+  onBeforeDragStart: () => void;
+  onDragStart: () => void;
+  onDrag: () => void;
+  onDragStop: () => void;
+}
+
+/** Read the owning dragger of an item (test/introspection helper). */
+export function getItemDragger(item: Element): BaseDrag | undefined;
+
+export class BaseDrag<S extends BaseDragSettings = BaseDragSettings> extends Base<S> {
+  static readonly minMouseDist = 1;
+  static readonly windowScrollTargetSize = 25;
+  static readonly defaults: BaseDragSettings;
+
+  // public properties (names + semantics per doc 07 §1.3)
+  $items: Element[];
+  $targetItem: HTMLElement | null;
+  dragging: boolean;
+  mousedownX/Y, realMouseX/Y, mouseX/Y, mouseDistX/Y, mouseOffsetX/Y: number | null;
+  scrollProperty: 'scrollTop' | 'scrollLeft' | null;
+  scrollAxis: 'X' | 'Y' | null;
+  scrollDist: number | null;
+  scrollFrame: number | null;
+
+  constructor(items?: DragItemsInput | Partial<S> | null, settings?: Partial<S>);
+
+  // items
+  addItems(items: DragItemsInput): void;
+  removeItems(items: DragItemsInput): void;
+  removeAllItems(): void;
+  getPrevItem(item: Element): Element | null;
+  getNextItem(item: Element): Element | null;
+
+  // lifecycle (overridable via super-dispatch)
+  allowDragging(): boolean;            // default true
+  startDragging(): void;
+  drag(didMouseMove: boolean): void;
+  stopDragging(): void;
+  setScrollContainer(): void;
+  isScrollingWindow(): boolean;
+  override destroy(): void;
+
+  // hooks (trigger event + settings.on*)
+  onBeforeDragStart(): void;           // sync
+  onDragStart(): void;                 // RAF-deferred
+  onDrag(): void;                      // RAF-deferred
+  onDragStop(): void;                  // RAF-deferred
+}
+```
+
+Events triggered: `beforeDragStart`, `dragStart`, `drag`, `dragStop` (+ inherited `destroy`).
+
+### `src/drag-move.ts`
+
+```ts
+export class DragMove extends BaseDrag {
+  override onDrag(): void; // sets $targetItem.style.left/top, then super.onDrag()
+}
+export { type BaseDragSettings }; // re-exported for convenience
+```
+
+### `src/utils/scroll.ts`
+
+```ts
+export function getScrollParent(el: Element, axis?: 'x' | 'y' | null): Element | Window;
+export function isWindowScrollContainer(container: Element | Window): boolean;
+```
+
+### `src/utils/dom.ts` (additions)
+
+```ts
+export function getOuterWidth(elem: HTMLElement): number;  // offsetWidth
+export function getOuterHeight(elem: HTMLElement): number; // offsetHeight
+```
+
+## Modal draggable/resizable status
+
+**Both work; both default to `false`.** No code path throws anymore.
+
+- **`draggable`** → `new DragMove(this.$container, {handle})` where `handle` is the
+  container, or `dragHandleSelector`'s resolved element. The dragged item is always
+  the container; only the handle differs.
+- **`resizable`** → creates a `<div class="resizehandle">` (innerHTML = `ResizeHandle`
+  SVG, `touch-action: none`), appends it to the container, and drives it with a
+  `BaseDrag` whose `onDragStart`/`onDrag` call the ported `_handleResizeStart` /
+  `_handleResize`. RTL mirrors the horizontal direction (`globals.ltr`).
+- **`destroy()`** tears down `dragger?.destroy()` + `resizeDragger?.destroy()` before
+  `super.destroy()`.
+- `dragger: DragMove | null`, `resizeDragger: BaseDrag | null` (were `unknown`).
+
+## Deviations from doc 07 (and why)
+
+1. **`getScrollParent` body order.** The doc described starting at the element's
+   nearest scroll parent then checking html/body. The implementation climbs
+   `parentElement` and checks **html/body first** each step (returns `win`), then
+   tests `overflow` auto/scroll/overlay **and** axis-scrollability. Net behavior
+   matches the legacy `setScrollContainer` walk; it is a strict superset of the old
+   private `animation.ts` finder (which only checked `overflowY` + vertical
+   scrollability and didn't normalize html/body), so `scrollContainerToElement`
+   keeps working. The `getScrollParent(target)` single-arg form (no axis) accepts
+   **either** axis — also a superset.
+
+2. **`DragMove.onDrag` calls `super.onDrag()`** (doc §5 Option A). Legacy did not, so
+   legacy `DragMove` never emitted `drag`. Ours does (strictly more capable). The CSS
+   `left/top` write is synchronous; the event emission stays RAF-deferred via super.
+
+3. **Auto-scroll clamp uses `clientHeight`/`clientWidth`** for the element-container
+   case, not legacy `outerHeight()` (doc §4.2 / §9 risk 3). Window case uses
+   `documentElement.scrollHeight/Width - innerHeight/Width` for `scrollMax`.
+   **Validate live** in the playground.
+
+4. **Pointer Events** replace the legacy `mousedown`+document-`mousemove`/`mouseup`
+   and the entire touch-shim path (doc §3). `pointerdown` binds on the handle;
+   `pointermove`/`pointerup`/`pointercancel` bind on `document`. `pointercancel` is
+   treated as `pointerup` (legacy had no equivalent — fixes a possible stuck drag).
+   `_pointerId` is tracked and move/up from a different pointer id are ignored
+   (multi-touch safety). **`touch-action: none`** is required on handles to prevent
+   the browser eating the gesture — Modal sets it on the resize handle; consumers
+   must set it on their own draggable handles (the draggable-container path does not
+   force it, to avoid surprising existing layouts — flagged for the playground).
+
+5. **`_computeEdgeScroll` extracted as a private helper.** Doc §7 recommended
+   factoring the "is the pointer in the edge band, how far" math into a pure-ish
+   function. Done — it returns `{property, axis, dist} | null`; `drag()` consumes it.
+   This is what the auto-scroll-decision tests assert (via the public `scroll*`
+   fields), since the live RAF loop and window scroll aren't reproducible in
+   happy-dom.
+
+6. **`_deinitItem` removes listeners from the resolved handle**, not the item
+   (legacy called `removeAllListeners(item)` but bound on the handle). With native
+   delegation the listener lives on `_getItemHandle(item)`, so we remove from there.
+   For the common `handle: null` case the handle *is* the item, so behavior matches;
+   for a separate handle this is the correct fix.
+
+7. **`getItemDragger(item)` exported** as a small introspection/test helper over the
+   module-level `WeakMap<Element, BaseDrag>` (`dragRegistry`). Not in the doc's API
+   list, but harmless and keeps the WeakMap private while letting tests assert
+   ownership. The `Drag`/`DragSort` ports can use it instead of re-exposing the map.
+
+## happy-dom / testing caveats (for the next engineer)
+
+- **`PointerEvent` exists, but `pageX`/`pageY`/`pointerId` are always `0`** (no
+  geometry). Tests construct a real `PointerEvent` and override those props with
+  `Object.defineProperty` before dispatch (see `firePointer` in `tests/drag.test.ts`).
+- **No layout:** `getBoundingClientRect()` returns zeros, so coordinate-math tests
+  `vi.spyOn(el, 'getBoundingClientRect')` to return a known rect (drives `getOffset`).
+- **RAF hooks:** `tests/drag.test.ts` `vi.mock('../src/utils/animation')` to make
+  `requestAnimationFrame` run its callback synchronously, so the deferred
+  `onDragStart`/`onDrag`/`onDragStop` events are assertable without a real frame.
+- **`element.animate` is `undefined`** in happy-dom — irrelevant to drag, but it's
+  why Modal's fade resolves synchronously in the modal tests.
+
+## Playground-only (NOT unit-tested — needs real layout/pointer)
+
+- End-to-end `DragMove` element following the cursor.
+- Modal `draggable` (drag by handle / container) and `resizable` (symmetric grow/
+  shrink; RTL mirroring) actually moving/resizing.
+- The live auto-scroll RAF loop near container/window edges, including the
+  window-scroll cursor correction (`mouseX/Y -= scrollPos - newScrollPos`) keeping
+  the helper under the cursor (doc §9 risk 4).
+- `touch-action: none` behavior and `pointercancel` cleanup on touch devices.
+- Deeply-nested scroll-container `getScrollParent` edge cases (doc §9 risk 2).
+
+> A `playground/` drag page (free `DragMove` box, draggable+resizable Modal, tall
+> scroll container) was **not** added in this slice — recommended next, so the above
+> can be eyeballed.
+
+## For the `Drag` / `DragSort` port (next engineers)
+
+- `BaseDrag.$items` is now **`Element[]`**, not a jQuery collection. Use array
+  indexing (`this.$items[i]`, `.indexOf`, `.length`), not `.eq()`/`$.inArray`.
+- Reserved-but-unimplemented property names `Drag` will add (do not collide):
+  `targetItemWidth`, `targetItemHeight`, `otherItems`, `draggeeDisplay`, `$draggee`,
+  `helpers`. `onReturnHelpersToDraggees` belongs to `Drag`, not `BaseDrag`.
+- `getOuterWidth`/`getOuterHeight` (`utils/dom.ts`) are the native `.outerWidth()`/
+  `.outerHeight()` replacements `Drag` reads off `$targetItem`.
+- Override `startDragging`/`drag`/`stopDragging` with a real `constructor` + `super`
+  and `super.method()` — there is no `init()`/`this.base()` trampoline.
+- Use `getItemDragger(item)` (or import the pattern) instead of `$.data(item, 'drag')`.
+```
diff --git a/packages/craftcms-garnish/docs/09-drag-dragdrop-design.md b/packages/craftcms-garnish/docs/09-drag-dragdrop-design.md
new file mode 100644
index 00000000000..fdda3e60972
--- /dev/null
+++ b/packages/craftcms-garnish/docs/09-drag-dragdrop-design.md
@@ -0,0 +1,970 @@
+# 09 — `Drag` / `DragDrop` Design (helpers, return-to-source, drop targets)
+
+> **Status:** design contract only. This document specifies the TypeScript surface
+> the implementation engineer should build for the legacy `Drag.js` (~460 LOC) and
+> `DragDrop.js` (~115 LOC) ports. No implementation code is written here.
+>
+> **Scope:** port `Drag` (the "pick up the selected element(s)" layer that creates
+> drag *helpers*, follows the cursor with lag, and animates the helpers back to
+> their source on drop) and `DragDrop` (the "drop target" layer on top of `Drag`)
+> onto the **already-shipped** modern `BaseDrag` (`src/drag/base-drag.ts`, see docs
+> 07/08). `DragSort` is **out of scope** for this slice.
+>
+> **Grounding:** every modern signature below is written against the *real*
+> `BaseDrag` API as implemented in `src/drag/base-drag.ts`, not the doc-07 sketch.
+> Key facts the `Drag` port must build on:
+>
+> - `$items` is `Element[]`, `$targetItem` is `HTMLElement | null` (native, not
+>   jQuery). Use `this.$items[i]` / `.indexOf` / `.length`, never `.eq()` /
+>   `$.inArray`.
+> - `BaseDrag` uses native `class extends` — **no `init()`/`this.base()` trampoline.**
+>   Override with a real `constructor` + `super(...)` and call `super.method()`.
+> - `startDragging` / `drag(didMouseMove)` / `stopDragging` / `onDragStart` /
+>   `onDrag` / `onDragStop` / `allowDragging` are all overridable via super-dispatch.
+> - `onDragStart`/`onDrag`/`onDragStop` already defer their *event emission* inside a
+>   `requestAnimationFrame`. `mouseX/Y`, `mouseDistX/Y`, `mouseOffsetX/Y` are set
+>   **synchronously** in `_handlePointerMove` *before* `drag()`/`onDrag()` run, so
+>   helper-position math reads fresh coordinates.
+> - `getItemDragger(item)` exposes the `WeakMap<Element, BaseDrag>` ownership for
+>   tests; `DragDrop` does not need it.
+> - Reserved (doc 08) property names `Drag` may now claim without collision:
+>   `targetItemWidth`, `targetItemHeight`, `otherItems`, `draggeeDisplay`,
+>   `$draggee`, `helpers`. `onReturnHelpersToDraggees` belongs to `Drag`.
+
+---
+
+## 0. Reuse inventory — what the modern core already provides
+
+Do **not** re-create these; `Drag`/`DragDrop` consume them directly.
+
+| Need | Already exists | Location |
+| --- | --- | --- |
+| Full pointer/drag lifecycle, auto-scroll, items, coords | `BaseDrag` | `src/drag/base-drag.ts` |
+| `outerWidth`/`outerHeight` (border-box) | `getOuterWidth(el)` / `getOuterHeight(el)` | `src/utils/dom.ts` |
+| Page-relative offset (`$.offset()`) | `getOffset(el): {top,left}` | `src/utils/dom.ts` |
+| **Hit-test (page coords, replaces `Garnish.hitTest`)** | `hitTest(x, y, elem)` / `isCursorOver(ev, elem)` | `src/utils/dom.ts` |
+| Copy form-input values src→clone (`Garnish.copyInputValues`) | `copyInputValues($source, $target)` | `src/utils/forms.ts` |
+| `requestAnimationFrame` / `cancelAnimationFrame` | re-exported native | `src/utils/animation.ts` |
+| Reduced-motion gate + preferred duration | `prefersReducedMotion()` / `getUserPreferredAnimationDuration()` | `src/utils/animation.ts` |
+| `FX_DURATION` (200ms) | constant | `src/constants.ts` |
+| `win` / `doc` / `bod` | refs | `src/globals.ts` |
+| `activateEventsMuted`, `ltr`/`rtl` | mutable flags | `src/globals.ts` |
+| Element coercion (`$(x)` → array) | `coerceElements` | `src/utils/dom.ts` |
+| Settings/events/listeners base | `Base` (via `BaseDrag`) | `src/base.ts` |
+
+`hitTest` in modern `utils/dom.ts` already mirrors the legacy `Garnish.hitTest`
+exactly: it adds `scrollX/Y` and uses `getOffset` + `getOuterWidth/Height` to build
+the page-coords bounding box. **No new hit-test code is needed** — `DragDrop` just
+calls `hitTest(this.mouseX!, this.mouseY!, elem)`.
+
+**Gaps that must be filled (new code):**
+
+1. **WAAPI "return helpers to draggees" animation** — the legacy `$helper.velocity({left,top})`
+   tween back to each source's offset, plus a `fadeOutHelpers` path. The modern core
+   has no Velocity; reuse the WAAPI pattern Modal already established (`element.animate`,
+   tracked + cancelable, reduced-motion-gated). See §3.
+2. **Helper/clone creation without jQuery** — `.clone()`, name-stripping, sizing,
+   z-index/opacity styling, and the `settings.helper` wrapper hook. See §2.
+3. **A native `display`/`visibility` show/hide path** to replace jQuery `.hide()` /
+   `.show()` / `.css('visibility', …)`. See §2.4.
+
+---
+
+## 1. `Drag` public contract
+
+`Drag extends BaseDrag<DragSettings>`. It overrides the lifecycle to (a) snapshot
+the target's size and the full draggee set, (b) build helper clones that follow the
+cursor with lag, and (c) animate the helpers home on drop.
+
+### 1.1 Constructor
+
+Legacy `init(items, settings)` with the same param-shift `BaseDrag` already handles.
+**`BaseDrag`'s constructor already implements the param-shift** (`new BaseDrag(settings)`
+when the first arg is a plain object) and already calls `setSettings(settings, defaults)`.
+`Drag` only needs to merge **its own** defaults on top, then delegate:
+
+```ts
+export class Drag<S extends DragSettings = DragSettings> extends BaseDrag<S> {
+  constructor(items?: DragItemsInput | Partial<S> | null, settings?: Partial<S>) {
+    // Re-run the same plain-object param-shift BaseDrag uses, so we can merge
+    // Drag.defaults before super() applies them.
+    let resolvedItems: DragItemsInput | Partial<S> | null = items ?? null;
+    if (settings === undefined && isPlainObject(items)) {
+      settings = items as Partial<S>;
+      resolvedItems = null;
+    }
+    super(
+      resolvedItems as DragItemsInput | null,
+      {...(settings ?? {})} as Partial<S>
+    );
+    // Layer Drag.defaults *under* the caller's overrides without clobbering them.
+    this.setSettings(this.settings as Partial<S>, Drag.defaults as Partial<S>);
+  }
+}
+```
+
+> **Settings-merge note.** `BaseDrag.setSettings(settings, BaseDrag.defaults)` runs
+> inside `super()` and fills `BaseDrag` defaults. `Drag` then calls
+> `setSettings(this.settings, Drag.defaults)` so its own keys get defaults while the
+> already-merged caller overrides + BaseDrag keys survive. (`setSettings` on `Base`
+> merges `defaults` *under* the first arg.) Verify the precedence against
+> `Base.setSettings` during implementation; if precedence is wrong, build the merged
+> object explicitly: `super(items, {...Drag.defaults, ...callerSettings})`. The
+> explicit-merge form is the safer default and is recommended.
+
+### 1.2 Settings (every `Drag` setting + default)
+
+These extend `BaseDragSettings`. Defaults mirror legacy `Drag.defaults`.
+
+```ts
+export interface DragSettings extends BaseDragSettings {
+  /** Which item(s) are actually dragged. `null` → just `$targetItem`. */
+  filter: (() => ElementInput) | string | null;
+  /** Build one helper for the whole draggee set instead of one per draggee. */
+  singleHelper: boolean;
+  /** Collapse multiple draggees into the target (hide the rest). */
+  collapseDraggees: boolean;
+  /** Hide the draggee entirely (display:none) while dragging. */
+  removeDraggee: boolean;
+  /** Hide the draggee via `visibility:hidden` while dragging. */
+  hideDraggee: boolean;
+  /** Copy `<input>`/`<select>`/`<textarea>` values from source into the clone. */
+  copyDraggeeInputValuesToHelper: boolean;
+  /** Helper opacity (1 → no opacity override). */
+  helperOpacity: number;
+  /** Position the helper's top-left at the cursor, not at the grab offset. */
+  moveHelperToCursor: boolean;
+  /**
+   * Optional helper wrapper. A function `(helper, index) => wrappedHelper`, or an
+   * element/markup the clone is appended into. `null` → use the bare clone.
+   */
+  helper:
+    | ((helper: HTMLElement, index: number) => HTMLElement)
+    | ElementInput
+    | null;
+  helperBaseZindex: number;
+  helperLagBase: number;
+  helperLagIncrementDividend: number;
+  helperSpacingX: number;
+  helperSpacingY: number;
+
+  onReturnHelpersToDraggees: () => void;
+}
+
+static readonly defaults: DragSettings = {
+  ...BaseDrag.defaults,
+  filter: null,
+  singleHelper: false,
+  collapseDraggees: false,
+  removeDraggee: false,
+  hideDraggee: true,
+  copyDraggeeInputValuesToHelper: false,
+  helperOpacity: 1,
+  moveHelperToCursor: false,
+  helper: null,
+  helperBaseZindex: 1000,
+  helperLagBase: 3,
+  helperLagIncrementDividend: 1.5,
+  helperSpacingX: 5,
+  helperSpacingY: 5,
+  onReturnHelpersToDraggees: () => {},
+};
+```
+
+### 1.3 Public properties (rename jQuery → native)
+
+Legacy `Drag` exposed jQuery collections; modern keeps the `$`-prefixed names for
+consumer parity but holds native types. **Helpers become `HTMLElement[]`**, not an
+array of jQuery objects.
+
+```ts
+// Snapshot of the target geometry (read by drag()/DragSort)
+targetItemWidth: number | null = null;            // getOuterWidth($targetItem)
+targetItemHeight: number | null = null;           // getOuterHeight($targetItem)
+targetItemPositionInDraggee: number | null = null;
+
+/** The dragged element(s); target item is always index 0. */
+$draggee: HTMLElement[] = [];
+
+/** Items NOT in $draggee (everything else still tracked). */
+otherItems: Element[] = [];
+totalOtherItems: number | null = null;
+
+/** The floating clones following the cursor. (legacy: jQuery[]) */
+helpers: HTMLElement[] = [];
+helperTargets: Array<{left: number; top: number}> = [];
+helperPositions: Array<{left: number; top: number}> = [];
+helperLagIncrement: number | null = null;
+
+/** RAF handle for the lag-follow loop (replaces legacy updateHelperPosFrame). */
+updateHelperPosFrame: number | null = null;
+
+lastMouseX: number | null = null;
+lastMouseY: number | null = null;
+
+/** Set true while the return-to-source animation runs; gates allowDragging(). */
+private _returningHelpersToDraggees = false;
+
+/** Display value snapshotted off the target so we can restore it. */
+draggeeDisplay: string | null = null;
+
+/** Virtual midpoint of the draggee (read by DragSort / consumers). */
+draggeeVirtualMidpointX: number | null = null;
+draggeeVirtualMidpointY: number | null = null;
+```
+
+> Legacy used a bound `updateHelperPosProxy` + a function-property `_i/_j/_lag`
+> micro-optimization (avoiding per-frame closures). In the modern port, use a plain
+> arrow `() => this._updateHelperPos()` (RAF callback) and ordinary local `for`
+> loop variables — the closure cost is negligible and the legacy pattern hurts
+> readability and is untyped.
+
+### 1.4 Public / overridable methods — mapped onto the real `BaseDrag`
+
+```ts
+// --- Lifecycle overrides (call super where noted) -------------------------
+
+/** Block a new drag while helpers are animating home (legacy parity). */
+override allowDragging(): boolean;        // return !this._returningHelpersToDraggees
+
+/**
+ * Snapshot target geometry + display, resolve the draggee set, build helpers,
+ * start the lag-follow loop, then delegate the rest of start-up to BaseDrag.
+ *
+ * IMPORTANT (deviation from legacy): legacy Drag.startDragging *replaced*
+ * BaseDrag.startDragging and re-implemented onBeforeDragStart/dragging/
+ * setScrollContainer/onDragStart/activateEventsMuted inline. The modern
+ * BaseDrag.startDragging already does all of that. So the override does only
+ * the Drag-specific work, then calls super.startDragging() for the rest.
+ */
+override startDragging(): void;
+
+/** Update draggeeVirtualMidpointX/Y from fresh coords, then super.drag(). */
+override drag(didMouseMove: boolean): void;
+
+/** Cancel the lag-follow RAF, then super.stopDragging(). */
+override stopDragging(): void;
+
+// --- Draggee management ---------------------------------------------------
+
+/** Resolve which items are dragged (settings.filter | string | $targetItem). */
+findDraggee(): HTMLElement[];
+
+/** Set $draggee (target first), create helpers, apply hide/collapse styling. */
+setDraggee(draggee: HTMLElement[]): void;
+
+/** Append more draggees mid-drag (create helpers unless collapsed). */
+appendDraggee(newDraggee: HTMLElement[]): void;
+
+// --- Helper geometry ------------------------------------------------------
+
+getHelperTargetX(real?: boolean): number;
+getHelperTargetY(real?: boolean): number;
+
+// --- Return / fade --------------------------------------------------------
+
+/** Animate every helper back to its source's offset, then show + remove. */
+returnHelpersToDraggees(): void;
+
+/** Fade each helper out and remove it (no return tween). */
+fadeOutHelpers(): void;
+
+// --- Hook (event emitter) -------------------------------------------------
+
+/** RAF-deferred: trigger('returnHelpersToDraggees') + settings callback. */
+onReturnHelpersToDraggees(): void;
+```
+
+### 1.5 `startDragging` body — concrete, against the real super
+
+```ts
+override startDragging(): void {
+  // Drag-specific snapshot (BaseDrag.startDragging does NOT do this).
+  this.helpers = [];
+  this.helperTargets = [];
+  this.helperPositions = [];
+  this.lastMouseX = this.lastMouseY = null;
+
+  this.targetItemWidth = getOuterWidth(this.$targetItem!);
+  this.targetItemHeight = getOuterHeight(this.$targetItem!);
+  this.draggeeDisplay = getComputedStyle(this.$targetItem!).display;
+
+  this.setDraggee(this.findDraggee());   // builds helpers
+
+  // Everything not in the draggee set.
+  this.otherItems = this.$items.filter((it) => !this.$draggee.includes(it as HTMLElement));
+  this.totalOtherItems = this.otherItems.length;
+
+  this.helperLagIncrement =
+    this.helpers.length === 1
+      ? 0
+      : this.settings!.helperLagIncrementDividend / (this.helpers.length - 1);
+  this.updateHelperPosFrame = requestAnimationFrame(() => this._updateHelperPos());
+
+  // BaseDrag.startDragging: onBeforeDragStart(), dragging=true,
+  // setScrollContainer(), onDragStart(), activateEventsMuted=true.
+  super.startDragging();
+}
+```
+
+> **Ordering subtlety.** Legacy called `onBeforeDragStart()` *first*, then did the
+> snapshot. The modern `BaseDrag.startDragging` calls `onBeforeDragStart()` itself.
+> Calling `super.startDragging()` *last* means our snapshot runs *before*
+> `onBeforeDragStart` fires — the reverse of legacy. **This matters** only if a
+> consumer's `onBeforeDragStart` callback inspects `$draggee`/`helpers`. Legacy fired
+> `onBeforeDragStart` before helpers existed, so it could *not* see them either —
+> meaning the safe, legacy-equivalent choice is to fire `onBeforeDragStart` before
+> the snapshot. **Recommendation:** call `this.onBeforeDragStart()` explicitly first,
+> do the snapshot, then call the rest of super's work. Since `BaseDrag.startDragging`
+> bundles `onBeforeDragStart` with the rest, the cleanest port is to **not** call
+> `super.startDragging()` and instead replicate its small body inline *minus*
+> `onBeforeDragStart` (which we already called). Document whichever path is chosen;
+> the inline-replication path is the faithful one. Pseudocode:
+>
+> ```ts
+> override startDragging(): void {
+>   this.onBeforeDragStart();              // legacy order: first
+>   // ...Drag snapshot + helper build + lag loop...
+>   this.dragging = true;
+>   this.setScrollContainer();
+>   this.onDragStart();
+>   globals.activateEventsMuted = true;
+> }
+> ```
+>
+> This duplicates ~4 lines of `BaseDrag.startDragging` but preserves the exact
+> legacy hook ordering. Flag the duplication in the impl notes. (If `BaseDrag` later
+> grows a `protected _beginDragging()` that excludes `onBeforeDragStart`, switch to
+> that.)
+
+---
+
+## 2. Helper / clone creation (`_createHelper`)
+
+The legacy `_createHelper(index)` clones a draggee, sizes it, strips form `name`s,
+optionally copies input values, optionally wraps it via `settings.helper`, appends
+to `<body>`, and positions it absolutely with z-index/opacity. Native port:
+
+```ts
+private _createHelper(index: number): void {
+  const draggee = this.$draggee[index];
+  let helper = draggee.cloneNode(true) as HTMLElement;     // .clone() (deep)
+  helper.classList.add('draghelper');
+
+  if (draggee.closest('#content')) helper.classList.add('drag-in-content');
+  if (draggee.closest('.slideout-container'))
+    helper.classList.add('drag-in-slideout');
+
+  if (this.settings!.copyDraggeeInputValuesToHelper) {
+    copyInputValues(draggee, helper);                       // utils/forms.ts
+  }
+
+  // Blank every name= so cloned radios/checkboxes don't hijack form values.
+  helper.querySelectorAll<HTMLElement>('[name]').forEach((el) =>
+    el.setAttribute('name', '')
+  );
+
+  // Size to match source (border-box). Legacy used jQuery .outerWidth(n) which
+  // sets content-box+padding+border; the native equivalent is width/height in
+  // border-box. Set box-sizing:border-box + width/height = ceil(getOuterWidth).
+  helper.style.boxSizing = 'border-box';
+  helper.style.width = `${Math.ceil(getOuterWidth(draggee))}px`;
+  helper.style.height = `${Math.ceil(getOuterHeight(draggee))}px`;
+  helper.style.margin = '0';
+  helper.style.pointerEvents = 'none';
+
+  // Optional wrapper hook.
+  if (this.settings!.helper) {
+    if (typeof this.settings!.helper === 'function') {
+      helper = this.settings!.helper(helper, index);
+    } else {
+      const wrapper = coerceElements(this.settings!.helper)[0] as HTMLElement;
+      wrapper.appendChild(helper);
+      helper = wrapper;
+    }
+  }
+
+  bod.appendChild(helper);
+
+  const pos = this._getHelperTarget(index, true);           // real=true: no cursor snap
+  helper.style.position = 'absolute';
+  helper.style.top = `${pos.top}px`;
+  helper.style.left = `${pos.left}px`;
+  helper.style.zIndex = String(
+    this.settings!.helperBaseZindex + this.$draggee.length - index
+  );
+  helper.style.display = this.draggeeDisplay!;
+  if (this.settings!.helperOpacity !== 1) {
+    helper.style.opacity = String(this.settings!.helperOpacity);
+  }
+
+  this.helperPositions[index] = {top: pos.top, left: pos.left};
+  this.helpers.push(helper);
+}
+```
+
+### 2.1 `_getHelperTarget` / `getHelperTargetX|Y`
+
+```ts
+getHelperTargetX(real = false): number {
+  if (!real && this.settings!.moveHelperToCursor) return this.mouseX!;
+  return this.mouseX! - this.mouseOffsetX!;
+}
+getHelperTargetY(real = false): number {
+  if (!real && this.settings!.moveHelperToCursor) return this.mouseY!;
+  return this.mouseY! - this.mouseOffsetY!;
+}
+
+private _getHelperTarget(index: number, real = false): {left: number; top: number} {
+  return {
+    left: this.getHelperTargetX(real) + this.settings!.helperSpacingX * index,
+    top: this.getHelperTargetY(real) + this.settings!.helperSpacingY * index,
+  };
+}
+```
+
+### 2.2 Lag-follow loop (`_updateHelperPos`)
+
+Each RAF frame: recompute targets when the pointer moved, then ease each helper
+toward its target by `1/lag` (a critically-damped-ish follow). Direct port, native
+`.style` writes:
+
+```ts
+private _updateHelperPos(): void {
+  if (this.mouseX !== this.lastMouseX || this.mouseY !== this.lastMouseY) {
+    for (let i = 0; i < this.helpers.length; i++) {
+      this.helperTargets[i] = this._getHelperTarget(i);     // real=false → may snap to cursor
+    }
+    this.lastMouseX = this.mouseX;
+    this.lastMouseY = this.mouseY;
+  }
+
+  for (let j = 0; j < this.helpers.length; j++) {
+    const lag = this.settings!.helperLagBase + this.helperLagIncrement! * j;
+    const cur = this.helperPositions[j];
+    const tgt = this.helperTargets[j];
+    cur.left += (tgt.left - cur.left) / lag;
+    cur.top += (tgt.top - cur.top) / lag;
+    this.helpers[j].style.left = `${cur.left}px`;
+    this.helpers[j].style.top = `${cur.top}px`;
+  }
+
+  this.updateHelperPosFrame = requestAnimationFrame(() => this._updateHelperPos());
+}
+```
+
+> Cancel it in `stopDragging()` via `cancelAnimationFrame(this.updateHelperPosFrame!)`
+> *before* `super.stopDragging()`.
+
+### 2.3 `setDraggee` / `appendDraggee`
+
+`setDraggee` records the target's index within the draggee set, forces the target to
+index 0, builds helpers, and applies the hide/collapse styling. Native port replaces
+jQuery `.add()`/`.not()`/`.hide()`/`.css('visibility')`:
+
+```ts
+setDraggee(draggee: HTMLElement[]): void {
+  const target = this.$targetItem!;
+  const all = draggee.includes(target) ? draggee : [...draggee, target];
+  this.targetItemPositionInDraggee = all.indexOf(target);
+
+  // Target first, then the rest (dedup target out).
+  this.$draggee = [target, ...all.filter((el) => el !== target)];
+
+  if (this.settings!.singleHelper) {
+    this._createHelper(0);
+  } else {
+    for (let i = 0; i < this.$draggee.length; i++) this._createHelper(i);
+  }
+
+  if (this.settings!.removeDraggee) {
+    this.$draggee.forEach((el) => this._hide(el));
+  } else if (this.settings!.collapseDraggees) {
+    target.style.visibility = 'hidden';
+    this.$draggee.filter((el) => el !== target).forEach((el) => this._hide(el));
+  } else if (this.settings!.hideDraggee) {
+    this.$draggee.forEach((el) => (el.style.visibility = 'hidden'));
+  }
+}
+```
+
+`appendDraggee` follows the same structure (see legacy lines 154–179): early-return
+on empty, snapshot `oldLength` unless collapsing, concat, create helpers for the new
+indices unless collapsing, then hide the new draggees per the same three settings.
+
+### 2.4 Native show/hide helpers
+
+Replace jQuery `.hide()`/`.show()` (which save/restore the inline `display`):
+
+```ts
+/** jQuery .hide() — stash current display, set display:none. */
+private _hide(el: HTMLElement): void {
+  if (el.style.display !== 'none') {
+    el.dataset.garnishOldDisplay = el.style.display;   // '' if none was inline
+  }
+  el.style.display = 'none';
+}
+
+/** jQuery .show() — restore the stashed inline display (or clear it). */
+private _show(el: HTMLElement): void {
+  el.style.display = el.dataset.garnishOldDisplay ?? '';
+  delete el.dataset.garnishOldDisplay;
+}
+```
+
+> `Drag` mostly toggles `visibility`, not `display`, for the draggees; `display:none`
+> is only used in the `removeDraggee`/`collapseDraggees`-of-others paths. The
+> `draggeeDisplay` snapshot (computed `display` of the target at drag start) is what
+> gets re-applied to helpers and restored to draggees on return — keep that distinct
+> from the `_hide`/`_show` inline-display stash.
+
+---
+
+## 3. Return-to-source animation (WAAPI, replaces Velocity)
+
+This is the only genuinely new machinery. Legacy used
+`$helper.velocity({left, top}, FX_DURATION, callback)` to tween each helper back to
+its source draggee's offset, then `_showDraggee` removed the helpers and restored the
+draggees. The modern core has no Velocity; **reuse the WAAPI pattern `Modal` already
+uses** (`element.animate(...)`, tracked `Animation`, cancelable, reduced-motion gated,
+`element.animate` may be absent in happy-dom).
+
+### 3.1 `returnHelpersToDraggees`
+
+```ts
+returnHelpersToDraggees(): void {
+  this._returningHelpersToDraggees = true;   // gates allowDragging()
+
+  let pending = this.helpers.length;
+  if (pending === 0) {
+    this._showDraggee();
+    return;
+  }
+
+  this.helpers.forEach((helper, i) => {
+    const draggee = this.$draggee[i];
+
+    // Restore the draggee's display now (it animates in *under* the helper).
+    if (draggee) {
+      draggee.style.display = this.draggeeDisplay!;
+      draggee.style.visibility = this.settings!.hideDraggee ? 'hidden' : '';
+    }
+
+    const targetOffset = draggee ? getOffset(draggee) : {left: 0, top: 0};
+
+    const finalize = () => {
+      // Snap to final, then let _showDraggee remove all helpers at once.
+      helper.style.left = `${targetOffset.left}px`;
+      helper.style.top = `${targetOffset.top}px`;
+      if (--pending === 0) this._showDraggee();
+    };
+
+    // Reduced-motion or no WAAPI → jump straight home.
+    if (prefersReducedMotion() || typeof helper.animate !== 'function') {
+      finalize();
+      return;
+    }
+
+    const fromLeft = parseFloat(helper.style.left) || getOffset(helper).left;
+    const fromTop = parseFloat(helper.style.top) || getOffset(helper).top;
+
+    const anim = helper.animate(
+      [
+        {left: `${fromLeft}px`, top: `${fromTop}px`},
+        {left: `${targetOffset.left}px`, top: `${targetOffset.top}px`},
+      ],
+      {duration: getUserPreferredAnimationDuration(FX_DURATION), fill: 'forwards'}
+    );
+    this._returnAnimations.push(anim);
+    anim.addEventListener('finish', finalize, {once: true});
+    anim.addEventListener('cancel', finalize, {once: true});
+  });
+}
+```
+
+> **WAAPI `left`/`top` caveat.** `element.animate` does not interpolate `left`/`top`
+> as smoothly as `transform: translate()` and forces layout each frame. Legacy
+> Velocity animated `left`/`top` too, so visual parity is preserved by using them —
+> but the impl engineer **may** instead animate `transform: translate(dx, dy)` from
+> the current to the target delta and commit the final `left`/`top` on finish (better
+> perf, identical end state). Recommend `transform` and note the deviation; either is
+> acceptable. Whichever is chosen, the **end state must set `left`/`top`** to the
+> source offset so `_showDraggee` can remove the helper without a flash.
+
+> **`getUserPreferredAnimationDuration(FX_DURATION)`** is the modern equivalent of
+> the legacy fixed `FX_DURATION` — it already returns `0` under reduced-motion, so
+> the explicit `prefersReducedMotion()` short-circuit above is belt-and-suspenders
+> (matches how `modal.ts::_fade` is written). Keep both for clarity.
+
+### 3.2 `_showDraggee` (completion)
+
+```ts
+private _showDraggee(): void {
+  for (const helper of this.helpers) helper.remove();
+  this.helpers = [];
+  this._returnAnimations = [];
+
+  // jQuery .show().css('visibility','') → restore display + clear visibility.
+  this.$draggee.forEach((el) => {
+    this._show(el);
+    el.style.visibility = '';
+  });
+
+  this.onReturnHelpersToDraggees();
+  this._returningHelpersToDraggees = false;
+}
+```
+
+> Legacy only ran the `_showDraggee` completion off the **first** helper's tween
+> callback (`i === 0`), assuming all tweens share the same duration and finish
+> together. The port above is more robust: it counts down `pending` so completion
+> fires after the **last** helper lands (or immediately under reduced motion). This
+> is a deliberate, safe improvement — note it in the impl notes.
+
+### 3.3 `fadeOutHelpers`
+
+```ts
+fadeOutHelpers(): void {
+  this.helpers.forEach((helper) => {
+    if (prefersReducedMotion() || typeof helper.animate !== 'function') {
+      helper.remove();
+      return;
+    }
+    const anim = helper.animate([{opacity: 1}, {opacity: 0}], {
+      duration: getUserPreferredAnimationDuration(FX_DURATION),
+      fill: 'forwards',
+    });
+    anim.addEventListener('finish', () => helper.remove(), {once: true});
+    anim.addEventListener('cancel', () => helper.remove(), {once: true});
+  });
+}
+```
+
+### 3.4 `onReturnHelpersToDraggees` + animation tracking
+
+```ts
+/** RAF-deferred event hook (legacy parity). */
+onReturnHelpersToDraggees(): void {
+  requestAnimationFrame(() => {
+    this.trigger('returnHelpersToDraggees');
+    this.settings!.onReturnHelpersToDraggees();
+  });
+}
+
+/** Tracked return animations so destroy()/a new drag can cancel mid-flight. */
+private _returnAnimations: Animation[] = [];
+
+override destroy(): void {
+  if (this.updateHelperPosFrame) cancelAnimationFrame(this.updateHelperPosFrame);
+  this._returnAnimations.forEach((a) => a.cancel());
+  this.helpers.forEach((h) => h.remove());
+  super.destroy();   // BaseDrag.destroy → removeAllItems() + Base teardown
+}
+```
+
+---
+
+## 4. jQuery removals — `Drag.js` + `DragDrop.js`
+
+| # | Legacy | Native replacement |
+| --- | --- | --- |
+| 1 | `$.extend({}, Drag.defaults, settings)` | `setSettings` / explicit `{...Drag.defaults, ...settings}` |
+| 2 | `$.isPlainObject(items)` param-shift | local `isPlainObject()` (same as `base-drag.ts`) |
+| 3 | `this.$targetItem.outerWidth()/outerHeight()` | `getOuterWidth/Height($targetItem)` (`utils/dom.ts`) |
+| 4 | `this.$targetItem.css('display')` | `getComputedStyle($targetItem).display` |
+| 5 | `$.inArray(item, this.$draggee)` / `$.inArray(target, …)` | `array.indexOf(item)` / `.includes(item)` |
+| 6 | `$([target].concat($draggee.not(target).toArray()))` | `[target, ...draggee.filter(el => el !== target)]` |
+| 7 | `$draggee.hide()` / `.show()` | `_hide(el)` / `_show(el)` (§2.4) |
+| 8 | `.css('visibility', 'hidden' \| '')` | `el.style.visibility = …` |
+| 9 | `$draggee.clone()` | `draggee.cloneNode(true) as HTMLElement` |
+| 10 | `$draggee.parents('#content').length` | `draggee.closest('#content')` (truthy) |
+| 11 | `Garnish.copyInputValues($d, $h)` | `copyInputValues(draggee, helper)` (`utils/forms.ts`) |
+| 12 | `$helper.find('[name]').attr('name','')` | `helper.querySelectorAll('[name]').forEach(el => el.setAttribute('name',''))` |
+| 13 | `$helper.outerWidth(n).outerHeight(n).css(…)` | `style.boxSizing='border-box'` + `style.width/height` + `style.*` |
+| 14 | `$(this.settings.helper).append($helper)` | `coerceElements(helper)[0].appendChild(clone)` |
+| 15 | `$helper.appendTo(Garnish.$bod)` | `bod.appendChild(helper)` |
+| 16 | `$helper.css({position, top, left, zIndex, display})` | discrete `helper.style.*` writes |
+| 17 | `this.$draggee.eq(i)` | `this.$draggee[i]` |
+| 18 | `$draggee.offset()` (return target) | `getOffset(draggee)` (`utils/dom.ts`) |
+| 19 | `$helper.velocity({left,top}, FX_DURATION, cb)` | `helper.animate([...], {...})` + `finish`/`cancel` (§3) |
+| 20 | `$draggeeHelper.velocity('fadeOut', {…})` | `helper.animate([{opacity:1},{opacity:0}], …)` (§3.3) |
+| 21 | `Garnish.requestAnimationFrame/cancelAnimationFrame` | `requestAnimationFrame`/`cancelAnimationFrame` (`utils/animation.ts`) |
+| 22 | `Garnish.activateEventsMuted = true` | handled by `super.startDragging()` (or `globals.activateEventsMuted`) |
+| 23 | `$.noop` | `() => {}` |
+| **DragDrop** | | |
+| 24 | `$(this.settings.dropTargets)` / `$(fn())` | `coerceElements(...)` → `Element[]`; `null` if empty |
+| 25 | `Garnish.hitTest(mouseX, mouseY, elem)` | `hitTest(this.mouseX!, this.mouseY!, elem)` (`utils/dom.ts`) |
+| 26 | `this.$dropTargets[i]` loop | `for (const el of this.$dropTargets)` |
+| 27 | `$activeDropTarget.addClass/removeClass(cls)` | `el.classList.add/remove(cls)` |
+| 28 | `this.$activeDropTarget[0]` identity compare | compare `Element` refs directly (no `[0]`) |
+| 29 | `$(elem).addClass(cls)` then store | `el.classList.add(cls)`; store the raw `Element` |
+
+---
+
+## 5. `DragDrop` public contract
+
+`DragDrop extends Drag<DragDropSettings>`. It adds drop targets and active-target
+tracking. Because hit-testing is already provided by `hitTest`, this layer is thin.
+
+### 5.1 Settings
+
+```ts
+export interface DragDropSettings extends DragSettings {
+  /** Drop-target element(s), a selector, or a resolver function. */
+  dropTargets: ElementInput | (() => ElementInput) | null;
+  /** Called whenever the active drop target changes (with the new one or null). */
+  onDropTargetChange: (activeDropTarget: HTMLElement | null) => void;
+  /** Class toggled on the active drop target. */
+  activeDropTargetClass: string;
+}
+
+static readonly defaults: DragDropSettings = {
+  ...Drag.defaults,
+  dropTargets: null,
+  onDropTargetChange: () => {},
+  activeDropTargetClass: 'active',
+};
+```
+
+### 5.2 Properties (native rename)
+
+```ts
+/** Resolved drop targets, or null when none. (legacy: jQuery | null) */
+$dropTargets: HTMLElement[] | null = null;
+
+/** The element the cursor is currently over, or null. (legacy: jQuery | null) */
+$activeDropTarget: HTMLElement | null = null;
+```
+
+> **Rename note:** legacy `$activeDropTarget` was a jQuery object and consumers read
+> `this.$activeDropTarget[0]`. Modern holds a single `HTMLElement | null` directly —
+> consumers must drop the `[0]`. Flag this for the compat layer.
+
+### 5.3 Methods (mapped onto the real super-dispatch)
+
+```ts
+constructor(settings?: Partial<DragDropSettings>) {
+  super(null, {...DragDrop.defaults, ...(settings ?? {})});
+  // DragDrop's legacy init only takes (settings); items come via addItems later.
+}
+
+/** Resolve settings.dropTargets → HTMLElement[] | null (null if empty). */
+updateDropTargets(): void {
+  const dt = this.settings!.dropTargets;
+  if (!dt) { this.$dropTargets = null; return; }
+  const resolved = (typeof dt === 'function'
+    ? coerceElements(dt())
+    : coerceElements(dt)
+  ).filter((el): el is HTMLElement => el instanceof HTMLElement);
+  this.$dropTargets = resolved.length ? resolved : null;
+}
+
+override onDragStart(): void {
+  this.updateDropTargets();
+  this.$activeDropTarget = null;
+  super.onDragStart();
+}
+
+override onDrag(): void {
+  if (this.$dropTargets) {
+    let active: HTMLElement | null = null;
+    for (const el of this.$dropTargets) {
+      if (hitTest(this.mouseX!, this.mouseY!, el)) { active = el; break; }
+    }
+
+    // Did the active target change?
+    if (active !== this.$activeDropTarget) {
+      if (this.$activeDropTarget) {
+        this.$activeDropTarget.classList.remove(this.settings!.activeDropTargetClass);
+      }
+      this.$activeDropTarget = active;
+      if (active) active.classList.add(this.settings!.activeDropTargetClass);
+      this.settings!.onDropTargetChange(this.$activeDropTarget);
+    }
+  }
+  super.onDrag();   // Drag.onDrag → BaseDrag.onDrag (RAF event emit)
+}
+
+override onDragStop(): void {
+  if (this.$dropTargets && this.$activeDropTarget) {
+    this.$activeDropTarget.classList.remove(this.settings!.activeDropTargetClass);
+  }
+  super.onDragStop();
+}
+```
+
+### 5.4 Hit-detection contract
+
+- **Coordinate space:** `this.mouseX/mouseY` are **page coords** (set from
+  `ev.pageX/pageY` in `BaseDrag._handlePointerMove`). `hitTest(x, y, elem)` in
+  `utils/dom.ts` also works in page coords (it adds `scrollX/Y` to the element's
+  `getBoundingClientRect`). So the spaces match — pass `mouseX/mouseY` straight in.
+- **First-match wins:** like legacy, iterate `$dropTargets` in order and `break` on
+  the first hit. Overlapping targets resolve to the earliest in the list.
+- **Change detection:** identity comparison of `Element` refs (no `[0]` unwrap).
+  `onDropTargetChange` fires only on a *change*, including target→null and
+  null→target transitions.
+- **Cleanup:** `onDragStop` strips the active class. There is no separate "drop"
+  event in legacy `DragDrop` — the consumer reads `$activeDropTarget` inside its own
+  `dragStop`/`onDragStop` handler to perform the drop. Preserve that contract (do
+  **not** invent an `onDrop` here).
+
+> `Drag.onDrag` (the immediate super) does **not** override `BaseDrag.onDrag` in
+> legacy — only `DragDrop` does. So `DragDrop.onDrag`'s `super.onDrag()` resolves to
+> `BaseDrag.onDrag` (RAF-deferred trigger). Confirm the modern `Drag` does **not**
+> add its own `onDrag` override (it shouldn't — `Drag`'s per-frame work is in
+> `_updateHelperPos`, not `onDrag`), so the chain stays `DragDrop → BaseDrag`.
+
+---
+
+## 6. File layout & exports
+
+```
+src/
+  drag/
+    base-drag.ts     # EXISTS — BaseDrag (docs 07/08)
+    drag.ts          # NEW — class Drag extends BaseDrag + DragSettings
+    drag-drop.ts     # NEW — class DragDrop extends Drag + DragDropSettings
+  drag-move.ts       # EXISTS — DragMove
+```
+
+- **`src/drag/drag.ts`** exports `Drag` (default + named), `DragSettings`, and the
+  reserved-name types. **`src/drag/drag-drop.ts`** exports `DragDrop` (default +
+  named) and `DragDropSettings`.
+- **`src/index.ts` named exports:** add `Drag`, `DragSettings`, `DragDrop`,
+  `DragDropSettings` alongside the existing `BaseDrag`/`DragMove` exports.
+- **`Garnish` namespace object** (lower half of `index.ts`): add `Drag` and
+  `DragDrop` so `new Garnish.Drag(...)` / `new Garnish.DragDrop(...)` resolve — this
+  is what legacy `DragDrop.js` (`Garnish.DragDrop.defaults`) and downstream plugins
+  call, and what the compat layer relies on. Mirror how `BaseDrag`/`DragMove` were
+  added in doc 08.
+- **No new utils.** Everything `Drag`/`DragDrop` need (`getOuterWidth/Height`,
+  `getOffset`, `hitTest`, `copyInputValues`, `coerceElements`,
+  `requestAnimationFrame`, `prefersReducedMotion`,
+  `getUserPreferredAnimationDuration`) already exists and is barrel-exported.
+- **`isPlainObject`:** `base-drag.ts` keeps this private. Either re-export it from a
+  shared `utils/misc.ts` for `drag.ts` to reuse, or duplicate the tiny helper. The
+  doc-08 impl left it module-private in `base-drag.ts`; **recommend** promoting it to
+  `utils/misc.ts` and having `base-drag.ts` import it, so `drag.ts` shares one copy.
+
+---
+
+## 7. Testing strategy (happy-dom — no layout, no real pointer)
+
+Mirror the doc-07/08 split. happy-dom returns `0` for geometry and **`element.animate`
+is `undefined`** (so the reduced-motion / no-WAAPI fallback path is the one exercised
+in tests — which is convenient: return-to-source resolves synchronously).
+
+**Unit-testable (Vitest):**
+
+- **Settings/defaults merge** — `Drag.defaults` and `DragDropSettings` defaults
+  applied; param-shift (`new Drag(settingsObj)`); confirm BaseDrag keys survive.
+- **`findDraggee`** — `filter` as function, as selector string (filter `$items`),
+  and `null` (→ `[$targetItem]`).
+- **`setDraggee`** — target forced to index 0; `targetItemPositionInDraggee`
+  computed; `_createHelper` called once (`singleHelper`) vs per-draggee; the three
+  hide/collapse styling branches (`removeDraggee`/`collapseDraggees`/`hideDraggee`)
+  set the right `display`/`visibility`. Spy on `_createHelper`.
+- **`_createHelper`** — clone gets `draghelper` class; `[name]` attrs blanked;
+  `copyInputValues` invoked when `copyDraggeeInputValuesToHelper`; z-index/opacity/
+  position styles; `settings.helper` function-wrapper and element-wrapper paths;
+  appended to `bod`. (Mock `getOuterWidth/Height` since happy-dom returns 0.)
+- **`getHelperTargetX/Y` + `_getHelperTarget`** — `real` flag, `moveHelperToCursor`,
+  per-index spacing. Set `mouseX/Y` + `mouseOffsetX/Y` directly.
+- **`_updateHelperPos`** — set `helperPositions`/`helperTargets`/`helperLagIncrement`
+  + `mouseX/Y`, run one frame (stub RAF synchronous), assert eased `style.left/top`
+  and that targets recompute only when the mouse moved.
+- **`startDragging`/`stopDragging` ordering** — spy on `onBeforeDragStart`,
+  `setDraggee`, `super.startDragging` (or the inlined body), and the lag-RAF
+  start/cancel. Assert `otherItems`/`totalOtherItems`. Assert `stopDragging` cancels
+  `updateHelperPosFrame` before super.
+- **`drag`** — `draggeeVirtualMidpointX/Y` computed from `mouseX - mouseOffsetX +
+  targetItemWidth/2` before `super.drag`.
+- **`returnHelpersToDraggees` / `_showDraggee` (reduced-motion path)** — since
+  `element.animate` is undefined, the `finalize()` path runs sync: draggees restored
+  (`display`/`visibility`), helpers removed, `_returningHelpersToDraggees` toggled
+  true→false, `onReturnHelpersToDraggees` event fired (stub RAF). Also test the
+  `helpers.length === 0` early `_showDraggee`. Mock `prefersReducedMotion`→`true`
+  to test the explicit short-circuit too.
+- **`fadeOutHelpers`** — reduced-motion path removes helpers immediately.
+- **`allowDragging`** — `false` while `_returningHelpersToDraggees`, else `true`.
+- **`destroy`** — cancels lag RAF, cancels tracked return anims (push a fake
+  `{cancel: vi.fn()}` into `_returnAnimations`), removes helpers, calls super.
+- **DragDrop `updateDropTargets`** — element list, selector, resolver fn, and the
+  empty→`null` collapse.
+- **DragDrop `onDrag` hit-detection** — mock `hitTest` to return true for a chosen
+  element; assert first-match `break`, class add/remove on change, `onDropTargetChange`
+  fires only on change (target↔null↔target transitions), identity compare (no `[0]`).
+- **DragDrop `onDragStop`** — strips active class when a target is active.
+
+**Manual (Vite playground) only — needs real layout/pointer/animation:**
+
+- Helpers actually cloning, sizing to source, and lag-following the cursor (incl.
+  multi-helper spacing/lag and `singleHelper`).
+- `moveHelperToCursor`, `helperOpacity`, custom `settings.helper` wrapper visuals.
+- **Return-to-source WAAPI tween** landing exactly on each draggee's offset with no
+  flash before removal (the path happy-dom can't run); `fadeOutHelpers`.
+- Reduced-motion: helpers jump home instead of tweening.
+- DragDrop active-target highlighting while dragging over real, laid-out targets;
+  overlap/first-match resolution; auto-scroll + drop-target interplay.
+- `copyDraggeeInputValuesToHelper` preserving real input/radio/checkbox state.
+
+> Recommend extending the (still-unbuilt) drag playground page from doc 08 with: a
+> multi-item `Drag` with helpers + return animation, and a `DragDrop` with several
+> drop targets.
+
+---
+
+## 8. Hard-to-reproduce legacy behavior / risks
+
+1. **WAAPI `left`/`top` vs `transform` (§3.1).** Velocity tweened `left`/`top`;
+   WAAPI can too but it's layout-thrashy. If the impl switches to `transform` for
+   perf, the **end state must commit `left`/`top`** so `_showDraggee` removes helpers
+   without a flash. **Risk: medium** — validate the landing is pixel-exact in the
+   playground.
+
+2. **Completion fires on last helper, not first (§3.2).** Legacy keyed `_showDraggee`
+   off helper 0's callback. The port counts pending tweens. Equivalent when durations
+   match (they do), more robust otherwise. **Risk: low** — but if a custom
+   `settings.helper` wrapper changes a helper's animation, the countdown is the safer
+   model.
+
+3. **`startDragging` hook ordering (§1.5).** Legacy fires `onBeforeDragStart` *before*
+   building helpers; the naive `super.startDragging()`-last port reverses it. Use the
+   inline-replication path (call `onBeforeDragStart` first) to preserve order.
+   **Risk: medium** if any consumer's `onBeforeDragStart` mutates the DOM that helper
+   cloning then snapshots.
+
+4. **`outerWidth(n)` border-box semantics (§2).** jQuery `.outerWidth(n)` *sets* the
+   total box; the native equivalent needs `box-sizing: border-box` + `width`. If the
+   cloned element has a different `box-sizing` than the source, sizing could drift.
+   **Risk: low–medium** — eyeball helper size vs. source in the playground.
+
+5. **`name=""` blanking on clones (§2).** Required so cloned radios/checkboxes don't
+   steal posted values from the originals. `querySelectorAll('[name]')` must run on
+   the *clone* before it's appended. **Risk: low** but security/data-relevant — keep
+   the test that asserts every `[name]` is blanked.
+
+6. **`copyInputValues` clone alignment.** The modern `copyInputValues(source, target)`
+   must walk source/clone inputs in the same order the legacy jQuery version did
+   (index-aligned). Verify the `utils/forms.ts` implementation matches before relying
+   on it for `copyDraggeeInputValuesToHelper`. **Risk: low** (it's already a ported,
+   tested util) — but add a focused test.
+
+7. **`$activeDropTarget` shape change (jQuery → `HTMLElement`).** Consumers reading
+   `this.$activeDropTarget[0]` break. The compat layer should expose a jQuery-wrapped
+   accessor if any external plugin needs it; core/Vue consumers use the raw element.
+   **Risk: medium** for external plugins; flag in the compat layer.
+
+8. **`$items`/`$draggee` as `Element[]`.** Same caveat as doc 08 §risk 7 — no `.eq()`,
+   `.length` on a real array is fine, `$.inArray` → `.indexOf`/`.includes`. **Risk:
+   low** within this port (we control it); relevant for `DragSort` next.
+
+9. **`getUserPreferredAnimationDuration` returning 0.** Under reduced motion the
+   duration is 0; the WAAPI animation still fires `finish` synchronously-ish. The
+   explicit `prefersReducedMotion()` short-circuit avoids relying on a 0-duration
+   animation firing — keep both paths. **Risk: low.**
+
+10. **Lag-follow loop lifetime.** The `_updateHelperPos` RAF must be canceled in
+    `stopDragging` **and** `destroy`; a leaked loop keeps writing styles to removed
+    helpers. **Risk: low** but a classic leak — covered by the destroy/stop tests.
diff --git a/packages/craftcms-garnish/docs/10-drag-dragdrop-impl-notes.md b/packages/craftcms-garnish/docs/10-drag-dragdrop-impl-notes.md
new file mode 100644
index 00000000000..30f7fa72d04
--- /dev/null
+++ b/packages/craftcms-garnish/docs/10-drag-dragdrop-impl-notes.md
@@ -0,0 +1,216 @@
+# 10 — `Drag` / `DragDrop` Implementation Notes
+
+> Status: **Implemented.** Built against `09-drag-dragdrop-design.md` on top of the
+> shipped `BaseDrag` (docs 07/08). All gates green in the worktree:
+> `check:types`, `check:format`, `test` (**215 tests**, was 162 — +53), `build`.
+> `dist/index.js` jQuery references: **0** (`grep -ciE "jquery|\$\(" dist/index.js`).
+
+## What shipped
+
+| File | Change |
+| --- | --- |
+| `src/utils/misc.ts` | **Promoted** `isPlainObject(val)` here (was module-private in `base-drag.ts`). Single shared copy; barrel-exported from `utils/index.ts`. |
+| `src/drag/base-drag.ts` | Now imports `isPlainObject` from `utils/misc` (deleted its local copy). No behavior change. |
+| `src/drag/drag.ts` | **NEW.** `class Drag extends BaseDrag` — helpers/clones, lag-follow loop, WAAPI return-to-source / fade. |
+| `src/drag/drag-drop.ts` | **NEW.** `class DragDrop extends Drag` — drop targets + hit-detection. |
+| `src/index.ts` | Named exports `Drag`, `DragSettings`, `DragDrop`, `DragDropSettings`; added `Drag`/`DragDrop` to the `Garnish` namespace object. |
+| `tests/drag-drop.test.ts` | **NEW.** 53 tests covering `Drag` + `DragDrop`. |
+
+## Exact exported public API
+
+### `src/drag/drag.ts`
+
+```ts
+export type DragHelper =
+  | ((helper: HTMLElement, index: number) => HTMLElement)
+  | ElementInput
+  | null;
+
+export interface DragSettings extends BaseDragSettings {
+  filter: (() => ElementInput) | string | null;
+  singleHelper: boolean;
+  collapseDraggees: boolean;
+  removeDraggee: boolean;
+  hideDraggee: boolean;
+  copyDraggeeInputValuesToHelper: boolean;
+  helperOpacity: number;
+  moveHelperToCursor: boolean;
+  helper: DragHelper;
+  helperBaseZindex: number;
+  helperLagBase: number;
+  helperLagIncrementDividend: number;
+  helperSpacingX: number;
+  helperSpacingY: number;
+  onReturnHelpersToDraggees: () => void;
+}
+
+export class Drag<S extends DragSettings = DragSettings> extends BaseDrag<S> {
+  static override readonly defaults: DragSettings;
+
+  // public properties
+  targetItemWidth / targetItemHeight / targetItemPositionInDraggee: number | null;
+  $draggee: HTMLElement[];
+  otherItems: Element[];
+  totalOtherItems: number | null;
+  helpers: HTMLElement[];
+  helperTargets / helperPositions: Array<{left: number; top: number}>;
+  helperLagIncrement: number | null;
+  updateHelperPosFrame: number | null;
+  lastMouseX / lastMouseY: number | null;
+  draggeeDisplay: string | null;
+  draggeeVirtualMidpointX / draggeeVirtualMidpointY: number | null;
+
+  constructor(items?: DragItemsInput | Partial<S> | null, settings?: Partial<S>);
+
+  override allowDragging(): boolean;     // !_returningHelpersToDraggees
+  override startDragging(): void;
+  override drag(didMouseMove: boolean): void;
+  override stopDragging(): void;
+  override destroy(): void;
+
+  findDraggee(): HTMLElement[];
+  setDraggee(draggee: HTMLElement[]): void;
+  appendDraggee(newDraggee: HTMLElement[]): void;
+  getHelperTargetX(real?: boolean): number;
+  getHelperTargetY(real?: boolean): number;
+  returnHelpersToDraggees(): void;
+  fadeOutHelpers(): void;
+  onReturnHelpersToDraggees(): void;     // RAF-deferred
+}
+export default Drag;
+```
+
+Private: `_createHelper`, `_getHelperTarget`, `_updateHelperPos`, `_showDraggee`,
+`_hide`, `_show`. Event triggered: `returnHelpersToDraggees` (+ inherited drag events).
+
+### `src/drag/drag-drop.ts`
+
+```ts
+export interface DragDropSettings extends DragSettings {
+  dropTargets: ElementInput | (() => ElementInput) | null;
+  onDropTargetChange: (activeDropTarget: HTMLElement | null) => void;
+  activeDropTargetClass: string;
+}
+
+export class DragDrop<S extends DragDropSettings = DragDropSettings> extends Drag<S> {
+  static override readonly defaults: DragDropSettings;
+
+  $dropTargets: HTMLElement[] | null;     // null when none
+  $activeDropTarget: HTMLElement | null;  // RAW element, NOT jQuery (see deviation 4)
+
+  constructor(settings?: Partial<S>);      // (settings) only — no positional items
+  updateDropTargets(): void;
+  override onDragStart(): void;
+  override onDrag(): void;
+  override onDragStop(): void;
+}
+export default DragDrop;
+```
+
+No `drop` / `onDrop` event — consumers read `$activeDropTarget` inside their own
+`dragStop`/`onDragStop` handler (legacy contract preserved).
+
+### `src/utils/misc.ts` (addition)
+
+```ts
+export function isPlainObject(val: unknown): val is Record<string, unknown>;
+```
+
+## Deviations from doc 09 (and why)
+
+1. **`startDragging` hook ordering — inline-replication path (doc §1.5, risk 3).**
+   We call `this.onBeforeDragStart()` **first**, then snapshot + build helpers +
+   start the lag loop, then inline the tail of `BaseDrag.startDragging`
+   (`dragging = true; setScrollContainer(); onDragStart(); globals.activateEventsMuted = true`)
+   instead of calling `super.startDragging()`. This preserves the legacy order
+   (onBeforeDragStart fires before helpers exist) and duplicates ~4 lines of super.
+   If `BaseDrag` later grows a `protected _beginDragging()` excluding
+   `onBeforeDragStart`, switch to it.
+
+2. **Constructor merge — explicit form (doc §1.1, recommended).**
+   `super(resolvedItems, {...Drag.defaults, ...callerSettings})`. Since
+   `Drag.defaults` already spreads `BaseDrag.defaults`, and `BaseDrag`'s
+   constructor then re-layers `BaseDrag.defaults` *under* that via `setSettings`
+   (`{...base, ...defaults, ...settings}`), every key resolves correctly with
+   caller overrides winning. Verified via the settings/defaults tests.
+   `DragDrop`'s constructor takes `(settings)` only (legacy `init(settings)`) and
+   merges `{...DragDrop.defaults, ...settings}`.
+
+3. **Return-to-source uses WAAPI on `left`/`top` (doc §3.1).** Mirrors
+   `Modal._fade`: tracked in `_returnAnimations`, cancelable, reduced-motion
+   gated, and feature-detected (`typeof helper.animate !== 'function'`). I kept
+   `left`/`top` interpolation (Velocity parity) rather than switching to
+   `transform` — simpler and the end state commits `left`/`top` either way. The
+   `transform` perf optimization remains available as a future change; **validate
+   landing pixel-exactness in the playground** if switched.
+
+4. **Completion fires on the LAST helper (doc §3.2).** `returnHelpersToDraggees`
+   counts a `pending` countdown and calls `_showDraggee` when it hits 0 (or
+   immediately on the no-WAAPI / reduced-motion path), rather than keying off
+   helper 0's callback like legacy. Safe improvement; equivalent when durations
+   match.
+
+5. **`$activeDropTarget` is a raw `HTMLElement | null`** (doc §5.2), not a jQuery
+   object. **Consumers that read `this.$activeDropTarget[0]` break** — they must
+   use the element directly. `onDropTargetChange` is also called with the raw
+   element (or `null`). Flag for the compat layer if any external plugin needs the
+   jQuery-wrapped form.
+
+6. **`isPlainObject` promoted to `utils/misc.ts`** (doc §6 recommendation).
+   `base-drag.ts` and `drag.ts` share one copy; also barrel-exported.
+
+7. **No `_muteActivateEvents` indirection** — `startDragging` sets
+   `globals.activateEventsMuted = true` inline, identical to `BaseDrag`.
+
+## happy-dom / testing caveats (for the next engineer)
+
+- **`element.animate` is `undefined`** → `returnHelpersToDraggees` / `fadeOutHelpers`
+  take the no-WAAPI fallback and resolve **synchronously**. That's the only path
+  unit-tested; the real WAAPI tweens are playground-only. One test injects a fake
+  `helper.animate` returning a never-finishing animation to assert the
+  `_returningHelpersToDraggees` gate (`allowDragging()` → false mid-flight).
+- **The lag-follow loop (`_updateHelperPos`) re-schedules itself every RAF.** The
+  `drag-drop.test.ts` animation mock therefore pushes RAF callbacks onto a manual
+  `rafQueue` (flushed explicitly via `flushRaf()`) instead of running them
+  synchronously — a synchronous stub would infinitely recurse. `startDragging`
+  tests stub `_updateHelperPos` to a no-op.
+- **No layout:** `getOuterWidth/Height` read `offsetWidth/Height` (0 in happy-dom)
+  and `getBoundingClientRect` returns zeros. Tests `vi.spyOn(...,
+  'getBoundingClientRect')` where `getOffset`/`hitTest` math matters; helper
+  sizing just needs the call to not throw.
+- **Spying on private methods:** `vi.spyOn(d as never, '_x')` typechecks for reads
+  but **not** for `.mockImplementation`. Cast through a `DragPrivate` interface
+  (`d as unknown as DragPrivate`) when you need to stub.
+
+## Playground-only (NOT unit-tested — needs real layout/pointer/animation)
+
+- Helpers actually cloning, sizing to source (border-box parity), and lag-following
+  the cursor — multi-helper spacing/lag and `singleHelper`.
+- `moveHelperToCursor`, `helperOpacity`, custom `settings.helper` wrapper visuals.
+- The **WAAPI return-to-source tween** landing exactly on each draggee's offset
+  with no flash before removal; `fadeOutHelpers`; reduced-motion jump-home.
+- `DragDrop` active-target highlighting over real laid-out targets; overlap /
+  first-match; auto-scroll + drop-target interplay.
+- `copyDraggeeInputValuesToHelper` preserving real input/radio/checkbox state.
+
+## For the `DragSort` port (next engineer)
+
+- `Drag.$draggee` / `BaseDrag.$items` are **`HTMLElement[]` / `Element[]`** — array
+  ops only (`.indexOf`, `.includes`, `[i]`), never `.eq()`/`$.inArray`.
+- Reserved/claimed property names now in use by `Drag` (do not collide):
+  `targetItemWidth`, `targetItemHeight`, `targetItemPositionInDraggee`, `$draggee`,
+  `otherItems`, `totalOtherItems`, `helpers`, `helperTargets`, `helperPositions`,
+  `helperLagIncrement`, `updateHelperPosFrame`, `lastMouseX/Y`, `draggeeDisplay`,
+  `draggeeVirtualMidpointX/Y`. Private: `_returningHelpersToDraggees`,
+  `_returnAnimations`, `_createHelper`, `_getHelperTarget`, `_updateHelperPos`,
+  `_showDraggee`, `_hide`, `_show`.
+- `Drag` exposes `draggeeVirtualMidpointX/Y` (computed in `drag()` before
+  `super.drag()`), `appendDraggee`, and `setDraggee` — the hooks `DragSort` builds
+  insertion logic on.
+- `Drag` does **not** override `onDrag` (its per-frame work is in the
+  `_updateHelperPos` RAF loop), so `DragDrop.onDrag`'s `super.onDrag()` chains
+  straight to `BaseDrag.onDrag` (RAF-deferred event emit). `DragSort` should
+  follow the same pattern.
+- Override lifecycle via real `constructor` + `super.method()` — no
+  `init()`/`this.base()` trampoline.
+```
diff --git a/packages/craftcms-garnish/docs/11-dragsort-design.md b/packages/craftcms-garnish/docs/11-dragsort-design.md
new file mode 100644
index 00000000000..16857921fe3
--- /dev/null
+++ b/packages/craftcms-garnish/docs/11-dragsort-design.md
@@ -0,0 +1,410 @@
+# 11 — `DragSort` Design (sortable lists + live insertion feedback)
+
+> **Status:** design contract. Specifies the TypeScript surface for the legacy `DragSort.js`
+> (~697 LOC) port onto the **already-shipped** modern `Drag` (`src/drag/drag.ts`, docs 09/10),
+> which itself sits on `BaseDrag` (docs 07/08). `DragSort` is the last Phase-2 (drag cluster)
+> module — once it lands the drag cluster is COMPLETE.
+>
+> **Grounding:** every signature below is written against the *real* modern API, not legacy
+> names. The load-bearing facts:
+>
+> - `BaseDrag.$items` is `Element[]`, `$targetItem` is `HTMLElement | null`; `Drag.$draggee` is
+>   `HTMLElement[]` (target always index 0). Array ops only — `.indexOf`/`.includes`/`[i]`,
+>   never `.eq()`/`$.inArray`.
+> - `BaseDrag.getPrevItem(item)`/`getNextItem(item)` take an `Element` and return
+>   `Element | null` (no jQuery).
+> - `Drag` computes `draggeeVirtualMidpointX/Y` inside `drag()` *before* `super.drag()` runs
+>   `onDrag()`, so `DragSort.onDrag` reads fresh virtual-midpoint coords.
+> - The RAF-emitting hooks `onDragStart`/`onDrag`/`onDragStop` run **synchronously** inside
+>   `startDragging`/`drag`/`stopDragging`; only their `trigger(...)` emission is RAF-deferred.
+>   So a `DragSort` override does its synchronous work, then calls `super.onDragStart()` (etc.)
+>   to schedule the event — exactly mirroring the legacy `this.base()` order.
+> - `Drag` does **not** override `onDrag`/`onDragStart`/`onDragStop`, so `super.*` from
+>   `DragSort` chains straight to `BaseDrag.*` (the RAF emitters). Same pattern `DragDrop` uses.
+> - `Drag.setDraggee` records `targetItemPositionInDraggee` (the target's index in the
+>   *input* draggee order) and forces `$draggee[0] === $targetItem`.
+
+---
+
+## 0. What `DragSort` is
+
+`DragSort extends Drag`. It is the sortable-list dragger: drag items to reorder them within their
+container, with **live insertion feedback** — as the cursor moves, the dragged item (and an
+optional placeholder element) is physically re-inserted into the DOM at the spot it would land,
+so the surrounding items shift in real time. On drop the new order is committed and a
+`sortChange` event fires if anything actually moved.
+
+Unlike `DragDrop` (which highlights a separate drop *zone*), `DragSort` reorders the items
+*amongst themselves*: the draggee moves through the list and the list reflows around it.
+
+---
+
+## 1. Public contract
+
+### 1.1 Constructor
+
+Same `(items?, settings?)` shape + plain-object param-shift as `Drag`. Mirror the `Drag`/`DragDrop`
+explicit-merge form: layer `DragSort.defaults` under the caller's overrides, then delegate to
+`super` (which layers `Drag.defaults`/`BaseDrag.defaults` under that — every key resolves).
+
+```ts
+constructor(items?: DragItemsInput | Partial<S> | null, settings?: Partial<S>) {
+  let resolvedItems = (items as DragItemsInput) ?? null;
+  if (settings === undefined && isPlainObject(items)) {
+    settings = items as Partial<S>;
+    resolvedItems = null;
+  }
+  super(resolvedItems, {...(DragSort.defaults as Partial<S>), ...(settings ?? {})});
+}
+```
+
+### 1.2 Settings (`DragSortSettings`, extends `DragSettings`)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `container` | `null` | The list container (element / selector / list). At drag start, walked up to the nearest ancestor that actually has a height; the drag only sorts while the cursor is over that `$heightedContainer`. |
+| `insertion` | `null` | The placeholder. A function `(draggee) => element \| markup`, an element, or an HTML string. Re-inserted just before the draggee to show the landing spot. `null` → no placeholder (the draggee itself is the feedback). |
+| `moveTargetItemToFront` | `false` | If the target item isn't the first draggee, move it to the front of the draggee block in the DOM at drag start (and leave it there on drop). |
+| `magnetStrength` | `1` | Divides the helper's pull toward the cursor. `1` → no magnetism (helper tracks the cursor exactly, as in `Drag`). `>1` → the helper lags toward the draggee's home, giving a rubber-band feel. |
+| `onInsertionPointChange` | no-op | Fired (RAF-deferred) whenever the insertion point moves. |
+| `onSortChange` | no-op | Fired (RAF-deferred) on drop when the order actually changed. |
+| `canInsertBefore` | `() => true` | Gate: may the draggee be inserted *before* this item? |
+| `canInsertAfter` | `() => true` | Gate: may the draggee be inserted *after* this item? |
+
+```ts
+export interface DragSortSettings extends DragSettings {
+  container: ElementInput | null;
+  insertion:
+    | ((draggee: HTMLElement[]) => HTMLElement | string)
+    | HTMLElement
+    | string
+    | null;
+  moveTargetItemToFront: boolean;
+  magnetStrength: number;
+  onInsertionPointChange: () => void;
+  onSortChange: () => void;
+  canInsertBefore: (item: HTMLElement) => boolean;
+  canInsertAfter: (item: HTMLElement) => boolean;
+}
+```
+
+### 1.3 Public properties (jQuery → native)
+
+Legacy held jQuery collections; modern keeps the `$`-prefixed names for consumer parity but
+holds native types.
+
+```ts
+$heightedContainer: HTMLElement | null = null;  // legacy: jQuery
+$insertion: HTMLElement | null = null;           // legacy: jQuery
+insertionVisible = false;
+oldDraggeeIndexes: number[] | null = null;
+newDraggeeIndexes: number[] | null = null;
+closestItem: HTMLElement | null = null;          // legacy: raw element already
+```
+
+Private: `_allMidpoints: Map<Element, Midpoint> | null`, `_midpointVersion: number`.
+
+### 1.4 Methods & hooks (mapped onto the real super-dispatch)
+
+```ts
+// --- Lifecycle hooks (synchronous work, then super to RAF-emit) -----------
+override onDragStart(): void;   // record indexes, moveTargetItemToFront, create+place
+                                // insertion, clear+precalc midpoints, super.onDragStart()
+override onDrag(): void;        // container hit-test → closest-item detection →
+                                // _updateInsertion, then super.onDrag()
+override onDragStop(): void;    // remove insertion, restore target pos, return helpers,
+                                // super.onDragStop(), re-sort $items, fire sortChange
+
+// --- Helper geometry override (magnetStrength) ----------------------------
+override getHelperTargetX(real?: boolean): number;
+override getHelperTargetY(real?: boolean): number;
+
+// --- Insertion / gating ---------------------------------------------------
+createInsertion(): HTMLElement | null;
+canInsertBefore(item: HTMLElement): boolean;
+canInsertAfter(item: HTMLElement): boolean;
+
+// --- Event hooks ----------------------------------------------------------
+onInsertionPointChange(): void; // RAF-deferred trigger('insertionPointChange') + callback
+onSortChange(): void;           // RAF-deferred trigger('sortChange') + callback
+```
+
+Private: `_precalculateMidpoints`, `_getVisibleItems`, `_getItemIndex`, `_getDraggeeIndexes`,
+`_getClosestItem`, `_clearMidpoints`, `_getItemMidpoint`, `_updateInsertion`, `_moveDraggeeToItem`,
+`_placeInsertionWithDraggee`, `_removeInsertion`, `_sortItemsByDomOrder`, `_siblingIndex`,
+`_toInsertionElement`.
+
+**Events:** `insertionPointChange`, `sortChange`, plus all inherited `Drag`/`BaseDrag` events
+(`returnHelpersToDraggees`, `beforeDragStart`, `dragStart`, `drag`, `dragStop`, `destroy`).
+
+---
+
+## 2. The `_getClosestItem` spatial hit-test (the hard part)
+
+For each pointer frame `DragSort` must find which item the dragged element is closest to, so it
+can decide where to re-insert. The legacy algorithm:
+
+1. **Virtual midpoint.** `Drag.draggeeVirtualMidpointX/Y` is the center the *draggee would have*
+   at the current cursor position (`mouse - mouseOffset + targetItem{W,H}/2`). All distances are
+   measured from it.
+2. **Seed.** Start by testing the draggee itself (or, when `removeDraggee`, the visible insertion)
+   so the current position is the baseline closest.
+3. **Walk outward both directions.** From the item *before* the first draggee, walking backward,
+   then from the item *after* the last draggee, walking forward. For each candidate, compute the
+   axis-appropriate distance (`X_AXIS` → dx only, `Y_AXIS` → dy only, else Euclidean).
+4. **Early-skip when receding.** While walking, if a candidate is getting *further* on every
+   relevant axis than the last tested one, skip testing it (but keep walking) — the cheap
+   monotonic-distance filter that lets large lists bail out of full comparisons.
+5. **Gate.** Only items where `canInsertBefore(item) || canInsertAfter(item)` are tested.
+6. **Result.** The nearest tested item, unless it's the draggee/insertion itself → `null`.
+
+### 2.1 Midpoint caching (perf on large lists)
+
+Measuring `getBoundingClientRect()` per item per frame thrashes layout. So:
+
+- **`_precalculateMidpoints()`** runs once at drag start: a single read pass over `$items` storing
+  `{x, y, width, height, top, bottom}` (page coords, scroll-adjusted) in `_allMidpoints: Map`.
+  `_getItemMidpoint(item)` then returns the cached value — O(1), zero layout reads mid-drag.
+- **`_updateInsertion()`** moves the draggee in the DOM, which shifts neighbors, so it recomputes
+  **only** the moved item + its previous/next neighbors' midpoints (not the whole list).
+- **Viewport filter.** For lists `> 200` items, `_getVisibleItems()` restricts the closest-item
+  scan to items within ~300px of the viewport (using the cached `top/bottom`), skipping the
+  directional walk entirely.
+
+> **Deviation from legacy (documented in doc 12).** Legacy `_getItemMidpoint` had a second,
+> pre-optimization fallback that *temporarily re-inserted the draggee next to each candidate and
+> measured it via `$.offset()/outerWidth()`* (the `$.data('midpointVersion', …)` path). Since the
+> modern flow **always** populates `_allMidpoints` at drag start, that fallback is dead for
+> `$items`; it only ever mattered for the non-cached `insertion` element. The port replaces the
+> repositioning dance with a direct `getBoundingClientRect()` measurement for any element not in
+> the cache. This is faithful to the *optimized* legacy path, avoids layout thrash, and is the
+> behavior the midpoint cache was written to supersede. `_clearMidpoints()` invalidates the cache
+> (nulls the map + bumps `_midpointVersion`); `_precalculateMidpoints()` rebuilds it.
+
+### 2.2 Concrete shape
+
+```ts
+interface Midpoint {
+  x: number; y: number; width: number; height: number; top: number; bottom: number;
+}
+
+_getClosestItem(): HTMLElement | null {
+  let closest: HTMLElement | null = null;
+  let closestDist = 0;
+  const axis = this.settings!.axis;
+  const vx = this.draggeeVirtualMidpointX!;
+  const vy = this.draggeeVirtualMidpointY!;
+
+  const test = (item: HTMLElement): void => {
+    const mp = this._getItemMidpoint(item);
+    const dx = Math.abs(mp.x - vx);
+    const dy = Math.abs(mp.y - vy);
+    const dist =
+      axis === X_AXIS ? dx : axis === Y_AXIS ? dy : Math.sqrt(dx ** 2 + dy ** 2);
+    if (closest === null || dist < closestDist) {
+      closest = item;
+      closestDist = dist;
+    }
+  };
+
+  const visibleItems =
+    this._allMidpoints && this.$items.length > 200 ? this._getVisibleItems() : null;
+
+  // Seed with the draggee (or the visible insertion when removeDraggee).
+  if (!this.settings!.removeDraggee) test(this.$draggee[0]!);
+  else if (this.insertionVisible && this.$insertion) test(this.$insertion);
+
+  // Baseline distances off the seed.
+  let lastX: number | null = null, lastY: number | null = null;
+  let startX: number | null = null, startY: number | null = null;
+  if (closest) {
+    const mp = this._getItemMidpoint(closest);
+    if (axis !== Y_AXIS) startX = lastX = Math.abs(mp.x - vx);
+    if (axis !== X_AXIS) startY = lastY = Math.abs(mp.y - vy);
+  }
+
+  const walk = (next: (i: Element) => Element | null, from: Element | null): void => {
+    let other = from as HTMLElement | null;
+    while (other) {
+      const mp = this._getItemMidpoint(other);
+      const dx = axis !== Y_AXIS ? Math.abs(mp.x - vx) : 0;
+      const dy = axis !== X_AXIS ? Math.abs(mp.y - vy) : 0;
+      const receding =
+        (axis === Y_AXIS || (lastX !== null && dx > lastX)) &&
+        (axis === X_AXIS || (lastY !== null && dy > lastY));
+      if (!receding) {
+        if (axis !== Y_AXIS) lastX = dx;
+        if (axis !== X_AXIS) lastY = dy;
+        if (this.canInsertBefore(other) || this.canInsertAfter(other)) test(other);
+      }
+      other = next(other) as HTMLElement | null;
+    }
+  };
+
+  if (visibleItems) {
+    for (const item of visibleItems) {
+      if (this.canInsertBefore(item) || this.canInsertAfter(item)) test(item);
+    }
+  } else {
+    walk((i) => this.getPrevItem(i), this.getPrevItem(this.$draggee[0]!));
+    lastX = startX; lastY = startY;             // reset for the forward pass
+    walk((i) => this.getNextItem(i), this.getNextItem(this.$draggee.at(-1)!));
+  }
+
+  // Ignore a "closest" that is the draggee/insertion itself.
+  if (closest !== this.$draggee[0] && (!this.insertionVisible || closest !== this.$insertion)) {
+    return closest;
+  }
+  return null;
+}
+```
+
+---
+
+## 3. Insertion / placeholder feedback
+
+The visual feedback is the **real DOM reorder**: as `closestItem` changes, `_moveDraggeeToItem`
+re-inserts the whole `$draggee` block before/after the target, and the optional `$insertion`
+placeholder is re-positioned just before the draggee.
+
+```ts
+// onDrag: detect a new closest item, then update.
+override onDrag(): void {
+  if (this.$heightedContainer && !hitTest(this.mouseX!, this.mouseY!, this.$heightedContainer)) {
+    if (this.closestItem) { this.closestItem = null; this._removeInsertion(); }
+  } else {
+    const prev = this.closestItem;
+    this.closestItem = this._getClosestItem();
+    if (prev !== this.closestItem && this.closestItem !== null) this._updateInsertion();
+  }
+  super.onDrag();
+}
+
+_moveDraggeeToItem(item: HTMLElement): void {
+  const first = this.$draggee[0]!;
+  const sameParent = first.parentNode === item.parentNode;
+  const goingDown =
+    this.canInsertAfter(item) && sameParent &&
+    this._siblingIndex(first) < this._siblingIndex(item);
+  if (goingDown) item.after(...this.$draggee);   // jQuery $draggee.insertAfter(item)
+  else item.before(...this.$draggee);            // jQuery $draggee.insertBefore(item)
+  this._placeInsertionWithDraggee();
+  this.$items = this._sortItemsByDomOrder(this.$items);   // jQuery $().add($items) re-sort
+}
+
+_placeInsertionWithDraggee(): void {
+  if (this.$insertion && this.$draggee[0]) {
+    this.$draggee[0].before(this.$insertion);   // jQuery $insertion.insertBefore($draggee.first())
+    this.insertionVisible = true;
+  }
+}
+```
+
+`_updateInsertion()` calls `_moveDraggeeToItem(this.closestItem)`, recomputes the moved item's +
+neighbors' cached midpoints, then `onInsertionPointChange()`.
+
+On drop (`onDragStop`): remove the insertion, optionally restore the target's position within the
+draggee block (unless `moveTargetItemToFront`), return the helpers home (`Drag`'s
+`returnHelpersToDraggees` — `DragSort` auto-returns, matching legacy), then re-sort `$items` to DOM
+order, recompute `newDraggeeIndexes`, and fire `sortChange` if they differ from `oldDraggeeIndexes`.
+
+---
+
+## 4. jQuery removals — `DragSort.js`
+
+| # | Legacy | Native replacement |
+| --- | --- | --- |
+| 1 | `$.extend({}, DragSort.defaults, settings)` | explicit `{...DragSort.defaults, ...settings}` via `super` |
+| 2 | `$.isPlainObject(items)` param-shift | `isPlainObject()` (`utils/misc`) |
+| 3 | `$(this.settings.insertion)` / `$(fn($draggee))` | `_toInsertionElement(...)` — `<template>` parse for markup, else element |
+| 4 | `this.$draggee.offset().left/top` (magnet) | `getOffset(this.$draggee[0])` (`utils/dom`) |
+| 5 | `Garnish.hitTest(x, y, $container)` | `hitTest(this.mouseX!, this.mouseY!, container)` (`utils/dom`) |
+| 6 | `$(container).height()` + `.parent()` walk | `getOuterHeight(el)` + `el.parentElement` walk |
+| 7 | `$draggee.first().insertBefore($draggee[1])` | `this.$draggee[1].before(this.$draggee[0])` |
+| 8 | `$targetItem.insertAfter($draggee.eq(pos))` | `this.$draggee[pos].after(this.$targetItem)` |
+| 9 | `$draggee.insertAfter(item)` / `.insertBefore(item)` | `item.after(...$draggee)` / `item.before(...$draggee)` |
+| 10 | `$insertion.insertBefore($draggee.first())` | `this.$draggee[0].before(this.$insertion)` |
+| 11 | `$insertion.remove()` | `this.$insertion.remove()` (native `ChildNode.remove`) |
+| 12 | `this.$items.index(item)` | `this.$items.indexOf(item)` |
+| 13 | `$draggee.index()` / `$(item).index()` | `_siblingIndex(el)` (index among element siblings) |
+| 14 | `this.$draggee.eq(i)` | `this.$draggee[i]` |
+| 15 | `$().add(this.$items)` (DOM-order re-sort) | `_sortItemsByDomOrder` via `compareDocumentPosition` |
+| 16 | `$.contains($draggee[0], item)` | `this.$draggee[0].contains(item)` (`Node.contains`) |
+| 17 | `$.data(item, 'midpoint'/'midpointVersion')` | `_allMidpoints: WeakMap`-style `Map<Element, Midpoint>` |
+| 18 | `item.getBoundingClientRect()` + `pageXOffset` | same, via `win.scrollX/scrollY` |
+| 19 | `Garnish.requestAnimationFrame` | `requestAnimationFrame` (`utils/animation`) |
+| 20 | `$.noop` | `() => {}` |
+| 21 | `$draggee.parent()[0] === $(item).parent()[0]` | `first.parentNode === item.parentNode` |
+
+---
+
+## 5. File layout & exports
+
+```
+src/drag/
+  base-drag.ts   # EXISTS
+  drag.ts        # EXISTS
+  drag-drop.ts   # EXISTS
+  drag-sort.ts   # NEW — class DragSort extends Drag + DragSortSettings
+```
+
+- `src/drag/drag-sort.ts` exports `DragSort` (default + named) and `DragSortSettings`.
+- `src/index.ts`: named export `DragSort` + `DragSortSettings`; add `DragSort` to the `Garnish`
+  namespace object so `new Garnish.DragSort(...)` resolves (compat-layer relies on it).
+- **No new utils** — everything (`getOffset`, `getOuterHeight`, `hitTest`, `coerceElements`,
+  `requestAnimationFrame`, `getPrevItem`/`getNextItem`, `isPlainObject`) already exists.
+
+---
+
+## 6. Testing strategy (happy-dom — no layout, no real pointer)
+
+happy-dom returns `0` geometry and `element.animate` is `undefined`, so `returnHelpersToDraggees`
+takes the synchronous no-WAAPI path (as in the `Drag` tests). Mirror `drag-drop.test.ts`: mock the
+animation module's RAF onto a manual queue, mock `getBoundingClientRect` where midpoint math
+matters.
+
+**Unit-testable (Vitest):**
+
+- **Settings/defaults** — `DragSort.defaults`; param-shift; `canInsertBefore/After` default `true`;
+  `Drag`/`BaseDrag` keys survive the merge.
+- **`createInsertion`** — function form (gets `$draggee`), markup string (parsed), element,
+  and `null`.
+- **`canInsertBefore`/`canInsertAfter`** — delegate to settings.
+- **`_getItemIndex` / `_getDraggeeIndexes`** — indices into `$items`.
+- **`_getClosestItem`** — build a vertical list, mock each item's rect, `_precalculateMidpoints`,
+  set `draggeeVirtualMidpointX/Y`, assert the nearest insertable item is returned (and `null` when
+  the draggee is closest); assert `canInsertBefore/After` gating excludes items.
+- **`_moveDraggeeToItem` / `_placeInsertionWithDraggee` / `_removeInsertion`** — DOM reorder
+  (before/after by sibling index), insertion placement + `insertionVisible` toggle.
+- **`onDragStart`** — records `oldDraggeeIndexes`, creates+places insertion, precalcs midpoints,
+  honors `moveTargetItemToFront` DOM reorder.
+- **`onDrag`** — a changed closest item invokes `_updateInsertion` (spy); the container-miss path
+  clears `closestItem` + removes the insertion.
+- **`onDragStop`** — removes insertion, calls `returnHelpersToDraggees`, fires `sortChange`
+  (RAF-flushed) only when indexes changed; no `sortChange` when order is unchanged.
+- **`insertionPointChange` / `sortChange` events** — wired through `trigger` + the settings
+  callbacks (RAF-flushed).
+- **Event wiring** — synthetic `PointerEvent` (shimmed page coords like the BaseDrag tests):
+  pointerdown on an item + a past-threshold pointermove starts a drag and emits `dragStart`.
+
+**Playground-only (needs real layout/pointer/animation):**
+
+- Items actually shifting as the draggee passes (real reflow); the `insertion` placeholder
+  showing the landing slot; `magnetStrength` rubber-banding; large-list viewport-filter perf;
+  `axis`-locked sorting; `moveTargetItemToFront`; multi-draggee blocks.
+
+---
+
+## 7. Risks
+
+1. **`_getClosestItem` fidelity** — the receding-distance early-skip + axis branching is subtle;
+   covered by focused midpoint-math tests. **Risk: medium.**
+2. **DOM-order `$items` re-sort** — legacy leaned on jQuery `.add()` sorting; the
+   `compareDocumentPosition` replacement must keep `$items` in document order after every move so
+   `_getDraggeeIndexes` is correct. **Risk: medium** — tested directly.
+3. **Midpoint-cache staleness** — `_updateInsertion` recomputes only the moved item + neighbors;
+   if the move shifts more than the neighbors the cache can drift. Matches legacy's same
+   optimization. **Risk: low–medium** — validate visually on large lists.
+4. **`insertion` markup parsing** — `<template>`-based parse returns the first element child;
+   multi-root markup drops siblings (legacy `$(markup)` kept all). **Risk: low** — placeholders
+   are single elements in practice; documented.
diff --git a/packages/craftcms-garnish/docs/12-dragsort-impl-notes.md b/packages/craftcms-garnish/docs/12-dragsort-impl-notes.md
new file mode 100644
index 00000000000..63d1d2bd89c
--- /dev/null
+++ b/packages/craftcms-garnish/docs/12-dragsort-impl-notes.md
@@ -0,0 +1,149 @@
+# 12 — `DragSort` Implementation Notes
+
+> Status: **Implemented.** Built against `11-dragsort-design.md` on top of the shipped
+> `Drag` (docs 09/10) / `BaseDrag` (docs 07/08). With `DragSort` landed, the **drag
+> cluster is COMPLETE** — no drag modules remain. All gates green in the worktree:
+> `check:types`, `check:format`, `test` (**247 tests**, was 215 — +32), `build`,
+> `playground:build`. `dist/index.js` jQuery references: **0**
+> (`grep -ciE "jquery|\$\(" dist/index.js`).
+
+## What shipped
+
+| File | Change |
+| --- | --- |
+| `src/drag/drag-sort.ts` | **NEW.** `class DragSort extends Drag` — sortable list with live insertion feedback, `_getClosestItem` spatial hit-test, midpoint cache. |
+| `src/index.ts` | Named exports `DragSort`, `DragSortSettings`; added `DragSort` to the `Garnish` namespace object. |
+| `tests/drag-sort.test.ts` | **NEW.** 32 tests covering settings, insertion, gating, closest-item math, DOM reorder, lifecycle hooks, `sortChange`, magnet, pointer wiring. |
+| `playground/{index.html,main.ts,styles.css}` | **NEW** section 9 "DragSort — reorderable list" (utilities renumbered to 10). |
+| `README.md`, `docs/06-api-reference.md` | DragSort marked **supported**; drag cluster **COMPLETE**; reference entry + usage example added. |
+
+## Exact exported public API
+
+```ts
+export type DragSortInsertion =
+  | ((draggee: HTMLElement[]) => HTMLElement | string)
+  | HTMLElement
+  | string
+  | null;
+
+export interface DragSortSettings extends DragSettings {
+  container: ElementInput | null;
+  insertion: DragSortInsertion;
+  moveTargetItemToFront: boolean;
+  magnetStrength: number;
+  onInsertionPointChange: () => void;
+  onSortChange: () => void;
+  canInsertBefore: (item: HTMLElement) => boolean;
+  canInsertAfter: (item: HTMLElement) => boolean;
+}
+
+export class DragSort<S extends DragSortSettings = DragSortSettings> extends Drag<S> {
+  static override readonly defaults: DragSortSettings;
+
+  $heightedContainer: HTMLElement | null;
+  $insertion: HTMLElement | null;
+  insertionVisible: boolean;
+  oldDraggeeIndexes: number[] | null;
+  newDraggeeIndexes: number[] | null;
+  closestItem: HTMLElement | null;
+
+  constructor(items?: DragItemsInput | Partial<S> | null, settings?: Partial<S>);
+
+  createInsertion(): HTMLElement | null;
+  canInsertBefore(item: HTMLElement): boolean;
+  canInsertAfter(item: HTMLElement): boolean;
+  override getHelperTargetX(real?: boolean): number;
+  override getHelperTargetY(real?: boolean): number;
+  override onDragStart(): void;
+  override onDrag(): void;
+  override onDragStop(): void;
+  onInsertionPointChange(): void;   // RAF-deferred
+  onSortChange(): void;             // RAF-deferred
+}
+export default DragSort;
+```
+
+Private: `_precalculateMidpoints`, `_getVisibleItems`, `_getItemIndex`,
+`_getDraggeeIndexes`, `_getClosestItem`, `_clearMidpoints`, `_getItemMidpoint`,
+`_measureMidpoint`, `_updateInsertion`, `_moveDraggeeToItem`,
+`_placeInsertionWithDraggee`, `_removeInsertion`, `_sortItemsByDomOrder`,
+`_siblingIndex`, `_toInsertionElement`. Events triggered: `insertionPointChange`,
+`sortChange` (+ inherited `Drag`/`BaseDrag` events).
+
+## Deviations from doc 11 (and why)
+
+1. **Midpoint fallback dropped (doc §2.1).** Legacy `_getItemMidpoint` had a second,
+   pre-optimization path that *temporarily re-inserted the draggee next to each
+   candidate and measured it via `$.offset()/outerWidth()`* (the
+   `$.data('midpointVersion', …)` dance). Because the modern flow **always** runs
+   `_precalculateMidpoints()` at drag start, that path is dead for `$items`; it only
+   ever mattered for the non-cached `insertion` placeholder. The port replaces it with
+   a direct `getBoundingClientRect()` measurement (`_measureMidpoint`) for any element
+   not in the cache. Faithful to the *optimized* legacy path; avoids layout thrash.
+   `_midpointVersion` is kept (bumped by `_clearMidpoints`) for parity/debug, but the
+   `Map` cache is the real store.
+
+2. **Lifecycle hooks, not `startDragging`/`drag`/`stopDragging` (doc §1.4).** All
+   DragSort-specific work lives in `onDragStart`/`onDrag`/`onDragStop`, exactly as
+   legacy did (`this.base()` → `super.*`). The synchronous setup/build that `Drag`
+   added (helper clones, lag loop) stays in `Drag.startDragging`; DragSort never
+   overrides it. `super.onDragStart()`/`super.onDrag()`/`super.onDragStop()` chain
+   straight to `BaseDrag.*` (the RAF event emitters), since neither `Drag` nor
+   `DragDrop` overrides those — the same pattern `DragDrop` uses.
+
+3. **`$().add($items)` → `compareDocumentPosition` re-sort (doc §4 #15).** After every
+   DOM move (`_moveDraggeeToItem`) and on drop, `$items` is re-sorted into document
+   order via `_sortItemsByDomOrder` so `_getDraggeeIndexes` reports the real order.
+   This replaces jQuery's implicit DOM-order sorting in `.add()`.
+
+4. **Draggee block move via `ChildNode.before/after(...spread)` (doc §4 #7–10).**
+   `$draggee.insertBefore/After(item)` → `item.before(...this.$draggee)` /
+   `item.after(...this.$draggee)`, which moves the whole block in order in one call.
+   `moveTargetItemToFront` uses `this.$draggee[1].before(this.$draggee[0])`.
+
+5. **`getHelperTargetX/Y` gained the `Drag` `real` parameter.** Legacy DragSort's
+   override took no args; the modern `Drag` signature is `(real = false)`. When
+   `magnetStrength === 1` (or no draggee yet) it delegates to `super.getHelperTargetX/Y(real)`
+   (so `moveHelperToCursor` still works); otherwise it applies the magnet formula
+   against `getOffset(this.$draggee[0])` (legacy used `$draggee.offset()`, i.e. the
+   first element).
+
+6. **`insertion` markup parse via `<template>`.** A string `insertion` is parsed with
+   a `<template>` and returns `content.firstElementChild`. Multi-root markup keeps only
+   the first element (legacy `$(markup)` kept all) — placeholders are single elements
+   in practice; documented in doc 11 §7.4.
+
+7. **`DragSort` auto-returns helpers on drop.** Unlike `Drag`/`DragDrop` (where the
+   consumer calls `returnHelpersToDraggees()` in their own `dragStop`), `DragSort.onDragStop`
+   calls it itself — legacy parity (the sort *is* the drop action).
+
+## happy-dom / testing caveats (for the next engineer)
+
+- **`element.animate` is `undefined`** → `returnHelpersToDraggees` (called inside
+  `onDragStop`) takes the synchronous no-WAAPI fallback. Set `helpers = []` /
+  `draggeeDisplay` in `onDragStop` tests to keep that path trivial.
+- **RAF is queued, not synchronous.** As in `drag-drop.test.ts`, the animation
+  module's `requestAnimationFrame` is mocked onto a manual `rafQueue`; the lag-follow
+  loop would infinitely recurse under a synchronous stub. The RAF-deferred event
+  emitters (`dragStart`, `sortChange`, `insertionPointChange`) only fire after an
+  explicit `flushRaf()`.
+- **No layout** → `getBoundingClientRect()` returns zeros. The `_getClosestItem` math
+  tests `vi.spyOn(el, 'getBoundingClientRect')` to stub a vertical list, then call
+  `_precalculateMidpoints()` + `_getClosestItem()` directly.
+- **Spying private methods:** cast through the `DragSortPrivate` interface
+  (`ds as unknown as DragSortPrivate`) to stub `_updateInsertion`/`_getClosestItem` or
+  read `_allMidpoints`.
+
+## Playground-only (NOT unit-tested — needs real layout/pointer/animation)
+
+- Items actually shifting as the draggee passes (real reflow); the `insertion`
+  placeholder showing the landing slot.
+- `magnetStrength > 1` rubber-banding the helper toward the dragged item's home.
+- Large-list (`> 200` items) viewport-filter perf path in `_getClosestItem`.
+- `axis`-locked sorting feel; `moveTargetItemToFront`; multi-draggee blocks.
+- The WAAPI return-to-source tween landing exactly on each row's offset (inherited
+  from `Drag`).
+
+See playground section 9 ("DragSort — reorderable list"): a 5-row sortable list
+constrained to `container`, `axis: 'y'`, with a dashed `insertion` placeholder, logging
+`dragStart`/`drag`/`dragStop`/`insertionPointChange`/`sortChange`.
diff --git a/packages/craftcms-garnish/docs/13-hud-design.md b/packages/craftcms-garnish/docs/13-hud-design.md
new file mode 100644
index 00000000000..6f9b51f04d8
--- /dev/null
+++ b/packages/craftcms-garnish/docs/13-hud-design.md
@@ -0,0 +1,246 @@
+# 13 — `HUD` Design
+
+> Phase 3 of the migration plan (doc 00): the anchored popover/bubble. **MED-HIGH**
+> difficulty — the risk is the smart 4-way positioning + the scroll-follow loop.
+> HUD is the last blocker for porting `FieldLayoutDesigner`, which does
+> `new Garnish.HUD(this.$addBtn, {...})`.
+>
+> HUD extends `Base` and reuses the overlay infrastructure `Modal` already ships:
+> the `UiLayerManager` (layer stacking + the Escape shortcut), the focus utilities,
+> and the native DOM/scroll utils that replace jQuery. It is **not** a `Modal`
+> subclass — it is anchored to a trigger, not centered in the viewport.
+
+## 1. What a HUD is
+
+A HUD ("heads-up display") attaches a floating panel to a **trigger** element. It:
+
+1. Picks one of four **orientations** (`bottom` / `top` / `right` / `left`) from the
+   available clearance around the trigger, in a configurable order of preference.
+2. Draws a **tip** (arrow) that points back at the trigger from the chosen side.
+3. **Follows** the trigger when the window or the trigger's scroll container
+   scrolls or resizes, and when its own main content resizes.
+4. Traps `Tab` focus so it cycles between the trigger and the HUD body.
+5. Registers a **UI layer** + an **Escape** shortcut via the shared
+   `UiLayerManager`, exactly like `Modal`.
+
+Unlike `Modal`, the legacy HUD does **not** animate: `showContainer`/`hideContainer`
+are plain `.show()`/`.hide()` display toggles (there is no Velocity call in
+`HUD.js`), so there is no Velocity→WAAPI conversion in this port — see doc 14.
+
+## 2. Public contract
+
+### Constructor
+
+```ts
+new HUD(
+  trigger: ElementInput,
+  bodyContents?: HUDBodyContents | Partial<HUDSettings>,
+  settings?: Partial<HUDSettings>,
+)
+```
+
+- **Param shift** (legacy parity): `new HUD(trigger, settings)` is treated as
+  `new HUD(trigger, '', settings)` when the second arg is a plain object. This is
+  exactly how `FieldLayoutDesigner` calls it: `new Garnish.HUD(this.$addBtn, {…})`.
+- `trigger` is coerced to a single `HTMLElement` via `getElement` (the native
+  replacement for `$(trigger)`).
+- `bodyContents` accepts `string` HTML, a `Node`, or a list of nodes
+  (`HUDBodyContents`).
+- On construction the HUD builds its DOM tree, detects a `position: fixed`
+  ancestor (→ fixed positioning), wires its listeners, and — when `showOnInit`
+  (default) — shows immediately (hidden at opacity 0 until the first positioning
+  pass, to avoid a flash at the origin).
+
+### Settings (`HUDSettings`) + defaults
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `shadeClass` | `'hud-shade'` | Class for the shade/backdrop element. |
+| `hudClass` | `'hud'` | Class(es) for the HUD container (multi-class string OK). |
+| `tipClass` | `'tip'` | Base class for the tip; the orientation suffix is appended. |
+| `bodyClass` | `'body'` | Class for the `<form>` body. |
+| `headerClass` | `'hud-header'` | Identifies a header within the body content. |
+| `footerClass` | `'hud-footer'` | Identifies a footer within the body content. |
+| `mainContainerClass` | `'main-container'` | Class for the scrollable wrapper. |
+| `mainClass` | `'main'` | Class for the main content element. |
+| `orientations` | `['bottom','top','right','left']` | Sides to try, in order. |
+| `triggerSpacing` | `10` | Gap (px) between the HUD and its trigger. |
+| `windowSpacing` | `10` | Min gap (px) between the HUD and the viewport edge. |
+| `tipWidth` | `30` | Tip/arrow width (px). |
+| `minBodyWidth` | `200` | Minimum HUD body width (px). |
+| `minBodyHeight` | `0` | Minimum HUD body height (px). |
+| `withShade` | `true` | Render a shade/backdrop behind the HUD. |
+| `onShow` / `onHide` / `onSubmit` | no-op | Registered as `show`/`hide`/`submit` handlers. |
+| `closeBtn` | `null` | Element whose `activate` hides the HUD. |
+| `listenToMainResize` | `true` | Reposition on the main element's `resize` event. |
+| `showOnInit` | `true` | Show immediately on construction. |
+| `closeOtherHUDs` | `true` | Hide every other open HUD on show. |
+| `hideOnEsc` | `true` | Hide on Escape. |
+| `hideOnShadeClick` | `true` | Hide when the shade is clicked. |
+
+### Public properties
+
+`$trigger`, `$fixedTriggerParent`, `$hud`, `$tip`, `$body` (a `<form>`), `$header`,
+`$footer`, `$mainContainer`, `$main`, `$shade`, `$nextFocusableElement` — all
+`HTMLElement | null`, keeping the legacy `$`-prefixed names so consumers
+(`FieldLayoutDesigner` appends its library into `hud.$main`) read unchanged.
+`showing: boolean`, `orientation: HUDOrientation | null`, `tipClass: string | null`,
+plus the reposition bookkeeping records (`windowWidth/Height`, `scrollTop/Left`,
+`mainWidth/Height`, `sp*`).
+
+### Methods + overridable hooks
+
+| Member | Description |
+| --- | --- |
+| `show(ev?)` / `hide()` | Show / hide (display toggle); no-op if already in that state. |
+| `toggle()` | Flip visibility. |
+| `showContainer()` / `hideContainer()` | The raw display toggles (overridable). |
+| `updateBody(contents)` | Replace body content; re-extract header/footer. |
+| `updateRecords()` | Re-measure; returns whether anything changed (drives scroll-follow). |
+| `updateSizeAndPosition(force?)` | Schedule a RAF reposition (forced, or when records changed). |
+| `updateSizeAndPositionInternal()` | The 4-way positioning pass (runs in the RAF). |
+| `submit()` | Fire the `submit` flow. |
+| `onShow()` / `onHide()` / `onSubmit()` | Hooks; emit the event. Override + `super.*()`. |
+| `destroy()` | Remove DOM, drop from `instances`/`activeHUDs`, base teardown. |
+
+### Statics
+
+`HUD.instances: HUD[]`, `HUD.activeHUDs: Record<string, HUD>` (keyed by instance
+namespace, used by `closeOtherHUDs`), `HUD.tipClasses` (orientation → tip suffix),
+`HUD.defaults`.
+
+### Events
+
+`show`, `hide`, `submit`, `updateSizeAndPosition`, `destroy`. The `onShow` /
+`onHide` / `onSubmit` settings callbacks are registered as handlers for the
+matching events at construction (legacy behavior — they fire through the event
+system, not by a direct call inside the hook).
+
+## 3. The 4-way positioning algorithm
+
+Run in `updateSizeAndPositionInternal()` (on a RAF). All math is a faithful port
+of `HUD.js`'s `updateSizeAndPositionInternal`.
+
+1. **Measure.** Window scroll (`window.scrollX/Y`); trigger border-box size
+   (`getOuterWidth/Height`); the trigger's document-relative offset (jQuery
+   `.offset()` → `rect.top + scrollY`) **and** its scroll-container-relative offset
+   (`getOffset`, which adds the scroll container's scroll when it isn't the
+   window). For a fixed trigger, offsets are de-scrolled and the scroll terms
+   zeroed. The HUD body's content box is measured with `getContentWidth/Height`
+   (jQuery `.width()/.height()` parity = border-box rect minus padding+border).
+
+2. **Clearances.** Compute the available space on each side of the trigger:
+
+   ```
+   bottom = windowHeight + scScrollTop  - triggerBottom
+   top    = triggerTop   - scScrollTop
+   right  = windowWidth  + scScrollLeft - triggerRight
+   left   = triggerLeft  - scScrollLeft
+   ```
+
+3. **Pick the side.** Walk `settings.orientations` in order. The "relevant size"
+   is the body **height** for `top`/`bottom` and the body **width** for
+   `left`/`right`. The first orientation whose
+   `clearance - (windowSpacing + triggerSpacing) >= relevantSize` wins. If none
+   fits, fall back to the side with the **most** clearance seen so far; a final
+   guard pins it to `bottom`.
+
+4. **Tip class.** Remove the previous `tipClass`, then add
+   `` `${tipClass}-${HUD.tipClasses[orientation]}` `` — the tip points *back* at
+   the trigger, so `bottom → tip-top`, `top → tip-bottom`, `right → tip-left`,
+   `left → tip-right`.
+
+5. **Clamp the body.** Derive `maxHudBodyWidth/Height` from the chosen side's
+   clearance (or the window for the cross-axis), floored by `minBodyWidth/Height`.
+   If the body exceeds the max (or is under the min), set `hud.style.width` /
+   `mainContainer.style.height` and switch on `overflow-x/y: scroll` when the
+   measured content (`mainWidth/Height`) overflows.
+
+6. **Place the HUD + tip.** For `top`/`bottom`: center the HUD horizontally on the
+   trigger center, clamp `left` into `[windowSpacing, windowWidth - bodyWidth -
+   windowSpacing]`, set `top` above/below the trigger by `triggerSpacing`, and set
+   the tip's `left` to `within(triggerCenter - left - tipWidth/2, 0, bodyWidth -
+   tipWidth)`. For `left`/`right`: the mirror, swapping axes. Near the corners,
+   shrink the adjacent border radius to `2px` (legacy nicety) so the tip doesn't
+   collide with a rounded corner.
+
+The tip's **edge** placement (which side of the HUD it sits on) is the CSS
+orientation class's job; the JS only sets the perpendicular offset along that edge
+(and clears the inline value on the other axis).
+
+## 4. Scroll-follow / reposition machinery
+
+- `updateSizeAndPosition(force?)` is the throttled entry point. When `force === true`
+  (on show) it always schedules; otherwise it calls `updateRecords()` and only
+  schedules when something changed **and** a pass isn't already pending
+  (`updatingSizeAndPosition`). It schedules `updateSizeAndPositionInternal` via the
+  native `requestAnimationFrame` re-export (`updatingSizeAndPosition` is cleared at
+  the end of the internal pass).
+- `updateRecords()` re-reads window size, scroll-container scroll, the main
+  element's outer size, and — when the trigger's `getScrollParent` differs from the
+  global scroll container — that scroll parent's size/scroll, returning whether any
+  changed. This is the change-detection that keeps the scroll/resize handlers cheap.
+- Listeners wired at construction: `window` `resize`, the scroll container's
+  `scroll` (skipped for a fixed trigger), and — when `listenToMainResize` — the
+  main element's synthetic `resize`. `FieldLayoutDesigner` passes
+  `listenToMainResize: false`.
+
+## 5. jQuery removals → modern utils
+
+| Legacy (`HUD.js`) | Modern replacement |
+| --- | --- |
+| `$(trigger)` | `getElement(trigger)` (→ a single `HTMLElement`) |
+| `$('<div/>', {class})` + `.appendTo()` | `document.createElement` + `appendChild` |
+| `$.isPlainObject(bodyContents)` | `isPlainObject` (`utils/misc`) |
+| `.data('hud', this)` | module-level `WeakMap<Element, HUD>` |
+| `.css('position')` / `.offsetParent()` | `getComputedStyle().position` / `el.offsetParent` |
+| `.scrollParent()` | `getScrollParent` (`utils/scroll`) |
+| `$trigger.offset()` | inline `rect.top + window.scrollY` (jQuery `.offset()` parity) |
+| `Garnish.getOffset($trigger)` | `getOffset` (`utils/dom`) |
+| `.outerWidth()` / `.outerHeight()` | `getOuterWidth` / `getOuterHeight` (`utils/dom`) |
+| `$body.width()` / `.height()` | `getContentWidth` / `getContentHeight` (rect − padding − border) |
+| `Garnish.$win` / `$bod` / `$scrollContainer` | `win` / `bod` / `globals.scrollContainer` |
+| `$win.scrollLeft()/scrollTop()` | `window.scrollX/Y` |
+| `$scrollContainer.scrollTop()` | `_scrollContainerScrollTop()` (window → `scrollY`, else `el.scrollTop`) |
+| `.find(':focusable')` | `getFocusableElements` (`utils/focusable`) |
+| `getKeyboardFocusableElements($hud)` | `getKeyboardFocusableElements` (`utils/focus`) |
+| `Garnish.focusIsInside($hud)` | `focusIsInside` (`utils/focus`) |
+| `Garnish.within(...)` | `within` (`utils/misc`) |
+| `Garnish.requestAnimationFrame` | the native RAF re-export (`utils/animation`) |
+| `Garnish.uiLayerManager` | `getUiLayerManager()` (`managers/registry`) |
+| `.velocity()` / `.show()` / `.hide()` | **n/a** — legacy HUD has no Velocity; show/hide are explicit `style.display = 'block' \| 'none'` toggles (`'block'`, not `''`, since `.hud` defaults to `display: none` — see doc 14) |
+| `$header.insertBefore($mainContainer)` / `insertAfter` | `mainContainer.before(header)` / `.after(footer)` |
+
+## 6. Testing strategy
+
+happy-dom has no layout (`getBoundingClientRect()`/`offset*`/`client*` are 0) and
+its proxy blocks `defineProperty` on `clientWidth`, so the implementation reads the
+body's content box via `getBoundingClientRect()` (mockable with `vi.spyOn`) rather
+than `clientWidth`.
+
+**Unit-testable (happy-dom, mocked rects):**
+
+- Settings/defaults merge; construction (DOM tree, shade, `aria-expanded`,
+  `instances`); the `(trigger, settings)` param shift and the full
+  `(trigger, body, settings)` signature.
+- `updateBody` header/footer extraction + `has-header`/`has-footer` flags.
+- `show`/`hide`/`toggle` toggling, `show`/`hide`/`submit` events + the settings
+  callbacks, `aria-expanded` flips, `activeHUDs` membership, `closeOtherHUDs`.
+- Layer add/remove via a fresh `UiLayerManager`; the Escape shortcut
+  (`manager.triggerShortcut`); shade-click hide.
+- Focus: `Tab` on the trigger moves focus into the HUD; `hide` restores focus to
+  the trigger when focus was inside (focusable children get `getClientRects`
+  stubbed to look visible, as in the Modal/focusable tests).
+- **Positioning math** with `getBoundingClientRect` mocked on the trigger + body
+  and `windowWidth/Height` set directly: assert the chosen `orientation` and tip
+  class for "room below" (`bottom`), "tall body against the left edge" (`right`),
+  and the `orientations` preference order; assert `updateSizeAndPosition` fires and
+  `hud.style.left/top` get set. `updateSizeAndPosition(true)` is asserted to defer
+  to RAF (the animation module's RAF is mocked onto a manual queue + `flushRaf()`).
+- `updateRecords` change detection; `destroy` cleanup.
+
+**Playground-only (needs real layout/pointer/CSS):** the side actually flipping as
+a trigger nears an edge, the tip rendering against the correct edge, the
+scroll-follow loop tracking the trigger on real scroll/resize, body
+overflow/`overflow: scroll` clamping, and the corner border-radius nicety. See
+playground section 11 ("HUD — anchored popover").
diff --git a/packages/craftcms-garnish/docs/14-hud-impl-notes.md b/packages/craftcms-garnish/docs/14-hud-impl-notes.md
new file mode 100644
index 00000000000..d5612c050a3
--- /dev/null
+++ b/packages/craftcms-garnish/docs/14-hud-impl-notes.md
@@ -0,0 +1,199 @@
+# 14 — `HUD` Implementation Notes
+
+> Status: **Implemented.** Built against `13-hud-design.md` on top of `Base` (docs
+> 01/05), the `UiLayerManager`, and the focus/dom/scroll utils that `Modal` (doc 03)
+> already uses. `HUD` is **Phase 3** of the migration plan and the last
+> `FieldLayoutDesigner` overlay blocker. All gates green in the worktree:
+> `check:types`, `check:format`, `test` (**286 tests**, was 247 — +39), `build`,
+> `playground:build`. `dist/index.js` jQuery references: **0**
+> (`grep -ciE "jquery|\$\(" dist/index.js`).
+
+## What shipped
+
+| File | Change |
+| --- | --- |
+| `src/hud.ts` | **NEW.** `class HUD extends Base<HUDSettings>` — anchored popover, 4-way positioning, tip, scroll-follow, focus cycle, layer + Esc. |
+| `src/index.ts` | Named exports `HUD`, `HUDSettings` (+ `HUDOrientation`, `HUDBodyContents` types); added `HUD` to the `Garnish` namespace object. |
+| `tests/hud.test.ts` | **NEW.** 39 tests: settings/defaults, construction + param-shift, updateBody, show/hide/toggle + events, layer/Esc/shade, submit, focus, positioning math (mocked rects), updateRecords, destroy. |
+| `playground/{index.html,main.ts,styles.css}` | **NEW** section 11 "HUD — anchored popover": five edge-anchored triggers, event logging, HUD/tip CSS. |
+| `README.md`, `docs/06-api-reference.md` | HUD marked **supported**; reference entry + usage example; overlay set noted complete. |
+
+## Exact exported public API
+
+```ts
+export type HUDOrientation = 'top' | 'bottom' | 'left' | 'right';
+export type HUDBodyContents =
+  | string | Node | Node[] | NodeListOf<Node> | null | undefined;
+
+export interface HUDSettings extends GarnishBaseSettings {
+  shadeClass: string; hudClass: string; tipClass: string; bodyClass: string;
+  headerClass: string; footerClass: string; mainContainerClass: string; mainClass: string;
+  orientations: HUDOrientation[];
+  triggerSpacing: number; windowSpacing: number; tipWidth: number;
+  minBodyWidth: number; minBodyHeight: number;
+  withShade: boolean;
+  onShow: HUDCallback; onHide: HUDCallback; onSubmit: HUDCallback;
+  closeBtn: ElementInput | null;
+  listenToMainResize: boolean; showOnInit: boolean; closeOtherHUDs: boolean;
+  hideOnEsc: boolean; hideOnShadeClick: boolean;
+}
+
+export class HUD extends Base<HUDSettings> {
+  static instances: HUD[];
+  static activeHUDs: Record<string, HUD>;
+  static readonly tipClasses: Record<HUDOrientation, string>;
+  static readonly defaults: HUDSettings;
+
+  $trigger; $fixedTriggerParent; $hud; $tip; $body; $header; $footer;
+  $mainContainer; $main; $shade; $nextFocusableElement;   // HTMLElement | null
+  showing: boolean; orientation: HUDOrientation | null; tipClass: string | null;
+  windowWidth; windowHeight; scrollTop; scrollLeft; mainWidth; mainHeight;
+  spWidth; spHeight; spScrollTop; spScrollLeft;            // number | null
+
+  constructor(trigger: ElementInput, bodyContents?: HUDBodyContents | Partial<HUDSettings>, settings?: Partial<HUDSettings>);
+
+  updateBody(bodyContents: HUDBodyContents): void;
+  show(ev?: Event): void;
+  showContainer(): void;
+  onShow(): void;
+  updateRecords(): boolean;
+  updateSizeAndPosition(force?: boolean | Event): void;
+  updateSizeAndPositionInternal(): void;
+  hide(): void;
+  hideContainer(): void;
+  onHide(): void;
+  toggle(): void;
+  submit(): void;
+  onSubmit(): void;
+  override destroy(): void;
+}
+export default HUD;
+```
+
+Private: `_handleSubmit`, `_scrollContainerScrollTop`, `_scrollContainerScrollLeft`,
+`_setRadius`. Module-private helpers: `appendContent`, `jQueryOffset`,
+`getContentWidth`, `getContentHeight`. Events: `show`, `hide`, `submit`,
+`updateSizeAndPosition`, `destroy`.
+
+## What the `FieldLayoutDesigner` consumer needs (the real contract)
+
+`FieldLayoutDesigner.js` (~line 505) does:
+
+```js
+const hud = new Garnish.HUD(this.$addBtn, {
+  hudClass: 'hud fld-library-hud cp-legacy',
+  listenToMainResize: false,
+  showOnInit: false,
+  orientations: ['right', 'bottom', 'left'],
+});
+hud.on('show', () => { this.designer.$libraryContainer.appendTo(hud.$main); ... });
+hud.on('hide', () => { this.$addBtn.focus(); });
+this.$addBtn.on('activate', () => { hud.show(); });
+```
+
+The modern HUD covers all of it:
+
+- **`new HUD(trigger, settings)` param shift** — the 2nd-arg plain object is treated
+  as settings (no body contents). ✔
+- **`hudClass` multi-class string** — assigned via `el.className`, so
+  `'hud fld-library-hud cp-legacy'` lands as three classes. ✔
+- **`listenToMainResize: false`, `showOnInit: false`, `orientations`** — honored. ✔
+- **`hud.$main`** — a raw `HTMLElement` the consumer appends into. Under compat,
+  jQuery `$(hud.$main)` / `.appendTo(hud.$main)` still works because jQuery accepts a
+  DOM element. ✔
+- **`hud.on('show'|'hide', …)`** + **`hud.show()`** — the event system + method. ✔
+- **`$addBtn.on('activate', …)` → `hud.show()`** — the consumer wires that; the HUD
+  also flips the trigger's `aria-expanded` on show/hide. ✔
+
+## Deviations from legacy `HUD.js` (and why)
+
+1. **No fade / no Velocity.** The shipped legacy `HUD.js` does **not** use Velocity —
+   `showContainer`/`hideContainer` are jQuery `.show()`/`.hide()` (display toggles),
+   and `showOnInit` just sets `opacity` 0→1 around the first positioning pass. The
+   migration-plan table (doc 00) lists `.velocity()` as a HUD jQuery-removal, but
+   that does not match the current source, so there is **no Velocity→WAAPI
+   conversion** here. We port the display toggles to `style.display = 'block'` /
+   `'none'` and keep the opacity-0-until-positioned flicker guard. (If a fade is
+   wanted later, reuse `Modal._fade` — but that would be a new feature, not parity.)
+
+   **`showContainer` must set an explicit `display`, not `''`.** The CP stylesheet
+   defaults `.hud` (and `.hud-shade:not(.visible)`) to `display: none`, so jQuery
+   `.show()` resolved that to an explicit inline `display: block`. Clearing the inline
+   value (`style.display = ''`) would let the element fall back to the cascade —
+   `display: none` — and the HUD would stay invisible even though it's in the DOM and
+   fully populated. Both `showContainer()` and the shade reveal in `show()` therefore
+   set `style.display = 'block'`; `hideContainer()` sets `'none'`. (Inline `block`
+   outranks the class-based `none` rule, so this is robust regardless of which
+   stylesheet defines `.hud`.)
+
+2. **`$body.width()/.height()` → rect-minus-box, not `clientWidth`.** jQuery
+   `.width()/.height()` is the content box. The port computes it from
+   `getBoundingClientRect()` minus computed padding **and** border (`getContentWidth`/
+   `getContentHeight`) rather than `clientWidth - padding`. Reason: identical result
+   in a real browser, **and** it stays mockable in happy-dom, whose proxy throws on
+   `Object.defineProperty(el, 'clientWidth', …)` but allows `vi.spyOn(el,
+   'getBoundingClientRect')`.
+
+3. **Setting body/HUD width via `style.width` directly.** Legacy `$hud.width(n)` /
+   `$mainContainer.height(n)` go through jQuery's box-model-aware setters. The port
+   sets `style.width`/`style.height` in px. For the CP's content-box HUD this matches;
+   for a border-box HUD the clamp would be off by padding+border. This only affects
+   the rarely-hit overflow-clamp branch and is layout-/playground-verified.
+
+4. **Window size = `window.innerWidth/innerHeight`** (matching the `Modal` port),
+   where legacy used `$(window).width()/.height()` (= `documentElement.clientWidth`,
+   i.e. excluding the scrollbar). The difference is the scrollbar width (~15px) and
+   only shifts the viewport-edge clamp slightly; consistent with `Modal`. Documented
+   here rather than re-deriving the jQuery value.
+
+5. **`tap,click` → `click` on the shade.** No `tap` synthetic event exists in the
+   modern core (it's a touch alias). The shade dismiss binds `click`; on touch
+   devices a tap dispatches `click`, so behavior is preserved.
+
+6. **`activeHUDs` keyed by the instance namespace.** Legacy used `this._namespace` as
+   the key in the `Garnish.HUD.activeHUDs` object; the port keeps that exactly
+   (`HUD.activeHUDs[this._namespace]`). `destroy()` additionally `delete`s the
+   `activeHUDs` entry (legacy did not) so `closeOtherHUDs` can never call `.hide()` on
+   a destroyed instance — a small, safe hardening.
+
+7. **`$.data('hud', this)` → `WeakMap`.** A module-level `WeakMap<Element, HUD>`
+   (`hudElements`) mirrors `Modal`'s `containerModals`. Nothing in core reads it yet
+   (legacy didn't either), but it's kept for parity and cleared in `destroy`.
+
+8. **Fixed-ancestor walk uses native `offsetParent`.** `$parent.offsetParent()` +
+   `nodeName !== 'HTML'` → a `while` over `el.offsetParent`, checking
+   `getComputedStyle(parent).position === 'fixed'`. `offsetParent` returns `null` for
+   detached/hidden trees, which terminates the loop naturally.
+
+## happy-dom / testing caveats (for the next engineer)
+
+- **No layout.** `getBoundingClientRect()`, `offset*`, and `client*` are all 0. The
+  positioning tests `vi.spyOn(trigger, 'getBoundingClientRect')` and the body's rect,
+  and set `hud.windowWidth/windowHeight` directly before calling
+  `updateSizeAndPositionInternal()` (which reads those records, not `updateRecords`).
+- **`defineProperty` on `clientWidth` throws** under happy-dom's proxy — hence
+  deviation #2 (measure via the mockable `getBoundingClientRect`).
+- **RAF is mocked onto a manual queue** (as in the drag tests) so
+  `updateSizeAndPosition(true)` is observably *deferred*; `flushRaf()` runs the
+  positioning pass. Calling `updateSizeAndPositionInternal()` directly skips the queue
+  for the math assertions.
+- **Focusable elements need visible layout boxes** — `getClientRects` is stubbed on
+  focusable children (`makeVisible`) so `getFocusableElements`/`getKeyboardFocusableElements`
+  see them, matching the Modal/focusable tests.
+- **`<form>` proxy identity.** happy-dom hands back a *distinct* proxy when you reach
+  a `<form>` via `parentElement`, so the tree-shape test asserts nesting with a
+  selector from `$hud` (`form.body > .main-container > .main`) instead of node
+  identity.
+
+## Playground-only (NOT unit-tested — needs real layout/pointer/CSS)
+
+- The side actually flipping as a trigger nears a viewport edge (the visible
+  orientation pick), and the tip rendering against the correct edge.
+- The scroll-follow loop tracking the trigger on real scroll/resize (and the
+  fixed-trigger `position: fixed` branch).
+- Body overflow → `overflow-x/y: scroll` clamping when content exceeds the clearance.
+- The corner border-radius nicety near the tip.
+
+See playground **section 11** ("HUD — anchored popover"): five triggers anchored near
+different edges of a bounded arena, each toggling a HUD that logs
+`show`/`hide`/`updateSizeAndPosition` (with the chosen orientation).
diff --git a/packages/craftcms-garnish/docs/15-disclosuremenu-design.md b/packages/craftcms-garnish/docs/15-disclosuremenu-design.md
new file mode 100644
index 00000000000..d3f1493eb6b
--- /dev/null
+++ b/packages/craftcms-garnish/docs/15-disclosuremenu-design.md
@@ -0,0 +1,220 @@
+# 15 — `DisclosureMenu` Design
+
+> Phase 3 of the migration plan (doc 00): the disclosure dropdown/menu. **HIGH**
+> difficulty — the largest remaining UI component (~1,008 LOC). The risk is the
+> combination of anchored positioning, full keyboard nav + type-ahead search,
+> focus management, and the item/group builder surface that ~19 CP sites depend
+> on.
+>
+> `DisclosureMenu` extends `Base` and reuses the overlay infrastructure already
+> shipped: the `UiLayerManager` (layer stacking + the Escape shortcut), the
+> focus/focusable utilities, the native DOM/scroll utils that replace jQuery, and
+> the WAAPI fade approach `Modal` uses. It is **not** a `HUD` subclass — the menu
+> panel is **pre-existing markup** referenced by the trigger's `aria-controls`,
+> not a tree the component builds.
+
+## 1. What a DisclosureMenu is
+
+A disclosure menu attaches a **menu panel** to a **trigger** button. It:
+
+1. Resolves the panel from the trigger's `aria-controls` id (or the trigger's
+   next sibling), moves it to the end of `<body>`, and toggles it on click.
+2. Anchors the panel **below** the trigger when there's room, flipping **above**
+   when there isn't, and aligns it **left / center / right** (from
+   `data-align`) within the viewport — repositioning on scroll/resize.
+3. Manages **keyboard navigation** (Up/Down/Left/Right move between items; Tab
+   cycles out to the trigger / the next focusable element) and **type-ahead
+   search** (printable keys focus the first item whose text matches the buffer).
+4. Manages **focus**: focuses the first item on show and restores focus to the
+   trigger on hide.
+5. Registers a **UI layer** + an **Escape** shortcut via the shared
+   `UiLayerManager`, like `Modal`/`HUD`, and dismisses on an **outside
+   mousedown**.
+6. Exposes **item/group builders** (`addItem` / `addItems` / `addGroup` /
+   `addHr` / `removeItem` / …) consumers use to populate the panel
+   programmatically.
+
+Unlike `HUD`, show is **instant** (legacy only animates the *hide*): show adds
+the `visible` class + `opacity: 1`; hide fades the panel out via the Web
+Animations API (`.velocity('fadeOut')` → WAAPI), gated on `prefersReducedMotion`.
+
+## 2. Public contract
+
+### Constructor
+
+```ts
+new DisclosureMenu(trigger: ElementInput, settings?: Partial<DisclosureMenuSettings>)
+```
+
+- `trigger` is coerced to a single `HTMLElement` via `getElement` (the native
+  replacement for `$(trigger)`). It must carry `aria-controls` pointing at the
+  panel, or have the panel as its next sibling.
+- **Param shift: N/A.** Unlike `Modal`/`HUD`, the legacy `init(trigger, settings)`
+  has no body-contents argument, so there is no plain-object first-arg shift. The
+  only constructor flexibility is `ElementInput` coercion of the trigger (a
+  selector string / element / element list).
+- On construction the menu resolves + relocates the panel, sets
+  `data-disclosure-trigger` on the trigger, defaults `aria-expanded="false"`,
+  captures the alignment element, wires its listeners, optionally adds a search
+  input, and registers itself in `DisclosureMenu.instances`. A second
+  construction on the same trigger **warns and bails** (legacy
+  double-instantiation guard).
+
+### Settings (`DisclosureMenuSettings`) + defaults
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `position` | `null` | `'below'` pins the panel below regardless of clearance; any other value lets the clearance logic pick above/below. |
+| `windowSpacing` | `5` | Min gap (px) between the panel and the viewport edge. |
+| `withSearchInput` | `false` | Render a search input that filters items live. Also enabled when the panel carries `data-with-search-input`. |
+
+### Public properties
+
+`$trigger`, `$container`, `$alignmentElement`, `$nextFocusableElement`,
+`$searchInput` — all `HTMLElement | null`, keeping the legacy `$`-prefixed names
+for consumer parity. `searchStr: string`, `clearSearchStrTimeout`,
+`infoIconActivated: boolean`.
+
+### Methods + overridable hooks
+
+| Member | Description |
+| --- | --- |
+| `show()` / `hide()` | Show / hide; no-op if already in that state (or, for show, if the trigger is `.disabled`). |
+| `handleTriggerClick()` | Toggle (re-captures the alignment element first). |
+| `isExpanded()` | Whether `aria-expanded === 'true'`. |
+| `setContainerPosition()` | The above/below + left/center/right positioning pass (also a scroll/resize handler). |
+| `captureAlignmentElement()` | (Re)resolve the `data-align-to` descendant (or the trigger). |
+| `focusElement(el \| 'prev' \| 'next')` | Focus a specific element or move within the menu's focusables. |
+| `handleKeypress(ev)` | Arrows / Tab cycle / type-ahead (bound to the container). |
+| `handleMousedown(ev)` | Outside-click dismissal. |
+| `addItem` / `addItems` / `createItem` / `addList` / `addGroup` / `addHr` | Item/group builders. |
+| `toggleItem` / `showItem` / `hideItem` / `toggleGroup` / `removeItem` | Item visibility. |
+| `updateVisibility` / `hasVisibleItems` / `getFirstDestructiveGroup` / `isPadded` | Visibility/query helpers. |
+| `clearSearchStr()` | Reset the type-ahead buffer + timeout. |
+| `destroy()` | Drop registrations, remove from `instances`, base teardown. |
+
+### Statics
+
+`DisclosureMenu.instances: DisclosureMenu[]`, `DisclosureMenu.defaults`,
+`DisclosureMenu.getInstance(el)` (reads the trigger/container → instance
+`WeakMap`, the native replacement for `$el.data('disclosureMenu')`).
+
+### Events
+
+`beforeShow`, `show`, `hide`, and the base `destroy`. **Item selection is
+per-item:** each item's `onActivate` / `callback` runs on the item's `activate`
+event, after which the menu hides. There is no menu-level `optionselect` event
+(that belongs to the legacy `MenuBtn`/`Menu`, not `DisclosureMenu`).
+
+## 3. The positioning algorithm
+
+Run in `setContainerPosition()` (also wired as the scroll/resize handler). A
+faithful port of the legacy clearance math:
+
+1. **Measure.** Viewport (`window.innerWidth/innerHeight`, `window.scrollX/Y`);
+   the alignment element's document-relative offset (rect + scroll, jQuery
+   `.offset()` parity) and border-box size (`getOuterWidth/Height`).
+2. **Min width.** Set the panel's `minWidth` to the alignment width minus the
+   panel's own horizontal padding+border (so the panel is at least as wide as the
+   trigger). Clamp `maxWidth` to the viewport when the panel overflows it.
+3. **Above vs below.** Compute `topClearance` / `bottomClearance`. Place **below**
+   (top = alignment bottom) when `position === 'below'`, or there's room below, or
+   above is even tighter; otherwise place **above** (top = alignment top −
+   min(menuHeight, topClearance − windowSpacing)). Either way set `maxHeight` to
+   the chosen side's clearance − `windowSpacing`.
+4. **Horizontal align.** Read `data-align` (`left` default / `center` / `right`).
+   Center when the panel fills the viewport or `align === 'center'`; otherwise
+   compute left/right clearance and pick `_alignLeft` / `_alignRight` /
+   `_alignCenter`, each clamped to `>= 0`.
+
+## 4. Keyboard-nav + type-ahead model
+
+- **Arrows.** Right/Down → `focusElement('next')`; Left/Up → `focusElement('prev')`
+  — move within `getFocusableElements(container)` from the currently-focused item.
+- **Tab cycle.** On the first focusable, Shift-Tab returns to the trigger; on the
+  last, Tab moves to `$nextFocusableElement` (the focusable after the trigger in
+  the document, wired on show — Shift-Tab on *it* returns to the panel's last
+  item). Tabbing on the **trigger** while expanded moves focus into the panel.
+- **Type-ahead.** A printable key (regex `/^[^ ]$/`, plus space once the buffer is
+  non-empty) appends to `searchStr`. The first `<li>` whose cached **searchText**
+  `startsWith(searchStr)` is focused. The searchText is the `<li>`'s text with
+  nested `<svg>`s stripped, lowercased and `trimStart()`ed, cached per `<li>` in a
+  `WeakMap` (legacy `$o.data('searchText')`). A 1s timeout clears the buffer.
+- **Search input** (`withSearchInput`): typing filters `<li>`s by substring
+  (toggling the `filtered` class), un-filters items under a matching `<h3>`, then
+  re-runs `updateVisibility()` + `setContainerPosition()`. Esc clears it; Return
+  is swallowed so it doesn't submit a form.
+
+## 5. Focus management
+
+- **On show:** focus the first `getFocusableElements(container)` item, or — when
+  the panel has none — make the container itself focusable (`tabindex="-1"`) and
+  focus it.
+- **On hide:** if focus is inside the panel (`focusIsInside`), restore it to the
+  trigger; drop the `$nextFocusableElement` Shift-Tab listener.
+
+## 6. jQuery removals → modern utils
+
+| Legacy (`DisclosureMenu.js`) | Modern replacement |
+| --- | --- |
+| `$(trigger)` | `getElement(trigger)` |
+| `$('#' + id)` / `.next()` | `document.getElementById` / `nextElementSibling` |
+| `.attr()` / `.data()` (DOM data) | `getAttribute` / `setAttribute` |
+| `.data('disclosureMenu', this)` | module-level `WeakMap` + `DisclosureMenu.getInstance` |
+| `$o.data('searchText')` | module-level `WeakMap<HTMLElement, string>` |
+| `.find(':focusable')` / `:focusable:first/last` | `getFocusableElements` (`utils/focusable`) |
+| `$component.is(':focusable')` | `isFocusable` (`utils/focusable`) |
+| `Garnish.getFocusedElement()` + `$.contains` | `focusIsInside` (`utils/focus`) |
+| `.scrollParent()` | `getScrollParent` (`utils/scroll`) |
+| `$alignmentElement.offset()` | inline `rect.top + scrollY` (jQuery `.offset()` parity) |
+| `.outerWidth()` / `.outerHeight()` | `getOuterWidth` / `getOuterHeight` (`utils/dom`) |
+| `$container.width()` (content box) | rect − padding − border (`getContentWidth`) |
+| `.velocity('fadeOut', …)` | the Web Animations API (gated on `prefersReducedMotion`) |
+| `.velocity('stop')` | the tracked animation's `cancel()` |
+| `.find/closest/filter/parent/children/eq` | native `querySelector(All)` / `closest` / `children` |
+| `.prevUntil/.nextUntil` | a native `siblingsUntil(el, stop, dir)` walk |
+| `Garnish.$win/$doc/$bod/$scrollContainer` | `win` / `doc` / `bod` / `globals.scrollContainer` |
+| `Garnish.uiLayerManager` | `getUiLayerManager()` (`managers/registry`) |
+| `Garnish.isCtrlKeyPressed` | `isCtrlKeyPressed` (`utils/env`) |
+| `Craft.getUrl` / `Craft.t` / `Craft.initUiElements` | optional-global accessors (`getCraft()`), graceful fallbacks |
+| `$(el).formsubmit()` | **omitted** — the `formsubmit` class + `data-action` are still set (doc 16) |
+
+## 7. Testing strategy
+
+happy-dom has no layout (`getBoundingClientRect`/`offset*`/`getClientRects` are
+0/empty) and no `element.animate`. The fade therefore finalizes synchronously
+(hide is observable immediately — no RAF/animation mock needed). Focusable
+elements get `getClientRects` stubbed to look visible (`makeVisible`, as in the
+Modal/HUD/focusable tests).
+
+**Unit-testable (happy-dom, mocked rects):**
+
+- Settings/defaults merge; container resolution (`aria-controls` + next-sibling),
+  the no-container throw, `data-disclosure-trigger`, `aria-expanded` defaulting,
+  `instances`/`getInstance` registration, the double-instantiation warn+bail,
+  selector-string trigger coercion, panel relocation to `<body>`.
+- `show`/`hide`/`handleTriggerClick` toggling, `beforeShow`/`show`/`hide` events,
+  `aria-expanded` flips, the `.disabled` trigger guard.
+- Layer add/remove via a fresh `UiLayerManager`; the Escape shortcut.
+- Focus: first-item focus on show, container fallback, trigger restore on hide.
+- Keyboard nav (Arrow Up/Down between items, Shift-Tab → trigger, Tab on the
+  trigger → into the panel) and type-ahead (single + accumulated buffer).
+- Outside-mousedown dismissal vs. inside-mousedown no-op.
+- Item building: `addItem` (button/link inference), selected/destructive/disabled
+  flags, `formsubmit` + `data-action`, the unsupported-config throw, `addGroup`
+  heading + last-group fill, `getFirstDestructiveGroup`, `removeItem` empties the
+  group, `addHr`, `hasVisibleItems`.
+- Item selection: `onActivate` / `callback` runs on `activate`, then the menu
+  hides (a tick later — fake timers).
+- Search input: build-on-setting + `data-with-search-input`, live filtering +
+  clearing, Return-swallow.
+- Positioning math with `getBoundingClientRect`/`offset*` mocked: below when
+  there's room, above when there isn't, `position: 'below'` override; `top`/`left`
+  get set.
+- `destroy` cleanup.
+
+**Playground-only (needs real layout/pointer/CSS):** the panel actually flipping
+above as the trigger nears the viewport bottom; left/center/right alignment near
+the edges; the scroll-follow reposition on real scroll/resize; the search-input
+filter visually collapsing empty groups/separators; the fade-out timing. See
+playground **section 12** ("DisclosureMenu — dropdown menu").
diff --git a/packages/craftcms-garnish/docs/16-disclosuremenu-impl-notes.md b/packages/craftcms-garnish/docs/16-disclosuremenu-impl-notes.md
new file mode 100644
index 00000000000..914e7f79f56
--- /dev/null
+++ b/packages/craftcms-garnish/docs/16-disclosuremenu-impl-notes.md
@@ -0,0 +1,217 @@
+# 16 — `DisclosureMenu` Implementation Notes
+
+> Status: **Implemented.** Built against `15-disclosuremenu-design.md` on top of
+> `Base` (docs 01/05), the `UiLayerManager`, the focus/focusable/scroll/dom
+> utils, and the WAAPI fade pattern `Modal` (doc 03) uses. `DisclosureMenu` is
+> **Phase 3** of the migration plan and the largest UI component in the port
+> (~1,008 legacy LOC). All gates green in the worktree: `check:types`,
+> `check:format`, `test` (**336 tests**, of which **49** are new in
+> `tests/disclosure-menu.test.ts`), `build`, `playground:build`. `dist/index.js`
+> jQuery references: **0** (`grep -ciE "jquery|\$\(" dist/index.js`).
+
+## What shipped
+
+| File | Change |
+| --- | --- |
+| `src/disclosure-menu.ts` | **NEW.** `class DisclosureMenu extends Base<DisclosureMenuSettings>` — disclosure dropdown: above/below + left/center/right positioning, keyboard nav + type-ahead, focus management, layer + Esc, outside-click dismissal, optional search input, item/group builders. |
+| `src/index.ts` | Named exports `DisclosureMenu`, `DisclosureMenuSettings` (+ `DisclosureMenuItem`, `DisclosureMenuItemConfig` types); added `DisclosureMenu` to the `Garnish` namespace object. |
+| `tests/disclosure-menu.test.ts` | **NEW.** 49 tests across 12 describe blocks (see doc 15 §7). |
+| `playground/{index.html,main.ts,styles.css}` | **NEW** section 12 "DisclosureMenu — dropdown menu": a static-markup actions menu + an API-built filterable menu with a search input; event + selection logging; menu CSS. |
+| `README.md`, `docs/06-api-reference.md` | DisclosureMenu marked **supported**; reference entry + usage example; Phase-3 status updated. |
+
+## Exact exported public API
+
+```ts
+export interface DisclosureMenuSettings extends GarnishBaseSettings {
+  position: string | null; // 'below' forces below; else clearance picks
+  windowSpacing: number;
+  withSearchInput: boolean;
+}
+
+export interface DisclosureMenuItemConfig {
+  type?: 'button' | 'link'; url?: string; id?: string;
+  selected?: boolean; destructive?: boolean; disabled?: boolean;
+  action?: string; icon?: string | Element | (() => Promise<Element> | Element);
+  iconColor?: string; params?: string | Record<string, unknown>;
+  confirm?: string; redirect?: string; attributes?: Record<string, string>;
+  status?: string; label?: string; html?: string; description?: string;
+  hidden?: boolean;
+  onActivate?: (el: HTMLElement) => void; callback?: (el: HTMLElement) => void;
+}
+export type DisclosureMenuItem = DisclosureMenuItemConfig | Element;
+
+export class DisclosureMenu extends Base<DisclosureMenuSettings> {
+  static instances: DisclosureMenu[];
+  static readonly defaults: DisclosureMenuSettings;
+  static getInstance(el: Element | null | undefined): DisclosureMenu | undefined;
+
+  $trigger; $container; $alignmentElement; $nextFocusableElement; $searchInput; // HTMLElement | null
+  searchStr: string; clearSearchStrTimeout; infoIconActivated: boolean;
+
+  constructor(trigger: ElementInput, settings?: Partial<DisclosureMenuSettings>);
+
+  captureAlignmentElement(): void;
+  addSearchInput(): void;
+  addDisclosureMenuEventListeners(): void;
+  focusElement(component: HTMLElement | 'prev' | 'next'): void;
+  handleMousedown(event: MouseEvent): void;
+  handleKeypress(ev: KeyboardEvent): void;
+  isExpanded(): boolean;
+  handleTriggerClick(): void;
+  show(): void;
+  hide(): void;
+  focusIsInMenu(): boolean;
+  setContainerPosition(): void;
+  clearSearchStr(): void;
+  isPadded(tag?: string): boolean;
+  createItem(item: DisclosureMenuItem): HTMLLIElement;
+  addList(): HTMLUListElement;
+  addItem(item: DisclosureMenuItem, ul?: HTMLElement | null, prepend?: boolean): HTMLElement;
+  addItems(items: DisclosureMenuItem[], ul?: HTMLElement | null): void;
+  addHr(before?: Element | null): HTMLHRElement;
+  getFirstDestructiveGroup(): HTMLUListElement | undefined;
+  addGroup(heading?: string | null, addHrs?: boolean, before?: Element | null): HTMLUListElement;
+  toggleItem(el: HTMLElement, show?: boolean): void;
+  showItem(el: HTMLElement): void;
+  hideItem(el: HTMLElement): void;
+  toggleGroup(group: HTMLElement): void;
+  removeItem(el: HTMLElement): void;
+  updateHrVisibility(): void;  // @deprecated → updateVisibility
+  updateVisibility(): void;
+  hasVisibleItems(): boolean;
+  override destroy(): void;
+}
+export default DisclosureMenu;
+```
+
+Module-private helpers: `getCraft`, `craftUrl`, `craftT`, `jQueryOffset`,
+`getContentWidth`, `isVisibleItem`, `siblingsUntil`. Module state: `menuElements`
+(trigger/container → instance `WeakMap`), `searchTextCache` (`<li>` → searchText
+`WeakMap`), `itemIdCounter`. Events: `beforeShow`, `show`, `hide`, `destroy`.
+
+## What the CP consumers need (the real contract)
+
+`DisclosureMenu` is heavily used across the CP (~19 sites:
+`NestedElementManager`, `EditableTable`, `BaseElementIndex`, `EntryIndex`,
+`CustomizeSourcesModal`, `MatrixInput`, …). The two call shapes are:
+
+```js
+new Garnish.DisclosureMenu($menuBtn);
+new Garnish.DisclosureMenu($trigger, settings);
+```
+
+and the consumers then drive it via:
+
+- the **item/group builders** — `disclosureMenu.addItem({...})`,
+  `.addItems(...)`, `.addGroup()`, `.addHr()`, `.removeItem(el)` — all ported. ✔
+- the **instance lookup** — legacy `$el.data('disclosureMenu')`. The modern
+  equivalent is the trigger/container `WeakMap` read via
+  `DisclosureMenu.getInstance(el)`. Bridging the jQuery `.data('disclosureMenu')`
+  *accessor* (so existing `$btn.data('disclosureMenu')` keeps resolving) is the
+  **compat layer's** job, not this component's — out of scope for this port, but
+  the instance is registered for both the trigger and the container so the bridge
+  has something to read. ✔
+- `.show()` / `.hide()` / `.isExpanded()` and the `show`/`hide` events. ✔
+
+The modern public contract covers all of the above, so the legacy `.extend()`
+path works once compat wraps the class (compat picks up any class on the
+`Garnish` namespace automatically — doc, `compat.ts` §"Known core classes").
+
+## Deviations from legacy `DisclosureMenu.js` (and why)
+
+1. **Show is instant, hide fades (faithful) — but via WAAPI, not Velocity.** The
+   legacy `show` does `velocity('stop').addClass('visible').css('opacity', 1)` (no
+   animation), and `hide` does `velocity('fadeOut', {duration: FX_DURATION})`. The
+   port keeps that asymmetry: show adds `visible` + `opacity: 1` instantly; hide
+   animates opacity 1→0 over 200ms with `element.animate`, then strips `visible` +
+   inline display. Gated on `prefersReducedMotion` / environments without
+   `element.animate` (happy-dom), which finalize synchronously. `.velocity('stop')`
+   → the tracked animation's `cancel()`.
+
+2. **Hide reordered: bookkeeping before the fade.** Legacy starts the (async)
+   `velocity('fadeOut')` *first*, then sets `aria-expanded=false`, restores focus,
+   etc.; the velocity `complete` callback runs later. Because the WAAPI fade
+   finalizes **synchronously** under happy-dom, the port does all the synchronous
+   bookkeeping (aria, focus restore, listener/layer teardown, search clear, the
+   `hide` event) **before** starting the fade. Behaviorally equivalent (the
+   focus/aria work always ran before the panel was actually removed) and robust to
+   the synchronous-finalize path.
+
+3. **`Craft.*` via an optional global.** Legacy `createItem`/`addSearchInput`/init
+   call `Craft.getUrl`, `Craft.t`, and `Craft.initUiElements` directly. The modern
+   core is Craft-free, so these route through a `getCraft()` accessor
+   (`globalThis.Craft`) with graceful fallbacks: `craftUrl(url)` returns the url
+   unchanged when Craft is absent; `craftT(message)` returns the message; the
+   slideout `initUiElements` is a no-op. In the CP (via compat) the real Craft is
+   used; standalone (tests/playground) the fallbacks apply.
+
+4. **`$(el).formsubmit()` omitted.** The legacy item builder calls jQuery's Craft
+   `formsubmit` plugin to register action items. Calling it (or even *naming*
+   jQuery) would re-introduce jQuery and fail the `dist/index.js` jQuery-free gate
+   (the literal `jQuery` / `$(` strings are what the grep matches). The port still
+   sets the `formsubmit` class + `data-action` / `data-form="false"` /
+   `data-params` / `data-redirect` / `data-confirm` attributes, which is the markup
+   the CP's global form-submit machinery keys off; only the explicit jQuery
+   registration call is dropped. **Playground/CP-verified concern**, not unit
+   tested.
+
+5. **`$(el).data('searchText')` → `WeakMap`.** The per-`<li>` type-ahead text cache
+   is a module-level `WeakMap<HTMLElement, string>` (`searchTextCache`) instead of
+   jQuery data. Built identically (clone the `<li>`, strip `<svg>`s, lowercase +
+   `trimStart`).
+
+6. **Generated item ids use a counter, not `Math.random`.** Legacy ids are
+   `menu-item-${Math.floor(Math.random() * 1000000)}`. The port uses a monotonic
+   module counter (`menu-item-1`, `-2`, …) — deterministic and collision-free.
+
+7. **The scroll-parent scroll listener is removed on hide.** Legacy `show` adds a
+   `scroll` listener on the trigger's `scrollParent` but `hide` only removes the
+   `$scrollContainer` + `$win` listeners (the scroll-parent one leaks until
+   destroy). The port tracks `_scrollParent` and removes its listener on hide — a
+   small, safe hardening (mirrors the HUD port's `activeHUDs` delete-on-destroy).
+
+8. **`maxWidth` reset before measuring.** `setContainerPosition` clears any prior
+   `maxWidth` clamp before measuring the panel's natural width, so a previous
+   viewport-overflow clamp doesn't shrink the next measurement. Legacy left the
+   stale `maxWidth` in place. Only affects the rarely-hit viewport-overflow branch.
+
+9. **Window size = `window.innerWidth/innerHeight`** (matching the `Modal`/`HUD`
+   ports), where legacy used `$(window).width()/.height()`
+   (= `documentElement.clientWidth`, excluding the scrollbar). The difference is
+   the scrollbar width (~15px) and only shifts the viewport-edge clamp slightly.
+
+10. **No `optionselect` / `onOptionSelect`.** Selection is per-item (`onActivate` /
+    `callback` on the item's `activate` event, then `hide`), exactly as in legacy
+    `DisclosureMenu.js`. The menu-level `optionselect` event some CP code uses
+    belongs to the separate legacy `MenuBtn`/`Menu` widgets, not `DisclosureMenu`.
+
+## happy-dom / testing caveats (for the next engineer)
+
+- **No layout.** `getBoundingClientRect()`, `offset*`, and `getClientRects()` are
+  0/empty. The positioning tests `vi.spyOn(el, 'getBoundingClientRect')` and define
+  `offsetWidth/Height` on the trigger + container (`mockRect`); the default
+  happy-dom viewport (1024×768) is used as-is.
+- **No `element.animate`.** The fade finalizes synchronously, so `hide()` is
+  observable immediately — no RAF/animation mock is needed (unlike the HUD test,
+  which mocks RAF for the deferred positioning pass; `DisclosureMenu` positions
+  synchronously in `setContainerPosition`).
+- **Focusable elements need visible layout boxes** — item buttons + the trigger
+  get `getClientRects` stubbed (`makeVisible`) so `getFocusableElements` sees them,
+  matching the Modal/HUD/focusable tests.
+- **Item `activate`.** `addListener(el, 'activate', …)` installs the synthetic
+  `activate` source; dispatching a plain `new CustomEvent('activate')` on the item
+  invokes the handler. The subsequent `hide()` is scheduled `setTimeout(…, 1)`, so
+  the selection tests use fake timers + `advanceTimersByTime(1)`.
+
+## Playground-only (NOT unit-tested — needs real layout/pointer/CSS)
+
+- The panel actually flipping above as the trigger nears the viewport bottom, and
+  the left/center/right alignment near the edges.
+- The scroll-follow reposition on real scroll/resize.
+- The search-input filter visually collapsing empty groups / `<hr>`s / headings.
+- The fade-out timing, and the `formsubmit` action-item submission (CP-only).
+
+See playground **section 12** ("DisclosureMenu — dropdown menu"): a static-markup
+actions menu (groups, a disabled item, a destructive item) and an API-built
+filterable menu (`withSearchInput`, 10 items added via `addItems`), each logging
+`beforeShow`/`show`/`hide` + the selected item.
diff --git a/packages/craftcms-garnish/docs/17-storybook-notes.md b/packages/craftcms-garnish/docs/17-storybook-notes.md
new file mode 100644
index 00000000000..1e12cfaf0e1
--- /dev/null
+++ b/packages/craftcms-garnish/docs/17-storybook-notes.md
@@ -0,0 +1,137 @@
+# 17 — Storybook notes
+
+The interactive demos for `@craftcms/garnish` live in **Storybook**, replacing the
+old single-page Vite `playground/`. This doc covers the setup, how to add a story
+when you port a new component, and the shared event-log helper.
+
+## Why Storybook, and why `html-vite`
+
+The playground had grown to 12 demo sections in one ~900-line `main.ts`. Splitting
+it into one story file per component keeps each component's demos isolated,
+navigable, and documented (autodocs).
+
+Garnish widgets are **imperative** — `new Modal(container)`,
+`new DisclosureMenu(trigger)`, `new HUD(trigger, body)` — operating on plain DOM,
+**not** web components. So we use the **`@storybook/html-vite`** renderer: each
+story's `render()` returns an `HTMLElement` and instantiates the Garnish class
+inside it. (By contrast, `@craftcms/cp` uses `@storybook/web-components-vite`
+because its components are custom elements.) We otherwise match cp's Storybook:
+version **10.4.1** and the **docs / a11y / themes** addons.
+
+## Layout
+
+```
+packages/craftcms-garnish/
+  .storybook/
+    main.ts        # framework: @storybook/html-vite; stories glob; addons
+    preview.ts     # global parameters + theme decorator; imports preview.css
+    preview.css    # demo globals migrated from the old playground/styles.css
+  stories/
+    _log.ts        # Actions-panel event logger + drag-event wiring + layout helper
+    _helpers.ts    # shared modal-container builders
+    modal.stories.ts
+    focus.stories.ts
+    compat.stories.ts
+    base-drag.stories.ts
+    drag.stories.ts
+    drag-drop.stories.ts
+    drag-sort.stories.ts
+    hud.stories.ts
+    disclosure-menu.stories.ts
+    utilities.stories.ts
+```
+
+Stories live in a **top-level `stories/`** directory (mirroring how `tests/` was
+split out of `src/`), so `src/` stays implementation-only. The stories glob is
+`../stories/**/*.stories.@(ts|mdx)`; helper modules are prefixed with `_` so they
+are imported but never picked up as stories. Each story imports the **real source**
+(`../src/index`, `../src/compat`) — never the built `dist/` — so changes
+hot-reload.
+
+`tsconfig.json` includes `stories` and `.storybook` so `npm run check:types`
+type-checks them; Prettier's globs include them too.
+
+## Scripts
+
+```bash
+npm run dev          # storybook dev -p 6006  (the dev harness)
+npm run storybook    # alias of dev
+npm run build:storybook  # static build (compiles every story — the CI proof)
+```
+
+`vite`/`vitest`/`tsdown` are unchanged; Storybook's `html-vite` builder uses Vite
+under the hood and supplies its own pipeline (there is no package-root
+`vite.config.ts` anymore — it only ever served the playground).
+
+## The event logger (Storybook Actions)
+
+Drag/menu/modal stories surface the events the real widgets fire by logging them
+to Storybook's built-in **Actions** panel (the "Actions" tab in the addons panel),
+rather than a hand-rolled in-canvas panel. `stories/_log.ts` wraps
+`storybook/actions` and exports:
+
+- `createEventLog()` → `{log}`. Call `log(tag, message)` from your event handlers;
+  each `tag` becomes a named action so the panel groups events by tag (e.g.
+  `modal`, `drag`, `disclosure`). No DOM panel to mount.
+- `wireDragEvents(log, dragger, tag, label)` — subscribes a dragger's
+  `dragStart`/`drag`/`dragStop` into the log, coalescing the per-RAF-frame `drag`
+  to a single line per gesture so the panel stays readable.
+- `storyLayout(main)` — tags the demo element with `.pg-story` for the global
+  styles; the canvas is just the demo.
+
+The Actions panel is part of Storybook core in 10.x — no `@storybook/addon-actions`
+entry is needed in `.storybook/main.ts`; importing `action` from
+`storybook/actions` is enough.
+
+Typical story shape:
+
+```ts
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {Modal} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+
+const meta: Meta = {title: 'Modal'};
+export default meta;
+type Story = StoryObj;
+
+export const Basic: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    // …build controls, `new Modal(container)`, wire events to `log.log('modal', …)`…
+    return storyLayout(main);
+  },
+};
+```
+
+Use Storybook `args`/`argTypes` controls where they add value — e.g. Modal's
+`hideOnEsc`/`hideOnShadeClick`/`closeOtherModals`, the draggable/resizable
+toggles, HUD `preferredOrientation`, `Drag` drop mode, and DisclosureMenu
+`withSearchInput`.
+
+### Imperative widgets and the DOM
+
+Modals, HUDs, and disclosure menus position themselves `fixed`/`absolute` and
+move their own elements to `document.body`, so the demo containers are appended to
+`document.body` rather than the story canvas (see `_helpers.ts`). `DisclosureMenu`
+resolves its panel from the trigger's `aria-controls`; since a story builds its
+DOM detached before Storybook mounts it, keep the menu panel as the trigger's
+**next element sibling** with a **unique id** (the disclosure story uses a counter)
+so resolution works and re-renders don't collide with panels already moved to
+`<body>`.
+
+## Adding a story for a new component
+
+When you port a new component, **add `stories/<name>.stories.ts`** instead of a
+playground section:
+
+1. Create `stories/<component>.stories.ts` with a default `Meta` (`title`) and one
+   or more `StoryObj` exports.
+2. In each `render()`, build the demo DOM, instantiate the component from
+   `../src/index`, and (if it fires events worth showing) wire them into a
+   `createEventLog()` panel via `storyLayout`.
+3. Reuse the `.pg-*` classes in `.storybook/preview.css`; add component-specific
+   globals there if the widget renders its own elements (shade, tip, menu panel).
+   Keep `touch-action: none` on any drag/menu handles.
+4. Prefer `args`/`argTypes` over multiple near-duplicate buttons when a setting is
+   the thing being demonstrated.
diff --git a/packages/craftcms-garnish/package.json b/packages/craftcms-garnish/package.json
new file mode 100644
index 00000000000..4f153b0879a
--- /dev/null
+++ b/packages/craftcms-garnish/package.json
@@ -0,0 +1,77 @@
+{
+  "name": "@craftcms/garnish",
+  "version": "0.0.0",
+  "description": "Modern, tree-shakeable TypeScript rewrite of Craft CMS's Garnish UI library",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/craftcms/npm-packages.git"
+  },
+  "keywords": [
+    "craftcms",
+    "garnish",
+    "ui"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "build:watch": "tsdown --watch",
+    "dev": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 6006",
+    "build:storybook": "storybook build",
+    "test": "vitest run",
+    "test:dev": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "format": "prettier --write ./src ./tests ./stories ./.storybook",
+    "check:format": "prettier --check ./src ./tests ./stories ./.storybook",
+    "check:types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "lint": "npm run check:types && npm run check:format"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./compat": {
+      "types": "./dist/compat.d.ts",
+      "import": "./dist/compat.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "jquery": "^3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "jquery": {
+      "optional": true
+    }
+  },
+  "author": "Pixel & Tonic, Inc. <support@pixelandtonic.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/craftcms/npm-packages/issues"
+  },
+  "homepage": "https://github.com/craftcms/npm-packages#readme",
+  "devDependencies": {
+    "@storybook/addon-a11y": "^10.4.1",
+    "@storybook/addon-docs": "^10.4.1",
+    "@storybook/addon-themes": "^10.4.1",
+    "@storybook/html-vite": "^10.4.1",
+    "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "happy-dom": "^20.9.0",
+    "storybook": "^10.4.1",
+    "tsdown": "^0.21.10",
+    "typescript": "^6.0.3",
+    "vite": "^7.1.5",
+    "vitest": "^4.1.5"
+  }
+}
diff --git a/packages/craftcms-garnish/src/base.ts b/packages/craftcms-garnish/src/base.ts
new file mode 100644
index 00000000000..86a51a20241
--- /dev/null
+++ b/packages/craftcms-garnish/src/base.ts
@@ -0,0 +1,362 @@
+/**
+ * Garnish base class — native `class extends`, jQuery-free.
+ *
+ * Replaces the legacy Dean Edwards `Base.extend()` + `init()` trampoline. The
+ * `init()` indirection and `this.base()` super-dispatch are intentionally NOT
+ * here — those are the compat layer's job. Subclasses use a real `constructor`
+ * and `super()`.
+ */
+
+import {DomListenerRegistry, type DomListenerOptions} from './dom-listeners';
+import {EventEmitter, type GarnishEventHandler} from './events';
+import {garnishClassBus} from './globals';
+import type {ElementInput, GarnishBaseSettings} from './types';
+
+function makeNamespace(): string {
+  const uuid =
+    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : String(Math.floor(Math.random() * 1000000000));
+  return `.Garnish${uuid}`;
+}
+
+/**
+ * The base class every Garnish component extends — a modern, jQuery-free,
+ * native-`class` replacement for the legacy `Garnish.Base`.
+ *
+ * `Base` provides four facilities to subclasses:
+ *
+ * - **Settings** — a typed, shallow-merged `settings` object (see {@link setSettings}).
+ * - **Object pub/sub** — per-instance events via {@link on} / {@link once} /
+ *   {@link off} / {@link trigger}, plus class-level subscription through the
+ *   `Garnish.on/off/once` proxies.
+ * - **DOM listeners** — namespaced, auto-tracked bindings via
+ *   {@link addListener} / {@link removeListener} / {@link removeAllListeners}
+ *   that are torn down automatically on {@link destroy}.
+ * - **Lifecycle** — {@link enable} / {@link disable} (which gate DOM listeners)
+ *   and {@link destroy}.
+ *
+ * Unlike the legacy library, there is **no `init()` trampoline and no
+ * `this.base()`** — subclasses use a real `constructor` + `super()` and call
+ * `super.method()` for super-dispatch. Those legacy affordances live only in the
+ * opt-in `@craftcms/garnish/compat` layer.
+ *
+ * @typeParam S - The subclass's settings shape; defaults to {@link GarnishBaseSettings}.
+ *
+ * @example Defining a component
+ * ```ts
+ * import {Base, type GarnishBaseSettings} from '@craftcms/garnish';
+ *
+ * interface CounterSettings extends GarnishBaseSettings {
+ *   step: number;
+ * }
+ *
+ * class Counter extends Base<CounterSettings> {
+ *   static defaults: CounterSettings = {step: 1};
+ *   value = 0;
+ *
+ *   constructor(button: HTMLElement, settings?: Partial<CounterSettings>) {
+ *     super();
+ *     this.setSettings(settings, Counter.defaults);
+ *     this.addListener(button, 'click', () => {
+ *       this.value += this.settings!.step;
+ *       this.trigger('change', {value: this.value});
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export abstract class Base<
+  S extends GarnishBaseSettings = GarnishBaseSettings,
+> {
+  /**
+   * The instance's resolved settings (defaults merged with the passed
+   * overrides). `null` until {@link setSettings} has run — most subclasses call
+   * it in their constructor, so guard with `this.settings!` once you know it has.
+   */
+  settings: S | null = null;
+
+  protected _disabled = false;
+
+  /** Per-instance namespace; kept for compat/debugging parity. */
+  protected readonly _namespace: string = makeNamespace();
+
+  /** Object pub/sub registry. */
+  protected readonly _emitter = new EventEmitter<this>(this);
+
+  /** Tracked DOM listener bindings for namespaced removal + bulk teardown. */
+  protected readonly _domListeners: DomListenerRegistry =
+    new DomListenerRegistry(this);
+
+  constructor() {
+    // No init() trampoline. Subclasses do their own setup after super().
+  }
+
+  // --- Settings -------------------------------------------------------------
+
+  /**
+   * Resolve {@link settings} by shallow-merging, in increasing precedence:
+   * any existing `settings`, then `defaults`, then the passed `settings`.
+   *
+   * Matches the legacy `$.extend({}, base, defaults, settings)` precedence — it
+   * is a **shallow** merge, not a deep one. Nested objects are replaced wholesale,
+   * not recursively combined.
+   *
+   * @param settings - Per-instance overrides (highest precedence).
+   * @param defaults - The component's default settings.
+   *
+   * @example
+   * ```ts
+   * this.setSettings(passedSettings, MyComponent.defaults);
+   * // this.settings is now {...defaults, ...passedSettings}
+   * ```
+   */
+  setSettings(settings?: Partial<S>, defaults?: Partial<S>): void {
+    const base = this.settings ?? {};
+    this.settings = Object.assign({}, base, defaults, settings) as S;
+  }
+
+  // --- Object pub/sub -------------------------------------------------------
+
+  /**
+   * Subscribe to one or more instance events.
+   *
+   * The event string follows the legacy grammar: space-separated for multiple
+   * events, with an optional `.namespace` suffix per token
+   * (e.g. `'show hide.myPlugin'`). Namespaces let you remove a related group of
+   * handlers later with {@link off}.
+   *
+   * @param events - Space-separated event name(s), each optionally `.namespaced`.
+   * @param data - Optional per-registration data, merged into the event object
+   *   passed to the handler.
+   * @param handler - The callback, invoked with a {@link GarnishEvent}.
+   *
+   * @example
+   * ```ts
+   * modal.on('show', (ev) => console.log('shown', ev.target));
+   * modal.on('hide.myPlugin', (ev) => cleanup());
+   * modal.off('.myPlugin'); // remove every handler in that namespace
+   * ```
+   */
+  on(events: string, handler: GarnishEventHandler): void;
+  on(
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  on(
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    // Delegate; the emitter handles the overload.
+    (this._emitter.on as (...a: unknown[]) => void)(
+      events,
+      dataOrHandler,
+      handler
+    );
+  }
+
+  /**
+   * Like {@link on}, but the handler is automatically removed after it fires
+   * once (per matched event token).
+   *
+   * @param events - Space-separated event name(s), each optionally `.namespaced`.
+   * @param data - Optional per-registration data merged into the event object.
+   * @param handler - The callback, invoked at most once.
+   */
+  once(events: string, handler: GarnishEventHandler): void;
+  once(
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  once(
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    (this._emitter.once as (...a: unknown[]) => void)(
+      events,
+      dataOrHandler,
+      handler
+    );
+  }
+
+  /**
+   * Unsubscribe from instance events.
+   *
+   * Matching mirrors jQuery's namespaced `.off`: a registration is removed when
+   * its type matches AND (the requested namespace is empty OR the namespaces
+   * match) AND (`handler` is omitted OR is the same function reference).
+   *
+   * - `off('show')` — remove all `show` handlers.
+   * - `off('show', fn)` — remove only `fn`.
+   * - `off('.myPlugin')` — remove every handler registered under that namespace,
+   *   across all event types.
+   *
+   * @param events - Space-separated event name(s), each optionally `.namespaced`.
+   * @param handler - When given, only the matching handler reference is removed.
+   */
+  off(events: string, handler?: GarnishEventHandler): void {
+    this._emitter.off(events, handler);
+  }
+
+  /**
+   * Emit an event. Dispatches first to this instance's handlers (registered via
+   * {@link on} / {@link once}), then to class-level handlers registered through
+   * `Garnish.on(SomeClass, …)` whose target this instance is an `instanceof`
+   * (two-pass dispatch, matching the legacy behavior).
+   *
+   * @param type - The event type (no namespace; namespaces are a subscribe-side
+   *   concept only).
+   * @param data - Optional payload, spread onto the {@link GarnishEvent} passed
+   *   to handlers (trigger-time keys win over per-registration `data`).
+   *
+   * @example
+   * ```ts
+   * this.trigger('change', {value: this.value});
+   * ```
+   */
+  trigger(type: string, data?: Record<string, unknown>): void {
+    this._emitter.trigger(type, data);
+    garnishClassBus.dispatch(this, type, data);
+  }
+
+  // --- DOM listeners --------------------------------------------------------
+
+  /**
+   * Bind one or more native DOM event listeners, tracked by this instance so
+   * they can be removed by name/namespace or torn down in bulk on
+   * {@link destroy}. This is the jQuery-free replacement for the legacy
+   * `addListener`.
+   *
+   * Signature-compatible with legacy: `(elem, events, handler)` or
+   * `(elem, events, data, handler)`. The `handler` may be a function (bound to
+   * `this`) or a **method-name string** resolved against `this` at call time.
+   *
+   * The `events` string uses the comma grammar (e.g. `'click, keydown'`), each
+   * token optionally `.namespaced`. Handlers do not fire while the instance is
+   * {@link disable | disabled}. Custom Garnish events (`activate`, `textchange`,
+   * `resize`) are supported transparently.
+   *
+   * Supported `data` keys: `delegate` (a selector — fire only when the event
+   * originates within a matching descendant) and event-specific options such as
+   * `delay` for `textchange`.
+   *
+   * @param elem - Target(s): an element, `window`/`document`, an array/NodeList,
+   *   or a CSS selector string (see {@link ElementInput}).
+   * @param events - Comma-separated event name(s), each optionally `.namespaced`.
+   * @param dataOrHandler - Either the handler, or a `data` object when a 4th arg
+   *   is supplied.
+   * @param handler - The handler (function or method-name string) when `data`
+   *   is passed.
+   *
+   * @example
+   * ```ts
+   * this.addListener(this.$button, 'click', (ev) => this.handleClick(ev));
+   * this.addListener(this.$shade, 'click', 'hide'); // method-name string
+   * this.addListener(this.$list, 'click', {delegate: 'li'}, this.onItem);
+   * ```
+   */
+  addListener(
+    elem: ElementInput,
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler | string,
+    handler?: GarnishEventHandler | string
+  ): void {
+    let data: Record<string, unknown> = {};
+    let func: GarnishEventHandler | string | undefined;
+
+    // Param mapping: if handler is undefined and `dataOrHandler` isn't a plain
+    // object, treat `dataOrHandler` as the handler.
+    if (handler === undefined && !isPlainObject(dataOrHandler)) {
+      func = dataOrHandler as GarnishEventHandler | string;
+    } else {
+      data = (dataOrHandler as Record<string, unknown>) ?? {};
+      func = handler;
+    }
+
+    let resolved: GarnishEventHandler;
+    if (typeof func === 'function') {
+      resolved = func.bind(this);
+    } else if (typeof func === 'string') {
+      // Method-name string (e.g. UiLayerManager uses 'triggerShortcut').
+      resolved = (this[func as keyof this] as GarnishEventHandler).bind(this);
+    } else {
+      return;
+    }
+
+    const options: DomListenerOptions = {};
+    if ('delegate' in data && typeof data.delegate === 'string') {
+      options.delegate = data.delegate;
+    }
+    if ('delay' in data || Object.keys(data).length) {
+      options.data = data;
+    }
+
+    this._domListeners.add(elem, events, resolved, options);
+  }
+
+  /**
+   * Remove specific DOM listener(s) this instance bound on the element(s).
+   * Honors namespaces: `removeListener(el, '.myNs')` removes every namespaced
+   * binding regardless of type.
+   *
+   * @param elem - The same target(s) the listener was bound on.
+   * @param events - Comma-separated event name(s), each optionally `.namespaced`.
+   */
+  removeListener(elem: ElementInput, events: string): void {
+    this._domListeners.remove(elem, events);
+  }
+
+  /**
+   * Remove every DOM listener this instance bound on the given element(s).
+   *
+   * @param elem - The target(s) to clear listeners from.
+   */
+  removeAllListeners(elem: ElementInput): void {
+    this._domListeners.removeAllOn(elem);
+  }
+
+  // --- Enable/disable/destroy ----------------------------------------------
+
+  /**
+   * Disable the instance. While disabled, DOM listeners bound via
+   * {@link addListener} are short-circuited (they don't fire). Object events
+   * ({@link trigger}) are unaffected.
+   */
+  disable(): void {
+    this._disabled = true;
+  }
+
+  /** Re-enable the instance, restoring DOM-listener dispatch. */
+  enable(): void {
+    this._disabled = false;
+  }
+
+  /** Whether the instance is currently {@link disable | disabled}. */
+  get disabled(): boolean {
+    return this._disabled;
+  }
+
+  /**
+   * Tear the instance down: emit a `destroy` event, then remove every tracked
+   * DOM listener and clear all object-event registrations. Subclasses that
+   * override this should call `super.destroy()`.
+   */
+  destroy(): void {
+    this.trigger('destroy');
+    this._domListeners.removeAll();
+    this._emitter.clear();
+  }
+}
+
+function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    (Object.getPrototypeOf(val) === Object.prototype ||
+      Object.getPrototypeOf(val) === null)
+  );
+}
diff --git a/packages/craftcms-garnish/src/compat.ts b/packages/craftcms-garnish/src/compat.ts
new file mode 100644
index 00000000000..db1a0685878
--- /dev/null
+++ b/packages/craftcms-garnish/src/compat.ts
@@ -0,0 +1,599 @@
+/**
+ * @craftcms/garnish/compat — opt-in legacy compatibility layer.
+ *
+ * Restores the entire legacy Garnish authoring contract on top of the modern,
+ * jQuery-free core:
+ *
+ *  - `Garnish.Base.extend(instanceMembers, staticMembers)` → real subclasses
+ *  - `init()` as the constructor trampoline (subclasses write `init`, not `constructor`)
+ *  - `this.base(...)` super-dispatch with per-call save/restore re-entrancy,
+ *    ported faithfully from Dean Edwards `lib/Base.js` (the `/\bbase\b/` source-sniff)
+ *  - jQuery-collection coercion for `$container`-style constructor args
+ *  - `isJquery`, jQuery-wrapped `$win`/`$doc`/`$bod`/`$scrollContainer`
+ *  - `getFocusedElement()` returning a jQuery collection (legacy shape)
+ *  - the deprecated `Menu` / `ShortcutManager` aliases
+ *  - the `$.fn.activate/textchange/resize` chaining sugar (when jQuery is present)
+ *  - a legacy-shaped `window.Garnish` global, guarded like the legacy code
+ *
+ * ## Opt-in story
+ *
+ * This entry is **side-effecting**: importing it installs `window.Garnish`
+ * (under the same `if (typeof window.Garnish === 'undefined')` guard the legacy
+ * library used) and gives you `.extend()`-able, jQuery-shaped classes.
+ *
+ *   // legacy plugin, zero code changes beyond this one line:
+ *   import '@craftcms/garnish/compat';
+ *   Craft.MyModal = Garnish.Modal.extend({ init() { … } });
+ *
+ * To **drop** the compat layer, delete that import line and move to the modern
+ * surface (`import {Modal} from '@craftcms/garnish'; class extends Modal {…}`).
+ * Tree-shaking then removes all of this code and the `window.Garnish` global.
+ *
+ * For programmatic / non-auto-install use, call `installGarnishCompat()` (it is
+ * idempotent and returns the assembled namespace), or import the named
+ * `compatify` / `GarnishCompat` exports directly.
+ *
+ * jQuery is a **peer dependency of this entry only** — the modern `.` entry stays
+ * jQuery-free. jQuery is detected at runtime from the global scope; the compat
+ * layer degrades gracefully (or throws a clear error) when it is absent.
+ */
+
+import * as Core from './index';
+import {Garnish as CoreGarnish, initGarnish} from './index';
+import {getFocusedElement as coreGetFocusedElement} from './utils/focus';
+import {win, doc, bod} from './globals';
+
+/* ------------------------------------------------------------------------- *
+ * jQuery runtime detection (peer dependency of ./compat only)
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Minimal structural type for a jQuery function/collection. We can't depend on
+ * `@types/jquery` here (jQuery is only an optional peer of this entry), so this
+ * is intentionally loose.
+ */
+export interface JQueryLike {
+  (selectorOrEl?: unknown): JQueryCollection;
+  fn: Record<string, unknown> & {jquery?: string};
+  prototype: object;
+}
+
+export interface JQueryCollection {
+  length: number;
+  [index: number]: Element;
+  get(index?: number): Element | Element[];
+  on(...args: unknown[]): JQueryCollection;
+  trigger(...args: unknown[]): JQueryCollection;
+  toArray?(): Element[];
+}
+
+/**
+ * Resolve jQuery from the global scope (`window.jQuery` or `window.$`), or
+ * `null` if it isn't present. jQuery is an optional peer dependency of the
+ * compat entry only and is detected at runtime.
+ *
+ * @returns The global jQuery function, or `null`.
+ */
+export function resolveJQuery(): JQueryLike | null {
+  const g = globalThis as Record<string, unknown>;
+  const candidate = (g.jQuery ?? g.$) as JQueryLike | undefined;
+  if (typeof candidate === 'function' && (candidate as JQueryLike).fn) {
+    return candidate as JQueryLike;
+  }
+  return null;
+}
+
+/** Throw a clear, actionable error when jQuery is required but absent. */
+function requireJQuery(feature: string): JQueryLike {
+  const jq = resolveJQuery();
+  if (!jq) {
+    throw new Error(
+      `@craftcms/garnish/compat: jQuery is required for ${feature} but was not ` +
+        `found on the global scope. Load jQuery before importing the compat ` +
+        `layer, or migrate to the modern jQuery-free API.`
+    );
+  }
+  return jq;
+}
+
+/**
+ * Whether a value is a jQuery collection — the modern home of the legacy
+ * `Garnish.isJquery`. Returns `false` when jQuery isn't loaded.
+ *
+ * @param val - The value to test.
+ * @returns `true` if `val` is a jQuery collection.
+ */
+export function isJquery(val: unknown): boolean {
+  const jq = resolveJQuery();
+  if (!jq) {
+    return false;
+  }
+  // jQuery collections are instances of jQuery.fn.init; the cheapest reliable
+  // check is the prototype chain, mirroring legacy `val instanceof $`.
+  return val instanceof (jq as unknown as {prototype: object} & Function);
+}
+
+/**
+ * Wrap a native element / list in a jQuery collection (`$(value)`).
+ *
+ * @param value - Anything jQuery's `$()` accepts.
+ * @returns The jQuery collection.
+ * @throws If jQuery is absent — the `$`-prefixed legacy surface is meaningless
+ *   without it.
+ */
+export function toJq(value: unknown): JQueryCollection {
+  const jq = requireJQuery('jQuery-wrapped values');
+  return jq(value);
+}
+
+/**
+ * Coerce a possibly-jQuery constructor argument down to the native input the
+ * modern classes expect. Modern constructors accept
+ * `Element | EventTarget | string | null`; legacy callers may pass a jQuery
+ * collection (`$container`) — this unwraps it to its first element (or `null`
+ * when empty). Non-jQuery values pass through untouched.
+ *
+ * @param value - The (possibly jQuery) value.
+ * @returns The native element, or the value unchanged.
+ */
+export function unwrapJq(value: unknown): unknown {
+  if (value == null) {
+    return value;
+  }
+  if (isJquery(value)) {
+    const coll = value as JQueryCollection;
+    return coll.length ? coll[0] : null;
+  }
+  return value;
+}
+
+/* ------------------------------------------------------------------------- *
+ * compatify(ModernClass) — the legacy `.extend()` / `this.base()` shim
+ * ------------------------------------------------------------------------- */
+
+type AnyCtor = abstract new (...args: any[]) => object;
+type ConcreteCtor = new (...args: any[]) => object;
+
+export interface LegacyMembers {
+  /** Legacy constructor trampoline; receives the `new` arguments. */
+  init?: (...args: any[]) => void;
+  [key: string]: unknown;
+}
+
+export interface LegacyCtor extends ConcreteCtor {
+  /** Dean-Edwards-style subclassing: returns a new legacy-shaped subclass. */
+  extend(instanceMembers?: LegacyMembers, staticMembers?: object): LegacyCtor;
+  /** The class this one extends (legacy `klass.ancestor`). */
+  ancestor?: unknown;
+}
+
+/**
+ * The marker we stash on every compatified prototype so a subclass can find the
+ * ancestor implementation of an overridden method when synthesizing `this.base`.
+ *
+ * We walk the *prototype chain* (real inheritance) rather than cloning prototypes
+ * the way Dean Edwards' `new this()` did — the lookup is
+ * `Object.getPrototypeOf(subclassProto)[name]`.
+ */
+
+/**
+ * Detect whether a function's source references `base` as an identifier — the
+ * exact `/\bbase\b/` source-sniff from `lib/Base.js`. Only methods that actually
+ * call `this.base()` get wrapped, matching legacy behavior (and avoiding the
+ * overhead/observable `this.base` mutation for methods that don't).
+ */
+const BASE_RE = /\bbase\b/;
+
+function referencesBase(fn: unknown): fn is (...args: any[]) => unknown {
+  return (
+    typeof fn === 'function' &&
+    BASE_RE.test(Function.prototype.toString.call(fn))
+  );
+}
+
+/**
+ * Wrap an override so that, on entry, `this.base` is set to the ancestor method
+ * (bound to `this`), the override runs, and the prior `this.base` is restored on
+ * exit. Ported verbatim from `lib/Base.js`'s save/restore dance, with a
+ * try/finally so nested / re-entrant super-calls restore correctly even when an
+ * override throws.
+ */
+function wrapWithBase(
+  method: (...args: any[]) => unknown,
+  ancestor: ((...args: any[]) => unknown) | undefined
+): (...args: any[]) => unknown {
+  const noopBase = function noBase(): void {
+    // Calling this.base() with no ancestor is a legacy no-op.
+  };
+
+  return function baseWrapper(this: Record<string, unknown>, ...args: any[]) {
+    const previous = this.base;
+    this.base = ancestor ? ancestor.bind(this) : noopBase;
+    try {
+      return method.apply(this, args);
+    } finally {
+      this.base = previous;
+    }
+  };
+}
+
+/**
+ * Copy a single legacy instance member onto a subclass prototype. Functions that
+ * reference `base` are wrapped for super-dispatch against the ancestor found on
+ * the prototype chain.
+ */
+function defineInstanceMember(
+  proto: object,
+  parentProto: object,
+  key: string,
+  value: unknown
+): void {
+  if (referencesBase(value)) {
+    const ancestor = (parentProto as Record<string, unknown>)[key] as
+      | ((...args: any[]) => unknown)
+      | undefined;
+    Object.defineProperty(proto, key, {
+      value: wrapWithBase(value, ancestor),
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  } else {
+    Object.defineProperty(proto, key, {
+      value,
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+}
+
+/**
+ * Turn a modern ES class into a legacy-shaped constructor that supports the full
+ * Dean-Edwards authoring contract: `.extend(instanceMembers, staticMembers)`,
+ * `init` as the constructor trampoline, and `this.base(...)` super-dispatch.
+ *
+ * The returned constructor is directly `new`-able (it forwards to the modern
+ * class) and exposes a static `extend`. Each `.extend()` produces a **real
+ * subclass** (native prototype chain) so `instanceof` and `super` keep working,
+ * with the legacy affordances layered on top: `init` runs once on the most
+ * derived class, and methods whose source references `base` get a per-call
+ * `this.base` bound to the ancestor implementation.
+ *
+ * This is what makes an unmodified legacy plugin run against the modern core.
+ * For TypeScript-authored code, prefer plain `class extends ModernClass` with
+ * `super.method()` instead — `compatify` exists for the upgrade path.
+ *
+ * @typeParam T - The modern (abstract or concrete) class to wrap.
+ * @param Modern - The modern ES class.
+ * @returns A legacy-shaped constructor with `.extend()`.
+ *
+ * @example
+ * ```ts
+ * import {Modal} from '@craftcms/garnish';
+ * import {compatify} from '@craftcms/garnish/compat';
+ *
+ * const LegacyModal = compatify(Modal);
+ *
+ * const MyModal = LegacyModal.extend({
+ *   init(container) {
+ *     this.base(container, {closeOtherModals: true}); // calls Modal's constructor
+ *   },
+ *   onShow() {
+ *     this.base();   // calls Modal.prototype.onShow
+ *     // ...custom behavior
+ *   },
+ * });
+ *
+ * new MyModal(document.querySelector('#my-modal'));
+ * ```
+ */
+export function compatify<T extends AnyCtor>(Modern: T): LegacyCtor {
+  // The root compat constructor simply forwards to the modern class. Modern
+  // classes have plain constructors (no init trampoline), so a bare `new` is a
+  // valid legacy instantiation with no `init` member.
+  const Root = makeSubclass(Modern as unknown as ConcreteCtor, undefined);
+
+  // Faithful to lib/Base.js (`proto.base = function () {}`): every compatified
+  // class has a default no-op `base` on its prototype, so `this.base` is ALWAYS
+  // callable even outside a wrapped override, and the save/restore dance in
+  // `wrapWithBase` always restores to a function rather than `undefined`.
+  if (!Object.prototype.hasOwnProperty.call(Root.prototype, 'base')) {
+    Object.defineProperty(Root.prototype, 'base', {
+      value: function noBase(): void {
+        // call this method from any other method to invoke that method's ancestor
+      },
+      writable: true,
+      configurable: true,
+      enumerable: false,
+    });
+  }
+
+  return Root;
+}
+
+/**
+ * Build one level of the legacy-shaped class hierarchy.
+ *
+ * @param Parent  The (modern or already-compatified) constructor to extend.
+ * @param members The legacy instance members for THIS level (or undefined for
+ *                the root wrapper, which adds none).
+ * @param statics Static members to copy onto the constructor.
+ */
+function makeSubclass(
+  Parent: ConcreteCtor,
+  members: LegacyMembers | undefined,
+  statics?: object
+): LegacyCtor {
+  const parentProto = Parent.prototype as object;
+  const hasInit = typeof members?.init === 'function';
+
+  // The legacy-shaped constructor. It runs the modern constructor (super), then,
+  // if this level (or an ancestor level) supplied an `init`, invokes it with the
+  // original arguments — matching legacy `this.init.apply(this, arguments)`.
+  class Subclass extends (Parent as ConcreteCtor) {
+    constructor(...args: any[]) {
+      // Coerce jQuery-collection / selector args down to native inputs the
+      // modern constructor (and the legacy `init`) understand
+      // ($container → element). Unwrap once so super() and init() agree.
+      const nativeArgs = args.map(unwrapJq) as any[];
+      super(...nativeArgs);
+
+      // Only run init from the *most derived* level that defined one. Because
+      // each subclass constructor runs this, we guard so `init` fires exactly
+      // once: only when `this.constructor === Subclass` (the instantiated class).
+      // Inherited `init`s are found via the prototype and run by the leaf ctor.
+      if (this.constructor === Subclass) {
+        const initFn = (this as Record<string, unknown>).init;
+        if (typeof initFn === 'function') {
+          (initFn as (...a: any[]) => void).apply(this, nativeArgs);
+        }
+      }
+    }
+  }
+
+  // Copy instance members onto the subclass prototype, wrapping `base`-callers.
+  if (members) {
+    for (const key of Object.keys(members)) {
+      if (key === 'constructor') {
+        continue;
+      }
+      const desc = Object.getOwnPropertyDescriptor(members, key)!;
+      if ('value' in desc) {
+        defineInstanceMember(Subclass.prototype, parentProto, key, desc.value);
+      } else {
+        // Preserve getters/setters (legacy Dean Edwards copied descriptors).
+        Object.defineProperty(Subclass.prototype, key, desc);
+      }
+    }
+  }
+  // Mark whether this level brought its own init (debug/parity aid).
+  void hasInit;
+
+  const Ctor = Subclass as unknown as LegacyCtor;
+
+  // Static members.
+  if (statics) {
+    Object.assign(Ctor, statics);
+  }
+  Ctor.ancestor = Parent;
+
+  // The legacy `.extend()` entry point: build the next level down.
+  Ctor.extend = function extend(
+    instanceMembers?: LegacyMembers,
+    staticMembers?: object
+  ): LegacyCtor {
+    return makeSubclass(
+      Ctor as unknown as ConcreteCtor,
+      instanceMembers,
+      staticMembers
+    );
+  };
+
+  return Ctor;
+}
+
+/* ------------------------------------------------------------------------- *
+ * Legacy-shaped Garnish namespace assembly
+ * ------------------------------------------------------------------------- */
+
+/** The set of class keys on the core namespace we run through `compatify`. */
+const CLASS_KEYS = ['Base', 'EscManager', 'UiLayerManager'] as const;
+
+export interface GarnishCompatNamespace {
+  [key: string]: unknown;
+}
+
+let installed: GarnishCompatNamespace | undefined;
+
+/**
+ * Assemble the legacy-shaped `Garnish` namespace **without** assigning it to
+ * `window`: {@link compatify} each Garnish class so `.extend()` works, run
+ * `initGarnish()` for the manager singletons, re-add the jQuery-only members
+ * (`isJquery`, `$win`/`$doc`/`$bod`/`$scrollContainer`, the `$.fn.activate/…`
+ * chaining sugar), and restore the deprecated aliases (`Menu`,
+ * `ShortcutManager`).
+ *
+ * Use {@link installGarnishCompat} (or the side-effecting `import` of this
+ * module) if you also want `window.Garnish` set.
+ *
+ * @returns The assembled namespace. Idempotent — repeated calls return the same object.
+ */
+export function buildGarnishCompat(): GarnishCompatNamespace {
+  if (installed) {
+    return installed;
+  }
+
+  // Start from the live core namespace so utilities, constants, flags, and the
+  // class-level event bus proxies (`on`/`off`/`once`) are all carried over.
+  const G: GarnishCompatNamespace = Object.assign({}, CoreGarnish);
+
+  // Wrap every (currently-ported) class so `.extend()` / `init` / `this.base()`
+  // work. New classes (Modal, HUD, …) are picked up automatically as the core
+  // namespace gains them.
+  for (const key of Object.keys(CoreGarnish)) {
+    const value = (CoreGarnish as Record<string, unknown>)[key];
+    if (isCompatifiableClass(key, value)) {
+      G[key] = compatify(value as AnyCtor);
+    }
+  }
+
+  // --- jQuery-only surface (re-added from core, which omitted it) -----------
+
+  G.isJquery = isJquery;
+
+  // jQuery-wrapped DOM refs (lazy getters so jQuery only needs to exist at
+  // access time, not import time).
+  Object.defineProperties(G, {
+    $win: {
+      configurable: true,
+      enumerable: true,
+      get: () => toJq(win),
+    },
+    $doc: {
+      configurable: true,
+      enumerable: true,
+      get: () => toJq(doc),
+    },
+    $bod: {
+      configurable: true,
+      enumerable: true,
+      get: () => toJq(bod),
+    },
+    $scrollContainer: {
+      configurable: true,
+      enumerable: true,
+      get: () => toJq(CoreGarnish.scrollContainer),
+    },
+  });
+
+  // getFocusedElement returned a jQuery `:focus` collection in legacy.
+  G.getFocusedElement = (): JQueryCollection | Element | null => {
+    if (resolveJQuery()) {
+      const el = coreGetFocusedElement();
+      return toJq(el ?? []);
+    }
+    return coreGetFocusedElement();
+  };
+
+  // --- Manager singletons ---------------------------------------------------
+
+  initGarnish();
+  G.escManager = CoreGarnish.escManager;
+  G.uiLayerManager = CoreGarnish.uiLayerManager;
+
+  // --- Deprecated aliases ---------------------------------------------------
+
+  // Menu → CustomSelect (when CustomSelect is ported), else fall back to nothing.
+  const customSelect = (G as Record<string, unknown>).CustomSelect;
+  if (customSelect) {
+    G.Menu = customSelect;
+  }
+  // ShortcutManager → UiLayerManager (compatified form).
+  G.ShortcutManager = G.UiLayerManager;
+  // Legacy lowercase alias used by index.js.
+  G.shortcutManager = CoreGarnish.uiLayerManager;
+
+  // --- $.fn chaining sugar (only when jQuery is present) --------------------
+  installJqueryFnSugar();
+
+  installed = G;
+  return installed;
+}
+
+/**
+ * Re-add the legacy `$.fn.activate/textchange/resize` chaining sugar IF jQuery is
+ * present. Routes through jQuery's own `.on(name, …)` / `.trigger(name)` exactly
+ * like the legacy `$.each(['activate','textchange','resize'], …)` block. The
+ * underlying custom-event semantics are installed by the core
+ * `installActivate/Textchange/Resize` when the listeners actually bind via
+ * `Garnish.Base#addListener`; this sugar only restores the fluent jQuery call
+ * shape. Degrades to a no-op when jQuery is absent.
+ */
+function installJqueryFnSugar(): void {
+  const jq = resolveJQuery();
+  if (!jq || !jq.fn) {
+    return;
+  }
+  for (const name of ['activate', 'textchange', 'resize'] as const) {
+    if (typeof jq.fn[name] === 'function') {
+      continue; // already installed (e.g. by the legacy bundle)
+    }
+    jq.fn[name] = function (
+      this: JQueryCollection,
+      data?: unknown,
+      fn?: unknown
+    ): JQueryCollection {
+      return arguments.length > 0
+        ? this.on(name, null, data, fn)
+        : this.trigger(name);
+    };
+  }
+}
+
+function isCompatifiableClass(key: string, value: unknown): boolean {
+  if (typeof value !== 'function') {
+    return false;
+  }
+  // Known core classes, plus any future class exposed on the namespace whose
+  // prototype descends from the (already-known) Base.
+  if ((CLASS_KEYS as readonly string[]).includes(key)) {
+    return true;
+  }
+  // Heuristic for not-yet-enumerated classes (Modal, HUD, …): a function with a
+  // prototype that is a Base (or subclass) instance shape. We avoid wrapping
+  // plain utility functions by requiring the value to be a class extending Core.Base.
+  try {
+    return value.prototype instanceof Core.Base;
+  } catch {
+    return false;
+  }
+}
+
+/* ------------------------------------------------------------------------- *
+ * window.Garnish installation
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Build the legacy-shaped `Garnish` namespace and install it onto `window`,
+ * guarded exactly like the legacy library (`if (typeof window.Garnish ===
+ * 'undefined')`) so it never clobbers an existing (legacy-bundle) global during
+ * the coexistence period.
+ *
+ * Importing `@craftcms/garnish/compat` calls this automatically (via the eager
+ * {@link GarnishCompat} export); call it yourself only for explicit/programmatic
+ * installation.
+ *
+ * @returns The assembled namespace, regardless of whether it won the `window.Garnish`
+ *   slot. Idempotent.
+ *
+ * @example
+ * ```ts
+ * import {installGarnishCompat} from '@craftcms/garnish/compat';
+ * const Garnish = installGarnishCompat();
+ * const MyModal = Garnish.Modal.extend({ init() { … } });
+ * ```
+ */
+export function installGarnishCompat(): GarnishCompatNamespace {
+  const G = buildGarnishCompat();
+
+  const w = (typeof window !== 'undefined' ? window : undefined) as
+    | (Window & {Garnish?: unknown})
+    | undefined;
+
+  if (w && typeof w.Garnish === 'undefined') {
+    w.Garnish = G;
+  }
+
+  return G;
+}
+
+/**
+ * The assembled legacy-shaped `Garnish` namespace, built (and installed onto
+ * `window.Garnish`) eagerly when this module is imported. This is the default
+ * export too, so `import Garnish from '@craftcms/garnish/compat'` gives you the
+ * namespace directly.
+ */
+export const GarnishCompat = installGarnishCompat();
+
+export default GarnishCompat;
diff --git a/packages/craftcms-garnish/src/constants.ts b/packages/craftcms-garnish/src/constants.ts
new file mode 100644
index 00000000000..746e4599c0c
--- /dev/null
+++ b/packages/craftcms-garnish/src/constants.ts
@@ -0,0 +1,54 @@
+/**
+ * Garnish constants.
+ *
+ * Ported verbatim from the legacy `Garnish` singleton (src/Garnish.js).
+ * Plain numeric/string constants only — no jQuery dependency.
+ */
+
+// Key code constants
+export const BACKSPACE_KEY = 8;
+export const TAB_KEY = 9;
+export const CLEAR_KEY = 12;
+export const RETURN_KEY = 13;
+export const SHIFT_KEY = 16;
+export const CTRL_KEY = 17;
+export const ALT_KEY = 18;
+export const ESC_KEY = 27;
+export const SPACE_KEY = 32;
+export const PAGE_UP_KEY = 33;
+export const PAGE_DOWN_KEY = 34;
+export const END_KEY = 35;
+export const HOME_KEY = 36;
+export const LEFT_KEY = 37;
+export const UP_KEY = 38;
+export const RIGHT_KEY = 39;
+export const DOWN_KEY = 40;
+export const DELETE_KEY = 46;
+export const A_KEY = 65;
+export const S_KEY = 83;
+export const CMD_KEY = 91;
+export const META_KEY = 224;
+
+// ARIA hidden classes
+export const JS_ARIA_CLASS = 'garnish-js-aria';
+export const JS_ARIA_TRUE_CLASS = 'garnish-js-aria-true';
+export const JS_ARIA_FALSE_CLASS = 'garnish-js-aria-false';
+
+// Mouse button constants
+// NOTE: these match the legacy `event.which` numbering (1 = primary, 3 = secondary).
+// Native code should prefer `MouseEvent.button` (0 = primary). Kept for compat-layer parity.
+export const PRIMARY_CLICK = 1;
+export const SECONDARY_CLICK = 3;
+
+// Axis constants
+export const X_AXIS = 'x';
+export const Y_AXIS = 'y';
+
+export const FX_DURATION = 200;
+
+// Node types
+export const TEXT_NODE = 3;
+
+// Shake animation
+export const SHAKE_STEPS = 10;
+export const SHAKE_STEP_DURATION = 25;
diff --git a/packages/craftcms-garnish/src/custom-events/activate.ts b/packages/craftcms-garnish/src/custom-events/activate.ts
new file mode 100644
index 00000000000..24f3dffb08d
--- /dev/null
+++ b/packages/craftcms-garnish/src/custom-events/activate.ts
@@ -0,0 +1,149 @@
+/**
+ * Garnish `activate` custom event.
+ *
+ * Native replacement for the legacy `$.event.special.activate`. Wires
+ * mousedown/click/keydown listeners that dispatch a synthetic `activate`
+ * CustomEvent, preserving the legacy focus/preventDefault behavior.
+ */
+
+import {RETURN_KEY, SPACE_KEY} from '../constants';
+import {globals} from '../globals';
+import {isCtrlKeyPressed} from '../utils/env';
+import {hasAttr} from '../utils/dom';
+
+// Track installs so installation is idempotent per element.
+const installed = new WeakMap<
+  HTMLElement,
+  {count: number; dispose: () => void}
+>();
+
+function isButtonish(el: HTMLElement): boolean {
+  return el.nodeName === 'BUTTON' || el.getAttribute('role') === 'button';
+}
+
+function dispatchActivate(el: HTMLElement, originalEvent: Event): void {
+  const event = new CustomEvent('activate', {
+    bubbles: true,
+    cancelable: true,
+    detail: {originalEvent},
+  });
+  // Expose `originalEvent` directly (legacy shape).
+  (event as unknown as {originalEvent: Event}).originalEvent = originalEvent;
+  el.dispatchEvent(event);
+}
+
+/**
+ * Attach Garnish `activate` semantics to an element: a unified click/keyboard
+ * "activate" event (Space/Enter or click) that respects disabled state, manages
+ * `tabindex`, and avoids hijacking modifier-clicks on real links. Dispatched as
+ * a native `activate` `CustomEvent`. Usually reached via
+ * `addListener(el, 'activate', fn)` rather than called directly.
+ *
+ * Idempotent per element: repeated calls increment a ref-count.
+ *
+ * @param el - The element to make activatable.
+ * @returns A disposer that decrements the ref-count and removes the listeners
+ *   when the last consumer releases.
+ */
+export function installActivate(el: HTMLElement): () => void {
+  const existing = installed.get(el);
+  if (existing) {
+    existing.count++;
+    return makeDisposer(el);
+  }
+
+  const onMousedown = (e: MouseEvent): void => {
+    // Prevent buttons from getting focus on click.
+    if (isButtonish(e.currentTarget as HTMLElement)) {
+      e.preventDefault();
+    }
+  };
+
+  const onClick = (e: MouseEvent): void => {
+    if (globals.activateEventsMuted) {
+      return;
+    }
+
+    const disabled = el.classList.contains('disabled');
+
+    // Don't interfere with Ctrl/⌘-clicks on real links.
+    if (
+      !disabled &&
+      el.nodeName === 'A' &&
+      hasAttr(el, 'href') &&
+      !['#', ''].includes(el.getAttribute('href') ?? '') &&
+      isCtrlKeyPressed(e)
+    ) {
+      return;
+    }
+
+    if (isButtonish(e.currentTarget as HTMLElement)) {
+      e.preventDefault();
+    }
+
+    if (!disabled) {
+      dispatchActivate(el, e);
+    }
+  };
+
+  const onKeydown = (e: KeyboardEvent): void => {
+    // Ignore muted, bubbled events, or non-Space/Return keys.
+    if (
+      globals.activateEventsMuted ||
+      e.currentTarget !== el ||
+      ![SPACE_KEY, RETURN_KEY].includes(e.keyCode)
+    ) {
+      return;
+    }
+
+    if (isButtonish(e.currentTarget as HTMLElement)) {
+      e.preventDefault();
+    }
+
+    if (!el.classList.contains('disabled')) {
+      dispatchActivate(el, e);
+    }
+  };
+
+  el.addEventListener('mousedown', onMousedown as EventListener);
+  el.addEventListener('click', onClick as EventListener);
+  el.addEventListener('keydown', onKeydown as EventListener);
+
+  // Manage tabindex, mirroring the legacy setup.
+  if (!el.classList.contains('disabled')) {
+    // Make focusable unless this is the body element.
+    if (el !== document.body) {
+      el.setAttribute('tabindex', '0');
+    }
+  } else if (!el.classList.contains('read-only')) {
+    el.removeAttribute('tabindex');
+  }
+
+  const dispose = (): void => {
+    el.removeEventListener('mousedown', onMousedown as EventListener);
+    el.removeEventListener('click', onClick as EventListener);
+    el.removeEventListener('keydown', onKeydown as EventListener);
+  };
+
+  installed.set(el, {count: 1, dispose});
+  return makeDisposer(el);
+}
+
+function makeDisposer(el: HTMLElement): () => void {
+  let called = false;
+  return () => {
+    if (called) {
+      return;
+    }
+    called = true;
+    const record = installed.get(el);
+    if (!record) {
+      return;
+    }
+    record.count--;
+    if (record.count <= 0) {
+      record.dispose();
+      installed.delete(el);
+    }
+  };
+}
diff --git a/packages/craftcms-garnish/src/custom-events/index.ts b/packages/craftcms-garnish/src/custom-events/index.ts
new file mode 100644
index 00000000000..d73428cea83
--- /dev/null
+++ b/packages/craftcms-garnish/src/custom-events/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Garnish custom DOM events — native installers replacing `$.event.special`.
+ */
+
+export {installActivate} from './activate';
+export {installTextchange, type TextchangeOptions} from './textchange';
+export {installResize} from './resize';
+
+export interface ActivateOptions {
+  /* none today */
+}
diff --git a/packages/craftcms-garnish/src/custom-events/resize.ts b/packages/craftcms-garnish/src/custom-events/resize.ts
new file mode 100644
index 00000000000..e1f052c6472
--- /dev/null
+++ b/packages/craftcms-garnish/src/custom-events/resize.ts
@@ -0,0 +1,104 @@
+/**
+ * Garnish `resize` custom event.
+ *
+ * Native replacement for the legacy `$.event.special.resize`. The window uses
+ * the native `resize` event; other elements share a single lazily-created
+ * `ResizeObserver` and only dispatch when their dimensions actually change and
+ * resize events aren't muted.
+ */
+
+import {globals} from '../globals';
+
+interface SizeRecord {
+  width: number;
+  height: number;
+}
+
+// Per-observed-element last-known size.
+const sizes = new WeakMap<Element, SizeRecord>();
+
+let resizeObserver: ResizeObserver | undefined;
+
+function getResizeObserver(): ResizeObserver {
+  if (!resizeObserver) {
+    resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const size = sizes.get(entry.target);
+        if (!size) {
+          continue;
+        }
+        const {width, height} = entry.target.getBoundingClientRect();
+        if (width !== size.width || height !== size.height) {
+          sizes.set(entry.target, {width, height});
+          if (!globals.resizeEventsMuted) {
+            entry.target.dispatchEvent(
+              new CustomEvent('resize', {bubbles: false, cancelable: false})
+            );
+          }
+        }
+      }
+    });
+  }
+  return resizeObserver;
+}
+
+const installed = new WeakMap<
+  EventTarget,
+  {count: number; dispose: () => void}
+>();
+
+/**
+ * Attach `resize` semantics to an element (or `window`): a `resize`
+ * `CustomEvent` that fires when the element's dimensions actually change, backed
+ * by a shared `ResizeObserver` (the window uses the native `resize` event).
+ * Suppressed while resize events are muted (see `muteResizeEvents`). Usually
+ * reached via `addListener(el, 'resize', fn)`. Idempotent per target
+ * (ref-counted).
+ *
+ * @param el - The element (or window) to observe.
+ * @returns A disposer that unobserves when the last consumer releases.
+ */
+export function installResize(el: HTMLElement): () => void {
+  const existing = installed.get(el);
+  if (existing) {
+    existing.count++;
+    return makeDisposer(el);
+  }
+
+  // The window natively supports `resize`; nothing to install.
+  if ((el as unknown) === window) {
+    installed.set(el, {count: 1, dispose: () => {}});
+    return makeDisposer(el);
+  }
+
+  const {width, height} = el.getBoundingClientRect();
+  sizes.set(el, {width, height});
+  getResizeObserver().observe(el);
+
+  const dispose = (): void => {
+    getResizeObserver().unobserve(el);
+    sizes.delete(el);
+  };
+
+  installed.set(el, {count: 1, dispose});
+  return makeDisposer(el);
+}
+
+function makeDisposer(el: EventTarget): () => void {
+  let called = false;
+  return () => {
+    if (called) {
+      return;
+    }
+    called = true;
+    const record = installed.get(el);
+    if (!record) {
+      return;
+    }
+    record.count--;
+    if (record.count <= 0) {
+      record.dispose();
+      installed.delete(el);
+    }
+  };
+}
diff --git a/packages/craftcms-garnish/src/custom-events/textchange.ts b/packages/craftcms-garnish/src/custom-events/textchange.ts
new file mode 100644
index 00000000000..4ef6c8fe53e
--- /dev/null
+++ b/packages/craftcms-garnish/src/custom-events/textchange.ts
@@ -0,0 +1,99 @@
+/**
+ * Garnish `textchange` custom event.
+ *
+ * Native replacement for the legacy `$.event.special.textchange`. Stores the
+ * last value and dispatches a `textchange` CustomEvent only when the value
+ * actually changes, with optional debounce.
+ */
+
+export interface TextchangeOptions {
+  delay?: number | null;
+}
+
+const installed = new WeakMap<
+  HTMLElement,
+  {count: number; dispose: () => void}
+>();
+
+/**
+ * Attach `textchange` semantics to an input: a `textchange` `CustomEvent` that
+ * fires only when the value actually changes (across keypress/keyup/change/blur),
+ * with optional debounce. Usually reached via
+ * `addListener(input, 'textchange', fn)`. Idempotent per element (ref-counted).
+ *
+ * @param el - The input/textarea to watch.
+ * @param options - `{delay}` to debounce dispatch by N milliseconds.
+ * @returns A disposer that removes the listeners when the last consumer releases.
+ */
+export function installTextchange(
+  el: HTMLElement & {value: string},
+  options: TextchangeOptions = {}
+): () => void {
+  const existing = installed.get(el);
+  if (existing) {
+    existing.count++;
+    return makeDisposer(el);
+  }
+
+  let lastValue = el.value;
+  let delayTimeout: ReturnType<typeof setTimeout> | undefined;
+  const delay = options.delay ?? null;
+
+  const fire = (): void => {
+    el.dispatchEvent(
+      new CustomEvent('textchange', {bubbles: true, cancelable: true})
+    );
+  };
+
+  const onInputEvent = (): void => {
+    const val = el.value;
+    if (val !== lastValue) {
+      lastValue = val;
+
+      if (delay) {
+        if (delayTimeout) {
+          clearTimeout(delayTimeout);
+        }
+        delayTimeout = setTimeout(fire, delay);
+      } else {
+        fire();
+      }
+    }
+  };
+
+  const events = ['keypress', 'keyup', 'change', 'blur'];
+  for (const type of events) {
+    el.addEventListener(type, onInputEvent as EventListener);
+  }
+
+  const dispose = (): void => {
+    if (delayTimeout) {
+      clearTimeout(delayTimeout);
+    }
+    for (const type of events) {
+      el.removeEventListener(type, onInputEvent as EventListener);
+    }
+  };
+
+  installed.set(el, {count: 1, dispose});
+  return makeDisposer(el);
+}
+
+function makeDisposer(el: HTMLElement): () => void {
+  let called = false;
+  return () => {
+    if (called) {
+      return;
+    }
+    called = true;
+    const record = installed.get(el);
+    if (!record) {
+      return;
+    }
+    record.count--;
+    if (record.count <= 0) {
+      record.dispose();
+      installed.delete(el);
+    }
+  };
+}
diff --git a/packages/craftcms-garnish/src/disclosure-menu.ts b/packages/craftcms-garnish/src/disclosure-menu.ts
new file mode 100644
index 00000000000..31cf9bd2fee
--- /dev/null
+++ b/packages/craftcms-garnish/src/disclosure-menu.ts
@@ -0,0 +1,1417 @@
+/**
+ * DisclosureMenu — modern, jQuery-free TypeScript port of Garnish's
+ * `DisclosureMenu`.
+ *
+ * A disclosure menu is a trigger button (carrying `aria-controls` /
+ * `aria-expanded`) paired with a menu panel of items/groups. Unlike {@link HUD},
+ * the panel is **pre-existing markup** referenced by the trigger's
+ * `aria-controls` (not built by the component); the component anchors it under
+ * the trigger, manages keyboard navigation + type-ahead search, focus, and the
+ * `UiLayerManager` layer + Escape shortcut, and exposes item/group builders
+ * (`addItem` / `addGroup` / `addHr`) that consumers across the CP rely on.
+ *
+ * This is the jQuery-free port of the legacy `DisclosureMenu.js` (doc 15). It
+ * follows the same overlay patterns {@link HUD}/{@link Modal} already use and
+ * replaces every jQuery call with native DOM:
+ *
+ * - `$(trigger)` → {@link getElement}
+ * - `$('#id')` / `.next()` → `document.getElementById` / `nextElementSibling`
+ * - `.data('disclosureMenu', …)` → a module-level `WeakMap`
+ * - `:focusable` → {@link getFocusableElements} / {@link isFocusable}
+ * - `.scrollParent()` → {@link getScrollParent}
+ * - `.offset()` / `.outerWidth()/.outerHeight()` → rect-based helpers +
+ *   {@link getOuterWidth} / {@link getOuterHeight}
+ * - `.velocity('fadeOut')` → the Web Animations API (gated on
+ *   {@link prefersReducedMotion}, like {@link Modal})
+ * - `$o.data('searchText')` (type-ahead cache) → a module-level `WeakMap`
+ * - `.find/closest/filter/parent/prevUntil/nextUntil` → native DOM walks
+ *
+ * The few legacy Craft touchpoints (`Craft.getUrl` / `Craft.t` /
+ * `Craft.initUiElements`) are resolved through an optional global so the
+ * component runs standalone (tests/playground) and defers to Craft when present
+ * in the CP. The legacy `$(el).formsubmit()` jQuery registration is intentionally
+ * not called here (it would re-introduce jQuery); the `formsubmit` class +
+ * `data-action` attributes are still set so the CP's form-submit machinery picks
+ * the item up (doc 16).
+ */
+
+import {Base} from './base';
+import {bod, doc, globals, win} from './globals';
+import {
+  DOWN_KEY,
+  ESC_KEY,
+  LEFT_KEY,
+  RETURN_KEY,
+  RIGHT_KEY,
+  SPACE_KEY,
+  TAB_KEY,
+  UP_KEY,
+} from './constants';
+import {getUiLayerManager} from './managers/registry';
+import {
+  getElement,
+  getOffset,
+  getOuterHeight,
+  getOuterWidth,
+} from './utils/dom';
+import {getScrollParent} from './utils/scroll';
+import {focusIsInside} from './utils/focus';
+import {getFocusableElements, isFocusable} from './utils/focusable';
+import {prefersReducedMotion} from './utils/animation';
+import {isCtrlKeyPressed} from './utils/env';
+import {isPlainObject} from './utils/misc';
+import type {ElementInput, GarnishBaseSettings} from './types';
+import type {GarnishEvent} from './events';
+
+/** Duration (ms) of the menu fade-out, matching legacy `FX_DURATION`. */
+const FADE_OUT_DURATION = 200;
+
+/**
+ * Settings accepted by {@link DisclosureMenu}. Pass a
+ * `Partial<DisclosureMenuSettings>` to the constructor; unset keys fall back to
+ * {@link DisclosureMenu.defaults}.
+ */
+export interface DisclosureMenuSettings extends GarnishBaseSettings {
+  /**
+   * Force the menu below the trigger regardless of clearance. `'below'` pins it
+   * below; any other value (or `null`) lets the clearance logic choose
+   * above/below. Default `null`.
+   */
+  position: string | null;
+  /** Min gap (px) between the menu and the viewport edge. Default `5`. */
+  windowSpacing: number;
+  /**
+   * Render a search input at the top of the menu that filters items by text.
+   * Also enabled when the container carries `data-with-search-input`. Default
+   * `false`.
+   */
+  withSearchInput: boolean;
+}
+
+/**
+ * A single item configuration accepted by {@link DisclosureMenu.addItem} /
+ * {@link DisclosureMenu.createItem}. An already-built `Element` is also accepted
+ * and returned as-is.
+ */
+export interface DisclosureMenuItemConfig {
+  /** `'button'` (default) or `'link'`. Inferred as `'link'` when `url` is set. */
+  type?: 'button' | 'link';
+  /** The link href (implies `type: 'link'`); run through `Craft.getUrl` when present. */
+  url?: string;
+  /** Explicit element id; a unique `menu-item-*` id is generated when omitted. */
+  id?: string;
+  /** Mark the item selected (adds the `sel` class). */
+  selected?: boolean;
+  /** Mark the item destructive (adds `error` + `data-destructive`). */
+  destructive?: boolean;
+  /** Disable the item (adds the `disabled` class). */
+  disabled?: boolean;
+  /** A Craft controller action (adds `formsubmit` + `data-action`). */
+  action?: string;
+  /** An icon: a `data-icon` name string, an `Element`, or a (async) factory. */
+  icon?: string | Element | (() => Promise<Element> | Element);
+  /** A color class applied alongside the icon. */
+  iconColor?: string;
+  /** Action params, as a query string or a JSON-serializable object. */
+  params?: string | Record<string, unknown>;
+  /** A `data-confirm` confirmation message. */
+  confirm?: string;
+  /** A `data-redirect` target. */
+  redirect?: string;
+  /** Extra attributes to set on the item element. */
+  attributes?: Record<string, string>;
+  /** A status indicator class (renders a `status <status>` element). */
+  status?: string;
+  /** The item label (text). */
+  label?: string;
+  /** The item label as raw HTML (used when `label` is absent). */
+  html?: string;
+  /** A secondary description line. */
+  description?: string;
+  /** Start the item hidden. */
+  hidden?: boolean;
+  /** Invoked (with the item element) when the item is activated. */
+  onActivate?: (el: HTMLElement) => void;
+  /** Legacy alias for {@link onActivate}. */
+  callback?: (el: HTMLElement) => void;
+}
+
+/** An item passed to {@link DisclosureMenu.addItem}: a config object or an element. */
+export type DisclosureMenuItem = DisclosureMenuItemConfig | Element;
+
+/** The optional Craft global the legacy item builder leaned on. */
+interface CraftLike {
+  getUrl?(url: string): string;
+  t?(category: string, message: string): string;
+  initUiElements?(el: Element): void;
+}
+
+/** Resolve the Craft global, if present (CP runtime); `undefined` standalone. */
+function getCraft(): CraftLike | undefined {
+  return (globalThis as {Craft?: CraftLike}).Craft;
+}
+
+/** `Craft.getUrl(url)` when available, else the url unchanged. */
+function craftUrl(url: string): string {
+  return getCraft()?.getUrl?.(url) ?? url;
+}
+
+/** `Craft.t('app', message)` when available, else the message unchanged. */
+function craftT(message: string): string {
+  return getCraft()?.t?.('app', message) ?? message;
+}
+
+/**
+ * Maps a trigger / container element back to its `DisclosureMenu` — the native
+ * replacement for the legacy `$el.data('disclosureMenu', this)`. Read it with
+ * {@link DisclosureMenu.getInstance}.
+ */
+const menuElements = new WeakMap<Element, DisclosureMenu>();
+
+/** Type-ahead search-text cache per `<li>` (legacy `$o.data('searchText')`). */
+const searchTextCache = new WeakMap<HTMLElement, string>();
+
+/** Monotonic id source for generated `menu-item-*` ids (deterministic; was `Math.random`). */
+let itemIdCounter = 0;
+
+/**
+ * An accessible disclosure dropdown/menu — the jQuery-free TypeScript port of
+ * Garnish's `DisclosureMenu`. Pairs a trigger button (`aria-controls` /
+ * `aria-expanded`) with a pre-existing menu panel, anchoring it under the
+ * trigger with smart above/below + left/center/right placement, full keyboard
+ * navigation (arrows / Home-less Tab cycle) + type-ahead search, focus
+ * management, a `UiLayerManager` layer + Escape shortcut, optional search input,
+ * and item/group builders.
+ *
+ * Emits `beforeShow`, `show`, `hide`, and `destroy` events (subscribe with
+ * {@link Base.on}). Item selection is per-item: each item's `onActivate` /
+ * `callback` runs on `activate`, then the menu hides.
+ *
+ * @example
+ * ```ts
+ * import {DisclosureMenu} from '@craftcms/garnish';
+ *
+ * // <button aria-controls="menu1" aria-expanded="false">Actions</button>
+ * // <div id="menu1" class="menu menu--disclosure"><ul>…</ul></div>
+ * const menu = new DisclosureMenu(document.querySelector('button')!);
+ * menu.addItem({label: 'Rename', onActivate: () => rename()});
+ * menu.on('show', () => console.log('opened'));
+ * ```
+ */
+export class DisclosureMenu extends Base<DisclosureMenuSettings> {
+  /** Every live `DisclosureMenu` (pushed on construction, removed on {@link destroy}). */
+  static instances: DisclosureMenu[] = [];
+
+  /** Default {@link DisclosureMenuSettings}, merged with the per-instance overrides. */
+  static readonly defaults: DisclosureMenuSettings = {
+    position: null,
+    windowSpacing: 5,
+    withSearchInput: false,
+  };
+
+  /**
+   * The `DisclosureMenu` registered for a trigger or container element, if any —
+   * the native replacement for the legacy `$el.data('disclosureMenu')`.
+   */
+  static getInstance(
+    el: Element | null | undefined
+  ): DisclosureMenu | undefined {
+    return el ? menuElements.get(el) : undefined;
+  }
+
+  // --- Instance state (legacy `$`-prefixed names for consumer parity) ---
+
+  /** The trigger/anchor element. */
+  $trigger: HTMLElement | null = null;
+  /** The menu panel element (referenced by the trigger's `aria-controls`). */
+  $container: HTMLElement | null = null;
+  /** The element the menu aligns to (the trigger, or a `data-align-to` descendant). */
+  $alignmentElement: HTMLElement | null = null;
+  /** The focusable element immediately after the trigger in the DOM, for the Tab cycle. */
+  $nextFocusableElement: HTMLElement | null = null;
+  /** The optional search input (only when `withSearchInput`). */
+  $searchInput: HTMLInputElement | null = null;
+
+  /** The current type-ahead search buffer. */
+  searchStr = '';
+  /** The pending timeout that clears {@link searchStr}, or `null`. */
+  clearSearchStrTimeout: ReturnType<typeof setTimeout> | null = null;
+  /** Tracks an info-icon mousedown so it isn't treated as an outside click. */
+  infoIconActivated = false;
+
+  // Tracked WAAPI fade-out so it can be cancelled on re-show (legacy `.velocity('stop')`).
+  private _anim: Animation | null = null;
+  // The trigger's scroll parent listened to while open (removed on hide).
+  private _scrollParent: Element | null = null;
+
+  // Transient positioning measurements (set per `setContainerPosition` pass).
+  private _vpWidth = 0;
+  private _vpScrollLeft = 0;
+  private _alignOffsetLeft = 0;
+  private _alignWidth = 0;
+  private _menuWidth = 0;
+
+  /**
+   * @param trigger - The trigger element (or selector / `ElementInput`). Must
+   *   carry `aria-controls` pointing at the menu panel (or have it as its next
+   *   sibling).
+   * @param settings - Optional settings overrides (see {@link DisclosureMenuSettings}).
+   */
+  constructor(
+    trigger: ElementInput,
+    settings?: Partial<DisclosureMenuSettings>
+  ) {
+    super();
+
+    this.setSettings(settings, DisclosureMenu.defaults);
+
+    this.$trigger = (getElement(trigger) as HTMLElement | undefined) ?? null;
+
+    // Double-instantiation guard (legacy `$trigger.data('trigger')`).
+    if (this.$trigger && menuElements.has(this.$trigger)) {
+      console.warn('Double-instantiating a disclosure menu on an element');
+      return;
+    }
+
+    this.$trigger?.setAttribute('data-disclosure-trigger', 'true');
+
+    // Resolve the container from `aria-controls` (or the next sibling).
+    const containerId = this.$trigger?.getAttribute('aria-controls') ?? null;
+    let container: HTMLElement | null = containerId
+      ? document.getElementById(containerId)
+      : null;
+    if (!container && containerId) {
+      const next = this.$trigger?.nextElementSibling;
+      if (next instanceof HTMLElement && next.id === containerId) {
+        container = next;
+      }
+    }
+    if (!container) {
+      throw 'No disclosure container found.';
+    }
+    this.$container = container;
+
+    if (this.$trigger) {
+      menuElements.set(this.$trigger, this);
+    }
+    menuElements.set(this.$container, this);
+
+    // Ensure the trigger advertises a collapsed state for a11y.
+    if (!this.$trigger?.getAttribute('aria-expanded')) {
+      this.$trigger?.setAttribute('aria-expanded', 'false');
+    }
+
+    this.captureAlignmentElement();
+
+    bod.appendChild(this.$container);
+
+    // If the trigger lives in a slideout, (re)initialize its UI elements.
+    if (this.$trigger?.closest('.slideout')) {
+      getCraft()?.initUiElements?.(this.$container);
+    }
+
+    this.addDisclosureMenuEventListeners();
+
+    // Add a search input?
+    this.settings!.withSearchInput =
+      this.settings!.withSearchInput ||
+      this.$container.hasAttribute('data-with-search-input');
+    if (this.settings!.withSearchInput) {
+      this.addSearchInput();
+    }
+
+    DisclosureMenu.instances.push(this);
+  }
+
+  /**
+   * (Re)capture the alignment element: the `data-align-to` descendant of the
+   * trigger, if set, otherwise the trigger itself.
+   */
+  captureAlignmentElement(): void {
+    const alignmentSelector = this.$container?.getAttribute('data-align-to');
+    if (alignmentSelector && this.$trigger) {
+      this.$alignmentElement =
+        this.$trigger.querySelector<HTMLElement>(alignmentSelector) ??
+        this.$trigger;
+    } else {
+      this.$alignmentElement = this.$trigger;
+    }
+  }
+
+  /** Build and wire the optional search input at the top of the menu. */
+  addSearchInput(): void {
+    const outer = document.createElement('div');
+    outer.className = 'search-container';
+    this.$container!.prepend(outer);
+
+    const inner = document.createElement('div');
+    inner.className = 'texticon search icon clearable';
+    outer.appendChild(inner);
+
+    this.$searchInput = document.createElement('input');
+    this.$searchInput.className = 'fullwidth text';
+    this.$searchInput.type = 'text';
+    this.$searchInput.setAttribute('inputmode', 'search');
+    this.$searchInput.autocomplete = 'off';
+    this.$searchInput.placeholder = craftT('Search');
+    inner.appendChild(this.$searchInput);
+
+    const clearBtn = document.createElement('div');
+    clearBtn.className = 'clear-btn hidden';
+    clearBtn.title = craftT('Clear');
+    clearBtn.setAttribute('aria-label', craftT('Clear'));
+    inner.appendChild(clearBtn);
+
+    this.addListener(this.$searchInput, 'input', () => {
+      this._applySearchFilter(this.$searchInput!.value, clearBtn);
+    });
+
+    this.addListener(this.$searchInput, 'keydown', (event) => {
+      const ev = event as unknown as KeyboardEvent;
+      switch (ev.keyCode) {
+        case ESC_KEY:
+          this.$searchInput!.value = '';
+          this._applySearchFilter('', clearBtn);
+          break;
+        case RETURN_KEY:
+          // They most likely don't want to submit the form from here.
+          ev.preventDefault();
+          break;
+      }
+    });
+
+    this.addListener(clearBtn, 'click', () => {
+      this.$searchInput!.value = '';
+      this._applySearchFilter('', clearBtn);
+      this.$searchInput!.focus();
+    });
+  }
+
+  /** Apply the search filter to the menu items (factored out of the input handler). */
+  private _applySearchFilter(rawValue: string, clearBtn: HTMLElement): void {
+    const val = rawValue.toLowerCase().replace(/['"]/g, '');
+    const options = Array.from(
+      this.$container!.querySelectorAll<HTMLElement>('li')
+    );
+
+    if (val) {
+      clearBtn.classList.remove('hidden');
+      const matches = new Set<HTMLElement>();
+      for (const option of options) {
+        if ((option.textContent ?? '').toLowerCase().includes(val)) {
+          matches.add(option);
+        }
+      }
+      for (const option of options) {
+        if (matches.has(option)) {
+          option.classList.remove('filtered');
+        } else {
+          option.classList.add('filtered');
+        }
+      }
+
+      // Also match the headings: a matching <h3> un-filters its group's items.
+      for (const heading of Array.from(
+        this.$container!.querySelectorAll<HTMLElement>('h3')
+      )) {
+        if ((heading.textContent ?? '').toLowerCase().includes(val)) {
+          const ul = heading.nextElementSibling;
+          if (ul && ul.tagName === 'UL') {
+            ul.querySelectorAll('li.filtered').forEach((li) =>
+              li.classList.remove('filtered')
+            );
+          }
+        }
+      }
+    } else {
+      clearBtn.classList.add('hidden');
+      for (const option of options) {
+        option.classList.remove('filtered');
+      }
+    }
+
+    this.updateVisibility();
+    this.setContainerPosition();
+  }
+
+  /** Wire the trigger / container / document event listeners (legacy parity). */
+  addDisclosureMenuEventListeners(): void {
+    this.addListener(this.$trigger, 'mousedown', (event) => {
+      const ev = event as unknown as MouseEvent;
+      ev.stopPropagation();
+      ev.preventDefault();
+
+      // Let the other disclosure menus know about it, at least.
+      for (const disclosureMenu of DisclosureMenu.instances) {
+        if (disclosureMenu !== this) {
+          disclosureMenu.handleMousedown(ev);
+        }
+      }
+    });
+
+    this.addListener(this.$trigger, 'mouseup', (event) => {
+      const ev = event as unknown as MouseEvent;
+      ev.stopPropagation();
+      ev.preventDefault();
+    });
+
+    this.addListener(this.$trigger, 'click', (event) => {
+      const ev = event as unknown as MouseEvent;
+      ev.stopPropagation();
+      ev.preventDefault();
+      this.handleTriggerClick();
+    });
+
+    this.addListener(this.$container, 'keydown', (event) => {
+      this.handleKeypress(event as unknown as KeyboardEvent);
+    });
+
+    this.addListener(doc, 'mousedown', (event) => {
+      this.handleMousedown(event as unknown as MouseEvent);
+    });
+
+    // When the menu is expanded, tabbing on the trigger should move focus into it.
+    this.addListener(this.$trigger, 'keydown', (event) => {
+      const ev = event as unknown as KeyboardEvent;
+      if (ev.keyCode === TAB_KEY && !ev.shiftKey && this.isExpanded()) {
+        const focusable = getFocusableElements(this.$container!)[0];
+        if (focusable) {
+          ev.preventDefault();
+          focusable.focus();
+        }
+      }
+    });
+  }
+
+  /**
+   * Focus a menu element. With an `HTMLElement`, focuses it (or its first
+   * focusable descendant). With `'prev'`/`'next'`, moves focus to the
+   * previous/next focusable element within the container.
+   */
+  focusElement(component: HTMLElement | 'prev' | 'next'): void {
+    if (component instanceof HTMLElement) {
+      if (isFocusable(component)) {
+        component.focus();
+      } else {
+        getFocusableElements(component)[0]?.focus();
+      }
+      return;
+    }
+
+    const focusable = getFocusableElements(this.$container!);
+    const currentIndex = focusable.indexOf(
+      document.activeElement as HTMLElement
+    );
+    const newIndex = component === 'prev' ? currentIndex - 1 : currentIndex + 1;
+
+    if (newIndex >= 0 && newIndex < focusable.length) {
+      focusable[newIndex]!.focus();
+    }
+  }
+
+  /** Outside-click handler: hide the menu unless the click was inside it / its trigger. */
+  handleMousedown(event: MouseEvent): void {
+    const target = event.target as Element | null;
+
+    // If the info icon was previously activated, reset and ignore this mousedown.
+    if (this.infoIconActivated) {
+      this.infoIconActivated = false;
+      return;
+    }
+
+    if (target && (target as HTMLElement).classList?.contains('info')) {
+      this.infoIconActivated = true;
+    }
+
+    // Click on this disclosure's trigger → do nothing.
+    const trigger = target?.closest('[data-disclosure-trigger]') ?? null;
+    if (trigger && trigger === this.$trigger) {
+      return;
+    }
+
+    // Click inside this disclosure's container → do nothing.
+    if (
+      this.$container === event.target ||
+      (target && this.$container!.contains(target))
+    ) {
+      return;
+    }
+
+    // Click inside a nested disclosure whose trigger lives in this menu → do nothing.
+    const nested = target?.closest('.menu--disclosure') ?? null;
+    if (nested) {
+      const disclosure = menuElements.get(nested);
+      if (
+        disclosure &&
+        disclosure.$trigger &&
+        this.$container!.contains(disclosure.$trigger)
+      ) {
+        return;
+      }
+    }
+
+    this.hide();
+  }
+
+  /** Keyboard handler bound to the container: arrows, Tab cycle, and type-ahead. */
+  handleKeypress(ev: KeyboardEvent): void {
+    if (isCtrlKeyPressed(ev)) {
+      return;
+    }
+
+    switch (ev.keyCode) {
+      case RIGHT_KEY:
+      case DOWN_KEY:
+        ev.preventDefault();
+        this.focusElement('next');
+        return;
+      case LEFT_KEY:
+      case UP_KEY:
+        ev.preventDefault();
+        this.focusElement('prev');
+        return;
+      case TAB_KEY: {
+        const focusable = getFocusableElements(this.$container!);
+        const index = focusable.indexOf(ev.target as HTMLElement);
+
+        if (index === 0 && ev.shiftKey) {
+          ev.preventDefault();
+          this.$trigger?.focus();
+        } else if (
+          index === focusable.length - 1 &&
+          !ev.shiftKey &&
+          this.$nextFocusableElement
+        ) {
+          ev.preventDefault();
+          this.$nextFocusableElement.focus();
+        }
+        return;
+      }
+    }
+
+    // Type-ahead search: a printable key (or space, mid-search) focuses the first
+    // matching option.
+    if (
+      (ev.target as Element).nodeName !== 'INPUT' &&
+      ev.key &&
+      (ev.key.match(/^[^ ]$/) || (this.searchStr.length && ev.key === ' '))
+    ) {
+      this.searchStr += ev.key.toLowerCase();
+
+      let match: HTMLElement | undefined;
+      const options = Array.from(
+        this.$container!.querySelectorAll<HTMLElement>('li')
+      );
+      for (const option of options) {
+        if (!searchTextCache.has(option)) {
+          // Clone without nested SVGs, then take its trimmed lowercase text.
+          const clone = option.cloneNode(true) as HTMLElement;
+          clone.querySelectorAll('svg').forEach((svg) => svg.remove());
+          searchTextCache.set(
+            option,
+            (clone.textContent ?? '').toLowerCase().trimStart()
+          );
+        }
+        if (searchTextCache.get(option)!.startsWith(this.searchStr)) {
+          match = option;
+          break;
+        }
+      }
+
+      if (match) {
+        this.focusElement(match);
+      }
+
+      if (this.clearSearchStrTimeout) {
+        clearTimeout(this.clearSearchStrTimeout);
+      }
+      this.clearSearchStrTimeout = setTimeout(() => {
+        this.clearSearchStr();
+      }, 1000);
+    }
+  }
+
+  /** Whether the menu is currently expanded (reads the trigger's `aria-expanded`). */
+  isExpanded(): boolean {
+    return this.$trigger?.getAttribute('aria-expanded') === 'true';
+  }
+
+  /** Toggle the menu on a trigger click (re-capturing the alignment element first). */
+  handleTriggerClick(): void {
+    if (!this.isExpanded()) {
+      this.captureAlignmentElement();
+      this.show();
+    } else {
+      this.hide();
+    }
+  }
+
+  /**
+   * Show the menu: move it to the end of `<body>`, position it under the
+   * trigger, wire scroll/resize repositioning, reveal it, focus the first item,
+   * register the UI layer + Escape shortcut, and emit `beforeShow` then `show`.
+   * No-op if already expanded or the trigger is disabled.
+   */
+  show(): void {
+    if (this.isExpanded() || this.$trigger?.classList.contains('disabled')) {
+      return;
+    }
+
+    this.trigger('beforeShow');
+
+    // Move the menu to the end of the DOM (highest sub-z-index).
+    bod.appendChild(this.$container!);
+
+    this.setContainerPosition();
+    this.addListener(globals.scrollContainer, 'scroll', 'setContainerPosition');
+
+    const scrollParent = this.$trigger
+      ? getScrollParent(this.$trigger)
+      : globals.scrollContainer;
+    if (scrollParent instanceof Element && scrollParent !== bod) {
+      this._scrollParent = scrollParent;
+      this.addListener(scrollParent, 'scroll', 'setContainerPosition');
+    }
+    this.addListener(win, 'resize', 'setContainerPosition');
+
+    // Reveal (instant — legacy only fades on hide).
+    this._cancelAnim();
+    this.$container!.classList.add('visible');
+    this.$container!.style.opacity = '1';
+    if (window.getComputedStyle(this.$container!).display === 'none') {
+      this.$container!.style.display = 'block';
+    }
+
+    this.$trigger?.setAttribute('aria-expanded', 'true');
+
+    // Focus the first focusable element (or the container itself).
+    const firstFocusable = getFocusableElements(this.$container!)[0];
+    if (firstFocusable) {
+      firstFocusable.focus();
+    } else {
+      this.$container!.setAttribute('tabindex', '-1');
+      this.$container!.focus();
+    }
+
+    // Find the next focusable element after the trigger; Shift-Tab on it should
+    // take focus back into the container.
+    if (this.$trigger) {
+      const focusableElements = getFocusableElements(bod);
+      const triggerIndex = focusableElements.indexOf(this.$trigger);
+      if (triggerIndex !== -1 && focusableElements.length > triggerIndex + 1) {
+        this.$nextFocusableElement = focusableElements[triggerIndex + 1]!;
+        this.addListener(this.$nextFocusableElement, 'keydown', (event) => {
+          const ev = event as unknown as KeyboardEvent;
+          if (ev.keyCode === TAB_KEY && ev.shiftKey) {
+            const items = getFocusableElements(this.$container!);
+            const last = items[items.length - 1];
+            if (last) {
+              ev.preventDefault();
+              last.focus();
+            }
+          }
+        });
+      }
+    }
+
+    this.trigger('show');
+    this.clearSearchStr();
+
+    const manager = getUiLayerManager();
+    manager?.addLayer(this.$container ?? undefined);
+    manager?.registerShortcut(ESC_KEY, () => {
+      this.hide();
+    });
+  }
+
+  /**
+   * Hide the menu: restore focus to the trigger if focus was inside, drop the
+   * Tab-cycle + scroll/resize listeners, pop the UI layer, clear the search
+   * input/buffer, emit `hide`, then fade the panel out. No-op if not expanded.
+   */
+  hide(): void {
+    if (!this.isExpanded()) {
+      return;
+    }
+
+    this._cancelAnim();
+    this.$trigger?.setAttribute('aria-expanded', 'false');
+
+    if (this.focusIsInMenu()) {
+      this.$trigger?.focus();
+    }
+
+    if (this.$nextFocusableElement) {
+      this.removeListener(this.$nextFocusableElement, 'keydown');
+      this.$nextFocusableElement = null;
+    }
+
+    if (this.$searchInput) {
+      this.$searchInput.value = '';
+      const clearBtn =
+        this.$container!.querySelector<HTMLElement>('.clear-btn');
+      if (clearBtn) {
+        this._applySearchFilter('', clearBtn);
+      }
+    }
+
+    this.trigger('hide');
+    this.clearSearchStr();
+
+    this.removeListener(globals.scrollContainer, 'scroll');
+    if (this._scrollParent) {
+      this.removeListener(this._scrollParent, 'scroll');
+      this._scrollParent = null;
+    }
+    this.removeListener(win, 'resize');
+    getUiLayerManager()?.removeLayer(this.$container ?? undefined);
+
+    // Fade the panel out, then drop the `visible` class + inline display.
+    this._fadeOutContainer();
+  }
+
+  /** Whether keyboard focus currently lives inside the menu container. */
+  focusIsInMenu(): boolean {
+    return !!this.$container && focusIsInside(this.$container);
+  }
+
+  /**
+   * Position the menu under (or above) the trigger and align it
+   * left/center/right within the viewport. A faithful port of the legacy
+   * `setContainerPosition` clearance math.
+   */
+  setContainerPosition(): void {
+    const container = this.$container;
+    const alignmentElement = this.$alignmentElement;
+    if (!container || !alignmentElement) {
+      return;
+    }
+
+    const settings = this.settings!;
+
+    const vpWidth = window.innerWidth;
+    const vpHeight = window.innerHeight;
+    const vpScrollLeft = window.scrollX;
+    const vpScrollTop = window.scrollY;
+
+    const alignOffset = jQueryOffset(alignmentElement);
+    const alignWidth = getOuterWidth(alignmentElement);
+    const alignHeight = getOuterHeight(alignmentElement);
+    const alignOffsetRight = alignOffset.left + alignWidth;
+    const alignOffsetBottom = alignOffset.top + alignHeight;
+
+    // Re-measure from scratch (clear any prior max-width clamp).
+    container.style.maxWidth = '';
+    container.style.minWidth = '0';
+    container.style.minWidth = `${
+      alignWidth - (getOuterWidth(container) - getContentWidth(container))
+    }px`;
+
+    let menuWidth = getOuterWidth(container);
+    const menuHeight = getOuterHeight(container);
+
+    if (menuWidth > vpWidth) {
+      container.style.maxWidth = `${vpWidth}px`;
+      menuWidth = vpWidth;
+    }
+
+    // Is there room for the menu below the trigger?
+    const topClearance = alignOffset.top - vpScrollTop;
+    const bottomClearance = vpHeight + vpScrollTop - alignOffsetBottom;
+
+    if (
+      settings.position === 'below' ||
+      bottomClearance >= menuHeight ||
+      (topClearance < menuHeight && bottomClearance >= topClearance)
+    ) {
+      container.style.top = `${alignOffsetBottom}px`;
+      container.style.maxHeight = `${bottomClearance - settings.windowSpacing}px`;
+    } else {
+      container.style.top = `${
+        alignOffset.top -
+        Math.min(menuHeight, topClearance - settings.windowSpacing)
+      }px`;
+      container.style.maxHeight = `${topClearance - settings.windowSpacing}px`;
+    }
+
+    // Stash transient values for the _align* helpers.
+    this._vpWidth = vpWidth;
+    this._vpScrollLeft = vpScrollLeft;
+    this._alignOffsetLeft = alignOffset.left;
+    this._alignWidth = alignWidth;
+    this._menuWidth = menuWidth;
+
+    // Figure out how we're aligning it.
+    let align = container.getAttribute('data-align');
+    if (align !== 'left' && align !== 'center' && align !== 'right') {
+      align = 'left';
+    }
+
+    if (menuWidth === vpWidth || align === 'center') {
+      this._alignCenter();
+    } else {
+      const rightClearance =
+        vpWidth + vpScrollLeft - (alignOffset.left + menuWidth);
+      const leftClearance = alignOffsetRight - menuWidth;
+
+      if (leftClearance < 0 && rightClearance < 0) {
+        this._alignCenter();
+      } else if (
+        (align === 'right' && leftClearance >= 0) ||
+        rightClearance < 0
+      ) {
+        this._alignRight();
+      } else {
+        this._alignLeft();
+      }
+    }
+  }
+
+  /** Clear the type-ahead search buffer + its pending timeout. */
+  clearSearchStr(): void {
+    this.searchStr = '';
+    if (this.clearSearchStrTimeout) {
+      clearTimeout(this.clearSearchStrTimeout);
+      this.clearSearchStrTimeout = null;
+    }
+  }
+
+  /** Whether the menu uses padded groups (a direct child `<tag>.padded`). */
+  isPadded(tag = 'ul'): boolean {
+    return !!this.$container?.querySelector(`:scope > ${tag}.padded`);
+  }
+
+  /**
+   * Build a menu item element from a config object (or pass an existing element
+   * through). Returns the `<li>` wrapper.
+   */
+  createItem(item: DisclosureMenuItem): HTMLLIElement {
+    if (item instanceof Element) {
+      // Already a built element (e.g. an <li>); return it as-is.
+      return item as HTMLLIElement;
+    }
+
+    if (!isPlainObject(item)) {
+      throw 'Unsupported item configuration.';
+    }
+
+    const config = item as DisclosureMenuItemConfig;
+
+    let type: 'button' | 'link';
+    if (config.type) {
+      type = config.type;
+    } else if (config.url) {
+      type = 'link';
+    } else {
+      type = 'button';
+    }
+
+    const li = document.createElement('li');
+    const el = document.createElement(type === 'button' ? 'button' : 'a');
+
+    if (type === 'button') {
+      el.setAttribute('type', 'button');
+    }
+
+    el.id = config.id || `menu-item-${++itemIdCounter}`;
+    el.className = 'menu-item';
+    if (config.selected) {
+      el.classList.add('sel');
+    }
+    if (config.destructive) {
+      el.classList.add('error');
+      el.setAttribute('data-destructive', 'true');
+    }
+    if (config.disabled) {
+      el.classList.add('disabled');
+    }
+    if (config.action) {
+      // The CP's form-submit machinery keys off the `formsubmit` class +
+      // `data-action`; the legacy `$(el).formsubmit()` jQuery call is omitted
+      // here to keep the bundle jQuery-free (doc 16).
+      el.classList.add('formsubmit');
+    }
+    if (type === 'link') {
+      (el as HTMLAnchorElement).href = craftUrl(config.url ?? '');
+    }
+    if (config.icon) {
+      if (typeof config.icon === 'string') {
+        el.setAttribute('data-icon', config.icon);
+        if (config.iconColor) {
+          el.classList.add(config.iconColor);
+        }
+      } else {
+        const iconSource = config.icon;
+        void (async () => {
+          let icon: Element;
+          if (iconSource instanceof Element) {
+            icon = iconSource;
+          } else if (typeof iconSource === 'function') {
+            icon = await iconSource();
+          } else {
+            throw 'Unsupported icon type';
+          }
+          const span = document.createElement('span');
+          span.className = 'icon';
+          if (config.iconColor) {
+            span.classList.add(config.iconColor);
+          }
+          span.append(icon);
+          el.prepend(span);
+        })();
+      }
+    }
+    if (config.action) {
+      el.setAttribute('data-action', config.action);
+      el.setAttribute('data-form', 'false');
+    }
+    if (config.params) {
+      el.setAttribute(
+        'data-params',
+        typeof config.params === 'string'
+          ? config.params
+          : JSON.stringify(config.params)
+      );
+    }
+    if (config.confirm) {
+      el.setAttribute('data-confirm', config.confirm);
+    }
+    if (config.redirect) {
+      el.setAttribute('data-redirect', config.redirect);
+    }
+    if (config.attributes) {
+      for (const name in config.attributes) {
+        el.setAttribute(name, config.attributes[name]!);
+      }
+    }
+    li.append(el);
+
+    if (config.status) {
+      const status = document.createElement('div');
+      status.className = `status ${config.status}`;
+      el.append(status);
+    }
+
+    const label = document.createElement('span');
+    label.className = 'menu-item-label';
+    if (config.label) {
+      label.textContent = config.label;
+    } else if (config.html) {
+      label.innerHTML = config.html;
+    }
+    el.append(label);
+
+    if (config.description) {
+      const description = document.createElement('div');
+      description.className = 'menu-item-description smalltext light';
+      description.textContent = config.description;
+      el.append(description);
+    }
+
+    if (type === 'link') {
+      this.addListener(el, 'keydown', (event) => {
+        if ((event as unknown as KeyboardEvent).keyCode === SPACE_KEY) {
+          (el as HTMLElement).click();
+        }
+      });
+    }
+
+    this.addListener(el, 'activate', () => {
+      if (config.onActivate) {
+        config.onActivate(el as HTMLElement);
+      } else if (config.callback) {
+        config.callback(el as HTMLElement);
+      }
+      setTimeout(() => {
+        this.hide();
+      }, 1);
+    });
+
+    return li;
+  }
+
+  /** Append a new empty `<ul>` group to the menu and return it. */
+  addList(): HTMLUListElement {
+    const ul = document.createElement('ul');
+    this.$container!.appendChild(ul);
+    return ul;
+  }
+
+  /**
+   * Add an item to the menu. Builds it via {@link createItem}, appends (or
+   * prepends) it to `ul` (defaulting to the last group, creating one if needed),
+   * shows/hides it, and returns the item's `<a>`/`<button>` element.
+   */
+  addItem(
+    item: DisclosureMenuItem,
+    ul?: HTMLElement | null,
+    prepend = false
+  ): HTMLElement {
+    const li = this.createItem(item);
+
+    if (!ul) {
+      ul = this.lastChildUl() ?? this.addGroup();
+    }
+
+    if (prepend) {
+      ul.prepend(li);
+    } else {
+      ul.append(li);
+    }
+
+    const el = li.querySelector<HTMLElement>('a, button')!;
+    const hidden =
+      !(item instanceof Element) && (item as DisclosureMenuItemConfig).hidden;
+
+    // Show or hide it (show, in case the UL is already hidden).
+    this.toggleItem(el, !hidden);
+    this.updateVisibility();
+
+    return el;
+  }
+
+  /** Add several items to the menu (optionally into a given group). */
+  addItems(items: DisclosureMenuItem[], ul?: HTMLElement | null): void {
+    for (const item of items) {
+      this.addItem(item, ul);
+    }
+  }
+
+  /** Add a horizontal rule, either before `before` or at the end of the menu. */
+  addHr(before?: Element | null): HTMLHRElement {
+    const hr = document.createElement('hr');
+    if (this.isPadded('hr')) {
+      hr.className = 'padded';
+    }
+
+    if (before) {
+      before.parentNode?.insertBefore(hr, before);
+    } else {
+      this.$container!.append(hr);
+    }
+
+    return hr;
+  }
+
+  /** The first group `<ul>` containing a destructive item, if any. */
+  getFirstDestructiveGroup(): HTMLUListElement | undefined {
+    for (const child of Array.from(this.$container!.children)) {
+      if (child.tagName === 'UL' && child.querySelector('[data-destructive]')) {
+        return child as HTMLUListElement;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Add a group (an optional `<h3>` heading + a `<ul>`), with surrounding
+   * `<hr>`s by default, either before `before` or at the end. Returns the `<ul>`.
+   */
+  addGroup(
+    heading: string | null = null,
+    addHrs = true,
+    before: Element | null = null
+  ): HTMLUListElement {
+    const padded = this.isPadded();
+
+    if (heading) {
+      const h3 = document.createElement('h3');
+      h3.classList.add('h6');
+      if (padded) {
+        h3.classList.add('padded');
+      }
+      h3.textContent = heading;
+
+      if (before) {
+        before.parentNode?.insertBefore(h3, before);
+      } else {
+        this.$container!.append(h3);
+      }
+    }
+
+    const ul = document.createElement('ul');
+    if (padded) {
+      ul.className = 'padded';
+    }
+
+    if (before) {
+      before.parentNode?.insertBefore(ul, before);
+    } else {
+      this.$container!.append(ul);
+    }
+
+    if (addHrs) {
+      const prev = ul.previousElementSibling;
+      if (
+        prev &&
+        prev.nodeName !== 'HR' &&
+        !prev.classList.contains('search-container')
+      ) {
+        this.addHr(ul);
+      }
+      if (ul.nextElementSibling && ul.nextElementSibling.nodeName !== 'HR') {
+        this.addHr(ul.nextElementSibling);
+      }
+    }
+
+    this.updateVisibility();
+
+    return ul;
+  }
+
+  /** Show or hide an item's `<li>`. Defaults to flipping the current state. */
+  toggleItem(el: HTMLElement, show?: boolean): void {
+    if (typeof show === 'undefined') {
+      show = el.parentElement!.classList.contains('hidden');
+    }
+
+    if (show) {
+      this.showItem(el);
+    } else {
+      this.hideItem(el);
+    }
+  }
+
+  /** Reveal an item's `<li>` and re-run visibility/positioning. */
+  showItem(el: HTMLElement): void {
+    el.parentElement!.classList.remove('hidden');
+    this.updateVisibility();
+    if (this.isExpanded()) {
+      this.setContainerPosition();
+    }
+  }
+
+  /** Hide an item's `<li>` and re-run visibility/positioning. */
+  hideItem(el: HTMLElement): void {
+    el.parentElement!.classList.add('hidden');
+    this.updateVisibility();
+    if (this.isExpanded()) {
+      this.setContainerPosition();
+    }
+  }
+
+  /** Show/hide a group based on whether it has any visible (non-filtered) items. */
+  toggleGroup(group: HTMLElement): void {
+    if (group.querySelectorAll('li:not(.hidden):not(.filtered)').length) {
+      group.classList.remove('hidden');
+    } else {
+      group.classList.add('hidden');
+    }
+  }
+
+  /** Remove an item; drops its group too if it becomes empty. */
+  removeItem(el: HTMLElement): void {
+    const li = el.parentElement!;
+    const ul = li.parentElement!;
+    li.remove();
+    if (ul.querySelectorAll(':scope > li').length === 0) {
+      ul.remove();
+    }
+
+    this.updateVisibility();
+    if (this.isExpanded()) {
+      this.setContainerPosition();
+    }
+  }
+
+  /** @deprecated Use {@link updateVisibility}. */
+  updateHrVisibility(): void {
+    this.updateVisibility();
+  }
+
+  /**
+   * Recompute group / `<hr>` / heading visibility: hide empty groups, hide
+   * `<hr>`s without visible items on both sides, and hide headings with no
+   * following visible items.
+   */
+  updateVisibility(): void {
+    const container = this.$container!;
+
+    for (const group of Array.from(
+      container.querySelectorAll<HTMLElement>(
+        ':scope > ul, :scope > .menu-group'
+      )
+    )) {
+      this.toggleGroup(group);
+    }
+
+    for (const hr of Array.from(
+      container.querySelectorAll<HTMLElement>('hr')
+    )) {
+      const prevVisible = siblingsUntil(hr, 'h3, hr', 'prev').some(
+        isVisibleItem
+      );
+      const nextVisible = siblingsUntil(hr, 'h3, hr', 'next').some(
+        isVisibleItem
+      );
+      if (prevVisible && nextVisible) {
+        hr.classList.remove('hidden');
+      } else {
+        hr.classList.add('hidden');
+      }
+    }
+
+    for (const h3 of Array.from(
+      container.querySelectorAll<HTMLElement>('h3')
+    )) {
+      const nextVisible = siblingsUntil(h3, 'h3, hr', 'next').some(
+        isVisibleItem
+      );
+      if (nextVisible) {
+        h3.classList.remove('hidden');
+      } else {
+        h3.classList.add('hidden');
+      }
+    }
+  }
+
+  /** Whether the menu has any non-hidden items. */
+  hasVisibleItems(): boolean {
+    return !!this.$container?.querySelector('li:not(.hidden)');
+  }
+
+  /**
+   * Destroy the menu: drop the trigger/container element registrations, remove
+   * it from {@link DisclosureMenu.instances}, clear the search timeout, then run
+   * the base teardown (emits `destroy`, removes all listeners).
+   */
+  override destroy(): void {
+    if (this.$trigger) {
+      menuElements.delete(this.$trigger);
+    }
+    if (this.$container) {
+      menuElements.delete(this.$container);
+    }
+
+    this.clearSearchStr();
+    this._cancelAnim();
+
+    DisclosureMenu.instances = DisclosureMenu.instances.filter(
+      (o) => o !== this
+    );
+
+    super.destroy();
+  }
+
+  // --- Internals ------------------------------------------------------------
+
+  /** The last direct-child `<ul>` of the container, if any. */
+  private lastChildUl(): HTMLUListElement | null {
+    const uls =
+      this.$container!.querySelectorAll<HTMLUListElement>(':scope > ul');
+    return uls.length ? uls[uls.length - 1]! : null;
+  }
+
+  private _alignLeft(): void {
+    this.$container!.style.left = `${Math.max(this._alignOffsetLeft, 0)}px`;
+    this.$container!.style.right = 'auto';
+  }
+
+  private _alignRight(): void {
+    const right = this._vpWidth - (this._alignOffsetLeft + this._alignWidth);
+    this.$container!.style.right = `${Math.max(right, 0)}px`;
+    this.$container!.style.left = 'auto';
+  }
+
+  private _alignCenter(): void {
+    const left = Math.round(
+      this._alignOffsetLeft + this._alignWidth / 2 - this._menuWidth / 2
+    );
+    this.$container!.style.left = `${Math.max(left, 0)}px`;
+    this.$container!.style.right = 'auto';
+  }
+
+  /**
+   * Fade the container out (Web Animations API), then strip the `visible` class
+   * and inline display. Gated on `prefersReducedMotion` / environments without
+   * `element.animate` (happy-dom), which finalize synchronously.
+   */
+  private _fadeOutContainer(): void {
+    const el = this.$container!;
+    const finalize = (): void => {
+      el.style.opacity = '0';
+      el.classList.remove('visible');
+      el.style.display = '';
+      this._anim = null;
+    };
+
+    if (prefersReducedMotion() || typeof el.animate !== 'function') {
+      finalize();
+      return;
+    }
+
+    el.style.opacity = '1';
+    const anim = el.animate([{opacity: 1}, {opacity: 0}], {
+      duration: FADE_OUT_DURATION,
+      fill: 'forwards',
+    });
+    this._anim = anim;
+    anim.onfinish = finalize;
+    anim.oncancel = (): void => {
+      this._anim = null;
+    };
+  }
+
+  /** Cancel a pending fade-out (legacy `.velocity('stop')`). */
+  private _cancelAnim(): void {
+    if (this._anim) {
+      this._anim.cancel();
+    }
+    this._anim = null;
+  }
+}
+
+/** Document-relative offset rectangle (jQuery `.offset()` parity). */
+function jQueryOffset(el: Element): {top: number; left: number} {
+  const rect = el.getBoundingClientRect();
+  return {top: rect.top + window.scrollY, left: rect.left + window.scrollX};
+}
+
+/**
+ * Content-box width (jQuery `.width()` parity): the border-box width from
+ * `getBoundingClientRect()` minus horizontal padding + border. Using the rect
+ * (not `clientWidth`) keeps it mockable in layout-less test environments.
+ */
+function getContentWidth(el: HTMLElement): number {
+  const cs = window.getComputedStyle(el);
+  return (
+    el.getBoundingClientRect().width -
+    (parseFloat(cs.paddingLeft) || 0) -
+    (parseFloat(cs.paddingRight) || 0) -
+    (parseFloat(cs.borderLeftWidth) || 0) -
+    (parseFloat(cs.borderRightWidth) || 0)
+  );
+}
+
+/** Whether a menu sibling counts as a visible item (not `hidden`/`filtered`). */
+function isVisibleItem(el: Element): boolean {
+  return !el.classList.contains('hidden') && !el.classList.contains('filtered');
+}
+
+/**
+ * Collect siblings of `el` in the given direction up to (but not including) the
+ * first sibling matching `stopSelector` — the native replacement for jQuery's
+ * `.prevUntil()` / `.nextUntil()`.
+ */
+function siblingsUntil(
+  el: Element,
+  stopSelector: string,
+  direction: 'prev' | 'next'
+): Element[] {
+  const out: Element[] = [];
+  let node =
+    direction === 'prev' ? el.previousElementSibling : el.nextElementSibling;
+  while (node) {
+    if (node.matches(stopSelector)) {
+      break;
+    }
+    out.push(node);
+    node =
+      direction === 'prev'
+        ? node.previousElementSibling
+        : node.nextElementSibling;
+  }
+  return out;
+}
+
+export default DisclosureMenu;
diff --git a/packages/craftcms-garnish/src/dom-listeners.ts b/packages/craftcms-garnish/src/dom-listeners.ts
new file mode 100644
index 00000000000..6ce6bae0df6
--- /dev/null
+++ b/packages/craftcms-garnish/src/dom-listeners.ts
@@ -0,0 +1,292 @@
+/**
+ * Namespaced DOM-listener registry — jQuery-free replacement for
+ * `Base.addListener/removeListener/removeAllListeners`.
+ *
+ * Native `addEventListener` has no namespace concept, so the registry stores a
+ * tuple per binding `{element, type, namespace, wrappedHandler, capture}` and
+ * replays jQuery's namespaced `.off` semantics over that array.
+ *
+ * Custom Garnish event types (`activate`/`textchange`/`resize`) are routed
+ * through the matching installer so `addListener(el, 'activate', fn)` keeps
+ * working.
+ */
+
+import {parseEvents} from './events';
+import type {GarnishEvent, GarnishEventHandler} from './events';
+import type {ElementInput} from './types';
+import {coerceElements} from './utils/dom';
+import {globals} from './globals';
+import {
+  installActivate,
+  installResize,
+  installTextchange,
+} from './custom-events';
+
+export type {ElementInput} from './types';
+
+export interface DomListenerOptions {
+  /** Delegated target selector; handler fires only when the event target matches/closests this. */
+  delegate?: string;
+  /** Extra data; used by custom events (e.g. textchange `delay`). Merged into the event object. */
+  data?: Record<string, unknown>;
+  capture?: boolean;
+  passive?: boolean;
+}
+
+/** The minimal host contract the registry needs (a `Base`). */
+export interface DomListenerHost {
+  readonly disabled: boolean;
+}
+
+interface Binding {
+  element: EventTarget;
+  type: string;
+  namespace: string | null;
+  wrappedHandler: EventListener;
+  capture: boolean;
+  /** Disposer for synthetic custom events; native listeners use removeEventListener. */
+  dispose?: () => void;
+}
+
+const CUSTOM_EVENT_TYPES = new Set(['activate', 'textchange', 'resize']);
+
+/**
+ * The namespaced DOM-listener registry that backs {@link Base.addListener} /
+ * `removeListener` / `removeAllListeners`. Each `Base` owns one. It records every
+ * binding so jQuery-style namespaced removal and bulk teardown work without
+ * jQuery, and routes the custom Garnish events (`activate`/`textchange`/`resize`)
+ * through their installers. Exported for advanced/standalone use; most code goes
+ * through `Base`.
+ */
+export class DomListenerRegistry {
+  private readonly bindings: Binding[] = [];
+
+  constructor(private readonly host: DomListenerHost) {}
+
+  /**
+   * Bind one or more (comma/space-grammar) events on the resolved elements.
+   * The handler runs with the host's `this` already applied by the caller, and
+   * is short-circuited while `host.disabled` is true.
+   */
+  add(
+    elements: ElementInput,
+    events: string,
+    handler: GarnishEventHandler,
+    options: DomListenerOptions = {}
+  ): void {
+    const targets = coerceElements(elements);
+    if (targets.length === 0) {
+      return;
+    }
+
+    // `addListener` grammar: split on commas.
+    const parsed = parseEvents(events, ',');
+    const capture = options.capture ?? false;
+
+    for (const target of targets) {
+      for (const ev of parsed) {
+        if (CUSTOM_EVENT_TYPES.has(ev.type)) {
+          this.bindCustom(target, ev.type, ev.namespace, handler, options);
+        } else {
+          this.bindNative(
+            target,
+            ev.type,
+            ev.namespace,
+            handler,
+            options,
+            capture
+          );
+        }
+      }
+    }
+  }
+
+  private wrap(
+    target: EventTarget,
+    type: string,
+    handler: GarnishEventHandler,
+    options: DomListenerOptions
+  ): EventListener {
+    return (nativeEvent: Event): void => {
+      // Disabled gate (legacy `_disabled`).
+      if (this.host.disabled) {
+        return;
+      }
+
+      let currentTarget: EventTarget | null = target;
+
+      // Delegation: only fire when the event originated within the selector.
+      if (options.delegate) {
+        const origin = nativeEvent.target as Element | null;
+        const matched = origin?.closest?.(options.delegate) ?? null;
+        if (!matched || !(target as Element).contains?.(matched)) {
+          return;
+        }
+        currentTarget = matched;
+      }
+
+      // Build a Garnish-style event object that also exposes native props.
+      const garnishEvent = this.toGarnishEvent(
+        nativeEvent,
+        type,
+        currentTarget,
+        options
+      );
+      handler(garnishEvent);
+    };
+  }
+
+  private toGarnishEvent(
+    nativeEvent: Event,
+    type: string,
+    currentTarget: EventTarget | null,
+    options: DomListenerOptions
+  ): GarnishEvent {
+    // Pass through the real DOM event; only define fields that are missing so we
+    // never write to read-only native getters (`type`/`target` already exist).
+    const ev = nativeEvent as unknown as GarnishEvent;
+
+    if (!('data' in ev) || ev.data === undefined) {
+      Object.defineProperty(ev, 'data', {
+        value: options.data ?? {},
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
+    }
+
+    // Expose the delegated match (parity with jQuery's delegate currentTarget).
+    if (options.delegate && currentTarget) {
+      Object.defineProperty(ev, 'garnishTarget', {
+        value: currentTarget,
+        configurable: true,
+        enumerable: true,
+        writable: true,
+      });
+    }
+
+    return ev;
+  }
+
+  private bindNative(
+    target: EventTarget,
+    type: string,
+    namespace: string | null,
+    handler: GarnishEventHandler,
+    options: DomListenerOptions,
+    capture: boolean
+  ): void {
+    const wrapped = this.wrap(target, type, handler, options);
+    target.addEventListener(type, wrapped, {
+      capture,
+      passive: options.passive,
+    });
+    this.bindings.push({
+      element: target,
+      type,
+      namespace,
+      wrappedHandler: wrapped,
+      capture,
+    });
+  }
+
+  private bindCustom(
+    target: EventTarget,
+    type: string,
+    namespace: string | null,
+    handler: GarnishEventHandler,
+    options: DomListenerOptions
+  ): void {
+    const el = target as HTMLElement;
+
+    // Install the synthetic event source (idempotent per element/type).
+    let installerDispose: () => void = () => {};
+    if (type === 'activate') {
+      installerDispose = installActivate(el);
+    } else if (type === 'textchange') {
+      installerDispose = installTextchange(
+        el as HTMLElement & {value: string},
+        {delay: (options.data?.delay as number | null | undefined) ?? null}
+      );
+    } else if (type === 'resize') {
+      installerDispose = installResize(el);
+    }
+
+    // The synthetic event dispatches as a native CustomEvent on the element.
+    const wrapped = this.wrap(target, type, handler, options);
+    target.addEventListener(type, wrapped);
+
+    const binding: Binding = {
+      element: target,
+      type,
+      namespace,
+      wrappedHandler: wrapped,
+      capture: false,
+    };
+    binding.dispose = () => {
+      target.removeEventListener(type, wrapped);
+      // Only tear down the installer if this was the last listener of its type.
+      const stillBound = this.bindings.some(
+        (b) => b !== binding && b.element === target && b.type === type
+      );
+      if (!stillBound) {
+        installerDispose();
+      }
+    };
+    this.bindings.push(binding);
+  }
+
+  /** Remove specific event(s) previously bound by this host on the element(s). */
+  remove(elements: ElementInput, events: string): void {
+    const targets = coerceElements(elements);
+    const parsed = parseEvents(events, ',');
+
+    for (const target of targets) {
+      for (const ev of parsed) {
+        this.removeWhere(
+          (b) =>
+            b.element === target &&
+            // An empty type with a namespace removes all of that namespace.
+            (ev.type === '' || b.type === ev.type) &&
+            (!ev.namespace || b.namespace === ev.namespace)
+        );
+      }
+    }
+  }
+
+  /** Remove all listeners this host bound on the element(s). */
+  removeAllOn(elements: ElementInput): void {
+    const targets = coerceElements(elements);
+    for (const target of targets) {
+      this.removeWhere((b) => b.element === target);
+    }
+  }
+
+  /** Remove everything this host bound anywhere (used by destroy). */
+  removeAll(): void {
+    this.removeWhere(() => true);
+  }
+
+  private removeWhere(predicate: (b: Binding) => boolean): void {
+    for (let i = this.bindings.length - 1; i >= 0; i--) {
+      const binding = this.bindings[i]!;
+      if (!predicate(binding)) {
+        continue;
+      }
+
+      if (binding.dispose) {
+        binding.dispose();
+      } else {
+        binding.element.removeEventListener(
+          binding.type,
+          binding.wrappedHandler,
+          {capture: binding.capture}
+        );
+      }
+      this.bindings.splice(i, 1);
+    }
+  }
+}
+
+// Re-export for convenience; keeps `globals` import tree-shake friendly.
+void globals;
diff --git a/packages/craftcms-garnish/src/drag-move.ts b/packages/craftcms-garnish/src/drag-move.ts
new file mode 100644
index 00000000000..157ae78c985
--- /dev/null
+++ b/packages/craftcms-garnish/src/drag-move.ts
@@ -0,0 +1,82 @@
+/**
+ * DragMove — trivial `BaseDrag` subclass that positions the dragged element's
+ * top-left at the cursor (minus the grab offset) on each drag frame.
+ *
+ * The legacy `DragMove.onDrag` *replaced* `BaseDrag.onDrag` and did not call
+ * super, so it never emitted the `drag` event. We call `super.onDrag()` here
+ * (doc 07 §5 Option A) so `DragMove` is strictly more capable — it also emits
+ * `drag` / invokes `settings.onDrag`. The CSS write happens synchronously before
+ * delegating to the RAF-deferred `super.onDrag()`.
+ */
+
+import {BaseDrag, type BaseDragSettings} from './drag/base-drag';
+import {getOffset} from './utils/dom';
+
+export {type BaseDragSettings};
+
+/**
+ * Page-coordinate origin of `el`'s containing block — the box its CSS
+ * `left`/`top` are resolved against. We convert the pointer's PAGE coordinates
+ * into this space before writing `left`/`top`:
+ *
+ * - **Positioned ancestor** (`offsetParent` is an element): the padding box of
+ *   that ancestor, adjusted for its border (`clientLeft/Top`) and scroll.
+ * - **`position: fixed`** (`offsetParent` is `null`): the containing block is
+ *   the viewport, whose top-left sits at the page scroll offset — so the origin
+ *   is `{scrollX, scrollY}`. Without this a fixed element (e.g. a `Modal`) jumps
+ *   *down/right by the scroll amount* on the first drag frame.
+ * - **`position: absolute` with no positioned ancestor** (`offsetParent` is
+ *   `<body>`/`<html>`), or a detached/`display:none` element: the initial
+ *   containing block anchored at the page origin → `{0, 0}`.
+ */
+function containingBlockOrigin(el: HTMLElement): {left: number; top: number} {
+  const parent = el.offsetParent as HTMLElement | null;
+
+  if (!parent) {
+    // No offsetParent: position:fixed (containing block = the viewport), or a
+    // detached/display:none element. Only fixed needs the scroll correction.
+    if (
+      typeof window.getComputedStyle === 'function' &&
+      window.getComputedStyle(el).position === 'fixed'
+    ) {
+      return {left: window.scrollX, top: window.scrollY};
+    }
+    return {left: 0, top: 0};
+  }
+
+  if (parent === document.body || parent === document.documentElement) {
+    // Absolute with no positioned ancestor → initial containing block at the
+    // page origin (matches the legacy <body>-relative assumption).
+    return {left: 0, top: 0};
+  }
+
+  const offset = getOffset(parent);
+  return {
+    left: offset.left + parent.clientLeft - parent.scrollLeft,
+    top: offset.top + parent.clientTop - parent.scrollTop,
+  };
+}
+
+/**
+ * Drag-to-move helper: a {@link BaseDrag} subclass whose only job is to set the
+ * dragged element's `left`/`top` so it follows the cursor. Used by `Modal`'s
+ * `draggable` option.
+ */
+export class DragMove extends BaseDrag {
+  override onDrag(): void {
+    if (this.$targetItem) {
+      // `mouseX/Y - mouseOffset` is the target position in PAGE coordinates.
+      // Convert it into the element's own containing-block coordinates before
+      // writing `left`/`top` — otherwise an element nested inside a positioned
+      // container is offset by that container's page position and flies
+      // off-screen the moment the drag starts.
+      const origin = containingBlockOrigin(this.$targetItem);
+      this.$targetItem.style.left = `${this.mouseX! - this.mouseOffsetX! - origin.left}px`;
+      this.$targetItem.style.top = `${this.mouseY! - this.mouseOffsetY! - origin.top}px`;
+    }
+
+    super.onDrag();
+  }
+}
+
+export default DragMove;
diff --git a/packages/craftcms-garnish/src/drag/base-drag.ts b/packages/craftcms-garnish/src/drag/base-drag.ts
new file mode 100644
index 00000000000..3d5f9e4f1c1
--- /dev/null
+++ b/packages/craftcms-garnish/src/drag/base-drag.ts
@@ -0,0 +1,668 @@
+/**
+ * BaseDrag — modern, jQuery-free TypeScript port of Garnish's `BaseDrag`.
+ *
+ * Does all the grunt work for manipulating elements via click-and-drag, while
+ * leaving the actual element manipulation up to a subclass (`DragMove`, and
+ * later `Drag`/`DragSort`). Every jQuery call from the legacy `BaseDrag.js` is
+ * replaced with native DOM (see doc 07 §2):
+ *
+ * - `mousedown`/`mousemove`/`mouseup` + the legacy touch shim → the Pointer
+ *   Events API (`pointerdown`/`pointermove`/`pointerup`/`pointercancel`), which
+ *   unifies mouse + touch + pen.
+ * - `$.data(item, 'drag')` → a module-level `WeakMap<Element, BaseDrag>`.
+ * - `$()` collections → native `Element[]`; `$.scrollParent()` →
+ *   `getScrollParent` (`utils/scroll.ts`); `$.offset()` → `getOffset`.
+ * - `Garnish.requestAnimationFrame` etc. → `utils/animation.ts`.
+ *
+ * Consumers honor the `$`-prefixed public names (`$items`, `$targetItem`) for
+ * parity, even though they now hold native elements rather than jQuery
+ * collections.
+ */
+
+import {Base} from '../base';
+import {X_AXIS, Y_AXIS} from '../constants';
+import {doc, globals, win} from '../globals';
+import {requestAnimationFrame, cancelAnimationFrame} from '../utils/animation';
+import {coerceElements, getOffset} from '../utils/dom';
+import {isPrimaryClick} from '../utils/env';
+import {getDist, isPlainObject} from '../utils/misc';
+import {getScrollParent, isWindowScrollContainer} from '../utils/scroll';
+import type {GarnishEvent} from './../events';
+import type {ElementInput, GarnishBaseSettings} from '../types';
+
+/** Anything `addItems`/`removeItems` accepts: a selector, element, or list. */
+export type DragItemsInput = ElementInput;
+
+/** A drag handle: element(s), a selector resolved within each item, a resolver fn, or `null`. */
+export type DragHandle =
+  | ElementInput
+  | ((item: Element) => ElementInput)
+  | null;
+
+/** Settings accepted by {@link BaseDrag}. */
+export interface BaseDragSettings extends GarnishBaseSettings {
+  /** Min px the pointer must travel before a drag starts. `null` → the static {@link BaseDrag.minMouseDist} (1). */
+  minMouseDist: number | null;
+  /**
+   * The drag handle. Element(s), a selector resolved within each item, or a
+   * function `(item) => handleElement`. `null` → the item itself is the handle.
+   */
+  handle: DragHandle;
+  /** Restrict movement to one axis: {@link X_AXIS}, {@link Y_AXIS}, or `null` (both). */
+  axis: typeof X_AXIS | typeof Y_AXIS | null;
+  /** Pointer-down on a descendant matching this selector is ignored (unless it IS the handle). */
+  ignoreHandleSelector: string | null;
+
+  onBeforeDragStart: () => void;
+  onDragStart: () => void;
+  onDrag: () => void;
+  onDragStop: () => void;
+}
+
+/**
+ * Maps a draggable item element back to its owning `BaseDrag` instance — the
+ * native replacement for the legacy `$.data(item, 'drag')`.
+ */
+const dragRegistry = new WeakMap<Element, BaseDrag>();
+
+/** Read the owning dragger of an item (test/introspection helper). */
+export function getItemDragger(item: Element): BaseDrag | undefined {
+  return dragRegistry.get(item);
+}
+
+const noop = (): void => {};
+
+/**
+ * The base drag class. Tracks a set of draggable items, watches for a
+ * pointer-down on each item's handle, starts a drag once the pointer has moved
+ * past {@link BaseDragSettings.minMouseDist}, and drives an auto-scroll loop
+ * when the pointer nears a scroll edge. Subclasses override
+ * {@link onDragStart}/{@link onDrag}/{@link onDragStop} (and optionally
+ * {@link startDragging}/{@link drag}/{@link stopDragging} via `super`-dispatch)
+ * to manipulate the dragged element(s).
+ *
+ * @typeParam S - The settings shape; defaults to {@link BaseDragSettings}.
+ *
+ * @example
+ * ```ts
+ * const dragger = new BaseDrag('.draggable', {
+ *   axis: 'x',
+ *   onDrag: () => console.log('dragging'),
+ * });
+ * ```
+ */
+export class BaseDrag<
+  S extends BaseDragSettings = BaseDragSettings,
+> extends Base<S> {
+  /** Fallback for `settings.minMouseDist === null`. */
+  static readonly minMouseDist = 1;
+  /** px edge band that triggers auto-scroll. */
+  static readonly windowScrollTargetSize = 25;
+
+  /** Default {@link BaseDragSettings}. */
+  static readonly defaults: BaseDragSettings = {
+    minMouseDist: null,
+    handle: null,
+    axis: null,
+    ignoreHandleSelector: 'input, textarea, button, select, .btn',
+    onBeforeDragStart: noop,
+    onDragStart: noop,
+    onDrag: noop,
+    onDragStop: noop,
+  };
+
+  // --- Items + current target (legacy `$`-prefixed names) -------------------
+
+  /** The draggable items (native elements; legacy held a jQuery collection). */
+  $items: Element[] = [];
+  /** The element currently being dragged, or `null`. */
+  $targetItem: HTMLElement | null = null;
+
+  // --- State ----------------------------------------------------------------
+
+  /** Whether a drag is in progress. */
+  dragging = false;
+
+  // --- Pointer coordinates (page coords) ------------------------------------
+
+  mousedownX: number | null = null;
+  mousedownY: number | null = null;
+  /** Unconstrained pointer X (before axis lock). */
+  realMouseX: number | null = null;
+  realMouseY: number | null = null;
+  /** Axis-constrained pointer X; what subclasses use. */
+  mouseX: number | null = null;
+  mouseY: number | null = null;
+  /** `mouseX - mousedownX`. */
+  mouseDistX: number | null = null;
+  mouseDistY: number | null = null;
+  /** Pointer-down page X minus the target's left offset (grab offset). */
+  mouseOffsetX: number | null = null;
+  mouseOffsetY: number | null = null;
+
+  // --- Scroll-loop state ----------------------------------------------------
+
+  scrollProperty: 'scrollTop' | 'scrollLeft' | null = null;
+  scrollAxis: 'X' | 'Y' | null = null;
+  scrollDist: number | null = null;
+  /** RAF handle for the auto-scroll loop. */
+  scrollFrame: number | null = null;
+
+  /** The resolved scroll container (replaces the legacy `this._.$scrollContainer`). */
+  private _scrollContainer: Element | Window = win;
+  /** The pointer id that started the current interaction (multi-touch safety). */
+  private _pointerId: number | null = null;
+
+  /**
+   * @param items - Elements that should be draggable right away (selector,
+   *   element, or list), or — via the legacy param-shift — a `Partial<S>`
+   *   settings object when no second argument is given.
+   * @param settings - Optional settings overrides (see {@link BaseDragSettings}).
+   */
+  constructor(
+    items?: DragItemsInput | Partial<S> | null,
+    settings?: Partial<S>
+  ) {
+    super();
+
+    // Param-shift: `new BaseDrag(settings)` when the first arg is a plain object.
+    let resolvedItems: DragItemsInput = null;
+    if (settings === undefined && isPlainObject(items)) {
+      settings = items as Partial<S>;
+    } else {
+      resolvedItems = (items as DragItemsInput) ?? null;
+    }
+
+    this.setSettings(settings, BaseDrag.defaults as Partial<S>);
+
+    this.$items = [];
+
+    if (resolvedItems) {
+      this.addItems(resolvedItems);
+    }
+  }
+
+  // --- Drag lifecycle -------------------------------------------------------
+
+  /** Returns whether dragging is allowed right now. Subclasses override to gate. */
+  allowDragging(): boolean {
+    return true;
+  }
+
+  /** Begin a drag: fire the before/start hooks, resolve the scroll container. */
+  startDragging(): void {
+    this.onBeforeDragStart();
+    this.dragging = true;
+    this.setScrollContainer();
+    this.onDragStart();
+
+    // Mute activate events while dragging (legacy parity).
+    globals.activateEventsMuted = true;
+  }
+
+  /** Resolve {@link _scrollContainer} for the current target via the axis-aware finder. */
+  setScrollContainer(): void {
+    const axis = (this.settings!.axis as 'x' | 'y' | null) ?? null;
+    this._scrollContainer = this.$targetItem
+      ? getScrollParent(this.$targetItem, axis)
+      : win;
+  }
+
+  /** Whether the resolved scroll container is the window. */
+  isScrollingWindow(): boolean {
+    return isWindowScrollContainer(this._scrollContainer);
+  }
+
+  /**
+   * Advance the drag a frame. When `didMouseMove`, decide whether the pointer is
+   * within the auto-scroll edge band and (start|update|cancel) the scroll loop
+   * accordingly, then fire {@link onDrag}.
+   */
+  drag(didMouseMove: boolean): void {
+    if (didMouseMove) {
+      const decision = this._computeEdgeScroll();
+
+      if (decision) {
+        // Are we starting to scroll now?
+        if (!this.scrollProperty) {
+          if (this.scrollFrame) {
+            cancelAnimationFrame(this.scrollFrame);
+            this.scrollFrame = null;
+          }
+          this.scrollFrame = requestAnimationFrame(() => this._scrollWindow());
+        }
+
+        this.scrollProperty = decision.property;
+        this.scrollAxis = decision.axis;
+        this.scrollDist = decision.dist;
+      } else {
+        this._cancelWindowScroll();
+      }
+    }
+
+    this.onDrag();
+  }
+
+  /** End the drag: fire {@link onDragStop}, cancel scrolling, unmute activate events. */
+  stopDragging(): void {
+    this.dragging = false;
+    this.onDragStop();
+
+    this._cancelWindowScroll();
+
+    requestAnimationFrame(() => {
+      globals.activateEventsMuted = false;
+    });
+  }
+
+  // --- Item management ------------------------------------------------------
+
+  /**
+   * Make the given element(s) draggable: register them with this dragger and
+   * bind a `pointerdown` listener on each item's handle.
+   */
+  addItems(items: DragItemsInput): void {
+    const elements = coerceElements(items).filter(
+      (el): el is Element => el instanceof Element
+    );
+
+    for (const item of elements) {
+      // Make sure this element doesn't belong to another dragger.
+      const owner = dragRegistry.get(item);
+      if (owner) {
+        if (owner === this) {
+          continue;
+        }
+        console.warn('Element was added to more than one dragger');
+        owner.removeItems(item);
+      }
+
+      dragRegistry.set(item, this);
+
+      // Bind pointerdown on the handle. The registry passes the native event
+      // through (core impl note #2), so it is a real PointerEvent at runtime.
+      this.addListener(this._getItemHandle(item), 'pointerdown', (ev) => {
+        this._handlePointerDown(ev as unknown as PointerEvent, item);
+      });
+
+      this.$items.push(item);
+    }
+  }
+
+  /** Stop tracking the given element(s) and unbind their handle listeners. */
+  removeItems(items: DragItemsInput): void {
+    const elements = coerceElements(items).filter(
+      (el): el is Element => el instanceof Element
+    );
+
+    for (const item of elements) {
+      const index = this.$items.indexOf(item);
+      if (index !== -1) {
+        this._deinitItem(item);
+        this.$items.splice(index, 1);
+      }
+    }
+  }
+
+  /** The item before `item` in {@link $items}, or `null`. */
+  getPrevItem(item: Element): Element | null {
+    const index = this.$items.indexOf(item);
+    if (index === -1 || index === 0) {
+      return null;
+    }
+    return this.$items[index - 1] ?? null;
+  }
+
+  /** The item after `item` in {@link $items}, or `null`. */
+  getNextItem(item: Element): Element | null {
+    const index = this.$items.indexOf(item);
+    if (index === -1 || index === this.$items.length - 1) {
+      return null;
+    }
+    return this.$items[index + 1] ?? null;
+  }
+
+  /** Stop tracking every item. */
+  removeAllItems(): void {
+    for (const item of this.$items) {
+      this._deinitItem(item);
+    }
+    this.$items = [];
+  }
+
+  /** Tear the dragger down: drop all items, then run the base teardown. */
+  override destroy(): void {
+    this.removeAllItems();
+    super.destroy();
+  }
+
+  // --- Overridable hooks (event emitters) -----------------------------------
+
+  /** Sync hook: emits `beforeDragStart` + invokes `settings.onBeforeDragStart`. */
+  onBeforeDragStart(): void {
+    this.trigger('beforeDragStart');
+    this.settings!.onBeforeDragStart();
+  }
+
+  /** RAF-deferred hook: emits `dragStart` + invokes `settings.onDragStart`. */
+  onDragStart(): void {
+    requestAnimationFrame(() => {
+      this.trigger('dragStart');
+      this.settings!.onDragStart();
+    });
+  }
+
+  /** RAF-deferred hook: emits `drag` + invokes `settings.onDrag`. */
+  onDrag(): void {
+    requestAnimationFrame(() => {
+      this.trigger('drag');
+      this.settings!.onDrag();
+    });
+  }
+
+  /** RAF-deferred hook: emits `dragStop` + invokes `settings.onDragStop`. */
+  onDragStop(): void {
+    requestAnimationFrame(() => {
+      this.trigger('dragStop');
+      this.settings!.onDragStop();
+    });
+  }
+
+  // --- Private --------------------------------------------------------------
+
+  /** Resolve the handle element(s) for an item from `settings.handle`. */
+  private _getItemHandle(item: Element): Element[] {
+    const {handle} = this.settings!;
+    if (!handle) {
+      return [item];
+    }
+
+    if (typeof handle === 'function') {
+      return coerceElements(handle(item)).filter(
+        (el): el is Element => el instanceof Element
+      );
+    }
+
+    if (typeof handle === 'string') {
+      // Legacy split commas and forced `:first` per selector to dodge
+      // craftcms/cms#12896. `querySelector` is inherently first-match, so the
+      // `:first` hack is dropped.
+      return handle
+        .split(',')
+        .map((s) => item.querySelector(s.trim()))
+        .filter((el): el is Element => el !== null);
+    }
+
+    // Element / list of elements passed directly (Modal passes the container).
+    return coerceElements(handle).filter(
+      (el): el is Element => el instanceof Element
+    );
+  }
+
+  /** Pointer-down on a handle: capture the target + initial coords, start listening. */
+  private _handlePointerDown(ev: PointerEvent, item: Element): void {
+    // Ignore right/ctrl-clicks.
+    if (!isPrimaryClick(ev)) {
+      return;
+    }
+
+    // Ignore if we already have a target.
+    if (this.$targetItem) {
+      return;
+    }
+
+    // Make sure the target isn't a button (unless the button IS the handle).
+    const evTarget = ev.target as Element | null;
+    if (item !== ev.target && this.settings!.ignoreHandleSelector) {
+      if (evTarget?.closest(this.settings!.ignoreHandleSelector)) {
+        return;
+      }
+    }
+
+    ev.preventDefault();
+
+    // Make sure that dragging is allowed right now.
+    if (!this.allowDragging()) {
+      return;
+    }
+
+    // Capture the target + pointer.
+    this.$targetItem = item as HTMLElement;
+    this._pointerId = ev.pointerId;
+
+    // Capture the current pointer position.
+    this.mousedownX = this.mouseX = ev.pageX;
+    this.mousedownY = this.mouseY = ev.pageY;
+
+    // Capture the difference between the pointer position and the target's offset.
+    const offset = getOffset(this.$targetItem);
+    this.mouseOffsetX = ev.pageX - offset.left;
+    this.mouseOffsetY = ev.pageY - offset.top;
+
+    // Listen for pointermove/up/cancel on the document.
+    this.addListener(doc, 'pointermove', '_handlePointerMove');
+    this.addListener(doc, 'pointerup', '_handlePointerUp');
+    this.addListener(doc, 'pointercancel', '_handlePointerUp');
+  }
+
+  /** Pointer-move: update coords, gate the drag start, then drag. */
+  private _handlePointerMove(ev: PointerEvent): void {
+    // Ignore events from a different pointer (multi-touch safety).
+    if (this._pointerId !== null && ev.pointerId !== this._pointerId) {
+      return;
+    }
+
+    ev.preventDefault();
+
+    this.realMouseX = ev.pageX;
+    this.realMouseY = ev.pageY;
+
+    if (this.settings!.axis !== Y_AXIS) {
+      this.mouseX = ev.pageX;
+    }
+    if (this.settings!.axis !== X_AXIS) {
+      this.mouseY = ev.pageY;
+    }
+
+    this.mouseDistX = this.mouseX! - this.mousedownX!;
+    this.mouseDistY = this.mouseY! - this.mousedownY!;
+
+    if (!this.dragging) {
+      // Has the pointer moved far enough to initiate dragging yet?
+      const dist = getDist(
+        this.mousedownX!,
+        this.mousedownY!,
+        this.realMouseX,
+        this.realMouseY
+      );
+
+      if (dist >= (this.settings!.minMouseDist ?? BaseDrag.minMouseDist)) {
+        this.startDragging();
+      }
+    }
+
+    if (this.dragging) {
+      this.drag(true);
+    }
+  }
+
+  /** Pointer-up / -cancel: unbind doc listeners, stop dragging, clear the target. */
+  private _handlePointerUp(ev: PointerEvent): void {
+    if (this._pointerId !== null && ev.pointerId !== this._pointerId) {
+      return;
+    }
+
+    this.removeAllListeners(doc);
+
+    if (this.dragging) {
+      this.stopDragging();
+    }
+
+    this.$targetItem = null;
+    this._pointerId = null;
+  }
+
+  /**
+   * Decide whether the pointer is inside the auto-scroll edge band and, if so,
+   * which scroll property/axis to drive and by how far. Pure-ish helper factored
+   * out of the legacy `drag()` body so it is unit-testable without a live loop.
+   */
+  private _computeEdgeScroll(): {
+    property: 'scrollTop' | 'scrollLeft';
+    axis: 'X' | 'Y';
+    dist: number;
+  } | null {
+    const edge = BaseDrag.windowScrollTargetSize;
+    const container = this._scrollContainer;
+    const onWindow = this.isScrollingWindow();
+
+    // Vertical (unless axis-locked to X).
+    if (this.settings!.axis !== X_AXIS && this.mouseY != null) {
+      let min: number;
+      let max: number;
+      if (onWindow) {
+        min = win.scrollY;
+        max = min + win.innerHeight;
+      } else {
+        const el = container as Element;
+        min = getOffset(el).top;
+        // Behavior fix (doc 07 §4.2): clientHeight, not the legacy outerHeight.
+        max = min + el.clientHeight;
+      }
+      min += edge;
+      max -= edge;
+
+      if (this.mouseY < min) {
+        return {
+          property: 'scrollTop',
+          axis: 'Y',
+          dist: Math.round((this.mouseY - min) / 2),
+        };
+      }
+      if (this.mouseY > max) {
+        return {
+          property: 'scrollTop',
+          axis: 'Y',
+          dist: Math.round((this.mouseY - max) / 2),
+        };
+      }
+    }
+
+    // Horizontal (unless axis-locked to Y), only if vertical didn't claim it.
+    if (this.settings!.axis !== Y_AXIS && this.mouseX != null) {
+      let min: number;
+      let max: number;
+      if (onWindow) {
+        min = win.scrollX;
+        max = min + win.innerWidth;
+      } else {
+        const el = container as Element;
+        min = getOffset(el).left;
+        max = min + el.clientWidth;
+      }
+      min += edge;
+      max -= edge;
+
+      if (this.mouseX < min) {
+        return {
+          property: 'scrollLeft',
+          axis: 'X',
+          dist: Math.round((this.mouseX - min) / 2),
+        };
+      }
+      if (this.mouseX > max) {
+        return {
+          property: 'scrollLeft',
+          axis: 'X',
+          dist: Math.round((this.mouseX - max) / 2),
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /** Auto-scroll one frame, correct the cursor when scrolling the window, re-schedule. */
+  private _scrollWindow(): void {
+    if (!this.scrollProperty || !this.scrollAxis || this.scrollDist == null) {
+      return;
+    }
+
+    const onWindow = this.isScrollingWindow();
+    const prop = this.scrollProperty;
+
+    const scrollPos = onWindow
+      ? prop === 'scrollTop'
+        ? win.scrollY
+        : win.scrollX
+      : (this._scrollContainer as Element)[prop];
+
+    let targetPos = scrollPos + this.scrollDist;
+    if (targetPos < 0) {
+      targetPos = 0;
+    } else {
+      let scrollMax: number;
+      if (onWindow) {
+        scrollMax =
+          this.scrollAxis === 'Y'
+            ? doc.documentElement.scrollHeight - win.innerHeight
+            : doc.documentElement.scrollWidth - win.innerWidth;
+      } else {
+        const el = this._scrollContainer as Element;
+        // Behavior fix (doc 07 §4.2): clientHeight/Width, not legacy outerHeight.
+        scrollMax =
+          this.scrollAxis === 'Y'
+            ? el.scrollHeight - el.clientHeight
+            : el.scrollWidth - el.clientWidth;
+      }
+      if (targetPos > scrollMax) {
+        targetPos = scrollMax;
+      }
+    }
+
+    // Apply the scroll.
+    if (onWindow) {
+      if (prop === 'scrollTop') {
+        win.scrollTo({top: targetPos});
+      } else {
+        win.scrollTo({left: targetPos});
+      }
+    } else {
+      (this._scrollContainer as Element)[prop] = targetPos;
+    }
+
+    // Window-only correction: keep the dragged helper tracking the cursor.
+    if (onWindow) {
+      const newScrollPos = prop === 'scrollTop' ? win.scrollY : win.scrollX;
+      if (this.scrollAxis === 'Y') {
+        if (this.mouseY != null) this.mouseY -= scrollPos - newScrollPos;
+        this.realMouseY = this.mouseY;
+      } else {
+        if (this.mouseX != null) this.mouseX -= scrollPos - newScrollPos;
+        this.realMouseX = this.mouseX;
+      }
+    }
+
+    this.scrollFrame = requestAnimationFrame(() => this._scrollWindow());
+    this.drag(true);
+  }
+
+  /** Cancel the auto-scroll loop and clear its state. */
+  private _cancelWindowScroll(): void {
+    if (this.scrollFrame) {
+      cancelAnimationFrame(this.scrollFrame);
+      this.scrollFrame = null;
+    }
+    this.scrollProperty = null;
+    this.scrollAxis = null;
+    this.scrollDist = null;
+  }
+
+  /** Unbind an item's handle listeners and drop it from the registry. */
+  private _deinitItem(item: Element): void {
+    this.removeAllListeners(this._getItemHandle(item));
+    dragRegistry.delete(item);
+  }
+}
+
+export default BaseDrag;
diff --git a/packages/craftcms-garnish/src/drag/drag-drop.ts b/packages/craftcms-garnish/src/drag/drag-drop.ts
new file mode 100644
index 00000000000..70ce626ad61
--- /dev/null
+++ b/packages/craftcms-garnish/src/drag/drag-drop.ts
@@ -0,0 +1,140 @@
+/**
+ * DragDrop — modern, jQuery-free TypeScript port of Garnish's `DragDrop`.
+ *
+ * Builds on {@link Drag} by letting you set up "drop targets" the dragged
+ * element(s) can be dropped onto. Hit-detection reuses the shared `hitTest`
+ * (`utils/dom.ts`), so this layer is thin.
+ *
+ * jQuery removals (see doc 09 §4):
+ *
+ * - `$(this.settings.dropTargets)` / `$(fn())` → `coerceElements(...)`.
+ * - `Garnish.hitTest(mouseX, mouseY, elem)` → `hitTest(this.mouseX!, this.mouseY!, elem)`.
+ * - `$activeDropTarget.addClass/removeClass` → `el.classList.add/remove`.
+ * - `this.$activeDropTarget[0]` identity compare → raw `HTMLElement` ref compare.
+ *
+ * RENAME (doc 09 §5.2): legacy `$activeDropTarget` was a jQuery object and
+ * consumers read `this.$activeDropTarget[0]`. Modern holds a single
+ * `HTMLElement | null` directly — consumers must drop the `[0]`.
+ */
+
+import {coerceElements, hitTest} from '../utils/dom';
+import {isPlainObject} from '../utils/misc';
+import {Drag, type DragSettings} from './drag';
+import type {ElementInput} from '../types';
+
+/** Settings accepted by {@link DragDrop} (extends {@link DragSettings}). */
+export interface DragDropSettings extends DragSettings {
+  /** Drop-target element(s), a selector, or a resolver function. */
+  dropTargets: ElementInput | (() => ElementInput) | null;
+  /** Called whenever the active drop target changes (with the new one or `null`). */
+  onDropTargetChange: (activeDropTarget: HTMLElement | null) => void;
+  /** Class toggled on the active drop target. */
+  activeDropTargetClass: string;
+}
+
+const noop = (): void => {};
+
+/**
+ * The drag-and-drop class. Extends {@link Drag} with drop targets and
+ * active-target tracking. There is no separate "drop" event — consumers read
+ * {@link $activeDropTarget} inside their own `dragStop`/`onDragStop` handler to
+ * perform the drop (legacy contract preserved).
+ *
+ * @typeParam S - The settings shape; defaults to {@link DragDropSettings}.
+ */
+export class DragDrop<
+  S extends DragDropSettings = DragDropSettings,
+> extends Drag<S> {
+  /** Default {@link DragDropSettings}. */
+  static override readonly defaults: DragDropSettings = {
+    ...Drag.defaults,
+    dropTargets: null,
+    onDropTargetChange: noop,
+    activeDropTargetClass: 'active',
+  };
+
+  /** Resolved drop targets, or `null` when none (legacy: jQuery | null). */
+  $dropTargets: HTMLElement[] | null = null;
+
+  /** The element the cursor is currently over, or `null` (legacy: jQuery | null). */
+  $activeDropTarget: HTMLElement | null = null;
+
+  /**
+   * @param settings - Optional settings overrides (see {@link DragDropSettings}).
+   *   Legacy `DragDrop.init` only took `(settings)`; items come via `addItems`.
+   */
+  constructor(settings?: Partial<S>) {
+    // Mirror legacy `init(settings)`: items are never passed positionally. Guard
+    // against a stray non-settings first arg the same way the param-shift would.
+    const resolved =
+      settings !== undefined && isPlainObject(settings)
+        ? settings
+        : ((settings as Partial<S> | undefined) ?? ({} as Partial<S>));
+    super(null, {
+      ...(DragDrop.defaults as Partial<S>),
+      ...resolved,
+    });
+  }
+
+  /** Resolve `settings.dropTargets` → `HTMLElement[] | null` (null if empty). */
+  updateDropTargets(): void {
+    const dt = this.settings!.dropTargets;
+    if (!dt) {
+      this.$dropTargets = null;
+      return;
+    }
+
+    const resolved = (
+      typeof dt === 'function' ? coerceElements(dt()) : coerceElements(dt)
+    ).filter((el): el is HTMLElement => el instanceof HTMLElement);
+
+    this.$dropTargets = resolved.length ? resolved : null;
+  }
+
+  override onDragStart(): void {
+    this.updateDropTargets();
+    this.$activeDropTarget = null;
+    super.onDragStart();
+  }
+
+  override onDrag(): void {
+    if (this.$dropTargets) {
+      // Is the cursor over any drop target? First match wins (legacy parity).
+      let active: HTMLElement | null = null;
+      for (const el of this.$dropTargets) {
+        if (hitTest(this.mouseX!, this.mouseY!, el)) {
+          active = el;
+          break;
+        }
+      }
+
+      // Has the active target changed? (identity compare, no `[0]` unwrap)
+      if (active !== this.$activeDropTarget) {
+        if (this.$activeDropTarget) {
+          this.$activeDropTarget.classList.remove(
+            this.settings!.activeDropTargetClass
+          );
+        }
+        this.$activeDropTarget = active;
+        if (active) {
+          active.classList.add(this.settings!.activeDropTargetClass);
+        }
+        this.settings!.onDropTargetChange(this.$activeDropTarget);
+      }
+    }
+
+    super.onDrag();
+  }
+
+  override onDragStop(): void {
+    if (this.$dropTargets && this.$activeDropTarget) {
+      this.$activeDropTarget.classList.remove(
+        this.settings!.activeDropTargetClass
+      );
+    }
+
+    super.onDragStop();
+  }
+}
+
+export default DragDrop;
diff --git a/packages/craftcms-garnish/src/drag/drag-sort.ts b/packages/craftcms-garnish/src/drag/drag-sort.ts
new file mode 100644
index 00000000000..718195a17d0
--- /dev/null
+++ b/packages/craftcms-garnish/src/drag/drag-sort.ts
@@ -0,0 +1,635 @@
+/**
+ * DragSort — modern, jQuery-free TypeScript port of Garnish's `DragSort`.
+ *
+ * Builds on {@link Drag} by letting you sort the dragged element(s) *amongst*
+ * the other items: as the cursor moves, the draggee (and an optional placeholder
+ * element) is physically re-inserted into the DOM at the spot it would land, so
+ * the surrounding items reflow in real time. On drop the new order is committed
+ * and a `sortChange` event fires if anything actually moved.
+ *
+ * jQuery removals (see doc 11 §4):
+ *
+ * - `$(this.settings.insertion)` / `$(fn($draggee))` → `_toInsertionElement`
+ *   (`<template>` parse for markup, else the element directly).
+ * - `$draggee.offset()` (magnet math) → `getOffset(this.$draggee[0])`.
+ * - `Garnish.hitTest(x, y, $container)` → `hitTest(mouseX, mouseY, container)`.
+ * - `$(container).height()` + `.parent()` walk → `getOuterHeight` + `parentElement`.
+ * - `$draggee.insertBefore/After(item)` → `item.before/after(...$draggee)`.
+ * - `$insertion.insertBefore($draggee.first())` → `$draggee[0].before($insertion)`.
+ * - `this.$items.index(item)` → `this.$items.indexOf(item)`; `$el.index()` →
+ *   `_siblingIndex(el)`; `this.$draggee.eq(i)` → `this.$draggee[i]`.
+ * - `$().add(this.$items)` DOM-order re-sort → `_sortItemsByDomOrder`
+ *   (`compareDocumentPosition`).
+ * - `$.contains($draggee[0], item)` → `this.$draggee[0].contains(item)`.
+ * - `$.data(item, 'midpoint')` → a `Map<Element, Midpoint>` midpoint cache.
+ * - `Garnish.requestAnimationFrame` → `utils/animation.ts`; `$.noop` → `() => {}`.
+ *
+ * DEVIATION (doc 11 §2.1): the legacy `_getItemMidpoint` reposition-and-measure
+ * fallback (`$.data('midpointVersion', …)`) is dropped. The modern flow always
+ * populates the midpoint cache at drag start, so non-cached elements (only the
+ * insertion placeholder) are measured directly via `getBoundingClientRect`.
+ */
+
+import {X_AXIS, Y_AXIS} from '../constants';
+import {win} from '../globals';
+import {requestAnimationFrame} from '../utils/animation';
+import {coerceElements, getOffset, getOuterHeight, hitTest} from '../utils/dom';
+import {isPlainObject} from '../utils/misc';
+import {Drag, type DragSettings} from './drag';
+import type {DragItemsInput} from './base-drag';
+import type {ElementInput} from '../types';
+
+/** A precomputed, scroll-adjusted (page-coords) midpoint + box for one item. */
+interface Midpoint {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  top: number;
+  bottom: number;
+}
+
+/** The insertion placeholder hook: a builder fn, an element, markup, or `null`. */
+export type DragSortInsertion =
+  | ((draggee: HTMLElement[]) => HTMLElement | string)
+  | HTMLElement
+  | string
+  | null;
+
+/** Settings accepted by {@link DragSort} (extends {@link DragSettings}). */
+export interface DragSortSettings extends DragSettings {
+  /**
+   * The list container (element / selector / list). At drag start it is walked
+   * up to the nearest ancestor that actually has a height; the drag only sorts
+   * while the cursor is over that resolved {@link DragSort.$heightedContainer}.
+   */
+  container: ElementInput | null;
+  /**
+   * The placeholder shown at the landing spot. A function `(draggee) => element
+   * | markup`, an element, or an HTML string. `null` → no placeholder (the
+   * draggee itself is the feedback).
+   */
+  insertion: DragSortInsertion;
+  /**
+   * If the target item isn't the first draggee, move it to the front of the
+   * draggee block in the DOM at drag start (and leave it there on drop).
+   */
+  moveTargetItemToFront: boolean;
+  /**
+   * Divides the helper's pull toward the cursor. `1` → track the cursor exactly
+   * (as in {@link Drag}); `>1` → rubber-band toward the draggee's home.
+   */
+  magnetStrength: number;
+
+  /** Fired (RAF-deferred) whenever the insertion point moves. */
+  onInsertionPointChange: () => void;
+  /** Fired (RAF-deferred) on drop when the order actually changed. */
+  onSortChange: () => void;
+  /** Gate: may the draggee be inserted *before* this item? */
+  canInsertBefore: (item: HTMLElement) => boolean;
+  /** Gate: may the draggee be inserted *after* this item? */
+  canInsertAfter: (item: HTMLElement) => boolean;
+}
+
+const noop = (): void => {};
+
+/** Viewport buffer (px) for the large-list visible-items filter. */
+const VIEWPORT_BUFFER = 300;
+/** Above this many items, restrict the closest-item scan to visible items. */
+const LARGE_LIST_THRESHOLD = 200;
+
+/**
+ * The drag-to-sort class. Extends {@link Drag} with live insertion feedback:
+ * the draggee is re-inserted into the DOM at the closest landing spot as the
+ * cursor moves, and a `sortChange` event fires on drop if the order changed.
+ *
+ * @typeParam S - The settings shape; defaults to {@link DragSortSettings}.
+ */
+export class DragSort<
+  S extends DragSortSettings = DragSortSettings,
+> extends Drag<S> {
+  /** Default {@link DragSortSettings}. */
+  static override readonly defaults: DragSortSettings = {
+    ...Drag.defaults,
+    container: null,
+    insertion: null,
+    moveTargetItemToFront: false,
+    magnetStrength: 1,
+    onInsertionPointChange: noop,
+    onSortChange: noop,
+    canInsertBefore: () => true,
+    canInsertAfter: () => true,
+  };
+
+  // --- Public state (legacy `$`-prefixed names; now native) -----------------
+
+  /** Nearest ancestor of `settings.container` that has a height, or `null`. */
+  $heightedContainer: HTMLElement | null = null;
+  /** The insertion placeholder element, or `null` (legacy: jQuery). */
+  $insertion: HTMLElement | null = null;
+  /** Whether the insertion placeholder is currently in the DOM. */
+  insertionVisible = false;
+  /** Draggee indexes (into `$items`) captured at drag start. */
+  oldDraggeeIndexes: number[] | null = null;
+  /** Draggee indexes (into `$items`) captured on drop. */
+  newDraggeeIndexes: number[] | null = null;
+  /** The item the draggee is currently closest to, or `null`. */
+  closestItem: HTMLElement | null = null;
+
+  // --- Private --------------------------------------------------------------
+
+  /** Per-drag midpoint cache (replaces `$.data(item, 'midpoint')`). */
+  private _allMidpoints: Map<Element, Midpoint> | null = null;
+  /** Bumped on every `_clearMidpoints` (parity/debug; cache is the real store). */
+  private _midpointVersion = 0;
+
+  /**
+   * @param items - Elements draggable right away, or — via the legacy
+   *   param-shift — a `Partial<S>` settings object when no second arg is given.
+   * @param settings - Optional settings overrides (see {@link DragSortSettings}).
+   */
+  constructor(
+    items?: DragItemsInput | Partial<S> | null,
+    settings?: Partial<S>
+  ) {
+    let resolvedItems: DragItemsInput | null =
+      (items as DragItemsInput) ?? null;
+    if (settings === undefined && isPlainObject(items)) {
+      settings = items as Partial<S>;
+      resolvedItems = null;
+    }
+
+    super(resolvedItems, {
+      ...(DragSort.defaults as Partial<S>),
+      ...(settings ?? {}),
+    });
+  }
+
+  // --- Insertion / gating ---------------------------------------------------
+
+  /** Build the insertion placeholder element from `settings.insertion`. */
+  createInsertion(): HTMLElement | null {
+    const {insertion} = this.settings!;
+    if (!insertion) {
+      return null;
+    }
+    const value =
+      typeof insertion === 'function' ? insertion(this.$draggee) : insertion;
+    return this._toInsertionElement(value);
+  }
+
+  /** Whether the draggee may be inserted before `item` (delegates to settings). */
+  canInsertBefore(item: HTMLElement): boolean {
+    return this.settings!.canInsertBefore(item);
+  }
+
+  /** Whether the draggee may be inserted after `item` (delegates to settings). */
+  canInsertAfter(item: HTMLElement): boolean {
+    return this.settings!.canInsertAfter(item);
+  }
+
+  // --- Helper geometry overrides (magnetStrength) ---------------------------
+
+  /** The helper's target X — applies `magnetStrength` rubber-banding when set. */
+  override getHelperTargetX(real = false): number {
+    if (this.settings!.magnetStrength !== 1 && this.$draggee[0]) {
+      const offsetX = getOffset(this.$draggee[0]).left;
+      return (
+        offsetX +
+        (this.mouseX! - this.mouseOffsetX! - offsetX) /
+          this.settings!.magnetStrength
+      );
+    }
+    return super.getHelperTargetX(real);
+  }
+
+  /** The helper's target Y — applies `magnetStrength` rubber-banding when set. */
+  override getHelperTargetY(real = false): number {
+    if (this.settings!.magnetStrength !== 1 && this.$draggee[0]) {
+      const offsetY = getOffset(this.$draggee[0]).top;
+      return (
+        offsetY +
+        (this.mouseY! - this.mouseOffsetY! - offsetY) /
+          this.settings!.magnetStrength
+      );
+    }
+    return super.getHelperTargetY(real);
+  }
+
+  // --- Lifecycle hooks ------------------------------------------------------
+
+  /** Capture order, create the insertion, precalc midpoints, then emit dragStart. */
+  override onDragStart(): void {
+    this.oldDraggeeIndexes = this._getDraggeeIndexes();
+
+    // Move the target to the front of the draggee block if asked, and it isn't.
+    if (
+      this.settings!.moveTargetItemToFront &&
+      this.$draggee.length > 1 &&
+      this._getItemIndex(this.$draggee[0]!) >
+        this._getItemIndex(this.$draggee[1]!)
+    ) {
+      this.$draggee[1]!.before(this.$draggee[0]!);
+    }
+
+    // Create + place the insertion placeholder.
+    this.$insertion = this.createInsertion();
+    this._placeInsertionWithDraggee();
+
+    this.closestItem = null;
+    this._clearMidpoints();
+
+    // Resolve the nearest container ancestor that actually has a height.
+    if (this.settings!.container) {
+      let container =
+        (coerceElements(this.settings!.container)[0] as HTMLElement | null) ??
+        null;
+      while (container && !getOuterHeight(container)) {
+        container = container.parentElement;
+      }
+      this.$heightedContainer = container;
+    }
+
+    // PERFORMANCE: pre-calculate all midpoints in a single read pass to avoid
+    // layout thrashing during the drag.
+    this._precalculateMidpoints();
+
+    super.onDragStart();
+  }
+
+  /** Detect a new closest item and update the insertion, then emit drag. */
+  override onDrag(): void {
+    if (
+      this.$heightedContainer &&
+      !hitTest(this.mouseX!, this.mouseY!, this.$heightedContainer)
+    ) {
+      // The cursor left the container — clear any insertion feedback.
+      if (this.closestItem) {
+        this.closestItem = null;
+        this._removeInsertion();
+      }
+    } else {
+      // Is there a new closest item?
+      const prev = this.closestItem;
+      this.closestItem = this._getClosestItem();
+      if (prev !== this.closestItem && this.closestItem !== null) {
+        this._updateInsertion();
+      }
+    }
+
+    super.onDrag();
+  }
+
+  /** Commit the new order, return helpers, emit dragStop + sortChange. */
+  override onDragStop(): void {
+    this._removeInsertion();
+
+    // Keep the target where it was, unless we moved it to the front.
+    if (
+      !this.settings!.moveTargetItemToFront &&
+      this.targetItemPositionInDraggee !== 0 &&
+      this.$targetItem
+    ) {
+      const ref = this.$draggee[this.targetItemPositionInDraggee!];
+      if (ref) {
+        ref.after(this.$targetItem);
+      }
+    }
+
+    // Return the helpers to the draggees (DragSort auto-returns; legacy parity).
+    this.returnHelpersToDraggees();
+
+    super.onDragStop();
+
+    // Has the order actually changed?
+    this.$items = this._sortItemsByDomOrder(this.$items);
+    this.newDraggeeIndexes = this._getDraggeeIndexes();
+
+    if (
+      this.newDraggeeIndexes.join(',') !==
+      (this.oldDraggeeIndexes ?? []).join(',')
+    ) {
+      this.onSortChange();
+    }
+  }
+
+  // --- Event hooks ----------------------------------------------------------
+
+  /** RAF-deferred: emit `insertionPointChange` + run the settings callback. */
+  onInsertionPointChange(): void {
+    requestAnimationFrame(() => {
+      this.trigger('insertionPointChange');
+      this.settings!.onInsertionPointChange();
+    });
+  }
+
+  /** RAF-deferred: emit `sortChange` + run the settings callback. */
+  onSortChange(): void {
+    requestAnimationFrame(() => {
+      this.trigger('sortChange');
+      this.settings!.onSortChange();
+    });
+  }
+
+  // --- Private --------------------------------------------------------------
+
+  /** Single read pass populating the midpoint cache for every tracked item. */
+  private _precalculateMidpoints(): void {
+    this._allMidpoints = new Map();
+
+    const scrollX = win.scrollX;
+    const scrollY = win.scrollY;
+
+    for (const item of this.$items) {
+      this._allMidpoints.set(
+        item,
+        this._measureMidpoint(item, scrollX, scrollY)
+      );
+    }
+  }
+
+  /** Items currently within (or near) the viewport — used for large lists. */
+  private _getVisibleItems(): HTMLElement[] {
+    const viewportTop = win.scrollY;
+    const viewportBottom = viewportTop + win.innerHeight;
+    const visible: HTMLElement[] = [];
+
+    for (const item of this.$items) {
+      // Skip items inside the draggee.
+      if (this.$draggee[0] && this.$draggee[0].contains(item)) {
+        continue;
+      }
+      const mp = this._allMidpoints?.get(item);
+      if (!mp) {
+        continue;
+      }
+      if (
+        mp.bottom >= viewportTop - VIEWPORT_BUFFER &&
+        mp.top <= viewportBottom + VIEWPORT_BUFFER
+      ) {
+        visible.push(item as HTMLElement);
+      }
+    }
+
+    return visible;
+  }
+
+  /** Index of an item within `$items` (replaces `this.$items.index(item)`). */
+  private _getItemIndex(item: Element): number {
+    return this.$items.indexOf(item);
+  }
+
+  /** Indexes (into `$items`) of every draggee, in draggee order. */
+  private _getDraggeeIndexes(): number[] {
+    return this.$draggee.map((item) => this._getItemIndex(item));
+  }
+
+  /** The closest insertable item to the draggee's virtual midpoint, or `null`. */
+  private _getClosestItem(): HTMLElement | null {
+    let closest: HTMLElement | null = null;
+    let closestDist = 0;
+    const axis = this.settings!.axis;
+    const vx = this.draggeeVirtualMidpointX!;
+    const vy = this.draggeeVirtualMidpointY!;
+
+    const test = (item: HTMLElement): void => {
+      const mp = this._getItemMidpoint(item);
+      const dx = Math.abs(mp.x - vx);
+      const dy = Math.abs(mp.y - vy);
+      const dist =
+        axis === X_AXIS
+          ? dx
+          : axis === Y_AXIS
+            ? dy
+            : Math.sqrt(dx ** 2 + dy ** 2);
+      if (closest === null || dist < closestDist) {
+        closest = item;
+        closestDist = dist;
+      }
+    };
+
+    // PERFORMANCE: for large lists, only scan items near the viewport.
+    const visibleItems =
+      this._allMidpoints && this.$items.length > LARGE_LIST_THRESHOLD
+        ? this._getVisibleItems()
+        : null;
+
+    // Seed with the draggee itself (or the visible insertion when removeDraggee).
+    if (!this.settings!.removeDraggee && this.$draggee[0]) {
+      test(this.$draggee[0]);
+    } else if (this.insertionVisible && this.$insertion) {
+      test(this.$insertion);
+    }
+
+    // Baseline distances off the seed.
+    let lastX: number | null = null;
+    let lastY: number | null = null;
+    let startX: number | null = null;
+    let startY: number | null = null;
+    if (closest) {
+      const mp = this._getItemMidpoint(closest);
+      if (axis !== Y_AXIS) {
+        startX = lastX = Math.abs(mp.x - vx);
+      }
+      if (axis !== X_AXIS) {
+        startY = lastY = Math.abs(mp.y - vy);
+      }
+    }
+
+    const walk = (
+      next: (item: Element) => Element | null,
+      from: Element | null
+    ): void => {
+      let other = from as HTMLElement | null;
+      while (other) {
+        const mp = this._getItemMidpoint(other);
+        const dx = axis !== Y_AXIS ? Math.abs(mp.x - vx) : 0;
+        const dy = axis !== X_AXIS ? Math.abs(mp.y - vy) : 0;
+        // Skip testing once we're receding on every relevant axis (but keep
+        // walking) — the cheap monotonic-distance early-out from legacy.
+        const receding =
+          (axis === Y_AXIS || (lastX !== null && dx > lastX)) &&
+          (axis === X_AXIS || (lastY !== null && dy > lastY));
+        if (!receding) {
+          if (axis !== Y_AXIS) {
+            lastX = dx;
+          }
+          if (axis !== X_AXIS) {
+            lastY = dy;
+          }
+          if (this.canInsertBefore(other) || this.canInsertAfter(other)) {
+            test(other);
+          }
+        }
+        other = next(other) as HTMLElement | null;
+      }
+    };
+
+    if (visibleItems) {
+      for (const item of visibleItems) {
+        if (this.canInsertBefore(item) || this.canInsertAfter(item)) {
+          test(item);
+        }
+      }
+    } else {
+      // Items before the draggee, walking backward.
+      walk(
+        (item) => this.getPrevItem(item),
+        this.$draggee[0] ? this.getPrevItem(this.$draggee[0]) : null
+      );
+      // Reset for the forward pass.
+      lastX = startX;
+      lastY = startY;
+      // Items after the draggee, walking forward.
+      const last = this.$draggee[this.$draggee.length - 1];
+      walk(
+        (item) => this.getNextItem(item),
+        last ? this.getNextItem(last) : null
+      );
+    }
+
+    // Ignore a "closest" that is the draggee/insertion itself.
+    if (
+      closest !== this.$draggee[0] &&
+      (!this.insertionVisible || closest !== this.$insertion)
+    ) {
+      return closest;
+    }
+    return null;
+  }
+
+  /** Invalidate the midpoint cache (bumps the version for parity/debug). */
+  private _clearMidpoints(): void {
+    this._midpointVersion++;
+    this._allMidpoints = null;
+  }
+
+  /**
+   * The cached midpoint for an item, or a fresh measurement for elements not in
+   * the cache (only the insertion placeholder; see doc 11 §2.1 deviation).
+   */
+  private _getItemMidpoint(item: Element): Midpoint {
+    const cached = this._allMidpoints?.get(item);
+    if (cached) {
+      return cached;
+    }
+    return this._measureMidpoint(item, win.scrollX, win.scrollY);
+  }
+
+  /** Measure an element's page-coords midpoint + box from its bounding rect. */
+  private _measureMidpoint(
+    item: Element,
+    scrollX: number,
+    scrollY: number
+  ): Midpoint {
+    const rect = item.getBoundingClientRect();
+    return {
+      x: rect.left + scrollX + rect.width / 2,
+      y: rect.top + scrollY + rect.height / 2,
+      width: rect.width,
+      height: rect.height,
+      top: rect.top + scrollY,
+      bottom: rect.bottom + scrollY,
+    };
+  }
+
+  /** Move the draggee to the closest item, refresh affected midpoints, notify. */
+  private _updateInsertion(): void {
+    if (this.closestItem) {
+      this._moveDraggeeToItem(this.closestItem);
+    }
+
+    // PERFORMANCE: recompute only the moved item + its neighbors, not the list.
+    if (this._allMidpoints && this.closestItem) {
+      const toUpdate: Element[] = [this.closestItem];
+      const prev = this.getPrevItem(this.closestItem);
+      const next = this.getNextItem(this.closestItem);
+      if (prev) {
+        toUpdate.push(prev);
+      }
+      if (next) {
+        toUpdate.push(next);
+      }
+
+      const scrollX = win.scrollX;
+      const scrollY = win.scrollY;
+      for (const item of toUpdate) {
+        this._allMidpoints.set(
+          item,
+          this._measureMidpoint(item, scrollX, scrollY)
+        );
+      }
+    } else {
+      this._clearMidpoints();
+    }
+
+    this.onInsertionPointChange();
+  }
+
+  /** Re-insert the whole draggee block before/after `item`, place the insertion. */
+  private _moveDraggeeToItem(item: HTMLElement): void {
+    const first = this.$draggee[0];
+    if (!first) {
+      return;
+    }
+
+    const sameParent = first.parentNode === item.parentNode;
+    const goingDown =
+      this.canInsertAfter(item) &&
+      sameParent &&
+      this._siblingIndex(first) < this._siblingIndex(item);
+
+    if (goingDown) {
+      item.after(...this.$draggee);
+    } else {
+      item.before(...this.$draggee);
+    }
+
+    this._placeInsertionWithDraggee();
+    this.$items = this._sortItemsByDomOrder(this.$items);
+  }
+
+  /** Put the insertion placeholder immediately before the first draggee. */
+  private _placeInsertionWithDraggee(): void {
+    if (this.$insertion && this.$draggee[0]) {
+      this.$draggee[0].before(this.$insertion);
+      this.insertionVisible = true;
+    }
+  }
+
+  /** Remove the insertion placeholder from the DOM, if visible. */
+  private _removeInsertion(): void {
+    if (this.insertionVisible && this.$insertion) {
+      this.$insertion.remove();
+      this.insertionVisible = false;
+    }
+  }
+
+  /** Sort a list of elements into document order (replaces jQuery `$().add()`). */
+  private _sortItemsByDomOrder(items: Element[]): Element[] {
+    return [...items].sort((a, b) =>
+      a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1
+    );
+  }
+
+  /** An element's index among its element siblings (replaces jQuery `.index()`). */
+  private _siblingIndex(el: Element): number {
+    const parent = el.parentNode;
+    if (!parent) {
+      return -1;
+    }
+    return Array.prototype.indexOf.call(parent.children, el);
+  }
+
+  /** Coerce an insertion value (markup string or element) into an element. */
+  private _toInsertionElement(value: HTMLElement | string): HTMLElement | null {
+    if (typeof value === 'string') {
+      const template = document.createElement('template');
+      template.innerHTML = value.trim();
+      return template.content.firstElementChild as HTMLElement | null;
+    }
+    return value ?? null;
+  }
+}
+
+export default DragSort;
diff --git a/packages/craftcms-garnish/src/drag/drag.ts b/packages/craftcms-garnish/src/drag/drag.ts
new file mode 100644
index 00000000000..c2e84a09a0f
--- /dev/null
+++ b/packages/craftcms-garnish/src/drag/drag.ts
@@ -0,0 +1,603 @@
+/**
+ * Drag — modern, jQuery-free TypeScript port of Garnish's `Drag`.
+ *
+ * Builds on {@link BaseDrag} by "picking up" the selected element(s): it
+ * snapshots the target's geometry and the full draggee set, builds floating
+ * *helper* clones that follow the cursor with a little lag, and animates those
+ * helpers back home (or fades them out) when the drag ends. It does not decide
+ * *what* to do with a dragged element — that's left to `DragDrop` / `DragSort`.
+ *
+ * jQuery removals (see doc 09 §4):
+ *
+ * - `$draggee.clone()` → `draggee.cloneNode(true)`.
+ * - `$.outerWidth()/outerHeight()` → `getOuterWidth/getOuterHeight`.
+ * - `$.offset()` → `getOffset`; `$.hide()/.show()` → native display stash.
+ * - `Garnish.copyInputValues` → `copyInputValues` (`utils/forms.ts`).
+ * - `$helper.velocity({left,top})` return tween → the Web Animations API,
+ *   mirroring `Modal._fade` (tracked, cancelable, reduced-motion gated).
+ * - `Garnish.requestAnimationFrame` → `utils/animation.ts`.
+ */
+
+import {FX_DURATION} from '../constants';
+import {bod, globals} from '../globals';
+import {
+  cancelAnimationFrame,
+  getUserPreferredAnimationDuration,
+  prefersReducedMotion,
+  requestAnimationFrame,
+} from '../utils/animation';
+import {
+  coerceElements,
+  getOffset,
+  getOuterHeight,
+  getOuterWidth,
+} from '../utils/dom';
+import {copyInputValues} from '../utils/forms';
+import {isPlainObject} from '../utils/misc';
+import {
+  BaseDrag,
+  type BaseDragSettings,
+  type DragItemsInput,
+} from './base-drag';
+import type {ElementInput} from '../types';
+
+/** A `{left, top}` page-coordinate point used for helper positioning. */
+interface Point {
+  left: number;
+  top: number;
+}
+
+/** A helper-wrapping hook: a function, an element/markup to wrap into, or `null`. */
+export type DragHelper =
+  | ((helper: HTMLElement, index: number) => HTMLElement)
+  | ElementInput
+  | null;
+
+/** Settings accepted by {@link Drag} (extends {@link BaseDragSettings}). */
+export interface DragSettings extends BaseDragSettings {
+  /**
+   * Which item(s) are actually dragged. A function returning the draggee set, a
+   * selector that filters `$items`, or `null` → just `$targetItem`.
+   */
+  filter: (() => ElementInput) | string | null;
+  /** Build one helper for the whole draggee set instead of one per draggee. */
+  singleHelper: boolean;
+  /** Collapse multiple draggees into the target (hide the rest via `display:none`). */
+  collapseDraggees: boolean;
+  /** Hide every draggee entirely (`display:none`) while dragging. */
+  removeDraggee: boolean;
+  /** Hide the draggee via `visibility:hidden` while dragging. */
+  hideDraggee: boolean;
+  /** Copy `<input>`/`<select>`/`<textarea>` values from source into the clone. */
+  copyDraggeeInputValuesToHelper: boolean;
+  /** Helper opacity (`1` → no opacity override). */
+  helperOpacity: number;
+  /** Position the helper's top-left at the cursor, not at the grab offset. */
+  moveHelperToCursor: boolean;
+  /**
+   * Optional helper wrapper. A function `(helper, index) => wrappedHelper`, or an
+   * element/markup the clone is appended into. `null` → use the bare clone.
+   */
+  helper: DragHelper;
+  helperBaseZindex: number;
+  helperLagBase: number;
+  helperLagIncrementDividend: number;
+  helperSpacingX: number;
+  helperSpacingY: number;
+
+  onReturnHelpersToDraggees: () => void;
+}
+
+const noop = (): void => {};
+
+/**
+ * The drag class. Extends {@link BaseDrag} with helper-clone creation, a
+ * cursor-lag-follow loop, and a Web-Animations-API "return helpers to draggees"
+ * animation on drop.
+ *
+ * @typeParam S - The settings shape; defaults to {@link DragSettings}.
+ */
+export class Drag<S extends DragSettings = DragSettings> extends BaseDrag<S> {
+  /** Default {@link DragSettings}. */
+  static override readonly defaults: DragSettings = {
+    ...BaseDrag.defaults,
+    filter: null,
+    singleHelper: false,
+    collapseDraggees: false,
+    removeDraggee: false,
+    hideDraggee: true,
+    copyDraggeeInputValuesToHelper: false,
+    helperOpacity: 1,
+    moveHelperToCursor: false,
+    helper: null,
+    helperBaseZindex: 1000,
+    helperLagBase: 3,
+    helperLagIncrementDividend: 1.5,
+    helperSpacingX: 5,
+    helperSpacingY: 5,
+    onReturnHelpersToDraggees: noop,
+  };
+
+  // --- Target geometry snapshot (read by drag()/DragSort) -------------------
+
+  targetItemWidth: number | null = null;
+  targetItemHeight: number | null = null;
+  targetItemPositionInDraggee: number | null = null;
+
+  /** The dragged element(s); the target item is always index 0. */
+  $draggee: HTMLElement[] = [];
+
+  /** Items NOT in {@link $draggee} (everything else still tracked). */
+  otherItems: Element[] = [];
+  totalOtherItems: number | null = null;
+
+  /** The floating clones following the cursor (legacy held jQuery objects). */
+  helpers: HTMLElement[] = [];
+  helperTargets: Point[] = [];
+  helperPositions: Point[] = [];
+  helperLagIncrement: number | null = null;
+
+  /** RAF handle for the lag-follow loop. */
+  updateHelperPosFrame: number | null = null;
+
+  lastMouseX: number | null = null;
+  lastMouseY: number | null = null;
+
+  /** Display value snapshotted off the target so we can restore it. */
+  draggeeDisplay: string | null = null;
+
+  /** Virtual midpoint of the draggee (read by DragSort / consumers). */
+  draggeeVirtualMidpointX: number | null = null;
+  draggeeVirtualMidpointY: number | null = null;
+
+  /** Set true while the return-to-source animation runs; gates allowDragging(). */
+  private _returningHelpersToDraggees = false;
+
+  /** Tracked return animations so destroy()/a new drag can cancel mid-flight. */
+  private _returnAnimations: Animation[] = [];
+
+  /**
+   * @param items - Elements that should be draggable right away, or — via the
+   *   legacy param-shift — a `Partial<S>` settings object when no second
+   *   argument is given.
+   * @param settings - Optional settings overrides (see {@link DragSettings}).
+   */
+  constructor(
+    items?: DragItemsInput | Partial<S> | null,
+    settings?: Partial<S>
+  ) {
+    // Re-run the same plain-object param-shift BaseDrag uses, so we can merge
+    // Drag.defaults *under* the caller's overrides before super() applies them.
+    let resolvedItems: DragItemsInput | null =
+      (items as DragItemsInput) ?? null;
+    if (settings === undefined && isPlainObject(items)) {
+      settings = items as Partial<S>;
+      resolvedItems = null;
+    }
+
+    // Explicit merge (doc 09 §1.1, recommended form): Drag.defaults under the
+    // caller's settings. BaseDrag's constructor then layers BaseDrag.defaults
+    // *under* that via setSettings — and since Drag.defaults already spreads
+    // BaseDrag.defaults, every key resolves correctly.
+    super(resolvedItems, {
+      ...(Drag.defaults as Partial<S>),
+      ...(settings ?? {}),
+    });
+  }
+
+  // --- Lifecycle overrides --------------------------------------------------
+
+  /** Block a new drag while helpers are animating home (legacy parity). */
+  override allowDragging(): boolean {
+    return !this._returningHelpersToDraggees;
+  }
+
+  /**
+   * Snapshot the target geometry + display, resolve the draggee set, build the
+   * helpers, start the lag-follow loop, then finish drag start-up.
+   *
+   * DEVIATION (doc 09 §1.5): legacy `Drag.startDragging` *replaced* BaseDrag's
+   * and fired `onBeforeDragStart` *before* building helpers. The modern
+   * `BaseDrag.startDragging` bundles `onBeforeDragStart` with the rest, so
+   * calling `super.startDragging()` last would reverse that order. To preserve
+   * the legacy hook ordering we call `onBeforeDragStart` first, do the snapshot,
+   * then inline the (small) remainder of `BaseDrag.startDragging`. This
+   * duplicates ~4 lines of super; flagged in the impl notes.
+   */
+  override startDragging(): void {
+    this.onBeforeDragStart();
+
+    // Reset helper state.
+    this.helpers = [];
+    this.helperTargets = [];
+    this.helperPositions = [];
+    this.lastMouseX = this.lastMouseY = null;
+
+    // Capture the target item's geometry + display.
+    this.targetItemWidth = getOuterWidth(this.$targetItem!);
+    this.targetItemHeight = getOuterHeight(this.$targetItem!);
+    this.draggeeDisplay = getComputedStyle(this.$targetItem!).display;
+
+    // Resolve the draggee set + build helpers + apply hide/collapse styling.
+    this.setDraggee(this.findDraggee());
+
+    // Everything not in the draggee set.
+    this.otherItems = this.$items.filter(
+      (item) => !this.$draggee.includes(item as HTMLElement)
+    );
+    this.totalOtherItems = this.otherItems.length;
+
+    // Keep the helpers following the cursor with a little lag.
+    this.helperLagIncrement =
+      this.helpers.length === 1
+        ? 0
+        : this.settings!.helperLagIncrementDividend / (this.helpers.length - 1);
+    this.updateHelperPosFrame = requestAnimationFrame(() =>
+      this._updateHelperPos()
+    );
+
+    // --- Inlined tail of BaseDrag.startDragging (minus onBeforeDragStart) ---
+    this.dragging = true;
+    this.setScrollContainer();
+    this.onDragStart();
+    // Mute activate events while dragging (legacy parity), exactly as
+    // BaseDrag.startDragging does.
+    globals.activateEventsMuted = true;
+  }
+
+  /** Update the draggee's virtual midpoint from fresh coords, then super.drag(). */
+  override drag(didMouseMove: boolean): void {
+    this.draggeeVirtualMidpointX =
+      this.mouseX! - this.mouseOffsetX! + this.targetItemWidth! / 2;
+    this.draggeeVirtualMidpointY =
+      this.mouseY! - this.mouseOffsetY! + this.targetItemHeight! / 2;
+
+    super.drag(didMouseMove);
+  }
+
+  /** Cancel the lag-follow RAF, then super.stopDragging(). */
+  override stopDragging(): void {
+    if (this.updateHelperPosFrame !== null) {
+      cancelAnimationFrame(this.updateHelperPosFrame);
+      this.updateHelperPosFrame = null;
+    }
+
+    super.stopDragging();
+  }
+
+  // --- Draggee management ---------------------------------------------------
+
+  /** Resolve which items are dragged (settings.filter | string | $targetItem). */
+  findDraggee(): HTMLElement[] {
+    const {filter} = this.settings!;
+
+    if (typeof filter === 'function') {
+      return coerceElements(filter()).filter(
+        (el): el is HTMLElement => el instanceof HTMLElement
+      );
+    }
+
+    if (typeof filter === 'string') {
+      return this.$items.filter(
+        (item): item is HTMLElement =>
+          item instanceof HTMLElement && item.matches(filter)
+      );
+    }
+
+    return this.$targetItem ? [this.$targetItem] : [];
+  }
+
+  /** Set $draggee (target first), create helpers, apply hide/collapse styling. */
+  setDraggee(draggee: HTMLElement[]): void {
+    const target = this.$targetItem!;
+    const all = draggee.includes(target) ? draggee : [...draggee, target];
+
+    // Record the target's index within the (target-included) draggee set.
+    this.targetItemPositionInDraggee = all.indexOf(target);
+
+    // Keep the target item at the front of the list.
+    this.$draggee = [target, ...all.filter((el) => el !== target)];
+
+    // Create the helper(s).
+    if (this.settings!.singleHelper) {
+      this._createHelper(0);
+    } else {
+      for (let i = 0; i < this.$draggee.length; i++) {
+        this._createHelper(i);
+      }
+    }
+
+    if (this.settings!.removeDraggee) {
+      this.$draggee.forEach((el) => this._hide(el));
+    } else if (this.settings!.collapseDraggees) {
+      target.style.visibility = 'hidden';
+      this.$draggee
+        .filter((el) => el !== target)
+        .forEach((el) => this._hide(el));
+    } else if (this.settings!.hideDraggee) {
+      this.$draggee.forEach((el) => (el.style.visibility = 'hidden'));
+    }
+  }
+
+  /** Append additional draggees mid-drag (create helpers unless collapsed). */
+  appendDraggee(newDraggee: HTMLElement[]): void {
+    if (!newDraggee.length) {
+      return;
+    }
+
+    const oldLength = this.$draggee.length;
+    this.$draggee = [...this.$draggee, ...newDraggee];
+
+    // Create new helpers (unless collapsing).
+    if (!this.settings!.collapseDraggees) {
+      const newLength = this.$draggee.length;
+      for (let i = oldLength; i < newLength; i++) {
+        this._createHelper(i);
+      }
+    }
+
+    if (this.settings!.removeDraggee || this.settings!.collapseDraggees) {
+      newDraggee.forEach((el) => this._hide(el));
+    } else if (this.settings!.hideDraggee) {
+      newDraggee.forEach((el) => (el.style.visibility = 'hidden'));
+    }
+  }
+
+  // --- Helper geometry ------------------------------------------------------
+
+  /** The helper's target X position (page coords). */
+  getHelperTargetX(real = false): number {
+    if (!real && this.settings!.moveHelperToCursor) {
+      return this.mouseX!;
+    }
+    return this.mouseX! - this.mouseOffsetX!;
+  }
+
+  /** The helper's target Y position (page coords). */
+  getHelperTargetY(real = false): number {
+    if (!real && this.settings!.moveHelperToCursor) {
+      return this.mouseY!;
+    }
+    return this.mouseY! - this.mouseOffsetY!;
+  }
+
+  // --- Return / fade --------------------------------------------------------
+
+  /**
+   * Animate every helper back to its source draggee's offset, then restore the
+   * draggees and remove the helpers.
+   *
+   * Uses the Web Animations API (mirroring `Modal._fade`): tracked + cancelable,
+   * reduced-motion gated, and feature-detected (happy-dom lacks
+   * `element.animate`, so this resolves synchronously under test). Completion
+   * fires after the LAST helper lands (a `pending` countdown), rather than off
+   * helper 0's callback like legacy — see impl notes.
+   */
+  returnHelpersToDraggees(): void {
+    this._returningHelpersToDraggees = true;
+
+    let pending = this.helpers.length;
+    if (pending === 0) {
+      this._showDraggee();
+      return;
+    }
+
+    this.helpers.forEach((helper, i) => {
+      const draggee = this.$draggee[i] as HTMLElement | undefined;
+
+      // Restore the draggee's display now (it animates in under the helper).
+      if (draggee) {
+        draggee.style.display = this.draggeeDisplay!;
+        draggee.style.visibility = this.settings!.hideDraggee ? 'hidden' : '';
+      }
+
+      const targetOffset = draggee ? getOffset(draggee) : {left: 0, top: 0};
+
+      const finalize = (): void => {
+        helper.style.left = `${targetOffset.left}px`;
+        helper.style.top = `${targetOffset.top}px`;
+        if (--pending === 0) {
+          this._showDraggee();
+        }
+      };
+
+      // Reduced-motion or no WAAPI → jump straight home.
+      if (prefersReducedMotion() || typeof helper.animate !== 'function') {
+        finalize();
+        return;
+      }
+
+      const fromLeft = parseFloat(helper.style.left) || getOffset(helper).left;
+      const fromTop = parseFloat(helper.style.top) || getOffset(helper).top;
+
+      const anim = helper.animate(
+        [
+          {left: `${fromLeft}px`, top: `${fromTop}px`},
+          {left: `${targetOffset.left}px`, top: `${targetOffset.top}px`},
+        ],
+        {
+          duration: getUserPreferredAnimationDuration(FX_DURATION),
+          fill: 'forwards',
+        }
+      );
+      this._returnAnimations.push(anim);
+      anim.addEventListener('finish', finalize, {once: true});
+      anim.addEventListener('cancel', finalize, {once: true});
+    });
+  }
+
+  /** Fade each helper out and remove it (no return tween). */
+  fadeOutHelpers(): void {
+    this.helpers.forEach((helper) => {
+      if (prefersReducedMotion() || typeof helper.animate !== 'function') {
+        helper.remove();
+        return;
+      }
+      const anim = helper.animate([{opacity: 1}, {opacity: 0}], {
+        duration: getUserPreferredAnimationDuration(FX_DURATION),
+        fill: 'forwards',
+      });
+      anim.addEventListener('finish', () => helper.remove(), {once: true});
+      anim.addEventListener('cancel', () => helper.remove(), {once: true});
+    });
+  }
+
+  // --- Hook (event emitter) -------------------------------------------------
+
+  /** RAF-deferred: trigger('returnHelpersToDraggees') + settings callback. */
+  onReturnHelpersToDraggees(): void {
+    requestAnimationFrame(() => {
+      this.trigger('returnHelpersToDraggees');
+      this.settings!.onReturnHelpersToDraggees();
+    });
+  }
+
+  /** Tear the dragger down: cancel loops/animations, remove helpers, then super. */
+  override destroy(): void {
+    if (this.updateHelperPosFrame !== null) {
+      cancelAnimationFrame(this.updateHelperPosFrame);
+      this.updateHelperPosFrame = null;
+    }
+    this._returnAnimations.forEach((anim) => anim.cancel());
+    this._returnAnimations = [];
+    this.helpers.forEach((helper) => helper.remove());
+    this.helpers = [];
+
+    super.destroy();
+  }
+
+  // --- Private --------------------------------------------------------------
+
+  /** Creates a helper clone for the draggee at `index`. */
+  private _createHelper(index: number): void {
+    const draggee = this.$draggee[index]!;
+    let helper = draggee.cloneNode(true) as HTMLElement;
+    helper.classList.add('draghelper');
+
+    if (draggee.closest('#content')) {
+      helper.classList.add('drag-in-content');
+    }
+    if (draggee.closest('.slideout-container')) {
+      helper.classList.add('drag-in-slideout');
+    }
+
+    if (this.settings!.copyDraggeeInputValuesToHelper) {
+      copyInputValues(draggee, helper);
+    }
+
+    // Blank every name= so cloned radios/checkboxes don't hijack form values.
+    helper
+      .querySelectorAll<HTMLElement>('[name]')
+      .forEach((el) => el.setAttribute('name', ''));
+
+    // Size to match the source (border-box). jQuery `.outerWidth(n)` *sets* the
+    // total box; the native equivalent is `box-sizing:border-box` + width/height.
+    helper.style.boxSizing = 'border-box';
+    helper.style.width = `${Math.ceil(getOuterWidth(draggee))}px`;
+    helper.style.height = `${Math.ceil(getOuterHeight(draggee))}px`;
+    helper.style.margin = '0';
+    helper.style.pointerEvents = 'none';
+
+    // Optional wrapper hook.
+    if (this.settings!.helper) {
+      const helperSetting = this.settings!.helper;
+      if (typeof helperSetting === 'function') {
+        helper = helperSetting(helper, index);
+      } else {
+        const wrapper = coerceElements(helperSetting)[0] as
+          | HTMLElement
+          | undefined;
+        if (wrapper) {
+          wrapper.appendChild(helper);
+          helper = wrapper;
+        }
+      }
+    }
+
+    bod.appendChild(helper);
+
+    const pos = this._getHelperTarget(index, true);
+    helper.style.position = 'absolute';
+    helper.style.top = `${pos.top}px`;
+    helper.style.left = `${pos.left}px`;
+    helper.style.zIndex = String(
+      this.settings!.helperBaseZindex + this.$draggee.length - index
+    );
+    helper.style.display = this.draggeeDisplay!;
+    if (this.settings!.helperOpacity !== 1) {
+      helper.style.opacity = String(this.settings!.helperOpacity);
+    }
+
+    this.helperPositions[index] = {top: pos.top, left: pos.left};
+    this.helpers.push(helper);
+  }
+
+  /** Target position for helper `index`, incl. per-index spacing. */
+  private _getHelperTarget(index: number, real = false): Point {
+    return {
+      left: this.getHelperTargetX(real) + this.settings!.helperSpacingX * index,
+      top: this.getHelperTargetY(real) + this.settings!.helperSpacingY * index,
+    };
+  }
+
+  /** One frame of the lag-follow loop: ease each helper toward its target. */
+  private _updateHelperPos(): void {
+    // Recompute targets only when the pointer actually moved.
+    if (this.mouseX !== this.lastMouseX || this.mouseY !== this.lastMouseY) {
+      for (let i = 0; i < this.helpers.length; i++) {
+        this.helperTargets[i] = this._getHelperTarget(i);
+      }
+      this.lastMouseX = this.mouseX;
+      this.lastMouseY = this.mouseY;
+    }
+
+    // Gravitate helpers toward their target positions.
+    for (let j = 0; j < this.helpers.length; j++) {
+      const lag = this.settings!.helperLagBase + this.helperLagIncrement! * j;
+      const cur = this.helperPositions[j]!;
+      const tgt = this.helperTargets[j]!;
+      cur.left += (tgt.left - cur.left) / lag;
+      cur.top += (tgt.top - cur.top) / lag;
+      this.helpers[j]!.style.left = `${cur.left}px`;
+      this.helpers[j]!.style.top = `${cur.top}px`;
+    }
+
+    this.updateHelperPosFrame = requestAnimationFrame(() =>
+      this._updateHelperPos()
+    );
+  }
+
+  /** Completion: remove helpers, restore draggees, fire the hook. */
+  private _showDraggee(): void {
+    for (const helper of this.helpers) {
+      helper.remove();
+    }
+    this.helpers = [];
+    this._returnAnimations = [];
+
+    // jQuery .show().css('visibility','') → restore display + clear visibility.
+    this.$draggee.forEach((el) => {
+      this._show(el);
+      el.style.visibility = '';
+    });
+
+    this.onReturnHelpersToDraggees();
+    this._returningHelpersToDraggees = false;
+  }
+
+  /** jQuery `.hide()` — stash the current inline display, set `display:none`. */
+  private _hide(el: HTMLElement): void {
+    if (el.style.display !== 'none') {
+      el.dataset.garnishOldDisplay = el.style.display;
+    }
+    el.style.display = 'none';
+  }
+
+  /** jQuery `.show()` — restore the stashed inline display (or clear it). */
+  private _show(el: HTMLElement): void {
+    el.style.display = el.dataset.garnishOldDisplay ?? '';
+    delete el.dataset.garnishOldDisplay;
+  }
+}
+
+export default Drag;
diff --git a/packages/craftcms-garnish/src/events.ts b/packages/craftcms-garnish/src/events.ts
new file mode 100644
index 00000000000..a119c850393
--- /dev/null
+++ b/packages/craftcms-garnish/src/events.ts
@@ -0,0 +1,395 @@
+/**
+ * Garnish event system (object pub/sub + class-level pub/sub).
+ *
+ * Reproduces the two in-memory observer registries from the legacy core:
+ *  - `EventEmitter` backs `Base.on/off/once/trigger` (per-instance).
+ *  - `ClassEventBus` backs `Garnish.on/off/once` (class-level, instanceof dispatch).
+ *
+ * DOM listeners are a separate concern (see dom-listeners.ts).
+ */
+
+import type {Constructor} from './types';
+
+/** Result of parsing a single event token. */
+export interface ParsedEvent {
+  /** Event type, e.g. `'click'`. May be `''` for the "remove by namespace" form. */
+  type: string;
+  /** Namespace, e.g. `'foo'` for `'click.foo'`. `null` when none. */
+  namespace: string | null;
+}
+
+/**
+ * The event object passed to every Garnish event handler. For object events it
+ * carries the emitting instance as {@link target} plus any data; for DOM events
+ * routed through {@link Base.addListener} it is the native `Event` augmented with
+ * these fields, so native props (`stopPropagation`, `currentTarget`, …) are also
+ * available at runtime.
+ */
+export interface GarnishEvent<T = unknown, Target = unknown> {
+  type: string;
+  /** The emitting object (legacy: the Base instance). */
+  target: Target;
+  /** Per-registration data merged with trigger-time data. */
+  data: Record<string, unknown>;
+  /** Present when re-emitting a DOM event (legacy `activate` etc.). */
+  originalEvent?: Event;
+  /** Trigger-time payload is spread on (legacy `$.extend` behavior). */
+  [extra: string]: unknown;
+}
+
+/**
+ * A Garnish event handler: a callback receiving a {@link GarnishEvent}. This is
+ * the handler type accepted by {@link Base.on} / {@link Base.once} and
+ * {@link Base.addListener}.
+ */
+export type GarnishEventHandler<E extends GarnishEvent = GarnishEvent> = (
+  event: E
+) => void;
+
+/** Internal registration record. */
+interface Registration {
+  type: string;
+  namespace: string | null;
+  data: Record<string, unknown>;
+  handler: GarnishEventHandler;
+}
+
+/**
+ * Parse a Garnish event string into `{type, namespace}` records.
+ *
+ * Legacy `_normalizeEvents` splits on spaces, then each token on its **first**
+ * `.` into `[type, namespace]`. This preserves that grammar exactly.
+ *
+ * @param events  An event string or pre-split array.
+ * @param splitOn Separator for multiple events: `' '` for pub/sub (default),
+ *                `','` for `addListener` (the legacy split inconsistency).
+ */
+export function parseEvents(
+  events: string | string[],
+  splitOn: ' ' | ',' = ' '
+): ParsedEvent[] {
+  let tokens: string[];
+
+  if (typeof events === 'string') {
+    tokens = events.split(splitOn);
+  } else {
+    tokens = events;
+  }
+
+  const parsed: ParsedEvent[] = [];
+
+  for (let token of tokens) {
+    if (typeof token !== 'string') {
+      continue;
+    }
+
+    // For comma splitting, legacy trims each token.
+    if (splitOn === ',') {
+      token = token.trim();
+    }
+
+    // Split on the first '.' only. 'click.a.b' => type='click', namespace='a.b'.
+    const dotIndex = token.indexOf('.');
+    if (dotIndex === -1) {
+      parsed.push({type: token, namespace: null});
+    } else {
+      parsed.push({
+        type: token.slice(0, dotIndex),
+        namespace: token.slice(dotIndex + 1) || null,
+      });
+    }
+  }
+
+  return parsed;
+}
+
+/**
+ * Format an event string for DOM binding by appending an instance namespace.
+ *
+ * Mirrors legacy `_formatEvents`: splits on commas (the `addListener` grammar),
+ * trims, appends the namespace, and rejoins on spaces.
+ *
+ * `formatDomEvents('click,drag', '.Garnish123')` => `'click.Garnish123 drag.Garnish123'`
+ */
+export function formatDomEvents(
+  events: string | string[],
+  namespace: string
+): string {
+  let tokens: string[];
+
+  if (typeof events === 'string') {
+    tokens = events.split(',');
+  } else {
+    tokens = events.slice();
+  }
+
+  return tokens.map((token) => `${token.trim()}${namespace}`).join(' ');
+}
+
+/**
+ * Build the event object passed to a handler.
+ *
+ * Reproduces the legacy precedence exactly:
+ *   `$.extend({data: registration.data}, triggerData, {type, target})`
+ *
+ * i.e. trigger-time data keys win over registration `data`, and `type`/`target`
+ * always win last. This is observable — some call sites pass `target` overrides
+ * in `data` and legacy lets the `ev` object override them.
+ */
+function buildEvent(
+  registrationData: Record<string, unknown>,
+  triggerData: Record<string, unknown> | undefined,
+  type: string,
+  target: unknown
+): GarnishEvent {
+  return Object.assign({data: registrationData}, triggerData, {
+    type,
+    target,
+  }) as GarnishEvent;
+}
+
+/**
+ * Per-instance object pub/sub registry backing {@link Base.on} / `once` / `off`
+ * / `trigger`. One emitter exists per `Base` instance and owns that instance as
+ * the event {@link GarnishEvent.target}. Exported for advanced/standalone use;
+ * most code interacts with it through `Base`.
+ */
+export class EventEmitter<Target = unknown> {
+  private readonly registrations: Registration[] = [];
+
+  constructor(private readonly target: Target) {}
+
+  on(events: string, handler: GarnishEventHandler): void;
+  on(
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  on(
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    let data: Record<string, unknown>;
+    let fn: GarnishEventHandler;
+
+    if (typeof dataOrHandler === 'function') {
+      fn = dataOrHandler;
+      data = {};
+    } else {
+      data = dataOrHandler;
+      fn = handler as GarnishEventHandler;
+    }
+
+    for (const ev of parseEvents(events)) {
+      this.registrations.push({
+        type: ev.type,
+        namespace: ev.namespace,
+        data,
+        handler: fn,
+      });
+    }
+  }
+
+  once(events: string, handler: GarnishEventHandler): void;
+  once(
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  once(
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    let data: Record<string, unknown>;
+    let fn: GarnishEventHandler;
+
+    if (typeof dataOrHandler === 'function') {
+      fn = dataOrHandler;
+      data = {};
+    } else {
+      data = dataOrHandler;
+      fn = handler as GarnishEventHandler;
+    }
+
+    // Wrapper-closure `once` (legacy behavior): `off(events, onceler)` removes it.
+    const onceler: GarnishEventHandler = (event) => {
+      this.off(events, onceler);
+      fn(event);
+    };
+
+    this.on(events, data, onceler);
+  }
+
+  /**
+   * Remove matching registrations. A registration matches when its `type` ===
+   * the parsed type, AND (the parsed namespace is empty OR namespaces match),
+   * AND (handler omitted OR handler ===). Iterates backwards + splices.
+   */
+  off(events: string, handler?: GarnishEventHandler): void {
+    for (const ev of parseEvents(events)) {
+      for (let i = this.registrations.length - 1; i >= 0; i--) {
+        const reg = this.registrations[i]!;
+
+        if (
+          reg.type === ev.type &&
+          (!ev.namespace || reg.namespace === ev.namespace) &&
+          (handler === undefined || reg.handler === handler)
+        ) {
+          this.registrations.splice(i, 1);
+        }
+      }
+    }
+  }
+
+  /** Dispatch to instance handlers matching `type`. */
+  trigger(type: string, data?: Record<string, unknown>): void {
+    // Snapshot the matching handlers first; a `once` handler mutates the array.
+    const matching = this.registrations.filter((reg) => reg.type === type);
+
+    for (const reg of matching) {
+      const event = buildEvent(reg.data, data, type, this.target);
+      reg.handler(event);
+    }
+  }
+
+  /** Remove every registration (used by destroy). */
+  clear(): void {
+    this.registrations.length = 0;
+  }
+}
+
+/**
+ * Class-level pub/sub bus backing `Garnish.on/off/once`. Handlers are registered
+ * against a class; any instance's {@link Base.trigger} dispatches to class-level
+ * handlers whose target the instance is an `instanceof`. A single shared
+ * instance powers the `Garnish` namespace; exported for advanced use.
+ */
+export class ClassEventBus {
+  private readonly registrations: Array<Registration & {target: Constructor}> =
+    [];
+
+  on(target: Constructor, events: string, handler: GarnishEventHandler): void;
+  on(
+    target: Constructor,
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  on(
+    target: Constructor,
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    if (typeof target === 'undefined') {
+      console.warn('Garnish.on() called for an invalid target class.');
+      return;
+    }
+
+    let data: Record<string, unknown>;
+    let fn: GarnishEventHandler;
+
+    if (typeof dataOrHandler === 'function') {
+      fn = dataOrHandler;
+      data = {};
+    } else {
+      data = dataOrHandler;
+      fn = handler as GarnishEventHandler;
+    }
+
+    for (const ev of parseEvents(events)) {
+      this.registrations.push({
+        target,
+        type: ev.type,
+        namespace: ev.namespace,
+        data,
+        handler: fn,
+      });
+    }
+  }
+
+  once(target: Constructor, events: string, handler: GarnishEventHandler): void;
+  once(
+    target: Constructor,
+    events: string,
+    data: Record<string, unknown>,
+    handler: GarnishEventHandler
+  ): void;
+  once(
+    target: Constructor,
+    events: string,
+    dataOrHandler: Record<string, unknown> | GarnishEventHandler,
+    handler?: GarnishEventHandler
+  ): void {
+    if (typeof target === 'undefined') {
+      console.warn('Garnish.once() called for an invalid target class.');
+      return;
+    }
+
+    let data: Record<string, unknown>;
+    let fn: GarnishEventHandler;
+
+    if (typeof dataOrHandler === 'function') {
+      fn = dataOrHandler;
+      data = {};
+    } else {
+      data = dataOrHandler;
+      fn = handler as GarnishEventHandler;
+    }
+
+    const onceler: GarnishEventHandler = (event) => {
+      this.off(target, events, onceler);
+      fn(event);
+    };
+
+    this.on(target, events, data, onceler);
+  }
+
+  off(
+    target: Constructor,
+    events: string,
+    handler?: GarnishEventHandler
+  ): void {
+    for (const ev of parseEvents(events)) {
+      for (let i = this.registrations.length - 1; i >= 0; i--) {
+        const reg = this.registrations[i]!;
+
+        if (
+          reg.target === target &&
+          reg.type === ev.type &&
+          (!ev.namespace || reg.namespace === ev.namespace) &&
+          (handler === undefined || reg.handler === handler)
+        ) {
+          this.registrations.splice(i, 1);
+        }
+      }
+    }
+  }
+
+  /**
+   * Dispatch class-level handlers whose target the instance is an `instanceof`
+   * (legacy `Garnish._eventHandlers` walk inside `Base.trigger`).
+   */
+  dispatch(
+    instance: object,
+    type: string,
+    data: Record<string, unknown> | undefined
+  ): void {
+    const matching = this.registrations.filter(
+      (reg) =>
+        reg && reg.target && instance instanceof reg.target && reg.type === type
+    );
+
+    for (const reg of matching) {
+      const event = buildEvent(reg.data, data, type, instance);
+      reg.handler(event);
+    }
+  }
+
+  /** Remove every registration (mostly for tests). */
+  clear(): void {
+    this.registrations.length = 0;
+  }
+}
diff --git a/packages/craftcms-garnish/src/globals.ts b/packages/craftcms-garnish/src/globals.ts
new file mode 100644
index 00000000000..4ff6a41358b
--- /dev/null
+++ b/packages/craftcms-garnish/src/globals.ts
@@ -0,0 +1,41 @@
+/**
+ * Garnish shared global state.
+ *
+ * Native references replacing the legacy jQuery collections (`$win`/`$doc`/
+ * `$bod`/`$scrollContainer`), mutable feature flags, and the single shared
+ * class-level event bus instance.
+ *
+ * The compat layer re-exposes the jQuery-wrapped forms (`$win` etc.).
+ */
+
+import {ClassEventBus} from './events';
+
+/** `window` (compat exposes `$win = $(window)`). */
+export const win: Window = window;
+
+/** `document` (compat exposes `$doc = $(document)`). */
+export const doc: Document = document;
+
+/** `document.body` (compat exposes `$bod = $(document.body)`). */
+export const bod: HTMLElement = document.body;
+
+/**
+ * The scroll container. Defaults to `window`; legacy `$scrollContainer` could be
+ * reassigned to another element. Kept mutable for parity.
+ */
+export const globals = {
+  scrollContainer: window as EventTarget,
+  activateEventsMuted: false,
+  resizeEventsMuted: false,
+  // Derived from `document.body`'s `rtl` class at module init.
+  rtl: document.body.classList.contains('rtl'),
+  get ltr(): boolean {
+    return !this.rtl;
+  },
+};
+
+/**
+ * The single shared class-level event bus. `Base.trigger` dispatches into it,
+ * and `Garnish.on/off/once` proxy to it.
+ */
+export const garnishClassBus = new ClassEventBus();
diff --git a/packages/craftcms-garnish/src/hud.ts b/packages/craftcms-garnish/src/hud.ts
new file mode 100644
index 00000000000..2ab239c5891
--- /dev/null
+++ b/packages/craftcms-garnish/src/hud.ts
@@ -0,0 +1,1098 @@
+/**
+ * HUD — modern, jQuery-free TypeScript port of Garnish's `HUD`.
+ *
+ * A HUD ("heads-up display") is an anchored popover/bubble: it attaches to a
+ * trigger element, picks one of four orientations (bottom / top / right / left)
+ * based on the available clearance around the trigger, draws a tip/arrow that
+ * points back at the trigger, and follows the trigger when the window or its
+ * scroll container scrolls/resizes.
+ *
+ * This is the jQuery-free port of the legacy `HUD.js` (doc 13). It reuses the
+ * same overlay infrastructure {@link Modal} already uses — the `UiLayerManager`
+ * for layer stacking + the Escape shortcut, the focus utilities for the in/out
+ * Tab cycle, and the native DOM utils that replace jQuery:
+ *
+ * - element creation/insertion → `document.createElement` + `appendChild` /
+ *   `before` / `after`
+ * - `$.data('hud', this)` → a module-level `WeakMap`
+ * - `.scrollParent()` → {@link getScrollParent}
+ * - `.offset()` / `Garnish.getOffset()` → an inline rect-based offset +
+ *   {@link getOffset}
+ * - `.outerWidth()` / `.outerHeight()` → {@link getOuterWidth} / {@link getOuterHeight}
+ * - `:focusable` → {@link getFocusableElements} / {@link getKeyboardFocusableElements}
+ * - `Garnish.within` → {@link within}
+ * - `Garnish.requestAnimationFrame` → the native RAF re-export
+ *
+ * Unlike `Modal`, the legacy HUD does **not** fade with Velocity — its
+ * `showContainer` / `hideContainer` are plain `.show()` / `.hide()` display
+ * toggles, so there is no Velocity→WAAPI conversion to do here (doc 14).
+ */
+
+import {Base} from './base';
+import {bod, globals, win} from './globals';
+import {ESC_KEY, TAB_KEY} from './constants';
+import {getUiLayerManager} from './managers/registry';
+import {
+  getElement,
+  getOffset,
+  getOuterHeight,
+  getOuterWidth,
+} from './utils/dom';
+import {getScrollParent} from './utils/scroll';
+import {focusIsInside, getKeyboardFocusableElements} from './utils/focus';
+import {getFocusableElements} from './utils/focusable';
+import {requestAnimationFrame} from './utils/animation';
+import {isPlainObject, within} from './utils/misc';
+import type {ElementInput, GarnishBaseSettings} from './types';
+import type {GarnishEvent} from './events';
+
+/** One of the four sides a HUD can be anchored on, relative to its trigger. */
+export type HUDOrientation = 'top' | 'bottom' | 'left' | 'right';
+
+/** Body contents accepted by the constructor / {@link HUD.updateBody}. */
+export type HUDBodyContents =
+  | string
+  | Node
+  | Node[]
+  | NodeListOf<Node>
+  | null
+  | undefined;
+
+type HUDCallback = (...args: unknown[]) => void;
+
+const noop: HUDCallback = () => {};
+
+/**
+ * Settings accepted by {@link HUD}. Pass a `Partial<HUDSettings>` to the
+ * constructor; unset keys fall back to {@link HUD.defaults}.
+ */
+export interface HUDSettings extends GarnishBaseSettings {
+  /** CSS class for the shade/backdrop element. Default `'hud-shade'`. */
+  shadeClass: string;
+  /** CSS class(es) for the HUD container element. Default `'hud'`. */
+  hudClass: string;
+  /** CSS class for the tip/arrow element. Default `'tip'`. */
+  tipClass: string;
+  /** CSS class for the (form) body element. Default `'body'`. */
+  bodyClass: string;
+  /** CSS class identifying a header within the body content. Default `'hud-header'`. */
+  headerClass: string;
+  /** CSS class identifying a footer within the body content. Default `'hud-footer'`. */
+  footerClass: string;
+  /** CSS class for the scrollable main-content wrapper. Default `'main-container'`. */
+  mainContainerClass: string;
+  /** CSS class for the main-content element. Default `'main'`. */
+  mainClass: string;
+  /** Orientations to try, in order of preference. Default `['bottom','top','right','left']`. */
+  orientations: HUDOrientation[];
+  /** Gap (px) between the HUD and its trigger. Default `10`. */
+  triggerSpacing: number;
+  /** Min gap (px) between the HUD and the viewport edge. Default `10`. */
+  windowSpacing: number;
+  /** Width (px) of the tip/arrow. Default `30`. */
+  tipWidth: number;
+  /** Minimum HUD body width (px). Default `200`. */
+  minBodyWidth: number;
+  /** Minimum HUD body height (px). Default `0`. */
+  minBodyHeight: number;
+  /** Render a shade/backdrop behind the HUD. Default `true`. */
+  withShade: boolean;
+  /** Callback invoked when the HUD is shown. Default no-op. */
+  onShow: HUDCallback;
+  /** Callback invoked when the HUD is hidden. Default no-op. */
+  onHide: HUDCallback;
+  /** Callback invoked when the HUD's body form is submitted. Default no-op. */
+  onSubmit: HUDCallback;
+  /** An element whose `activate` should hide the HUD (e.g. a close button). Default `null`. */
+  closeBtn: ElementInput | null;
+  /** Reposition when the main-content element fires `resize`. Default `true`. */
+  listenToMainResize: boolean;
+  /** Show the HUD immediately on construction. Default `true`. */
+  showOnInit: boolean;
+  /** Hide every other open HUD when this one is shown. Default `true`. */
+  closeOtherHUDs: boolean;
+  /** Hide the HUD when Escape is pressed. Default `true`. */
+  hideOnEsc: boolean;
+  /** Hide the HUD when its shade is clicked (only with `withShade`). Default `true`. */
+  hideOnShadeClick: boolean;
+}
+
+/** Mutable offset rectangle (page-relative) used by the positioning math. */
+interface OffsetRect {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+}
+
+/**
+ * Maps a HUD container element back to its `HUD` instance — the native
+ * replacement for the legacy `$hud.data('hud', this)`.
+ */
+const hudElements = new WeakMap<Element, HUD>();
+
+/**
+ * An anchored, accessible popover — the jQuery-free TypeScript port of Garnish's
+ * `HUD`. Attaches to a trigger element, picks the best of four orientations from
+ * the available clearance, draws a tip pointing at the trigger, traps Tab focus
+ * between the trigger and the HUD body, registers an Escape shortcut + UI layer
+ * (via the shared `UiLayerManager`), and repositions on scroll/resize.
+ *
+ * The constructor accepts a trigger plus optional body contents and settings,
+ * with a legacy-compatible param shift: `new HUD(trigger, settings)` is treated
+ * as `new HUD(trigger, '', settings)` when the second argument is a plain object.
+ *
+ * Emits `show`, `hide`, `submit`, `updateSizeAndPosition`, and `destroy` events
+ * (subscribe with {@link Base.on}). The `onShow` / `onHide` / `onSubmit` settings
+ * callbacks are registered as handlers for those events at construction time.
+ *
+ * @example
+ * ```ts
+ * import {HUD} from '@craftcms/garnish';
+ *
+ * const trigger = document.querySelector('#add-btn')!;
+ * const hud = new HUD(trigger, {
+ *   hudClass: 'hud fld-library-hud',
+ *   orientations: ['right', 'bottom', 'left'],
+ *   showOnInit: false,
+ * });
+ * hud.on('show', () => populate(hud.$main!));
+ * hud.on('hide', () => trigger.focus());
+ * // trigger.addEventListener('click', () => hud.show());
+ * ```
+ */
+export class HUD extends Base<HUDSettings> {
+  /** Every live `HUD` instance (pushed on construction, removed on {@link destroy}). */
+  static instances: HUD[] = [];
+
+  /** Open HUDs keyed by their instance namespace (used by `closeOtherHUDs`). */
+  static activeHUDs: Record<string, HUD> = {};
+
+  /** Maps an orientation to the tip-class suffix (the tip points back at the trigger). */
+  static readonly tipClasses: Record<HUDOrientation, string> = {
+    bottom: 'top',
+    top: 'bottom',
+    right: 'left',
+    left: 'right',
+  };
+
+  /** Default {@link HUDSettings}, merged with the per-instance overrides. */
+  static readonly defaults: HUDSettings = {
+    shadeClass: 'hud-shade',
+    hudClass: 'hud',
+    tipClass: 'tip',
+    bodyClass: 'body',
+    headerClass: 'hud-header',
+    footerClass: 'hud-footer',
+    mainContainerClass: 'main-container',
+    mainClass: 'main',
+    orientations: ['bottom', 'top', 'right', 'left'],
+    triggerSpacing: 10,
+    windowSpacing: 10,
+    tipWidth: 30,
+    minBodyWidth: 200,
+    minBodyHeight: 0,
+    withShade: true,
+    onShow: noop,
+    onHide: noop,
+    onSubmit: noop,
+    closeBtn: null,
+    listenToMainResize: true,
+    showOnInit: true,
+    closeOtherHUDs: true,
+    hideOnEsc: true,
+    hideOnShadeClick: true,
+  };
+
+  // --- Instance state (named with the legacy `$`-prefix for consumer parity) ---
+
+  /** The trigger/anchor element. */
+  $trigger: HTMLElement | null = null;
+  /** The nearest `position: fixed` ancestor of the trigger, if any (drives fixed positioning). */
+  $fixedTriggerParent: HTMLElement | null = null;
+  /** The HUD container element. */
+  $hud: HTMLElement | null = null;
+  /** The tip/arrow element. */
+  $tip: HTMLElement | null = null;
+  /** The HUD body — a `<form>` element. */
+  $body: HTMLFormElement | null = null;
+  /** The header pulled out of the body content, if present. */
+  $header: HTMLElement | null = null;
+  /** The footer pulled out of the body content, if present. */
+  $footer: HTMLElement | null = null;
+  /** The scrollable wrapper around {@link $main}. */
+  $mainContainer: HTMLElement | null = null;
+  /** The main content element (consumers append their content here). */
+  $main: HTMLElement | null = null;
+  /** The shade/backdrop element (only when `withShade`). */
+  $shade: HTMLElement | null = null;
+  /** The focusable element immediately after the trigger in the DOM, for the Tab cycle. */
+  $nextFocusableElement: HTMLElement | null = null;
+
+  /** Whether the HUD is currently shown. */
+  showing = false;
+  /** The currently chosen orientation, or `null` before the first positioning pass. */
+  orientation: HUDOrientation | null = null;
+  /** The currently applied tip class (e.g. `'tip-top'`), or `null`. */
+  tipClass: string | null = null;
+
+  // Reposition bookkeeping (legacy parity; powers the scroll-follow change detection).
+  private updatingSizeAndPosition = false;
+  windowWidth: number | null = null;
+  windowHeight: number | null = null;
+  scrollTop: number | null = null;
+  scrollLeft: number | null = null;
+  mainWidth: number | null = null;
+  mainHeight: number | null = null;
+  spWidth: number | null = null;
+  spHeight: number | null = null;
+  spScrollTop: number | null = null;
+  spScrollLeft: number | null = null;
+
+  /**
+   * @param trigger - The trigger/anchor element (or selector/`ElementInput`).
+   * @param bodyContents - Initial body contents (string HTML, node(s)), or a
+   *   `Partial<HUDSettings>` object (param shift: when this is a plain object and
+   *   no third arg is given, it is treated as the settings).
+   * @param settings - Optional settings overrides (see {@link HUDSettings}).
+   */
+  constructor(
+    trigger: ElementInput,
+    bodyContents: HUDBodyContents | Partial<HUDSettings> = '',
+    settings?: Partial<HUDSettings>
+  ) {
+    super();
+
+    this.$trigger = (getElement(trigger) as HTMLElement | undefined) ?? null;
+
+    // Param mapping: `new HUD(trigger, settings)` when the 2nd arg is a plain object.
+    let contents: HUDBodyContents = '';
+    if (settings === undefined && isPlainObject(bodyContents)) {
+      settings = bodyContents as Partial<HUDSettings>;
+    } else {
+      contents = bodyContents as HUDBodyContents;
+    }
+
+    this.setSettings(settings, HUD.defaults);
+
+    // Register the settings callbacks as event handlers (legacy behavior).
+    this.on('show', this.settings!.onShow as never);
+    this.on('hide', this.settings!.onHide as never);
+    this.on('submit', this.settings!.onSubmit as never);
+
+    this.$trigger?.setAttribute('aria-expanded', 'false');
+
+    // Build the shade.
+    if (this.settings!.withShade) {
+      this.$shade = document.createElement('div');
+      this.$shade.className = this.settings!.shadeClass;
+    }
+
+    // Build the HUD tree: hud > (tip, body > mainContainer > main).
+    this.$hud = document.createElement('div');
+    this.$hud.className = this.settings!.hudClass;
+    hudElements.set(this.$hud, this);
+
+    this.$tip = document.createElement('div');
+    this.$tip.className = this.settings!.tipClass;
+    this.$hud.appendChild(this.$tip);
+
+    this.$body = document.createElement('form');
+    this.$body.className = this.settings!.bodyClass;
+    this.$hud.appendChild(this.$body);
+
+    this.$mainContainer = document.createElement('div');
+    this.$mainContainer.className = this.settings!.mainContainerClass;
+    this.$body.appendChild(this.$mainContainer);
+
+    this.$main = document.createElement('div');
+    this.$main.className = this.settings!.mainClass;
+    this.$mainContainer.appendChild(this.$main);
+
+    this.updateBody(contents);
+
+    // Detect a fixed-position ancestor → the HUD positions itself `fixed` too.
+    let parent: Element | null = this.$trigger;
+    while (parent && parent.nodeName !== 'HTML') {
+      if (window.getComputedStyle(parent).position === 'fixed') {
+        this.$fixedTriggerParent = parent as HTMLElement;
+        break;
+      }
+      parent = (parent as HTMLElement).offsetParent;
+    }
+
+    this.$hud.style.position = this.$fixedTriggerParent ? 'fixed' : 'absolute';
+
+    this.addListener(this.$body, 'submit', '_handleSubmit');
+
+    if (this.settings!.withShade && this.settings!.hideOnShadeClick) {
+      this.addListener(this.$shade!, 'click', 'hide');
+    }
+
+    if (this.settings!.closeBtn) {
+      this.addListener(this.settings!.closeBtn, 'activate', 'hide');
+    }
+
+    this.addListener(win, 'resize', 'updateSizeAndPosition');
+    if (!this.$fixedTriggerParent) {
+      this.addListener(
+        globals.scrollContainer,
+        'scroll',
+        'updateSizeAndPosition'
+      );
+    }
+    if (this.settings!.listenToMainResize) {
+      this.addListener(this.$main, 'resize', 'updateSizeAndPosition');
+    }
+
+    // Tabbing on the trigger while open should move focus into the HUD.
+    if (this.$trigger) {
+      this.addListener(this.$trigger, 'keydown', (event) => {
+        const ev = event as unknown as KeyboardEvent;
+        if (ev.keyCode === TAB_KEY && !ev.shiftKey && this.showing) {
+          const focusable = getKeyboardFocusableElements(this.$hud!)[0];
+          if (focusable) {
+            ev.preventDefault();
+            focusable.focus();
+          }
+        }
+      });
+    }
+
+    // Manage focus wrapping within the HUD.
+    this.addListener(this.$hud, 'keydown', (event) => {
+      const ev = event as unknown as KeyboardEvent;
+      if (ev.keyCode !== TAB_KEY) {
+        return;
+      }
+
+      const focusable = getKeyboardFocusableElements(this.$hud!);
+      const index = focusable.indexOf(ev.target as HTMLElement);
+
+      if (index === 0 && ev.shiftKey) {
+        ev.preventDefault();
+        this.$trigger?.focus();
+      } else if (
+        index === focusable.length - 1 &&
+        !ev.shiftKey &&
+        this.$nextFocusableElement
+      ) {
+        ev.preventDefault();
+        this.$nextFocusableElement.focus();
+      }
+    });
+
+    if (this.settings!.showOnInit) {
+      // Hide the HUD until it gets positioned to avoid a flash at (0,0).
+      this.$hud.style.opacity = '0';
+      this.show();
+      this.$hud.style.opacity = '1';
+    } else {
+      bod.appendChild(this.$hud);
+      this.hideContainer();
+    }
+
+    HUD.instances.push(this);
+  }
+
+  /**
+   * Replace the HUD body contents, re-extracting any header/footer (matched by
+   * `headerClass` / `footerClass`) and hoisting them out of the scrollable main
+   * region.
+   *
+   * @param bodyContents - String HTML, a node, or a list of nodes.
+   */
+  updateBody(bodyContents: HUDBodyContents): void {
+    // Cleanup.
+    this.$main!.innerHTML = '';
+
+    if (this.$header) {
+      this.$hud!.classList.remove('has-header');
+      this.$header.remove();
+      this.$header = null;
+    }
+
+    if (this.$footer) {
+      this.$hud!.classList.remove('has-footer');
+      this.$footer.remove();
+      this.$footer = null;
+    }
+
+    // Append the new body contents.
+    appendContent(this.$main!, bodyContents);
+
+    // Look for a header and footer (first match each).
+    const header = this.$main!.querySelector<HTMLElement>(
+      `.${this.settings!.headerClass}`
+    );
+    const footer = this.$main!.querySelector<HTMLElement>(
+      `.${this.settings!.footerClass}`
+    );
+
+    if (header) {
+      this.$mainContainer!.before(header);
+      this.$header = header;
+      this.$hud!.classList.add('has-header');
+    }
+
+    if (footer) {
+      this.$mainContainer!.after(footer);
+      this.$footer = footer;
+      this.$hud!.classList.add('has-footer');
+    }
+  }
+
+  /**
+   * Show the HUD: append it (and the shade) to `<body>`, register the UI layer +
+   * Escape shortcut, wire the trigger→HUD Tab cycle, emit `show`, and position
+   * it against the trigger. No-op if already showing.
+   *
+   * @param ev - The triggering DOM event, if any; its propagation is stopped.
+   */
+  show(ev?: Event): void {
+    if (ev && ev.stopPropagation) {
+      ev.stopPropagation();
+    }
+
+    if (this.showing) {
+      return;
+    }
+
+    if (this.settings!.closeOtherHUDs) {
+      for (const hudID in HUD.activeHUDs) {
+        if (!Object.prototype.hasOwnProperty.call(HUD.activeHUDs, hudID)) {
+          continue;
+        }
+        HUD.activeHUDs[hudID]!.hide();
+      }
+    }
+
+    // Blur the active element to prevent the page from jumping.
+    if (
+      document.activeElement &&
+      document.activeElement !== document.body &&
+      document.activeElement instanceof HTMLElement
+    ) {
+      document.activeElement.blur();
+    }
+
+    // Move it to the end of <body> for the highest sub-z-index.
+    if (this.settings!.withShade) {
+      bod.appendChild(this.$shade!);
+      this.$shade!.style.display = 'block';
+    }
+
+    bod.appendChild(this.$hud!);
+    this.$trigger?.setAttribute('aria-expanded', 'true');
+    this.showContainer();
+
+    this.showing = true;
+    HUD.activeHUDs[this._namespace] = this;
+
+    const manager = getUiLayerManager();
+    manager?.addLayer(this.$hud ?? undefined);
+
+    if (this.settings!.hideOnEsc) {
+      manager?.registerShortcut(ESC_KEY, () => {
+        this.hide();
+      });
+    }
+
+    // Find the next focusable element after the trigger; Shift-Tab on it should
+    // take focus back into the HUD.
+    if (this.$trigger) {
+      const focusable = getFocusableElements(bod);
+      const triggerIndex = focusable.indexOf(this.$trigger);
+      if (triggerIndex !== -1 && focusable.length > triggerIndex + 1) {
+        this.$nextFocusableElement = focusable[triggerIndex + 1]!;
+        this.addListener(this.$nextFocusableElement, 'keydown', (event) => {
+          const kev = event as unknown as KeyboardEvent;
+          if (kev.keyCode === TAB_KEY && kev.shiftKey) {
+            const items = getKeyboardFocusableElements(this.$hud!);
+            const last = items[items.length - 1];
+            if (last) {
+              kev.preventDefault();
+              last.focus();
+            }
+          }
+        });
+      }
+    }
+
+    this.onShow();
+    this.enable();
+
+    if (this.updateRecords()) {
+      // Prevent the browser from jumping.
+      this.$hud!.style.top = `${this._scrollContainerScrollTop()}px`;
+      this.updateSizeAndPosition(true);
+    }
+  }
+
+  /** Reveal the HUD container (display toggle; legacy `$hud.show()`). */
+  showContainer(): void {
+    this.$hud!.style.display = 'block';
+  }
+
+  /**
+   * Hook called when the HUD is shown: emits the `show` event. Override and call
+   * `super.onShow()` to extend.
+   */
+  onShow(): void {
+    this.trigger('show');
+  }
+
+  /**
+   * Re-measure the window / scroll / main-content records, returning whether any
+   * of them changed since the last measurement. Drives the scroll-follow
+   * change-detection so repositioning only runs when something actually moved.
+   */
+  updateRecords(): boolean {
+    let changed = false;
+
+    changed =
+      this.windowWidth !== (this.windowWidth = window.innerWidth) || changed;
+    changed =
+      this.windowHeight !== (this.windowHeight = window.innerHeight) || changed;
+    changed =
+      this.scrollTop !== (this.scrollTop = this._scrollContainerScrollTop()) ||
+      changed;
+    changed =
+      this.scrollLeft !==
+        (this.scrollLeft = this._scrollContainerScrollLeft()) || changed;
+    changed =
+      this.mainWidth !== (this.mainWidth = getOuterWidth(this.$main!)) ||
+      changed;
+    changed =
+      this.mainHeight !== (this.mainHeight = getOuterHeight(this.$main!)) ||
+      changed;
+
+    const scrollParent = this.$trigger
+      ? getScrollParent(this.$trigger)
+      : globals.scrollContainer;
+    if (
+      scrollParent !== globals.scrollContainer &&
+      scrollParent instanceof Element
+    ) {
+      changed =
+        this.spWidth !== (this.spWidth = scrollParent.clientWidth) || changed;
+      changed =
+        this.spHeight !== (this.spHeight = scrollParent.clientHeight) ||
+        changed;
+      changed =
+        this.spScrollTop !== (this.spScrollTop = scrollParent.scrollTop) ||
+        changed;
+      changed =
+        this.spScrollLeft !== (this.spScrollLeft = scrollParent.scrollLeft) ||
+        changed;
+    }
+
+    return changed;
+  }
+
+  /**
+   * Schedule a reposition. Runs {@link updateSizeAndPositionInternal} on the next
+   * animation frame when forced, or when {@link updateRecords} reports a change
+   * and a reposition isn't already pending.
+   *
+   * @param force - Reposition unconditionally (used on show).
+   */
+  updateSizeAndPosition(force?: boolean | Event): void {
+    if (
+      force === true ||
+      (this.updateRecords() && !this.updatingSizeAndPosition)
+    ) {
+      this.updatingSizeAndPosition = true;
+      requestAnimationFrame(() => this.updateSizeAndPositionInternal());
+    }
+  }
+
+  /**
+   * The core 4-way positioning pass. Measures the trigger and HUD body, computes
+   * the available clearance on each side, picks the first orientation (in
+   * `orientations` order) that fits — falling back to the side with the most
+   * clearance — then clamps the body within the viewport, centers the HUD on the
+   * trigger, and positions the tip. Emits `updateSizeAndPosition` when done.
+   */
+  updateSizeAndPositionInternal(): void {
+    const settings = this.settings!;
+    const hud = this.$hud!;
+    const tip = this.$tip!;
+    const body = this.$body!;
+    const mainContainer = this.$mainContainer!;
+
+    // Window scroll + trigger metrics.
+    let windowScrollLeft = window.scrollX;
+    let windowScrollTop = window.scrollY;
+
+    const triggerWidth = this.$trigger ? getOuterWidth(this.$trigger) : 0;
+    const triggerHeight = this.$trigger ? getOuterHeight(this.$trigger) : 0;
+
+    // Document-relative offset (jQuery `.offset()`).
+    const triggerOffset: OffsetRect = this.$trigger
+      ? jQueryOffset(this.$trigger)
+      : {top: 0, left: 0, right: 0, bottom: 0};
+
+    let scrollContainerTriggerOffset: OffsetRect;
+    let scrollContainerScrollLeft: number;
+    let scrollContainerScrollTop: number;
+
+    if (this.$fixedTriggerParent) {
+      triggerOffset.left -= windowScrollLeft;
+      triggerOffset.top -= windowScrollTop;
+
+      scrollContainerTriggerOffset = {...triggerOffset};
+
+      windowScrollLeft = 0;
+      windowScrollTop = 0;
+      scrollContainerScrollLeft = 0;
+      scrollContainerScrollTop = 0;
+    } else {
+      const off = this.$trigger ? getOffset(this.$trigger) : {top: 0, left: 0};
+      scrollContainerTriggerOffset = {
+        top: off.top,
+        left: off.left,
+        right: 0,
+        bottom: 0,
+      };
+      scrollContainerScrollLeft = this._scrollContainerScrollLeft();
+      scrollContainerScrollTop = this._scrollContainerScrollTop();
+    }
+
+    triggerOffset.right = triggerOffset.left + triggerWidth;
+    triggerOffset.bottom = triggerOffset.top + triggerHeight;
+
+    scrollContainerTriggerOffset.right =
+      scrollContainerTriggerOffset.left + triggerWidth;
+    scrollContainerTriggerOffset.bottom =
+      scrollContainerTriggerOffset.top + triggerHeight;
+
+    // Reset HUD sizing, then measure the body.
+    hud.style.width = '';
+    mainContainer.style.height = '';
+    mainContainer.style.overflowX = '';
+    mainContainer.style.overflowY = '';
+
+    let hudBodyWidth = getContentWidth(body);
+    let hudBodyHeight = getContentHeight(body);
+
+    // Available clearance on each side of the trigger.
+    const clearances: Record<HUDOrientation, number> = {
+      bottom:
+        this.windowHeight! +
+        scrollContainerScrollTop -
+        scrollContainerTriggerOffset.bottom,
+      top: scrollContainerTriggerOffset.top - scrollContainerScrollTop,
+      right:
+        this.windowWidth! +
+        scrollContainerScrollLeft -
+        scrollContainerTriggerOffset.right,
+      left: scrollContainerTriggerOffset.left - scrollContainerScrollLeft,
+    };
+
+    // Pick the first orientation with enough room, in order of preference.
+    this.orientation = null;
+
+    for (let i = 0; i < settings.orientations.length; i++) {
+      const orientation = settings.orientations[i]!;
+      const relevantSize =
+        orientation === 'top' || orientation === 'bottom'
+          ? hudBodyHeight
+          : hudBodyWidth;
+
+      if (
+        clearances[orientation] -
+          (settings.windowSpacing + settings.triggerSpacing) >=
+        relevantSize
+      ) {
+        this.orientation = orientation;
+        break;
+      }
+
+      if (
+        !this.orientation ||
+        clearances[orientation] > clearances[this.orientation]
+      ) {
+        // Fall back to the side with the most clearance so far.
+        this.orientation = orientation;
+      }
+    }
+
+    // Just in case.
+    if (
+      !this.orientation ||
+      !['bottom', 'top', 'right', 'left'].includes(this.orientation)
+    ) {
+      this.orientation = 'bottom';
+    }
+
+    // Update the tip class.
+    if (this.tipClass) {
+      tip.classList.remove(this.tipClass);
+    }
+    this.tipClass = `${settings.tipClass}-${HUD.tipClasses[this.orientation]}`;
+    tip.classList.add(this.tipClass);
+
+    // Constrain the HUD body to the allowed size.
+    let maxHudBodyWidth: number;
+    let maxHudBodyHeight: number;
+
+    if (this.orientation === 'top' || this.orientation === 'bottom') {
+      maxHudBodyWidth = this.windowWidth! - settings.windowSpacing * 2;
+      maxHudBodyHeight =
+        clearances[this.orientation] -
+        settings.windowSpacing -
+        settings.triggerSpacing;
+    } else {
+      maxHudBodyWidth =
+        clearances[this.orientation] -
+        settings.windowSpacing -
+        settings.triggerSpacing;
+      maxHudBodyHeight = this.windowHeight! - settings.windowSpacing * 2;
+    }
+
+    if (maxHudBodyWidth < settings.minBodyWidth) {
+      maxHudBodyWidth = settings.minBodyWidth;
+    }
+    if (maxHudBodyHeight < settings.minBodyHeight) {
+      maxHudBodyHeight = settings.minBodyHeight;
+    }
+
+    if (
+      hudBodyWidth > maxHudBodyWidth ||
+      hudBodyWidth < settings.minBodyWidth
+    ) {
+      if (hudBodyWidth > maxHudBodyWidth) {
+        hudBodyWidth = maxHudBodyWidth;
+      } else {
+        hudBodyWidth = settings.minBodyWidth;
+      }
+
+      hud.style.width = `${hudBodyWidth}px`;
+
+      // Any horizontal overflow now?
+      if (this.mainWidth! > maxHudBodyWidth) {
+        mainContainer.style.overflowX = 'scroll';
+      }
+
+      // The height may have changed.
+      hudBodyHeight = getContentHeight(body);
+    }
+
+    if (
+      hudBodyHeight > maxHudBodyHeight ||
+      hudBodyHeight < settings.minBodyHeight
+    ) {
+      if (hudBodyHeight > maxHudBodyHeight) {
+        hudBodyHeight = maxHudBodyHeight;
+      } else {
+        hudBodyHeight = settings.minBodyHeight;
+      }
+
+      let mainHeight = hudBodyHeight;
+      if (this.$header) {
+        mainHeight -= getOuterHeight(this.$header);
+      }
+      if (this.$footer) {
+        mainHeight -= getOuterHeight(this.$footer);
+      }
+
+      mainContainer.style.height = `${mainHeight}px`;
+
+      // Any vertical overflow now?
+      if (this.mainHeight! > mainHeight) {
+        mainContainer.style.overflowY = 'scroll';
+      }
+    }
+
+    // Position the HUD + tip.
+    let triggerCenter: number;
+    let left: number;
+    let top: number;
+
+    hud.style.borderTopLeftRadius = '';
+    hud.style.borderTopRightRadius = '';
+    hud.style.borderBottomRightRadius = '';
+    hud.style.borderBottomLeftRadius = '';
+    const borderRadius =
+      parseInt(window.getComputedStyle(hud).borderRadius, 10) || 0;
+
+    if (this.orientation === 'top' || this.orientation === 'bottom') {
+      // Center horizontally.
+      const maxLeft =
+        this.windowWidth! +
+        windowScrollLeft -
+        (hudBodyWidth + settings.windowSpacing);
+      const minLeft = windowScrollLeft + settings.windowSpacing;
+      triggerCenter = triggerOffset.left + Math.round(triggerWidth / 2);
+      left = triggerCenter - Math.round(hudBodyWidth / 2);
+
+      if (left > maxLeft) {
+        left = maxLeft;
+      }
+      if (left < minLeft) {
+        left = minLeft;
+      }
+
+      hud.style.left = `${left}px`;
+
+      const tipLeft = within(
+        triggerCenter - left - settings.tipWidth / 2,
+        0,
+        hudBodyWidth - settings.tipWidth
+      );
+      tip.style.left = `${tipLeft}px`;
+      tip.style.top = '';
+
+      if (this.orientation === 'top') {
+        top = triggerOffset.top - (hudBodyHeight + settings.triggerSpacing);
+      } else {
+        top = triggerOffset.bottom + settings.triggerSpacing;
+      }
+      hud.style.top = `${top}px`;
+
+      const adjustRadius = this.orientation === 'top' ? 'bottom' : 'top';
+      if (tipLeft < borderRadius) {
+        this._setRadius(adjustRadius, 'left');
+      } else if (tipLeft > hudBodyWidth - borderRadius - settings.tipWidth) {
+        this._setRadius(adjustRadius, 'right');
+      }
+    } else {
+      // Center vertically.
+      const maxTop =
+        this.windowHeight! +
+        windowScrollTop -
+        (hudBodyHeight + settings.windowSpacing);
+      const minTop = windowScrollTop + settings.windowSpacing;
+      triggerCenter = triggerOffset.top + Math.round(triggerHeight / 2);
+      top = triggerCenter - Math.round(hudBodyHeight / 2);
+
+      if (top > maxTop) {
+        top = maxTop;
+      }
+      if (top < minTop) {
+        top = minTop;
+      }
+
+      hud.style.top = `${top}px`;
+
+      const tipTop = within(
+        triggerCenter - top - settings.tipWidth / 2,
+        0,
+        hudBodyHeight - settings.tipWidth
+      );
+      tip.style.top = `${tipTop}px`;
+      tip.style.left = '';
+
+      if (this.orientation === 'left') {
+        left = triggerOffset.left - (hudBodyWidth + settings.triggerSpacing);
+      } else {
+        left = triggerOffset.right + settings.triggerSpacing;
+      }
+      hud.style.left = `${left}px`;
+
+      const adjustRadius = this.orientation === 'left' ? 'right' : 'left';
+      if (tipTop < borderRadius) {
+        this._setRadius('top', adjustRadius);
+      } else if (tipTop > hudBodyHeight - borderRadius - settings.tipWidth) {
+        this._setRadius('bottom', adjustRadius);
+      }
+    }
+
+    this.updatingSizeAndPosition = false;
+    this.trigger('updateSizeAndPosition');
+  }
+
+  /**
+   * Hide the HUD: toggle the container off, restore focus to the trigger if focus
+   * was inside, pop the UI layer, drop the Tab-cycle listener, and emit `hide`.
+   * No-op if not currently showing.
+   */
+  hide(): void {
+    if (!this.showing) {
+      return;
+    }
+
+    this.disable();
+    this.$trigger?.setAttribute('aria-expanded', 'false');
+    this.hideContainer();
+
+    if (this.settings!.withShade && this.$shade) {
+      this.$shade.style.display = 'none';
+    }
+
+    this.showing = false;
+    delete HUD.activeHUDs[this._namespace];
+    getUiLayerManager()?.removeLayer();
+
+    if (this.$hud && focusIsInside(this.$hud)) {
+      this.$trigger?.focus();
+    }
+
+    if (this.$nextFocusableElement) {
+      this.removeListener(this.$nextFocusableElement, 'keydown');
+      this.$nextFocusableElement = null;
+    }
+
+    this.onHide();
+  }
+
+  /** Hide the HUD container (display toggle; legacy `$hud.hide()`). */
+  hideContainer(): void {
+    this.$hud!.style.display = 'none';
+  }
+
+  /**
+   * Hook called when the HUD is hidden: emits the `hide` event. Override and call
+   * `super.onHide()` to extend.
+   */
+  onHide(): void {
+    this.trigger('hide');
+  }
+
+  /** Toggle the HUD's visibility. */
+  toggle(): void {
+    if (this.showing) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  }
+
+  /** Submit the HUD (fires the `submit` event via {@link onSubmit}). */
+  submit(): void {
+    this.onSubmit();
+  }
+
+  /**
+   * Hook called when the HUD's form is submitted: emits the `submit` event.
+   * Override and call `super.onSubmit()` to extend.
+   */
+  onSubmit(): void {
+    this.trigger('submit');
+  }
+
+  /**
+   * Destroy the HUD: remove its container + shade from the DOM, drop it from
+   * {@link HUD.instances} and {@link HUD.activeHUDs}, then run the base teardown
+   * (emits `destroy`, removes all listeners). Override and call `super.destroy()`
+   * to clean up extra state.
+   */
+  override destroy(): void {
+    if (this.$hud) {
+      hudElements.delete(this.$hud);
+      this.$hud.remove();
+    }
+
+    if (this.settings!.withShade && this.$shade) {
+      this.$shade.remove();
+    }
+
+    delete HUD.activeHUDs[this._namespace];
+    HUD.instances = HUD.instances.filter((o) => o !== this);
+
+    super.destroy();
+  }
+
+  // --- Internals ------------------------------------------------------------
+
+  private _handleSubmit(ev: GarnishEvent): void {
+    (ev as unknown as Event).preventDefault();
+    this.submit();
+  }
+
+  /** The scroll container's vertical scroll offset (window or element). */
+  private _scrollContainerScrollTop(): number {
+    const sc = globals.scrollContainer;
+    return sc === win ? window.scrollY : (sc as Element).scrollTop;
+  }
+
+  /** The scroll container's horizontal scroll offset (window or element). */
+  private _scrollContainerScrollLeft(): number {
+    const sc = globals.scrollContainer;
+    return sc === win ? window.scrollX : (sc as Element).scrollLeft;
+  }
+
+  /** Set one of the HUD's corner border-radii to the legacy tip-clearance value. */
+  private _setRadius(
+    vertical: 'top' | 'bottom',
+    horizontal: 'left' | 'right'
+  ): void {
+    const prop =
+      vertical === 'top'
+        ? horizontal === 'left'
+          ? 'borderTopLeftRadius'
+          : 'borderTopRightRadius'
+        : horizontal === 'left'
+          ? 'borderBottomLeftRadius'
+          : 'borderBottomRightRadius';
+    this.$hud!.style[prop] = '2px';
+  }
+}
+
+/**
+ * Append body contents to an element — the native replacement for jQuery
+ * `.append()`. Strings are parsed as HTML; nodes are appended; lists are
+ * appended in order. Empty/nullish content is a no-op.
+ */
+function appendContent(parent: HTMLElement, content: HUDBodyContents): void {
+  if (content === null || content === undefined || content === '') {
+    return;
+  }
+
+  if (typeof content === 'string') {
+    parent.insertAdjacentHTML('beforeend', content);
+  } else if (content instanceof Node) {
+    parent.appendChild(content);
+  } else {
+    for (const node of Array.from(content as ArrayLike<Node>)) {
+      if (node) {
+        parent.appendChild(node);
+      }
+    }
+  }
+}
+
+/** Document-relative offset rectangle (jQuery `.offset()` parity). */
+function jQueryOffset(el: Element): OffsetRect {
+  const rect = el.getBoundingClientRect();
+  return {
+    top: rect.top + window.scrollY,
+    left: rect.left + window.scrollX,
+    right: 0,
+    bottom: 0,
+  };
+}
+
+/**
+ * Content-box width (jQuery `.width()` parity): the border-box width from
+ * `getBoundingClientRect()` minus horizontal padding and border. Using the rect
+ * (rather than `clientWidth`) keeps it mockable in layout-less test environments.
+ */
+function getContentWidth(el: HTMLElement): number {
+  const cs = window.getComputedStyle(el);
+  return (
+    el.getBoundingClientRect().width -
+    (parseFloat(cs.paddingLeft) || 0) -
+    (parseFloat(cs.paddingRight) || 0) -
+    (parseFloat(cs.borderLeftWidth) || 0) -
+    (parseFloat(cs.borderRightWidth) || 0)
+  );
+}
+
+/**
+ * Content-box height (jQuery `.height()` parity): the border-box height from
+ * `getBoundingClientRect()` minus vertical padding and border.
+ */
+function getContentHeight(el: HTMLElement): number {
+  const cs = window.getComputedStyle(el);
+  return (
+    el.getBoundingClientRect().height -
+    (parseFloat(cs.paddingTop) || 0) -
+    (parseFloat(cs.paddingBottom) || 0) -
+    (parseFloat(cs.borderTopWidth) || 0) -
+    (parseFloat(cs.borderBottomWidth) || 0)
+  );
+}
+
+export default HUD;
diff --git a/packages/craftcms-garnish/src/icons/resize-handle.ts b/packages/craftcms-garnish/src/icons/resize-handle.ts
new file mode 100644
index 00000000000..ad9cc80f8ea
--- /dev/null
+++ b/packages/craftcms-garnish/src/icons/resize-handle.ts
@@ -0,0 +1,9 @@
+/**
+ * ResizeHandle SVG markup (ltr + rtl variants), ported verbatim from
+ * `icons/ResizeHandle.js`. Used by resizable modals.
+ */
+
+export const ResizeHandle =
+  '<svg class="ltr" fill="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="M20 0 0 20h2L20 2V0ZM20 6 6 20h2L20 8V6ZM20 12l-8 8h2l6-6v-2Z" fill="#000"/></svg><svg class="rtl" fill="none" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><path d="m0 0 20 20h-2L0 2V0ZM0 6l14 14h-2L0 8V6ZM0 12l8 8H6l-6-6v-2Z" fill="#000"/></svg>';
+
+export default ResizeHandle;
diff --git a/packages/craftcms-garnish/src/index.ts b/packages/craftcms-garnish/src/index.ts
new file mode 100644
index 00000000000..590d13461f1
--- /dev/null
+++ b/packages/craftcms-garnish/src/index.ts
@@ -0,0 +1,253 @@
+/**
+ * @craftcms/garnish — modern, tree-shakeable TypeScript rewrite of Craft CMS's
+ * Garnish UI library. jQuery-free, ESM-only.
+ *
+ * Exposes BOTH tree-shakeable named exports (preferred for new code) and a
+ * legacy-shaped `Garnish` namespace object (+ `initGarnish()`) for incremental
+ * migration and for the compat layer to extend.
+ *
+ * The core deliberately does NOT: assign `window.Garnish`, add `$.fn` sugar, or
+ * pull in jQuery — those are the compat layer's job.
+ */
+
+import {Base} from './base';
+import {
+  ClassEventBus,
+  EventEmitter,
+  formatDomEvents,
+  parseEvents,
+  type GarnishEvent,
+  type GarnishEventHandler,
+} from './events';
+import {
+  DomListenerRegistry,
+  type DomListenerOptions,
+  type ElementInput,
+} from './dom-listeners';
+import {
+  installActivate,
+  installResize,
+  installTextchange,
+} from './custom-events';
+import {EscManager} from './managers/esc-manager';
+import {UiLayerManager} from './managers/ui-layer-manager';
+import {setUiLayerManager} from './managers/registry';
+import {Modal, type ModalSettings} from './modal';
+import {HUD, type HUDSettings} from './hud';
+import {DisclosureMenu, type DisclosureMenuSettings} from './disclosure-menu';
+import {BaseDrag, type BaseDragSettings} from './drag/base-drag';
+import {Drag, type DragSettings} from './drag/drag';
+import {DragDrop, type DragDropSettings} from './drag/drag-drop';
+import {DragSort, type DragSortSettings} from './drag/drag-sort';
+import {DragMove} from './drag-move';
+import {ResizeHandle} from './icons/resize-handle';
+import {garnishClassBus, globals, win, doc, bod} from './globals';
+import type {Constructor, GarnishBaseSettings} from './types';
+
+import * as constants from './constants';
+import * as utils from './utils';
+
+// --- Named exports (preferred for new code) ---------------------------------
+
+export {Base};
+export type {GarnishBaseSettings, ElementInput};
+export {
+  EventEmitter,
+  ClassEventBus,
+  parseEvents,
+  formatDomEvents,
+  type GarnishEvent,
+  type GarnishEventHandler,
+};
+export {DomListenerRegistry, type DomListenerOptions};
+export {installActivate, installTextchange, installResize};
+export type {TextchangeOptions, ActivateOptions} from './custom-events';
+export {EscManager};
+export {UiLayerManager};
+export {Modal, type ModalSettings};
+export {HUD, type HUDSettings};
+export type {HUDOrientation, HUDBodyContents} from './hud';
+export {DisclosureMenu, type DisclosureMenuSettings};
+export type {
+  DisclosureMenuItem,
+  DisclosureMenuItemConfig,
+} from './disclosure-menu';
+export {BaseDrag, type BaseDragSettings};
+export {Drag, type DragSettings};
+export {DragDrop, type DragDropSettings};
+export {DragSort, type DragSortSettings};
+export {DragMove};
+export {ResizeHandle};
+export {win, doc, bod};
+
+export * from './utils';
+export * from './constants';
+
+export const VERSION = '0.0.0';
+
+// --- Legacy-shaped namespace object -----------------------------------------
+
+/**
+ * Class-level event bus proxies. Legacy `Garnish.on/off/once` register
+ * class-level handlers dispatched via instanceof in `Base.trigger`.
+ */
+function on(
+  target: Constructor,
+  events: string,
+  data: Record<string, unknown> | GarnishEventHandler,
+  handler?: GarnishEventHandler
+): void {
+  (garnishClassBus.on as (...a: unknown[]) => void)(
+    target,
+    events,
+    data,
+    handler
+  );
+}
+function off(
+  target: Constructor,
+  events: string,
+  handler?: GarnishEventHandler
+): void {
+  garnishClassBus.off(target, events, handler);
+}
+function once(
+  target: Constructor,
+  events: string,
+  data: Record<string, unknown> | GarnishEventHandler,
+  handler?: GarnishEventHandler
+): void {
+  (garnishClassBus.once as (...a: unknown[]) => void)(
+    target,
+    events,
+    data,
+    handler
+  );
+}
+
+/**
+ * The legacy-shaped `Garnish` namespace object — a single value carrying every
+ * Garnish class, constant, utility, and feature flag, mirroring the legacy
+ * `window.Garnish` singleton.
+ *
+ * This is provided for incremental migration and is what the
+ * `@craftcms/garnish/compat` layer wraps and assigns to `window.Garnish`. **New
+ * code should prefer the tree-shakeable named exports** (e.g.
+ * `import {Modal, trapFocusWithin} from '@craftcms/garnish'`) — importing this
+ * object pulls in the whole surface.
+ *
+ * The manager singletons (`escManager`, `uiLayerManager`) are `undefined` until
+ * {@link initGarnish} is called.
+ */
+export const Garnish = {
+  // constants
+  ...constants,
+
+  // native globals (compat adds the jQuery-wrapped $win/$doc/$bod forms)
+  win,
+  doc,
+  bod,
+  get scrollContainer() {
+    return globals.scrollContainer;
+  },
+  set scrollContainer(value: EventTarget) {
+    globals.scrollContainer = value;
+  },
+  get rtl() {
+    return globals.rtl;
+  },
+  get ltr() {
+    return globals.ltr;
+  },
+  get activateEventsMuted() {
+    return globals.activateEventsMuted;
+  },
+  set activateEventsMuted(value: boolean) {
+    globals.activateEventsMuted = value;
+  },
+  get resizeEventsMuted() {
+    return globals.resizeEventsMuted;
+  },
+  set resizeEventsMuted(value: boolean) {
+    globals.resizeEventsMuted = value;
+  },
+
+  // classes
+  Base,
+  EscManager,
+  UiLayerManager,
+  Modal,
+  HUD,
+  DisclosureMenu,
+  BaseDrag,
+  Drag,
+  DragDrop,
+  DragSort,
+  DragMove,
+  /** @deprecated Use UiLayerManager instead. */
+  ShortcutManager: UiLayerManager,
+
+  // class-level event bus
+  on,
+  off,
+  once,
+
+  // event parser (legacy alias)
+  _normalizeEvents: (events: string | string[]) =>
+    parseEvents(events).map((e) => [e.type, e.namespace ?? undefined]),
+
+  // custom-event installers
+  installActivate,
+  installTextchange,
+  installResize,
+
+  // icons
+  ResizeHandle,
+
+  // utilities (every §4 member that survives in core)
+  ...utils,
+  muteResizeEvents,
+
+  // managers (attached by initGarnish)
+  escManager: undefined as EscManager | undefined,
+  uiLayerManager: undefined as UiLayerManager | undefined,
+};
+
+/**
+ * Suppress Garnish `resize` custom events while `callback` runs, then restore
+ * the previous muted state. Useful when programmatically resizing elements that
+ * have `resize` listeners and you don't want them to fire.
+ *
+ * @param callback - The work to run with resize events muted.
+ */
+function muteResizeEvents(callback: () => void): void {
+  const prior = globals.resizeEventsMuted;
+  globals.resizeEventsMuted = true;
+  callback();
+  globals.resizeEventsMuted = prior;
+}
+
+export {muteResizeEvents};
+
+/**
+ * Lazily instantiate the manager singletons (`escManager`, `uiLayerManager`)
+ * and attach them to the {@link Garnish} namespace, registering the UI layer
+ * manager so layer-aware components (like {@link Modal}) can find it. Idempotent.
+ *
+ * The compat layer calls this during install; call it yourself if you use the
+ * `Garnish` namespace object directly and need the managers populated.
+ *
+ * @returns The {@link Garnish} namespace, with managers attached.
+ */
+export function initGarnish(): typeof Garnish {
+  if (!Garnish.escManager) {
+    Garnish.escManager = new EscManager();
+  }
+  if (!Garnish.uiLayerManager) {
+    Garnish.uiLayerManager = new UiLayerManager();
+    setUiLayerManager(Garnish.uiLayerManager);
+  }
+  return Garnish;
+}
+
+export default Garnish;
diff --git a/packages/craftcms-garnish/src/managers/esc-manager.ts b/packages/craftcms-garnish/src/managers/esc-manager.ts
new file mode 100644
index 00000000000..5b3701d1d66
--- /dev/null
+++ b/packages/craftcms-garnish/src/managers/esc-manager.ts
@@ -0,0 +1,67 @@
+/**
+ * ESC key manager.
+ *
+ * @deprecated Use UiLayerManager instead. Kept for parity.
+ */
+
+import {Base} from '../base';
+import {bod} from '../globals';
+import {ESC_KEY} from '../constants';
+
+type EscHandlerFn = (ev: KeyboardEvent) => void;
+
+interface EscRegistration {
+  obj: {
+    [key: string]: unknown;
+    trigger?: (type: string) => void;
+  };
+  func: EscHandlerFn | string;
+}
+
+export class EscManager extends Base {
+  private handlers: EscRegistration[] = [];
+
+  constructor() {
+    super();
+
+    this.addListener(bod, 'keyup', (ev) => {
+      const keyEvent = ev as unknown as KeyboardEvent;
+      if (keyEvent.keyCode === ESC_KEY) {
+        this.escapeLatest(keyEvent);
+      }
+    });
+  }
+
+  register(obj: EscRegistration['obj'], func: EscHandlerFn | string): void {
+    this.handlers.push({obj, func});
+  }
+
+  unregister(obj: EscRegistration['obj']): void {
+    for (let i = this.handlers.length - 1; i >= 0; i--) {
+      if (this.handlers[i]!.obj === obj) {
+        this.handlers.splice(i, 1);
+      }
+    }
+  }
+
+  escapeLatest(ev: KeyboardEvent): void {
+    if (!this.handlers.length) {
+      return;
+    }
+
+    const handler = this.handlers.pop()!;
+
+    let func: EscHandlerFn;
+    if (typeof handler.func === 'function') {
+      func = handler.func;
+    } else {
+      func = handler.obj[handler.func] as EscHandlerFn;
+    }
+
+    func.call(handler.obj, ev);
+
+    if (typeof handler.obj.trigger === 'function') {
+      handler.obj.trigger('escape');
+    }
+  }
+}
diff --git a/packages/craftcms-garnish/src/managers/registry.ts b/packages/craftcms-garnish/src/managers/registry.ts
new file mode 100644
index 00000000000..c89bab29778
--- /dev/null
+++ b/packages/craftcms-garnish/src/managers/registry.ts
@@ -0,0 +1,53 @@
+/**
+ * Manager singleton registry.
+ *
+ * Breaks the circular dependency between `utils/aria.ts` (which needs the active
+ * UI layer manager) and `managers/ui-layer-manager.ts`. `initGarnish()` (or the
+ * compat layer) registers the live instance here.
+ */
+
+/** Minimal shape `utils/aria.ts` needs from the UI layer manager. */
+export interface UiLayer {
+  $container: Element | null;
+  isModal?: boolean;
+}
+
+export interface UiLayerManagerLike {
+  readonly currentLayer: UiLayer;
+  readonly highestModalLayer: UiLayer | undefined;
+}
+
+/**
+ * The fuller manager surface Modal (and other layer-using components) need:
+ * layer registration plus shortcut registration. Kept structural so the
+ * registry has no hard dependency on the concrete `UiLayerManager` class
+ * (avoids a circular import with the `index.ts` barrel).
+ */
+export interface UiLayerManagerFull extends UiLayerManagerLike {
+  addLayer(
+    container?: Element | Record<string, unknown> | null,
+    options?: Record<string, unknown>
+  ): unknown;
+  removeLayer(layer?: Element): unknown;
+  registerShortcut(
+    shortcut: number | {keyCode: number},
+    callback: (ev: KeyboardEvent) => void,
+    layer?: number
+  ): unknown;
+  unregisterShortcut(
+    shortcut: number | {keyCode: number},
+    layer?: number
+  ): unknown;
+}
+
+let uiLayerManager: UiLayerManagerFull | undefined;
+
+export function setUiLayerManager(
+  manager: UiLayerManagerFull | undefined
+): void {
+  uiLayerManager = manager;
+}
+
+export function getUiLayerManager(): UiLayerManagerFull | undefined {
+  return uiLayerManager;
+}
diff --git a/packages/craftcms-garnish/src/managers/ui-layer-manager.ts b/packages/craftcms-garnish/src/managers/ui-layer-manager.ts
new file mode 100644
index 00000000000..4d955caff7e
--- /dev/null
+++ b/packages/craftcms-garnish/src/managers/ui-layer-manager.ts
@@ -0,0 +1,304 @@
+/**
+ * UI Layer Manager.
+ *
+ * Manages the visible UI "layers" — the base document plus any open modals,
+ * HUDs, slideouts, or menus. jQuery-free port of the legacy class.
+ */
+
+import {Base} from '../base';
+import {bod} from '../globals';
+import {isCtrlKeyPressed} from '../utils/env';
+import {getElement} from '../utils/dom';
+import type {UiLayer} from './registry';
+
+export interface ShortcutDef {
+  keyCode: number;
+  ctrl?: boolean;
+  shift?: boolean;
+  alt?: boolean;
+}
+
+interface NormalizedShortcut {
+  keyCode: number;
+  ctrl: boolean;
+  shift: boolean;
+  alt: boolean;
+}
+
+interface RegisteredShortcut {
+  key: string;
+  shortcut: NormalizedShortcut;
+  callback: (ev: KeyboardEvent) => void;
+}
+
+interface LayerOptions {
+  bubble: boolean;
+}
+
+interface Layer extends UiLayer {
+  $container: Element | null;
+  shortcuts: RegisteredShortcut[];
+  isModal?: boolean;
+  options: LayerOptions;
+}
+
+type ShortcutKeyboardEvent = KeyboardEvent & {
+  bubbleShortcut?: () => void;
+};
+
+/**
+ * Manages the stack of visible UI "layers" — the base document plus any open
+ * modals, HUDs, slideouts, or menus — and the keyboard shortcuts scoped to each.
+ * The active instance is a singleton, created by {@link initGarnish} and exposed
+ * as `Garnish.uiLayerManager`; {@link Modal} uses it for layer stacking and its
+ * Escape shortcut.
+ *
+ * Shortcuts are dispatched top-down: a `keydown` is offered to the current
+ * layer's shortcuts first, then bubbles to lower layers only when the layer opts
+ * in (`options.bubble`) or `ev.bubbleShortcut()` is called.
+ */
+export class UiLayerManager extends Base {
+  /** The layer stack; index `0` is the base document layer. */
+  layers: Layer[];
+
+  constructor() {
+    super();
+
+    this.layers = [
+      {
+        $container: bod,
+        shortcuts: [],
+        options: {bubble: false},
+      },
+    ];
+
+    this.addListener(bod, 'keydown', 'triggerShortcut');
+  }
+
+  /** The index of the topmost layer (`0` = base document). */
+  get layer(): number {
+    return this.layers.length - 1;
+  }
+
+  /** The topmost (active) layer. */
+  get currentLayer(): Layer {
+    return this.layers[this.layer]!;
+  }
+
+  /** All layers flagged as modal. */
+  get modalLayers(): Layer[] {
+    return this.layers.filter((layer) => layer.isModal === true);
+  }
+
+  /** The highest modal layer, or `undefined` if no modal is open. */
+  get highestModalLayer(): Layer | undefined {
+    return this.modalLayers.pop();
+  }
+
+  /**
+   * Push a new UI layer onto the stack and emit `addLayer`. A layer whose
+   * container has `aria-modal="true"` is flagged as modal.
+   *
+   * Accepts `(container, options)` or `(options)` (param shift when the first
+   * arg is a plain options object).
+   *
+   * @param container - The layer's container element (or an options object).
+   * @param options - Layer options, e.g. `{bubble: true}` to let unhandled
+   *   shortcuts fall through to lower layers.
+   * @returns `this`, for chaining.
+   */
+  addLayer(
+    container?: Element | Partial<LayerOptions> | null,
+    options?: Partial<LayerOptions>
+  ): this {
+    let containerEl: Element | null = null;
+
+    if (isPlainObject(container)) {
+      options = container as Partial<LayerOptions>;
+      containerEl = null;
+    } else if (container) {
+      containerEl = (getElement(container as Element) as Element) ?? null;
+    }
+
+    const resolvedOptions: LayerOptions = Object.assign(
+      {bubble: false},
+      options ?? {}
+    );
+
+    this.layers.push({
+      $container: containerEl,
+      shortcuts: [],
+      isModal: containerEl
+        ? containerEl.getAttribute('aria-modal') === 'true'
+        : false,
+      options: resolvedOptions,
+    });
+
+    this.trigger('addLayer', {
+      layer: this.layer,
+      $container: this.currentLayer.$container,
+      options: resolvedOptions,
+    });
+
+    return this;
+  }
+
+  /**
+   * Remove a layer and emit `removeLayer`. With no argument, pops the topmost
+   * layer; with an element, removes the matching layer wherever it sits.
+   *
+   * @param layer - The container element of the layer to remove (optional).
+   * @returns `this` when the top layer was popped, otherwise `undefined`.
+   * @throws If asked to remove the base document layer.
+   */
+  removeLayer(layer?: Element): this | undefined {
+    if (this.layer === 0) {
+      throw 'Can’t remove the base layer.';
+    }
+
+    if (layer) {
+      const layerIndex = this.getLayerIndex(layer);
+      if (layerIndex) {
+        this.removeLayerAtIndex(layerIndex);
+      }
+      return undefined;
+    }
+
+    this.layers.pop();
+    this.trigger('removeLayer');
+    return this;
+  }
+
+  getLayerIndex(layer: Element): number | undefined {
+    const layerEl = getElement(layer) as Element | undefined;
+    let layerIndex: number | undefined;
+
+    this.layers.forEach((l, index) => {
+      if (
+        layerIndex === undefined &&
+        l.$container !== null &&
+        l.$container === layerEl
+      ) {
+        layerIndex = index;
+      }
+    });
+
+    return layerIndex;
+  }
+
+  removeLayerAtIndex(index: number): this {
+    this.layers.splice(index, 1);
+    this.trigger('removeLayer');
+    return this;
+  }
+
+  /**
+   * Register a keyboard shortcut on a layer (the current one by default).
+   *
+   * @param shortcut - A key code, or a `{keyCode, ctrl?, shift?, alt?}` definition.
+   * @param callback - Invoked (after `preventDefault`) when the shortcut matches.
+   * @param layer - Layer index to scope the shortcut to; defaults to the current layer.
+   * @returns `this`, for chaining.
+   *
+   * @example
+   * ```ts
+   * import {Garnish, ESC_KEY} from '@craftcms/garnish';
+   * Garnish.uiLayerManager!.registerShortcut(ESC_KEY, () => closeThing());
+   * ```
+   */
+  registerShortcut(
+    shortcut: number | ShortcutDef,
+    callback: (ev: KeyboardEvent) => void,
+    layer?: number
+  ): this {
+    const normalized = this._normalizeShortcut(shortcut);
+    if (layer === undefined) {
+      layer = this.layer;
+    }
+    this.layers[layer]!.shortcuts.push({
+      key: JSON.stringify(normalized),
+      shortcut: normalized,
+      callback,
+    });
+    return this;
+  }
+
+  /**
+   * Remove a previously registered shortcut from a layer.
+   *
+   * @param shortcut - The same key code / definition passed to {@link registerShortcut}.
+   * @param layer - Layer index; defaults to the current layer.
+   * @returns `this`, for chaining.
+   */
+  unregisterShortcut(shortcut: number | ShortcutDef, layer?: number): this {
+    const normalized = this._normalizeShortcut(shortcut);
+    const key = JSON.stringify(normalized);
+    if (layer === undefined) {
+      layer = this.layer;
+    }
+    const index = this.layers[layer]!.shortcuts.findIndex((s) => s.key === key);
+    if (index !== -1) {
+      this.layers[layer]!.shortcuts.splice(index, 1);
+    }
+    return this;
+  }
+
+  private _normalizeShortcut(
+    shortcut: number | ShortcutDef
+  ): NormalizedShortcut {
+    let def: ShortcutDef;
+    if (typeof shortcut === 'number') {
+      def = {keyCode: shortcut};
+    } else {
+      def = shortcut;
+    }
+
+    if (typeof def.keyCode !== 'number') {
+      throw 'Invalid shortcut';
+    }
+
+    return {
+      keyCode: def.keyCode,
+      ctrl: !!def.ctrl,
+      shift: !!def.shift,
+      alt: !!def.alt,
+    };
+  }
+
+  triggerShortcut(ev: ShortcutKeyboardEvent, layerIndex?: number): void {
+    if (layerIndex === undefined) {
+      layerIndex = this.layer;
+    }
+    const layer = this.layers[layerIndex]!;
+    const shortcut = layer.shortcuts.find(
+      (s) =>
+        s.shortcut.keyCode === ev.keyCode &&
+        s.shortcut.ctrl === isCtrlKeyPressed(ev) &&
+        s.shortcut.shift === ev.shiftKey &&
+        s.shortcut.alt === ev.altKey
+    );
+
+    ev.bubbleShortcut = () => {
+      if (layerIndex! > 0) {
+        this.triggerShortcut(ev, layerIndex! - 1);
+      }
+    };
+
+    if (shortcut) {
+      ev.preventDefault();
+      shortcut.callback(ev);
+    } else if (layer.options.bubble) {
+      ev.bubbleShortcut();
+    }
+  }
+}
+
+function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    !(val instanceof Element) &&
+    (Object.getPrototypeOf(val) === Object.prototype ||
+      Object.getPrototypeOf(val) === null)
+  );
+}
diff --git a/packages/craftcms-garnish/src/modal.ts b/packages/craftcms-garnish/src/modal.ts
new file mode 100644
index 00000000000..c489e763915
--- /dev/null
+++ b/packages/craftcms-garnish/src/modal.ts
@@ -0,0 +1,784 @@
+/**
+ * Modal — modern, jQuery-free TypeScript port of Garnish's `Modal`.
+ *
+ * This is the vertical-slice PoC component. It replaces every jQuery call in the
+ * legacy `Modal.js` (doc 03 §2) with native DOM:
+ *
+ * - element creation/insertion → `document.createElement` + `appendChild`/`insertBefore`
+ * - class/attr/style → `classList` / `setAttribute` / `.style`
+ * - dimensions → `offsetWidth`/`offsetHeight`
+ * - window size → `window.innerWidth`/`innerHeight`
+ * - display → `.style.display`
+ * - data storage → a module-level `WeakMap`
+ * - plain-object check → a local `isPlainObject`
+ * - **animation** → the Web Animations API (`element.animate`), gated on
+ *   `prefersReducedMotion`. `.velocity('stop')` → `cancel()` of the tracked
+ *   animation.
+ *
+ * Draggable/resizable are wired through `DragMove`/`BaseDrag` (doc 07 §6): a
+ * draggable modal uses a `DragMove` on its container (or `dragHandleSelector`),
+ * and a resizable modal uses a `BaseDrag` on a generated resize handle.
+ */
+
+import {Base} from './base';
+import {bod, globals, win} from './globals';
+import {ESC_KEY, FX_DURATION} from './constants';
+import {getUiLayerManager} from './managers/registry';
+import {BaseDrag} from './drag/base-drag';
+import {DragMove} from './drag-move';
+import {ResizeHandle} from './icons/resize-handle';
+import {
+  addModalAttributes,
+  hideModalBackgroundLayers,
+  resetModalBackgroundLayerVisibility,
+} from './utils/aria';
+import {
+  getFocusedElement,
+  setFocusWithin,
+  trapFocusWithin,
+  releaseFocusWithin,
+} from './utils/focus';
+import {prefersReducedMotion} from './utils/animation';
+import type {GarnishBaseSettings} from './types';
+
+/** Duration (ms) of the shade fade, matching legacy. */
+const SHADE_FX_DURATION = 50;
+
+type ModalCallback = () => void;
+
+/** A focus target may be an element, or a function returning one. */
+type FocusTarget =
+  | Element
+  | null
+  | undefined
+  | (() => Element | null | undefined);
+
+/**
+ * Settings accepted by {@link Modal}. Pass a `Partial<ModalSettings>` to the
+ * constructor; unset keys fall back to {@link Modal.defaults}.
+ */
+export interface ModalSettings extends GarnishBaseSettings {
+  /** Show the modal immediately on construction (when a container is given). Default `true`. */
+  autoShow: boolean;
+  /** Allow dragging the modal by its handle. Default `false`. */
+  draggable: boolean;
+  /** Selector for the drag handle (only relevant when `draggable`). Default `null`. */
+  dragHandleSelector: string | null;
+  /** Allow resizing the modal via a generated resize handle. Default `false`. */
+  resizable: boolean;
+  /** Minimum gutter (px) between the modal and the viewport edge. Default `10`. */
+  minGutter: number;
+  /** Callback invoked when the modal is shown. Default no-op. */
+  onShow: ModalCallback;
+  /** Callback invoked when the modal is hidden. Default no-op. */
+  onHide: ModalCallback;
+  /** Callback invoked after the modal finishes fading in. Default no-op. */
+  onFadeIn: ModalCallback;
+  /** Callback invoked after the modal finishes fading out. Default no-op. */
+  onFadeOut: ModalCallback;
+  /** Hide any other visible modal when this one is shown. Default `false`. */
+  closeOtherModals: boolean;
+  /** Hide the modal when the Escape key is pressed. Default `true`. */
+  hideOnEsc: boolean;
+  /** Hide the modal when its shade (backdrop) is clicked. Default `true`. */
+  hideOnShadeClick: boolean;
+  /**
+   * The element (or a function returning one) to restore focus to when the modal
+   * hides. Defaults to whatever was focused at construction time.
+   */
+  triggerElement: FocusTarget;
+  /** CSS class applied to the shade/backdrop element. Default `'modal-shade'`. */
+  shadeClass: string;
+}
+
+/**
+ * Maps a modal container element back to its `Modal` instance — the native
+ * replacement for the legacy `$container.data('modal', this)`.
+ */
+const containerModals = new WeakMap<Element, Modal>();
+
+const noop: ModalCallback = () => {};
+
+/**
+ * An accessible, animated modal dialog — the jQuery-free TypeScript port of
+ * Garnish's `Modal`, and the vertical-slice reference component for this package.
+ *
+ * Handles shade/backdrop, centered sizing within the viewport, fade in/out via
+ * the Web Animations API (respecting `prefers-reduced-motion`), focus trapping
+ * and restoration, ARIA backgrounding of sibling layers, and Escape /
+ * shade-click dismissal. Emits `show`, `hide`, `fadeIn`, `fadeOut`,
+ * `updateSizeAndPosition`, `escape`, and `destroy` events (subscribe with
+ * {@link Base.on}).
+ *
+ * The constructor accepts a container element and/or a settings object, with a
+ * legacy-compatible param shift: `new Modal(settings)` is treated as
+ * `new Modal(null, settings)` when the first argument is a plain object.
+ *
+ * @remarks `draggable` and `resizable` are supported via `DragMove`/`BaseDrag`;
+ * both default to `false`. Drag handles get `touch-action: none` so touch
+ * gestures drive the drag rather than panning the page.
+ *
+ * @example Modern usage
+ * ```ts
+ * import {Modal} from '@craftcms/garnish';
+ *
+ * const el = document.querySelector('#my-modal')!;
+ * const modal = new Modal(el, {
+ *   closeOtherModals: true,
+ *   onShow: () => console.log('shown'),
+ * });
+ *
+ * modal.on('hide', () => console.log('hidden'));
+ * // modal.hide();  modal.destroy();
+ * ```
+ */
+export class Modal extends Base<ModalSettings> {
+  /** Every live `Modal` instance (pushed on construction, removed on {@link destroy}). */
+  static instances: Modal[] = [];
+
+  /** The currently visible modal, or `null` if none is showing. */
+  static visibleModal: Modal | null = null;
+
+  /** Default {@link ModalSettings}, merged with the per-instance overrides. */
+  static readonly defaults: ModalSettings = {
+    autoShow: true,
+    draggable: false,
+    dragHandleSelector: null,
+    resizable: false,
+    minGutter: 10,
+    onShow: noop,
+    onHide: noop,
+    onFadeIn: noop,
+    onFadeOut: noop,
+    closeOtherModals: false,
+    hideOnEsc: true,
+    hideOnShadeClick: true,
+    triggerElement: null,
+    shadeClass: 'modal-shade',
+  };
+
+  /** Legacy parity constant. */
+  static readonly relativeElemPadding = 8;
+
+  // --- Instance state (named with the legacy `$`-prefix for consumer parity) ---
+
+  /** The modal's container element, or `null` until {@link setContainer} runs. */
+  $container: HTMLElement | null = null;
+  /** The shade/backdrop element created for this modal. */
+  $shade: HTMLElement | null = null;
+  /** Overrides the focus-restore target; takes precedence over `settings.triggerElement`. */
+  $triggerElement: Element | null = null;
+  /** The visually-hidden `role="status"` live region appended to the container. */
+  $liveRegion: HTMLElement;
+
+  /** Whether the modal is currently shown. */
+  visible = false;
+
+  /** The `DragMove` driving `draggable`, or `null`. */
+  dragger: DragMove | null = null;
+  /** The `BaseDrag` driving `resizable` (on the resize handle), or `null`. */
+  resizeDragger: BaseDrag | null = null;
+  resizeStartWidth: number | null = null;
+  resizeStartHeight: number | null = null;
+
+  desiredWidth: number | null = null;
+  desiredHeight: number | null = null;
+
+  // Tracked WAAPI animations so we can `cancel()` them (legacy `.velocity('stop')`).
+  private _containerAnim: Animation | null = null;
+  private _shadeAnim: Animation | null = null;
+
+  /**
+   * @param container - The modal's container element, or a `Partial<ModalSettings>`
+   *   object (param shift: when the first arg is a plain object and no second
+   *   arg is given, it is treated as the settings). May be `null` to construct
+   *   a modal whose container is set later via {@link setContainer}.
+   * @param settings - Optional settings overrides (see {@link ModalSettings}).
+   */
+  constructor(
+    container?: Element | Partial<ModalSettings> | null,
+    settings?: Partial<ModalSettings>
+  ) {
+    super();
+
+    // Param mapping: `new Modal(settings)` when the first arg is a plain object.
+    let containerEl: Element | null = null;
+    if (settings === undefined && isPlainObject(container)) {
+      settings = container as Partial<ModalSettings>;
+    } else {
+      containerEl = (container as Element | null) ?? null;
+    }
+
+    this.setSettings(settings, Modal.defaults);
+
+    if (!this.settings!.triggerElement) {
+      this.settings!.triggerElement = getFocusedElement();
+    }
+
+    // Live region announcement element.
+    this.$liveRegion = document.createElement('span');
+    this.$liveRegion.className = 'visually-hidden';
+    this.$liveRegion.setAttribute('role', 'status');
+
+    // Create the shade.
+    this.$shade = document.createElement('div');
+    this.$shade.className = this.settings!.shadeClass;
+
+    // If the container is already set, drop the shade below it.
+    if (containerEl && containerEl.parentNode) {
+      containerEl.parentNode.insertBefore(this.$shade, containerEl);
+    } else {
+      bod.appendChild(this.$shade);
+    }
+
+    if (containerEl) {
+      this.setContainer(containerEl);
+      addModalAttributes(containerEl);
+
+      if (this.settings!.autoShow) {
+        this.show();
+      }
+    }
+
+    Modal.instances.push(this);
+  }
+
+  /** Append the live region ({@link $liveRegion}) to the container, if set. */
+  addLiveRegion(): void {
+    if (!this.$container) {
+      return;
+    }
+    this.$container.appendChild(this.$liveRegion);
+  }
+
+  /**
+   * Assign (or replace) the modal's container element, wiring up its ARIA
+   * attributes, live region, and shade-dismiss listeners. If another modal was
+   * already attached to this element, it is destroyed first.
+   *
+   * @param container - The element to use as the modal container.
+   */
+  setContainer(container: Element): void {
+    this.$container = container as HTMLElement;
+
+    // Already a modal? Tear the old one down (legacy double-instantiation guard).
+    const existing = containerModals.get(container);
+    if (existing) {
+      console.warn('Double-instantiating a modal on an element');
+      existing.destroy();
+    }
+
+    containerModals.set(container, this);
+
+    if (this.settings!.draggable) {
+      const handle = this.settings!.dragHandleSelector
+        ? this.$container.querySelector(this.settings!.dragHandleSelector)
+        : this.$container;
+      this.dragger = new DragMove(this.$container, {handle});
+    }
+
+    if (this.settings!.resizable) {
+      const handle = document.createElement('div');
+      handle.className = 'resizehandle';
+      handle.innerHTML = ResizeHandle;
+      // touch-action: none lets the pointer drive the resize on touch devices.
+      handle.style.touchAction = 'none';
+      this.$container.appendChild(handle);
+
+      this.resizeDragger = new BaseDrag(handle, {
+        onDragStart: () => this._handleResizeStart(),
+        onDrag: () => this._handleResize(),
+      });
+    }
+
+    this.addLiveRegion();
+
+    // The DOM-listener registry passes the native Event augmented with Garnish
+    // fields (core impl note #2), so `stopPropagation` is available at runtime.
+    this.addListener(this.$container, 'click', (ev) => {
+      (ev as unknown as Event).stopPropagation();
+    });
+
+    // Show it if we're late to the party.
+    if (this.visible) {
+      this.show();
+    }
+  }
+
+  /**
+   * Show the modal: move it to the top of `<body>`, fade in the shade then the
+   * container, trap focus, register the Escape shortcut, and emit `show` (and
+   * later `fadeIn`). No-op visually if already visible, but always re-enables.
+   */
+  show(): void {
+    // Close other modals as needed.
+    if (
+      this.settings!.closeOtherModals &&
+      Modal.visibleModal &&
+      Modal.visibleModal !== this
+    ) {
+      Modal.visibleModal.hide();
+    }
+
+    if (this.$container) {
+      // Move shade + container to the end of <body> for the highest sub-z-index.
+      this._cancelAnim('shade');
+      this._cancelAnim('container');
+      bod.appendChild(this.$shade!);
+      bod.appendChild(this.$container);
+
+      this.$container.style.display = 'block';
+      this.updateSizeAndPosition();
+
+      // Shade fade-in, then container fade-in.
+      this._fade(this.$shade!, 'in', SHADE_FX_DURATION, 'shade', () => {
+        this._fade(this.$container!, 'in', FX_DURATION, 'container', () => {
+          this.updateSizeAndPosition();
+          setFocusWithin(this.$container!);
+          this.onFadeIn();
+        });
+      });
+
+      if (this.settings!.hideOnShadeClick) {
+        this.addListener(this.$shade!, 'click', 'hide');
+      }
+
+      // Focus trap.
+      trapFocusWithin(this.$container);
+
+      this.addListener(win, 'resize', '_handleWindowResize');
+    }
+
+    this.enable();
+
+    if (!this.visible) {
+      this.visible = true;
+      Modal.visibleModal = this;
+
+      const manager = getUiLayerManager();
+      manager?.addLayer(this.$container ?? undefined);
+      hideModalBackgroundLayers();
+
+      if (this.settings!.hideOnEsc) {
+        manager?.registerShortcut(ESC_KEY, () => {
+          this.trigger('escape');
+          this.hide();
+        });
+      }
+
+      bod.classList.add('no-scroll');
+      this.onShow();
+    }
+  }
+
+  /**
+   * Hook called when the modal is shown: emits the `show` event and invokes the
+   * `onShow` setting. Override to react to showing (call `super.onShow()` to
+   * preserve the event + callback).
+   */
+  onShow(): void {
+    this.trigger('show');
+    this.settings!.onShow();
+  }
+
+  /** Show the modal immediately, skipping the fade animation. */
+  quickShow(): void {
+    this.show();
+
+    if (this.$container) {
+      this._cancelAnim('container');
+      this.$container.style.display = 'block';
+      this.$container.style.opacity = '1';
+
+      this._cancelAnim('shade');
+      this.$shade!.style.display = 'block';
+      this.$shade!.style.opacity = '1';
+    }
+  }
+
+  /**
+   * Hide the modal: fade out the container and shade, release the focus trap,
+   * pop the UI layer, restore background ARIA, emit `hide` (and later
+   * `fadeOut`), and restore focus to the trigger element shortly after. No-op
+   * if not currently visible.
+   *
+   * @param ev - The triggering DOM event, if any; its propagation is stopped.
+   */
+  hide(ev?: Event): void {
+    if (!this.visible) {
+      return;
+    }
+
+    this.disable();
+
+    if (ev) {
+      ev.stopPropagation();
+    }
+
+    if (this.$container) {
+      this._cancelAnim('container');
+      this._fade(this.$container, 'out', FX_DURATION, 'container');
+
+      this._cancelAnim('shade');
+      this._fade(this.$shade!, 'out', FX_DURATION, 'shade', () => {
+        this.onFadeOut();
+      });
+
+      if (this.settings!.hideOnShadeClick) {
+        this.removeListener(this.$shade!, 'click');
+      }
+
+      releaseFocusWithin(this.$container);
+      this.removeListener(win, 'resize');
+    }
+
+    this.visible = false;
+    bod.classList.remove('no-scroll');
+    Modal.visibleModal = null;
+
+    const manager = getUiLayerManager();
+    manager?.removeLayer();
+    resetModalBackgroundLayerVisibility();
+    this.onHide();
+
+    setTimeout(() => {
+      this._restoreTriggerFocus();
+    }, 200);
+  }
+
+  /**
+   * Hook called when the modal is hidden: emits the `hide` event and invokes the
+   * `onHide` setting. Override to react to hiding (call `super.onHide()` to
+   * preserve the event + callback).
+   */
+  onHide(): void {
+    this.trigger('hide');
+    this.settings!.onHide();
+  }
+
+  /** Hide the modal immediately, skipping the fade animation. */
+  quickHide(): void {
+    this.hide();
+
+    if (this.$container) {
+      this._cancelAnim('container');
+      this.$container.style.opacity = '0';
+      this.$container.style.display = 'none';
+
+      this._cancelAnim('shade');
+      this.$shade!.style.opacity = '0';
+      this.$shade!.style.display = 'none';
+
+      this.onFadeOut();
+    }
+  }
+
+  /**
+   * Recompute the modal's width, height, and centered position so it fits within
+   * the viewport (honoring `minGutter` and {@link desiredWidth} /
+   * {@link desiredHeight}), then emit `updateSizeAndPosition`. Called
+   * automatically on show and window resize; call it manually after changing the
+   * modal's content.
+   */
+  updateSizeAndPosition(): void {
+    if (!this.$container) {
+      return;
+    }
+
+    const c = this.$container;
+
+    // Reset sizing, then measure.
+    c.style.width = this.desiredWidth
+      ? `${Math.max(this.desiredWidth, 200)}px`
+      : '';
+    c.style.height = this.desiredHeight
+      ? `${Math.max(this.desiredHeight, 200)}px`
+      : '';
+    c.style.minWidth = '';
+    c.style.minHeight = '';
+
+    // Width first so height can adjust for the width.
+    const windowWidth = window.innerWidth;
+    const width = Math.min(
+      this.getWidth(),
+      windowWidth - this.settings!.minGutter * 2
+    );
+
+    c.style.width = `${width}px`;
+    c.style.minWidth = `${width}px`;
+    c.style.left = `${Math.round((windowWidth - width) / 2)}px`;
+
+    // Now the height.
+    const windowHeight = window.innerHeight;
+    const height = Math.min(
+      this.getHeight(),
+      windowHeight - this.settings!.minGutter * 2
+    );
+
+    c.style.height = `${height}px`;
+    c.style.minHeight = `${height}px`;
+    c.style.top = `${Math.round((windowHeight - height) / 2)}px`;
+
+    this.trigger('updateSizeAndPosition');
+  }
+
+  /**
+   * Hook called after the fade-in completes: emits `fadeIn` and invokes the
+   * `onFadeIn` setting. Override and call `super.onFadeIn()` to extend.
+   */
+  onFadeIn(): void {
+    this.trigger('fadeIn');
+    this.settings!.onFadeIn();
+  }
+
+  /**
+   * Hook called after the fade-out completes: emits `fadeOut` and invokes the
+   * `onFadeOut` setting. Override and call `super.onFadeOut()` to extend.
+   */
+  onFadeOut(): void {
+    this.trigger('fadeOut');
+    this.settings!.onFadeOut();
+  }
+
+  /**
+   * Measure the container's rendered height (px), temporarily displaying it if
+   * hidden.
+   *
+   * @returns The container's `offsetHeight`.
+   * @throws If the container has not been set.
+   */
+  getHeight(): number {
+    if (!this.$container) {
+      throw 'Attempted to get the height of a modal whose container has not been set.';
+    }
+
+    const hidden = !this.visible;
+    if (hidden) {
+      this.$container.style.display = 'block';
+    }
+
+    const height = this.$container.offsetHeight;
+
+    if (hidden) {
+      this.$container.style.display = 'none';
+    }
+
+    return height;
+  }
+
+  /**
+   * Measure the container's rendered width (px), temporarily displaying it if
+   * hidden.
+   *
+   * @returns The container's `offsetWidth` (+1px, matching legacy Chrome parity).
+   * @throws If the container has not been set.
+   */
+  getWidth(): number {
+    if (!this.$container) {
+      throw 'Attempted to get the width of a modal whose container has not been set.';
+    }
+
+    const hidden = !this.visible;
+    if (hidden) {
+      this.$container.style.display = 'block';
+    }
+
+    // Chrome might be 1px shy here for some reason (legacy parity).
+    const width = this.$container.offsetWidth + 1;
+
+    if (hidden) {
+      this.$container.style.display = 'none';
+    }
+
+    return width;
+  }
+
+  /**
+   * Destroy the modal: remove its container and shade from the DOM, drop it from
+   * {@link Modal.instances} (and clear {@link Modal.visibleModal} if it was the
+   * visible one), then run the base teardown (emits `destroy`, removes all
+   * listeners). Override and call `super.destroy()` to clean up extra state.
+   */
+  override destroy(): void {
+    this.dragger?.destroy();
+    this.resizeDragger?.destroy();
+
+    if (this.$container) {
+      containerModals.delete(this.$container);
+      this.$container.remove();
+    }
+
+    if (this.$shade) {
+      this.$shade.remove();
+    }
+
+    Modal.instances = Modal.instances.filter((o) => o !== this);
+
+    if (Modal.visibleModal === this) {
+      Modal.visibleModal = null;
+    }
+
+    super.destroy();
+  }
+
+  // --- Internals ------------------------------------------------------------
+
+  private _handleWindowResize(ev: Event): void {
+    // Ignore propagated resize events.
+    if (ev.target === window) {
+      this.updateSizeAndPosition();
+    }
+  }
+
+  /** Resize drag start: snapshot the current dimensions. */
+  private _handleResizeStart(): void {
+    this.resizeStartWidth = this.getWidth();
+    this.resizeStartHeight = this.getHeight();
+  }
+
+  /**
+   * Resize drag: grow/shrink symmetrically from the snapshot by 2× the pointer
+   * delta (RTL mirrors the horizontal direction), then re-center.
+   */
+  private _handleResize(): void {
+    if (globals.ltr) {
+      this.desiredWidth =
+        this.resizeStartWidth! + this.resizeDragger!.mouseDistX! * 2;
+    } else {
+      this.desiredWidth =
+        this.resizeStartWidth! - this.resizeDragger!.mouseDistX! * 2;
+    }
+    this.desiredHeight =
+      this.resizeStartHeight! + this.resizeDragger!.mouseDistY! * 2;
+    this.updateSizeAndPosition();
+  }
+
+  /**
+   * Restore focus to the trigger element after a hide (legacy behavior).
+   */
+  private _restoreTriggerFocus(): void {
+    let target: FocusTarget =
+      this.$triggerElement ?? this.settings!.triggerElement;
+
+    if (typeof target === 'function') {
+      target = target();
+    }
+
+    let el: Element | null = (target as Element | null) ?? null;
+
+    // If the trigger is hidden, try its disclosure-menu controller.
+    if (el && isElementHidden(el)) {
+      const disclosure = el.closest('.menu--disclosure');
+      if (disclosure && disclosure.id) {
+        el = document.querySelector(`[aria-controls="${disclosure.id}"]`);
+      } else {
+        el = null;
+      }
+    }
+
+    if (el && el instanceof HTMLElement) {
+      el.focus();
+    } else {
+      console.warn(
+        'There is no trigger element set for this modal. Set one with modal.$triggerElement = ...'
+      );
+    }
+  }
+
+  /**
+   * Fade an element in or out with the Web Animations API.
+   *
+   * Gated on `prefersReducedMotion` (and on environments lacking
+   * `element.animate`, e.g. happy-dom): in those cases the end state is applied
+   * immediately and the completion callback runs synchronously, so tests are
+   * deterministic and reduced-motion users get an instant transition while real
+   * browsers still animate.
+   */
+  private _fade(
+    el: HTMLElement,
+    direction: 'in' | 'out',
+    duration: number,
+    track: 'container' | 'shade',
+    complete?: ModalCallback
+  ): void {
+    const finalOpacity = direction === 'in' ? '1' : '0';
+
+    if (direction === 'in') {
+      el.style.display = 'block';
+    }
+
+    const finalize = (): void => {
+      el.style.opacity = finalOpacity;
+      if (direction === 'out') {
+        el.style.display = 'none';
+      }
+      this._setAnim(track, null);
+      complete?.();
+    };
+
+    // Feature-detect WAAPI; fall back to an immediate-complete path otherwise.
+    // happy-dom does not implement `element.animate`, so this keeps tests
+    // deterministic while letting real browsers animate.
+    if (prefersReducedMotion() || typeof el.animate !== 'function') {
+      finalize();
+      return;
+    }
+
+    el.style.opacity = direction === 'in' ? '0' : '1';
+    const anim = el.animate(
+      [
+        {opacity: direction === 'in' ? 0 : 1},
+        {opacity: direction === 'in' ? 1 : 0},
+      ],
+      {duration, fill: 'forwards'}
+    );
+    this._setAnim(track, anim);
+    anim.onfinish = finalize;
+    anim.oncancel = (): void => {
+      this._setAnim(track, null);
+    };
+  }
+
+  private _setAnim(track: 'container' | 'shade', anim: Animation | null): void {
+    if (track === 'container') {
+      this._containerAnim = anim;
+    } else {
+      this._shadeAnim = anim;
+    }
+  }
+
+  /** Cancel the tracked animation for a target (legacy `.velocity('stop')`). */
+  private _cancelAnim(track: 'container' | 'shade'): void {
+    const anim = track === 'container' ? this._containerAnim : this._shadeAnim;
+    if (anim) {
+      anim.cancel();
+    }
+    this._setAnim(track, null);
+  }
+}
+
+function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    !(val instanceof Element) &&
+    (Object.getPrototypeOf(val) === Object.prototype ||
+      Object.getPrototypeOf(val) === null)
+  );
+}
+
+/**
+ * Native replacement for jQuery `:hidden`: an element is hidden if it has no
+ * rendered boxes. In layout-less environments (happy-dom) this falls back to a
+ * computed-style check.
+ */
+function isElementHidden(el: Element): boolean {
+  const html = el as HTMLElement;
+  if (html.offsetWidth || html.offsetHeight || el.getClientRects().length) {
+    return false;
+  }
+  const style = window.getComputedStyle(el);
+  return style.display === 'none' || style.visibility === 'hidden';
+}
+
+export default Modal;
diff --git a/packages/craftcms-garnish/src/types.ts b/packages/craftcms-garnish/src/types.ts
new file mode 100644
index 00000000000..feff5c27710
--- /dev/null
+++ b/packages/craftcms-garnish/src/types.ts
@@ -0,0 +1,24 @@
+/**
+ * Shared Garnish core types.
+ */
+
+/** Base settings shape. Subclasses extend this with their own typed settings. */
+export interface GarnishBaseSettings {
+  [key: string]: unknown;
+}
+
+/**
+ * Anything `addListener` / the DOM-listener registry will accept as an element
+ * argument. jQuery is intentionally absent; the compat layer coerces jQuery
+ * collections into one of these before calling core.
+ */
+export type ElementInput =
+  | EventTarget
+  | EventTarget[]
+  | NodeListOf<Element>
+  | string
+  | null
+  | undefined;
+
+/** Generic constructor type used by the class-level event bus. */
+export type Constructor<T = object> = abstract new (...args: any[]) => T;
diff --git a/packages/craftcms-garnish/src/utils/animation.ts b/packages/craftcms-garnish/src/utils/animation.ts
new file mode 100644
index 00000000000..bb1c0dc05eb
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/animation.ts
@@ -0,0 +1,143 @@
+/**
+ * Animation / scroll utilities (jQuery-free; Velocity removed).
+ *
+ * `shake` uses the Web Animations API; `scrollContainerToElement` uses manual
+ * `scrollTop` math. Both respect `prefers-reduced-motion`.
+ */
+
+import {SHAKE_STEP_DURATION, SHAKE_STEPS} from '../constants';
+import {doc, win} from '../globals';
+import {getScrollParent} from './scroll';
+
+/** Re-export of the native RAF (vendor prefixes are long dead). */
+export const requestAnimationFrame: typeof window.requestAnimationFrame =
+  window.requestAnimationFrame.bind(window);
+
+export const cancelAnimationFrame: typeof window.cancelAnimationFrame =
+  window.cancelAnimationFrame.bind(window);
+
+/** Whether the user prefers reduced motion. */
+export function prefersReducedMotion(): boolean {
+  const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+  // Legacy returns true if the query is unavailable.
+  return !mediaQuery || mediaQuery.matches;
+}
+
+/**
+ * `0` if the user prefers reduced motion, otherwise the given duration.
+ */
+export function getUserPreferredAnimationDuration(
+  duration: number | string
+): number | string {
+  return prefersReducedMotion() ? 0 : duration;
+}
+
+/**
+ * Scrolls a container so that an element within it is in view.
+ *
+ * Parity with legacy `scrollContainerToElement`, minus Velocity (uses
+ * instant `scrollTop` assignment / `window.scrollTo`).
+ */
+export function scrollContainerToElement(
+  container: Element | Window,
+  elem?: Element
+): void {
+  let target: Element;
+  let scrollTarget: Element | Window;
+
+  if (elem === undefined) {
+    // Single-arg form: container is actually the element; find its scroll parent.
+    target = container as Element;
+    scrollTarget = getScrollParent(target);
+  } else {
+    scrollTarget = container;
+    target = elem;
+  }
+
+  // Normalize <html>/document to window.
+  if (
+    scrollTarget instanceof Element &&
+    (scrollTarget.nodeName === 'HTML' || scrollTarget === doc.documentElement)
+  ) {
+    scrollTarget = win;
+  }
+  if ((scrollTarget as unknown) === doc) {
+    scrollTarget = win;
+  }
+
+  const isWindow = scrollTarget === win;
+  const scrollTop = isWindow
+    ? window.scrollY
+    : (scrollTarget as Element).scrollTop;
+  const elemOffsetTop = target.getBoundingClientRect().top + window.scrollY;
+
+  let elemScrollOffset: number;
+  if (isWindow) {
+    elemScrollOffset = elemOffsetTop - scrollTop;
+  } else {
+    const containerOffsetTop =
+      (scrollTarget as Element).getBoundingClientRect().top + window.scrollY;
+    elemScrollOffset = elemOffsetTop - containerOffsetTop;
+  }
+
+  let targetScrollTop: number | false = false;
+
+  if (elemScrollOffset < 0) {
+    targetScrollTop = scrollTop + elemScrollOffset - 10;
+  } else {
+    const elemHeight = target.getBoundingClientRect().height;
+    const containerHeight = isWindow
+      ? window.innerHeight
+      : (scrollTarget as Element).clientHeight;
+
+    if (elemScrollOffset + elemHeight > containerHeight) {
+      targetScrollTop =
+        scrollTop + (elemScrollOffset - (containerHeight - elemHeight)) + 10;
+    }
+  }
+
+  if (targetScrollTop !== false) {
+    if (isWindow) {
+      window.scrollTo({top: targetScrollTop});
+    } else {
+      (scrollTarget as Element).scrollTop = targetScrollTop;
+    }
+  }
+}
+
+/**
+ * Shakes an element by animating a CSS property back and forth.
+ *
+ * Rewritten with the Web Animations API (Velocity removed). Respects
+ * `prefers-reduced-motion` (no-op). Mirrors the legacy 10-step amplitude ramp.
+ *
+ * @param elem The element to shake.
+ * @param prop The CSS property to adjust (default `'margin-left'`).
+ */
+export function shake(elem: HTMLElement, prop = 'margin-left'): void {
+  if (prefersReducedMotion()) {
+    return;
+  }
+
+  let startingPoint = parseInt(
+    window.getComputedStyle(elem).getPropertyValue(prop),
+    10
+  );
+  if (Number.isNaN(startingPoint)) {
+    startingPoint = 0;
+  }
+
+  // Build the keyframe ramp: same offsets the legacy setTimeout loop produced.
+  const keyframes: Keyframe[] = [];
+  for (let i = 0; i <= SHAKE_STEPS; i++) {
+    const value = startingPoint + (i % 2 ? -1 : 1) * (10 - i);
+    keyframes.push({[prop]: `${value}px`});
+  }
+
+  if (typeof elem.animate === 'function') {
+    elem.animate(keyframes, {
+      duration: SHAKE_STEP_DURATION * SHAKE_STEPS,
+      easing: 'linear',
+    });
+  }
+}
diff --git a/packages/craftcms-garnish/src/utils/aria.ts b/packages/craftcms-garnish/src/utils/aria.ts
new file mode 100644
index 00000000000..86110e3a936
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/aria.ts
@@ -0,0 +1,124 @@
+/**
+ * ARIA / modal-background utilities (jQuery-free).
+ */
+
+import {
+  JS_ARIA_CLASS,
+  JS_ARIA_FALSE_CLASS,
+  JS_ARIA_TRUE_CLASS,
+} from '../constants';
+import {getUiLayerManager} from '../managers/registry';
+
+/**
+ * Add the modal ARIA + role attributes (`aria-modal="true"`, `role="dialog"`) to
+ * a container. Called by {@link Modal} when its container is set.
+ *
+ * @param container - The modal container element.
+ */
+export function addModalAttributes(container: Element): void {
+  container.setAttribute('aria-modal', 'true');
+  container.setAttribute('role', 'dialog');
+}
+
+/** Whether an element is a `<script>` or `<style>`. */
+export function isScriptOrStyleElement(element: Element): boolean {
+  return element.tagName === 'SCRIPT' || element.tagName === 'STYLE';
+}
+
+/** Whether an element carries one of the JS-ARIA bookkeeping classes. */
+export function hasJsAriaClass(element: Element): boolean {
+  return (
+    element.classList.contains(JS_ARIA_CLASS) ||
+    element.classList.contains(JS_ARIA_FALSE_CLASS) ||
+    element.classList.contains(JS_ARIA_TRUE_CLASS)
+  );
+}
+
+/**
+ * Apply `aria-hidden="true"` to an element, recording its prior value via a
+ * bookkeeping class so {@link resetModalBackgroundLayerVisibility} can restore
+ * it exactly.
+ *
+ * @param element - The element to hide from assistive technology.
+ */
+export function ariaHide(element: Element): void {
+  const prior = element.getAttribute('aria-hidden');
+
+  if (!prior) {
+    element.classList.add(JS_ARIA_CLASS);
+  } else if (prior === 'false') {
+    element.classList.add(JS_ARIA_FALSE_CLASS);
+  } else if (prior === 'true') {
+    element.classList.add(JS_ARIA_TRUE_CLASS);
+  }
+
+  element.setAttribute('aria-hidden', 'true');
+}
+
+/**
+ * Hide every immediate child of `<body>` from assistive technology (via
+ * {@link ariaHide}), except `#notifications`, the topmost UI layer's container,
+ * and `<script>`/`<style>` elements. Used by {@link Modal} on show to background
+ * the rest of the page.
+ */
+export function hideModalBackgroundLayers(): void {
+  const manager = getUiLayerManager();
+  const topmostLayer = manager?.currentLayer.$container ?? null;
+
+  for (const child of Array.from(document.body.children)) {
+    if (child.id === 'notifications') {
+      continue;
+    }
+
+    // If element is the topmost layer or already hidden, do nothing.
+    if (hasJsAriaClass(child) || child === topmostLayer) {
+      continue;
+    }
+
+    if (!isScriptOrStyleElement(child)) {
+      ariaHide(child);
+    }
+  }
+}
+
+/**
+ * Reverse {@link hideModalBackgroundLayers}. If another modal layer is still
+ * open, only that layer is made accessible again; otherwise every element
+ * previously hidden has its prior `aria-hidden` state restored. Used by
+ * {@link Modal} on hide.
+ */
+export function resetModalBackgroundLayerVisibility(): void {
+  const manager = getUiLayerManager();
+  const highestModalLayer = manager?.highestModalLayer;
+
+  const hiddenLayerClasses = [
+    JS_ARIA_CLASS,
+    JS_ARIA_TRUE_CLASS,
+    JS_ARIA_FALSE_CLASS,
+  ];
+
+  // If there is another modal, make it accessible to AT and stop.
+  if (highestModalLayer && highestModalLayer.$container) {
+    const container = highestModalLayer.$container;
+    container.classList.remove(...hiddenLayerClasses);
+    container.removeAttribute('aria-hidden');
+    return;
+  }
+
+  // Otherwise, restore every element we hid.
+  const selector = hiddenLayerClasses.map((name) => `.${name}`).join(', ');
+  const hiddenElements = document.querySelectorAll(selector);
+
+  for (const el of Array.from(hiddenElements)) {
+    if (el.classList.contains(JS_ARIA_CLASS)) {
+      el.classList.remove(JS_ARIA_CLASS);
+      el.removeAttribute('aria-hidden');
+    } else if (el.classList.contains(JS_ARIA_FALSE_CLASS)) {
+      el.classList.remove(JS_ARIA_FALSE_CLASS);
+      el.setAttribute('aria-hidden', 'false');
+    } else if (el.classList.contains(JS_ARIA_TRUE_CLASS)) {
+      el.classList.remove(JS_ARIA_TRUE_CLASS);
+      el.setAttribute('aria-hidden', 'true');
+    }
+  }
+}
diff --git a/packages/craftcms-garnish/src/utils/dom.ts b/packages/craftcms-garnish/src/utils/dom.ts
new file mode 100644
index 00000000000..12cff613dad
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/dom.ts
@@ -0,0 +1,151 @@
+/**
+ * DOM utilities (jQuery-free).
+ *
+ * `coerceElements` is the native replacement for jQuery's `$(elem)` collection
+ * coercion, used throughout the DOM-listener registry and helpers.
+ */
+
+import type {ElementInput} from '../types';
+import {globals, win} from '../globals';
+
+/**
+ * Coerce any {@link ElementInput} into a flat array of `EventTarget`s — the
+ * native replacement for jQuery's permissive `$(x)` collection coercion.
+ *
+ *  - a CSS selector string → `querySelectorAll`
+ *  - a single node / window / document → `[node]`
+ *  - an array / NodeList → flattened (nulls dropped)
+ *  - null/undefined → `[]`
+ *
+ * @param input - The value to coerce.
+ * @returns A flat array of event targets.
+ */
+export function coerceElements(input: ElementInput): EventTarget[] {
+  if (input === null || input === undefined) {
+    return [];
+  }
+
+  if (typeof input === 'string') {
+    return Array.from(document.querySelectorAll(input));
+  }
+
+  // Array or NodeList (array-like with length, not an EventTarget itself).
+  if (Array.isArray(input)) {
+    return input.filter((el): el is EventTarget => el != null);
+  }
+
+  if (
+    typeof (input as NodeListOf<Element>).length === 'number' &&
+    typeof (input as EventTarget).addEventListener !== 'function'
+  ) {
+    return Array.from(input as NodeListOf<Element>).filter(
+      (el): el is Element => el != null
+    );
+  }
+
+  // Single EventTarget (Element, window, document, ...).
+  return [input as EventTarget];
+}
+
+/** First resolved element of an `ElementInput`, or `undefined`. */
+export function getElement(input: ElementInput): EventTarget | undefined {
+  return coerceElements(input)[0];
+}
+
+/**
+ * Returns whether an element has an attribute (present and not literally
+ * `"false"`). Legacy checked `$(elem).attr(attr)` for `!== undefined && !== false`;
+ * since DOM attributes are always strings, only a missing attribute is falsy.
+ */
+export function hasAttr(elem: Element, attr: string): boolean {
+  return elem.hasAttribute(attr);
+}
+
+/**
+ * Offset of an element relative to the document, adjusted for a non-window
+ * scroll container (parity with legacy `getOffset`).
+ */
+export function getOffset(elem: Element): {top: number; left: number} {
+  const rect = elem.getBoundingClientRect();
+  const offset = {
+    top: rect.top + window.scrollY,
+    left: rect.left + window.scrollX,
+  };
+
+  if (globals.scrollContainer !== win) {
+    const container = globals.scrollContainer as Element;
+    if (typeof container.scrollTop === 'number') {
+      offset.top += container.scrollTop;
+      offset.left += container.scrollLeft;
+    }
+  }
+
+  return offset;
+}
+
+/**
+ * Border-box width of an element (native replacement for jQuery's
+ * `.outerWidth()`). Reserved for the downstream `Drag` port, which reads
+ * `this.$targetItem.outerWidth()`.
+ */
+export function getOuterWidth(elem: HTMLElement): number {
+  return elem.offsetWidth;
+}
+
+/**
+ * Border-box height of an element (native replacement for jQuery's
+ * `.outerHeight()`). Reserved for the downstream `Drag` port.
+ */
+export function getOuterHeight(elem: HTMLElement): number {
+  return elem.offsetHeight;
+}
+
+/**
+ * Whether an element's bounding box contains a page-coordinate point.
+ * Uses page coords (adds `scrollX/Y`) to match legacy `hitTest`.
+ */
+export function hitTest(x: number, y: number, elem: Element): boolean {
+  const rect = elem.getBoundingClientRect();
+  const x1 = rect.left + window.scrollX;
+  const y1 = rect.top + window.scrollY;
+  const x2 = x1 + rect.width;
+  const y2 = y1 + rect.height;
+
+  return x >= x1 && x < x2 && y >= y1 && y < y2;
+}
+
+/** Whether the cursor (mouse event page coords) is over an element. */
+export function isCursorOver(
+  ev: {pageX: number; pageY: number},
+  elem: Element
+): boolean {
+  return hitTest(ev.pageX, ev.pageY, elem);
+}
+
+const TEXT_STYLE_PROPS = [
+  'fontFamily',
+  'fontSize',
+  'fontWeight',
+  'letterSpacing',
+  'lineHeight',
+  'textAlign',
+  'textIndent',
+  'whiteSpace',
+  'wordSpacing',
+  'wordWrap',
+] as const;
+
+/** Copies the 10 font/text CSS props from one element to another. */
+export function copyTextStyles(source: HTMLElement, target: HTMLElement): void {
+  const computed = window.getComputedStyle(source);
+  for (const prop of TEXT_STYLE_PROPS) {
+    target.style.setProperty(
+      toKebabCase(prop),
+      computed.getPropertyValue(toKebabCase(prop))
+    );
+  }
+}
+
+function toKebabCase(prop: string): string {
+  return prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
diff --git a/packages/craftcms-garnish/src/utils/env.ts b/packages/craftcms-garnish/src/utils/env.ts
new file mode 100644
index 00000000000..cea65793f21
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/env.ts
@@ -0,0 +1,99 @@
+/**
+ * Environment / input utilities.
+ */
+
+import {PRIMARY_CLICK} from '../constants';
+
+// Memoized mobile-browser detection results.
+let _isMobileBrowser: boolean | null = null;
+let _isMobileOrTabletBrowser: boolean | null = null;
+
+/**
+ * Whether this is a mobile browser (UA sniffing, ported verbatim from legacy).
+ * Detection regex courtesy of http://detectmobilebrowsers.com (last updated 2014).
+ *
+ * @deprecated UA sniffing; prefer pointer/feature media queries. Kept for
+ * call-site parity.
+ * @param detectTablets Also treat tablets as mobile.
+ */
+export function isMobileBrowser(detectTablets = false): boolean {
+  if (detectTablets) {
+    if (_isMobileOrTabletBrowser === null) {
+      _isMobileOrTabletBrowser = detect(true);
+    }
+    return _isMobileOrTabletBrowser;
+  }
+
+  if (_isMobileBrowser === null) {
+    _isMobileBrowser = detect(false);
+  }
+  return _isMobileBrowser;
+}
+
+function detect(detectTablets: boolean): boolean {
+  const a: string =
+    navigator.userAgent ||
+    navigator.vendor ||
+    (window as unknown as {opera?: string}).opera ||
+    '';
+
+  return (
+    new RegExp(
+      '(android|bbd+|meego).+mobile|avantgo|bada/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|mobile.+firefox|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)/|plucker|pocket|psp|series(4|6)0|symbian|treo|up.(browser|link)|vodafone|wap|windows ce|xda|xiino' +
+        (detectTablets ? '|android|ipad|playbook|silk' : ''),
+      'i'
+    ).test(a) ||
+    /1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s\-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|\-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw\-(n|u)|c55\/|capi|ccwa|cdm\-|cell|chtm|cldc|cmd\-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc\-s|devi|dica|dmob|do(c|p)o|ds(12|\-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(\-|_)|g1 u|g560|gene|gf\-5|g\-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd\-(m|p|t)|hei\-|hi(pt|ta)|hp( i|ip)|hs\-c|ht(c(\-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i\-(20|go|ma)|i230|iac( |\-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc\-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|\-[a-w])|libw|lynx|m1\-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m\-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(\-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)\-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|\-([1-8]|c))|phil|pire|pl(ay|uc)|pn\-2|po(ck|rt|se)|prox|psio|pt\-g|qa\-a|qc(07|12|21|32|60|\-[2-7]|i\-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h\-|oo|p\-)|sdk\/|se(c(\-|0|1)|47|mc|nd|ri)|sgh\-|shar|sie(\-|m)|sk\-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h\-|v\-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl\-|tdg\-|tel(i|m)|tim\-|t\-mo|to(pl|sh)|ts(70|m\-|m3|m5)|tx\-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|\-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(\-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas\-|your|zeto|zte\-/i.test(
+      a.substring(0, 4)
+    )
+  );
+}
+
+/**
+ * Whether a mouse event is a primary click (no Ctrl/Meta).
+ *
+ * Reads `MouseEvent.button === 0` (modern) but also honors the legacy
+ * `event.which === 1` shape for compat.
+ */
+export function isPrimaryClick(
+  ev:
+    | MouseEvent
+    | {which?: number; button?: number; ctrlKey?: boolean; metaKey?: boolean}
+): boolean {
+  const which = (ev as {which?: number}).which;
+  const isPrimary =
+    which !== undefined
+      ? which === PRIMARY_CLICK
+      : (ev as MouseEvent).button === 0;
+  return isPrimary && !ev.ctrlKey && !ev.metaKey;
+}
+
+/**
+ * Whether the platform's "Ctrl" key (⌘ on Mac) is pressed for an event.
+ */
+export function isCtrlKeyPressed(ev: {
+  metaKey?: boolean;
+  ctrlKey?: boolean;
+}): boolean {
+  const platform = (navigator as unknown as {platform?: string}).platform ?? '';
+  if (platform.match(/Mac/)) {
+    return !!ev.metaKey;
+  }
+  return !!ev.ctrlKey;
+}
+
+/** The body's real scrollTop, clamped (discards Safari banding). */
+export function getBodyScrollTop(): number {
+  let scrollTop = document.body.scrollTop;
+
+  if (scrollTop < 0) {
+    scrollTop = 0;
+  } else {
+    const maxScrollTop = document.body.offsetHeight - window.innerHeight;
+    if (scrollTop > maxScrollTop) {
+      scrollTop = maxScrollTop;
+    }
+  }
+
+  return scrollTop;
+}
diff --git a/packages/craftcms-garnish/src/utils/focus.ts b/packages/craftcms-garnish/src/utils/focus.ts
new file mode 100644
index 00000000000..b229414575b
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/focus.ts
@@ -0,0 +1,167 @@
+/**
+ * Focus management utilities (jQuery-free).
+ */
+
+import {TAB_KEY} from '../constants';
+import {
+  getFocusableElements,
+  isKeyboardFocusable,
+  isVisible,
+} from './focusable';
+
+/**
+ * Whether keyboard focus currently lives inside (but is not) a container.
+ *
+ * @param container - The container to test.
+ * @returns `true` if the active element is a descendant of `container`.
+ */
+export function focusIsInside(container: Element): boolean {
+  const active = document.activeElement;
+  return active !== null && container.contains(active) && active !== container;
+}
+
+/**
+ * The first focusable element inside a container, or `null` if none.
+ *
+ * @param container - The container to search.
+ */
+export function firstFocusableElement(container: Element): HTMLElement | null {
+  return getFocusableElements(container)[0] ?? null;
+}
+
+/**
+ * All keyboard-focusable (Tab-reachable) elements inside a container, in
+ * document order. Excludes `tabindex="-1"` elements.
+ *
+ * @param container - The container to search.
+ */
+export function getKeyboardFocusableElements(
+  container: Element
+): HTMLElement[] {
+  return getFocusableElements(container).filter((el) =>
+    isKeyboardFocusable(el)
+  );
+}
+
+/**
+ * The currently focused element, or `null`.
+ *
+ * @returns `document.activeElement`.
+ * @remarks The modern core returns a native element; the compat layer wraps it
+ *   in a jQuery `:focus` collection to match the legacy shape.
+ */
+export function getFocusedElement(): Element | null {
+  return document.activeElement;
+}
+
+// Tracks the `keydown` handler bound by `trapFocusWithin` per container so
+// `releaseFocusWithin` can remove exactly it (replaces the `.focus-trap` namespace).
+const focusTrapHandlers = new WeakMap<Element, (ev: KeyboardEvent) => void>();
+
+/**
+ * Trap keyboard focus within a container: tabbing past the last focusable
+ * element wraps to the first, and Shift-Tab past the first wraps to the last.
+ * Replaces any trap previously installed on the same container.
+ *
+ * Pair with {@link releaseFocusWithin} to remove the trap (e.g. when a modal
+ * closes).
+ *
+ * @param container - The element to confine Tab navigation within.
+ */
+export function trapFocusWithin(container: Element): void {
+  releaseFocusWithin(container);
+
+  const handler = (ev: KeyboardEvent): void => {
+    if (ev.keyCode !== TAB_KEY) {
+      return;
+    }
+
+    const focusable = getFocusableElements(container);
+    if (focusable.length === 0) {
+      return;
+    }
+
+    const index = focusable.indexOf(ev.target as HTMLElement);
+
+    if (index === 0 && ev.shiftKey) {
+      ev.preventDefault();
+      ev.stopPropagation();
+      focusable[focusable.length - 1]!.focus();
+    } else if (index === focusable.length - 1 && !ev.shiftKey) {
+      ev.preventDefault();
+      ev.stopPropagation();
+      focusable[0]!.focus();
+    }
+  };
+
+  container.addEventListener('keydown', handler as EventListener);
+  focusTrapHandlers.set(container, handler);
+}
+
+/**
+ * Release a focus trap previously installed by {@link trapFocusWithin}. No-op if
+ * none is active on the container.
+ *
+ * @param container - The trapped container.
+ */
+export function releaseFocusWithin(container: Element): void {
+  const handler = focusTrapHandlers.get(container);
+  if (handler) {
+    container.removeEventListener('keydown', handler as EventListener);
+    focusTrapHandlers.delete(container);
+  }
+}
+
+/**
+ * Move focus to the first sensible focusable element within a container, or to
+ * the container itself (made focusable with `tabindex="-1"`) when none is
+ * suitable. No-op if focus is already inside.
+ *
+ * Skips `.checkbox` and `.prevent-autofocus` elements, and preserves the
+ * `.field:visible` heuristic from cms#15245: if the first focusable element
+ * isn't inside the first visible `.field`, autofocus is skipped in favor of the
+ * container. Used by {@link Modal} on show.
+ *
+ * @param container - The container to focus within.
+ */
+export function setFocusWithin(container: Element): void {
+  // Already contains focus? Do nothing.
+  if (
+    document.activeElement &&
+    container.contains(document.activeElement) &&
+    document.activeElement !== container
+  ) {
+    return;
+  }
+
+  // First focusable that isn't a .checkbox or .prevent-autofocus.
+  let firstFocusable: HTMLElement | null =
+    getFocusableElements(container).find(
+      (el) =>
+        !el.classList.contains('checkbox') &&
+        !el.classList.contains('prevent-autofocus')
+    ) ?? null;
+
+  // First *visible* `.field` in the container.
+  const firstVisibleField =
+    Array.from(container.querySelectorAll('.field')).find((el) =>
+      isVisible(el)
+    ) ?? null;
+
+  // The `.field` ancestor of our first focusable.
+  const focusableField = firstFocusable
+    ? firstFocusable.closest('.field')
+    : null;
+
+  // If the first visible field isn't the first focusable's field, bail on autofocus.
+  if (firstVisibleField !== focusableField) {
+    firstFocusable = null;
+  }
+
+  if (firstFocusable) {
+    firstFocusable.focus();
+  } else {
+    container.setAttribute('tabindex', '-1');
+    (container as HTMLElement).focus();
+  }
+}
diff --git a/packages/craftcms-garnish/src/utils/focusable.ts b/packages/craftcms-garnish/src/utils/focusable.ts
new file mode 100644
index 00000000000..5fc36e527e5
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/focusable.ts
@@ -0,0 +1,115 @@
+/**
+ * Native focusable-element matcher.
+ *
+ * The highest-risk reimplementation in the core: jQuery-UI's `:focusable` /
+ * `:tabbable` selectors have no built-in DOM equivalent. This models the
+ * well-known jQuery-UI algorithm closely to preserve behavior for focus traps
+ * and modal accessibility.
+ *
+ * Reference: jQuery-UI `focusable(element, hasTabindex)`:
+ *   - <a>/<area> with href, or any element with a tabindex, are focusable when visible.
+ *   - <input>/<select>/<textarea>/<button> are focusable when not disabled, visible,
+ *     and (for inputs) not an unchecked radio in a same-name group with no focusable member.
+ *   - everything else needs an explicit tabindex.
+ *   - all of the above also require visibility.
+ */
+
+/**
+ * Whether an element is visible.
+ *
+ * jQuery's `:visible` is "has layout boxes": `offsetWidth || offsetHeight ||
+ * getClientRects().length`, plus we additionally exclude `visibility:hidden`
+ * (jQuery-UI's `visible()` does this via the `visibility` check on the element
+ * and its ancestors).
+ */
+export function isVisible(el: Element): boolean {
+  const html = el as HTMLElement;
+
+  // `display:none` (on the element or an ancestor) yields no layout boxes.
+  const hasBoxes =
+    html.offsetWidth > 0 ||
+    html.offsetHeight > 0 ||
+    el.getClientRects().length > 0;
+
+  if (!hasBoxes) {
+    return false;
+  }
+
+  // `visibility:hidden`/`collapse` on the element or any ancestor hides it.
+  let node: Element | null = el;
+  while (node) {
+    const visibility = window.getComputedStyle(node).visibility;
+    if (visibility === 'hidden' || visibility === 'collapse') {
+      return false;
+    }
+    node = node.parentElement;
+  }
+
+  return true;
+}
+
+const FOCUSABLE_FORM_TAGS = new Set(['input', 'select', 'textarea', 'button']);
+
+/**
+ * Whether an element is focusable (visible + not disabled + naturally or
+ * explicitly focusable). Negative tabindex still counts as focusable here
+ * (it's only excluded for *keyboard* focus).
+ */
+export function isFocusable(el: Element): boolean {
+  if (!(el instanceof HTMLElement) && !(el instanceof SVGElement)) {
+    // areas are SVG-unrelated but covered below; restrict to real elements.
+  }
+
+  const nodeName = el.nodeName.toLowerCase();
+  const tabindexAttr = el.getAttribute('tabindex');
+  const hasTabindex = tabindexAttr !== null;
+  const tabindex = hasTabindex ? Number(tabindexAttr) : null;
+
+  let focusable: boolean;
+
+  if (nodeName === 'area') {
+    // <area> is focusable only when it has an href and its <map>/<img> is shown.
+    const area = el as HTMLAreaElement;
+    const hasHref = !!area.getAttribute('href');
+    if (!hasHref) {
+      return false;
+    }
+    focusable = true;
+  } else if (FOCUSABLE_FORM_TAGS.has(nodeName)) {
+    focusable = !(el as HTMLInputElement).disabled;
+  } else if (nodeName === 'a') {
+    // Links are focusable with an href, or if they carry a tabindex.
+    focusable = !!el.getAttribute('href') || hasTabindex;
+  } else {
+    // Everything else needs an explicit, numeric tabindex.
+    focusable = hasTabindex && !Number.isNaN(tabindex);
+  }
+
+  return focusable && isVisible(el);
+}
+
+/**
+ * Whether the element is focusable by keyboard — i.e. focusable AND not
+ * `tabindex="-1"` (matches legacy `isKeyboardFocusable`).
+ */
+export function isKeyboardFocusable(el: Element): boolean {
+  if (!isFocusable(el)) {
+    return false;
+  }
+  return el.getAttribute('tabindex') !== '-1';
+}
+
+/**
+ * All focusable elements **within** a container, in document order. Equivalent
+ * to legacy `$(container).find(':focusable')` (the container itself is not
+ * included, matching jQuery's `.find()`).
+ *
+ * @param container - The element to search.
+ * @returns The focusable descendants, in document order.
+ */
+export function getFocusableElements(container: Element): HTMLElement[] {
+  // `find` excludes the container itself; match jQuery's `.find()` semantics.
+  return Array.from(container.querySelectorAll<HTMLElement>('*')).filter((el) =>
+    isFocusable(el)
+  );
+}
diff --git a/packages/craftcms-garnish/src/utils/forms.ts b/packages/craftcms-garnish/src/utils/forms.ts
new file mode 100644
index 00000000000..889c5033cdc
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/forms.ts
@@ -0,0 +1,143 @@
+/**
+ * Form / POST-data utilities (jQuery-free).
+ */
+
+type InputLike = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**
+ * The beginning of an input's `name` with any `[brackets]` stripped.
+ */
+export function getInputBasename(elem: Element): string | null {
+  const name = elem.getAttribute('name');
+  if (name) {
+    return name.replace(/\[.*/, '');
+  }
+  return null;
+}
+
+/**
+ * An input's value as it would be POSTed.
+ *
+ * - Unchecked checkbox/radio → `null`.
+ * - A multi-value input whose name doesn't end in `[]` → only the last value.
+ * - A `<select>` whose value is null → `''` (compat wart: not `null`).
+ */
+export function getInputPostVal(input: Element): string | string[] | null {
+  const el = input as InputLike;
+  const type = el.getAttribute('type');
+
+  // Unchecked checkbox/radio?
+  if (type === 'checkbox' || type === 'radio') {
+    if ((el as HTMLInputElement).checked) {
+      return (el as HTMLInputElement).value;
+    }
+    return null;
+  }
+
+  // Read the value (multi-selects yield an array).
+  let val: string | string[] | null;
+  if (el.nodeName === 'SELECT' && (el as HTMLSelectElement).multiple) {
+    val = Array.from((el as HTMLSelectElement).selectedOptions).map(
+      (opt) => opt.value
+    );
+  } else {
+    val = el.value ?? null;
+  }
+
+  // Flatten array values whose input name doesn't end in "[]" (e.g. multi-select).
+  const name = el.getAttribute('name') ?? '';
+  if (Array.isArray(val) && name.slice(-2) !== '[]') {
+    if (val.length) {
+      return val[val.length - 1]!;
+    }
+    return null;
+  }
+
+  // A dropdown with a null value → empty string (consistent with element.value).
+  if (val === null && el.nodeName === 'SELECT') {
+    return '';
+  }
+
+  return val;
+}
+
+/**
+ * Inputs within a container.
+ *
+ * NOTE: the selector includes the bogus `text` tag from the legacy code (it
+ * matches nothing). Preserved verbatim as a documented compat wart.
+ */
+export function findInputs(container: Element): HTMLElement[] {
+  return Array.from(
+    container.querySelectorAll<HTMLElement>('input,text,textarea,select,button')
+  );
+}
+
+/**
+ * Serialize the inputs within a container to a flat POST data map, handling
+ * `name[]` array indexing (disabled inputs and `null`-valued inputs are
+ * skipped). The jQuery-free equivalent of the legacy `getPostData`.
+ *
+ * @param container - The element whose inputs to serialize.
+ * @returns A `name → value` map ready to POST.
+ */
+export function getPostData(container: Element): Record<string, string> {
+  const postData: Record<string, string> = {};
+  const arrayInputCounters: Record<string, number> = {};
+  const inputs = findInputs(container);
+
+  for (const input of inputs) {
+    if ((input as InputLike).disabled) {
+      continue;
+    }
+
+    let inputName = input.getAttribute('name');
+    if (!inputName) {
+      continue;
+    }
+
+    let inputVal = getInputPostVal(input);
+    if (inputVal === null) {
+      continue;
+    }
+
+    const isArrayInput = inputName.slice(-2) === '[]';
+    let croppedName = '';
+
+    if (isArrayInput) {
+      croppedName = inputName.substring(0, inputName.length - 2);
+      if (arrayInputCounters[croppedName] === undefined) {
+        arrayInputCounters[croppedName] = 0;
+      }
+    }
+
+    const values = Array.isArray(inputVal) ? inputVal : [inputVal];
+
+    for (const value of values) {
+      if (isArrayInput) {
+        inputName = `${croppedName}[${arrayInputCounters[croppedName]}]`;
+        arrayInputCounters[croppedName]!++;
+      }
+      postData[inputName!] = value;
+    }
+  }
+
+  return postData;
+}
+
+/** Copies values input-by-input, skipping file inputs. */
+export function copyInputValues(source: Element, target: Element): void {
+  const sourceInputs = findInputs(source);
+  const targetInputs = findInputs(target);
+
+  for (let i = 0; i < sourceInputs.length; i++) {
+    const targetInput = targetInputs[i] as InputLike | undefined;
+    if (targetInput === undefined) {
+      break;
+    }
+
+    if (targetInput.getAttribute('type') !== 'file') {
+      targetInput.value = (sourceInputs[i] as InputLike).value;
+    }
+  }
+}
diff --git a/packages/craftcms-garnish/src/utils/index.ts b/packages/craftcms-garnish/src/utils/index.ts
new file mode 100644
index 00000000000..2031091f153
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/index.ts
@@ -0,0 +1,78 @@
+/**
+ * Re-export barrel for all Garnish core utilities.
+ */
+
+export {
+  coerceElements,
+  getElement,
+  hasAttr,
+  getOffset,
+  getOuterWidth,
+  getOuterHeight,
+  hitTest,
+  isCursorOver,
+  copyTextStyles,
+} from './dom';
+
+export {getScrollParent, isWindowScrollContainer} from './scroll';
+
+export {
+  isFocusable,
+  isKeyboardFocusable,
+  getFocusableElements,
+  isVisible,
+} from './focusable';
+
+export {
+  focusIsInside,
+  firstFocusableElement,
+  getKeyboardFocusableElements,
+  getFocusedElement,
+  trapFocusWithin,
+  releaseFocusWithin,
+  setFocusWithin,
+} from './focus';
+
+export {
+  addModalAttributes,
+  isScriptOrStyleElement,
+  hasJsAriaClass,
+  ariaHide,
+  hideModalBackgroundLayers,
+  resetModalBackgroundLayerVisibility,
+} from './aria';
+
+export {
+  getInputBasename,
+  getInputPostVal,
+  findInputs,
+  getPostData,
+  copyInputValues,
+} from './forms';
+
+export {
+  requestAnimationFrame,
+  cancelAnimationFrame,
+  prefersReducedMotion,
+  getUserPreferredAnimationDuration,
+  scrollContainerToElement,
+  shake,
+} from './animation';
+
+export {
+  isMobileBrowser,
+  isPrimaryClick,
+  isCtrlKeyPressed,
+  getBodyScrollTop,
+} from './env';
+
+export {
+  getDist,
+  within,
+  isString,
+  isArray,
+  isPlainObject,
+  isTextNode,
+  log,
+  handleActivatingKeypress,
+} from './misc';
diff --git a/packages/craftcms-garnish/src/utils/misc.ts b/packages/craftcms-garnish/src/utils/misc.ts
new file mode 100644
index 00000000000..157cff9cb04
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/misc.ts
@@ -0,0 +1,88 @@
+/**
+ * Miscellaneous pure utilities.
+ */
+
+import {RETURN_KEY, SPACE_KEY, TEXT_NODE} from '../constants';
+
+/**
+ * Whether a value is a "plain object" — the native replacement for jQuery's
+ * `$.isPlainObject`, used by the drag classes' `(items, settings)` param-shift to
+ * detect a settings object passed as the first argument.
+ *
+ * Excludes DOM nodes, arrays, array-likes (anything with a numeric `length`), and
+ * event targets, so an element / element list passed as `items` is never mistaken
+ * for settings.
+ */
+export function isPlainObject(val: unknown): val is Record<string, unknown> {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    !(val instanceof Element) &&
+    !(typeof Node !== 'undefined' && val instanceof Node) &&
+    !Array.isArray(val) &&
+    typeof (val as {length?: unknown}).length !== 'number' &&
+    typeof (val as EventTarget).addEventListener !== 'function' &&
+    (Object.getPrototypeOf(val) === Object.prototype ||
+      Object.getPrototypeOf(val) === null)
+  );
+}
+
+/** Euclidean distance between two coordinates. */
+export function getDist(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number
+): number {
+  return Math.sqrt(Math.pow(x1 - x2, 2) + Math.pow(y1 - y2, 2));
+}
+
+/** Clamp a number into a [min, max] range. */
+export function within(num: number, min: number, max: number): number {
+  num = Math.max(num, min);
+  num = Math.min(num, max);
+  return num;
+}
+
+/** Whether a value is a string. */
+export function isString(val: unknown): val is string {
+  return typeof val === 'string';
+}
+
+/**
+ * Whether a value is an array.
+ * @deprecated Use `Array.isArray` directly.
+ */
+export function isArray(val: unknown): val is unknown[] {
+  return Array.isArray(val);
+}
+
+/** Whether a node is a text node. */
+export function isTextNode(elem: Node): boolean {
+  return elem.nodeType === TEXT_NODE;
+}
+
+/**
+ * Logs a message to the console, if available.
+ * @deprecated Use `console` directly.
+ */
+export function log(msg: unknown): void {
+  if (typeof console !== 'undefined' && typeof console.log === 'function') {
+    console.log(msg);
+  }
+}
+
+/**
+ * Space/Enter → preventDefault + callback.
+ * @deprecated The `activate` event should be used instead.
+ */
+export function handleActivatingKeypress(
+  event: KeyboardEvent,
+  callback: () => void
+): void {
+  const key = event.keyCode;
+  if (key === SPACE_KEY || key === RETURN_KEY) {
+    event.preventDefault();
+    callback();
+  }
+}
diff --git a/packages/craftcms-garnish/src/utils/scroll.ts b/packages/craftcms-garnish/src/utils/scroll.ts
new file mode 100644
index 00000000000..750fe8a0491
--- /dev/null
+++ b/packages/craftcms-garnish/src/utils/scroll.ts
@@ -0,0 +1,73 @@
+/**
+ * Scroll-container utilities (jQuery-free).
+ *
+ * The drag foundation needs a shared, axis-aware "nearest scrollable ancestor"
+ * finder to replace jQuery's `.scrollParent()`. It lives here (not inside
+ * `base-drag.ts` or `animation.ts`) so it is a single source of truth that both
+ * the drag system and `scrollContainerToElement` reuse.
+ */
+
+import {X_AXIS, Y_AXIS} from '../constants';
+import {bod, doc, win} from '../globals';
+
+/** Whether an element scrolls overflow content on at least one axis. */
+function isScrollable(el: Element): boolean {
+  const style = window.getComputedStyle(el);
+  const overflow = `${style.overflow}${style.overflowY}${style.overflowX}`;
+  return /(auto|scroll|overlay)/.test(overflow);
+}
+
+/** Whether an element scrolls overflow content on the given axis (or either). */
+function isScrollableOnAxis(el: Element, axis?: 'x' | 'y' | null): boolean {
+  const verticallyScrollable =
+    axis !== X_AXIS && el.scrollHeight > el.clientHeight;
+  const horizontallyScrollable =
+    axis !== Y_AXIS && el.scrollWidth > el.clientWidth;
+  return verticallyScrollable || horizontallyScrollable;
+}
+
+/**
+ * Find the nearest scrollable ancestor of an element (the native, axis-aware
+ * replacement for jQuery's `.scrollParent()` used by `BaseDrag`).
+ *
+ * The walk mirrors the legacy `BaseDrag.setScrollContainer`:
+ *
+ * 1. Climb from `el` to the nearest ancestor whose computed `overflow` is
+ *    `auto`/`scroll`/`overlay`.
+ * 2. If that ancestor is `<html>` or `<body>`, the container is the window.
+ * 3. Otherwise, if it is scrollable **on the relevant axis** (has overflowing
+ *    content), it is the container.
+ * 4. Else, keep climbing.
+ *
+ * @param el - The element whose scroll container we want.
+ * @param axis - Restrict the scrollability test to one axis (`'x'`/`'y'`), or
+ *   `null`/omitted to accept either.
+ * @returns The scrollable ancestor element, or `window` when the page itself
+ *   (or `<html>`/`<body>`) is the scroller.
+ */
+export function getScrollParent(
+  el: Element,
+  axis?: 'x' | 'y' | null
+): Element | Window {
+  let node: Element | null = el.parentElement;
+
+  while (node) {
+    // <html>/<body> normalize to the window.
+    if (node === doc.documentElement || node === bod) {
+      return win;
+    }
+
+    if (isScrollable(node) && isScrollableOnAxis(node, axis)) {
+      return node;
+    }
+
+    node = node.parentElement;
+  }
+
+  return win;
+}
+
+/** True if the resolved scroll container is the window. */
+export function isWindowScrollContainer(container: Element | Window): boolean {
+  return container === win;
+}
diff --git a/packages/craftcms-garnish/stories/_helpers.ts b/packages/craftcms-garnish/stories/_helpers.ts
new file mode 100644
index 00000000000..64cbb68eb80
--- /dev/null
+++ b/packages/craftcms-garnish/stories/_helpers.ts
@@ -0,0 +1,56 @@
+/**
+ * Shared DOM builders for the modal-based stories.
+ *
+ * The Modal widget positions itself `fixed` and renders its own `.modal-shade`,
+ * so these containers are appended to `document.body` (not the story canvas) —
+ * exactly as the old playground did.
+ */
+
+import {Modal} from '../src/index';
+
+/** Build a styled modal container with the given heading + body HTML. */
+export function buildModalContainer(title: string, body: string): HTMLElement {
+  const el = document.createElement('div');
+  el.className = 'pg-modal';
+  el.innerHTML = `
+    <h3>${title}</h3>
+    <div class="pg-modal-body">${body}</div>
+    <div class="pg-modal-actions">
+      <button type="button" class="pg-modal-primary" data-modal-close>Close (hide)</button>
+    </div>
+  `;
+  document.body.appendChild(el);
+  el.querySelector('[data-modal-close]')!.addEventListener('click', () => {
+    // Find the owning Modal via the static registry and hide it.
+    Modal.instances.find((m) => m.$container === el)?.hide();
+  });
+  return el;
+}
+
+/**
+ * Build a modal container styled to look draggable, optionally with a header
+ * handle (for the `dragHandleSelector` demo).
+ */
+export function buildDragModalContainer(
+  title: string,
+  body: string,
+  withHandle: boolean
+): HTMLElement {
+  const el = document.createElement('div');
+  el.className = 'pg-modal pg-modal--draggable';
+  const handleHtml = withHandle
+    ? `<div class="pg-modal-drag-handle" data-drag-handle>${title} — drag here</div>`
+    : `<h3>${title}</h3>`;
+  el.innerHTML = `
+    ${handleHtml}
+    <div class="pg-modal-body">${body}</div>
+    <div class="pg-modal-actions">
+      <button type="button" class="pg-modal-primary" data-modal-close>Close (hide)</button>
+    </div>
+  `;
+  document.body.appendChild(el);
+  el.querySelector('[data-modal-close]')!.addEventListener('click', () => {
+    Modal.instances.find((m) => m.$container === el)?.hide();
+  });
+  return el;
+}
diff --git a/packages/craftcms-garnish/stories/_log.ts b/packages/craftcms-garnish/stories/_log.ts
new file mode 100644
index 00000000000..83cf79eeba1
--- /dev/null
+++ b/packages/craftcms-garnish/stories/_log.ts
@@ -0,0 +1,85 @@
+/**
+ * Shared event-logging helper for @craftcms/garnish stories.
+ *
+ * Backed by Storybook's built-in **Actions** panel (`storybook/actions`) rather
+ * than a hand-rolled DOM panel: every logged event shows up in the "Actions" tab
+ * under the addons panel, grouped by `tag`. Drag/menu/modal stories use it to
+ * surface the events the real widgets fire (`show`, `hide`, `dragStart`,
+ * `dropTargetChange`, …) as you interact.
+ *
+ * Usage in a story `render()`:
+ *
+ * ```ts
+ * const log = createEventLog();
+ * const main = document.createElement('div');
+ * // …build the demo, call log.log('modal', 'show') from event handlers…
+ * return storyLayout(main);
+ * ```
+ */
+
+import {action} from 'storybook/actions';
+
+/** A subscribable lifecycle object (Garnish `Base` / draggers expose `on`). */
+export interface Subscribable {
+  on(events: string, handler: () => void): void;
+}
+
+export interface EventLog {
+  /**
+   * Log an event to the Actions panel under `tag` with a human-readable message.
+   */
+  log(tag: string, message: string): void;
+}
+
+// Memoize one Storybook action per tag so the panel groups events by tag.
+const actions = new Map<string, ReturnType<typeof action>>();
+function actionFor(tag: string): ReturnType<typeof action> {
+  let fn = actions.get(tag);
+  if (!fn) {
+    fn = action(tag);
+    actions.set(tag, fn);
+  }
+  return fn;
+}
+
+/** Create a logger that writes events into Storybook's Actions panel. */
+export function createEventLog(): EventLog {
+  return {
+    log: (tag, message) => actionFor(tag)(message),
+  };
+}
+
+/**
+ * Wire a dragger's lifecycle into the log. `drag` fires once per RAF frame, so
+ * it is coalesced to a single "drag (moving…)" line per gesture to keep the
+ * Actions panel readable; `dragStart` / `dragStop` always log.
+ */
+export function wireDragEvents(
+  log: EventLog,
+  dragger: Subscribable,
+  tag: string,
+  label: string
+): void {
+  let dragging = false;
+  dragger.on('dragStart', () => {
+    dragging = false;
+    log.log(tag, `${label}: dragStart`);
+  });
+  dragger.on('drag', () => {
+    if (!dragging) {
+      dragging = true;
+      log.log(tag, `${label}: drag (moving…)`);
+    }
+  });
+  dragger.on('dragStop', () => log.log(tag, `${label}: dragStop`));
+}
+
+/**
+ * Wrap a story's demo column in the `.pg-story` container the global styles
+ * expect. Events surface in Storybook's Actions panel, so there is no in-canvas
+ * log panel to mount.
+ */
+export function storyLayout(main: HTMLElement): HTMLElement {
+  main.classList.add('pg-story');
+  return main;
+}
diff --git a/packages/craftcms-garnish/stories/base-drag.stories.ts b/packages/craftcms-garnish/stories/base-drag.stories.ts
new file mode 100644
index 00000000000..7944e8c58a8
--- /dev/null
+++ b/packages/craftcms-garnish/stories/base-drag.stories.ts
@@ -0,0 +1,144 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {BaseDrag, DragMove} from '../src/index';
+import {createEventLog, wireDragEvents, storyLayout} from './_log';
+
+/**
+ * Standalone `BaseDrag` / `DragMove` — playground sections 5 (standalone boxes)
+ * and 6 (auto-scroll while dragging).
+ */
+const meta: Meta = {
+  title: 'Drag/BaseDrag',
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const StandaloneBoxes: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Free-floating boxes inside the bounded area. The green boxes use
+        <code>new DragMove(box)</code> directly; the blue box uses a raw
+        <code>new BaseDrag(box, {onDrag})</code> that sets <code>left/top</code>
+        itself. The third green box is X-axis-locked (<code>{axis: 'x'}</code>).
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="reset">Reset box positions</button>
+      </div>
+      <div class="pg-drag-arena" data-arena>
+        <div class="pg-drag-box pg-drag-box--move" data-box="move-1">DragMove #1</div>
+        <div class="pg-drag-box pg-drag-box--move" data-box="move-2">DragMove #2</div>
+        <div class="pg-drag-box pg-drag-box--move pg-drag-box--xlock" data-box="move-x">DragMove (x-axis only)</div>
+        <div class="pg-drag-box pg-drag-box--base" data-box="base-1">BaseDrag + onDrag</div>
+      </div>`;
+
+    const arena = main.querySelector<HTMLElement>('[data-arena]')!;
+
+    const boxHomes: Record<string, {left: number; top: number}> = {
+      'move-1': {left: 16, top: 16},
+      'move-2': {left: 170, top: 16},
+      'move-x': {left: 16, top: 100},
+      'base-1': {left: 170, top: 100},
+    };
+
+    const placeBox = (box: HTMLElement): void => {
+      const home = boxHomes[box.dataset.box!];
+      if (home) {
+        box.style.left = `${home.left}px`;
+        box.style.top = `${home.top}px`;
+      }
+    };
+
+    const boxes = Array.from(arena.querySelectorAll<HTMLElement>('[data-box]'));
+    boxes.forEach(placeBox);
+
+    // Green boxes: DragMove drives left/top for us.
+    arena
+      .querySelectorAll<HTMLElement>(
+        '.pg-drag-box--move:not(.pg-drag-box--xlock)'
+      )
+      .forEach((box) => {
+        const dragger = new DragMove(box);
+        wireDragEvents(log, dragger, 'drag', box.dataset.box!);
+      });
+
+    // X-axis-locked DragMove.
+    const xBox = arena.querySelector<HTMLElement>('.pg-drag-box--xlock');
+    if (xBox) {
+      const dragger = new DragMove(xBox, {axis: 'x'});
+      wireDragEvents(log, dragger, 'drag', `${xBox.dataset.box} (x-locked)`);
+    }
+
+    // Blue box: raw BaseDrag with an onDrag that positions it ourselves.
+    const baseBox = arena.querySelector<HTMLElement>('.pg-drag-box--base');
+    if (baseBox) {
+      let start = {left: 0, top: 0};
+      const dragger: BaseDrag = new BaseDrag(baseBox, {
+        onDragStart: () => {
+          start = {left: baseBox.offsetLeft, top: baseBox.offsetTop};
+        },
+        onDrag: () => {
+          baseBox.style.left = `${start.left + dragger.mouseDistX!}px`;
+          baseBox.style.top = `${start.top + dragger.mouseDistY!}px`;
+        },
+      });
+      wireDragEvents(log, dragger, 'drag', 'base-1 (manual onDrag)');
+    }
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="reset"]')!
+      .addEventListener('click', () => {
+        boxes.forEach(placeBox);
+        log.log('drag', 'Reset box positions');
+      });
+
+    return storyLayout(main);
+  },
+};
+
+export const AutoScroll: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        The orange item lives inside a tall scrollable container. Grab it and drag
+        toward the top or bottom edge (within ~25px) — the container should
+        auto-scroll via the RAF loop.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="reset">Reset</button>
+      </div>
+      <div class="pg-scroll-container" data-scroll-container>
+        <div class="pg-scroll-tall">
+          <div class="pg-drag-box pg-drag-box--scroll" data-box="scroll-1">Drag me near an edge</div>
+          <p class="pg-scroll-filler">↑ tall scrollable content ↑</p>
+          <p class="pg-scroll-filler">scroll me by dragging to the edges</p>
+          <p class="pg-scroll-filler">↓ keep going ↓</p>
+        </div>
+      </div>`;
+
+    const scrollContainer = main.querySelector<HTMLElement>(
+      '[data-scroll-container]'
+    )!;
+    const scrollBox = scrollContainer.querySelector<HTMLElement>(
+      '.pg-drag-box--scroll'
+    )!;
+
+    const dragger = new DragMove(scrollBox);
+    wireDragEvents(log, dragger, 'autoscroll', 'scroll-box');
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="reset"]')!
+      .addEventListener('click', () => {
+        scrollBox.style.left = '20px';
+        scrollBox.style.top = '20px';
+        scrollContainer.scrollTop = 0;
+        log.log('autoscroll', 'Reset scroll item + scroll position');
+      });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/compat.stories.ts b/packages/craftcms-garnish/stories/compat.stories.ts
new file mode 100644
index 00000000000..9d794ae4f84
--- /dev/null
+++ b/packages/craftcms-garnish/stories/compat.stories.ts
@@ -0,0 +1,113 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {installGarnishCompat} from '../src/compat';
+import {createEventLog, storyLayout} from './_log';
+import {buildModalContainer} from './_helpers';
+
+/**
+ * Compat upgrade path — playground section 3.
+ *
+ * Calls `installGarnishCompat()`, then defines a subclass with the legacy
+ * `Garnish.Modal.extend({ init, onShow })` API and a `this.base()` super-call —
+ * proving the legacy authoring contract works in the browser against the modern
+ * `class Modal`. This is the `.extend()` / `this.base` upgrade story.
+ */
+const meta: Meta = {
+  title: 'Compat',
+};
+export default meta;
+
+type Story = StoryObj;
+
+interface LegacyCtorLike {
+  extend(instance: Record<string, unknown>, statics?: object): LegacyCtorLike;
+  new (...args: unknown[]): unknown;
+}
+
+interface GarnishGlobalLike {
+  Modal: LegacyCtorLike;
+  [key: string]: unknown;
+}
+
+export const ExtendUpgradePath: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Calls <code>installGarnishCompat()</code>, then defines a subclass with the
+        legacy <code>Garnish.Modal.extend({ init, onShow })</code> API and a
+        <code>this.base()</code> super-call — proving the legacy authoring contract
+        works against the modern <code>class Modal</code>.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="install">installGarnishCompat()</button>
+        <button type="button" data-act="extend">Instantiate Garnish.Modal.extend(...) subclass</button>
+      </div>`;
+
+    let compatGarnish: GarnishGlobalLike | null = null;
+
+    const actions: Record<string, () => void> = {
+      install: () => {
+        compatGarnish = installGarnishCompat() as unknown as GarnishGlobalLike;
+        const onWindow =
+          (window as unknown as {Garnish?: unknown}).Garnish !== undefined;
+        log.log(
+          'compat',
+          `installGarnishCompat() ran. window.Garnish present: ${onWindow}; Garnish.Modal.extend is ${typeof compatGarnish.Modal.extend}`
+        );
+      },
+      extend: () => {
+        if (!compatGarnish) {
+          actions.install!();
+        }
+        const Garnish = compatGarnish!;
+
+        // Define the subclass exactly the legacy way: init() trampoline + this.base().
+        const DemoModalSubclass = Garnish.Modal.extend({
+          init(this: {
+            base: (...a: unknown[]) => unknown;
+            $container: HTMLElement | null;
+          }) {
+            const container = buildModalContainer(
+              'Legacy .extend() subclass',
+              '<p>This modal was created via <code>Garnish.Modal.extend({ init, onShow })</code> and uses <code>this.base()</code> in <code>onShow</code>.</p>'
+            );
+            // Call the modern Modal constructor through the init trampoline.
+            this.base(container, {autoShow: false});
+            log.log(
+              'compat',
+              'subclass init() ran, called this.base(container)'
+            );
+          },
+          onShow(this: {base: () => void}) {
+            // this.base() dispatches to Modal.prototype.onShow (fires 'show').
+            this.base();
+            log.log('compat', 'subclass onShow() ran, then called this.base()');
+          },
+        }) as LegacyCtorLike;
+
+        const instance = new DemoModalSubclass() as {
+          on(evt: string, fn: () => void): void;
+          show(): void;
+        };
+        instance.on('show', () =>
+          log.log('compat', "subclass 'show' event observed")
+        );
+        instance.show();
+        log.log('compat', 'Instantiated + show()ed the .extend() subclass');
+      },
+    };
+
+    main.querySelectorAll<HTMLButtonElement>('[data-act]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        try {
+          actions[btn.dataset.act!]?.();
+        } catch (err) {
+          log.log('compat', `Error: ${(err as Error).message}`);
+        }
+      });
+    });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/disclosure-menu.stories.ts b/packages/craftcms-garnish/stories/disclosure-menu.stories.ts
new file mode 100644
index 00000000000..7cc5925b3bd
--- /dev/null
+++ b/packages/craftcms-garnish/stories/disclosure-menu.stories.ts
@@ -0,0 +1,147 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {DisclosureMenu} from '../src/index';
+import {createEventLog, storyLayout, type EventLog} from './_log';
+
+/**
+ * `DisclosureMenu` — dropdown menu — playground section 12.
+ *
+ * Pairs a trigger button (`aria-controls` / `aria-expanded`) with a menu panel.
+ * Click to toggle; the panel anchors under the trigger (flipping above when
+ * there's no room). Arrow keys move between items, typing a letter does type-ahead
+ * search, Esc / outside-click closes. A second variant adds a live search input.
+ *
+ * Each story builds its menu as the trigger's `nextElementSibling` with a unique
+ * id, so `DisclosureMenu` resolves it even before Storybook mounts the canvas.
+ */
+const meta: Meta = {
+  title: 'DisclosureMenu',
+};
+export default meta;
+
+type Story = StoryObj;
+
+// Unique-id counter so re-renders don't collide with menus moved to <body>.
+let uid = 0;
+const nextId = (): string => `sb-disc-menu-${++uid}`;
+
+/** Wire a menu's lifecycle events into the log. */
+function wireMenuEvents(
+  log: EventLog,
+  menu: DisclosureMenu,
+  label: string
+): void {
+  for (const evt of ['beforeShow', 'show', 'hide'] as const) {
+    menu.on(evt, () => log.log('disclosure', `${label}: ${evt}`));
+  }
+}
+
+export const Dropdown: Story = {
+  render: () => {
+    const log = createEventLog();
+    const menuId = nextId();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        A <code>new DisclosureMenu(trigger)</code> with static markup: groups, a
+        separator, plus a disabled and a destructive item. Open it, then use
+        <kbd>↑</kbd>/<kbd>↓</kbd>, type a letter for <strong>type-ahead</strong>, or
+        <kbd>Esc</kbd> to close.
+      </p>
+      <div class="pg-controls">
+        <button type="button" class="pg-disc-trigger" aria-controls="${menuId}" aria-expanded="false">Actions ▾</button>
+        <div id="${menuId}" class="menu menu--disclosure" data-align="left">
+          <ul>
+            <li><button type="button" class="menu-item"><span class="menu-item-label">New entry</span></button></li>
+            <li><button type="button" class="menu-item sel"><span class="menu-item-label">Duplicate</span></button></li>
+            <li><button type="button" class="menu-item disabled" disabled><span class="menu-item-label">Rename (disabled)</span></button></li>
+          </ul>
+          <hr />
+          <h3 class="h6">Danger zone</h3>
+          <ul>
+            <li><button type="button" class="menu-item error" data-destructive="true"><span class="menu-item-label">Delete</span></button></li>
+          </ul>
+        </div>
+        <button type="button" data-act="destroy">Destroy this menu</button>
+      </div>`;
+
+    const trigger = main.querySelector<HTMLButtonElement>('.pg-disc-trigger')!;
+    const menu = new DisclosureMenu(trigger);
+    wireMenuEvents(log, menu, 'actions');
+
+    menu.$container
+      ?.querySelectorAll<HTMLButtonElement>('.menu-item:not(.disabled)')
+      .forEach((item) => {
+        item.addEventListener('click', () => {
+          const label =
+            item.querySelector('.menu-item-label')?.textContent ?? '?';
+          log.log('disclosure', `actions: selected "${label}"`);
+        });
+      });
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="destroy"]')!
+      .addEventListener('click', () => {
+        menu.destroy();
+        log.log('disclosure', 'Destroyed the DisclosureMenu instance');
+      });
+
+    return storyLayout(main);
+  },
+};
+
+interface FilterableArgs {
+  withSearchInput: boolean;
+}
+
+export const Filterable: StoryObj<FilterableArgs> = {
+  argTypes: {
+    withSearchInput: {
+      control: 'boolean',
+      description: 'Add a live search input that filters the items',
+    },
+  },
+  args: {
+    withSearchInput: true,
+  },
+  render: (args) => {
+    const log = createEventLog();
+    const menuId = nextId();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Items are added via the API (<code>addItems</code>). With
+        <code>withSearchInput</code> enabled, a search field filters them live.
+      </p>
+      <div class="pg-controls">
+        <button type="button" class="pg-disc-trigger" aria-controls="${menuId}" aria-expanded="false">Filterable ▾</button>
+        <div id="${menuId}" class="menu menu--disclosure" data-align="left"></div>
+      </div>`;
+
+    const trigger = main.querySelector<HTMLButtonElement>('.pg-disc-trigger')!;
+    const menu = new DisclosureMenu(trigger, {
+      withSearchInput: args.withSearchInput,
+    });
+    wireMenuEvents(log, menu, 'filter');
+
+    const fruits = [
+      'Apple',
+      'Apricot',
+      'Banana',
+      'Blueberry',
+      'Cherry',
+      'Grape',
+      'Mango',
+      'Orange',
+      'Peach',
+      'Pear',
+    ];
+    menu.addItems(
+      fruits.map((name) => ({
+        label: name,
+        onActivate: () => log.log('disclosure', `filter: selected "${name}"`),
+      }))
+    );
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/drag-drop.stories.ts b/packages/craftcms-garnish/stories/drag-drop.stories.ts
new file mode 100644
index 00000000000..bff10afb298
--- /dev/null
+++ b/packages/craftcms-garnish/stories/drag-drop.stories.ts
@@ -0,0 +1,103 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {DragDrop} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+
+/**
+ * `DragDrop` — drop targets & hit detection — playground section 8.
+ *
+ * A `new DragDrop({ dropTargets, ... })` wired to draggable chips and three drop
+ * zones. While dragging, the zone under the cursor highlights
+ * (`activeDropTargetClass`) and `dropTargetChange` logs the new active target.
+ * On release, the demo reads `$activeDropTarget` in its `dragStop` handler.
+ */
+const meta: Meta = {
+  title: 'Drag/DragDrop',
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const DropTargets: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Drag a chip over a zone: the zone under the cursor highlights and
+        <code>dropTargetChange</code> logs the new active target (or
+        <code>null</code>). On release the demo reads <code>$activeDropTarget</code>
+        to report where it landed. Overlap resolves to the first target in document
+        order.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="reset">Reset chips</button>
+      </div>
+      <div class="pg-dragdrop-layout">
+        <div class="pg-dragdrop-chips" data-chips>
+          <div class="pg-dragdrop-chip" data-dragdrop-chip="a">Chip A</div>
+          <div class="pg-dragdrop-chip" data-dragdrop-chip="b">Chip B</div>
+          <div class="pg-dragdrop-chip" data-dragdrop-chip="c">Chip C</div>
+        </div>
+        <div class="pg-dragdrop-zones" data-zones>
+          <div class="pg-dropzone" data-dropzone="inbox">Inbox</div>
+          <div class="pg-dropzone" data-dropzone="archive">Archive</div>
+          <div class="pg-dropzone" data-dropzone="trash">Trash</div>
+        </div>
+      </div>`;
+
+    const chips = Array.from(
+      main.querySelectorAll<HTMLElement>('[data-dragdrop-chip]')
+    );
+    const zones = Array.from(
+      main.querySelectorAll<HTMLElement>('[data-dropzone]')
+    );
+
+    const dragDrop = new DragDrop({
+      dropTargets: zones,
+      hideDraggee: true,
+      helperOpacity: 0.92,
+      onDropTargetChange(activeDropTarget) {
+        const name = activeDropTarget?.dataset.dropzone ?? 'none';
+        log.log('dragdrop', `dropTargetChange → ${name}`);
+      },
+      onDragStop() {
+        // Legacy contract: no `drop` event — read $activeDropTarget here.
+        const target = dragDrop.$activeDropTarget;
+        if (target) {
+          log.log(
+            'dragdrop',
+            `dropped on "${target.dataset.dropzone}" (read from $activeDropTarget)`
+          );
+          target.classList.add('pg-dropzone--hit');
+          setTimeout(() => target.classList.remove('pg-dropzone--hit'), 600);
+        } else {
+          log.log('dragdrop', 'dropped outside any drop target');
+        }
+        dragDrop.returnHelpersToDraggees();
+      },
+    });
+    dragDrop.addItems(chips);
+
+    // Also surface the raw drag lifecycle (coalesce the per-frame `drag`).
+    let dragging = false;
+    dragDrop.on('dragStart', () => {
+      dragging = false;
+      log.log('dragdrop', 'dragStart');
+    });
+    dragDrop.on('drag', () => {
+      if (!dragging) {
+        dragging = true;
+        log.log('dragdrop', 'drag (over zones…)');
+      }
+    });
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="reset"]')!
+      .addEventListener('click', () => {
+        zones.forEach((z) => z.classList.remove('active', 'pg-dropzone--hit'));
+        log.log('dragdrop', 'Reset chips + cleared zone highlights');
+      });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/drag-sort.stories.ts b/packages/craftcms-garnish/stories/drag-sort.stories.ts
new file mode 100644
index 00000000000..41dea3dc713
--- /dev/null
+++ b/packages/craftcms-garnish/stories/drag-sort.stories.ts
@@ -0,0 +1,102 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {DragSort} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+
+/**
+ * `DragSort` — reorderable list — playground section 9.
+ *
+ * A `new DragSort(items, { insertion, ... })` wired to a sortable list. Grab a
+ * row and drag it: the list reflows live around a dashed `insertion` placeholder
+ * (`insertionPointChange` logs each move). On drop the new order is committed and
+ * `sortChange` logs the new index order. The list is `axis: 'y'`-locked.
+ */
+const meta: Meta = {
+  title: 'Drag/DragSort',
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const ReorderableList: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Grab a row and drag it up or down — the list reflows live around a dashed
+        <code>insertion</code> placeholder. On drop the new order commits;
+        <code>sortChange</code> logs the new order. Handles carry
+        <code>touch-action: none</code>.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="reset">Reset list order</button>
+      </div>
+      <ul class="pg-sort-list" data-sort-list>
+        <li class="pg-sort-item" data-sort-item="1"><span class="pg-sort-grip" aria-hidden="true">⠿</span> Apples</li>
+        <li class="pg-sort-item" data-sort-item="2"><span class="pg-sort-grip" aria-hidden="true">⠿</span> Oranges</li>
+        <li class="pg-sort-item" data-sort-item="3"><span class="pg-sort-grip" aria-hidden="true">⠿</span> Bananas</li>
+        <li class="pg-sort-item" data-sort-item="4"><span class="pg-sort-grip" aria-hidden="true">⠿</span> Grapes</li>
+        <li class="pg-sort-item" data-sort-item="5"><span class="pg-sort-grip" aria-hidden="true">⠿</span> Mangoes</li>
+      </ul>`;
+
+    const sortList = main.querySelector<HTMLElement>('[data-sort-list]')!;
+    const items = Array.from(
+      sortList.querySelectorAll<HTMLElement>('[data-sort-item]')
+    );
+    const originalOrder = items.map((el) => el.dataset.sortItem!);
+
+    const currentOrder = (): string =>
+      Array.from(sortList.querySelectorAll<HTMLElement>('[data-sort-item]'))
+        .map((el) => el.dataset.sortItem)
+        .join(', ');
+
+    const dragSort = new DragSort(items, {
+      container: sortList,
+      axis: 'y',
+      hideDraggee: true,
+      helperOpacity: 0.95,
+      insertion: () => {
+        const ph = document.createElement('li');
+        ph.className = 'pg-sort-insertion';
+        return ph;
+      },
+      onInsertionPointChange() {
+        log.log(
+          'dragsort',
+          `insertionPointChange → order now [${currentOrder()}]`
+        );
+      },
+      onSortChange() {
+        log.log('dragsort', `sortChange → new order [${currentOrder()}]`);
+      },
+    });
+
+    // Surface the raw drag lifecycle too (coalesce the per-frame `drag`).
+    let dragging = false;
+    dragSort.on('dragStart', () => {
+      dragging = false;
+      log.log('dragsort', 'dragStart');
+    });
+    dragSort.on('drag', () => {
+      if (!dragging) {
+        dragging = true;
+        log.log('dragsort', 'drag (reordering…)');
+      }
+    });
+    dragSort.on('dragStop', () => log.log('dragsort', 'dragStop'));
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="reset"]')!
+      .addEventListener('click', () => {
+        for (const id of originalOrder) {
+          const el = sortList.querySelector<HTMLElement>(
+            `[data-sort-item="${id}"]`
+          );
+          if (el) sortList.appendChild(el);
+        }
+        log.log('dragsort', `Reset list order → [${currentOrder()}]`);
+      });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/drag.stories.ts b/packages/craftcms-garnish/stories/drag.stories.ts
new file mode 100644
index 00000000000..c7a40a901e2
--- /dev/null
+++ b/packages/craftcms-garnish/stories/drag.stories.ts
@@ -0,0 +1,103 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {Drag} from '../src/index';
+import {createEventLog, storyLayout, type EventLog} from './_log';
+
+/**
+ * `Drag` with helpers — playground section 7.
+ *
+ * Grabbing an item builds a floating helper clone that trails the cursor with
+ * lag (`createHelper` + the lag-follow RAF loop). On drop the helper animates
+ * back to its source via the Web Animations API (`returnHelpersToDraggees`) — or
+ * fades out (`fadeOutHelpers`), selectable via the `dropMode` control.
+ */
+const meta: Meta = {
+  title: 'Drag/Drag',
+};
+export default meta;
+
+interface DragArgs {
+  dropMode: 'return' | 'fade';
+}
+
+type Story = StoryObj<DragArgs>;
+
+/** Wire a Drag's lifecycle into the log, including `returnHelpersToDraggees`. */
+function wireHelperDragEvents(
+  log: EventLog,
+  dragger: Drag,
+  label: string
+): void {
+  let dragging = false;
+  dragger.on('dragStart', () => {
+    dragging = false;
+    log.log('draghelper', `${label}: dragStart (helper clone created)`);
+  });
+  dragger.on('drag', () => {
+    if (!dragging) {
+      dragging = true;
+      log.log('draghelper', `${label}: drag (helper trailing cursor…)`);
+    }
+  });
+  dragger.on('dragStop', () => log.log('draghelper', `${label}: dragStop`));
+  dragger.on('returnHelpersToDraggees', () =>
+    log.log('draghelper', `${label}: returnHelpersToDraggees (helpers home)`)
+  );
+}
+
+export const Helpers: Story = {
+  argTypes: {
+    dropMode: {
+      control: 'inline-radio',
+      options: ['return', 'fade'],
+      description: 'On drop: return helpers to source, or fade them out',
+    },
+  },
+  args: {
+    dropMode: 'return',
+  },
+  render: (args) => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        These rows use <code>new Drag(items, {...})</code>. Grabbing an item builds
+        a floating <strong>helper clone</strong> that trails the cursor. On drop the
+        helper either animates back to its source or fades out — pick via the
+        <code>dropMode</code> control.
+      </p>
+      <div class="pg-helper-list" data-helper-list>
+        <div class="pg-helper-item" data-helper-item="1"><span class="pg-helper-grip" aria-hidden="true">⠿</span> Draggable item #1 — grab &amp; drag me</div>
+        <div class="pg-helper-item" data-helper-item="2"><span class="pg-helper-grip" aria-hidden="true">⠿</span> Draggable item #2 — a helper clone trails the cursor</div>
+        <div class="pg-helper-item" data-helper-item="3"><span class="pg-helper-grip" aria-hidden="true">⠿</span> Draggable item #3 — release to animate home</div>
+        <div class="pg-helper-item" data-helper-item="4"><span class="pg-helper-grip" aria-hidden="true">⠿</span> Draggable item #4</div>
+      </div>`;
+
+    const list = main.querySelector<HTMLElement>('[data-helper-list]')!;
+    const items = Array.from(
+      list.querySelectorAll<HTMLElement>('[data-helper-item]')
+    );
+
+    items.forEach((item) => {
+      const dragger = new Drag(item, {
+        // Hide the source while its helper clone is in flight.
+        hideDraggee: true,
+        helperOpacity: 0.92,
+        onDragStop() {
+          // Default Drag does NOT auto-return; the consumer decides.
+          if (args.dropMode === 'fade') {
+            dragger.fadeOutHelpers();
+            log.log(
+              'draghelper',
+              `${item.dataset.helperItem}: fadeOutHelpers()`
+            );
+          } else {
+            dragger.returnHelpersToDraggees();
+          }
+        },
+      });
+      wireHelperDragEvents(log, dragger, `item ${item.dataset.helperItem}`);
+    });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/focus.stories.ts b/packages/craftcms-garnish/stories/focus.stories.ts
new file mode 100644
index 00000000000..bdd7be39bde
--- /dev/null
+++ b/packages/craftcms-garnish/stories/focus.stories.ts
@@ -0,0 +1,105 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {Modal, getFocusableElements, isKeyboardFocusable} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+import {buildModalContainer} from './_helpers';
+
+/**
+ * Focusable matcher & focus trap — playground section 2.
+ *
+ * Run `getFocusableElements` / `isKeyboardFocusable` over a mixed container to
+ * highlight what they match, then open a focus-trap modal and Tab / Shift+Tab to
+ * see cycling stay trapped inside.
+ */
+const meta: Meta = {
+  title: 'Focus',
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const FocusableMatcherAndTrap: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        The container mixes focusable and non-focusable elements. Run the matcher
+        to highlight what <code>getFocusableElements</code> /
+        <code>isKeyboardFocusable</code> select, then open the focus-trap modal and
+        press <kbd>Tab</kbd> / <kbd>Shift+Tab</kbd>.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="highlight">Highlight focusable elements</button>
+        <button type="button" data-act="clear">Clear highlights</button>
+        <button type="button" data-act="trap-modal">Open focus-trap modal</button>
+      </div>
+      <div class="pg-focus-sample" data-focus-sample>
+        <a href="#">Link with href (focusable)</a>
+        <a>Link, no href (not focusable)</a>
+        <button type="button">Enabled button (focusable)</button>
+        <button type="button" disabled>Disabled button (not focusable)</button>
+        <input type="text" placeholder="Text input (focusable)" />
+        <input type="text" disabled placeholder="Disabled input" />
+        <span tabindex="0">Span tabindex=0 (keyboard focusable)</span>
+        <span tabindex="-1">Span tabindex=-1 (focusable, not keyboard)</span>
+        <span>Plain span (not focusable)</span>
+        <textarea placeholder="Textarea (focusable)"></textarea>
+      </div>`;
+
+    const sample = main.querySelector<HTMLElement>('[data-focus-sample]')!;
+
+    const clear = (): void => {
+      sample
+        .querySelectorAll('.pg-highlight-focusable, .pg-highlight-keyboard')
+        .forEach((el) =>
+          el.classList.remove('pg-highlight-focusable', 'pg-highlight-keyboard')
+        );
+    };
+
+    const actions: Record<string, () => void> = {
+      highlight: () => {
+        clear();
+        let focusableCount = 0;
+        let keyboardCount = 0;
+        getFocusableElements(sample).forEach((el) => {
+          el.classList.add('pg-highlight-focusable');
+          focusableCount++;
+          if (isKeyboardFocusable(el)) {
+            el.classList.add('pg-highlight-keyboard');
+            keyboardCount++;
+          }
+        });
+        log.log(
+          'focus',
+          `getFocusableElements matched ${focusableCount}; ${keyboardCount} keyboard-focusable (blue ring)`
+        );
+      },
+      clear,
+      'trap-modal': () => {
+        const container = buildModalContainer(
+          'Focus trap',
+          `<p>Tab / Shift+Tab cycles only within these three controls:</p>
+           <p>
+             <button type="button">First</button>
+             <input type="text" placeholder="Second" />
+             <a href="#">Third</a>
+           </p>`
+        );
+        const modal = new Modal(container);
+        for (const evt of ['show', 'hide', 'escape'] as const) {
+          modal.on(evt, () => log.log('focus', `focusTrap: ${evt}`));
+        }
+        log.log(
+          'focus',
+          'Opened focus-trap modal — Tab cycling is trapped inside'
+        );
+      },
+    };
+
+    main.querySelectorAll<HTMLButtonElement>('[data-act]').forEach((btn) => {
+      btn.addEventListener('click', () => actions[btn.dataset.act!]?.());
+    });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/hud.stories.ts b/packages/craftcms-garnish/stories/hud.stories.ts
new file mode 100644
index 00000000000..a56977420c2
--- /dev/null
+++ b/packages/craftcms-garnish/stories/hud.stories.ts
@@ -0,0 +1,117 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {HUD, type HUDOrientation} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+
+/**
+ * `HUD` — anchored popover — playground section 11.
+ *
+ * Each trigger in the arena anchors a `new HUD(trigger, …)`. Clicking a trigger
+ * toggles its HUD, which picks one of four orientations from the clearance around
+ * the trigger and draws a tip pointing back at it. Use the `preferredOrientation`
+ * control to bias which side it tries first.
+ */
+const meta: Meta = {
+  title: 'HUD',
+};
+export default meta;
+
+interface HUDArgs {
+  preferredOrientation: 'auto' | HUDOrientation;
+}
+
+type Story = StoryObj<HUDArgs>;
+
+const ALL_ORIENTATIONS: HUDOrientation[] = ['bottom', 'top', 'right', 'left'];
+
+export const AnchoredPopover: Story = {
+  argTypes: {
+    preferredOrientation: {
+      control: 'select',
+      options: ['auto', ...ALL_ORIENTATIONS],
+      description:
+        'Bias which orientation the HUD tries first (auto = the default bottom/top/right/left order)',
+    },
+  },
+  args: {
+    preferredOrientation: 'auto',
+  },
+  render: (args) => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Click a trigger to toggle its HUD: it picks an orientation from the
+        clearance around the trigger and draws a <strong>tip</strong> pointing back
+        at it. Triggers sit near different edges so you can see the side flip;
+        scroll or resize to watch the HUD follow.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="destroy">Destroy all HUDs</button>
+      </div>
+      <div class="pg-hud-arena" data-arena>
+        <button class="pg-hud-trigger" data-hud-trigger="top-left" style="top: 12px; left: 12px">Top-left</button>
+        <button class="pg-hud-trigger" data-hud-trigger="top-right" style="top: 12px; right: 12px">Top-right</button>
+        <button class="pg-hud-trigger" data-hud-trigger="mid-left" style="top: 50%; left: 12px">Mid-left</button>
+        <button class="pg-hud-trigger" data-hud-trigger="mid-right" style="top: 50%; right: 12px">Mid-right</button>
+        <button class="pg-hud-trigger" data-hud-trigger="bottom-center" style="bottom: 12px; left: 50%; transform: translateX(-50%)">Bottom-center</button>
+      </div>`;
+
+    const arena = main.querySelector<HTMLElement>('[data-arena]')!;
+    const huds = new Map<HTMLElement, HUD>();
+
+    const orientations =
+      args.preferredOrientation === 'auto'
+        ? ALL_ORIENTATIONS
+        : [
+            args.preferredOrientation,
+            ...ALL_ORIENTATIONS.filter((o) => o !== args.preferredOrientation),
+          ];
+
+    const hudBody = (label: string): string => `
+      <div class="pg-hud-content">
+        <h4>HUD: ${label}</h4>
+        <p>Orientation is chosen from the clearance around this trigger. Scroll or resize to watch the HUD follow.</p>
+        <button type="button" class="pg-modal-primary" data-hud-close>Close</button>
+      </div>`;
+
+    const getHud = (trigger: HTMLElement): HUD => {
+      const existing = huds.get(trigger);
+      if (existing && HUD.instances.includes(existing)) {
+        return existing;
+      }
+      const id = trigger.dataset.hudTrigger!;
+      const hud = new HUD(trigger, hudBody(id), {
+        showOnInit: false,
+        hudClass: 'hud pg-hud',
+        orientations,
+      });
+      hud.on('show', () => log.log('hud', `${id}: show`));
+      hud.on('hide', () => log.log('hud', `${id}: hide`));
+      hud.on('updateSizeAndPosition', () =>
+        log.log('hud', `${id}: positioned → orientation "${hud.orientation}"`)
+      );
+      hud.$main
+        ?.querySelector<HTMLButtonElement>('[data-hud-close]')
+        ?.addEventListener('click', () => hud.hide());
+      huds.set(trigger, hud);
+      return hud;
+    };
+
+    arena
+      .querySelectorAll<HTMLButtonElement>('[data-hud-trigger]')
+      .forEach((trigger) => {
+        trigger.addEventListener('click', () => getHud(trigger).toggle());
+      });
+
+    main
+      .querySelector<HTMLButtonElement>('[data-act="destroy"]')!
+      .addEventListener('click', () => {
+        const count = HUD.instances.length;
+        [...HUD.instances].forEach((h) => h.destroy());
+        huds.clear();
+        log.log('hud', `Destroyed ${count} HUD instance(s)`);
+      });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/modal.stories.ts b/packages/craftcms-garnish/stories/modal.stories.ts
new file mode 100644
index 00000000000..a5878d82849
--- /dev/null
+++ b/packages/craftcms-garnish/stories/modal.stories.ts
@@ -0,0 +1,211 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {Modal, type ModalSettings} from '../src/index';
+import {createEventLog, wireDragEvents, storyLayout} from './_log';
+import {buildModalContainer, buildDragModalContainer} from './_helpers';
+
+/**
+ * `Modal` — construct `new Modal(container)` instances and drive their lifecycle.
+ *
+ * Migrated from playground sections 1 (Modal) and 4 (Draggable & resizable Modal).
+ * Every `show / hide / fadeIn / fadeOut / escape` (and, for draggable/resizable
+ * modals, `dragStart / drag / dragStop`) event is piped into the event log.
+ */
+
+interface ModalArgs {
+  autoShow: boolean;
+  hideOnEsc: boolean;
+  hideOnShadeClick: boolean;
+  closeOtherModals: boolean;
+}
+
+const meta: Meta = {
+  title: 'Modal',
+};
+export default meta;
+
+type Story = StoryObj<ModalArgs>;
+
+/** Wire every demo event of a modal into the log panel. */
+function wireModalEvents(
+  log: ReturnType<typeof createEventLog>,
+  modal: Modal,
+  label: string
+): void {
+  for (const evt of ['show', 'hide', 'fadeIn', 'fadeOut', 'escape'] as const) {
+    modal.on(evt, () => log.log('modal', `${label}: ${evt}`));
+  }
+}
+
+export const Basic: Story = {
+  argTypes: {
+    autoShow: {
+      control: 'boolean',
+      description: 'Show the modal on construction',
+    },
+    hideOnEsc: {control: 'boolean', description: 'Close when Esc is pressed'},
+    hideOnShadeClick: {
+      control: 'boolean',
+      description: 'Close when the dimmed shade is clicked',
+    },
+    closeOtherModals: {
+      control: 'boolean',
+      description: 'Opening this modal hides any other visible modal',
+    },
+  },
+  args: {
+    autoShow: false,
+    hideOnEsc: true,
+    hideOnShadeClick: true,
+    closeOtherModals: false,
+  },
+  render: (args) => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Construct <code>new Modal()</code> instances and drive their lifecycle.
+        The settings controls (Esc / shade / closeOtherModals) feed straight into
+        <code>ModalSettings</code>. Open the event log to watch events fire.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="show">new Modal() + show()</button>
+        <button type="button" data-act="hide">hide()</button>
+        <button type="button" data-act="quick-show">quickShow()</button>
+        <button type="button" data-act="quick-hide">quickHide()</button>
+        <button type="button" data-act="destroy">destroy() all modals</button>
+      </div>`;
+
+    let modal: Modal | null = null;
+    const getModal = (): Modal => {
+      if (modal && Modal.instances.includes(modal)) {
+        return modal;
+      }
+      const settings: Partial<ModalSettings> = {
+        autoShow: args.autoShow,
+        hideOnEsc: args.hideOnEsc,
+        hideOnShadeClick: args.hideOnShadeClick,
+        closeOtherModals: args.closeOtherModals,
+      };
+      const container = buildModalContainer(
+        'Basic modal',
+        '<p>A plain <code>new Modal(container, settings)</code>. Try quickShow / quickHide, or toggle the settings controls and reopen.</p>'
+      );
+      modal = new Modal(container, settings);
+      wireModalEvents(log, modal, 'basic');
+      return modal;
+    };
+
+    const actions: Record<string, () => void> = {
+      show: () => getModal().show(),
+      hide: () => getModal().hide(),
+      'quick-show': () => getModal().quickShow(),
+      'quick-hide': () => getModal().quickHide(),
+      destroy: () => {
+        const count = Modal.instances.length;
+        [...Modal.instances].forEach((m) => m.destroy());
+        modal = null;
+        log.log('modal', `Destroyed ${count} modal instance(s)`);
+      },
+    };
+
+    main.querySelectorAll<HTMLButtonElement>('[data-act]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        try {
+          actions[btn.dataset.act!]?.();
+        } catch (err) {
+          log.log('modal', `Error: ${(err as Error).message}`);
+        }
+      });
+    });
+
+    return storyLayout(main);
+  },
+};
+
+interface DragModalArgs {
+  draggable: boolean;
+  headerHandleOnly: boolean;
+  resizable: boolean;
+}
+
+export const DraggableAndResizable: StoryObj<DragModalArgs> = {
+  argTypes: {
+    draggable: {control: 'boolean', description: 'Modal can be dragged'},
+    headerHandleOnly: {
+      control: 'boolean',
+      description: 'Restrict dragging to the header bar (dragHandleSelector)',
+    },
+    resizable: {control: 'boolean', description: 'Modal can be resized'},
+  },
+  args: {
+    draggable: true,
+    headerHandleOnly: true,
+    resizable: true,
+  },
+  render: (args) => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>
+        Modal's <code>draggable</code> / <code>resizable</code> options (they used
+        to throw). Open the modal and drag/resize it live — <code>dragStart / drag /
+        dragStop</code> events pipe into the log.
+      </p>
+      <div class="pg-controls">
+        <button type="button" data-act="open">Open modal (from current settings)</button>
+        <button type="button" data-act="destroy">Destroy these modals</button>
+      </div>`;
+
+    const dragModals: Modal[] = [];
+
+    const actions: Record<string, () => void> = {
+      open: () => {
+        const withHandle = args.draggable && args.headerHandleOnly;
+        const container = buildDragModalContainer(
+          'Drag / resize me',
+          '<p>Drag the modal (the header bar if <code>dragHandleSelector</code> is set) and/or grab the corner handle to resize.</p>',
+          withHandle
+        );
+        const settings: Partial<ModalSettings> = {
+          draggable: args.draggable,
+          resizable: args.resizable,
+        };
+        if (withHandle) {
+          settings.dragHandleSelector = '[data-drag-handle]';
+        }
+        const modal = new Modal(container, settings);
+        wireModalEvents(log, modal, 'drag-modal');
+        if (modal.dragger) {
+          wireDragEvents(log, modal.dragger, 'modal-drag', 'modal (move)');
+        }
+        if (modal.resizeDragger) {
+          wireDragEvents(
+            log,
+            modal.resizeDragger,
+            'modal-drag',
+            'modal (resize)'
+          );
+        }
+        dragModals.push(modal);
+        log.log('modal', 'Opened modal — drag/resize it; watch the log.');
+      },
+      destroy: () => {
+        const count = dragModals.length;
+        dragModals.splice(0).forEach((m) => m.destroy());
+        log.log('modal', `Destroyed ${count} draggable/resizable modal(s)`);
+      },
+    };
+
+    main.querySelectorAll<HTMLButtonElement>('[data-act]').forEach((btn) => {
+      btn.addEventListener('click', () => {
+        try {
+          actions[btn.dataset.act!]?.();
+        } catch (err) {
+          log.log('modal', `Error: ${(err as Error).message}`);
+        }
+      });
+    });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/stories/utilities.stories.ts b/packages/craftcms-garnish/stories/utilities.stories.ts
new file mode 100644
index 00000000000..cae29064e39
--- /dev/null
+++ b/packages/craftcms-garnish/stories/utilities.stories.ts
@@ -0,0 +1,62 @@
+import type {Meta, StoryObj} from '@storybook/html-vite';
+import {hasAttr, getDist, installActivate} from '../src/index';
+import {createEventLog, storyLayout} from './_log';
+
+/**
+ * Events & utilities — playground section 10.
+ *
+ * Small demos of core utilities (`hasAttr`, `getDist`) and the synthetic
+ * `activate` custom event (click / Space / Enter all dispatch it).
+ */
+const meta: Meta = {
+  title: 'Utilities',
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const EventsAndUtilities: Story = {
+  render: () => {
+    const log = createEventLog();
+    const main = document.createElement('div');
+    main.innerHTML = `
+      <p>Small demos of core utilities and the synthetic <code>activate</code> custom event.</p>
+      <div class="pg-controls">
+        <button type="button" data-act="hasattr">Garnish.hasAttr(this, "data-demo")</button>
+        <button type="button" data-act="getdist">getDist(0,0,3,4)</button>
+        <button type="button" data-act="activate" data-demo="yes">activate me (click / Space / Enter)</button>
+      </div>`;
+
+    const actions: Record<string, (btn: HTMLButtonElement) => void> = {
+      hasattr: (btn) => {
+        log.log(
+          'util',
+          `hasAttr(button, "data-demo") → ${hasAttr(btn, 'data-demo')}`
+        );
+      },
+      getdist: () => {
+        log.log('util', `getDist(0, 0, 3, 4) → ${getDist(0, 0, 3, 4)}`);
+      },
+      activate: (btn) => {
+        // Install the synthetic `activate` event (idempotent), then listen.
+        installActivate(btn);
+        if (!btn.dataset.activateWired) {
+          btn.addEventListener('activate', () => {
+            log.log('util', 'activate custom event fired on the button');
+          });
+          btn.dataset.activateWired = 'yes';
+          log.log(
+            'util',
+            'installActivate(button) — now click it or press Space/Enter'
+          );
+        }
+      },
+    };
+
+    main.querySelectorAll<HTMLButtonElement>('[data-act]').forEach((btn) => {
+      btn.addEventListener('click', () => actions[btn.dataset.act!]?.(btn));
+    });
+
+    return storyLayout(main);
+  },
+};
diff --git a/packages/craftcms-garnish/tests/base.test.ts b/packages/craftcms-garnish/tests/base.test.ts
new file mode 100644
index 00000000000..f140b8eb9a7
--- /dev/null
+++ b/packages/craftcms-garnish/tests/base.test.ts
@@ -0,0 +1,124 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {Base} from '../src/base';
+import {garnishClassBus} from '../src/globals';
+
+class TestBase extends Base {}
+
+describe('Base settings', () => {
+  it('shallow-merges with precedence base < defaults < settings', () => {
+    const obj = new TestBase();
+    obj.setSettings({a: 1, b: 2}, {a: 0, c: 3});
+    expect(obj.settings).toEqual({a: 1, b: 2, c: 3});
+  });
+
+  it('subsequent setSettings layers over existing (existing is lowest)', () => {
+    const obj = new TestBase();
+    obj.setSettings({a: 1});
+    obj.setSettings({b: 2});
+    expect(obj.settings).toEqual({a: 1, b: 2});
+  });
+
+  it('does NOT deep-merge nested objects (replaces wholesale)', () => {
+    const obj = new TestBase();
+    obj.setSettings({nested: {x: 1, y: 2}});
+    obj.setSettings({nested: {z: 3}});
+    expect(obj.settings!.nested).toEqual({z: 3});
+  });
+
+  it('skips null/undefined args (Object.assign semantics)', () => {
+    const obj = new TestBase();
+    obj.setSettings(undefined, {a: 1});
+    expect(obj.settings).toEqual({a: 1});
+  });
+});
+
+describe('Base pub/sub', () => {
+  it('on/trigger works at the instance level', () => {
+    const obj = new TestBase();
+    const fn = vi.fn();
+    obj.on('foo', fn);
+    obj.trigger('foo');
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('trigger also dispatches class-level handlers (instanceof)', () => {
+    garnishClassBus.clear();
+    const fn = vi.fn();
+    garnishClassBus.on(Base, 'foo', fn);
+    const obj = new TestBase();
+    obj.trigger('foo');
+    expect(fn).toHaveBeenCalledOnce();
+    expect((fn.mock.calls[0]![0] as {target: unknown}).target).toBe(obj);
+    garnishClassBus.clear();
+  });
+});
+
+describe('Base DOM listeners + disabled gate', () => {
+  let el: HTMLButtonElement;
+  beforeEach(() => {
+    el = document.createElement('button');
+    document.body.appendChild(el);
+  });
+
+  it('addListener binds and invokes with the host as `this`', () => {
+    const obj = new TestBase();
+    let receivedThis: unknown;
+    obj.addListener(el, 'click', function (this: unknown) {
+      receivedThis = this;
+    });
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(receivedThis).toBe(obj);
+  });
+
+  it('does not invoke handlers while disabled', () => {
+    const obj = new TestBase();
+    const fn = vi.fn();
+    obj.addListener(el, 'click', fn);
+    obj.disable();
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(fn).not.toHaveBeenCalled();
+    obj.enable();
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('supports a method-name string handler', () => {
+    class WithMethod extends Base {
+      called = false;
+      handleClick(): void {
+        this.called = true;
+      }
+    }
+    const obj = new WithMethod();
+    obj.addListener(el, 'click', 'handleClick');
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(obj.called).toBe(true);
+  });
+
+  it('removeListener removes a specific event', () => {
+    const obj = new TestBase();
+    const fn = vi.fn();
+    obj.addListener(el, 'click', fn);
+    obj.removeListener(el, 'click');
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('destroy triggers destroy + removes all listeners', () => {
+    const obj = new TestBase();
+    const clickFn = vi.fn();
+    const destroyFn = vi.fn();
+    obj.addListener(el, 'click', clickFn);
+    obj.on('destroy', destroyFn);
+    obj.destroy();
+    expect(destroyFn).toHaveBeenCalledOnce();
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(clickFn).not.toHaveBeenCalled();
+  });
+
+  it('bails silently when no elements resolve', () => {
+    const obj = new TestBase();
+    expect(() => obj.addListener(null, 'click', () => {})).not.toThrow();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/compat.test.ts b/packages/craftcms-garnish/tests/compat.test.ts
new file mode 100644
index 00000000000..cb34f284932
--- /dev/null
+++ b/packages/craftcms-garnish/tests/compat.test.ts
@@ -0,0 +1,394 @@
+/**
+ * Compat-layer tests — proving the legacy upgrade path works end-to-end:
+ *   - `Garnish.Base.extend({init, foo})` produces a working instance
+ *   - `this.base()` dispatches to the ancestor (incl. 2-level chains + override)
+ *   - `init` runs with the constructor args
+ *   - static members merge
+ *   - `window.Garnish` is installed under the legacy guard
+ *   - jQuery surface is feature-detected (degrades when jQuery is absent)
+ *   - (conditionally) `Garnish.Modal.extend({...})` works if Modal is exported
+ */
+
+import {describe, it, expect, beforeEach, vi} from 'vitest';
+import GarnishCompat, {
+  compatify,
+  installGarnishCompat,
+  isJquery,
+  resolveJQuery,
+  unwrapJq,
+} from '../src/compat';
+import {Base} from '../src/index';
+import * as Core from '../src/index';
+
+type AnyObj = Record<string, any>;
+
+describe('compatify / Garnish.Base.extend', () => {
+  it('produces a working instance from extend({init, foo})', () => {
+    const LegacyBase = compatify(Base);
+    const calls: string[] = [];
+
+    const Widget = LegacyBase.extend({
+      init() {
+        calls.push('init');
+      },
+      foo() {
+        return 'foo-result';
+      },
+    });
+
+    const w = new Widget() as AnyObj;
+    expect(calls).toEqual(['init']);
+    expect(w.foo()).toBe('foo-result');
+    // Real prototype chain → instanceof the modern Base.
+    expect(w).toBeInstanceOf(Base);
+  });
+
+  it('runs init with the constructor arguments', () => {
+    const LegacyBase = compatify(Base);
+    let received: unknown[] = [];
+
+    const Widget = LegacyBase.extend({
+      init(...args: unknown[]) {
+        received = args;
+      },
+    });
+
+    new Widget('a', 42, {k: 1});
+    expect(received).toEqual(['a', 42, {k: 1}]);
+  });
+
+  it('merges static members onto the constructor', () => {
+    const LegacyBase = compatify(Base);
+    const Widget = LegacyBase.extend(
+      {
+        init() {},
+      },
+      {
+        defaults: {speed: 5},
+        staticHelper() {
+          return 'helped';
+        },
+      }
+    );
+
+    expect((Widget as AnyObj).defaults).toEqual({speed: 5});
+    expect((Widget as AnyObj).staticHelper()).toBe('helped');
+  });
+
+  it('this.base() dispatches to the ancestor method', () => {
+    const LegacyBase = compatify(Base);
+
+    const Parent = LegacyBase.extend({
+      init() {},
+      greet() {
+        return 'parent';
+      },
+    });
+
+    const Child = Parent.extend({
+      init() {},
+      greet() {
+        // @ts-expect-error legacy compat affordance
+        return 'child+' + this.base();
+      },
+    });
+
+    const c = new Child() as AnyObj;
+    expect(c.greet()).toBe('child+parent');
+  });
+
+  it('this.base() works across a 2-level extend chain', () => {
+    const LegacyBase = compatify(Base);
+
+    const A = LegacyBase.extend({
+      init() {},
+      val() {
+        return 1;
+      },
+    });
+    const B = A.extend({
+      init() {},
+      val() {
+        // @ts-expect-error legacy compat affordance
+        return 10 + this.base();
+      },
+    });
+    const C = B.extend({
+      init() {},
+      val() {
+        // @ts-expect-error legacy compat affordance
+        return 100 + this.base();
+      },
+    });
+
+    const c = new C() as AnyObj;
+    // C.val → 100 + B.val (10 + A.val (1)) = 111
+    expect(c.val()).toBe(111);
+  });
+
+  it('restores this.base after the call (re-entrancy)', () => {
+    const LegacyBase = compatify(Base);
+
+    const A = LegacyBase.extend({
+      init() {},
+      step() {
+        return 'A';
+      },
+    });
+    const B = A.extend({
+      init() {},
+      step() {
+        // @ts-expect-error compat affordance
+        const inner = this.base();
+        // calling base again still resolves to the same ancestor within this frame
+        // @ts-expect-error compat affordance
+        const inner2 = this.base();
+        return `B(${inner})(${inner2})`;
+      },
+    });
+
+    const b = new B() as AnyObj;
+    expect(b.step()).toBe('B(A)(A)');
+    // After the call, this.base must be restored to the no-op (not leak A).
+    expect(typeof (b as AnyObj).base).toBe('function');
+  });
+
+  it('only the leaf init runs (init fires once)', () => {
+    const LegacyBase = compatify(Base);
+    const order: string[] = [];
+
+    const A = LegacyBase.extend({
+      init() {
+        order.push('A');
+      },
+    });
+    const B = A.extend({
+      init() {
+        order.push('B');
+      },
+    });
+
+    new B();
+    expect(order).toEqual(['B']);
+  });
+
+  it('a leaf without init inherits an ancestor init', () => {
+    const LegacyBase = compatify(Base);
+    const order: string[] = [];
+
+    const A = LegacyBase.extend({
+      init() {
+        order.push('A');
+      },
+    });
+    // B adds no init of its own.
+    const B = A.extend({
+      other() {
+        return 1;
+      },
+    });
+
+    new B();
+    expect(order).toEqual(['A']);
+  });
+
+  it('leaf init can reach the ancestor init via this.base()', () => {
+    const LegacyBase = compatify(Base);
+    const order: string[] = [];
+
+    const A = LegacyBase.extend({
+      init() {
+        order.push('A');
+      },
+    });
+    const B = A.extend({
+      init() {
+        order.push('B-before');
+        // @ts-expect-error compat affordance
+        this.base();
+        order.push('B-after');
+      },
+    });
+
+    new B();
+    expect(order).toEqual(['B-before', 'A', 'B-after']);
+  });
+
+  it('preserves getters/setters from instance members', () => {
+    const LegacyBase = compatify(Base);
+    const Widget = LegacyBase.extend({
+      init() {},
+      _n: 0,
+      get doubled() {
+        return (this as AnyObj)._n * 2;
+      },
+    });
+    const w = new Widget() as AnyObj;
+    w._n = 21;
+    expect(w.doubled).toBe(42);
+  });
+});
+
+describe('jQuery feature-detection / coercion', () => {
+  it('isJquery returns false when jQuery is absent', () => {
+    // No jQuery is installed in this package's test env.
+    expect(resolveJQuery()).toBeNull();
+    expect(isJquery({})).toBe(false);
+    expect(isJquery(null)).toBe(false);
+  });
+
+  it('unwrapJq passes through non-jQuery values unchanged', () => {
+    const el = document.createElement('div');
+    expect(unwrapJq(el)).toBe(el);
+    expect(unwrapJq('string')).toBe('string');
+    expect(unwrapJq(null)).toBe(null);
+  });
+
+  it('unwrapJq unwraps a fake jQuery collection to its first element', () => {
+    const el = document.createElement('div');
+    // Install a fake jQuery so isJquery() recognizes the collection.
+    const fakeProto = {};
+    function FakeJq(this: any) {}
+    FakeJq.prototype = fakeProto;
+    (FakeJq as any).fn = {jquery: '3.x'};
+    const coll = Object.create(fakeProto);
+    coll[0] = el;
+    coll.length = 1;
+
+    const g = globalThis as AnyObj;
+    const priorJq = g.jQuery;
+    const prior$ = g.$;
+    g.jQuery = FakeJq;
+    g.$ = FakeJq;
+    try {
+      expect(isJquery(coll)).toBe(true);
+      expect(unwrapJq(coll)).toBe(el);
+    } finally {
+      g.jQuery = priorJq;
+      g.$ = prior$;
+    }
+  });
+
+  it('constructor unwraps a jQuery-collection $container arg to a native element', () => {
+    const el = document.createElement('div');
+    const fakeProto = {};
+    function FakeJq(this: any) {}
+    FakeJq.prototype = fakeProto;
+    (FakeJq as any).fn = {jquery: '3.x'};
+    const coll = Object.create(fakeProto);
+    coll[0] = el;
+    coll.length = 1;
+
+    const g = globalThis as AnyObj;
+    const priorJq = g.jQuery;
+    g.jQuery = FakeJq;
+    try {
+      const LegacyBase = compatify(Base);
+      let receivedArg: unknown;
+      const Widget = LegacyBase.extend({
+        init(arg: unknown) {
+          receivedArg = arg;
+        },
+      });
+      new Widget(coll);
+      // init sees the unwrapped native element, not the collection.
+      expect(receivedArg).toBe(el);
+    } finally {
+      g.jQuery = priorJq;
+    }
+  });
+});
+
+describe('window.Garnish installation', () => {
+  it('installs window.Garnish under the legacy guard and is idempotent', () => {
+    const w = window as AnyObj;
+    // GarnishCompat default export already auto-installed on import.
+    expect(w.Garnish).toBeDefined();
+    expect(w.Garnish).toBe(GarnishCompat);
+
+    // Re-running install is idempotent and does not clobber the existing global.
+    const again = installGarnishCompat();
+    expect(again).toBe(GarnishCompat);
+    expect(w.Garnish).toBe(GarnishCompat);
+  });
+
+  it('exposes compatified, extend-able classes', () => {
+    const G = GarnishCompat as AnyObj;
+    expect(typeof G.Base.extend).toBe('function');
+    expect(typeof G.UiLayerManager.extend).toBe('function');
+    expect(typeof G.EscManager.extend).toBe('function');
+
+    const Custom = G.UiLayerManager.extend({
+      init() {
+        // call modern super behavior (this is `any` here via AnyObj)
+        this.base();
+      },
+    });
+    const inst = new Custom();
+    expect(inst).toBeInstanceOf(Core.UiLayerManager);
+  });
+
+  it('attaches the manager singletons', () => {
+    const G = GarnishCompat as AnyObj;
+    expect(G.escManager).toBeInstanceOf(Core.EscManager);
+    expect(G.uiLayerManager).toBeInstanceOf(Core.UiLayerManager);
+    // legacy lowercase alias
+    expect(G.shortcutManager).toBe(G.uiLayerManager);
+  });
+
+  it('restores the ShortcutManager deprecated alias', () => {
+    const G = GarnishCompat as AnyObj;
+    expect(G.ShortcutManager).toBe(G.UiLayerManager);
+  });
+
+  it('carries over utilities and constants from core', () => {
+    const G = GarnishCompat as AnyObj;
+    expect(typeof G.getDist).toBe('function');
+    expect(typeof G.ESC_KEY).toBe('number');
+    expect(typeof G.on).toBe('function');
+    expect(typeof G.off).toBe('function');
+    expect(typeof G.once).toBe('function');
+  });
+
+  it('throws a clear error when accessing $win without jQuery', () => {
+    expect(resolveJQuery()).toBeNull();
+    const G = GarnishCompat as AnyObj;
+    expect(() => G.$win).toThrowError(/jQuery is required/);
+  });
+
+  it('getFocusedElement degrades to a native element when jQuery is absent', () => {
+    const G = GarnishCompat as AnyObj;
+    // No jQuery → returns the native activeElement (or null), not a collection.
+    const result = G.getFocusedElement();
+    expect(result === null || result instanceof Element).toBe(true);
+  });
+});
+
+describe('Modal compat (conditional)', () => {
+  const Modal = (Core as AnyObj).Modal;
+  const maybe = Modal ? it : it.skip;
+
+  maybe('Garnish.Modal.extend({...}) works end-to-end', () => {
+    const G = GarnishCompat as AnyObj;
+    const ModalCompat = G.Modal;
+    expect(typeof ModalCompat.extend).toBe('function');
+
+    const calls: string[] = [];
+    const MyModal = ModalCompat.extend({
+      init(container: unknown, settings: unknown) {
+        calls.push('init');
+        // (this is `any` here via AnyObj)
+        this.base(container, settings);
+      },
+    });
+
+    const container = document.createElement('div');
+    const m = new MyModal(container, {});
+    expect(calls).toContain('init');
+    expect(m).toBeInstanceOf(Modal);
+  });
+});
+
+// Keep vi referenced for environments that tree-shake unused imports in tests.
+void vi;
+beforeEach(() => {});
diff --git a/packages/craftcms-garnish/tests/custom-events.test.ts b/packages/craftcms-garnish/tests/custom-events.test.ts
new file mode 100644
index 00000000000..855ad0dd802
--- /dev/null
+++ b/packages/craftcms-garnish/tests/custom-events.test.ts
@@ -0,0 +1,79 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {installActivate} from '../src/custom-events';
+import {globals} from '../src/globals';
+
+describe('installActivate', () => {
+  let el: HTMLButtonElement;
+
+  beforeEach(() => {
+    globals.activateEventsMuted = false;
+    el = document.createElement('button');
+    document.body.appendChild(el);
+  });
+
+  afterEach(() => {
+    el.remove();
+  });
+
+  it('dispatches an `activate` event on click', () => {
+    const dispose = installActivate(el);
+    const fn = vi.fn();
+    el.addEventListener('activate', fn);
+    el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(fn).toHaveBeenCalledOnce();
+    dispose();
+  });
+
+  it('dispatches `activate` on Space/Enter keydown', () => {
+    const dispose = installActivate(el);
+    const fn = vi.fn();
+    el.addEventListener('activate', fn);
+    el.dispatchEvent(
+      new KeyboardEvent('keydown', {keyCode: 32, bubbles: true} as never)
+    );
+    expect(fn).toHaveBeenCalledOnce();
+    dispose();
+  });
+
+  it('does not dispatch `activate` when disabled (class)', () => {
+    el.classList.add('disabled');
+    const dispose = installActivate(el);
+    const fn = vi.fn();
+    el.addEventListener('activate', fn);
+    el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(fn).not.toHaveBeenCalled();
+    dispose();
+  });
+
+  it('does not dispatch `activate` when activate events are muted', () => {
+    const dispose = installActivate(el);
+    const fn = vi.fn();
+    el.addEventListener('activate', fn);
+    globals.activateEventsMuted = true;
+    el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(fn).not.toHaveBeenCalled();
+    dispose();
+  });
+
+  it('sets tabindex="0" on a non-disabled element', () => {
+    const dispose = installActivate(el);
+    expect(el.getAttribute('tabindex')).toBe('0');
+    dispose();
+  });
+
+  it('ref-counts: a single dispose does not tear down a doubly-installed element', () => {
+    const dispose1 = installActivate(el);
+    const dispose2 = installActivate(el);
+    const fn = vi.fn();
+    el.addEventListener('activate', fn);
+
+    dispose1();
+    el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(fn).toHaveBeenCalledOnce();
+
+    dispose2();
+    el.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(fn).toHaveBeenCalledOnce(); // no further activations
+  });
+});
diff --git a/packages/craftcms-garnish/tests/disclosure-menu.test.ts b/packages/craftcms-garnish/tests/disclosure-menu.test.ts
new file mode 100644
index 00000000000..e3bdc00b25f
--- /dev/null
+++ b/packages/craftcms-garnish/tests/disclosure-menu.test.ts
@@ -0,0 +1,667 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {DisclosureMenu} from '../src/disclosure-menu';
+import {UiLayerManager} from '../src/managers/ui-layer-manager';
+import {setUiLayerManager} from '../src/managers/registry';
+import {DOWN_KEY, ESC_KEY, RETURN_KEY, TAB_KEY, UP_KEY} from '../src/constants';
+import {globals} from '../src/globals';
+
+// happy-dom notes:
+// - No layout: `getBoundingClientRect()` / `offsetWidth` / `getClientRects()`
+//   are all 0/empty. Focusable elements get `getClientRects` stubbed to look
+//   visible (`makeVisible`), and the positioning test stubs `getBoundingClientRect`
+//   + `offsetWidth/Height` (`mockRect`).
+// - No `element.animate`: the hide fade finalizes synchronously, so hide() is
+//   observable immediately (no RAF/animation mock needed — DisclosureMenu uses
+//   neither).
+
+let manager: UiLayerManager;
+let idSeq = 0;
+
+/** Stub an element's layout boxes so the focusable matcher treats it as visible. */
+function makeVisible(el: Element): void {
+  vi.spyOn(el, 'getClientRects').mockReturnValue([
+    {width: 10, height: 10},
+  ] as unknown as DOMRectList);
+}
+
+/** Stub an element's bounding rect + offset box (positioning math). */
+function mockRect(
+  el: Element,
+  top: number,
+  left: number,
+  width = 0,
+  height = 0
+): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    top,
+    left,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+  Object.defineProperty(el, 'offsetWidth', {value: width, configurable: true});
+  Object.defineProperty(el, 'offsetHeight', {
+    value: height,
+    configurable: true,
+  });
+}
+
+interface BuiltMenu {
+  trigger: HTMLButtonElement;
+  container: HTMLDivElement;
+}
+
+/**
+ * Build a trigger + an `aria-controls`-linked container with `itemLabels` items.
+ * Both the trigger and the item buttons are stubbed visible.
+ */
+function buildMenu(
+  itemLabels: string[] = [],
+  opts: {nextSibling?: boolean} = {}
+): BuiltMenu {
+  const id = `menu-${++idSeq}`;
+
+  const trigger = document.createElement('button');
+  trigger.type = 'button';
+  trigger.textContent = 'Open';
+  trigger.setAttribute('aria-controls', id);
+  makeVisible(trigger);
+  document.body.appendChild(trigger);
+
+  const container = document.createElement('div');
+  container.id = id;
+  container.className = 'menu menu--disclosure';
+  const ul = document.createElement('ul');
+  for (const labelText of itemLabels) {
+    const li = document.createElement('li');
+    const btn = document.createElement('button');
+    btn.type = 'button';
+    btn.className = 'menu-item';
+    const label = document.createElement('span');
+    label.className = 'menu-item-label';
+    label.textContent = labelText;
+    btn.appendChild(label);
+    li.appendChild(btn);
+    ul.appendChild(li);
+    makeVisible(btn);
+  }
+  container.appendChild(ul);
+
+  if (opts.nextSibling) {
+    trigger.after(container);
+  } else {
+    document.body.appendChild(container);
+  }
+
+  return {trigger, container};
+}
+
+beforeEach(() => {
+  manager = new UiLayerManager();
+  setUiLayerManager(manager);
+  DisclosureMenu.instances = [];
+  idSeq = 0;
+  document.body.innerHTML = '';
+  document.body.className = '';
+  globals.scrollContainer = window;
+  globals.rtl = false;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.useRealTimers();
+});
+
+describe('DisclosureMenu construction', () => {
+  it('applies defaults merged with passed settings', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger, {windowSpacing: 12});
+    expect(menu.settings!.windowSpacing).toBe(12);
+    expect(menu.settings!.position).toBeNull();
+    expect(menu.settings!.withSearchInput).toBe(false);
+  });
+
+  it('uses the defaults when no settings are passed', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    expect(menu.settings!.windowSpacing).toBe(5);
+  });
+
+  it('resolves the container via aria-controls and flags the trigger', () => {
+    const {trigger, container} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    expect(menu.$container).toBe(container);
+    expect(trigger.getAttribute('data-disclosure-trigger')).toBe('true');
+  });
+
+  it('resolves a container that sits as the trigger’s next sibling', () => {
+    // The container immediately follows the trigger and carries the
+    // aria-controls id (the next-sibling resolution path).
+    const id = 'sibling-menu';
+    const trigger = document.createElement('button');
+    trigger.setAttribute('aria-controls', id);
+    document.body.appendChild(trigger);
+    const container = document.createElement('div');
+    container.id = id;
+    trigger.after(container);
+    const menu = new DisclosureMenu(trigger);
+    expect(menu.$container).toBe(container);
+  });
+
+  it('throws when no disclosure container can be found', () => {
+    const trigger = document.createElement('button');
+    trigger.setAttribute('aria-controls', 'does-not-exist');
+    document.body.appendChild(trigger);
+    expect(() => new DisclosureMenu(trigger)).toThrow();
+  });
+
+  it('defaults aria-expanded to false when absent', () => {
+    const {trigger} = buildMenu();
+    new DisclosureMenu(trigger);
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('preserves an existing aria-expanded value', () => {
+    const {trigger} = buildMenu();
+    trigger.setAttribute('aria-expanded', 'true');
+    new DisclosureMenu(trigger);
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('registers itself in instances and via getInstance (trigger + container)', () => {
+    const {trigger, container} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    expect(DisclosureMenu.instances).toContain(menu);
+    expect(DisclosureMenu.getInstance(trigger)).toBe(menu);
+    expect(DisclosureMenu.getInstance(container)).toBe(menu);
+  });
+
+  it('moves the container to the end of <body>', () => {
+    const {container} = buildMenu();
+    const trigger2 = buildMenu().trigger; // some trailing element
+    void trigger2;
+    new DisclosureMenu(document.querySelector('button')!);
+    expect(document.body.lastElementChild).toBe(container);
+  });
+
+  it('warns and bails on double-instantiation', () => {
+    const {trigger} = buildMenu();
+    new DisclosureMenu(trigger);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const second = new DisclosureMenu(trigger);
+    expect(warn).toHaveBeenCalledOnce();
+    // The second instance bailed before wiring its container.
+    expect(second.$container).toBeNull();
+  });
+
+  it('coerces a selector-string trigger', () => {
+    const {trigger} = buildMenu();
+    trigger.id = 'string-trigger';
+    const menu = new DisclosureMenu('#string-trigger');
+    expect(menu.$trigger).toBe(trigger);
+  });
+});
+
+describe('DisclosureMenu show / hide', () => {
+  it('show() expands, fires beforeShow + show, sets aria-expanded', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    const beforeShow = vi.fn();
+    const onShow = vi.fn();
+    menu.on('beforeShow', beforeShow);
+    menu.on('show', onShow);
+
+    menu.show();
+
+    expect(menu.isExpanded()).toBe(true);
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+    expect(menu.$container!.classList.contains('visible')).toBe(true);
+    expect(beforeShow).toHaveBeenCalledOnce();
+    expect(onShow).toHaveBeenCalledOnce();
+  });
+
+  it('hide() collapses, fires hide, clears the visible class', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    const onHide = vi.fn();
+    menu.on('hide', onHide);
+
+    menu.show();
+    menu.hide();
+
+    expect(menu.isExpanded()).toBe(false);
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+    expect(menu.$container!.classList.contains('visible')).toBe(false);
+    expect(onHide).toHaveBeenCalledOnce();
+  });
+
+  it('show() is a no-op when already expanded', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const onShow = vi.fn();
+    menu.on('show', onShow);
+    menu.show();
+    expect(onShow).not.toHaveBeenCalled();
+  });
+
+  it('hide() is a no-op when not expanded', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const onHide = vi.fn();
+    menu.on('hide', onHide);
+    menu.hide();
+    expect(onHide).not.toHaveBeenCalled();
+  });
+
+  it('show() does nothing when the trigger is disabled', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    trigger.classList.add('disabled');
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    expect(menu.isExpanded()).toBe(false);
+  });
+
+  it('handleTriggerClick toggles open/closed', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.handleTriggerClick();
+    expect(menu.isExpanded()).toBe(true);
+    menu.handleTriggerClick();
+    expect(menu.isExpanded()).toBe(false);
+  });
+});
+
+describe('DisclosureMenu layer + Escape', () => {
+  it('adds a UI layer on show and removes it on hide', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    expect(manager.layer).toBe(0);
+    menu.show();
+    expect(manager.layer).toBe(1);
+    menu.hide();
+    expect(manager.layer).toBe(0);
+  });
+
+  it('closes on Escape via the registered shortcut', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const ev = new KeyboardEvent('keydown', {keyCode: ESC_KEY} as never);
+    manager.triggerShortcut(ev);
+    expect(menu.isExpanded()).toBe(false);
+  });
+});
+
+describe('DisclosureMenu focus management', () => {
+  it('focuses the first item on show', () => {
+    const {trigger} = buildMenu(['Alpha', 'Beta']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const first = menu.$container!.querySelector('button')!;
+    expect(document.activeElement).toBe(first);
+  });
+
+  it('falls back to focusing the container when there are no items', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    expect(menu.$container!.getAttribute('tabindex')).toBe('-1');
+    expect(document.activeElement).toBe(menu.$container);
+  });
+
+  it('restores focus to the trigger on hide when focus was inside', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const item = menu.$container!.querySelector('button')!;
+    item.focus();
+    expect(document.activeElement).toBe(item);
+    menu.hide();
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+describe('DisclosureMenu keyboard navigation', () => {
+  it('Arrow Down / Up move focus between items', () => {
+    const {trigger, container} = buildMenu(['Alpha', 'Beta', 'Gamma']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const [a, b] = Array.from(container.querySelectorAll('button'));
+    a!.focus();
+
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {keyCode: DOWN_KEY, bubbles: true} as never)
+    );
+    expect(document.activeElement).toBe(b);
+
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {keyCode: UP_KEY, bubbles: true} as never)
+    );
+    expect(document.activeElement).toBe(a);
+  });
+
+  it('Shift+Tab on the first item returns focus to the trigger', () => {
+    const {trigger, container} = buildMenu(['Alpha', 'Beta']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    const first = container.querySelector('button')!;
+    first.focus();
+    const ev = new KeyboardEvent('keydown', {
+      keyCode: TAB_KEY,
+      shiftKey: true,
+      bubbles: true,
+    } as never);
+    Object.defineProperty(ev, 'target', {value: first});
+    container.dispatchEvent(ev);
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it('Tab on the trigger while expanded moves focus into the menu', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+    trigger.focus();
+    const ev = new KeyboardEvent('keydown', {keyCode: TAB_KEY} as never);
+    trigger.dispatchEvent(ev);
+    const first = menu.$container!.querySelector('button')!;
+    expect(document.activeElement).toBe(first);
+  });
+});
+
+describe('DisclosureMenu type-ahead search', () => {
+  it('focuses the first item whose text starts with the typed string', () => {
+    const {trigger, container} = buildMenu(['Apple', 'Banana', 'Cherry']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 'b', bubbles: true} as never)
+    );
+
+    const banana = Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent!.includes('Banana')
+    );
+    expect(document.activeElement).toBe(banana);
+  });
+
+  it('accumulates the search buffer across keystrokes and clears it', () => {
+    const {trigger, container} = buildMenu(['Car', 'Cat', 'Dog']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 'c', bubbles: true} as never)
+    );
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 'a', bubbles: true} as never)
+    );
+    container.dispatchEvent(
+      new KeyboardEvent('keydown', {key: 't', bubbles: true} as never)
+    );
+    expect(menu.searchStr).toBe('cat');
+    const cat = Array.from(container.querySelectorAll('button')).find((b) =>
+      b.textContent!.includes('Cat')
+    );
+    expect(document.activeElement).toBe(cat);
+
+    menu.clearSearchStr();
+    expect(menu.searchStr).toBe('');
+  });
+});
+
+describe('DisclosureMenu outside-click dismissal', () => {
+  it('hides when a mousedown lands outside the menu', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const outside = document.createElement('div');
+    document.body.appendChild(outside);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+
+    outside.dispatchEvent(new MouseEvent('mousedown', {bubbles: true}));
+    expect(menu.isExpanded()).toBe(false);
+  });
+
+  it('does not hide when the mousedown is inside the menu', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    menu.show();
+
+    const item = container.querySelector('button')!;
+    item.dispatchEvent(new MouseEvent('mousedown', {bubbles: true}));
+    expect(menu.isExpanded()).toBe(true);
+  });
+});
+
+describe('DisclosureMenu item building', () => {
+  it('addItem builds a button item and returns its element', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const el = menu.addItem({label: 'Rename'});
+    expect(el.tagName).toBe('BUTTON');
+    expect(el.classList.contains('menu-item')).toBe(true);
+    expect(el.querySelector('.menu-item-label')!.textContent).toBe('Rename');
+  });
+
+  it('infers a link item from a url', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const el = menu.addItem({label: 'Edit', url: '/edit'});
+    expect(el.tagName).toBe('A');
+    expect((el as HTMLAnchorElement).getAttribute('href')).toBe('/edit');
+  });
+
+  it('applies selected / destructive / disabled flags', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const el = menu.addItem({
+      label: 'Delete',
+      selected: true,
+      destructive: true,
+      disabled: true,
+    });
+    expect(el.classList.contains('sel')).toBe(true);
+    expect(el.classList.contains('error')).toBe(true);
+    expect(el.getAttribute('data-destructive')).toBe('true');
+    expect(el.classList.contains('disabled')).toBe(true);
+  });
+
+  it('sets the formsubmit class + data-action for action items', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const el = menu.addItem({label: 'Save', action: 'entries/save'});
+    expect(el.classList.contains('formsubmit')).toBe(true);
+    expect(el.getAttribute('data-action')).toBe('entries/save');
+  });
+
+  it('throws on an unsupported item configuration', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    expect(() => menu.createItem(42 as never)).toThrow();
+  });
+
+  it('addGroup creates a heading + ul and addItem fills the last group', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const ul = menu.addGroup('Actions');
+    expect(ul.tagName).toBe('UL');
+    expect(menu.$container!.querySelector('h3')!.textContent).toBe('Actions');
+    const el = menu.addItem({label: 'One'});
+    expect(el.closest('ul')).toBe(ul);
+  });
+
+  it('getFirstDestructiveGroup finds the group with a destructive item', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const safe = menu.addGroup();
+    menu.addItem({label: 'Safe'}, safe);
+    const danger = menu.addGroup();
+    menu.addItem({label: 'Delete', destructive: true}, danger);
+    expect(menu.getFirstDestructiveGroup()).toBe(danger);
+  });
+
+  it('removeItem drops the item and empties the group', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const ul = menu.addGroup();
+    const el = menu.addItem({label: 'Lonely'}, ul);
+    menu.removeItem(el);
+    expect(document.body.contains(ul)).toBe(false);
+  });
+
+  it('addHr inserts a horizontal rule', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const hr = menu.addHr();
+    expect(hr.tagName).toBe('HR');
+    expect(menu.$container!.contains(hr)).toBe(true);
+  });
+
+  it('hasVisibleItems reflects whether any item is shown', () => {
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const el = menu.addItem({label: 'Visible'});
+    expect(menu.hasVisibleItems()).toBe(true);
+    menu.hideItem(el);
+    expect(menu.hasVisibleItems()).toBe(false);
+  });
+});
+
+describe('DisclosureMenu item selection', () => {
+  it('runs onActivate and hides the menu on activate', () => {
+    vi.useFakeTimers();
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const onActivate = vi.fn();
+    const el = menu.addItem({label: 'Go', onActivate});
+    makeVisible(el);
+    menu.show();
+
+    el.dispatchEvent(new CustomEvent('activate'));
+    expect(onActivate).toHaveBeenCalledOnce();
+    expect(onActivate).toHaveBeenCalledWith(el);
+
+    // hide() is scheduled a tick later.
+    vi.advanceTimersByTime(1);
+    expect(menu.isExpanded()).toBe(false);
+  });
+
+  it('falls back to the legacy `callback` when onActivate is absent', () => {
+    vi.useFakeTimers();
+    const {trigger} = buildMenu();
+    const menu = new DisclosureMenu(trigger);
+    const callback = vi.fn();
+    const el = menu.addItem({label: 'Go', callback});
+    el.dispatchEvent(new CustomEvent('activate'));
+    expect(callback).toHaveBeenCalledOnce();
+  });
+});
+
+describe('DisclosureMenu search input', () => {
+  it('builds a search input when withSearchInput is set', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger, {withSearchInput: true});
+    expect(menu.$searchInput).not.toBeNull();
+    expect(menu.$container!.querySelector('.search-container')).not.toBeNull();
+  });
+
+  it('enables search via the data-with-search-input attribute', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    container.setAttribute('data-with-search-input', '');
+    const menu = new DisclosureMenu(trigger);
+    expect(menu.$searchInput).not.toBeNull();
+  });
+
+  it('filters items by typed text and clears the filter', () => {
+    const {trigger, container} = buildMenu(['Apple', 'Banana']);
+    const menu = new DisclosureMenu(trigger, {withSearchInput: true});
+
+    menu.$searchInput!.value = 'app';
+    menu.$searchInput!.dispatchEvent(new Event('input'));
+
+    const items = Array.from(container.querySelectorAll('li'));
+    const apple = items.find((li) => li.textContent!.includes('Apple'))!;
+    const banana = items.find((li) => li.textContent!.includes('Banana'))!;
+    expect(apple.classList.contains('filtered')).toBe(false);
+    expect(banana.classList.contains('filtered')).toBe(true);
+
+    menu.$searchInput!.value = '';
+    menu.$searchInput!.dispatchEvent(new Event('input'));
+    expect(banana.classList.contains('filtered')).toBe(false);
+  });
+
+  it('Return inside the search input does not submit (preventDefault)', () => {
+    const {trigger} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger, {withSearchInput: true});
+    const ev = new KeyboardEvent('keydown', {
+      keyCode: RETURN_KEY,
+      cancelable: true,
+    } as never);
+    menu.$searchInput!.dispatchEvent(ev);
+    expect(ev.defaultPrevented).toBe(true);
+  });
+});
+
+describe('DisclosureMenu positioning (mocked layout)', () => {
+  it('positions below the trigger when there is room and sets top/left', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    // Trigger near the top; menu short → fits below.
+    mockRect(trigger, 50, 100, 80, 24);
+    mockRect(container, 0, 0, 160, 120);
+    menu.$alignmentElement = trigger;
+
+    menu.setContainerPosition();
+
+    // top is the trigger's bottom (offset.top 50 + height 24 = 74).
+    expect(container.style.top).toBe('74px');
+    expect(container.style.left).not.toBe('');
+  });
+
+  it('positions above the trigger when there is no room below', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    // Trigger near the bottom of an 768px viewport, tall menu → must flip above.
+    mockRect(trigger, 740, 100, 80, 24);
+    mockRect(container, 0, 0, 160, 400);
+    menu.$alignmentElement = trigger;
+
+    menu.setContainerPosition();
+
+    // Above → top is less than the trigger's own top (740).
+    expect(parseFloat(container.style.top)).toBeLessThan(740);
+  });
+
+  it('honors position: "below" even when above has more room', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger, {position: 'below'});
+    mockRect(trigger, 700, 100, 80, 24);
+    mockRect(container, 0, 0, 160, 400);
+    menu.$alignmentElement = trigger;
+
+    menu.setContainerPosition();
+    // Forced below → top is the trigger bottom (724).
+    expect(container.style.top).toBe('724px');
+  });
+});
+
+describe('DisclosureMenu destroy', () => {
+  it('drops registrations, removes from instances, fires destroy', () => {
+    const {trigger, container} = buildMenu(['Alpha']);
+    const menu = new DisclosureMenu(trigger);
+    const onDestroy = vi.fn();
+    menu.on('destroy', onDestroy);
+
+    menu.destroy();
+
+    expect(onDestroy).toHaveBeenCalledOnce();
+    expect(DisclosureMenu.instances).not.toContain(menu);
+    expect(DisclosureMenu.getInstance(trigger)).toBeUndefined();
+    expect(DisclosureMenu.getInstance(container)).toBeUndefined();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/dom-listeners.test.ts b/packages/craftcms-garnish/tests/dom-listeners.test.ts
new file mode 100644
index 00000000000..9a4a93018a5
--- /dev/null
+++ b/packages/craftcms-garnish/tests/dom-listeners.test.ts
@@ -0,0 +1,96 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {DomListenerRegistry} from '../src/dom-listeners';
+
+function makeHost(disabled = false) {
+  return {disabled};
+}
+
+describe('DomListenerRegistry', () => {
+  let el: HTMLElement;
+
+  beforeEach(() => {
+    el = document.createElement('div');
+    document.body.appendChild(el);
+  });
+
+  it('binds and fires a native event', () => {
+    const reg = new DomListenerRegistry(makeHost());
+    const fn = vi.fn();
+    reg.add(el, 'click', fn);
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(fn).toHaveBeenCalledOnce();
+  });
+
+  it('short-circuits while the host is disabled', () => {
+    const host = makeHost(true);
+    const reg = new DomListenerRegistry(host);
+    const fn = vi.fn();
+    reg.add(el, 'click', fn);
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('supports comma-split multiple events', () => {
+    const reg = new DomListenerRegistry(makeHost());
+    const fn = vi.fn();
+    reg.add(el, 'click,mousedown', fn);
+    el.dispatchEvent(new MouseEvent('click'));
+    el.dispatchEvent(new MouseEvent('mousedown'));
+    expect(fn).toHaveBeenCalledTimes(2);
+  });
+
+  it('removes by namespace only (namespaced remove)', () => {
+    const reg = new DomListenerRegistry(makeHost());
+    const a = vi.fn();
+    const b = vi.fn();
+    reg.add(el, 'click.ns1', a);
+    reg.add(el, 'click.ns2', b);
+    reg.remove(el, '.ns1');
+    el.dispatchEvent(new MouseEvent('click'));
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalledOnce();
+  });
+
+  it('removeAllOn removes every listener on an element', () => {
+    const reg = new DomListenerRegistry(makeHost());
+    const fn = vi.fn();
+    reg.add(el, 'click', fn);
+    reg.add(el, 'mousedown', fn);
+    reg.removeAllOn(el);
+    el.dispatchEvent(new MouseEvent('click'));
+    el.dispatchEvent(new MouseEvent('mousedown'));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('delegation: only fires when the event originates within the selector', () => {
+    el.innerHTML =
+      '<button class="target">x</button><span class="other">y</span>';
+    const reg = new DomListenerRegistry(makeHost());
+    const fn = vi.fn();
+    reg.add(el, 'click', fn, {delegate: '.target'});
+
+    el.querySelector('.target')!.dispatchEvent(
+      new MouseEvent('click', {bubbles: true})
+    );
+    expect(fn).toHaveBeenCalledOnce();
+
+    el.querySelector('.other')!.dispatchEvent(
+      new MouseEvent('click', {bubbles: true})
+    );
+    expect(fn).toHaveBeenCalledOnce(); // unchanged
+  });
+
+  it('removeAll tears down everything', () => {
+    const reg = new DomListenerRegistry(makeHost());
+    const fn = vi.fn();
+    const el2 = document.createElement('div');
+    document.body.appendChild(el2);
+    reg.add(el, 'click', fn);
+    reg.add(el2, 'click', fn);
+    reg.removeAll();
+    el.dispatchEvent(new MouseEvent('click'));
+    el2.dispatchEvent(new MouseEvent('click'));
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/drag-drop.test.ts b/packages/craftcms-garnish/tests/drag-drop.test.ts
new file mode 100644
index 00000000000..2566204fd9d
--- /dev/null
+++ b/packages/craftcms-garnish/tests/drag-drop.test.ts
@@ -0,0 +1,831 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {Drag} from '../src/drag/drag';
+import {DragDrop} from '../src/drag/drag-drop';
+import {globals} from '../src/globals';
+
+// happy-dom notes (see doc 09 §7):
+// - No layout: `getBoundingClientRect()` returns zeros and `offsetWidth/Height`
+//   are 0. We mock `getOuterWidth/getOuterHeight` (utils/dom) for the geometry
+//   that matters, and `getBoundingClientRect` where getOffset is read.
+// - `element.animate` is `undefined`, so the return-to-source / fade WAAPI paths
+//   take the no-WAAPI fallback and resolve synchronously — exactly the path we
+//   can assert. The real tweens are playground-only.
+// - The RAF-deferred hooks + the lag-follow loop are made synchronous by
+//   stubbing the animation module's `requestAnimationFrame`. (Note: the lag loop
+//   re-schedules itself every frame; with a sync stub that would recurse
+//   forever, so tests that touch `startDragging` cancel the loop or never drive
+//   a real pointer move — see `runOneFrame` below.)
+vi.mock('../src/utils/animation', async (importOriginal) => {
+  const actual = await importOriginal<object>();
+  return {
+    ...actual,
+    // Default: defer to a manual queue so the self-rescheduling lag loop does
+    // not infinitely recurse. Tests flush the queue explicitly when needed.
+    requestAnimationFrame: (cb: FrameRequestCallback): number => {
+      rafQueue.push(cb);
+      return rafQueue.length;
+    },
+    cancelAnimationFrame: (handle: number): void => {
+      // handles are 1-based indices into rafQueue
+      if (handle > 0 && handle <= rafQueue.length) {
+        rafQueue[handle - 1] = undefined;
+      }
+    },
+  };
+});
+
+let rafQueue: Array<FrameRequestCallback | undefined> = [];
+
+/** Run every currently-queued RAF callback exactly once (new ones are deferred). */
+function flushRaf(): void {
+  const current = rafQueue;
+  rafQueue = [];
+  for (const cb of current) {
+    cb?.(0);
+  }
+}
+
+/**
+ * Private-method shape used to `vi.spyOn` Drag internals. `vi.spyOn(d as never,
+ * ...)` typechecks for reads but not for `.mockImplementation`, so we cast
+ * through this when we need to stub.
+ */
+interface DragPrivate {
+  _createHelper: (index: number) => void;
+  _updateHelperPos: () => void;
+  _getHelperTarget: (i: number, real?: boolean) => {left: number; top: number};
+}
+
+function makeItem(cls = ''): HTMLElement {
+  const el = document.createElement('div');
+  if (cls) el.className = cls;
+  document.body.appendChild(el);
+  return el;
+}
+
+/** Stub an element's bounding rect so getOffset/hitTest read a known box. */
+function mockRect(
+  el: Element,
+  top: number,
+  left: number,
+  width = 0,
+  height = 0
+): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    top,
+    left,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  document.body.className = '';
+  rafQueue = [];
+  globals.rtl = false;
+  globals.activateEventsMuted = false;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Drag — settings + defaults
+// ---------------------------------------------------------------------------
+
+describe('Drag settings + defaults', () => {
+  it('merges Drag.defaults with passed settings, preserving BaseDrag keys', () => {
+    const d = new Drag(null, {singleHelper: true, minMouseDist: 7});
+    expect(d.settings!.singleHelper).toBe(true);
+    expect(d.settings!.minMouseDist).toBe(7);
+    // Drag default survives.
+    expect(d.settings!.hideDraggee).toBe(true);
+    expect(d.settings!.helperBaseZindex).toBe(1000);
+    // BaseDrag default survives.
+    expect(d.settings!.ignoreHandleSelector).toBe(
+      'input, textarea, button, select, .btn'
+    );
+  });
+
+  it('supports the param-shift form: new Drag(settingsObj)', () => {
+    const d = new Drag({helperOpacity: 0.5});
+    expect(d.settings!.helperOpacity).toBe(0.5);
+    expect(d.$items).toEqual([]);
+  });
+
+  it('exposes the documented Drag defaults', () => {
+    expect(Drag.defaults.filter).toBeNull();
+    expect(Drag.defaults.singleHelper).toBe(false);
+    expect(Drag.defaults.helperLagBase).toBe(3);
+    expect(Drag.defaults.helperLagIncrementDividend).toBe(1.5);
+    expect(Drag.defaults.helperSpacingX).toBe(5);
+    expect(Drag.defaults.helperSpacingY).toBe(5);
+  });
+
+  it('starts with empty draggee/helper state', () => {
+    const d = new Drag();
+    expect(d.$draggee).toEqual([]);
+    expect(d.helpers).toEqual([]);
+    expect(d.allowDragging()).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — findDraggee
+// ---------------------------------------------------------------------------
+
+describe('Drag.findDraggee', () => {
+  it('returns [$targetItem] when filter is null', () => {
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.$targetItem = a;
+    expect(d.findDraggee()).toEqual([a]);
+  });
+
+  it('returns [] when filter is null and no target', () => {
+    const d = new Drag();
+    expect(d.findDraggee()).toEqual([]);
+  });
+
+  it('calls a function filter and coerces the result', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const d = new Drag([a], {filter: () => [a, b]});
+    d.$targetItem = a;
+    expect(d.findDraggee()).toEqual([a, b]);
+  });
+
+  it('treats a string filter as a selector over $items', () => {
+    const a = makeItem('sel');
+    const b = makeItem();
+    const c = makeItem('sel');
+    const d = new Drag([a, b, c], {filter: '.sel'});
+    expect(d.findDraggee()).toEqual([a, c]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — setDraggee + helper creation
+// ---------------------------------------------------------------------------
+
+describe('Drag.setDraggee', () => {
+  function setup(settings = {}): {d: Drag; a: HTMLElement; b: HTMLElement} {
+    const a = makeItem();
+    const b = makeItem();
+    const d = new Drag([a, b], settings);
+    d.$targetItem = a;
+    d.draggeeDisplay = 'block';
+    vi.spyOn(d as unknown as DragPrivate, '_createHelper').mockImplementation(
+      () => {}
+    );
+    return {d, a, b};
+  }
+
+  it('forces the target to index 0 and records its position', () => {
+    const {d, a, b} = setup();
+    d.setDraggee([b, a]);
+    expect(d.$draggee[0]).toBe(a);
+    expect(d.$draggee).toEqual([a, b]);
+    // The target was at index 1 in the input set ([b, a]).
+    expect(d.targetItemPositionInDraggee).toBe(1);
+  });
+
+  it('adds the target to the draggee set if missing', () => {
+    const {d, a, b} = setup();
+    d.setDraggee([b]);
+    expect(d.$draggee).toEqual([a, b]);
+  });
+
+  it('creates one helper per draggee by default', () => {
+    const {d, a, b} = setup();
+    const spy = vi.spyOn(d as unknown as DragPrivate, '_createHelper');
+    d.setDraggee([a, b]);
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it('creates a single helper when singleHelper is set', () => {
+    const {d, a, b} = setup({singleHelper: true});
+    const spy = vi.spyOn(d as unknown as DragPrivate, '_createHelper');
+    d.setDraggee([a, b]);
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith(0);
+  });
+
+  it('hideDraggee → visibility:hidden on every draggee', () => {
+    const {d, a, b} = setup({hideDraggee: true});
+    d.setDraggee([a, b]);
+    expect(a.style.visibility).toBe('hidden');
+    expect(b.style.visibility).toBe('hidden');
+  });
+
+  it('removeDraggee → display:none on every draggee', () => {
+    const {d, a, b} = setup({
+      hideDraggee: false,
+      removeDraggee: true,
+    });
+    d.setDraggee([a, b]);
+    expect(a.style.display).toBe('none');
+    expect(b.style.display).toBe('none');
+  });
+
+  it('collapseDraggees → target hidden via visibility, others via display', () => {
+    const {d, a, b} = setup({
+      hideDraggee: false,
+      collapseDraggees: true,
+    });
+    d.setDraggee([a, b]);
+    expect(a.style.visibility).toBe('hidden');
+    expect(b.style.display).toBe('none');
+  });
+});
+
+describe('Drag.appendDraggee', () => {
+  it('appends new draggees and creates helpers for the new indices', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const c = makeItem();
+    const d = new Drag([a, b, c]);
+    d.$targetItem = a;
+    d.draggeeDisplay = 'block';
+    vi.spyOn(d as unknown as DragPrivate, '_createHelper').mockImplementation(
+      () => {}
+    );
+    d.$draggee = [a];
+    const spy = vi.spyOn(d as unknown as DragPrivate, '_createHelper');
+    d.appendDraggee([b, c]);
+    expect(d.$draggee).toEqual([a, b, c]);
+    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveBeenCalledWith(1);
+    expect(spy).toHaveBeenCalledWith(2);
+  });
+
+  it('early-returns on an empty new set', () => {
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.$draggee = [a];
+    const spy = vi.spyOn(d as unknown as DragPrivate, '_createHelper');
+    d.appendDraggee([]);
+    expect(spy).not.toHaveBeenCalled();
+    expect(d.$draggee).toEqual([a]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — _createHelper (clone shape)
+// ---------------------------------------------------------------------------
+
+describe('Drag._createHelper', () => {
+  function setup(settings = {}): {d: Drag; a: HTMLElement} {
+    const a = makeItem();
+    const d = new Drag([a], settings);
+    d.$targetItem = a;
+    d.$draggee = [a];
+    d.draggeeDisplay = 'block';
+    d.mouseX = 100;
+    d.mouseY = 50;
+    d.mouseOffsetX = 10;
+    d.mouseOffsetY = 5;
+    // happy-dom returns 0 for offsetWidth/Height; the helper just needs *some*
+    // sizing call to succeed. getOuterWidth/Height read offsetWidth/Height (0).
+    return {d, a};
+  }
+
+  function callCreate(d: Drag, index: number): void {
+    (d as unknown as {_createHelper: (i: number) => void})._createHelper(index);
+  }
+
+  it('clones the draggee, adds .draghelper, and appends to body', () => {
+    const {d, a} = setup();
+    a.appendChild(document.createElement('span'));
+    callCreate(d, 0);
+    expect(d.helpers).toHaveLength(1);
+    const helper = d.helpers[0]!;
+    expect(helper.classList.contains('draghelper')).toBe(true);
+    expect(helper.parentElement).toBe(document.body);
+    // Deep clone preserved the child.
+    expect(helper.querySelector('span')).not.toBeNull();
+  });
+
+  it('blanks every [name] attribute on the clone', () => {
+    const {d, a} = setup();
+    const input = document.createElement('input');
+    input.setAttribute('name', 'foo');
+    a.appendChild(input);
+    callCreate(d, 0);
+    const helperInput = d.helpers[0]!.querySelector('input')!;
+    expect(helperInput.getAttribute('name')).toBe('');
+  });
+
+  it('sets absolute position, border-box sizing, z-index, and display', () => {
+    const {d, a} = setup();
+    callCreate(d, 0);
+    const helper = d.helpers[0]!;
+    expect(helper.style.position).toBe('absolute');
+    expect(helper.style.boxSizing).toBe('border-box');
+    expect(helper.style.display).toBe('block');
+    expect(helper.style.pointerEvents).toBe('none');
+    // zIndex = base(1000) + draggeeLength(1) - index(0) = 1001
+    expect(helper.style.zIndex).toBe('1001');
+    // real=true target: mouseX - mouseOffsetX = 90, mouseY - mouseOffsetY = 45
+    expect(helper.style.left).toBe('90px');
+    expect(helper.style.top).toBe('45px');
+    void a;
+  });
+
+  it('applies helperOpacity when not 1', () => {
+    const {d} = setup({helperOpacity: 0.4});
+    callCreate(d, 0);
+    expect(d.helpers[0]!.style.opacity).toBe('0.4');
+  });
+
+  it('invokes a function helper wrapper', () => {
+    const wrapper = document.createElement('div');
+    wrapper.className = 'wrap';
+    const helperFn = vi.fn((clone: HTMLElement) => {
+      wrapper.appendChild(clone);
+      return wrapper;
+    });
+    const {d} = setup({helper: helperFn});
+    callCreate(d, 0);
+    expect(helperFn).toHaveBeenCalled();
+    expect(d.helpers[0]).toBe(wrapper);
+    expect(wrapper.parentElement).toBe(document.body);
+  });
+
+  it('wraps the clone into an element helper', () => {
+    const wrapper = document.createElement('div');
+    wrapper.className = 'wrap';
+    document.body.appendChild(wrapper);
+    const {d} = setup({helper: wrapper});
+    callCreate(d, 0);
+    expect(d.helpers[0]).toBe(wrapper);
+    expect(wrapper.querySelector('.draghelper')).not.toBeNull();
+  });
+
+  it('copies input values when copyDraggeeInputValuesToHelper is set', () => {
+    const {d, a} = setup({copyDraggeeInputValuesToHelper: true});
+    const input = document.createElement('input');
+    input.value = 'hello';
+    a.appendChild(input);
+    callCreate(d, 0);
+    // The clone's [name] is blanked but the value is copied across.
+    const helperInput = d.helpers[0]!.querySelector('input')!;
+    expect(helperInput.value).toBe('hello');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — helper geometry
+// ---------------------------------------------------------------------------
+
+describe('Drag.getHelperTargetX/Y + _getHelperTarget', () => {
+  function setup(settings = {}): Drag {
+    const d = new Drag(null, settings);
+    d.mouseX = 200;
+    d.mouseY = 120;
+    d.mouseOffsetX = 30;
+    d.mouseOffsetY = 20;
+    return d;
+  }
+
+  it('subtracts the grab offset by default', () => {
+    const d = setup();
+    expect(d.getHelperTargetX()).toBe(170);
+    expect(d.getHelperTargetY()).toBe(100);
+  });
+
+  it('snaps to the cursor when moveHelperToCursor is set (real=false)', () => {
+    const d = setup({moveHelperToCursor: true});
+    expect(d.getHelperTargetX()).toBe(200);
+    expect(d.getHelperTargetY()).toBe(120);
+  });
+
+  it('ignores moveHelperToCursor when real=true', () => {
+    const d = setup({moveHelperToCursor: true});
+    expect(d.getHelperTargetX(true)).toBe(170);
+    expect(d.getHelperTargetY(true)).toBe(100);
+  });
+
+  it('applies per-index spacing in _getHelperTarget', () => {
+    const d = setup({helperSpacingX: 5, helperSpacingY: 8});
+    const pos = (
+      d as unknown as {
+        _getHelperTarget: (
+          i: number,
+          r?: boolean
+        ) => {left: number; top: number};
+      }
+    )._getHelperTarget(2, true);
+    // 170 + 5*2 = 180 ; 100 + 8*2 = 116
+    expect(pos).toEqual({left: 180, top: 116});
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — lag-follow loop
+// ---------------------------------------------------------------------------
+
+describe('Drag._updateHelperPos', () => {
+  it('eases each helper toward its target and recomputes targets on move', () => {
+    const helperEl = makeItem();
+    const d = new Drag(null, {helperLagBase: 2});
+    d.helpers = [helperEl];
+    d.helperPositions = [{left: 0, top: 0}];
+    d.helperTargets = [{left: 0, top: 0}];
+    d.helperLagIncrement = 0;
+    d.mouseX = 100;
+    d.mouseY = 40;
+    d.mouseOffsetX = 0;
+    d.mouseOffsetY = 0;
+    d.lastMouseX = null;
+    d.lastMouseY = null;
+
+    (d as unknown as {_updateHelperPos: () => void})._updateHelperPos();
+
+    // Mouse moved → target recomputed to (100, 40). Eased by 1/lag (lag=2):
+    // 0 + (100-0)/2 = 50 ; 0 + (40-0)/2 = 20
+    expect(d.helperPositions[0]).toEqual({left: 50, top: 20});
+    expect(helperEl.style.left).toBe('50px');
+    expect(helperEl.style.top).toBe('20px');
+    expect(d.lastMouseX).toBe(100);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — startDragging / stopDragging ordering
+// ---------------------------------------------------------------------------
+
+describe('Drag.startDragging / stopDragging', () => {
+  it('fires onBeforeDragStart first, snapshots, builds otherItems, mutes events', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const order: string[] = [];
+    const d = new Drag([a, b], {
+      onBeforeDragStart: () => order.push('before'),
+    });
+    d.$targetItem = a;
+    // setDraggee is the snapshot step; record ordering relative to onBefore.
+    vi.spyOn(d, 'setDraggee').mockImplementation((set) => {
+      order.push('setDraggee');
+      d.$draggee = set;
+    });
+    // Avoid driving the self-rescheduling lag loop; we only assert wiring.
+    vi.spyOn(
+      d as unknown as DragPrivate,
+      '_updateHelperPos'
+    ).mockImplementation(() => {});
+
+    d.startDragging();
+
+    expect(order).toEqual(['before', 'setDraggee']);
+    expect(d.dragging).toBe(true);
+    expect(globals.activateEventsMuted).toBe(true);
+    // otherItems = $items not in $draggee. $draggee = [a].
+    expect(d.otherItems).toEqual([b]);
+    expect(d.totalOtherItems).toBe(1);
+    // Lag loop was scheduled.
+    expect(d.updateHelperPosFrame).not.toBeNull();
+  });
+
+  it('cancels the lag-follow RAF in stopDragging', () => {
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.$targetItem = a;
+    vi.spyOn(
+      d as unknown as DragPrivate,
+      '_updateHelperPos'
+    ).mockImplementation(() => {});
+    d.startDragging();
+    expect(d.updateHelperPosFrame).not.toBeNull();
+    d.stopDragging();
+    expect(d.updateHelperPosFrame).toBeNull();
+    expect(d.dragging).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — drag() virtual midpoint
+// ---------------------------------------------------------------------------
+
+describe('Drag.drag', () => {
+  it('computes the draggee virtual midpoint from fresh coords', () => {
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.mouseX = 100;
+    d.mouseY = 60;
+    d.mouseOffsetX = 20;
+    d.mouseOffsetY = 10;
+    d.targetItemWidth = 40;
+    d.targetItemHeight = 20;
+    // super.drag walks the auto-scroll path; stub onDrag to avoid RAF noise.
+    vi.spyOn(d, 'onDrag').mockImplementation(() => {});
+    d.drag(false);
+    // mouseX - mouseOffsetX + width/2 = 100 - 20 + 20 = 100
+    expect(d.draggeeVirtualMidpointX).toBe(100);
+    // mouseY - mouseOffsetY + height/2 = 60 - 10 + 10 = 60
+    expect(d.draggeeVirtualMidpointY).toBe(60);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — returnHelpersToDraggees / fadeOutHelpers (no-WAAPI sync path)
+// ---------------------------------------------------------------------------
+
+describe('Drag.returnHelpersToDraggees', () => {
+  it('restores draggees, removes helpers, toggles the flag, fires the hook', () => {
+    const a = makeItem();
+    const helper = makeItem();
+    mockRect(a, 12, 8); // getOffset(a) → {top:12, left:8}
+    const d = new Drag([a], {hideDraggee: true});
+    d.$draggee = [a];
+    d.helpers = [helper];
+    d.draggeeDisplay = 'block';
+    const onReturn = vi.fn();
+    d.settings!.onReturnHelpersToDraggees = onReturn;
+
+    d.returnHelpersToDraggees();
+
+    // No element.animate in happy-dom → finalize() ran synchronously.
+    expect(helper.parentElement).toBeNull(); // removed
+    expect(d.helpers).toEqual([]);
+    // _show() restores the stashed inline display (none was stashed here, so it
+    // clears to ''), and visibility is cleared — matching jQuery .show().css().
+    expect(a.style.visibility).toBe('');
+    expect(d.allowDragging()).toBe(true); // flag toggled back off
+
+    // onReturnHelpersToDraggees is RAF-deferred — flush it.
+    flushRaf();
+    expect(onReturn).toHaveBeenCalledTimes(1);
+  });
+
+  it('short-circuits to _showDraggee when there are no helpers', () => {
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.$draggee = [a];
+    d.helpers = [];
+    d.draggeeDisplay = 'block';
+    d.returnHelpersToDraggees();
+    expect(d.allowDragging()).toBe(true);
+  });
+
+  it('sets _returningHelpersToDraggees true mid-flight (gates allowDragging)', () => {
+    // Force a pending state by stubbing prefersReducedMotion false AND providing
+    // a helper with a fake animate that never finishes.
+    const a = makeItem();
+    const helper = makeItem();
+    mockRect(a, 0, 0);
+    helper.animate = vi.fn(() => {
+      const listeners: Record<string, () => void> = {};
+      return {
+        addEventListener: (type: string, cb: () => void) => {
+          listeners[type] = cb;
+        },
+        cancel: () => {},
+      } as unknown as Animation;
+    }) as never;
+    const d = new Drag([a]);
+    d.$draggee = [a];
+    d.helpers = [helper];
+    d.draggeeDisplay = 'block';
+    d.returnHelpersToDraggees();
+    // Animation never fired finish → still returning → dragging blocked.
+    expect(d.allowDragging()).toBe(false);
+  });
+});
+
+describe('Drag.fadeOutHelpers', () => {
+  it('removes helpers immediately on the no-WAAPI path', () => {
+    const h1 = makeItem();
+    const h2 = makeItem();
+    const d = new Drag();
+    d.helpers = [h1, h2];
+    d.fadeOutHelpers();
+    expect(h1.parentElement).toBeNull();
+    expect(h2.parentElement).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Drag — allowDragging + destroy
+// ---------------------------------------------------------------------------
+
+describe('Drag.allowDragging + destroy', () => {
+  it('blocks dragging while returning helpers', () => {
+    const d = new Drag();
+    expect(d.allowDragging()).toBe(true);
+    (
+      d as unknown as {_returningHelpersToDraggees: boolean}
+    )._returningHelpersToDraggees = true;
+    expect(d.allowDragging()).toBe(false);
+  });
+
+  it('destroy cancels the lag RAF, cancels return anims, and removes helpers', () => {
+    const helper = makeItem();
+    const a = makeItem();
+    const d = new Drag([a]);
+    d.helpers = [helper];
+    d.updateHelperPosFrame = 5;
+    const cancel = vi.fn();
+    (
+      d as unknown as {_returnAnimations: Array<{cancel: () => void}>}
+    )._returnAnimations = [{cancel}];
+
+    d.destroy();
+
+    expect(cancel).toHaveBeenCalledTimes(1);
+    expect(helper.parentElement).toBeNull();
+    expect(d.helpers).toEqual([]);
+    expect(d.updateHelperPosFrame).toBeNull();
+    expect(d.$items).toEqual([]); // super.destroy ran
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DragDrop — settings + updateDropTargets
+// ---------------------------------------------------------------------------
+
+describe('DragDrop settings + defaults', () => {
+  it('merges DragDrop.defaults over Drag/BaseDrag defaults', () => {
+    const dd = new DragDrop({activeDropTargetClass: 'over'});
+    expect(dd.settings!.activeDropTargetClass).toBe('over');
+    expect(dd.settings!.dropTargets).toBeNull();
+    // Inherited Drag default.
+    expect(dd.settings!.hideDraggee).toBe(true);
+    // Inherited BaseDrag default.
+    expect(dd.settings!.ignoreHandleSelector).toBe(
+      'input, textarea, button, select, .btn'
+    );
+  });
+
+  it('exposes the documented DragDrop defaults', () => {
+    expect(DragDrop.defaults.dropTargets).toBeNull();
+    expect(DragDrop.defaults.activeDropTargetClass).toBe('active');
+  });
+});
+
+describe('DragDrop.updateDropTargets', () => {
+  it('resolves an element list', () => {
+    const t1 = makeItem();
+    const t2 = makeItem();
+    const dd = new DragDrop({dropTargets: [t1, t2]});
+    dd.updateDropTargets();
+    expect(dd.$dropTargets).toEqual([t1, t2]);
+  });
+
+  it('resolves a selector string', () => {
+    const t1 = makeItem('target');
+    const t2 = makeItem('target');
+    const dd = new DragDrop({dropTargets: '.target'});
+    dd.updateDropTargets();
+    expect(dd.$dropTargets).toEqual([t1, t2]);
+  });
+
+  it('resolves a resolver function', () => {
+    const t1 = makeItem();
+    const dd = new DragDrop({dropTargets: () => [t1]});
+    dd.updateDropTargets();
+    expect(dd.$dropTargets).toEqual([t1]);
+  });
+
+  it('collapses an empty result to null', () => {
+    const dd = new DragDrop({dropTargets: () => []});
+    dd.updateDropTargets();
+    expect(dd.$dropTargets).toBeNull();
+  });
+
+  it('leaves $dropTargets null when dropTargets is null', () => {
+    const dd = new DragDrop({dropTargets: null});
+    dd.updateDropTargets();
+    expect(dd.$dropTargets).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DragDrop — onDrag hit-detection
+// ---------------------------------------------------------------------------
+
+describe('DragDrop.onDrag hit-detection', () => {
+  function setup(): {
+    dd: DragDrop;
+    t1: HTMLElement;
+    t2: HTMLElement;
+  } {
+    const t1 = makeItem();
+    const t2 = makeItem();
+    // t1 box: 0..10 x 0..10 (page coords). t2 box: 100..110 x 100..110.
+    mockRect(t1, 0, 0, 10, 10);
+    mockRect(t2, 100, 100, 10, 10);
+    const dd = new DragDrop();
+    dd.$dropTargets = [t1, t2];
+    // Avoid the RAF-deferred super.onDrag emitting noise.
+    return {dd, t1, t2};
+  }
+
+  it('adds the active class and fires onDropTargetChange on enter', () => {
+    const onChange = vi.fn();
+    const {dd, t1} = setup();
+    dd.settings!.onDropTargetChange = onChange;
+    dd.mouseX = 5;
+    dd.mouseY = 5;
+    dd.onDrag();
+    expect(dd.$activeDropTarget).toBe(t1);
+    expect(t1.classList.contains('active')).toBe(true);
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith(t1);
+  });
+
+  it('does not re-fire onDropTargetChange when the target is unchanged', () => {
+    const onChange = vi.fn();
+    const {dd} = setup();
+    dd.settings!.onDropTargetChange = onChange;
+    dd.mouseX = 5;
+    dd.mouseY = 5;
+    dd.onDrag();
+    dd.onDrag();
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('swaps classes and fires on a target→target change', () => {
+    const onChange = vi.fn();
+    const {dd, t1, t2} = setup();
+    dd.settings!.onDropTargetChange = onChange;
+    dd.mouseX = 5;
+    dd.mouseY = 5;
+    dd.onDrag();
+    dd.mouseX = 105;
+    dd.mouseY = 105;
+    dd.onDrag();
+    expect(t1.classList.contains('active')).toBe(false);
+    expect(t2.classList.contains('active')).toBe(true);
+    expect(dd.$activeDropTarget).toBe(t2);
+    expect(onChange).toHaveBeenCalledTimes(2);
+    expect(onChange).toHaveBeenLastCalledWith(t2);
+  });
+
+  it('fires with null on a target→none change and removes the class', () => {
+    const onChange = vi.fn();
+    const {dd, t1} = setup();
+    dd.settings!.onDropTargetChange = onChange;
+    dd.mouseX = 5;
+    dd.mouseY = 5;
+    dd.onDrag();
+    dd.mouseX = 500;
+    dd.mouseY = 500;
+    dd.onDrag();
+    expect(t1.classList.contains('active')).toBe(false);
+    expect(dd.$activeDropTarget).toBeNull();
+    expect(onChange).toHaveBeenLastCalledWith(null);
+  });
+
+  it('first match wins for overlapping targets', () => {
+    const {dd, t1, t2} = setup();
+    // Make both targets contain the cursor; t1 comes first in the list.
+    mockRect(t1, 0, 0, 1000, 1000);
+    mockRect(t2, 0, 0, 1000, 1000);
+    dd.mouseX = 50;
+    dd.mouseY = 50;
+    dd.onDrag();
+    expect(dd.$activeDropTarget).toBe(t1);
+    void t2;
+  });
+
+  it('does nothing when there are no drop targets', () => {
+    const dd = new DragDrop();
+    dd.$dropTargets = null;
+    const onChange = vi.fn();
+    dd.settings!.onDropTargetChange = onChange;
+    dd.mouseX = 5;
+    dd.mouseY = 5;
+    expect(() => dd.onDrag()).not.toThrow();
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('DragDrop.onDragStart / onDragStop', () => {
+  it('onDragStart resolves drop targets and resets the active target', () => {
+    const t1 = makeItem();
+    const dd = new DragDrop({dropTargets: [t1]});
+    dd.$activeDropTarget = t1;
+    dd.onDragStart();
+    expect(dd.$dropTargets).toEqual([t1]);
+    expect(dd.$activeDropTarget).toBeNull();
+  });
+
+  it('onDragStop strips the active class when a target is active', () => {
+    const t1 = makeItem();
+    t1.classList.add('active');
+    const dd = new DragDrop();
+    dd.$dropTargets = [t1];
+    dd.$activeDropTarget = t1;
+    dd.onDragStop();
+    expect(t1.classList.contains('active')).toBe(false);
+  });
+});
diff --git a/packages/craftcms-garnish/tests/drag-sort.test.ts b/packages/craftcms-garnish/tests/drag-sort.test.ts
new file mode 100644
index 00000000000..8a76bd194a5
--- /dev/null
+++ b/packages/craftcms-garnish/tests/drag-sort.test.ts
@@ -0,0 +1,604 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {DragSort} from '../src/drag/drag-sort';
+import {X_AXIS, Y_AXIS} from '../src/constants';
+import {globals} from '../src/globals';
+
+// happy-dom notes (see doc 11 §6):
+// - No layout: `getBoundingClientRect()` returns zeros and `offsetWidth/Height`
+//   are 0. We mock `getBoundingClientRect` where midpoint math matters.
+// - `element.animate` is `undefined`, so `returnHelpersToDraggees` (called by
+//   DragSort.onDragStop) takes the synchronous no-WAAPI fallback.
+// - The RAF-deferred hooks + the lag-follow loop are deferred onto a manual
+//   queue (a synchronous stub would recurse forever via the lag loop). Tests
+//   flush the queue explicitly with `flushRaf()`.
+vi.mock('../src/utils/animation', async (importOriginal) => {
+  const actual = await importOriginal<object>();
+  return {
+    ...actual,
+    requestAnimationFrame: (cb: FrameRequestCallback): number => {
+      rafQueue.push(cb);
+      return rafQueue.length;
+    },
+    cancelAnimationFrame: (handle: number): void => {
+      if (handle > 0 && handle <= rafQueue.length) {
+        rafQueue[handle - 1] = undefined;
+      }
+    },
+  };
+});
+
+let rafQueue: Array<FrameRequestCallback | undefined> = [];
+
+/** Run every currently-queued RAF callback once (newly-scheduled ones defer). */
+function flushRaf(): void {
+  const current = rafQueue;
+  rafQueue = [];
+  for (const cb of current) {
+    cb?.(0);
+  }
+}
+
+/**
+ * Private-method shape used to `vi.spyOn`/read DragSort internals. `vi.spyOn(d
+ * as never, ...)` typechecks for reads but not for `.mockImplementation`, so we
+ * cast through this when stubbing.
+ */
+interface DragSortPrivate {
+  _updateInsertion: () => void;
+  _getClosestItem: () => HTMLElement | null;
+  _precalculateMidpoints: () => void;
+  _getDraggeeIndexes: () => number[];
+  _moveDraggeeToItem: (item: HTMLElement) => void;
+  _placeInsertionWithDraggee: () => void;
+  _removeInsertion: () => void;
+  _allMidpoints: Map<Element, unknown> | null;
+}
+
+function makeItem(cls = ''): HTMLElement {
+  const el = document.createElement('div');
+  if (cls) el.className = cls;
+  document.body.appendChild(el);
+  return el;
+}
+
+/** Dispatch a PointerEvent with page coords overridden (happy-dom zeros them). */
+function firePointer(
+  el: EventTarget,
+  type: string,
+  opts: {
+    pageX?: number;
+    pageY?: number;
+    pointerId?: number;
+    button?: number;
+  } = {}
+): void {
+  const ev = new PointerEvent(type, {bubbles: true, cancelable: true} as never);
+  Object.defineProperty(ev, 'pageX', {
+    value: opts.pageX ?? 0,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'pageY', {
+    value: opts.pageY ?? 0,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'pointerId', {
+    value: opts.pointerId ?? 1,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'button', {
+    value: opts.button ?? 0,
+    configurable: true,
+  });
+  el.dispatchEvent(ev);
+}
+
+/** Stub an element's bounding rect so midpoint/hit-test math reads a known box. */
+function mockRect(
+  el: Element,
+  top: number,
+  left: number,
+  width = 0,
+  height = 0
+): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    top,
+    left,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  document.body.className = '';
+  rafQueue = [];
+  globals.rtl = false;
+  globals.activateEventsMuted = false;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Settings + defaults
+// ---------------------------------------------------------------------------
+
+describe('DragSort settings + defaults', () => {
+  it('exposes the documented DragSort defaults', () => {
+    expect(DragSort.defaults.container).toBeNull();
+    expect(DragSort.defaults.insertion).toBeNull();
+    expect(DragSort.defaults.moveTargetItemToFront).toBe(false);
+    expect(DragSort.defaults.magnetStrength).toBe(1);
+    expect(DragSort.defaults.canInsertBefore(makeItem())).toBe(true);
+    expect(DragSort.defaults.canInsertAfter(makeItem())).toBe(true);
+  });
+
+  it('merges DragSort.defaults over Drag/BaseDrag defaults', () => {
+    const ds = new DragSort(null, {magnetStrength: 4, minMouseDist: 9});
+    expect(ds.settings!.magnetStrength).toBe(4);
+    expect(ds.settings!.minMouseDist).toBe(9);
+    // Inherited Drag default.
+    expect(ds.settings!.hideDraggee).toBe(true);
+    // Inherited BaseDrag default.
+    expect(ds.settings!.ignoreHandleSelector).toBe(
+      'input, textarea, button, select, .btn'
+    );
+  });
+
+  it('supports the param-shift form: new DragSort(settingsObj)', () => {
+    const ds = new DragSort({moveTargetItemToFront: true});
+    expect(ds.settings!.moveTargetItemToFront).toBe(true);
+    expect(ds.$items).toEqual([]);
+  });
+
+  it('starts with empty insertion/sort state', () => {
+    const ds = new DragSort();
+    expect(ds.$insertion).toBeNull();
+    expect(ds.insertionVisible).toBe(false);
+    expect(ds.closestItem).toBeNull();
+    expect(ds.oldDraggeeIndexes).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createInsertion
+// ---------------------------------------------------------------------------
+
+describe('DragSort.createInsertion', () => {
+  it('returns null when no insertion is configured', () => {
+    const ds = new DragSort();
+    expect(ds.createInsertion()).toBeNull();
+  });
+
+  it('invokes a function insertion with the draggee set', () => {
+    const el = document.createElement('li');
+    const fn = vi.fn(() => el);
+    const a = makeItem();
+    const ds = new DragSort([a], {insertion: fn});
+    ds.$draggee = [a];
+    expect(ds.createInsertion()).toBe(el);
+    expect(fn).toHaveBeenCalledWith([a]);
+  });
+
+  it('parses an HTML-string insertion into an element', () => {
+    const ds = new DragSort(null, {insertion: '<li class="ins">x</li>'});
+    const el = ds.createInsertion();
+    expect(el).not.toBeNull();
+    expect(el!.tagName).toBe('LI');
+    expect(el!.classList.contains('ins')).toBe(true);
+  });
+
+  it('passes an element insertion through unchanged', () => {
+    const el = document.createElement('div');
+    const ds = new DragSort(null, {insertion: el});
+    expect(ds.createInsertion()).toBe(el);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// canInsertBefore / canInsertAfter
+// ---------------------------------------------------------------------------
+
+describe('DragSort.canInsertBefore / canInsertAfter', () => {
+  it('delegate to the settings callbacks', () => {
+    const item = makeItem();
+    const before = vi.fn(() => false);
+    const after = vi.fn(() => true);
+    const ds = new DragSort(null, {
+      canInsertBefore: before,
+      canInsertAfter: after,
+    });
+    expect(ds.canInsertBefore(item)).toBe(false);
+    expect(ds.canInsertAfter(item)).toBe(true);
+    expect(before).toHaveBeenCalledWith(item);
+    expect(after).toHaveBeenCalledWith(item);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// _getDraggeeIndexes
+// ---------------------------------------------------------------------------
+
+describe('DragSort draggee indexes', () => {
+  it('maps each draggee to its index within $items', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const c = makeItem();
+    const ds = new DragSort([a, b, c]);
+    ds.$draggee = [c, a];
+    expect((ds as unknown as DragSortPrivate)._getDraggeeIndexes()).toEqual([
+      2, 0,
+    ]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// _getClosestItem — spatial hit-test math
+// ---------------------------------------------------------------------------
+
+describe('DragSort._getClosestItem', () => {
+  /** A 4-item vertical list (each 20px tall) with `b` as the dragged item. */
+  function verticalList(settings = {}): {
+    ds: DragSort;
+    items: HTMLElement[];
+  } {
+    const [a, b, c, d] = [makeItem(), makeItem(), makeItem(), makeItem()];
+    // midpoints y: a=10, b=30, c=50, d=70 (top + height/2, height 20); x all 10.
+    mockRect(a, 0, 0, 20, 20);
+    mockRect(b, 20, 0, 20, 20);
+    mockRect(c, 40, 0, 20, 20);
+    mockRect(d, 60, 0, 20, 20);
+    const ds = new DragSort([a, b, c, d], settings);
+    ds.$draggee = [b];
+    (ds as unknown as DragSortPrivate)._precalculateMidpoints();
+    return {ds, items: [a, b, c, d]};
+  }
+
+  it('returns the nearest insertable item (and ignores the draggee itself)', () => {
+    const {ds, items} = verticalList();
+    const [, , c] = items;
+    ds.draggeeVirtualMidpointX = 10;
+    ds.draggeeVirtualMidpointY = 55; // closest to c (mid 50)
+    expect((ds as unknown as DragSortPrivate)._getClosestItem()).toBe(c);
+  });
+
+  it('finds an item above the draggee when the cursor moves up', () => {
+    const {ds, items} = verticalList();
+    const [a] = items;
+    ds.draggeeVirtualMidpointX = 10;
+    ds.draggeeVirtualMidpointY = 8; // closest to a (mid 10)
+    expect((ds as unknown as DragSortPrivate)._getClosestItem()).toBe(a);
+  });
+
+  it('returns null when no item is insertable (only the draggee is closest)', () => {
+    const {ds} = verticalList({
+      canInsertBefore: () => false,
+      canInsertAfter: () => false,
+    });
+    ds.draggeeVirtualMidpointX = 10;
+    ds.draggeeVirtualMidpointY = 55;
+    // Every non-draggee item is gated out, so the seed (draggee) wins → null.
+    expect((ds as unknown as DragSortPrivate)._getClosestItem()).toBeNull();
+  });
+
+  it('uses only the Y distance under axis: y', () => {
+    const {ds, items} = verticalList({axis: Y_AXIS});
+    const [, , c] = items;
+    // A wildly different X must not matter when axis-locked to Y.
+    ds.draggeeVirtualMidpointX = 9999;
+    ds.draggeeVirtualMidpointY = 52;
+    expect((ds as unknown as DragSortPrivate)._getClosestItem()).toBe(c);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Insertion placement + DOM reorder
+// ---------------------------------------------------------------------------
+
+describe('DragSort insertion placement', () => {
+  it('_placeInsertionWithDraggee inserts before the first draggee and marks visible', () => {
+    const a = makeItem();
+    const ds = new DragSort([a]);
+    ds.$draggee = [a];
+    ds.$insertion = document.createElement('div');
+    (ds as unknown as DragSortPrivate)._placeInsertionWithDraggee();
+    expect(ds.insertionVisible).toBe(true);
+    expect(a.previousSibling).toBe(ds.$insertion);
+  });
+
+  it('_removeInsertion pulls the placeholder out and clears the flag', () => {
+    const a = makeItem();
+    const ds = new DragSort([a]);
+    ds.$draggee = [a];
+    ds.$insertion = document.createElement('div');
+    (ds as unknown as DragSortPrivate)._placeInsertionWithDraggee();
+    (ds as unknown as DragSortPrivate)._removeInsertion();
+    expect(ds.insertionVisible).toBe(false);
+    expect(ds.$insertion.parentNode).toBeNull();
+  });
+
+  it('_moveDraggeeToItem inserts the draggee after a later sibling (going down)', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const a = document.createElement('div');
+    const b = document.createElement('div');
+    const c = document.createElement('div');
+    container.append(a, b, c);
+    const ds = new DragSort([a, b, c]);
+    ds.$draggee = [a];
+    // a (index 0) → after c (index 2): goingDown branch.
+    (ds as unknown as DragSortPrivate)._moveDraggeeToItem(c);
+    expect(Array.from(container.children)).toEqual([b, c, a]);
+  });
+
+  it('_moveDraggeeToItem inserts the draggee before an earlier sibling (going up)', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const a = document.createElement('div');
+    const b = document.createElement('div');
+    const c = document.createElement('div');
+    container.append(a, b, c);
+    const ds = new DragSort([a, b, c]);
+    ds.$draggee = [c];
+    // c (index 2) → before a (index 0): goingUp branch.
+    (ds as unknown as DragSortPrivate)._moveDraggeeToItem(a);
+    expect(Array.from(container.children)).toEqual([c, a, b]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// onDragStart
+// ---------------------------------------------------------------------------
+
+describe('DragSort.onDragStart', () => {
+  it('records old draggee indexes and precalculates midpoints', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const ds = new DragSort([a, b]);
+    ds.$draggee = [b];
+    ds.$targetItem = b;
+    ds.onDragStart();
+    expect(ds.oldDraggeeIndexes).toEqual([1]);
+    expect((ds as unknown as DragSortPrivate)._allMidpoints).not.toBeNull();
+    expect(ds.closestItem).toBeNull();
+  });
+
+  it('honors moveTargetItemToFront by reordering the draggee in the DOM', () => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const a = document.createElement('div');
+    const b = document.createElement('div');
+    const c = document.createElement('div');
+    container.append(a, b, c);
+    const ds = new DragSort([a, b, c], {moveTargetItemToFront: true});
+    // Target c is the first draggee but sits after b in $items → move it front.
+    ds.$draggee = [c, b];
+    ds.$targetItem = c;
+    ds.onDragStart();
+    // c moved before b: DOM order a, c, b.
+    expect(Array.from(container.children)).toEqual([a, c, b]);
+  });
+
+  it('creates and places the insertion when configured', () => {
+    const a = makeItem();
+    const ds = new DragSort([a], {insertion: '<div class="ins"></div>'});
+    ds.$draggee = [a];
+    ds.$targetItem = a;
+    ds.onDragStart();
+    expect(ds.$insertion).not.toBeNull();
+    expect(ds.insertionVisible).toBe(true);
+    expect(a.previousElementSibling).toBe(ds.$insertion);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// onDrag
+// ---------------------------------------------------------------------------
+
+describe('DragSort.onDrag', () => {
+  it('updates the insertion when the closest item changes', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const ds = new DragSort([a, b]);
+    ds.$draggee = [a];
+    ds.draggeeVirtualMidpointX = 0;
+    ds.draggeeVirtualMidpointY = 0;
+    vi.spyOn(ds, 'onDrag'); // keep, but stub the internals below
+    vi.spyOn(
+      ds as unknown as DragSortPrivate,
+      '_getClosestItem'
+    ).mockReturnValue(b);
+    const update = vi
+      .spyOn(ds as unknown as DragSortPrivate, '_updateInsertion')
+      .mockImplementation(() => {});
+    ds.closestItem = null;
+    ds.onDrag();
+    expect(ds.closestItem).toBe(b);
+    expect(update).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not update the insertion when the closest item is unchanged', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const ds = new DragSort([a, b]);
+    ds.$draggee = [a];
+    vi.spyOn(
+      ds as unknown as DragSortPrivate,
+      '_getClosestItem'
+    ).mockReturnValue(b);
+    const update = vi
+      .spyOn(ds as unknown as DragSortPrivate, '_updateInsertion')
+      .mockImplementation(() => {});
+    ds.closestItem = b; // already on b
+    ds.onDrag();
+    expect(update).not.toHaveBeenCalled();
+  });
+
+  it('clears the closest item + insertion when the cursor leaves the container', () => {
+    const a = makeItem();
+    const ds = new DragSort([a]);
+    ds.$draggee = [a];
+    const container = makeItem();
+    mockRect(container, 0, 0, 10, 10); // box 0..10
+    ds.$heightedContainer = container;
+    ds.$insertion = document.createElement('div');
+    (ds as unknown as DragSortPrivate)._placeInsertionWithDraggee();
+    ds.closestItem = a;
+    ds.mouseX = 500; // far outside the container box
+    ds.mouseY = 500;
+    ds.onDrag();
+    expect(ds.closestItem).toBeNull();
+    expect(ds.insertionVisible).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// onDragStop + sortChange
+// ---------------------------------------------------------------------------
+
+describe('DragSort.onDragStop', () => {
+  function setup(): {ds: DragSort; a: HTMLElement; b: HTMLElement} {
+    const a = makeItem();
+    const b = makeItem();
+    const ds = new DragSort([a, b]);
+    ds.$draggee = [b];
+    ds.$targetItem = b;
+    ds.targetItemPositionInDraggee = 0;
+    ds.draggeeDisplay = 'block';
+    ds.helpers = [];
+    return {ds, a, b};
+  }
+
+  it('returns helpers and removes the insertion', () => {
+    const {ds} = setup();
+    const ret = vi.spyOn(ds, 'returnHelpersToDraggees');
+    const remove = vi.spyOn(
+      ds as unknown as DragSortPrivate,
+      '_removeInsertion'
+    );
+    ds.oldDraggeeIndexes = [1];
+    ds.onDragStop();
+    expect(remove).toHaveBeenCalled();
+    expect(ret).toHaveBeenCalled();
+  });
+
+  it('fires sortChange when the draggee order changed', () => {
+    const {ds} = setup();
+    const onSort = vi.fn();
+    ds.settings!.onSortChange = onSort;
+    const triggered = vi.fn();
+    ds.on('sortChange', triggered);
+    // Pretend the draggee used to be at index 0; it is now at index 1.
+    ds.oldDraggeeIndexes = [0];
+    ds.onDragStop();
+    flushRaf();
+    expect(triggered).toHaveBeenCalledTimes(1);
+    expect(onSort).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire sortChange when the order is unchanged', () => {
+    const {ds} = setup();
+    const triggered = vi.fn();
+    ds.on('sortChange', triggered);
+    // b is at index 1 both before and after.
+    ds.oldDraggeeIndexes = [1];
+    ds.onDragStop();
+    flushRaf();
+    expect(triggered).not.toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Event hooks
+// ---------------------------------------------------------------------------
+
+describe('DragSort event hooks', () => {
+  it('onInsertionPointChange emits the event + runs the callback (RAF-deferred)', () => {
+    const cb = vi.fn();
+    const ds = new DragSort(null, {onInsertionPointChange: cb});
+    const triggered = vi.fn();
+    ds.on('insertionPointChange', triggered);
+    ds.onInsertionPointChange();
+    expect(triggered).not.toHaveBeenCalled(); // deferred
+    flushRaf();
+    expect(triggered).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it('onSortChange emits the event + runs the callback (RAF-deferred)', () => {
+    const cb = vi.fn();
+    const ds = new DragSort(null, {onSortChange: cb});
+    const triggered = vi.fn();
+    ds.on('sortChange', triggered);
+    ds.onSortChange();
+    flushRaf();
+    expect(triggered).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getHelperTargetX/Y — magnetStrength
+// ---------------------------------------------------------------------------
+
+describe('DragSort helper-target magnetStrength', () => {
+  it('tracks the cursor exactly at magnetStrength 1 (delegates to Drag)', () => {
+    const a = makeItem();
+    const ds = new DragSort([a], {magnetStrength: 1});
+    ds.$draggee = [a];
+    ds.mouseX = 200;
+    ds.mouseY = 120;
+    ds.mouseOffsetX = 30;
+    ds.mouseOffsetY = 20;
+    expect(ds.getHelperTargetX()).toBe(170);
+    expect(ds.getHelperTargetY()).toBe(100);
+  });
+
+  it('rubber-bands toward the draggee home at magnetStrength > 1', () => {
+    const a = makeItem();
+    mockRect(a, 100, 50); // getOffset(a) → {top:100, left:50}
+    const ds = new DragSort([a], {magnetStrength: 2});
+    ds.$draggee = [a];
+    ds.mouseX = 250;
+    ds.mouseY = 300;
+    ds.mouseOffsetX = 10;
+    ds.mouseOffsetY = 10;
+    // X: 50 + (250 - 10 - 50) / 2 = 50 + 95 = 145
+    expect(ds.getHelperTargetX()).toBe(145);
+    // Y: 100 + (300 - 10 - 100) / 2 = 100 + 95 = 195
+    expect(ds.getHelperTargetY()).toBe(195);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Event wiring via synthetic PointerEvents
+// ---------------------------------------------------------------------------
+
+describe('DragSort pointer wiring', () => {
+  it('starts a drag and emits dragStart after a past-threshold pointer move', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const c = makeItem();
+    const ds = new DragSort([a, b, c]);
+    const started = vi.fn();
+    ds.on('dragStart', started);
+
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0, pointerId: 1});
+    firePointer(document, 'pointermove', {pageX: 0, pageY: 10, pointerId: 1});
+    flushRaf();
+
+    expect(ds.dragging).toBe(true);
+    expect(started).toHaveBeenCalled();
+    expect(ds.$draggee[0]).toBe(a);
+
+    firePointer(document, 'pointerup', {pointerId: 1});
+    void X_AXIS;
+  });
+});
diff --git a/packages/craftcms-garnish/tests/drag.test.ts b/packages/craftcms-garnish/tests/drag.test.ts
new file mode 100644
index 00000000000..4ea9cde871a
--- /dev/null
+++ b/packages/craftcms-garnish/tests/drag.test.ts
@@ -0,0 +1,577 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {BaseDrag, getItemDragger} from '../src/drag/base-drag';
+import {DragMove} from '../src/drag-move';
+import {getScrollParent, isWindowScrollContainer} from '../src/utils/scroll';
+import {X_AXIS, Y_AXIS} from '../src/constants';
+import {globals, win} from '../src/globals';
+
+// happy-dom notes (see doc 07 §7):
+// - `PointerEvent` exists but `pageX/pageY/pointerId` are always 0 (no
+//   geometry), so we dispatch a real PointerEvent and override those props.
+// - There is no layout, so `getBoundingClientRect()` returns zeros — we mock it
+//   where coordinate math depends on it.
+// - The RAF-deferred hooks (`onDragStart`/`onDrag`/`onDragStop`) are driven by
+//   stubbing the animation module's `requestAnimationFrame` to run synchronously
+//   (below), so we can assert the emitted events without a real frame.
+vi.mock('../src/utils/animation', async (importOriginal) => {
+  const actual = await importOriginal<object>();
+  return {
+    ...actual,
+    requestAnimationFrame: (cb: FrameRequestCallback): number => {
+      cb(0);
+      return 0;
+    },
+    cancelAnimationFrame: (): void => {},
+  };
+});
+
+/** Dispatch a PointerEvent on `el` with page coords overridden (happy-dom zeros them). */
+function firePointer(
+  el: EventTarget,
+  type: string,
+  opts: {
+    pageX?: number;
+    pageY?: number;
+    pointerId?: number;
+    button?: number;
+  } = {}
+): PointerEvent {
+  const ev = new PointerEvent(type, {bubbles: true, cancelable: true} as never);
+  Object.defineProperty(ev, 'pageX', {
+    value: opts.pageX ?? 0,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'pageY', {
+    value: opts.pageY ?? 0,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'pointerId', {
+    value: opts.pointerId ?? 1,
+    configurable: true,
+  });
+  Object.defineProperty(ev, 'button', {
+    value: opts.button ?? 0,
+    configurable: true,
+  });
+  el.dispatchEvent(ev);
+  return ev;
+}
+
+function makeItem(): HTMLElement {
+  const el = document.createElement('div');
+  document.body.appendChild(el);
+  return el;
+}
+
+/** Stub an element's bounding rect so getOffset returns a known top/left. */
+function mockRect(el: Element, top: number, left: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    top,
+    left,
+    right: left,
+    bottom: top,
+    width: 0,
+    height: 0,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  document.body.className = '';
+  globals.rtl = false;
+  globals.activateEventsMuted = false;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('BaseDrag settings + defaults', () => {
+  it('merges defaults with passed settings', () => {
+    const d = new BaseDrag(null, {axis: X_AXIS, minMouseDist: 5});
+    expect(d.settings!.axis).toBe(X_AXIS);
+    expect(d.settings!.minMouseDist).toBe(5);
+    // Untouched defaults survive.
+    expect(d.settings!.ignoreHandleSelector).toBe(
+      'input, textarea, button, select, .btn'
+    );
+  });
+
+  it('supports the param-shift form: new BaseDrag(settings)', () => {
+    const d = new BaseDrag({axis: Y_AXIS});
+    expect(d.settings!.axis).toBe(Y_AXIS);
+    expect(d.$items).toEqual([]);
+  });
+
+  it('exposes the static tunables', () => {
+    expect(BaseDrag.minMouseDist).toBe(1);
+    expect(BaseDrag.windowScrollTargetSize).toBe(25);
+  });
+
+  it('starts with the documented initial state', () => {
+    const d = new BaseDrag();
+    expect(d.dragging).toBe(false);
+    expect(d.$targetItem).toBeNull();
+    expect(d.$items).toEqual([]);
+    expect(d.mouseX).toBeNull();
+    expect(d.scrollProperty).toBeNull();
+  });
+});
+
+describe('BaseDrag item management + registry', () => {
+  it('addItems registers items in $items and the WeakMap registry', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const d = new BaseDrag();
+    d.addItems([a, b]);
+    expect(d.$items).toEqual([a, b]);
+    expect(getItemDragger(a)).toBe(d);
+    expect(getItemDragger(b)).toBe(d);
+  });
+
+  it('addItems accepts a selector string', () => {
+    const a = makeItem();
+    a.className = 'draggable';
+    const d = new BaseDrag('.draggable');
+    expect(d.$items).toContain(a);
+  });
+
+  it('dedupes items already owned by the same dragger', () => {
+    const a = makeItem();
+    const d = new BaseDrag([a]);
+    d.addItems([a]);
+    expect(d.$items).toEqual([a]);
+  });
+
+  it('warns and steals an item from another dragger', () => {
+    const a = makeItem();
+    const d1 = new BaseDrag([a]);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const d2 = new BaseDrag();
+    d2.addItems([a]);
+    expect(warn).toHaveBeenCalledWith(
+      'Element was added to more than one dragger'
+    );
+    expect(getItemDragger(a)).toBe(d2);
+    expect(d1.$items).not.toContain(a);
+    expect(d2.$items).toContain(a);
+  });
+
+  it('removeItems drops the item and its registry entry', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const d = new BaseDrag([a, b]);
+    d.removeItems(a);
+    expect(d.$items).toEqual([b]);
+    expect(getItemDragger(a)).toBeUndefined();
+  });
+
+  it('removeAllItems clears everything', () => {
+    const d = new BaseDrag([makeItem(), makeItem()]);
+    d.removeAllItems();
+    expect(d.$items).toEqual([]);
+  });
+
+  it('getPrevItem / getNextItem walk the $items array', () => {
+    const a = makeItem();
+    const b = makeItem();
+    const c = makeItem();
+    const d = new BaseDrag([a, b, c]);
+    expect(d.getPrevItem(b)).toBe(a);
+    expect(d.getNextItem(b)).toBe(c);
+    expect(d.getPrevItem(a)).toBeNull();
+    expect(d.getNextItem(c)).toBeNull();
+    expect(d.getPrevItem(makeItem())).toBeNull();
+  });
+
+  it('destroy removes all items + clears the registry', () => {
+    const a = makeItem();
+    const d = new BaseDrag([a]);
+    d.destroy();
+    expect(d.$items).toEqual([]);
+    expect(getItemDragger(a)).toBeUndefined();
+  });
+});
+
+describe('BaseDrag handle resolution', () => {
+  it('uses the item itself when handle is null', () => {
+    const a = makeItem();
+    const child = document.createElement('span');
+    a.appendChild(child);
+    const onBefore = vi.fn();
+    const d = new BaseDrag([a], {onBeforeDragStart: onBefore, minMouseDist: 0});
+    mockRect(a, 0, 0);
+    // pointerdown on the item starts capture.
+    firePointer(a, 'pointerdown', {pageX: 5, pageY: 5});
+    expect(d.$targetItem).toBe(a);
+  });
+
+  it('resolves a string handle via querySelector within the item', () => {
+    const a = makeItem();
+    const handle = document.createElement('div');
+    handle.className = 'handle';
+    a.appendChild(handle);
+    const d = new BaseDrag([a], {handle: '.handle'});
+    mockRect(a, 0, 0);
+    // pointerdown on the handle captures; pointerdown elsewhere on item does not.
+    firePointer(handle, 'pointerdown', {pageX: 1, pageY: 1});
+    expect(d.$targetItem).toBe(a);
+  });
+
+  it('resolves a function handle', () => {
+    const a = makeItem();
+    const handle = document.createElement('div');
+    a.appendChild(handle);
+    const d = new BaseDrag([a], {handle: () => handle});
+    mockRect(a, 0, 0);
+    firePointer(handle, 'pointerdown', {pageX: 1, pageY: 1});
+    expect(d.$targetItem).toBe(a);
+  });
+});
+
+describe('BaseDrag pointer-down gating + coordinate capture', () => {
+  it('ignores secondary (button !== 0) clicks', () => {
+    const a = makeItem();
+    const d = new BaseDrag([a]);
+    mockRect(a, 0, 0);
+    firePointer(a, 'pointerdown', {pageX: 5, pageY: 5, button: 2});
+    expect(d.$targetItem).toBeNull();
+  });
+
+  it('ignores pointerdown on an ignoreHandleSelector descendant', () => {
+    const a = makeItem();
+    const button = document.createElement('button');
+    a.appendChild(button);
+    const d = new BaseDrag([a]); // default ignoreHandleSelector includes `button`
+    mockRect(a, 0, 0);
+    firePointer(button, 'pointerdown', {pageX: 5, pageY: 5});
+    expect(d.$targetItem).toBeNull();
+  });
+
+  it('captures the target, mousedown coords, and the grab offset', () => {
+    const a = makeItem();
+    mockRect(a, 30, 20); // top=30, left=20
+    const d = new BaseDrag([a]);
+    firePointer(a, 'pointerdown', {pageX: 50, pageY: 60});
+    expect(d.$targetItem).toBe(a);
+    expect(d.mousedownX).toBe(50);
+    expect(d.mousedownY).toBe(60);
+    expect(d.mouseOffsetX).toBe(50 - 20);
+    expect(d.mouseOffsetY).toBe(60 - 30);
+  });
+});
+
+describe('BaseDrag drag start threshold + axis locking', () => {
+  it('starts dragging once minMouseDist is exceeded and fires the hooks', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const onStart = vi.fn();
+    const onDrag = vi.fn();
+    const d = new BaseDrag([a], {
+      minMouseDist: 5,
+      onDragStart: onStart,
+      onDrag,
+    });
+
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    // Small move — below threshold, no drag.
+    firePointer(document, 'pointermove', {pageX: 2, pageY: 0});
+    expect(d.dragging).toBe(false);
+
+    // Big move — crosses threshold.
+    firePointer(document, 'pointermove', {pageX: 20, pageY: 0});
+    expect(d.dragging).toBe(true);
+    // RAF is stubbed synchronous, so the deferred hooks have fired.
+    expect(onStart).toHaveBeenCalled();
+    expect(onDrag).toHaveBeenCalled();
+  });
+
+  it('locks to the X axis (mouseY stays at mousedown)', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {axis: X_AXIS, minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    firePointer(document, 'pointermove', {pageX: 40, pageY: 40});
+    expect(d.mouseX).toBe(40);
+    // mouseY was never reassigned past mousedown (axis-locked).
+    expect(d.mouseY).toBe(0);
+    expect(d.realMouseY).toBe(40); // realMouse is always tracked
+  });
+
+  it('locks to the Y axis (mouseX stays at mousedown)', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {axis: Y_AXIS, minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    firePointer(document, 'pointermove', {pageX: 40, pageY: 40});
+    expect(d.mouseY).toBe(40);
+    expect(d.mouseX).toBe(0);
+    expect(d.realMouseX).toBe(40);
+  });
+
+  it('computes mouseDistX/Y from mousedown', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 10, pageY: 10});
+    firePointer(document, 'pointermove', {pageX: 30, pageY: 25});
+    expect(d.mouseDistX).toBe(20);
+    expect(d.mouseDistY).toBe(15);
+  });
+
+  it('ignores pointermove from a different pointerId (multi-touch)', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0, pointerId: 1});
+    firePointer(document, 'pointermove', {pageX: 40, pageY: 40, pointerId: 2});
+    // The second pointer is ignored — no coords updated.
+    expect(d.mouseX).toBe(0);
+    expect(d.dragging).toBe(false);
+  });
+});
+
+describe('BaseDrag pointer-up / stop', () => {
+  it('stops dragging and clears the target on pointerup', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const onStop = vi.fn();
+    const d = new BaseDrag([a], {minMouseDist: 0, onDragStop: onStop});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    firePointer(document, 'pointermove', {pageX: 20, pageY: 0});
+    expect(d.dragging).toBe(true);
+
+    firePointer(document, 'pointerup', {pageX: 20, pageY: 0});
+    expect(d.dragging).toBe(false);
+    expect(d.$targetItem).toBeNull();
+    expect(onStop).toHaveBeenCalled();
+  });
+
+  it('treats pointercancel like pointerup', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    firePointer(document, 'pointermove', {pageX: 20, pageY: 0});
+    firePointer(document, 'pointercancel', {pageX: 20, pageY: 0});
+    expect(d.dragging).toBe(false);
+    expect(d.$targetItem).toBeNull();
+  });
+});
+
+describe('BaseDrag event hooks', () => {
+  it('onBeforeDragStart fires synchronously; trigger + callback', () => {
+    const d = new BaseDrag(null, {});
+    const onBefore = vi.fn();
+    d.settings!.onBeforeDragStart = onBefore;
+    const triggered = vi.fn();
+    d.on('beforeDragStart', triggered);
+    d.onBeforeDragStart();
+    expect(triggered).toHaveBeenCalled();
+    expect(onBefore).toHaveBeenCalled();
+  });
+
+  it('onDragStart / onDrag / onDragStop emit their events (RAF stubbed sync)', () => {
+    const d = new BaseDrag();
+    const start = vi.fn();
+    const drag = vi.fn();
+    const stop = vi.fn();
+    d.on('dragStart', start);
+    d.on('drag', drag);
+    d.on('dragStop', stop);
+    d.onDragStart();
+    d.onDrag();
+    d.onDragStop();
+    expect(start).toHaveBeenCalled();
+    expect(drag).toHaveBeenCalled();
+    expect(stop).toHaveBeenCalled();
+  });
+
+  it('startDragging mutes activate events; stopDragging unmutes them', () => {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    firePointer(document, 'pointermove', {pageX: 20, pageY: 0});
+    expect(globals.activateEventsMuted).toBe(true);
+    firePointer(document, 'pointerup', {pageX: 20, pageY: 0});
+    // stopDragging schedules the unmute in a RAF (stubbed synchronous here).
+    expect(globals.activateEventsMuted).toBe(false);
+  });
+});
+
+describe('DragMove', () => {
+  it('positions the target at the cursor minus the grab offset', () => {
+    const a = makeItem();
+    const d = new DragMove();
+    d.$targetItem = a;
+    d.mouseX = 100;
+    d.mouseY = 80;
+    d.mouseOffsetX = 10;
+    d.mouseOffsetY = 5;
+    d.onDrag();
+    expect(a.style.left).toBe('90px');
+    expect(a.style.top).toBe('75px');
+  });
+
+  it('still emits the drag event (Option A: calls super.onDrag)', () => {
+    const a = makeItem();
+    const d = new DragMove();
+    d.$targetItem = a;
+    d.mouseX = 0;
+    d.mouseY = 0;
+    d.mouseOffsetX = 0;
+    d.mouseOffsetY = 0;
+    const drag = vi.fn();
+    d.on('drag', drag);
+    d.onDrag();
+    expect(drag).toHaveBeenCalled();
+  });
+
+  it('subtracts page scroll for a position:fixed target (no scroll-jump)', () => {
+    // A fixed element's containing block is the viewport (anchored at the page
+    // scroll offset), so a page-coordinate target must have the scroll
+    // subtracted — otherwise the element jumps down by scrollY on the first drag
+    // frame. Repro of the draggable-Modal "jumps down the page" bug.
+    const a = makeItem();
+    vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+      position: 'fixed',
+    } as CSSStyleDeclaration);
+    Object.defineProperty(window, 'scrollX', {value: 0, configurable: true});
+    Object.defineProperty(window, 'scrollY', {value: 300, configurable: true});
+
+    const d = new DragMove();
+    d.$targetItem = a;
+    d.mouseX = 100; // pageX
+    d.mouseY = 380; // pageY = viewport 80 + scrollY 300
+    d.mouseOffsetX = 10;
+    d.mouseOffsetY = 5;
+    d.onDrag();
+
+    // left: 100 - 10 - 0 = 90; top: 380 - 5 - 300 = 75 (viewport-relative).
+    expect(a.style.left).toBe('90px');
+    expect(a.style.top).toBe('75px');
+
+    Object.defineProperty(window, 'scrollX', {value: 0, configurable: true});
+    Object.defineProperty(window, 'scrollY', {value: 0, configurable: true});
+  });
+});
+
+describe('getScrollParent (axis-aware)', () => {
+  it('returns window when no scrollable ancestor exists', () => {
+    const a = makeItem();
+    expect(getScrollParent(a)).toBe(win);
+    expect(isWindowScrollContainer(getScrollParent(a))).toBe(true);
+  });
+
+  it('returns a vertically-scrollable ancestor for the y axis', () => {
+    const container = document.createElement('div');
+    const child = document.createElement('div');
+    container.appendChild(child);
+    document.body.appendChild(container);
+
+    vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+      overflow: 'auto',
+      overflowX: 'visible',
+      overflowY: 'auto',
+    } as CSSStyleDeclaration);
+    Object.defineProperty(container, 'scrollHeight', {
+      value: 500,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'clientHeight', {
+      value: 100,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'scrollWidth', {
+      value: 100,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'clientWidth', {
+      value: 100,
+      configurable: true,
+    });
+
+    expect(getScrollParent(child, Y_AXIS)).toBe(container);
+  });
+
+  it('skips a container not scrollable on the requested axis', () => {
+    const container = document.createElement('div');
+    const child = document.createElement('div');
+    container.appendChild(child);
+    document.body.appendChild(container);
+
+    // overflow auto, but only vertically scrollable.
+    vi.spyOn(window, 'getComputedStyle').mockReturnValue({
+      overflow: 'auto',
+      overflowX: 'auto',
+      overflowY: 'auto',
+    } as CSSStyleDeclaration);
+    Object.defineProperty(container, 'scrollHeight', {
+      value: 500,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'clientHeight', {
+      value: 100,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'scrollWidth', {
+      value: 100,
+      configurable: true,
+    });
+    Object.defineProperty(container, 'clientWidth', {
+      value: 100,
+      configurable: true,
+    });
+
+    // Asking for X-axis scrollability: container isn't horizontally scrollable,
+    // and there is no other scrollable ancestor → window.
+    expect(getScrollParent(child, X_AXIS)).toBe(win);
+  });
+
+  it('normalizes <body>/<html> to the window', () => {
+    const a = makeItem(); // parented to <body>
+    // <body> has no overflow scroll; getScrollParent climbs to body → window.
+    expect(getScrollParent(a)).toBe(win);
+  });
+});
+
+describe('BaseDrag auto-scroll decision (window edges)', () => {
+  // Drive `_computeEdgeScroll` (private) via `drag(true)` after setting up state.
+  // We assert the public scroll* fields it populates.
+  function setupDraggingOnWindow(): BaseDrag {
+    const a = makeItem();
+    mockRect(a, 0, 0);
+    const d = new BaseDrag([a], {minMouseDist: 0});
+    firePointer(a, 'pointerdown', {pageX: 0, pageY: 0});
+    // Now dragging; container resolves to window (no scrollable ancestor).
+    return d;
+  }
+
+  it('claims a downward scroll when the pointer nears the bottom edge', () => {
+    const d = setupDraggingOnWindow();
+    // Window: innerHeight, scrollY known from happy-dom (0). Edge band = 25px.
+    const innerHeight = win.innerHeight;
+    // Put mouseY past (innerHeight - 25) so it triggers a down-scroll.
+    firePointer(document, 'pointermove', {
+      pageX: 0,
+      pageY: innerHeight - 5,
+    });
+    expect(d.scrollProperty).toBe('scrollTop');
+    expect(d.scrollAxis).toBe('Y');
+    expect(d.scrollDist).toBeGreaterThan(0);
+  });
+
+  it('does not claim a scroll when the pointer is mid-viewport', () => {
+    const d = setupDraggingOnWindow();
+    firePointer(document, 'pointermove', {
+      pageX: Math.round(win.innerWidth / 2),
+      pageY: Math.round(win.innerHeight / 2),
+    });
+    expect(d.scrollProperty).toBeNull();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/events.test.ts b/packages/craftcms-garnish/tests/events.test.ts
new file mode 100644
index 00000000000..b677501e83a
--- /dev/null
+++ b/packages/craftcms-garnish/tests/events.test.ts
@@ -0,0 +1,191 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {
+  ClassEventBus,
+  EventEmitter,
+  formatDomEvents,
+  parseEvents,
+  type GarnishEvent,
+} from '../src/events';
+
+describe('parseEvents', () => {
+  it('splits on spaces by default and on the first dot', () => {
+    expect(parseEvents('click.ns mousedown')).toEqual([
+      {type: 'click', namespace: 'ns'},
+      {type: 'mousedown', namespace: null},
+    ]);
+  });
+
+  it('only splits on the first dot', () => {
+    expect(parseEvents('click.a.b')).toEqual([
+      {type: 'click', namespace: 'a.b'},
+    ]);
+  });
+
+  it('splits on commas and trims when asked (addListener grammar)', () => {
+    expect(parseEvents('click, drag.ns', ',')).toEqual([
+      {type: 'click', namespace: null},
+      {type: 'drag', namespace: 'ns'},
+    ]);
+  });
+
+  it('supports the empty-type / namespace-only form for off', () => {
+    expect(parseEvents('.focus-trap')).toEqual([
+      {type: '', namespace: 'focus-trap'},
+    ]);
+  });
+});
+
+describe('formatDomEvents', () => {
+  it('appends the namespace to each comma-split token', () => {
+    expect(formatDomEvents('click,drag', '.Garnish123')).toBe(
+      'click.Garnish123 drag.Garnish123'
+    );
+  });
+});
+
+describe('EventEmitter', () => {
+  let emitter: EventEmitter<{id: string}>;
+  const target = {id: 'host'};
+
+  beforeEach(() => {
+    emitter = new EventEmitter(target);
+  });
+
+  it('on/trigger invokes handlers with type + target', () => {
+    const events: GarnishEvent[] = [];
+    emitter.on('foo', (ev) => events.push(ev));
+    emitter.trigger('foo');
+    expect(events).toHaveLength(1);
+    expect(events[0]!.type).toBe('foo');
+    expect(events[0]!.target).toBe(target);
+  });
+
+  it('on with a data object merges per-registration data', () => {
+    let received: GarnishEvent | undefined;
+    emitter.on('foo', {a: 1}, (ev) => (received = ev));
+    emitter.trigger('foo');
+    expect(received!.data).toEqual({a: 1});
+  });
+
+  it('trigger precedence: trigger data wins over registration data; type/target always win', () => {
+    let received: GarnishEvent | undefined;
+    emitter.on('foo', {a: 1}, (ev) => (received = ev));
+    // trigger-time data tries to override `type`, `target`, and a data key.
+    emitter.trigger('foo', {a: 2, type: 'evil', target: 'evil'});
+    // trigger data `a` wins; type/target are forced back.
+    expect(received!.a).toBe(2);
+    expect(received!.type).toBe('foo');
+    expect(received!.target).toBe(target);
+    // registration data is still present under `.data`.
+    expect(received!.data).toEqual({a: 1});
+  });
+
+  it('off by type removes all handlers of that type', () => {
+    const fn = vi.fn();
+    emitter.on('foo', fn);
+    emitter.on('foo', fn);
+    emitter.off('foo');
+    emitter.trigger('foo');
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('off by handler removes only the matching registration', () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    emitter.on('foo', a);
+    emitter.on('foo', b);
+    emitter.off('foo', a);
+    emitter.trigger('foo');
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalledTimes(1);
+  });
+
+  it('off by namespace only removes that namespace; empty namespace removes all', () => {
+    const a = vi.fn();
+    const b = vi.fn();
+    emitter.on('foo.ns1', a);
+    emitter.on('foo.ns2', b);
+    emitter.off('foo.ns1');
+    emitter.trigger('foo');
+    expect(a).not.toHaveBeenCalled();
+    expect(b).toHaveBeenCalledTimes(1);
+  });
+
+  it('once fires exactly once and is removable by original handler', () => {
+    const fn = vi.fn();
+    emitter.once('foo', fn);
+    emitter.trigger('foo');
+    emitter.trigger('foo');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it('a once registration can be removed by type before firing', () => {
+    // Legacy wart: `once` stores a wrapper closure, so `off(events, originalFn)`
+    // does NOT match it (only the wrapper does). Removing by type still works.
+    const fn = vi.fn();
+    emitter.once('foo', fn);
+    emitter.off('foo');
+    emitter.trigger('foo');
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('clear removes every registration', () => {
+    const fn = vi.fn();
+    emitter.on('foo', fn);
+    emitter.clear();
+    emitter.trigger('foo');
+    expect(fn).not.toHaveBeenCalled();
+  });
+});
+
+describe('ClassEventBus instanceof dispatch', () => {
+  class Animal {}
+  class Dog extends Animal {}
+  class Cat extends Animal {}
+
+  let bus: ClassEventBus;
+  beforeEach(() => {
+    bus = new ClassEventBus();
+  });
+
+  it('dispatches to handlers whose target the instance is an instanceof', () => {
+    const animalFn = vi.fn();
+    const dogFn = vi.fn();
+    const catFn = vi.fn();
+
+    bus.on(Animal, 'bark', animalFn);
+    bus.on(Dog, 'bark', dogFn);
+    bus.on(Cat, 'bark', catFn);
+
+    const dog = new Dog();
+    bus.dispatch(dog, 'bark', undefined);
+
+    expect(animalFn).toHaveBeenCalledTimes(1); // dog is an Animal
+    expect(dogFn).toHaveBeenCalledTimes(1); // dog is a Dog
+    expect(catFn).not.toHaveBeenCalled(); // dog is not a Cat
+  });
+
+  it('warns and no-ops on undefined target', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    bus.on(undefined as never, 'bark', vi.fn());
+    expect(warn).toHaveBeenCalledOnce();
+    warn.mockRestore();
+  });
+
+  it('off removes class-level handlers', () => {
+    const fn = vi.fn();
+    bus.on(Animal, 'bark', fn);
+    bus.off(Animal, 'bark', fn);
+    bus.dispatch(new Dog(), 'bark', undefined);
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('once fires once at the class level', () => {
+    const fn = vi.fn();
+    bus.once(Animal, 'bark', fn);
+    bus.dispatch(new Dog(), 'bark', undefined);
+    bus.dispatch(new Dog(), 'bark', undefined);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/craftcms-garnish/tests/focusable.test.ts b/packages/craftcms-garnish/tests/focusable.test.ts
new file mode 100644
index 00000000000..a1837fab6bb
--- /dev/null
+++ b/packages/craftcms-garnish/tests/focusable.test.ts
@@ -0,0 +1,95 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {
+  getFocusableElements,
+  isFocusable,
+  isKeyboardFocusable,
+} from '../src/utils/focusable';
+
+// happy-dom doesn't compute layout, so offsetWidth/Height are 0. Force the
+// visibility check to pass by stubbing getClientRects to report a box and
+// getComputedStyle visibility to 'visible'.
+function forceVisible(): void {
+  vi.spyOn(Element.prototype, 'getClientRects').mockImplementation(
+    () => [{width: 10, height: 10}] as unknown as DOMRectList
+  );
+}
+
+describe('isFocusable', () => {
+  let container: HTMLElement;
+
+  beforeEach(() => {
+    forceVisible();
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  it('treats an <a href> as focusable', () => {
+    const a = document.createElement('a');
+    a.setAttribute('href', '/x');
+    container.appendChild(a);
+    expect(isFocusable(a)).toBe(true);
+  });
+
+  it('treats an <a> without href and without tabindex as NOT focusable', () => {
+    const a = document.createElement('a');
+    container.appendChild(a);
+    expect(isFocusable(a)).toBe(false);
+  });
+
+  it('treats an enabled input as focusable, a disabled one as not', () => {
+    const input = document.createElement('input');
+    container.appendChild(input);
+    expect(isFocusable(input)).toBe(true);
+
+    input.disabled = true;
+    expect(isFocusable(input)).toBe(false);
+  });
+
+  it('treats a plain div as focusable only with a tabindex', () => {
+    const div = document.createElement('div');
+    container.appendChild(div);
+    expect(isFocusable(div)).toBe(false);
+
+    div.setAttribute('tabindex', '0');
+    expect(isFocusable(div)).toBe(true);
+
+    div.setAttribute('tabindex', '-1');
+    expect(isFocusable(div)).toBe(true); // still focusable (just not by keyboard)
+  });
+});
+
+describe('isKeyboardFocusable', () => {
+  beforeEach(() => forceVisible());
+
+  it('excludes tabindex="-1"', () => {
+    const div = document.createElement('div');
+    div.setAttribute('tabindex', '-1');
+    document.body.appendChild(div);
+    expect(isFocusable(div)).toBe(true);
+    expect(isKeyboardFocusable(div)).toBe(false);
+  });
+
+  it('includes tabindex="0"', () => {
+    const div = document.createElement('div');
+    div.setAttribute('tabindex', '0');
+    document.body.appendChild(div);
+    expect(isKeyboardFocusable(div)).toBe(true);
+  });
+});
+
+describe('getFocusableElements', () => {
+  beforeEach(() => forceVisible());
+
+  it('returns focusable descendants in document order, excluding the container', () => {
+    const container = document.createElement('div');
+    container.setAttribute('tabindex', '0'); // container itself is focusable
+    container.innerHTML =
+      '<a href="/a">a</a><span>x</span><button>b</button><input disabled>';
+    document.body.appendChild(container);
+
+    const focusable = getFocusableElements(container);
+    const tags = focusable.map((el) => el.tagName.toLowerCase());
+    expect(tags).toEqual(['a', 'button']);
+  });
+});
diff --git a/packages/craftcms-garnish/tests/hud.test.ts b/packages/craftcms-garnish/tests/hud.test.ts
new file mode 100644
index 00000000000..445b0df695a
--- /dev/null
+++ b/packages/craftcms-garnish/tests/hud.test.ts
@@ -0,0 +1,493 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {HUD} from '../src/hud';
+import {UiLayerManager} from '../src/managers/ui-layer-manager';
+import {setUiLayerManager} from '../src/managers/registry';
+import {ESC_KEY, TAB_KEY} from '../src/constants';
+import {globals} from '../src/globals';
+
+// happy-dom notes:
+// - No layout: `getBoundingClientRect()` returns zeros, `offsetWidth/Height`
+//   and `clientWidth/Height` are 0. We stub those where the positioning math
+//   needs known values (`mockRect` / `setContentSize`).
+// - `requestAnimationFrame` is mocked onto a manual queue so the deferred
+//   `updateSizeAndPositionInternal` runs only when we `flushRaf()` (a synchronous
+//   stub is fine for HUD, but the queue keeps the scheduling observable).
+// - The focusable matcher reads layout boxes, so focusable elements get their
+//   `getClientRects` stubbed to look visible (per the Modal/focusable tests).
+vi.mock('../src/utils/animation', async (importOriginal) => {
+  const actual = await importOriginal<object>();
+  return {
+    ...actual,
+    requestAnimationFrame: (cb: FrameRequestCallback): number => {
+      rafQueue.push(cb);
+      return rafQueue.length;
+    },
+    cancelAnimationFrame: (handle: number): void => {
+      if (handle > 0 && handle <= rafQueue.length) {
+        rafQueue[handle - 1] = undefined;
+      }
+    },
+  };
+});
+
+let rafQueue: Array<FrameRequestCallback | undefined> = [];
+
+/** Run every currently-queued RAF callback once. */
+function flushRaf(): void {
+  const current = rafQueue;
+  rafQueue = [];
+  for (const cb of current) {
+    cb?.(0);
+  }
+}
+
+let manager: UiLayerManager;
+
+/** A visible, focusable trigger button. */
+function makeTrigger(): HTMLButtonElement {
+  const btn = document.createElement('button');
+  btn.type = 'button';
+  btn.textContent = 'Open';
+  makeVisible(btn);
+  document.body.appendChild(btn);
+  return btn;
+}
+
+/** Stub an element's layout boxes so the focusable matcher treats it as visible. */
+function makeVisible(el: Element): void {
+  vi.spyOn(el, 'getClientRects').mockReturnValue([
+    {width: 10, height: 10},
+  ] as unknown as DOMRectList);
+}
+
+/** Stub an element's bounding rect (positioning math). */
+function mockRect(
+  el: Element,
+  top: number,
+  left: number,
+  width = 0,
+  height = 0
+): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    top,
+    left,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeEach(() => {
+  manager = new UiLayerManager();
+  setUiLayerManager(manager);
+  HUD.instances = [];
+  HUD.activeHUDs = {};
+  rafQueue = [];
+  document.body.innerHTML = '';
+  document.body.className = '';
+  globals.scrollContainer = window;
+  globals.rtl = false;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('HUD construction', () => {
+  it('applies defaults merged with passed settings', () => {
+    const hud = new HUD(makeTrigger(), {
+      showOnInit: false,
+      triggerSpacing: 25,
+    });
+    expect(hud.settings!.triggerSpacing).toBe(25);
+    expect(hud.settings!.windowSpacing).toBe(10);
+    expect(hud.settings!.hudClass).toBe('hud');
+    expect(hud.settings!.withShade).toBe(true);
+    expect(hud.settings!.orientations).toEqual([
+      'bottom',
+      'top',
+      'right',
+      'left',
+    ]);
+  });
+
+  it('supports the param-shift form: new HUD(trigger, settings)', () => {
+    const hud = new HUD(makeTrigger(), {
+      showOnInit: false,
+      hudClass: 'hud custom',
+    });
+    expect(hud.settings!.hudClass).toBe('hud custom');
+    expect(hud.$main!.innerHTML).toBe('');
+  });
+
+  it('treats a third-arg settings object as settings (full signature)', () => {
+    const hud = new HUD(makeTrigger(), '<p>body</p>', {showOnInit: false});
+    expect(hud.settings!.showOnInit).toBe(false);
+    expect(hud.$main!.querySelector('p')!.textContent).toBe('body');
+  });
+
+  it('builds the hud > tip / body > mainContainer > main tree', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    expect(hud.$hud!.classList.contains('hud')).toBe(true);
+    expect(hud.$tip!.parentElement).toBe(hud.$hud);
+    expect(hud.$body!.tagName).toBe('FORM');
+    expect(hud.$body!.parentElement).toBe(hud.$hud);
+    // ($body is a <form>; happy-dom hands back distinct proxies through the form,
+    // so assert the nesting via a selector from $hud rather than node identity.)
+    expect(
+      hud.$hud!.querySelector('form.body > .main-container > .main')
+    ).not.toBeNull();
+    expect(hud.$main!.classList.contains('main')).toBe(true);
+  });
+
+  it('creates a shade with the configured class when withShade', () => {
+    const hud = new HUD(makeTrigger(), {
+      showOnInit: false,
+      shadeClass: 'custom-shade',
+    });
+    expect(hud.$shade).not.toBeNull();
+    expect(hud.$shade!.classList.contains('custom-shade')).toBe(true);
+  });
+
+  it('omits the shade when withShade is false', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false, withShade: false});
+    expect(hud.$shade).toBeNull();
+  });
+
+  it('sets aria-expanded=false on the trigger', () => {
+    const trigger = makeTrigger();
+    new HUD(trigger, {showOnInit: false});
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('registers itself in the static instances list', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    expect(HUD.instances).toContain(hud);
+  });
+
+  it('positions absolute by default (no fixed ancestor)', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    expect(hud.$hud!.style.position).toBe('absolute');
+    expect(hud.$fixedTriggerParent).toBeNull();
+  });
+
+  it('auto-shows when showOnInit is true (the default)', () => {
+    const trigger = makeTrigger();
+    const hud = new HUD(trigger);
+    expect(hud.showing).toBe(true);
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+  });
+});
+
+describe('HUD updateBody', () => {
+  it('extracts a header and footer and flags the hud', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    hud.updateBody(
+      '<div class="hud-header">H</div><p>mid</p><div class="hud-footer">F</div>'
+    );
+    expect(hud.$header).not.toBeNull();
+    expect(hud.$footer).not.toBeNull();
+    expect(hud.$hud!.classList.contains('has-header')).toBe(true);
+    expect(hud.$hud!.classList.contains('has-footer')).toBe(true);
+    // Header hoisted before the main container; footer after it.
+    expect(hud.$header!.nextElementSibling).toBe(hud.$mainContainer);
+    expect(hud.$footer!.previousElementSibling).toBe(hud.$mainContainer);
+  });
+
+  it('clears a previous header/footer when the body is replaced', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    hud.updateBody('<div class="hud-header">H</div>');
+    expect(hud.$hud!.classList.contains('has-header')).toBe(true);
+    hud.updateBody('<p>plain</p>');
+    expect(hud.$header).toBeNull();
+    expect(hud.$hud!.classList.contains('has-header')).toBe(false);
+  });
+
+  it('appends node content', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    const node = document.createElement('span');
+    node.textContent = 'hi';
+    hud.updateBody(node);
+    expect(hud.$main!.contains(node)).toBe(true);
+  });
+});
+
+describe('HUD show/hide', () => {
+  it('show() toggles showing and fires show', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    const onShow = vi.fn();
+    hud.on('show', onShow);
+    hud.show();
+    expect(hud.showing).toBe(true);
+    expect(onShow).toHaveBeenCalledOnce();
+  });
+
+  it('invokes the onShow settings callback (registered as a handler)', () => {
+    const onShow = vi.fn();
+    const hud = new HUD(makeTrigger(), {showOnInit: false, onShow});
+    hud.show();
+    expect(onShow).toHaveBeenCalledOnce();
+  });
+
+  it('sets aria-expanded=true on show and false on hide', () => {
+    const trigger = makeTrigger();
+    const hud = new HUD(trigger, {showOnInit: false});
+    hud.show();
+    expect(trigger.getAttribute('aria-expanded')).toBe('true');
+    hud.hide();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('show() is a no-op when already showing', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    hud.show();
+    const onShow = vi.fn();
+    hud.on('show', onShow);
+    hud.show();
+    expect(onShow).not.toHaveBeenCalled();
+  });
+
+  it('hide() toggles showing and fires hide', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: true});
+    const onHide = vi.fn();
+    hud.on('hide', onHide);
+    hud.hide();
+    expect(hud.showing).toBe(false);
+    expect(onHide).toHaveBeenCalledOnce();
+  });
+
+  it('hide() is a no-op when not showing', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    const onHide = vi.fn();
+    hud.on('hide', onHide);
+    hud.hide();
+    expect(onHide).not.toHaveBeenCalled();
+  });
+
+  it('toggle() flips between show and hide', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    hud.toggle();
+    expect(hud.showing).toBe(true);
+    hud.toggle();
+    expect(hud.showing).toBe(false);
+  });
+
+  it('tracks itself in activeHUDs while showing', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: true});
+    expect(Object.values(HUD.activeHUDs)).toContain(hud);
+    hud.hide();
+    expect(Object.values(HUD.activeHUDs)).not.toContain(hud);
+  });
+
+  it('closeOtherHUDs hides any other open HUD on show', () => {
+    const a = new HUD(makeTrigger(), {showOnInit: true, closeOtherHUDs: true});
+    expect(a.showing).toBe(true);
+    const b = new HUD(makeTrigger(), {showOnInit: true, closeOtherHUDs: true});
+    expect(b.showing).toBe(true);
+    expect(a.showing).toBe(false);
+  });
+
+  it('hideContainer/showContainer toggle the container display', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    hud.hideContainer();
+    expect(hud.$hud!.style.display).toBe('none');
+    hud.showContainer();
+    expect(hud.$hud!.style.display).toBe('block');
+  });
+});
+
+describe('HUD layer + Esc + shade click', () => {
+  it('adds a UI layer on show and removes it on hide', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    expect(manager.layer).toBe(0);
+    hud.show();
+    expect(manager.layer).toBe(1);
+    hud.hide();
+    expect(manager.layer).toBe(0);
+  });
+
+  it('closes on Escape when hideOnEsc is true', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: true, hideOnEsc: true});
+    const ev = new KeyboardEvent('keydown', {keyCode: ESC_KEY} as never);
+    manager.triggerShortcut(ev);
+    expect(hud.showing).toBe(false);
+  });
+
+  it('does not register an Esc shortcut when hideOnEsc is false', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: true, hideOnEsc: false});
+    const ev = new KeyboardEvent('keydown', {keyCode: ESC_KEY} as never);
+    manager.triggerShortcut(ev);
+    expect(hud.showing).toBe(true);
+  });
+
+  it('closes when the shade is clicked (hideOnShadeClick)', () => {
+    const hud = new HUD(makeTrigger(), {
+      showOnInit: true,
+      hideOnShadeClick: true,
+    });
+    hud.$shade!.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(hud.showing).toBe(false);
+  });
+});
+
+describe('HUD submit', () => {
+  it('submit() fires the submit event', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    const onSubmit = vi.fn();
+    hud.on('submit', onSubmit);
+    hud.submit();
+    expect(onSubmit).toHaveBeenCalledOnce();
+  });
+
+  it('a body form submit is intercepted and re-fired as submit', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    const onSubmit = vi.fn();
+    hud.on('submit', onSubmit);
+    const ev = new Event('submit', {bubbles: true, cancelable: true});
+    hud.$body!.dispatchEvent(ev);
+    expect(onSubmit).toHaveBeenCalledOnce();
+    expect(ev.defaultPrevented).toBe(true);
+  });
+
+  it('invokes the onSubmit settings callback', () => {
+    const onSubmit = vi.fn();
+    const hud = new HUD(makeTrigger(), {showOnInit: false, onSubmit});
+    hud.submit();
+    expect(onSubmit).toHaveBeenCalledOnce();
+  });
+});
+
+describe('HUD focus management', () => {
+  it('Tab on the trigger while showing moves focus into the HUD', () => {
+    const trigger = makeTrigger();
+    const hud = new HUD(trigger, {showOnInit: false});
+    const input = document.createElement('input');
+    makeVisible(input);
+    hud.updateBody(input);
+    hud.show();
+
+    const ev = new KeyboardEvent('keydown', {keyCode: TAB_KEY} as never);
+    trigger.dispatchEvent(ev);
+    expect(document.activeElement).toBe(input);
+  });
+
+  it('restores focus to the trigger on hide when focus was inside', () => {
+    const trigger = makeTrigger();
+    const hud = new HUD(trigger, {showOnInit: false});
+    const input = document.createElement('input');
+    makeVisible(input);
+    hud.updateBody(input);
+    hud.show();
+    input.focus();
+    expect(document.activeElement).toBe(input);
+    hud.hide();
+    expect(document.activeElement).toBe(trigger);
+  });
+});
+
+describe('HUD updateSizeAndPosition (mocked layout)', () => {
+  /** Build a HUD with a mocked trigger rect + body content box. */
+  function buildPositioned(
+    triggerTop: number,
+    triggerLeft: number,
+    triggerW: number,
+    triggerH: number,
+    bodyW: number,
+    bodyH: number,
+    settings: Partial<ConstructorParameters<typeof HUD>[1] & object> = {}
+  ): HUD {
+    const trigger = makeTrigger();
+    mockRect(trigger, triggerTop, triggerLeft, triggerW, triggerH);
+    // outerWidth/Height read offsetWidth/Height — stub those too.
+    Object.defineProperty(trigger, 'offsetWidth', {
+      value: triggerW,
+      configurable: true,
+    });
+    Object.defineProperty(trigger, 'offsetHeight', {
+      value: triggerH,
+      configurable: true,
+    });
+    const hud = new HUD(trigger, {showOnInit: false, ...settings});
+    // The body's content box (jQuery `.width()/.height()` → rect minus 0 pad/border).
+    mockRect(hud.$body!, 0, 0, bodyW, bodyH);
+    hud.windowWidth = 1000;
+    hud.windowHeight = 800;
+    return hud;
+  }
+
+  it('picks "bottom" when there is room below the trigger', () => {
+    const hud = buildPositioned(100, 450, 50, 20, 200, 200);
+    hud.updateSizeAndPositionInternal();
+    expect(hud.orientation).toBe('bottom');
+    // tip points back up at the trigger.
+    expect(hud.$tip!.classList.contains('tip-top')).toBe(true);
+  });
+
+  it('falls through to "right" when top/bottom are too short for a tall body', () => {
+    // Trigger near the vertical center, against the left edge; body taller than
+    // top/bottom clearance but narrower than the right clearance.
+    const hud = buildPositioned(400, 0, 50, 20, 200, 700);
+    hud.updateSizeAndPositionInternal();
+    expect(hud.orientation).toBe('right');
+    expect(hud.$tip!.classList.contains('tip-left')).toBe(true);
+  });
+
+  it('respects the orientations preference order', () => {
+    const hud = buildPositioned(400, 0, 50, 20, 200, 200, {
+      orientations: ['right', 'bottom', 'left'],
+    });
+    hud.updateSizeAndPositionInternal();
+    expect(hud.orientation).toBe('right');
+  });
+
+  it('sets the hud left/top and fires updateSizeAndPosition', () => {
+    const hud = buildPositioned(100, 450, 50, 20, 200, 200);
+    const onUpdate = vi.fn();
+    hud.on('updateSizeAndPosition', onUpdate);
+    hud.updateSizeAndPositionInternal();
+    expect(onUpdate).toHaveBeenCalledOnce();
+    expect(hud.$hud!.style.left).not.toBe('');
+    expect(hud.$hud!.style.top).not.toBe('');
+  });
+
+  it('updateSizeAndPosition(true) schedules a deferred reposition', () => {
+    const hud = buildPositioned(100, 450, 50, 20, 200, 200);
+    const internal = vi.spyOn(hud, 'updateSizeAndPositionInternal');
+    hud.updateSizeAndPosition(true);
+    expect(internal).not.toHaveBeenCalled(); // deferred to RAF
+    flushRaf();
+    expect(internal).toHaveBeenCalledOnce();
+  });
+});
+
+describe('HUD updateRecords', () => {
+  it('reports a change on first measurement and stability afterward', () => {
+    const hud = new HUD(makeTrigger(), {showOnInit: false});
+    expect(hud.updateRecords()).toBe(true);
+    expect(hud.updateRecords()).toBe(false);
+  });
+});
+
+describe('HUD destroy', () => {
+  it('removes the hud + shade, drops from instances/activeHUDs, fires destroy', () => {
+    const trigger = makeTrigger();
+    const hud = new HUD(trigger, {showOnInit: true});
+    const onDestroy = vi.fn();
+    hud.on('destroy', onDestroy);
+    const shade = hud.$shade!;
+    const container = hud.$hud!;
+
+    hud.destroy();
+
+    expect(onDestroy).toHaveBeenCalledOnce();
+    expect(HUD.instances).not.toContain(hud);
+    expect(Object.values(HUD.activeHUDs)).not.toContain(hud);
+    expect(document.body.contains(container)).toBe(false);
+    expect(document.body.contains(shade)).toBe(false);
+  });
+});
diff --git a/packages/craftcms-garnish/tests/index.test.ts b/packages/craftcms-garnish/tests/index.test.ts
new file mode 100644
index 00000000000..5edd479e832
--- /dev/null
+++ b/packages/craftcms-garnish/tests/index.test.ts
@@ -0,0 +1,13 @@
+import {describe, expect, it} from 'vitest';
+
+import {VERSION} from '../src/index';
+
+describe('@craftcms/garnish', () => {
+  it('exposes a VERSION constant', () => {
+    expect(VERSION).toBe('0.0.0');
+  });
+
+  it('runs in a DOM environment', () => {
+    expect(typeof document).toBe('object');
+  });
+});
diff --git a/packages/craftcms-garnish/tests/managers.test.ts b/packages/craftcms-garnish/tests/managers.test.ts
new file mode 100644
index 00000000000..fd7f2b0d484
--- /dev/null
+++ b/packages/craftcms-garnish/tests/managers.test.ts
@@ -0,0 +1,91 @@
+import {beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {EscManager} from '../src/managers/esc-manager';
+import {UiLayerManager} from '../src/managers/ui-layer-manager';
+
+describe('EscManager', () => {
+  it('escapeLatest pops the most recently registered handler', () => {
+    const mgr = new EscManager();
+    const first = vi.fn();
+    const second = vi.fn();
+    const objA = {};
+    const objB = {};
+    mgr.register(objA, first);
+    mgr.register(objB, second);
+
+    mgr.escapeLatest(new KeyboardEvent('keyup'));
+    expect(second).toHaveBeenCalledOnce();
+    expect(first).not.toHaveBeenCalled();
+
+    mgr.escapeLatest(new KeyboardEvent('keyup'));
+    expect(first).toHaveBeenCalledOnce();
+  });
+
+  it('unregister removes a handler by object', () => {
+    const mgr = new EscManager();
+    const fn = vi.fn();
+    const obj = {};
+    mgr.register(obj, fn);
+    mgr.unregister(obj);
+    mgr.escapeLatest(new KeyboardEvent('keyup'));
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('triggers `escape` on the registered object when possible', () => {
+    const mgr = new EscManager();
+    const trigger = vi.fn();
+    const obj = {trigger, handle: vi.fn()};
+    mgr.register(obj, 'handle');
+    mgr.escapeLatest(new KeyboardEvent('keyup'));
+    expect(obj.handle).toHaveBeenCalledOnce();
+    expect(trigger).toHaveBeenCalledWith('escape');
+  });
+});
+
+describe('UiLayerManager', () => {
+  let mgr: UiLayerManager;
+
+  beforeEach(() => {
+    mgr = new UiLayerManager();
+  });
+
+  it('starts with a single base layer', () => {
+    expect(mgr.layer).toBe(0);
+    expect(mgr.currentLayer.$container).toBe(document.body);
+  });
+
+  it('addLayer pushes a new layer and detects modals', () => {
+    const container = document.createElement('div');
+    container.setAttribute('aria-modal', 'true');
+    mgr.addLayer(container);
+    expect(mgr.layer).toBe(1);
+    expect(mgr.currentLayer.isModal).toBe(true);
+    expect(mgr.highestModalLayer?.$container).toBe(container);
+  });
+
+  it('addLayer accepts an options-only call (param shift)', () => {
+    mgr.addLayer({bubble: true});
+    expect(mgr.currentLayer.$container).toBeNull();
+    expect(mgr.currentLayer.options.bubble).toBe(true);
+  });
+
+  it('removeLayer pops the top layer', () => {
+    mgr.addLayer(document.createElement('div'));
+    mgr.removeLayer();
+    expect(mgr.layer).toBe(0);
+  });
+
+  it('throws when removing the base layer', () => {
+    expect(() => mgr.removeLayer()).toThrow();
+  });
+
+  it('triggerShortcut fires a registered shortcut callback', () => {
+    const cb = vi.fn();
+    mgr.registerShortcut(27, cb);
+    const ev = new KeyboardEvent('keydown', {keyCode: 27} as never);
+    vi.spyOn(ev, 'preventDefault');
+    mgr.triggerShortcut(ev);
+    expect(cb).toHaveBeenCalledOnce();
+    expect(ev.preventDefault).toHaveBeenCalled();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/modal.test.ts b/packages/craftcms-garnish/tests/modal.test.ts
new file mode 100644
index 00000000000..4f4665d4c35
--- /dev/null
+++ b/packages/craftcms-garnish/tests/modal.test.ts
@@ -0,0 +1,391 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+
+import {Modal} from '../src/modal';
+import {BaseDrag} from '../src/drag/base-drag';
+import {DragMove} from '../src/drag-move';
+import {UiLayerManager} from '../src/managers/ui-layer-manager';
+import {setUiLayerManager} from '../src/managers/registry';
+import {ESC_KEY} from '../src/constants';
+import {globals} from '../src/globals';
+
+// happy-dom does not implement `element.animate`, so Modal's `_fade` takes its
+// immediate-complete fallback path — fade-in/out resolve synchronously here,
+// which keeps these assertions deterministic. (Real browsers still animate.)
+
+let manager: UiLayerManager;
+
+function makeContainer(): HTMLElement {
+  const el = document.createElement('div');
+  el.className = 'modal';
+  // Give it something focusable so setFocusWithin has a target.
+  const input = document.createElement('input');
+  input.type = 'text';
+  // happy-dom has no layout; stub getClientRects so the focusable matcher
+  // treats the input as visible (per core impl note #7).
+  vi.spyOn(input, 'getClientRects').mockReturnValue([
+    {width: 10, height: 10},
+  ] as unknown as DOMRectList);
+  el.appendChild(input);
+  document.body.appendChild(el);
+  return el;
+}
+
+beforeEach(() => {
+  // Fresh UI layer manager per test; register it so Modal can find it.
+  manager = new UiLayerManager();
+  setUiLayerManager(manager);
+  Modal.instances = [];
+  Modal.visibleModal = null;
+  document.body.innerHTML = '';
+  document.body.className = '';
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('Modal construction', () => {
+  it('applies defaults merged with passed settings', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false, minGutter: 25});
+    expect(modal.settings!.minGutter).toBe(25);
+    expect(modal.settings!.hideOnEsc).toBe(true);
+    expect(modal.settings!.shadeClass).toBe('modal-shade');
+    expect(modal.settings!.draggable).toBe(false);
+  });
+
+  it('supports the param-shift form: new Modal(settings)', () => {
+    const modal = new Modal({autoShow: false, closeOtherModals: true});
+    expect(modal.$container).toBeNull();
+    expect(modal.settings!.closeOtherModals).toBe(true);
+    expect(modal.settings!.autoShow).toBe(false);
+  });
+
+  it('registers itself in the static instances list', () => {
+    const modal = new Modal({autoShow: false});
+    expect(Modal.instances).toContain(modal);
+  });
+
+  it('creates a shade element with the configured class', () => {
+    const modal = new Modal({autoShow: false, shadeClass: 'custom-shade'});
+    expect(modal.$shade).not.toBeNull();
+    expect(modal.$shade!.classList.contains('custom-shade')).toBe(true);
+  });
+
+  it('auto-shows when autoShow is true and a container is given', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true});
+    expect(modal.visible).toBe(true);
+    expect(Modal.visibleModal).toBe(modal);
+  });
+
+  it('does not auto-show with autoShow:false', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    expect(modal.visible).toBe(false);
+  });
+});
+
+describe('Modal ARIA + focus', () => {
+  it('applies dialog/aria-modal attributes to the container', () => {
+    const container = makeContainer();
+    new Modal(container, {autoShow: false});
+    expect(container.getAttribute('role')).toBe('dialog');
+    expect(container.getAttribute('aria-modal')).toBe('true');
+  });
+
+  it('adds a live region inside the container', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    expect(container.contains(modal.$liveRegion)).toBe(true);
+    expect(modal.$liveRegion.getAttribute('role')).toBe('status');
+  });
+
+  it('moves focus inside the container on show', () => {
+    const container = makeContainer();
+    const input = container.querySelector('input')!;
+    const modal = new Modal(container, {autoShow: false});
+    modal.show();
+    expect(document.activeElement).toBe(input);
+  });
+});
+
+describe('Modal show/hide', () => {
+  it('show() toggles visible and fires the show event', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    const onShow = vi.fn();
+    modal.on('show', onShow);
+    modal.show();
+    expect(modal.visible).toBe(true);
+    expect(onShow).toHaveBeenCalledOnce();
+    expect(document.body.classList.contains('no-scroll')).toBe(true);
+  });
+
+  it('fires fadeIn after the fade completes', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    const onFadeIn = vi.fn();
+    modal.on('fadeIn', onFadeIn);
+    modal.show();
+    expect(onFadeIn).toHaveBeenCalledOnce();
+  });
+
+  it('calls the onShow settings callback', () => {
+    const container = makeContainer();
+    const onShow = vi.fn();
+    const modal = new Modal(container, {autoShow: false, onShow});
+    modal.show();
+    expect(onShow).toHaveBeenCalledOnce();
+  });
+
+  it('hide() toggles visible and fires the hide event', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true});
+    const onHide = vi.fn();
+    modal.on('hide', onHide);
+    modal.hide();
+    expect(modal.visible).toBe(false);
+    expect(onHide).toHaveBeenCalledOnce();
+    expect(Modal.visibleModal).toBeNull();
+    expect(document.body.classList.contains('no-scroll')).toBe(false);
+  });
+
+  it('hide() is a no-op when not visible', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    const onHide = vi.fn();
+    modal.on('hide', onHide);
+    modal.hide();
+    expect(onHide).not.toHaveBeenCalled();
+  });
+
+  it('show() registers a layer and hide() removes it', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    expect(manager.layer).toBe(0);
+    modal.show();
+    expect(manager.layer).toBe(1);
+    modal.hide();
+    expect(manager.layer).toBe(0);
+  });
+
+  it('closeOtherModals hides the currently visible modal', () => {
+    const a = new Modal(makeContainer(), {autoShow: true});
+    const b = new Modal(makeContainer(), {
+      autoShow: false,
+      closeOtherModals: true,
+    });
+    expect(a.visible).toBe(true);
+    b.show();
+    expect(a.visible).toBe(false);
+    expect(b.visible).toBe(true);
+  });
+
+  it('quickShow leaves the modal visible with full opacity', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    modal.quickShow();
+    expect(modal.visible).toBe(true);
+    expect(container.style.opacity).toBe('1');
+  });
+
+  it('quickHide leaves the modal hidden', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true});
+    modal.quickHide();
+    expect(modal.visible).toBe(false);
+    expect(container.style.display).toBe('none');
+  });
+});
+
+describe('Modal ESC + shade-click closing', () => {
+  it('closes on ESC when hideOnEsc is true', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true, hideOnEsc: true});
+    const onEscape = vi.fn();
+    modal.on('escape', onEscape);
+
+    const ev = new KeyboardEvent('keydown', {keyCode: ESC_KEY} as never);
+    manager.triggerShortcut(ev);
+
+    expect(onEscape).toHaveBeenCalledOnce();
+    expect(modal.visible).toBe(false);
+  });
+
+  it('does not register an ESC shortcut when hideOnEsc is false', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true, hideOnEsc: false});
+
+    const ev = new KeyboardEvent('keydown', {keyCode: ESC_KEY} as never);
+    manager.triggerShortcut(ev);
+
+    expect(modal.visible).toBe(true);
+  });
+
+  it('closes when the shade is clicked (hideOnShadeClick)', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {
+      autoShow: true,
+      hideOnShadeClick: true,
+    });
+    modal.$shade!.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(modal.visible).toBe(false);
+  });
+
+  it('does not close on shade click when hideOnShadeClick is false', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {
+      autoShow: true,
+      hideOnShadeClick: false,
+    });
+    modal.$shade!.dispatchEvent(new MouseEvent('click', {bubbles: true}));
+    expect(modal.visible).toBe(true);
+  });
+});
+
+describe('Modal getWidth/getHeight/updateSizeAndPosition', () => {
+  it('getWidth/getHeight throw when no container is set', () => {
+    const modal = new Modal({autoShow: false});
+    expect(() => modal.getWidth()).toThrow();
+    expect(() => modal.getHeight()).toThrow();
+  });
+
+  it('updateSizeAndPosition is a no-op without a container', () => {
+    const modal = new Modal({autoShow: false});
+    expect(() => modal.updateSizeAndPosition()).not.toThrow();
+  });
+
+  it('updateSizeAndPosition centers the container and fires its event', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    const onUpdate = vi.fn();
+    modal.on('updateSizeAndPosition', onUpdate);
+    modal.updateSizeAndPosition();
+    expect(onUpdate).toHaveBeenCalled();
+    expect(container.style.left).not.toBe('');
+    expect(container.style.top).not.toBe('');
+  });
+});
+
+describe('Modal destroy', () => {
+  it('removes the instance, container, and shade and fires destroy', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    const onDestroy = vi.fn();
+    modal.on('destroy', onDestroy);
+
+    modal.destroy();
+
+    expect(onDestroy).toHaveBeenCalledOnce();
+    expect(Modal.instances).not.toContain(modal);
+    expect(document.body.contains(container)).toBe(false);
+    expect(document.body.contains(modal.$shade!)).toBe(false);
+  });
+
+  it('clears visibleModal if the destroyed modal was visible', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: true});
+    expect(Modal.visibleModal).toBe(modal);
+    modal.destroy();
+    expect(Modal.visibleModal).toBeNull();
+  });
+});
+
+describe('Modal draggable/resizable', () => {
+  it('constructs without throwing and creates a DragMove when draggable', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false, draggable: true});
+    expect(modal.dragger).toBeInstanceOf(DragMove);
+    // The container itself is the default handle (registered with the dragger).
+    expect(modal.dragger!.$items).toContain(container);
+  });
+
+  it('uses the dragHandleSelector as the DragMove handle when given', () => {
+    const container = makeContainer();
+    const handle = document.createElement('div');
+    handle.className = 'drag-handle';
+    container.appendChild(handle);
+    const modal = new Modal(container, {
+      autoShow: false,
+      draggable: true,
+      dragHandleSelector: '.drag-handle',
+    });
+    // The item is still the container; only the handle differs (drag from it).
+    expect(modal.dragger).toBeInstanceOf(DragMove);
+    expect(modal.dragger!.$items).toContain(container);
+  });
+
+  it('constructs without throwing and creates a BaseDrag + resize handle when resizable', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false, resizable: true});
+    expect(modal.resizeDragger).toBeInstanceOf(BaseDrag);
+    const handle = container.querySelector('.resizehandle');
+    expect(handle).not.toBeNull();
+    expect(modal.resizeDragger!.$items).toContain(handle);
+  });
+
+  it('does not create draggers by default', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false});
+    expect(modal.dragger).toBeNull();
+    expect(modal.resizeDragger).toBeNull();
+  });
+
+  it('_handleResize grows width/height symmetrically (ltr) from the start size', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false, resizable: true});
+    document.body.classList.remove('rtl');
+    globals.rtl = false;
+
+    vi.spyOn(modal, 'getWidth').mockReturnValue(400);
+    vi.spyOn(modal, 'getHeight').mockReturnValue(300);
+    const update = vi
+      .spyOn(modal, 'updateSizeAndPosition')
+      .mockImplementation(() => {});
+
+    // Drive the resize handlers directly with a fake dragger delta.
+    (modal as unknown as {_handleResizeStart(): void})._handleResizeStart();
+    modal.resizeDragger!.mouseDistX = 10;
+    modal.resizeDragger!.mouseDistY = 5;
+    (modal as unknown as {_handleResize(): void})._handleResize();
+
+    expect(modal.desiredWidth).toBe(400 + 10 * 2);
+    expect(modal.desiredHeight).toBe(300 + 5 * 2);
+    expect(update).toHaveBeenCalled();
+  });
+
+  it('_handleResize mirrors the horizontal direction in rtl', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {autoShow: false, resizable: true});
+    globals.rtl = true;
+
+    vi.spyOn(modal, 'getWidth').mockReturnValue(400);
+    vi.spyOn(modal, 'getHeight').mockReturnValue(300);
+    vi.spyOn(modal, 'updateSizeAndPosition').mockImplementation(() => {});
+
+    (modal as unknown as {_handleResizeStart(): void})._handleResizeStart();
+    modal.resizeDragger!.mouseDistX = 10;
+    modal.resizeDragger!.mouseDistY = 5;
+    (modal as unknown as {_handleResize(): void})._handleResize();
+
+    expect(modal.desiredWidth).toBe(400 - 10 * 2);
+    expect(modal.desiredHeight).toBe(300 + 5 * 2);
+
+    globals.rtl = false;
+  });
+
+  it('tears down both draggers on destroy', () => {
+    const container = makeContainer();
+    const modal = new Modal(container, {
+      autoShow: false,
+      draggable: true,
+      resizable: true,
+    });
+    const dragDestroy = vi.spyOn(modal.dragger!, 'destroy');
+    const resizeDestroy = vi.spyOn(modal.resizeDragger!, 'destroy');
+    modal.destroy();
+    expect(dragDestroy).toHaveBeenCalledOnce();
+    expect(resizeDestroy).toHaveBeenCalledOnce();
+  });
+});
diff --git a/packages/craftcms-garnish/tests/utils.test.ts b/packages/craftcms-garnish/tests/utils.test.ts
new file mode 100644
index 00000000000..8dd976b2efd
--- /dev/null
+++ b/packages/craftcms-garnish/tests/utils.test.ts
@@ -0,0 +1,78 @@
+import {describe, expect, it} from 'vitest';
+
+import {getDist, within, isString, isTextNode} from '../src/utils/misc';
+import {getInputPostVal, getPostData, findInputs} from '../src/utils/forms';
+import {hasAttr} from '../src/utils/dom';
+
+describe('misc utils', () => {
+  it('getDist computes Euclidean distance', () => {
+    expect(getDist(0, 0, 3, 4)).toBe(5);
+  });
+  it('within clamps', () => {
+    expect(within(5, 0, 10)).toBe(5);
+    expect(within(-1, 0, 10)).toBe(0);
+    expect(within(11, 0, 10)).toBe(10);
+  });
+  it('isString', () => {
+    expect(isString('x')).toBe(true);
+    expect(isString(1)).toBe(false);
+  });
+  it('isTextNode', () => {
+    expect(isTextNode(document.createTextNode('x'))).toBe(true);
+    expect(isTextNode(document.createElement('div'))).toBe(false);
+  });
+});
+
+describe('dom utils', () => {
+  it('hasAttr reflects attribute presence', () => {
+    const el = document.createElement('a');
+    expect(hasAttr(el, 'href')).toBe(false);
+    el.setAttribute('href', '/x');
+    expect(hasAttr(el, 'href')).toBe(true);
+  });
+});
+
+describe('forms utils', () => {
+  it('getInputPostVal returns null for an unchecked checkbox', () => {
+    const cb = document.createElement('input');
+    cb.type = 'checkbox';
+    cb.value = 'yes';
+    expect(getInputPostVal(cb)).toBeNull();
+    cb.checked = true;
+    expect(getInputPostVal(cb)).toBe('yes');
+  });
+
+  it('findInputs collects inputs within a container', () => {
+    const container = document.createElement('div');
+    container.innerHTML =
+      '<input name="a"><textarea name="b"></textarea><select name="c"></select><button name="d"></button>';
+    expect(findInputs(container)).toHaveLength(4);
+  });
+
+  it('getPostData serializes name[] arrays with indexing', () => {
+    const container = document.createElement('div');
+    const i1 = document.createElement('input');
+    i1.name = 'tags[]';
+    i1.value = 'x';
+    const i2 = document.createElement('input');
+    i2.name = 'tags[]';
+    i2.value = 'y';
+    container.appendChild(i1);
+    container.appendChild(i2);
+    expect(getPostData(container)).toEqual({'tags[0]': 'x', 'tags[1]': 'y'});
+  });
+
+  it('getPostData skips disabled and unnamed inputs', () => {
+    const container = document.createElement('div');
+    const named = document.createElement('input');
+    named.name = 'a';
+    named.value = '1';
+    const disabled = document.createElement('input');
+    disabled.name = 'b';
+    disabled.value = '2';
+    disabled.disabled = true;
+    container.appendChild(named);
+    container.appendChild(disabled);
+    expect(getPostData(container)).toEqual({a: '1'});
+  });
+});
diff --git a/packages/craftcms-garnish/tsconfig.json b/packages/craftcms-garnish/tsconfig.json
new file mode 100644
index 00000000000..5f320ebf345
--- /dev/null
+++ b/packages/craftcms-garnish/tsconfig.json
@@ -0,0 +1,19 @@
+{
+  "extends": "@total-typescript/tsconfig/bundler/dom",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": ".",
+    "types": ["node", "vitest/globals"],
+    "paths": {
+      "@src/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "src",
+    "tests",
+    "stories",
+    ".storybook",
+    "tsdown.config.ts",
+    "vitest.config.ts"
+  ]
+}
diff --git a/packages/craftcms-garnish/tsdown.config.ts b/packages/craftcms-garnish/tsdown.config.ts
new file mode 100644
index 00000000000..793d08f15cc
--- /dev/null
+++ b/packages/craftcms-garnish/tsdown.config.ts
@@ -0,0 +1,33 @@
+import {defineConfig} from 'tsdown';
+
+export default defineConfig({
+  // Multiple entry points so consumers can opt into the legacy compatibility
+  // layer separately from the modern core. tsdown/Rolldown will code-split
+  // shared chunks between these automatically.
+  entry: {
+    index: './src/index.ts',
+    compat: './src/compat.ts',
+  },
+  format: ['esm'],
+  target: 'es2022',
+  platform: 'browser',
+  // Emit TypeScript declarations alongside the JS output.
+  dts: true,
+  sourcemap: true,
+  // Clean dist before each build.
+  clean: true,
+  // Tree-shakeable, ESM-only output.
+  treeshake: true,
+  // Keep readable output during the scaffold phase; flip on for releases.
+  minify: false,
+  // No external deps yet — this is a zero-dependency library by design
+  // (explicitly no jQuery). List peerDependencies under `deps.neverBundle`
+  // as they appear so they are not inlined into the bundle.
+  // jQuery is an OPTIONAL peer dependency of the `./compat` entry only. It is
+  // resolved at runtime from the global scope, never imported, so it can't leak
+  // into the bundle — but list it here so the build never inlines it should a
+  // future `import 'jquery'` be added.
+  deps: {
+    neverBundle: ['jquery'],
+  },
+});
diff --git a/packages/craftcms-garnish/vitest.config.ts b/packages/craftcms-garnish/vitest.config.ts
new file mode 100644
index 00000000000..dbaee5d6c12
--- /dev/null
+++ b/packages/craftcms-garnish/vitest.config.ts
@@ -0,0 +1,9 @@
+import {defineConfig} from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'happy-dom',
+    include: ['tests/**/*.{test,spec}.ts'],
+  },
+});
diff --git a/packages/craftcms-legacy/cp/src/Craft.js b/packages/craftcms-legacy/cp/src/Craft.js
index 5e31a09b3c4..2124da41d0e 100644
--- a/packages/craftcms-legacy/cp/src/Craft.js
+++ b/packages/craftcms-legacy/cp/src/Craft.js
@@ -69,7 +69,6 @@ import './js/EntrySelectInput.js';
 import './js/EntryTypeSelectInput.js';
 import './js/EnvVarGenerator.js';
 import './js/EntryMover.js';
-import './js/FieldLayoutDesigner.js';
 import './js/FormObserver.js';
 import './js/VolumeFolderSelectorModal.js';
 import './js/FieldToggle.js';
diff --git a/packages/craftcms-legacy/cp/src/css/craft.scss b/packages/craftcms-legacy/cp/src/css/craft.scss
index ff419da226b..105f235f9bd 100644
--- a/packages/craftcms-legacy/cp/src/css/craft.scss
+++ b/packages/craftcms-legacy/cp/src/css/craft.scss
@@ -7,19 +7,17 @@
 @import 'icon-picker';
 @import 'login';
 
-.cp-legacy {
-  @import 'main';
-  @import 'cp';
-  @import 'range';
-  @import 'global-sidebar';
-  @import 'craft-disclosure';
-  @import 'craft-spinner';
-  @import 'craft-tooltip';
-  @import 'preview';
-  @import 'entry-type-select';
-  @import 'fld';
-  @import 'grouped-entry-type-select';
-  @import 'image_editor';
-  @import 'shame';
-  @import 'debug_toolbar';
-}
+@import 'main';
+@import 'cp';
+@import 'range';
+@import 'global-sidebar';
+@import 'craft-disclosure';
+@import 'craft-spinner';
+@import 'craft-tooltip';
+@import 'preview';
+@import 'entry-type-select';
+@import 'fld';
+@import 'grouped-entry-type-select';
+@import 'image_editor';
+@import 'shame';
+@import 'debug_toolbar';
diff --git a/packages/craftcms-legacy/cp/src/js/FieldLayoutDesigner.js b/packages/craftcms-legacy/cp/src/js/FieldLayoutDesigner.js
deleted file mode 100644
index cc9a7f4f81e..00000000000
--- a/packages/craftcms-legacy/cp/src/js/FieldLayoutDesigner.js
+++ /dev/null
@@ -1,2195 +0,0 @@
-/** global: Craft */
-/** global: Garnish */
-/** global: $ */
-/** global: jQuery */
-
-Craft.FieldLayoutDesigner = Garnish.Base.extend(
-  {
-    $container: null,
-    $innerContainer: null,
-    $configInput: null,
-    $tabContainer: null,
-    $newTabBtn: null,
-    $libraryContainer: null,
-    $selectedLibrary: null,
-    $fieldLibrary: null,
-    $uiLibrary: null,
-    $uiLibraryElements: null,
-    $fieldSearch: null,
-    $clearFieldSearchBtn: null,
-    $fieldGroups: null,
-    $fields: null,
-    $createFieldBtn: null,
-
-    libraryPicker: null,
-    tabGrid: null,
-    elementDrag: null,
-
-    cvd: null,
-    $cvd: null,
-
-    _config: null,
-    _$selectedFields: null,
-
-    init: function (container, settings) {
-      this.$container = $(container);
-      this.setSettings(settings, Craft.FieldLayoutDesigner.defaults);
-
-      this.$configInput = this.$container.children('input[data-config-input]');
-      this._config = JSON.parse(this.$configInput.val());
-      if (!this._config.tabs) {
-        this._config.tabs = [];
-      }
-
-      this._fieldHandles = {};
-
-      this.$innerContainer = this.$container.children('.fld-container');
-      const $workspace = this.$innerContainer.children('.fld-workspace');
-      this.$tabContainer = $workspace.children('.fld-tabs');
-      this.$newTabBtn = $workspace.children('.fld-new-tab-btn');
-      this.$libraryContainer = this.$innerContainer.children('.fld-library');
-
-      this.$fieldLibrary = this.$selectedLibrary =
-        this.$libraryContainer.children('.fld-field-library');
-      let $fieldSearchContainer = this.$fieldLibrary.children('.search');
-      this.$fieldSearch = $fieldSearchContainer.children('input');
-      this.$clearFieldSearchBtn = $fieldSearchContainer.children('.clear-btn');
-      this.$fieldGroups = this.$libraryContainer.find('.fld-field-group');
-      this.$fields = this.$fieldGroups.children('.fld-element');
-      this.$uiLibrary = this.$libraryContainer.children('.fld-ui-library');
-      this.$uiLibraryElements = this.$uiLibrary.children();
-
-      if (this.settings.readOnly) {
-        this.$fieldLibrary.attr('tabindex', '-1');
-      }
-      // Set up the layout grids
-      this.tabGrid = new Craft.Grid(this.$tabContainer, {
-        itemSelector: '.fld-tab',
-        minColWidth: 24 * 13,
-        fillMode: 'grid',
-        snapToGrid: 24,
-      });
-
-      let $tabs = this.$tabContainer.children();
-      for (let i = 0; i < $tabs.length; i++) {
-        this.initTab($($tabs[i]));
-      }
-
-      this.elementDrag = new Craft.FieldLayoutDesigner.ElementDrag(this);
-      if (!this.settings.readOnly) {
-        this.initLibraryElements(this.$libraryContainer.find('.fld-element'));
-      }
-
-      if (this.settings.customizableTabs) {
-        this.tabDrag = new Craft.FieldLayoutDesigner.TabDrag(this);
-
-        this.addListener(this.$newTabBtn, 'activate', 'addTab');
-      }
-
-      // Set up the library
-      if (this.settings.customizableUi) {
-        const $libraryPicker = this.$libraryContainer.children('.btngroup');
-        this.libraryPicker = new Craft.Listbox($libraryPicker, {
-          onChange: ($selectedOption) => {
-            const library = $selectedOption.data('library');
-            switch (library) {
-              case 'field':
-                this.$fieldLibrary.removeClass('hidden');
-                this.$uiLibrary.addClass('hidden');
-                this.$createFieldBtn.removeClass('hidden');
-                break;
-              case 'ui':
-                this.$fieldLibrary.addClass('hidden');
-                this.$uiLibrary.removeClass('hidden');
-                this.$createFieldBtn.addClass('hidden');
-                break;
-            }
-          },
-        });
-      }
-
-      this.addListener(this.$fieldSearch, 'input', () => {
-        this.updateFieldSearchResults();
-      });
-
-      this.addListener(this.$fieldSearch, 'keydown', (ev) => {
-        switch (ev.keyCode) {
-          case Garnish.ESC_KEY:
-            this.$fieldSearch.val('').trigger('input');
-            break;
-          case Garnish.RETURN_KEY:
-            // they most likely don't want to submit the form from here
-            ev.preventDefault();
-            break;
-        }
-      });
-
-      // Clear the search when the X button is clicked
-      this.addListener(this.$clearFieldSearchBtn, 'click', () => {
-        this.clearSearch();
-      });
-
-      this.refreshSelectedFields();
-
-      // Add the “New Field” button
-      this.$createFieldBtn = Craft.ui
-        .createButton({
-          label: Craft.t('app', 'New field'),
-          class: 'mt-m fullwidth add icon dashed',
-          disabled: this.settings.readOnly,
-        })
-        .appendTo(this.$libraryContainer);
-
-      this.addListener(this.$createFieldBtn, 'activate', async () => {
-        this.createField();
-      });
-
-      // initiate Card Attributes Designer
-      if (this.settings.withCardViewDesigner) {
-        this.$cvd = this.$container
-          .parents('.fld-cvd')
-          .find('.card-view-designer');
-        this.initCvd();
-      }
-    },
-
-    updateFieldSearchResults() {
-      const val = this.$fieldSearch.val().toLowerCase().replace(/['"]/g, '');
-      if (!val) {
-        this.$fieldLibrary.find('.filtered').removeClass('filtered');
-        this.$clearFieldSearchBtn.addClass('hidden');
-        return;
-      }
-
-      this.$clearFieldSearchBtn.removeClass('hidden');
-      const $matches = this.$fields
-        .filter(`[data-keywords*="${val}"]`)
-        .add(
-          this.$fieldGroups
-            .filter(`[data-name*="${val}"]`)
-            .children('.fld-element')
-        )
-        .removeClass('filtered');
-      this.$fields.not($matches).addClass('filtered');
-
-      // hide any groups that don't have any results
-      for (let i = 0; i < this.$fieldGroups.length; i++) {
-        const $group = this.$fieldGroups.eq(i);
-        if ($group.find('.fld-element:not(.hidden):not(.filtered)').length) {
-          $group.removeClass('filtered');
-        } else {
-          $group.addClass('filtered');
-        }
-      }
-    },
-
-    clearSearch: function () {
-      this.$fieldSearch.val('').trigger('input');
-    },
-
-    initCvd: function () {
-      this.cvd = new Craft.FieldLayoutDesigner.CardViewDesigner(
-        this,
-        this.$cvd
-      );
-
-      // Add skip link
-      const skipLinkAnchor = this.cvd.$container.attr('id');
-
-      if (skipLinkAnchor) {
-        const $skipLink = $('<a/>', {
-          class: 'skip-link btn',
-          text: Craft.t('app', 'Skip to card view designer'),
-          href: `#${skipLinkAnchor}`,
-        });
-
-        this.cvd.$container.attr('tabindex', '-1');
-        this.$innerContainer.prepend($skipLink);
-      }
-    },
-
-    initTab: function ($tab) {
-      return new Craft.FieldLayoutDesigner.Tab(this, $tab);
-    },
-
-    removeFieldByHandle: function (attribute) {
-      this.$fields
-        .filter(`[data-attribute="${attribute}"]:first`)
-        .removeClass('hidden')
-        .closest('.fld-field-group')
-        .removeClass('hidden');
-    },
-
-    addTab: function () {
-      if (!this.settings.customizableTabs) {
-        return;
-      }
-
-      let defaultValue = '';
-      if (this.tabGrid.$items.length === 0) {
-        defaultValue = Craft.t('app', 'Content');
-      }
-      const name = Craft.escapeHtml(
-        prompt(Craft.t('app', 'Give your tab a name.'), defaultValue)
-      );
-
-      if (!name) {
-        return;
-      }
-
-      const $tab = $(`
-<div class="fld-tab">
-  <div class="tabs">
-    <div class="tab sel draggable">
-      <h3 class="fld-tab__name">${name}</h3>
-    </div>
-  </div>
-  <div class="fld-tabcontent">
-    <button class="btn add icon dashed fullwidth fld-add-btn" type="button">
-      ${Craft.t('app', 'Add')}
-    </button>
-  </div>
-</div>
-`);
-      // keep it before the resize object
-      const $lastTab = this.$tabContainer.children('.fld-tab:last');
-      if ($lastTab.length) {
-        $tab.insertAfter($lastTab);
-      } else {
-        $tab.prependTo(this.$tabContainer);
-      }
-
-      this.tabGrid.addItems($tab);
-      this.tabDrag.addItems($tab);
-
-      const tab = this.initTab($tab);
-      tab.updatePositionInConfig();
-    },
-
-    get config() {
-      return this._config;
-    },
-
-    set config(config) {
-      this._config = config;
-      this.$configInput.val(JSON.stringify(config));
-    },
-
-    updateConfig: function (callback) {
-      const config = callback(this.config);
-      if (config !== false) {
-        this.config = config;
-      }
-    },
-
-    refreshSelectedFields: function () {
-      this._$selectedFields = this.$tabContainer.find('.fld-field');
-    },
-
-    refreshLibraryFields() {
-      this.$fields = this.$fieldGroups.children('.fld-element');
-
-      for (let i = 0; i < this.$fieldGroups.length; i++) {
-        const $fieldGroup = this.$fieldGroups.eq(i);
-        const $fields = $fieldGroup.children('.fld-element');
-        $fields
-          .sort((a, b) => {
-            return $(a).data('ui-label') > $(b).data('ui-label') ? 1 : -1;
-          })
-          .appendTo($fieldGroup);
-      }
-
-      this.updateFieldSearchResults();
-    },
-
-    hasHandle: function (handle) {
-      for (let i = 0; i < this._$selectedFields.length; i++) {
-        const element = this._$selectedFields.eq(i).data('fld-element');
-        const elementHandle = element.config.handle || element.attribute;
-        if (handle === elementHandle) {
-          return true;
-        }
-      }
-
-      return false;
-    },
-
-    createField() {
-      const slideout = new Craft.CpScreenSlideout('fields/edit-field');
-
-      slideout.on('submit', async ({response}) => {
-        // add the library selector
-        const $selector = $(response.data.selectorHtml);
-        this.$fieldGroups.last().append($selector).removeClass('hidden');
-        this.refreshLibraryFields();
-        this.initLibraryElements($selector);
-
-        // add it to the active tab
-        this.addLibraryElementToActiveTab($selector);
-
-        Garnish.requestAnimationFrame(() => {
-          this.getActiveHud()?.hide();
-        });
-      });
-    },
-
-    initLibraryElements($elements) {
-      this.elementDrag.addItems($elements);
-
-      this.addListener($elements, 'activate', (ev) => {
-        // ignore if is on a dragged element
-        if (ev.currentTarget.style.visibility === 'hidden') {
-          return;
-        }
-        ev.stopPropagation();
-        ev.originalEvent.preventDefault();
-        this.addLibraryElementToActiveTab(ev.currentTarget);
-      });
-    },
-
-    cloneLibraryElementForSelection(libraryElement) {
-      // Create a new element based on that one
-      const $libraryElement = $(libraryElement);
-      const $element = $libraryElement
-        .clone()
-        .removeClass('unused')
-        .removeAttr('tabindex');
-
-      if (!Garnish.hasAttr($libraryElement, 'data-is-multi-instance')) {
-        // Hide the library element
-        $libraryElement
-          .css({visibility: 'inherit', display: 'field'})
-          .addClass('hidden');
-
-        // Hide the group too?
-        if ($libraryElement.siblings('.fld-field:not(.hidden)').length === 0) {
-          $libraryElement.closest('.fld-field-group').addClass('hidden');
-        }
-      }
-
-      // Add it to the element dragger
-      this.elementDrag.addItems($element);
-
-      return $element;
-    },
-
-    getActiveHud: function () {
-      return this.$libraryContainer.closest('.fld-library-hud').data('hud');
-    },
-
-    addLibraryElementToActiveTab: function (libraryElement) {
-      const hud = this.getActiveHud();
-      if (!hud) {
-        return;
-      }
-
-      const $element = this.cloneLibraryElementForSelection(libraryElement);
-      const tab = hud.$trigger.closest('.fld-tab').data('fld-tab');
-      $element.insertBefore(hud.$trigger);
-      const element = tab.initElement($element);
-      element.onSelect();
-      element.updatePositionInConfig();
-    },
-  },
-  {
-    defaults: {
-      elementType: null,
-      customizableTabs: true,
-      customizableUi: true,
-      withCardViewDesigner: false,
-      alwaysShowThumbAlignmentBtns: false,
-      readOnly: false,
-    },
-
-    async createSlideout(data, js, settings = {}) {
-      const $body = $('<div/>', {class: 'fld-element-settings-body'});
-      $('<div/>', {class: 'fields', html: data.settingsHtml}).appendTo($body);
-      const $footer = $('<div/>', {class: 'fld-element-settings-footer'});
-      $('<div/>', {class: 'flex-grow'}).appendTo($footer);
-      const $cancelBtn = Craft.ui
-        .createButton({
-          label: Craft.t('app', 'Close'),
-          spinner: true,
-        })
-        .appendTo($footer);
-      Craft.ui
-        .createSubmitButton({
-          class: 'secondary',
-          label: Craft.t('app', 'Apply'),
-          spinner: true,
-        })
-        .appendTo($footer);
-      const $contents = $body.add($footer);
-
-      const slideout = new Craft.Slideout(
-        $contents,
-        Object.assign(
-          {
-            containerElement: 'form',
-            containerAttributes: {
-              action: '',
-              method: 'post',
-              novalidate: '',
-              class: 'fld-element-settings',
-            },
-          },
-          settings
-        )
-      );
-      slideout.on('open', () => {
-        // Hold off a sec until it's positioned...
-        Garnish.requestAnimationFrame(() => {
-          // Focus on the first text input
-          slideout.$container.find('.text:first').focus();
-        });
-      });
-
-      $cancelBtn.on('click', () => {
-        slideout.close();
-      });
-
-      if (data.headHtml) {
-        await Craft.appendHeadHtml(data.headHtml);
-      }
-      if (data.bodyHtml) {
-        await Craft.appendBodyHtml(data.bodyHtml);
-      }
-      if (js) {
-        eval(js);
-      }
-
-      Craft.initUiElements(slideout.$container);
-
-      return slideout;
-    },
-  }
-);
-
-Craft.FieldLayoutDesigner.Tab = Garnish.Base.extend({
-  designer: null,
-  uid: null,
-  $container: null,
-  $addBtn: null,
-  slideout: null,
-  destroyed: false,
-
-  init: function (designer, $container) {
-    this.designer = designer;
-    this.$container = $container;
-    this.$container.data('fld-tab', this);
-    this.uid = this.$container.data('uid');
-
-    // New tab?
-    if (!this.uid) {
-      this.uid = Craft.uuid();
-      this.config = {
-        uid: this.uid,
-        name: this.$container.find('.tabs .tab .fld-tab__name').text(),
-        elements: [],
-      };
-    }
-
-    if (this.designer.settings.customizableTabs) {
-      this.createMenu();
-    }
-
-    // initialize the elements
-    const $tabContent = this.$container.children('.fld-tabcontent');
-
-    $tabContent.on('resize', () => {
-      this.designer.tabGrid.refreshCols(true);
-    });
-
-    this.$addBtn = $tabContent.children('.fld-add-btn');
-
-    const hud = new Garnish.HUD(this.$addBtn, {
-      hudClass: 'hud fld-library-hud cp-legacy',
-      listenToMainResize: false,
-      showOnInit: false,
-      orientations: ['right', 'bottom', 'left'],
-    });
-    hud.on('show', () => {
-      this.designer.$libraryContainer.appendTo(hud.$main);
-      this.designer.libraryPicker?.select(0);
-      this.designer.$fieldSearch.focus();
-      this.designer.clearSearch();
-      this.designer.$fieldLibrary.scrollTop(0);
-    });
-    hud.on('hide', () => {
-      this.$addBtn.focus();
-    });
-
-    this.$addBtn.on('activate', () => {
-      hud.show();
-    });
-
-    const $elements = $tabContent.children().not(this.$addBtn);
-
-    for (let i = 0; i < $elements.length; i++) {
-      this.initElement($($elements[i]));
-    }
-  },
-
-  createMenu: function () {
-    const $tab = this.$container.find('.tabs .tab');
-    const menuId = `actionmenu${Math.floor(Math.random() * 1000000)}`;
-    const $btn = $('<button/>', {
-      type: 'button',
-      class: 'btn action-btn',
-      'data-disclosure-trigger': 'true',
-      'aria-controls': menuId,
-      'aria-haspopup': 'true',
-      'aria-label': Craft.t('app', 'Actions'),
-      title: Craft.t('app', 'Actions'),
-      disabled: this.designer.settings.readOnly,
-    }).appendTo($tab);
-    const $menu = $('<div/>', {
-      id: menuId,
-      class: 'menu menu--disclosure',
-      'data-disclosure-menu': 'true',
-    }).appendTo($tab);
-
-    const disclosureMenu = $btn.disclosureMenu().data('disclosureMenu');
-
-    disclosureMenu.addItem(
-      {
-        label: Craft.t('app', 'Settings'),
-        icon: async () => await Craft.ui.icon('gear'),
-        onActivate: () => {
-          this.createSettings();
-        },
-      },
-      disclosureMenu.addGroup()
-    );
-
-    const moveUl = disclosureMenu.addGroup();
-    const moveLeftBtn = disclosureMenu.addItem(
-      {
-        label:
-          Craft.orientation === 'ltr'
-            ? Craft.t('app', 'Move to the left')
-            : Craft.t('app', 'Move to the right'),
-        icon: async () =>
-          await Craft.ui.icon(
-            Craft.orientation === 'ltr' ? 'arrow-left' : 'arrow-right'
-          ),
-        onActivate: () => {
-          this.moveLeft();
-        },
-      },
-      moveUl
-    );
-
-    const moveRightBtn = disclosureMenu.addItem(
-      {
-        label:
-          Craft.orientation === 'ltr'
-            ? Craft.t('app', 'Move to the right')
-            : Craft.t('app', 'Move to the left'),
-        icon: async () =>
-          await Craft.ui.icon(
-            Craft.orientation === 'ltr' ? 'arrow-right' : 'arrow-left'
-          ),
-        onActivate: () => {
-          this.moveRight();
-        },
-      },
-      moveUl
-    );
-
-    disclosureMenu.addItem(
-      {
-        label: Craft.t('app', 'Remove'),
-        icon: async () => await Craft.ui.icon('xmark'),
-        destructive: true,
-        onActivate: () => {
-          this.destroy();
-        },
-      },
-      disclosureMenu.addGroup()
-    );
-
-    disclosureMenu.on('show', () => {
-      disclosureMenu.toggleItem(
-        moveLeftBtn,
-        this.$container.prev('.fld-tab').length
-      );
-      disclosureMenu.toggleItem(
-        moveRightBtn,
-        this.$container.next('.fld-tab').length
-      );
-    });
-  },
-
-  async createSettings() {
-    let data;
-    try {
-      const response = await Craft.sendActionRequest(
-        'POST',
-        'fields/render-layout-component-settings',
-        {
-          data: {
-            uid: this.uid,
-            layoutConfig: this.designer.config,
-            elementType: this.designer.settings.elementType,
-          },
-        }
-      );
-      data = response.data;
-    } catch (e) {
-      Craft.cp.displayError(e?.response?.data?.message);
-      throw e;
-    }
-
-    this.settingsNamespace = data.namespace;
-    this.slideout = await Craft.FieldLayoutDesigner.createSlideout(data, null, {
-      triggerElement: this.$actionBtn,
-    });
-
-    this.slideout.$container.on('submit', (ev) => {
-      ev.preventDefault();
-      this.applySettings();
-    });
-    this.slideout.on('close', () => {
-      this.slideout.destroy();
-      this.slideout = null;
-    });
-  },
-
-  applySettings: function () {
-    if (!this.slideout.$container.find('[name$="[name]"]').val()) {
-      Craft.cp.displayError(Craft.t('app', 'You must specify a tab name.'));
-      return;
-    }
-
-    // update the UI
-    let $submitBtn = this.slideout.$container
-      .find('button[type=submit]')
-      .addClass('loading');
-
-    const config = $.extend({}, this.config);
-    delete config.elements;
-
-    Craft.sendActionRequest('POST', 'fields/apply-layout-tab-settings', {
-      data: {
-        uid: this.uid,
-        layoutConfig: this.designer.config,
-        elementType: this.designer.settings.elementType,
-        config,
-        settingsNamespace: this.settingsNamespace,
-        settings: this.slideout.$container.serialize(),
-      },
-    })
-      .then((response) => {
-        this.updateConfig((config) =>
-          $.extend(response.data.config, {elements: config.elements})
-        );
-        const $label = this.$container.find('.tabs .tab');
-        const $actionBtn = $label.children('button').detach();
-        $label.html(response.data.labelHtml).append($actionBtn);
-        this.slideout.close();
-      })
-      .catch((e) => {
-        Craft.cp.displayError();
-        console.error(e);
-      })
-      .finally(() => {
-        $submitBtn.removeClass('loading');
-        this.slideout.close();
-      });
-  },
-
-  moveLeft() {
-    let $prev = this.$container.prev('.fld-tab');
-    if ($prev.length) {
-      this.$container.insertBefore($prev);
-      this.updatePositionInConfig();
-    }
-  },
-
-  moveRight() {
-    let $next = this.$container.next('.fld-tab');
-    if ($next.length) {
-      this.$container.insertAfter($next);
-      this.updatePositionInConfig();
-    }
-  },
-
-  initElement: function ($element) {
-    return new Craft.FieldLayoutDesigner.Element(this, $element);
-  },
-
-  get index() {
-    return this.designer.config.tabs.findIndex((c) => c.uid === this.uid);
-  },
-
-  get config() {
-    if (!this.uid) {
-      throw 'Tab is missing its UID';
-    }
-    let config = this.designer.config.tabs.find((c) => c.uid === this.uid);
-    if (!config) {
-      config = {
-        uid: this.uid,
-        elements: [],
-      };
-      this.config = config;
-    }
-    return config;
-  },
-
-  set config(config) {
-    if (this.destroyed) {
-      return;
-    }
-
-    // Is the name changing?
-    if (config.name && config.name !== this.config.name) {
-      this.$container.find('.tabs .tab .fld-tab__name').text(config.name);
-    }
-
-    const designerConfig = this.designer.config;
-    const index = this.index;
-    if (index !== -1) {
-      designerConfig.tabs[index] = config;
-    } else {
-      const newIndex = $.inArray(
-        this.$container[0],
-        this.$container.parent().children('.fld-tab')
-      );
-      designerConfig.tabs.splice(newIndex, 0, config);
-    }
-    this.designer.config = designerConfig;
-  },
-
-  updateConfig: function (callback) {
-    if (this.destroyed) {
-      return;
-    }
-
-    const config = callback(this.config);
-    if (config !== false) {
-      this.config = config;
-    }
-  },
-
-  updatePositionInConfig: function () {
-    if (this.destroyed) {
-      return;
-    }
-
-    this.designer.updateConfig((config) => {
-      const tabConfig = this.config;
-      const oldIndex = this.index;
-      const newIndex = $.inArray(
-        this.$container[0],
-        this.$container.parent().children('.fld-tab')
-      );
-      if (oldIndex !== -1) {
-        config.tabs.splice(oldIndex, 1);
-      }
-      config.tabs.splice(newIndex, 0, tabConfig);
-      return config;
-    });
-  },
-
-  destroy: function () {
-    if (this.destroyed) {
-      return;
-    }
-
-    this.destroyed = true;
-
-    this.designer.updateConfig((config) => {
-      const index = this.index;
-      if (index === -1) {
-        return false;
-      }
-      config.tabs.splice(index, 1);
-      return config;
-    });
-
-    // First destroy the tab's elements
-    let $elements = this.$container.find('.fld-element');
-    for (let i = 0; i < $elements.length; i++) {
-      $elements.eq(i).data('fld-element').destroy();
-    }
-
-    // Set focus to the closest tab's first focusable element
-    const $focusElement = this.$container.siblings().find(':focusable:first');
-    if ($focusElement.length) {
-      $focusElement.focus();
-    } else {
-      this.designer.$newTabBtn.focus();
-    }
-
-    this.designer.tabGrid.removeItems(this.$container);
-    this.designer.tabDrag.removeItems(this.$container);
-    this.$container.remove();
-    this.designer.refreshSelectedFields();
-
-    this.base();
-  },
-});
-
-Craft.FieldLayoutDesigner.Element = Garnish.Base.extend({
-  tab: null,
-  $container: null,
-  $actionBtn: null,
-
-  uid: null,
-  isMandatory: false,
-  isMultiInstance: null,
-  isField: false,
-  attribute: null,
-  requirable: false,
-  thumbable: false,
-  hasCustomWidth: false,
-  hasSettings: false,
-  settingsNamespace: null,
-  slideout: null,
-  defaultHandle: null,
-  fieldId: null,
-  fieldsWithErrors: null,
-
-  init: function (tab, $container) {
-    this.tab = tab;
-    this.$container = $container;
-    this.uid = $container.data('uid');
-    this.fieldId = $container.data('id');
-
-    this.fieldsWithErrors = [];
-
-    // New element?
-    const isNew = !this.uid;
-    if (isNew) {
-      this.uid = Craft.uuid();
-      this.config = $.extend($container.data('config'), {uid: this.uid});
-    }
-
-    this.initUi();
-
-    if (isNew && this.isField) {
-      // Find a unique handle
-      let handle = this.defaultHandle;
-      let i = 1;
-      while (this.tab.designer.hasHandle(handle)) {
-        i++;
-        handle = this.defaultHandle + i;
-      }
-      if (handle !== this.defaultHandle) {
-        this.config = $.extend({}, this.config, {handle: handle});
-        $container.find('.fld-attribute-label').text(handle);
-      }
-      this.tab.designer.refreshSelectedFields();
-    }
-
-    // cleanup
-    $container.attr('data-keywords', null);
-  },
-
-  initUi: function () {
-    this.$container.data('fld-element', this);
-
-    this.isMandatory = Garnish.hasAttr(this.$container, 'data-mandatory');
-    this.isField = this.$container.hasClass('fld-field');
-    this.isMultiInstance = Garnish.hasAttr(
-      this.$container,
-      'data-is-multi-instance'
-    );
-
-    if (this.isField) {
-      this.requirable = Garnish.hasAttr(this.$container, 'data-requirable');
-      this.thumbable = Garnish.hasAttr(this.$container, 'data-thumbable');
-      this.attribute = this.$container.data('attribute');
-      this.defaultHandle = this.$container.data('default-handle');
-    }
-
-    this.hasCustomWidth =
-      this.tab.designer.settings.customizableUi &&
-      Garnish.hasAttr(this.$container, 'data-has-custom-width');
-
-    if (this.hasCustomWidth) {
-      let widthSlider = new Craft.SlidePicker(this.config.width || 100, {
-        min: 25,
-        max: 100,
-        step: 25,
-        valueLabel: (width) => {
-          return Craft.t('app', '{pct} width', {pct: `${width}%`});
-        },
-        onChange: (width) => {
-          this.updateConfig((config) => {
-            config.width = width;
-            return config;
-          });
-        },
-        readOnly: this.tab.designer.settings.readOnly,
-      });
-      widthSlider.$container.appendTo(this.$container);
-    }
-
-    // create the action menu
-    const menuId = `actionmenu${Math.floor(Math.random() * 1000000)}`;
-    this.$actionBtn = $('<button/>', {
-      type: 'button',
-      class: 'btn action-btn',
-      'data-disclosure-trigger': 'true',
-      'aria-controls': menuId,
-      'aria-haspopup': 'true',
-      'aria-label': Craft.t('app', 'Actions'),
-      title: Craft.t('app', 'Actions'),
-      disabled: this.tab.designer.settings.readOnly,
-    }).appendTo(this.$container);
-    $('<div/>', {
-      id: menuId,
-      class: 'menu menu--disclosure',
-      'data-disclosure-menu': 'true',
-    }).appendTo(this.$container);
-    const disclosureMenu = this.$actionBtn
-      .disclosureMenu()
-      .data('disclosureMenu');
-
-    let makeRequiredBtn, dropRequiredBtn;
-
-    this.hasSettings = Garnish.hasAttr(this.$container, 'data-has-settings');
-
-    if (this.hasSettings && !this.tab.designer.settings.readOnly) {
-      disclosureMenu.addItem({
-        label: Craft.t('app', 'Settings'),
-        icon: async () => await Craft.ui.icon('gear'),
-        onActivate: () => {
-          this.createSettings();
-        },
-      });
-
-      this.addListener(this.$container, 'dblclick', () => {
-        this.createSettings();
-      });
-    }
-
-    if (
-      this.requirable ||
-      (!this.tab.designer.settings.withCardViewDesigner && this.thumbable)
-    ) {
-      const actionUl = disclosureMenu.addGroup();
-
-      if (this.requirable) {
-        makeRequiredBtn = disclosureMenu.addItem(
-          {
-            label: Craft.t('app', 'Make required'),
-            icon: async () => await Craft.ui.icon('asterisk'),
-            iconColor: 'rose',
-            onActivate: () => {
-              this.makeRequired();
-            },
-          },
-          actionUl
-        );
-
-        dropRequiredBtn = disclosureMenu.addItem(
-          {
-            label: Craft.t('app', 'Make optional'),
-            icon: async () => await Craft.ui.icon('asterisk-slash'),
-            iconColor: 'gray',
-            onActivate: () => {
-              this.dropRequired();
-            },
-          },
-          actionUl
-        );
-      }
-    }
-
-    const moveGroup = disclosureMenu.addGroup();
-    const moveUpBtn = disclosureMenu.addItem(
-      {
-        label: Craft.t('app', 'Move up'),
-        icon: async () => await Craft.ui.icon('arrow-up'),
-        onActivate: () => {
-          this.moveUp();
-        },
-      },
-      moveGroup
-    );
-    const moveDownBtn = disclosureMenu.addItem(
-      {
-        label: Craft.t('app', 'Move down'),
-        icon: async () => await Craft.ui.icon('arrow-down'),
-        onActivate: () => {
-          this.moveDown();
-        },
-      },
-      moveGroup
-    );
-
-    if (!this.isMandatory) {
-      disclosureMenu.addItem(
-        {
-          label: Craft.t('app', 'Remove'),
-          icon: async () => await Craft.ui.icon('xmark'),
-          destructive: true,
-          onActivate: () => {
-            this.destroy();
-          },
-        },
-        disclosureMenu.addGroup()
-      );
-    }
-
-    disclosureMenu.on('show', () => {
-      if (this.requirable) {
-        disclosureMenu.toggleItem(makeRequiredBtn, !this.config.required);
-        disclosureMenu.toggleItem(dropRequiredBtn, this.config.required);
-      }
-
-      disclosureMenu.toggleItem(
-        moveUpBtn,
-        this.$container.prev('.fld-element').length
-      );
-      disclosureMenu.toggleItem(
-        moveDownBtn,
-        this.$container.next('.fld-element').length
-      );
-    });
-  },
-
-  onSelect() {
-    this.$container.attr('data-uid', this.uid);
-
-    const previewOptions = this.$container.data('preview-options');
-    if (previewOptions) {
-      const cvd = this.tab.designer.cvd;
-      if (cvd) {
-        previewOptions.forEach((option) => {
-          cvd.addCheckbox({
-            value: option.value.replace(/\{uid}/g, this.uid),
-            label: option.label,
-          });
-        });
-        cvd.updateThumbnailsDropdown(this, 'add');
-      }
-    }
-  },
-
-  getLabel() {
-    const label = this.$container.find('.fld-element-label').text();
-    return label !== '' ? label : this.$container.data('attribute');
-  },
-
-  async createSettings() {
-    let data;
-    try {
-      const response = await Craft.sendActionRequest(
-        'POST',
-        'fields/render-layout-component-settings',
-        {
-          data: {
-            uid: this.uid,
-            layoutConfig: this.tab.designer.config,
-            elementType: this.tab.designer.settings.elementType,
-          },
-        }
-      );
-      data = response.data;
-    } catch (e) {
-      Craft.cp.displayError(e?.response?.data?.message);
-      throw e;
-    }
-
-    this.settingsNamespace = data.namespace;
-    this.slideout = await Craft.FieldLayoutDesigner.createSlideout(data, null, {
-      triggerElement: this.$actionBtn,
-    });
-
-    this.slideout.$container.on('submit', (ev) => {
-      ev.preventDefault();
-      this.applySettings();
-    });
-    this.slideout.on('close', () => {
-      this.slideout.destroy();
-      this.slideout = null;
-    });
-
-    const $fieldsContainer = this.slideout.$container.find('.fields:first');
-
-    if (this.isField) {
-      const $handleInput = $fieldsContainer.find('input[name$="[handle]"]');
-      $handleInput.val(this.config.handle || '');
-    }
-
-    this.trigger('createSettings');
-  },
-
-  async applySettings() {
-    // update the UI
-    let $submitBtn = this.slideout.$container
-      .find('button[type=submit]')
-      .addClass('loading');
-
-    try {
-      await this.applyConfig(() => this.config, true);
-    } finally {
-      $submitBtn.removeClass('loading');
-    }
-  },
-
-  async showFieldEditor() {
-    const slideout = new Craft.CpScreenSlideout('fields/edit-field', {
-      params: {
-        fieldId: this.fieldId,
-        multiInstanceTypesOnly: this.isMultiInstance ? 1 : 0,
-      },
-    });
-
-    slideout.on('submit', async ({response}) => {
-      const designer = this.tab.designer;
-
-      // refresh the library selector
-      const $oldSelector = designer.$fieldLibrary.find(
-        `.fld-field[data-id=${this.fieldId}]`
-      );
-      const $newSelector = $(response.data.selectorHtml);
-      $oldSelector.replaceWith($newSelector);
-      designer.refreshLibraryFields();
-      designer.elementDrag.removeItems($oldSelector);
-      designer.elementDrag.addItems($newSelector);
-
-      // refresh all instances of this field
-      const $fields = designer.$tabContainer.find(
-        `.fld-field[data-id=${this.fieldId}]`
-      );
-      for (let i = 0; i < $fields.length; i++) {
-        $fields.eq(i).data('fld-element')?.refresh();
-      }
-    });
-  },
-
-  async makeRequired() {
-    await this.applyConfig((config) => {
-      config.required = true;
-      return config;
-    });
-  },
-
-  async dropRequired() {
-    await this.applyConfig((config) => {
-      config.required = false;
-      return config;
-    });
-  },
-
-  moveUp() {
-    const $prev = this.$container.prev('.fld-element');
-    if ($prev.length) {
-      this.$container.insertBefore($prev);
-      this.updatePositionInConfig();
-    }
-  },
-
-  moveDown() {
-    const $next = this.$container.next('.fld-element');
-    if ($next.length) {
-      this.$container.insertAfter($next);
-      this.updatePositionInConfig();
-    }
-  },
-
-  async applyConfig(callback, withSettings = false) {
-    const config = callback(this.config);
-    if (config === false) {
-      return;
-    }
-
-    this.fieldsWithErrors.forEach(($field) => {
-      Craft.ui.clearErrorsFromField($field);
-    });
-
-    let data;
-
-    try {
-      const response = await Craft.sendActionRequest(
-        'POST',
-        'fields/apply-layout-element-settings',
-        {
-          data: {
-            uid: this.uid,
-            layoutConfig: this.tab.designer.config,
-            elementType: this.tab.designer.settings.elementType,
-            config,
-            settingsNamespace: this.settingsNamespace,
-            settings: withSettings
-              ? this.slideout.$container.serialize()
-              : null,
-          },
-        }
-      );
-      data = response.data;
-    } catch (e) {
-      if (withSettings) {
-        let errors = e?.response?.data?.errors;
-        if (errors) {
-          Object.entries(errors).forEach(([name, fieldErrors]) => {
-            const $field = this.slideout.$container.find(
-              `[data-error-key="${name}"]`
-            );
-            if ($field.length) {
-              Craft.ui.addErrorsToField($field, fieldErrors);
-              this.fieldsWithErrors.push($field);
-            }
-          });
-        }
-      }
-
-      Craft.cp.displayError(e?.response?.data?.message);
-      throw e;
-    }
-
-    this.config = data.config;
-    const $oldContainer = this.$container;
-    const $newContainer = $(data.selectorHtml);
-    this.$container.replaceWith($newContainer);
-    this.$container = $newContainer;
-    this.initUi();
-
-    if (this.tab.designer.settings.withCardViewDesigner) {
-      const cvd = this.tab.designer.cvd;
-      if (cvd) {
-        const previewOptions = $newContainer.data('preview-options');
-        if (previewOptions) {
-          // update labels in cvd checkboxes
-          previewOptions.forEach((option) => {
-            cvd.updateCheckboxLabel(
-              option.value.replace(/\{uid}/g, this.uid),
-              option.label
-            );
-          });
-        }
-
-        // update label in the element thumbnails dropdown
-        cvd.updateThumbnailsDropdownOptionLabel(this.$container);
-      }
-    }
-
-    const designer = this.tab.designer;
-    designer.refreshSelectedFields();
-    designer.elementDrag.removeItems($oldContainer);
-    designer.elementDrag.addItems($newContainer);
-
-    if (this.slideout) {
-      this.slideout.close();
-      this.slideout.destroy();
-      this.slideout = null;
-    }
-
-    if (this.config.providesThumbs) {
-      // make sure this is the only one
-      const $fields = this.tab.designer.$tabContainer.find('.fld-field');
-      for (let i = 0; i < $fields.length; i++) {
-        const $field = $fields.eq(i);
-        const element = $field.data('fld-element');
-        if (element && element !== this && element.config.providesThumbs) {
-          element.applyConfig((config) => {
-            config.providesThumbs = false;
-            return config;
-          });
-        }
-      }
-    }
-  },
-
-  async refresh() {
-    await this.applyConfig((config) => config);
-  },
-
-  get index() {
-    const tabConfig = this.tab.config;
-    if (typeof tabConfig === 'undefined') {
-      return -1;
-    }
-    return tabConfig.elements.findIndex((c) => c.uid === this.uid);
-  },
-
-  get config() {
-    if (!this.uid) {
-      throw 'Tab is missing its UID';
-    }
-    let config = this.tab.config.elements.find((c) => c.uid === this.uid);
-    if (!config) {
-      config = {
-        uid: this.uid,
-      };
-      this.config = config;
-    }
-    return config;
-  },
-
-  set config(config) {
-    const tabConfig = this.tab.config;
-    const index = this.index;
-    if (index !== -1) {
-      tabConfig.elements[index] = config;
-    } else {
-      const newIndex = $.inArray(
-        this.$container[0],
-        this.$container.parent().children('.fld-element')
-      );
-      tabConfig.elements.splice(newIndex, 0, config);
-    }
-    this.tab.config = tabConfig;
-  },
-
-  updateConfig: function (callback) {
-    const config = callback(this.config);
-    if (config !== false) {
-      this.config = config;
-    }
-  },
-
-  updatePositionInConfig: function () {
-    this.tab.updateConfig((config) => {
-      const elementConfig = this.config;
-      const oldIndex = this.index;
-      const newIndex = $.inArray(
-        this.$container[0],
-        this.$container.parent().children('.fld-element')
-      );
-      if (oldIndex !== -1) {
-        config.elements.splice(oldIndex, 1);
-      }
-      config.elements.splice(newIndex, 0, elementConfig);
-      return config;
-    });
-  },
-
-  destroy: function () {
-    if (this.tab.designer.settings.withCardViewDesigner) {
-      const cvd = this.tab.designer.cvd;
-      if (cvd) {
-        // this needs to be called before removeCheckbox()
-        cvd.updateThumbnailsDropdown(this, 'remove');
-
-        const previewOptions = this.$container.data('preview-options');
-        if (previewOptions?.length) {
-          previewOptions.forEach((option) => {
-            cvd.removeCheckbox(option.value.replace(/\{uid}/g, this.uid));
-          });
-        }
-      }
-    }
-
-    this.tab.updateConfig((config) => {
-      const index = this.index;
-      if (index === -1) {
-        return false;
-      }
-      config.elements.splice(index, 1);
-      return config;
-    });
-
-    // Set focus to the closest element's first focusable element
-    const $focusElement = this.$container.siblings().find(':focusable:first');
-    if ($focusElement.length) {
-      $focusElement.focus();
-    } else {
-      this.tab.$addBtn.focus();
-    }
-
-    this.tab.designer.elementDrag.removeItems(this.$container);
-    this.$container.remove();
-
-    if (this.isField) {
-      this.tab.designer.refreshSelectedFields();
-
-      if (!this.isMultiInstance) {
-        this.tab.designer.removeFieldByHandle(
-          this.defaultHandle || this.attribute
-        );
-      }
-    } else {
-      // if it's not a field (so a ui element) and it's not multi instance, make it visible for selection again
-      if (!this.isMultiInstance) {
-        let uiLibraryElement = this.tab.designer.$uiLibraryElements.filter(
-          `[data-type="${this.$container.data('type')}"]:first`
-        );
-        if (uiLibraryElement.length) {
-          $(uiLibraryElement[0]).removeClass('hidden');
-        }
-      }
-    }
-
-    this.base();
-  },
-});
-
-Craft.FieldLayoutDesigner.BaseDrag = Garnish.Drag.extend({
-  designer: null,
-  $insertion: null,
-  showingInsertion: false,
-  $caboose: null,
-
-  /**
-   * Constructor
-   */
-  init: function (designer, settings) {
-    this.designer = designer;
-    this.base(this.findItems(), settings);
-  },
-
-  /**
-   * On Drag Start
-   */
-  onDragStart: function () {
-    this.base();
-
-    // Create the insertion
-    this.$insertion = this.createInsertion();
-
-    // Add the caboose
-    this.$caboose = this.createCaboose();
-    this.$items = $().add(this.$items.add(this.$caboose));
-
-    Garnish.$bod.addClass('dragging');
-  },
-
-  removeCaboose: function () {
-    this.$items = this.$items.not(this.$caboose);
-    this.$caboose.remove();
-  },
-
-  swapDraggeeWithInsertion: function () {
-    this.$insertion.insertBefore(this.$draggee);
-    this.$draggee.detach();
-    this.$items = $().add(this.$items.not(this.$draggee).add(this.$insertion));
-    this.showingInsertion = true;
-  },
-
-  swapInsertionWithDraggee: function () {
-    this.$insertion.replaceWith(this.$draggee);
-    this.$items = $().add(this.$items.not(this.$insertion).add(this.$draggee));
-    this.showingInsertion = false;
-  },
-
-  /**
-   * Sets the item midpoints up front so we don't have to keep checking on every mouse move
-   */
-  setMidpoints: function () {
-    for (let i = 0; i < this.$items.length; i++) {
-      let $item = $(this.$items[i]);
-      let offset = $item.offset();
-
-      // Skip library elements
-      if ($item.hasClass('unused')) {
-        continue;
-      }
-
-      $item.data('midpoint', {
-        left: offset.left + $item.outerWidth() / 2,
-        top: offset.top + $item.outerHeight() / 2,
-      });
-    }
-  },
-
-  /**
-   * Returns the closest item to the cursor.
-   */
-  getClosestItem: function () {
-    this.getClosestItem._closestItem = null;
-    this.getClosestItem._closestItemMouseDiff = null;
-
-    for (
-      this.getClosestItem._i = 0;
-      this.getClosestItem._i < this.$items.length;
-      this.getClosestItem._i++
-    ) {
-      this.getClosestItem._$item = $(this.$items[this.getClosestItem._i]);
-
-      this.getClosestItem._midpoint =
-        this.getClosestItem._$item.data('midpoint');
-      if (!this.getClosestItem._midpoint) {
-        continue;
-      }
-
-      this.getClosestItem._mouseDiff = Garnish.getDist(
-        this.getClosestItem._midpoint.left,
-        this.getClosestItem._midpoint.top,
-        this.mouseX,
-        this.mouseY
-      );
-
-      if (
-        this.getClosestItem._closestItem === null ||
-        this.getClosestItem._mouseDiff <
-          this.getClosestItem._closestItemMouseDiff
-      ) {
-        this.getClosestItem._closestItem = this.getClosestItem._$item[0];
-        this.getClosestItem._closestItemMouseDiff =
-          this.getClosestItem._mouseDiff;
-      }
-    }
-
-    return this.getClosestItem._closestItem;
-  },
-
-  checkForNewClosestItem: function () {
-    // Is there a new closest item?
-    this.checkForNewClosestItem._closestItem = this.getClosestItem();
-
-    if (this.checkForNewClosestItem._closestItem === this.$insertion[0]) {
-      return;
-    }
-
-    if (
-      this.showingInsertion &&
-      $.inArray(this.$insertion[0], this.$items) <
-        $.inArray(this.checkForNewClosestItem._closestItem, this.$items) &&
-      $.inArray(this.checkForNewClosestItem._closestItem, this.$caboose) === -1
-    ) {
-      this.$insertion.insertAfter(this.checkForNewClosestItem._closestItem);
-    } else {
-      this.$insertion.insertBefore(this.checkForNewClosestItem._closestItem);
-    }
-
-    // we only want to do it all if there's at least one tab in the layout
-    if (this.designer.tabGrid.$items.length > 0) {
-      this.$items = $().add(this.$items.add(this.$insertion));
-      this.showingInsertion = true;
-      this.setMidpoints();
-    }
-  },
-
-  /**
-   * On Drag Stop
-   */
-  onDragStop: function () {
-    if (this.showingInsertion) {
-      this.swapInsertionWithDraggee();
-    }
-
-    this.removeCaboose();
-
-    // return the helpers to the draggees
-    let offset = this.$draggee.offset();
-    if (!offset || (offset.top === 0 && offset.left === 0)) {
-      this.$draggee
-        .css({
-          display: this.draggeeDisplay,
-          visibility: 'visible',
-          opacity: 0,
-        })
-        .velocity({opacity: 1}, Garnish.FX_DURATION);
-      this.helpers[0].velocity({opacity: 0}, Garnish.FX_DURATION, () => {
-        this._showDraggee();
-      });
-    } else {
-      this.returnHelpersToDraggees();
-    }
-
-    this.base();
-
-    Garnish.$bod.removeClass('dragging');
-  },
-});
-
-Craft.FieldLayoutDesigner.TabDrag = Craft.FieldLayoutDesigner.BaseDrag.extend({
-  /**
-   * Constructor
-   */
-  init: function (designer) {
-    let settings = {
-      handle: '.tab',
-    };
-
-    this.base(designer, settings);
-  },
-
-  findItems: function () {
-    return this.designer.$tabContainer.find('> div.fld-tab');
-  },
-
-  /**
-   * On Drag Start
-   */
-  onDragStart: function () {
-    this.base();
-    this.swapDraggeeWithInsertion();
-    this.setMidpoints();
-  },
-
-  swapDraggeeWithInsertion: function () {
-    this.base();
-    this.designer.tabGrid.removeItems(this.$draggee);
-    this.designer.tabGrid.addItems(this.$insertion);
-  },
-
-  swapInsertionWithDraggee: function () {
-    this.base();
-    this.designer.tabGrid.removeItems(this.$insertion);
-    this.designer.tabGrid.addItems(this.$draggee);
-  },
-
-  /**
-   * On Drag
-   */
-  onDrag: function () {
-    this.checkForNewClosestItem();
-    this.base();
-  },
-
-  /**
-   * On Drag Stop
-   */
-  onDragStop: function () {
-    this.base();
-
-    // "show" the tab, but make it invisible
-    this.$draggee.css({
-      display: this.draggeeDisplay,
-      visibility: 'hidden',
-    });
-
-    this.$draggee.data('fld-tab').updatePositionInConfig();
-  },
-
-  /**
-   * Creates the caboose
-   */
-  createCaboose: function () {
-    let $caboose = $('<div class="fld-tab fld-tab-caboose"/>').appendTo(
-      this.designer.$tabContainer
-    );
-    this.designer.tabGrid.addItems($caboose);
-    return $caboose;
-  },
-
-  /**
-   * Removes the caboose
-   */
-  removeCaboose: function () {
-    this.base();
-    this.designer.tabGrid.removeItems(this.$caboose);
-  },
-
-  /**
-   * Creates the insertion
-   */
-  createInsertion: function () {
-    let $tab = this.$draggee.find('.tab');
-
-    return $(`
-<div class="fld-tab fld-insertion" style="height: ${this.$draggee.height()}px;">
-  <div class="tabs"><div class="tab sel draggable" style="width: ${$tab.outerWidth()}px; height: ${
-    $tab.outerHeight() + 2
-  }px;"></div></div>
-  <div class="fld-tabcontent" style="height: ${
-    this.$draggee.find('.fld-tabcontent').height() - 2
-  }px;"></div>
-</div>
-`);
-  },
-});
-
-Craft.FieldLayoutDesigner.ElementDrag =
-  Craft.FieldLayoutDesigner.BaseDrag.extend({
-    draggingLibraryElement: false,
-    draggingField: false,
-    draggingMultiInstanceElement: false,
-    originalTab: null,
-
-    /**
-     * On Drag Start
-     */
-    onDragStart: function () {
-      this.base();
-
-      // Are we dragging an element from the library?
-      this.draggingLibraryElement = this.$draggee.hasClass('unused');
-
-      // Is it a field?
-      this.draggingField = this.$draggee.hasClass('fld-field');
-
-      // Can the element have multiple instances?
-      this.draggingMultiInstanceElement = Garnish.hasAttr(
-        this.$draggee,
-        'data-is-multi-instance'
-      );
-
-      // keep UI elements visible
-      if (this.draggingLibraryElement && this.draggingMultiInstanceElement) {
-        this.$draggee.css({
-          display: this.draggeeDisplay,
-          visibility: 'visible',
-        });
-      }
-
-      // Swap the draggee with the insertion if dragging a selected item
-      if (!this.draggingLibraryElement) {
-        this.originalTab = this.$draggee.closest('.fld-tab').data('fld-tab');
-        this.swapDraggeeWithInsertion();
-      } else {
-        this.originalTab = null;
-      }
-
-      this.setMidpoints();
-    },
-
-    /**
-     * On Drag
-     */
-    onDrag: function () {
-      if (this.isDraggeeMandatory() || this.isHoveringOverTab()) {
-        this.checkForNewClosestItem();
-      } else if (this.showingInsertion) {
-        this.$insertion.remove();
-        this.$items = $().add(this.$items.not(this.$insertion));
-        this.showingInsertion = false;
-        this.setMidpoints();
-      }
-
-      this.base();
-    },
-
-    isDraggeeMandatory: function () {
-      return Garnish.hasAttr(this.$draggee, 'data-mandatory');
-    },
-
-    isHoveringOverTab: function () {
-      for (let i = 0; i < this.designer.tabGrid.$items.length; i++) {
-        if (
-          Garnish.hitTest(
-            this.mouseX,
-            this.mouseY,
-            this.designer.tabGrid.$items.eq(i)
-          )
-        ) {
-          return true;
-        }
-      }
-
-      return false;
-    },
-
-    findItems: function () {
-      // Return all of the in-use layout elements. (We'll add the library elements via initLibraryElement().)
-      return this.designer.$tabContainer.find('.fld-element');
-    },
-
-    /**
-     * Creates the caboose
-     */
-    createCaboose: function () {
-      let $caboose = $();
-      let $fieldContainers = this.designer.$tabContainer.find(
-        '> .fld-tab > .fld-tabcontent'
-      );
-
-      for (let i = 0; i < $fieldContainers.length; i++) {
-        $caboose = $caboose.add(
-          $('<div/>').insertBefore(
-            $fieldContainers.eq(i).children('.fld-add-btn')
-          )
-        );
-      }
-
-      return $caboose;
-    },
-
-    /**
-     * Creates the insertion
-     */
-    createInsertion: function () {
-      return $(
-        `<div class="fld-element fld-insertion" style="height: ${this.$draggee.outerHeight()}px;"/>`
-      );
-    },
-
-    /**
-     * On Drag Stop
-     */
-    onDragStop: function () {
-      let showingInsertion = this.showingInsertion;
-      if (showingInsertion) {
-        if (this.draggingLibraryElement) {
-          // Clone the element nad set this.$draggee to the clone, as if we were dragging that all along
-          this.$draggee = this.designer.cloneLibraryElementForSelection(
-            this.$draggee
-          );
-        }
-      } else if (!this.draggingLibraryElement) {
-        let $libraryElement = this.draggingField
-          ? this.designer.$fields.filter(
-              `[data-attribute="${this.$draggee.data('attribute')}"]:first`
-            )
-          : this.designer.$uiLibraryElements.filter(
-              `[data-type="${this.$draggee.data('type')}"]:first`
-            );
-
-        if (this.draggingField) {
-          // show the field in the library
-          $libraryElement.removeClass('hidden');
-          $libraryElement.closest('.fld-field-group').removeClass('hidden');
-        }
-
-        // Destroy the original element
-        this.$draggee.data('fld-element').destroy();
-
-        // Set this.$draggee to the library element, as if we were dragging that all along
-        this.$draggee = $libraryElement;
-      }
-
-      this.base();
-
-      this.$draggee.css({
-        display: this.draggeeDisplay,
-        visibility:
-          this.draggingField || showingInsertion ? 'hidden' : 'visible',
-      });
-
-      if (showingInsertion) {
-        const tab = this.$draggee.closest('.fld-tab').data('fld-tab');
-        let element;
-
-        if (this.draggingLibraryElement) {
-          element = tab.initElement(this.$draggee);
-          element.onSelect();
-        } else {
-          element = this.$draggee.data('fld-element');
-
-          // New tab?
-          if (tab !== this.originalTab) {
-            const config = element.config;
-
-            this.originalTab.updateConfig((config) => {
-              const index = element.index;
-              if (index === -1) {
-                return false;
-              }
-              config.elements.splice(index, 1);
-              return config;
-            });
-
-            this.$draggee.data('fld-element').tab = tab;
-            element.config = config;
-          }
-        }
-
-        element.updatePositionInConfig();
-      }
-    },
-  });
-
-Craft.FieldLayoutDesigner.CardViewDesigner = Garnish.Base.extend({
-  designer: null,
-  $container: null,
-  $previewContainer: null,
-  $libraryContainer: null,
-  sortableCheckboxSelect: null,
-  $thumbManagementContainer: null,
-  alwaysShowThumbAlignmentBtns: false,
-  cancelToken: null,
-
-  init: function (designer, container) {
-    this.designer = designer;
-    this.$container = $(container);
-    this.$container.data('cvd', this);
-
-    this.$previewContainer = this.$container.find('.cvd-preview');
-    this.$libraryContainer = this.$container.find(
-      '.cvd-library .checkbox-select'
-    );
-
-    this.sortableCheckboxSelect = this.$libraryContainer.data(
-      'sortableCheckboxSelect'
-    );
-
-    // If the checkboxes haven't been initialized yet, do that.
-    if (!this.sortableCheckboxSelect) {
-      console.trace('Not initialized');
-      this.sortableCheckboxSelect = new Craft.SortableCheckboxSelect(
-        this.$libraryContainer
-      );
-    }
-
-    this.$thumbManagementContainer = this.$container.find('.thumb-management');
-    this.alwaysShowThumbAlignmentBtns =
-      designer.settings.alwaysShowThumbAlignmentBtns;
-
-    let $thumbSelectDropdown = this.$thumbManagementContainer.find(
-      'select[id$="thumb-source"]'
-    );
-    this.addListener($thumbSelectDropdown, 'change', (ev) => {
-      this.manageThumbnails(ev.target);
-    });
-
-    if (this.alwaysShowThumbAlignmentBtns) {
-      // always show the thumbnail alignment buttons
-      this.showThumbAlignment();
-    }
-
-    let $thumbAlignmentBtns = this.$thumbManagementContainer.find(
-      'div.btngroup[id$="thumb-alignment"] .btn'
-    );
-    this.addListener($thumbAlignmentBtns, 'activate', (ev) => {
-      this.manageThumbnailAlignment(ev.target);
-    });
-
-    this.listenToCheckboxEvents();
-    this.disablePreviewLinks();
-  },
-
-  initDrag: function ($draggable) {
-    this.sortableCheckboxSelect.initDrag();
-    this.sortableCheckboxSelect.initItem($draggable);
-
-    // trigger preview update when items are dragged into new position
-    this.sortableCheckboxSelect.dragSort?.on('dragStop', () => {
-      this.updatePreview();
-    });
-
-    this.listenToCheckboxEvents();
-  },
-
-  listenToCheckboxEvents: function () {
-    // trigger preview update when items are checked/unchecked
-    this.$libraryContainer.on('change', (ev) => {
-      if ($(ev.target).is('input[type=checkbox]')) {
-        this.updateCardViewConfig();
-        this.updatePreview();
-      }
-    });
-    this.sortableCheckboxSelect.on('sortChange', () => {
-      this.updateCardViewConfig();
-      this.updatePreview();
-    });
-  },
-
-  updateCardViewConfig: function () {
-    this.designer.updateConfig((config) => {
-      // can't rely on :checked
-      config.cardView = this.$libraryContainer
-        .find('input[type=checkbox]')
-        .toArray()
-        .filter((el) => el.checked)
-        .map((e) => e.value);
-      return config;
-    });
-  },
-
-  updatePreview: async function () {
-    this.$previewContainer.addClass('loading');
-    Craft.cp.announce(Craft.t('app', 'Loading'));
-
-    if (this.cancelToken) {
-      this.cancelToken.cancel();
-    }
-
-    this.cancelToken = axios.CancelToken.source();
-
-    let response;
-    try {
-      response = await Craft.sendActionRequest(
-        'POST',
-        'fields/render-card-preview',
-        {
-          cancelToken: this.cancelToken.token,
-          data: {
-            fieldLayoutConfig: this.designer.config,
-          },
-        }
-      );
-    } catch (e) {
-      if (!axios.isCancel(e)) {
-        Craft.cp.displayError(e?.response?.data?.message);
-        throw e;
-      } else {
-        console.log('cancelled');
-      }
-    } finally {
-      this.$previewContainer.removeClass('loading');
-      Craft.cp.announce(Craft.t('app', 'Loading complete'));
-      this.cancelToken = null;
-    }
-
-    if (response) {
-      this.$previewContainer.html(response.data.previewHtml);
-      this.disablePreviewLinks();
-    }
-  },
-
-  disablePreviewLinks: function () {
-    // add aria-disabled to the preview links
-    this.$previewContainer.find('a').each((key, anchor) => {
-      $(anchor).attr('aria-disabled', true);
-    });
-
-    // prevent the preview links from being clickable
-    this.$previewContainer.find('a').on('click', (ev) => {
-      ev.preventDefault();
-    });
-  },
-
-  addCheckbox: function (config = {}) {
-    if (!this.$libraryContainer.length) {
-      return;
-    }
-
-    const $draggable = $('<div class="checkbox-select-item"/>');
-    if (Craft.hasMousePointerEvents()) {
-      $('<a class="move icon draggable-handle disabled"/>').appendTo(
-        $draggable
-      );
-    }
-    Craft.ui
-      .createCheckbox(
-        Object.assign(
-          {
-            checked: false,
-          },
-          config
-        )
-      )
-      .appendTo($draggable);
-
-    $draggable.appendTo(this.$libraryContainer);
-
-    // re-init dragging
-    this.initDrag($draggable);
-  },
-
-  updateCheckboxLabel: function (value, label) {
-    const $draggable = this.findCheckboxByValue(value);
-    if ($draggable?.length) {
-      $draggable.find('label').text(label);
-    }
-  },
-
-  removeCheckbox: function (value) {
-    const $draggable = this.findCheckboxByValue(value);
-
-    if ($draggable?.length) {
-      const updateConfig = $draggable
-        .find('input[type="checkbox"]')
-        .prop('checked');
-      $draggable.remove();
-
-      // and now make a call to update the card preview
-      if (updateConfig) {
-        this.updateCardViewConfig();
-        this.updatePreview();
-      }
-    }
-  },
-
-  findCheckboxByValue: function (value) {
-    if (!this.$libraryContainer.length) {
-      return null;
-    }
-
-    return this.$libraryContainer
-      .find(`input[value="${value}"]`)
-      .parents('.checkbox-select-item');
-  },
-
-  /** THUMBNAILS **/
-  manageThumbnailAlignment: function (target) {
-    let $btn = $(target);
-    let alignment = $btn.data('value');
-
-    if (alignment !== this.designer.config.thumbAlignment) {
-      this.designer.updateConfig((config) => {
-        config.cardThumbAlignment = alignment;
-        return config;
-      });
-      this.updatePreview();
-    }
-  },
-
-  manageThumbnails: function (target) {
-    const $select = $(target);
-    let thumbFieldKey = null;
-
-    if ($select.val() === '__none__' || $select.val() === '__default__') {
-      if (
-        $select.val() === '__none__' &&
-        !this.designer.settings.alwaysShowThumbAlignmentBtns
-      ) {
-        // hide the alignment buttons
-        this.hideThumbAlignment();
-      }
-    } else {
-      thumbFieldKey = $select.val();
-      // show the alignment buttons
-      this.showThumbAlignment();
-    }
-
-    if (thumbFieldKey !== this.designer.config.thumbFieldKey) {
-      this.designer.updateConfig((config) => {
-        config.thumbFieldKey = thumbFieldKey;
-        return config;
-      });
-      this.updatePreview();
-    }
-  },
-
-  updateThumbnailsDropdown: function (element, action) {
-    const $select = this.$thumbManagementContainer.find(
-      'select[id$="thumb-source"]'
-    );
-    if (!$select.length) {
-      return;
-    }
-
-    const thumbOptions = element.$container.data('thumb-options');
-    if (!thumbOptions?.length) {
-      return;
-    }
-
-    thumbOptions.forEach((option) => {
-      const value = option.value.replace(/\{uid}/g, element.uid);
-      switch (action) {
-        case 'add':
-          $('<option/>', {
-            value,
-            text: option.label,
-          }).appendTo($select);
-          break;
-        case 'remove':
-          const $option = $select.find(`option[value="${value}"]`);
-          if ($option.length) {
-            const selected = $option.prop('selected');
-            $option.remove();
-            if (selected) {
-              this.manageThumbnails($select);
-            }
-          }
-          break;
-      }
-    });
-  },
-
-  updateThumbnailsDropdownOptionLabel: function ($container) {
-    let uid = $container.data('uid');
-    let $select = this.$thumbManagementContainer.find(
-      'select[id$="thumb-source"]'
-    );
-    let $option = $select.find('option[value="' + uid + '"]');
-
-    if ($option === null) {
-      return null;
-    }
-
-    let label = $container.find('.fld-element-label').text() ?? this.attribute;
-    $option.text(label);
-  },
-
-  showThumbAlignment: function () {
-    this.$thumbManagementContainer
-      .find('[data-attribute="thumb-alignment"]')
-      .removeClass('hidden');
-  },
-
-  hideThumbAlignment: function () {
-    this.$thumbManagementContainer
-      .find('[data-attribute="thumb-alignment"]')
-      .addClass('hidden');
-  },
-});
diff --git a/resources/js/cp.ts b/resources/js/cp.ts
index 788896a201d..eec9e984188 100644
--- a/resources/js/cp.ts
+++ b/resources/js/cp.ts
@@ -2,6 +2,9 @@ import '@craftcms/cp';
 import Cp from './bootstrap/cp.js';
 import './modules/navigation/components/CpGlobalSidebar.js';
 import './modules/navigation/components/CpQueueIndicator.js';
+// Field Layout Designer — modern @craftcms/garnish port; assigns
+// window.Craft.FieldLayoutDesigner so the PHP-emitted constructor keeps working.
+import './modules/field-layout-designer';
 
 window.Cp = Cp;
 
diff --git a/resources/js/legacy.ts b/resources/js/legacy.ts
index 11b92226f7c..37096269d44 100644
--- a/resources/js/legacy.ts
+++ b/resources/js/legacy.ts
@@ -1,10 +1,12 @@
+import '../legacy/cp/dist/css/cp.css';
+
 // We need to globally register these for the moment because an
 // elevated session modal can be called from pretty much anywhere
-await Promise.all([
-  import('./modules/auth/components/login/login-form.js'),
-  import('./modules/auth/components/totp/totp-form.js'),
-  import('./modules/auth/components/recovery-codes/recovery-code-form.js'),
-]);
+import './modules/auth/components/login/login-form.js';
+import './modules/auth/components/totp/totp-form.js';
+import './modules/auth/components/recovery-codes/recovery-code-form.js';
+
+import './modules/field-layout-designer/index';
 
 const {default: Cp} = await import('./bootstrap/cp.js');
 
diff --git a/resources/js/modules/field-layout-designer/CardViewDesigner.ts b/resources/js/modules/field-layout-designer/CardViewDesigner.ts
new file mode 100644
index 00000000000..19e2e28b200
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/CardViewDesigner.ts
@@ -0,0 +1,350 @@
+import {Base} from '@craftcms/garnish';
+import {cvdData} from './support';
+import type {FieldLayoutDesigner} from './FieldLayoutDesigner';
+import type {Element as FldElement} from './Element';
+
+declare const Craft: any;
+declare const $: any;
+declare const axios: any;
+
+/**
+ * The card view designer (preview + thumbnail/attribute management). Native DOM
+ * port of the legacy `Craft.FieldLayoutDesigner.CardViewDesigner`. jQuery
+ * survives only at the `Craft.SortableCheckboxSelect` / `Craft.ui` seams.
+ */
+export class CardViewDesigner extends Base {
+  designer: FieldLayoutDesigner;
+  $container: any = null;
+  $previewContainer: any = null;
+  $libraryContainer: any = null;
+  sortableCheckboxSelect: any = null;
+  $thumbManagementContainer: any = null;
+  alwaysShowThumbAlignmentBtns = false;
+  cancelToken: any = null;
+  attribute: any = null;
+
+  constructor(designer: FieldLayoutDesigner, container: any) {
+    super();
+    this.designer = designer;
+    this.$container = container;
+    cvdData.set(this.$container, this);
+
+    this.$previewContainer = this.$container.querySelector('.cvd-preview');
+    this.$libraryContainer = this.$container.querySelector(
+      '.cvd-library .checkbox-select'
+    );
+
+    // Craft.SortableCheckboxSelect stores itself via jQuery `.data()` — seam.
+    this.sortableCheckboxSelect = $(this.$libraryContainer).data(
+      'sortableCheckboxSelect'
+    );
+
+    // If the checkboxes haven't been initialized yet, do that.
+    if (!this.sortableCheckboxSelect) {
+      console.trace('Not initialized');
+      this.sortableCheckboxSelect = new Craft.SortableCheckboxSelect(
+        $(this.$libraryContainer)
+      );
+    }
+
+    this.$thumbManagementContainer =
+      this.$container.querySelector('.thumb-management');
+    this.alwaysShowThumbAlignmentBtns =
+      designer.settings!.alwaysShowThumbAlignmentBtns;
+
+    const $thumbSelectDropdown = this.$thumbManagementContainer.querySelector(
+      'select[id$="thumb-source"]'
+    );
+    this.addListener($thumbSelectDropdown, 'change', (ev: any) => {
+      this.manageThumbnails(ev.target);
+    });
+
+    if (this.alwaysShowThumbAlignmentBtns) {
+      // always show the thumbnail alignment buttons
+      this.showThumbAlignment();
+    }
+
+    const $thumbAlignmentBtns = this.$thumbManagementContainer.querySelectorAll(
+      'div.btngroup[id$="thumb-alignment"] .btn'
+    );
+    this.addListener($thumbAlignmentBtns, 'activate', (ev: any) => {
+      this.manageThumbnailAlignment(ev.target);
+    });
+
+    this.listenToCheckboxEvents();
+    this.disablePreviewLinks();
+  }
+
+  initDrag($draggable: any): void {
+    this.sortableCheckboxSelect.initDrag();
+    // Craft.SortableCheckboxSelect.initItem expects a jQuery element — seam.
+    this.sortableCheckboxSelect.initItem($($draggable));
+
+    // trigger preview update when items are dragged into new position
+    this.sortableCheckboxSelect.dragSort?.on('dragStop', () => {
+      this.updatePreview();
+    });
+
+    this.listenToCheckboxEvents();
+  }
+
+  listenToCheckboxEvents(): void {
+    // trigger preview update when items are checked/unchecked
+    this.addListener(this.$libraryContainer, 'change', (ev: any) => {
+      if ((ev.target as HTMLElement).matches('input[type=checkbox]')) {
+        this.updateCardViewConfig();
+        this.updatePreview();
+      }
+    });
+    this.sortableCheckboxSelect.on('sortChange', () => {
+      this.updateCardViewConfig();
+      this.updatePreview();
+    });
+  }
+
+  updateCardViewConfig(): void {
+    this.designer.updateConfig((config: any) => {
+      // can't rely on :checked
+      config.cardView = (
+        Array.from(
+          this.$libraryContainer.querySelectorAll('input[type=checkbox]')
+        ) as HTMLInputElement[]
+      )
+        .filter((el) => el.checked)
+        .map((el) => el.value);
+      return config;
+    });
+  }
+
+  async updatePreview(): Promise<void> {
+    this.$previewContainer.classList.add('loading');
+    Craft.cp.announce(Craft.t('app', 'Loading'));
+
+    if (this.cancelToken) {
+      this.cancelToken.cancel();
+    }
+
+    this.cancelToken = axios.CancelToken.source();
+
+    let response;
+    try {
+      response = await Craft.sendActionRequest(
+        'POST',
+        'fields/render-card-preview',
+        {
+          cancelToken: this.cancelToken.token,
+          data: {
+            fieldLayoutConfig: this.designer.config,
+          },
+        }
+      );
+    } catch (e: any) {
+      if (!axios.isCancel(e)) {
+        Craft.cp.displayError(e?.response?.data?.message);
+        throw e;
+      } else {
+        console.log('cancelled');
+      }
+    } finally {
+      this.$previewContainer.classList.remove('loading');
+      Craft.cp.announce(Craft.t('app', 'Loading complete'));
+      this.cancelToken = null;
+    }
+
+    if (response) {
+      this.$previewContainer.innerHTML = response.data.previewHtml;
+      this.disablePreviewLinks();
+    }
+  }
+
+  disablePreviewLinks(): void {
+    this.$previewContainer
+      .querySelectorAll('a')
+      .forEach((anchor: HTMLElement) => {
+        // add aria-disabled to the preview links
+        anchor.setAttribute('aria-disabled', 'true');
+        // prevent the preview links from being clickable
+        anchor.addEventListener('click', (ev) => {
+          ev.preventDefault();
+        });
+      });
+  }
+
+  addCheckbox(config: any = {}): void {
+    if (!this.$libraryContainer) {
+      return;
+    }
+
+    const $draggable = document.createElement('div');
+    $draggable.className = 'checkbox-select-item';
+    if (Craft.hasMousePointerEvents()) {
+      const $handle = document.createElement('a');
+      $handle.className = 'move icon draggable-handle disabled';
+      $draggable.appendChild($handle);
+    }
+    // Craft.ui returns jQuery — unwrap to native at the seam.
+    $draggable.appendChild(
+      Craft.ui.createCheckbox(
+        Object.assign(
+          {
+            checked: false,
+          },
+          config
+        )
+      )[0]
+    );
+
+    this.$libraryContainer.appendChild($draggable);
+
+    // re-init dragging
+    this.initDrag($draggable);
+  }
+
+  updateCheckboxLabel(value: string, label: string): void {
+    const $draggable = this.findCheckboxByValue(value);
+    if ($draggable) {
+      const $label = $draggable.querySelector('label');
+      if ($label) {
+        $label.textContent = label;
+      }
+    }
+  }
+
+  removeCheckbox(value: string): void {
+    const $draggable = this.findCheckboxByValue(value);
+
+    if ($draggable) {
+      const updateConfig = (
+        $draggable.querySelector('input[type="checkbox"]') as HTMLInputElement
+      )?.checked;
+      $draggable.remove();
+
+      // and now make a call to update the card preview
+      if (updateConfig) {
+        this.updateCardViewConfig();
+        this.updatePreview();
+      }
+    }
+  }
+
+  findCheckboxByValue(value: string): HTMLElement | null {
+    if (!this.$libraryContainer) {
+      return null;
+    }
+
+    return (
+      this.$libraryContainer
+        .querySelector(`input[value="${value}"]`)
+        ?.closest('.checkbox-select-item') ?? null
+    );
+  }
+
+  /** THUMBNAILS **/
+  manageThumbnailAlignment(target: any): void {
+    const alignment = target.dataset.value;
+
+    if (alignment !== this.designer.config.thumbAlignment) {
+      this.designer.updateConfig((config: any) => {
+        config.cardThumbAlignment = alignment;
+        return config;
+      });
+      this.updatePreview();
+    }
+  }
+
+  manageThumbnails(target: any): void {
+    const $select = target;
+    let thumbFieldKey = null;
+
+    if ($select.value === '__none__' || $select.value === '__default__') {
+      if (
+        $select.value === '__none__' &&
+        !this.designer.settings!.alwaysShowThumbAlignmentBtns
+      ) {
+        // hide the alignment buttons
+        this.hideThumbAlignment();
+      }
+    } else {
+      thumbFieldKey = $select.value;
+      // show the alignment buttons
+      this.showThumbAlignment();
+    }
+
+    if (thumbFieldKey !== this.designer.config.thumbFieldKey) {
+      this.designer.updateConfig((config: any) => {
+        config.thumbFieldKey = thumbFieldKey;
+        return config;
+      });
+      this.updatePreview();
+    }
+  }
+
+  updateThumbnailsDropdown(element: FldElement, action: string): void {
+    const $select = this.$thumbManagementContainer.querySelector(
+      'select[id$="thumb-source"]'
+    );
+    if (!$select) {
+      return;
+    }
+
+    const thumbOptions = element.$container.dataset.thumbOptions
+      ? JSON.parse(element.$container.dataset.thumbOptions)
+      : null;
+    if (!thumbOptions?.length) {
+      return;
+    }
+
+    thumbOptions.forEach((option: any) => {
+      const value = option.value.replace(/\{uid}/g, element.uid);
+      switch (action) {
+        case 'add': {
+          const $option = document.createElement('option');
+          $option.value = value;
+          $option.text = option.label;
+          $select.appendChild($option);
+          break;
+        }
+        case 'remove': {
+          const $option = $select.querySelector(`option[value="${value}"]`);
+          if ($option) {
+            const selected = $option.selected;
+            $option.remove();
+            if (selected) {
+              this.manageThumbnails($select);
+            }
+          }
+          break;
+        }
+      }
+    });
+  }
+
+  updateThumbnailsDropdownOptionLabel($container: any): void {
+    const uid = $container.dataset.uid;
+    const $select = this.$thumbManagementContainer.querySelector(
+      'select[id$="thumb-source"]'
+    );
+    const $option = $select?.querySelector(`option[value="${uid}"]`);
+
+    if (!$option) {
+      return;
+    }
+
+    const label =
+      $container.querySelector('.fld-element-label')?.textContent ??
+      this.attribute;
+    $option.textContent = label;
+  }
+
+  showThumbAlignment(): void {
+    this.$thumbManagementContainer
+      .querySelectorAll('[data-attribute="thumb-alignment"]')
+      .forEach((el: HTMLElement) => el.classList.remove('hidden'));
+  }
+
+  hideThumbAlignment(): void {
+    this.$thumbManagementContainer
+      .querySelectorAll('[data-attribute="thumb-alignment"]')
+      .forEach((el: HTMLElement) => el.classList.add('hidden'));
+  }
+}
diff --git a/resources/js/modules/field-layout-designer/Element.ts b/resources/js/modules/field-layout-designer/Element.ts
new file mode 100644
index 00000000000..a3efb6f4698
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/Element.ts
@@ -0,0 +1,633 @@
+import {Base, hasAttr} from '@craftcms/garnish';
+import {FieldLayoutDesigner} from './FieldLayoutDesigner';
+import {
+  fldElementData,
+  firstFocusableInSiblings,
+  htmlToElement,
+} from './support';
+import type {Tab} from './Tab';
+
+declare const Craft: any;
+declare const $: any;
+
+/**
+ * A single layout element (field or UI element) within a {@link Tab}. Native DOM
+ * port of the legacy `Craft.FieldLayoutDesigner.Element`. jQuery survives only at
+ * Craft seams (`Craft.ui.*`, the `.disclosureMenu()` plugin, `Craft.*Slideout`).
+ */
+export class Element extends Base {
+  tab: Tab;
+  $container: any = null;
+  $actionBtn: any = null;
+
+  uid: any = null;
+  isMandatory = false;
+  isMultiInstance: any = null;
+  isField = false;
+  attribute: any = null;
+  requirable = false;
+  thumbable = false;
+  hasCustomWidth = false;
+  hasSettings = false;
+  settingsNamespace: any = null;
+  slideout: any = null;
+  defaultHandle: any = null;
+  fieldId: any = null;
+  fieldsWithErrors: any[] = [];
+
+  constructor(tab: Tab, $container: any) {
+    super();
+    this.tab = tab;
+    this.$container = $container;
+    this.uid = $container.dataset.uid;
+    this.fieldId = $container.dataset.id;
+
+    this.fieldsWithErrors = [];
+
+    // New element?
+    const isNew = !this.uid;
+    if (isNew) {
+      this.uid = Craft.uuid();
+      this.config = Object.assign(JSON.parse($container.dataset.config), {
+        uid: this.uid,
+      });
+    }
+
+    this.initUi();
+
+    if (isNew && this.isField) {
+      // Find a unique handle
+      let handle = this.defaultHandle;
+      let i = 1;
+      while (this.tab.designer.hasHandle(handle)) {
+        i++;
+        handle = this.defaultHandle + i;
+      }
+      if (handle !== this.defaultHandle) {
+        this.config = Object.assign({}, this.config, {handle: handle});
+        const $label = $container.querySelector('.fld-attribute-label');
+        if ($label) {
+          $label.textContent = handle;
+        }
+      }
+      this.tab.designer.refreshSelectedFields();
+    }
+
+    // cleanup
+    $container.removeAttribute('data-keywords');
+  }
+
+  initUi(): void {
+    fldElementData.set(this.$container, this);
+
+    this.isMandatory = hasAttr(this.$container, 'data-mandatory');
+    this.isField = this.$container.classList.contains('fld-field');
+    this.isMultiInstance = hasAttr(this.$container, 'data-is-multi-instance');
+
+    if (this.isField) {
+      this.requirable = hasAttr(this.$container, 'data-requirable');
+      this.thumbable = hasAttr(this.$container, 'data-thumbable');
+      this.attribute = this.$container.dataset.attribute;
+      this.defaultHandle = this.$container.dataset.defaultHandle;
+    }
+
+    this.hasCustomWidth =
+      this.tab.designer.settings!.customizableUi &&
+      hasAttr(this.$container, 'data-has-custom-width');
+
+    if (this.hasCustomWidth) {
+      const widthSlider = new Craft.SlidePicker(this.config.width || 100, {
+        min: 25,
+        max: 100,
+        step: 25,
+        valueLabel: (width: number) => {
+          return Craft.t('app', '{pct} width', {pct: `${width}%`});
+        },
+        onChange: (width: number) => {
+          this.updateConfig((config: any) => {
+            config.width = width;
+            return config;
+          });
+        },
+        readOnly: this.tab.designer.settings!.readOnly,
+      });
+      // Craft.SlidePicker exposes a jQuery $container — unwrap to native.
+      this.$container.appendChild(widthSlider.$container[0]);
+    }
+
+    // create the action menu
+    const menuId = `actionmenu${Math.floor(Math.random() * 1000000)}`;
+    this.$actionBtn = document.createElement('button');
+    this.$actionBtn.setAttribute('type', 'button');
+    this.$actionBtn.className = 'btn action-btn';
+    this.$actionBtn.setAttribute('data-disclosure-trigger', 'true');
+    this.$actionBtn.setAttribute('aria-controls', menuId);
+    this.$actionBtn.setAttribute('aria-haspopup', 'true');
+    this.$actionBtn.setAttribute('aria-label', Craft.t('app', 'Actions'));
+    this.$actionBtn.setAttribute('title', Craft.t('app', 'Actions'));
+    if (this.tab.designer.settings!.readOnly) {
+      this.$actionBtn.disabled = true;
+    }
+    this.$container.appendChild(this.$actionBtn);
+
+    const $menu = document.createElement('div');
+    $menu.id = menuId;
+    $menu.className = 'menu menu--disclosure';
+    $menu.setAttribute('data-disclosure-menu', 'true');
+    this.$container.appendChild($menu);
+
+    // The `.disclosureMenu()` jQuery plugin is a Craft seam.
+    const disclosureMenu = $(this.$actionBtn)
+      .disclosureMenu()
+      .data('disclosureMenu');
+
+    let makeRequiredBtn: any, dropRequiredBtn: any;
+
+    this.hasSettings = hasAttr(this.$container, 'data-has-settings');
+
+    if (this.hasSettings && !this.tab.designer.settings!.readOnly) {
+      disclosureMenu.addItem({
+        label: Craft.t('app', 'Settings'),
+        icon: async () => await Craft.ui.icon('gear'),
+        onActivate: () => {
+          this.createSettings();
+        },
+      });
+
+      this.addListener(this.$container, 'dblclick', () => {
+        this.createSettings();
+      });
+    }
+
+    if (
+      this.requirable ||
+      (!this.tab.designer.settings!.withCardViewDesigner && this.thumbable)
+    ) {
+      const actionUl = disclosureMenu.addGroup();
+
+      if (this.requirable) {
+        makeRequiredBtn = disclosureMenu.addItem(
+          {
+            label: Craft.t('app', 'Make required'),
+            icon: async () => await Craft.ui.icon('asterisk'),
+            iconColor: 'rose',
+            onActivate: () => {
+              this.makeRequired();
+            },
+          },
+          actionUl
+        );
+
+        dropRequiredBtn = disclosureMenu.addItem(
+          {
+            label: Craft.t('app', 'Make optional'),
+            icon: async () => await Craft.ui.icon('asterisk-slash'),
+            iconColor: 'gray',
+            onActivate: () => {
+              this.dropRequired();
+            },
+          },
+          actionUl
+        );
+      }
+    }
+
+    const moveGroup = disclosureMenu.addGroup();
+    const moveUpBtn = disclosureMenu.addItem(
+      {
+        label: Craft.t('app', 'Move up'),
+        icon: async () => await Craft.ui.icon('arrow-up'),
+        onActivate: () => {
+          this.moveUp();
+        },
+      },
+      moveGroup
+    );
+    const moveDownBtn = disclosureMenu.addItem(
+      {
+        label: Craft.t('app', 'Move down'),
+        icon: async () => await Craft.ui.icon('arrow-down'),
+        onActivate: () => {
+          this.moveDown();
+        },
+      },
+      moveGroup
+    );
+
+    if (!this.isMandatory) {
+      disclosureMenu.addItem(
+        {
+          label: Craft.t('app', 'Remove'),
+          icon: async () => await Craft.ui.icon('xmark'),
+          destructive: true,
+          onActivate: () => {
+            this.destroy();
+          },
+        },
+        disclosureMenu.addGroup()
+      );
+    }
+
+    disclosureMenu.on('show', () => {
+      if (this.requirable) {
+        disclosureMenu.toggleItem(makeRequiredBtn, !this.config.required);
+        disclosureMenu.toggleItem(dropRequiredBtn, this.config.required);
+      }
+
+      const prev = this.$container.previousElementSibling;
+      const next = this.$container.nextElementSibling;
+      disclosureMenu.toggleItem(
+        moveUpBtn,
+        !!(prev && prev.matches('.fld-element'))
+      );
+      disclosureMenu.toggleItem(
+        moveDownBtn,
+        !!(next && next.matches('.fld-element'))
+      );
+    });
+  }
+
+  onSelect(): void {
+    this.$container.setAttribute('data-uid', this.uid);
+
+    const previewOptions = this.$container.dataset.previewOptions
+      ? JSON.parse(this.$container.dataset.previewOptions)
+      : null;
+    if (previewOptions) {
+      const cvd = this.tab.designer.cvd;
+      if (cvd) {
+        previewOptions.forEach((option: any) => {
+          cvd.addCheckbox({
+            value: option.value.replace(/\{uid}/g, this.uid),
+            label: option.label,
+          });
+        });
+        cvd.updateThumbnailsDropdown(this, 'add');
+      }
+    }
+  }
+
+  getLabel(): string {
+    const label =
+      this.$container.querySelector('.fld-element-label')?.textContent ?? '';
+    return label !== '' ? label : this.$container.dataset.attribute;
+  }
+
+  async createSettings(): Promise<void> {
+    let data;
+    try {
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'fields/render-layout-component-settings',
+        {
+          data: {
+            uid: this.uid,
+            layoutConfig: this.tab.designer.config,
+            elementType: this.tab.designer.settings!.elementType,
+          },
+        }
+      );
+      data = response.data;
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+      throw e;
+    }
+
+    this.settingsNamespace = data.namespace;
+    this.slideout = await FieldLayoutDesigner.createSlideout(data, null, {
+      triggerElement: this.$actionBtn,
+    });
+
+    // slideout.$container is a Craft jQuery object; bind on the native form.
+    this.addListener(this.slideout.$container[0], 'submit', (ev: any) => {
+      ev.preventDefault();
+      this.applySettings();
+    });
+    this.slideout.on('close', () => {
+      this.slideout.destroy();
+      this.slideout = null;
+    });
+
+    const $fieldsContainer =
+      this.slideout.$container[0].querySelector('.fields');
+
+    if (this.isField) {
+      const $handleInput = $fieldsContainer?.querySelector(
+        'input[name$="[handle]"]'
+      );
+      if ($handleInput) {
+        $handleInput.value = this.config.handle || '';
+      }
+    }
+
+    this.trigger('createSettings');
+  }
+
+  async applySettings(): Promise<void> {
+    // update the UI
+    const $submitBtn = this.slideout.$container[0].querySelector(
+      'button[type=submit]'
+    );
+    $submitBtn?.classList.add('loading');
+
+    try {
+      await this.applyConfig(() => this.config, true);
+    } finally {
+      $submitBtn?.classList.remove('loading');
+    }
+  }
+
+  async showFieldEditor(): Promise<void> {
+    const slideout = new Craft.CpScreenSlideout('fields/edit-field', {
+      params: {
+        fieldId: this.fieldId,
+        multiInstanceTypesOnly: this.isMultiInstance ? 1 : 0,
+      },
+    });
+
+    slideout.on('submit', async ({response}: any) => {
+      const designer = this.tab.designer;
+
+      // refresh the library selector
+      const $oldSelector = designer.$fieldLibrary.querySelector(
+        `.fld-field[data-id=${this.fieldId}]`
+      );
+      const $newSelector = htmlToElement(response.data.selectorHtml);
+      $oldSelector?.replaceWith($newSelector);
+      designer.refreshLibraryFields();
+      designer.elementDrag!.removeItems($oldSelector);
+      designer.elementDrag!.addItems($newSelector);
+
+      // refresh all instances of this field
+      designer.$tabContainer
+        .querySelectorAll(`.fld-field[data-id=${this.fieldId}]`)
+        .forEach((el: HTMLElement) => fldElementData.get(el)?.refresh());
+    });
+  }
+
+  async makeRequired(): Promise<void> {
+    await this.applyConfig((config: any) => {
+      config.required = true;
+      return config;
+    });
+  }
+
+  async dropRequired(): Promise<void> {
+    await this.applyConfig((config: any) => {
+      config.required = false;
+      return config;
+    });
+  }
+
+  moveUp(): void {
+    const $prev = this.$container.previousElementSibling;
+    if ($prev && $prev.matches('.fld-element')) {
+      $prev.before(this.$container);
+      this.updatePositionInConfig();
+    }
+  }
+
+  moveDown(): void {
+    const $next = this.$container.nextElementSibling;
+    if ($next && $next.matches('.fld-element')) {
+      $next.after(this.$container);
+      this.updatePositionInConfig();
+    }
+  }
+
+  async applyConfig(
+    callback: (config: any) => any,
+    withSettings = false
+  ): Promise<void> {
+    const config = callback(this.config);
+    if (config === false) {
+      return;
+    }
+
+    // Craft.ui error helpers require jQuery fields — keep them at the seam.
+    this.fieldsWithErrors.forEach(($field: any) => {
+      Craft.ui.clearErrorsFromField($field);
+    });
+
+    let data;
+
+    try {
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'fields/apply-layout-element-settings',
+        {
+          data: {
+            uid: this.uid,
+            layoutConfig: this.tab.designer.config,
+            elementType: this.tab.designer.settings!.elementType,
+            config,
+            settingsNamespace: this.settingsNamespace,
+            settings: withSettings
+              ? this.slideout.$container.serialize()
+              : null,
+          },
+        }
+      );
+      data = response.data;
+    } catch (e: any) {
+      if (withSettings) {
+        const errors = e?.response?.data?.errors;
+        if (errors) {
+          Object.entries(errors).forEach(([name, fieldErrors]) => {
+            // Craft.ui.addErrorsToField needs a jQuery field — seam.
+            const $field = this.slideout.$container.find(
+              `[data-error-key="${name}"]`
+            );
+            if ($field.length) {
+              Craft.ui.addErrorsToField($field, fieldErrors);
+              this.fieldsWithErrors.push($field);
+            }
+          });
+        }
+      }
+
+      Craft.cp.displayError(e?.response?.data?.message);
+      throw e;
+    }
+
+    this.config = data.config;
+    const $oldContainer = this.$container;
+    const $newContainer = htmlToElement(data.selectorHtml);
+    this.$container.replaceWith($newContainer);
+    this.$container = $newContainer;
+    this.initUi();
+
+    if (this.tab.designer.settings!.withCardViewDesigner) {
+      const cvd = this.tab.designer.cvd;
+      if (cvd) {
+        const previewOptions = $newContainer.dataset.previewOptions
+          ? JSON.parse($newContainer.dataset.previewOptions)
+          : null;
+        if (previewOptions) {
+          // update labels in cvd checkboxes
+          previewOptions.forEach((option: any) => {
+            cvd.updateCheckboxLabel(
+              option.value.replace(/\{uid}/g, this.uid),
+              option.label
+            );
+          });
+        }
+
+        // update label in the element thumbnails dropdown
+        cvd.updateThumbnailsDropdownOptionLabel(this.$container);
+      }
+    }
+
+    const designer = this.tab.designer;
+    designer.refreshSelectedFields();
+    designer.elementDrag!.removeItems($oldContainer);
+    designer.elementDrag!.addItems($newContainer);
+
+    if (this.slideout) {
+      this.slideout.close();
+      this.slideout.destroy();
+      this.slideout = null;
+    }
+
+    if (this.config.providesThumbs) {
+      // make sure this is the only one
+      this.tab.designer.$tabContainer
+        .querySelectorAll('.fld-field')
+        .forEach(($field: HTMLElement) => {
+          const element = fldElementData.get($field);
+          if (element && element !== this && element.config.providesThumbs) {
+            element.applyConfig((config: any) => {
+              config.providesThumbs = false;
+              return config;
+            });
+          }
+        });
+    }
+  }
+
+  async refresh(): Promise<void> {
+    await this.applyConfig((config: any) => config);
+  }
+
+  get index(): number {
+    const tabConfig = this.tab.config;
+    if (typeof tabConfig === 'undefined') {
+      return -1;
+    }
+    return tabConfig.elements.findIndex((c: any) => c.uid === this.uid);
+  }
+
+  get config(): any {
+    if (!this.uid) {
+      throw 'Tab is missing its UID';
+    }
+    let config = this.tab.config.elements.find((c: any) => c.uid === this.uid);
+    if (!config) {
+      config = {
+        uid: this.uid,
+      };
+      this.config = config;
+    }
+    return config;
+  }
+
+  set config(config: any) {
+    const tabConfig = this.tab.config;
+    const index = this.index;
+    if (index !== -1) {
+      tabConfig.elements[index] = config;
+    } else {
+      const siblings = Array.from(
+        this.$container.parentElement.querySelectorAll(':scope > .fld-element')
+      );
+      const newIndex = siblings.indexOf(this.$container);
+      tabConfig.elements.splice(newIndex, 0, config);
+    }
+    this.tab.config = tabConfig;
+  }
+
+  updateConfig(callback: (config: any) => any): void {
+    const config = callback(this.config);
+    if (config !== false) {
+      this.config = config;
+    }
+  }
+
+  updatePositionInConfig(): void {
+    this.tab.updateConfig((config: any) => {
+      const elementConfig = this.config;
+      const oldIndex = this.index;
+      const siblings = Array.from(
+        this.$container.parentElement.querySelectorAll(':scope > .fld-element')
+      );
+      const newIndex = siblings.indexOf(this.$container);
+      if (oldIndex !== -1) {
+        config.elements.splice(oldIndex, 1);
+      }
+      config.elements.splice(newIndex, 0, elementConfig);
+      return config;
+    });
+  }
+
+  override destroy(): void {
+    if (this.tab.designer.settings!.withCardViewDesigner) {
+      const cvd = this.tab.designer.cvd;
+      if (cvd) {
+        // this needs to be called before removeCheckbox()
+        cvd.updateThumbnailsDropdown(this, 'remove');
+
+        const previewOptions = this.$container.dataset.previewOptions
+          ? JSON.parse(this.$container.dataset.previewOptions)
+          : null;
+        if (previewOptions?.length) {
+          previewOptions.forEach((option: any) => {
+            cvd.removeCheckbox(option.value.replace(/\{uid}/g, this.uid));
+          });
+        }
+      }
+    }
+
+    this.tab.updateConfig((config: any) => {
+      const index = this.index;
+      if (index === -1) {
+        return false;
+      }
+      config.elements.splice(index, 1);
+      return config;
+    });
+
+    // Set focus to the closest element's first focusable element
+    const $focusElement = firstFocusableInSiblings(this.$container);
+    if ($focusElement) {
+      $focusElement.focus();
+    } else {
+      this.tab.$addBtn.focus();
+    }
+
+    this.tab.designer.elementDrag!.removeItems(this.$container);
+    this.$container.remove();
+
+    if (this.isField) {
+      this.tab.designer.refreshSelectedFields();
+
+      if (!this.isMultiInstance) {
+        this.tab.designer.removeFieldByHandle(
+          this.defaultHandle || this.attribute
+        );
+      }
+    } else {
+      // if it's not a field (so a ui element) and it's not multi instance, make it visible for selection again
+      if (!this.isMultiInstance) {
+        const uiLibraryElement = this.tab.designer.$uiLibraryElements.find(
+          (el: HTMLElement) =>
+            el.matches(`[data-type="${this.$container.dataset.type}"]`)
+        );
+        if (uiLibraryElement) {
+          uiLibraryElement.classList.remove('hidden');
+        }
+      }
+    }
+
+    super.destroy();
+  }
+}
diff --git a/resources/js/modules/field-layout-designer/FieldLayoutDesigner.ts b/resources/js/modules/field-layout-designer/FieldLayoutDesigner.ts
new file mode 100644
index 00000000000..9e32a906e16
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/FieldLayoutDesigner.ts
@@ -0,0 +1,565 @@
+import {
+  Base,
+  ESC_KEY,
+  RETURN_KEY,
+  hasAttr,
+  requestAnimationFrame,
+} from '@craftcms/garnish';
+import {Tab} from './Tab';
+import {CardViewDesigner} from './CardViewDesigner';
+import {ElementDrag, TabDrag} from './drags';
+import {fldTabData, fldElementData, hudData, htmlToElement} from './support';
+import type {FieldLayoutDesignerSettings, FieldLayoutConfig} from './types';
+
+// `Craft` and jQuery (`$`) are still globals on the page. FLD is native; `$` is
+// used ONLY at the Craft-interop seams (Craft.ui/Grid/Listbox/Slideout return or
+// require jQuery). Everywhere else FLD uses native DOM.
+declare const Craft: any;
+declare const $: any;
+
+/**
+ * Field Layout Designer — a port of the legacy `Craft.FieldLayoutDesigner` onto
+ * the modern, jQuery-free `@craftcms/garnish` named API. FLD's own DOM work is
+ * native (`document.*`, `classList`, `dataset`, WeakMaps); jQuery survives only
+ * at the boundary with Craft's still-jQuery widgets.
+ */
+export class FieldLayoutDesigner extends Base<FieldLayoutDesignerSettings> {
+  static defaults: FieldLayoutDesignerSettings = {
+    elementType: null,
+    customizableTabs: true,
+    customizableUi: true,
+    withCardViewDesigner: false,
+    alwaysShowThumbAlignmentBtns: false,
+    readOnly: false,
+  };
+
+  $container: any = null;
+  $innerContainer: any = null;
+  $configInput: any = null;
+  $tabContainer: any = null;
+  $newTabBtn: any = null;
+  $libraryContainer: any = null;
+  $selectedLibrary: any = null;
+  $fieldLibrary: any = null;
+  $uiLibrary: any = null;
+  $uiLibraryElements: any = null;
+  $fieldSearch: any = null;
+  $clearFieldSearchBtn: any = null;
+  $fieldGroups: any = null;
+  $fields: any = null;
+  $createFieldBtn: any = null;
+
+  libraryPicker: any = null;
+  tabGrid: any = null;
+  elementDrag: ElementDrag | null = null;
+  tabDrag: TabDrag | null = null;
+
+  cvd: CardViewDesigner | null = null;
+  $cvd: any = null;
+
+  _config: FieldLayoutConfig | null = null;
+  _$selectedFields: any = null;
+  _fieldHandles: Record<string, unknown> = {};
+
+  constructor(container: any, settings?: Partial<FieldLayoutDesignerSettings>) {
+    super();
+    this.$container =
+      typeof container === 'string'
+        ? document.querySelector(container)
+        : container;
+    this.setSettings(settings, FieldLayoutDesigner.defaults);
+
+    this.$configInput = this.$container.querySelector(
+      ':scope > input[data-config-input]'
+    );
+    this._config = JSON.parse(this.$configInput.value);
+    if (!this._config!.tabs) {
+      this._config!.tabs = [];
+    }
+
+    this._fieldHandles = {};
+
+    this.$innerContainer = this.$container.querySelector(
+      ':scope > .fld-container'
+    );
+    const $workspace = this.$innerContainer.querySelector(
+      ':scope > .fld-workspace'
+    );
+    this.$tabContainer = $workspace.querySelector(':scope > .fld-tabs');
+    this.$newTabBtn = $workspace.querySelector(':scope > .fld-new-tab-btn');
+    this.$libraryContainer = this.$innerContainer.querySelector(
+      ':scope > .fld-library'
+    );
+
+    this.$fieldLibrary = this.$selectedLibrary =
+      this.$libraryContainer.querySelector(':scope > .fld-field-library');
+    const $fieldSearchContainer =
+      this.$fieldLibrary.querySelector(':scope > .search');
+    this.$fieldSearch = $fieldSearchContainer.querySelector(':scope > input');
+    this.$clearFieldSearchBtn = $fieldSearchContainer.querySelector(
+      ':scope > .clear-btn'
+    );
+    this.$fieldGroups = Array.from(
+      this.$libraryContainer.querySelectorAll('.fld-field-group')
+    );
+    this.$fields = this.collectLibraryFields();
+    this.$uiLibrary = this.$libraryContainer.querySelector(
+      ':scope > .fld-ui-library'
+    );
+    this.$uiLibraryElements = Array.from(this.$uiLibrary.children);
+
+    if (this.settings!.readOnly) {
+      this.$fieldLibrary.setAttribute('tabindex', '-1');
+    }
+    // Set up the layout grids — Craft.Grid is a jQuery seam.
+    this.tabGrid = new Craft.Grid($(this.$tabContainer), {
+      itemSelector: '.fld-tab',
+      minColWidth: 24 * 13,
+      fillMode: 'grid',
+      snapToGrid: 24,
+    });
+
+    const $tabs = Array.from(this.$tabContainer.children);
+    for (const tab of $tabs) {
+      this.initTab(tab as HTMLElement);
+    }
+
+    this.elementDrag = new ElementDrag(this);
+    if (!this.settings!.readOnly) {
+      this.initLibraryElements(
+        this.$libraryContainer.querySelectorAll('.fld-element')
+      );
+    }
+
+    if (this.settings!.customizableTabs) {
+      this.tabDrag = new TabDrag(this);
+
+      this.addListener(this.$newTabBtn, 'activate', 'addTab');
+    }
+
+    // Set up the library
+    if (this.settings!.customizableUi) {
+      const $libraryPicker =
+        this.$libraryContainer.querySelector(':scope > .btngroup');
+      // Craft.Listbox is a jQuery seam; its onChange hands us a jQuery option.
+      this.libraryPicker = new Craft.Listbox($($libraryPicker), {
+        onChange: ($selectedOption: any) => {
+          const library = $selectedOption[0]?.dataset.library;
+          switch (library) {
+            case 'field':
+              this.$fieldLibrary.classList.remove('hidden');
+              this.$uiLibrary.classList.add('hidden');
+              this.$createFieldBtn.classList.remove('hidden');
+              break;
+            case 'ui':
+              this.$fieldLibrary.classList.add('hidden');
+              this.$uiLibrary.classList.remove('hidden');
+              this.$createFieldBtn.classList.add('hidden');
+              break;
+          }
+        },
+      });
+    }
+
+    this.addListener(this.$fieldSearch, 'input', () => {
+      this.updateFieldSearchResults();
+    });
+
+    this.addListener(this.$fieldSearch, 'keydown', (ev: any) => {
+      switch (ev.keyCode) {
+        case ESC_KEY:
+          this.clearSearch();
+          break;
+        case RETURN_KEY:
+          // they most likely don't want to submit the form from here
+          ev.preventDefault();
+          break;
+      }
+    });
+
+    // Clear the search when the X button is clicked
+    this.addListener(this.$clearFieldSearchBtn, 'click', () => {
+      this.clearSearch();
+    });
+
+    this.refreshSelectedFields();
+
+    // Add the “New Field” button — Craft.ui returns jQuery; unwrap to native.
+    this.$createFieldBtn = Craft.ui.createButton({
+      label: Craft.t('app', 'New field'),
+      class: 'mt-m fullwidth add icon dashed',
+      disabled: this.settings!.readOnly,
+    })[0];
+    this.$libraryContainer.appendChild(this.$createFieldBtn);
+
+    this.addListener(this.$createFieldBtn, 'activate', async () => {
+      this.createField();
+    });
+
+    // initiate Card Attributes Designer
+    if (this.settings!.withCardViewDesigner) {
+      this.$cvd = this.$container
+        .closest('.fld-cvd')
+        ?.querySelector('.card-view-designer');
+      this.initCvd();
+    }
+  }
+
+  /** Direct `.fld-element` children of every field group, in DOM order. */
+  collectLibraryFields(): HTMLElement[] {
+    const fields: HTMLElement[] = [];
+    for (const group of this.$fieldGroups) {
+      fields.push(
+        ...(Array.from(
+          group.querySelectorAll(':scope > .fld-element')
+        ) as HTMLElement[])
+      );
+    }
+    return fields;
+  }
+
+  updateFieldSearchResults(): void {
+    const val = this.$fieldSearch.value.toLowerCase().replace(/['"]/g, '');
+    if (!val) {
+      this.$fieldLibrary
+        .querySelectorAll('.filtered')
+        .forEach((el: HTMLElement) => el.classList.remove('filtered'));
+      this.$clearFieldSearchBtn.classList.add('hidden');
+      return;
+    }
+
+    this.$clearFieldSearchBtn.classList.remove('hidden');
+
+    const matches = new Set<HTMLElement>();
+    for (const el of this.$fields) {
+      if (el.matches(`[data-keywords*="${val}"]`)) {
+        matches.add(el);
+      }
+    }
+    for (const group of this.$fieldGroups) {
+      if (group.matches(`[data-name*="${val}"]`)) {
+        for (const el of group.querySelectorAll(':scope > .fld-element')) {
+          matches.add(el as HTMLElement);
+        }
+      }
+    }
+    for (const el of matches) {
+      el.classList.remove('filtered');
+    }
+    for (const el of this.$fields) {
+      if (!matches.has(el)) {
+        el.classList.add('filtered');
+      }
+    }
+
+    // hide any groups that don't have any results
+    for (const group of this.$fieldGroups) {
+      if (group.querySelector('.fld-element:not(.hidden):not(.filtered)')) {
+        group.classList.remove('filtered');
+      } else {
+        group.classList.add('filtered');
+      }
+    }
+  }
+
+  clearSearch(): void {
+    this.$fieldSearch.value = '';
+    this.$fieldSearch.dispatchEvent(new Event('input'));
+  }
+
+  initCvd(): void {
+    this.cvd = new CardViewDesigner(this, this.$cvd);
+
+    // Add skip link
+    const skipLinkAnchor = this.cvd.$container.id;
+
+    if (skipLinkAnchor) {
+      const $skipLink = document.createElement('a');
+      $skipLink.className = 'skip-link btn';
+      $skipLink.textContent = Craft.t('app', 'Skip to card view designer');
+      $skipLink.href = `#${skipLinkAnchor}`;
+
+      this.cvd.$container.setAttribute('tabindex', '-1');
+      this.$innerContainer.prepend($skipLink);
+    }
+  }
+
+  initTab($tab: any): Tab {
+    return new Tab(this, $tab);
+  }
+
+  removeFieldByHandle(attribute: string): void {
+    const field = this.$fields.find((el: HTMLElement) =>
+      el.matches(`[data-attribute="${attribute}"]`)
+    );
+    if (field) {
+      field.classList.remove('hidden');
+      field.closest('.fld-field-group')?.classList.remove('hidden');
+    }
+  }
+
+  addTab(): void {
+    if (!this.settings!.customizableTabs) {
+      return;
+    }
+
+    let defaultValue = '';
+    if (this.tabGrid.$items.length === 0) {
+      defaultValue = Craft.t('app', 'Content');
+    }
+    const name = Craft.escapeHtml(
+      prompt(Craft.t('app', 'Give your tab a name.'), defaultValue)
+    );
+
+    if (!name) {
+      return;
+    }
+
+    const $tab = htmlToElement(`
+<div class="fld-tab">
+  <div class="tabs">
+    <div class="tab sel draggable">
+      <h3 class="fld-tab__name">${name}</h3>
+    </div>
+  </div>
+  <div class="fld-tabcontent">
+    <button class="btn add icon dashed fullwidth fld-add-btn" type="button">
+      ${Craft.t('app', 'Add')}
+    </button>
+  </div>
+</div>
+`);
+    // keep it before the resize object
+    const $tabs = this.$tabContainer.querySelectorAll(':scope > .fld-tab');
+    const $lastTab = $tabs[$tabs.length - 1];
+    if ($lastTab) {
+      $lastTab.after($tab);
+    } else {
+      this.$tabContainer.prepend($tab);
+    }
+
+    this.tabGrid.addItems($($tab));
+    this.tabDrag!.addItems($tab);
+
+    const tab = this.initTab($tab);
+    tab.updatePositionInConfig();
+  }
+
+  get config(): FieldLayoutConfig {
+    return this._config!;
+  }
+
+  set config(config: FieldLayoutConfig) {
+    this._config = config;
+    this.$configInput.value = JSON.stringify(config);
+  }
+
+  updateConfig(
+    callback: (config: FieldLayoutConfig) => FieldLayoutConfig | false
+  ): void {
+    const config = callback(this.config);
+    if (config !== false) {
+      this.config = config;
+    }
+  }
+
+  refreshSelectedFields(): void {
+    this._$selectedFields = Array.from(
+      this.$tabContainer.querySelectorAll('.fld-field')
+    );
+  }
+
+  refreshLibraryFields(): void {
+    this.$fields = this.collectLibraryFields();
+
+    for (const $fieldGroup of this.$fieldGroups) {
+      const $fields = Array.from(
+        $fieldGroup.querySelectorAll(':scope > .fld-element')
+      ) as HTMLElement[];
+      $fields.sort((a, b) =>
+        (a.dataset.uiLabel ?? '') > (b.dataset.uiLabel ?? '') ? 1 : -1
+      );
+      for (const el of $fields) {
+        $fieldGroup.appendChild(el);
+      }
+    }
+
+    this.updateFieldSearchResults();
+  }
+
+  hasHandle(handle: string): boolean {
+    for (const el of this._$selectedFields) {
+      const element = fldElementData.get(el);
+      if (!element) {
+        continue;
+      }
+      const elementHandle = element.config.handle || element.attribute;
+      if (handle === elementHandle) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  createField(): void {
+    const slideout = new Craft.CpScreenSlideout('fields/edit-field');
+
+    slideout.on('submit', async ({response}: any) => {
+      // add the library selector
+      const $selector = htmlToElement(response.data.selectorHtml);
+      const $lastGroup = this.$fieldGroups[this.$fieldGroups.length - 1];
+      $lastGroup.appendChild($selector);
+      $lastGroup.classList.remove('hidden');
+      this.refreshLibraryFields();
+      this.initLibraryElements($selector);
+
+      // add it to the active tab
+      this.addLibraryElementToActiveTab($selector);
+
+      requestAnimationFrame(() => {
+        this.getActiveHud()?.hide();
+      });
+    });
+  }
+
+  initLibraryElements($elements: any): void {
+    this.elementDrag!.addItems($elements);
+
+    this.addListener($elements, 'activate', (ev: any) => {
+      // ignore if is on a dragged element
+      if (ev.currentTarget.style.visibility === 'hidden') {
+        return;
+      }
+      ev.stopPropagation();
+      ev.originalEvent.preventDefault();
+      this.addLibraryElementToActiveTab(ev.currentTarget);
+    });
+  }
+
+  cloneLibraryElementForSelection(libraryElement: any): HTMLElement {
+    // Create a new element based on that one
+    const $libraryElement = libraryElement as HTMLElement;
+    const $element = $libraryElement.cloneNode(true) as HTMLElement;
+    $element.classList.remove('unused');
+    $element.removeAttribute('tabindex');
+
+    if (!hasAttr($libraryElement, 'data-is-multi-instance')) {
+      // Hide the library element
+      $libraryElement.style.visibility = 'inherit';
+      $libraryElement.style.display = 'field';
+      $libraryElement.classList.add('hidden');
+
+      // Hide the group too?
+      const visibleSibling = Array.from(
+        $libraryElement.parentElement?.children ?? []
+      ).some(
+        (el) => el !== $libraryElement && el.matches('.fld-field:not(.hidden)')
+      );
+      if (!visibleSibling) {
+        $libraryElement.closest('.fld-field-group')?.classList.add('hidden');
+      }
+    }
+
+    // Add it to the element dragger
+    this.elementDrag!.addItems($element);
+
+    return $element;
+  }
+
+  getActiveHud(): any {
+    const hudEl = this.$libraryContainer.closest('.fld-library-hud');
+    return hudEl ? hudData.get(hudEl) : undefined;
+  }
+
+  addLibraryElementToActiveTab(libraryElement: any): void {
+    const hud = this.getActiveHud();
+    if (!hud) {
+      return;
+    }
+
+    const $element = this.cloneLibraryElementForSelection(libraryElement);
+    const tab = fldTabData.get(hud.$trigger.closest('.fld-tab'));
+    hud.$trigger.before($element);
+    const element = tab!.initElement($element);
+    element.onSelect();
+    element.updatePositionInConfig();
+  }
+
+  static async createSlideout(
+    data: any,
+    js: string | null,
+    settings: any = {}
+  ): Promise<any> {
+    const $body = document.createElement('div');
+    $body.className = 'fld-element-settings-body';
+    const $fields = document.createElement('div');
+    $fields.className = 'fields';
+    $fields.innerHTML = data.settingsHtml;
+    $body.appendChild($fields);
+
+    const $footer = document.createElement('div');
+    $footer.className = 'fld-element-settings-footer';
+    const $flexGrow = document.createElement('div');
+    $flexGrow.className = 'flex-grow';
+    $footer.appendChild($flexGrow);
+
+    // Craft.ui returns jQuery — unwrap to native at the seam.
+    const $cancelBtn = Craft.ui.createButton({
+      label: Craft.t('app', 'Close'),
+      spinner: true,
+    })[0];
+    $footer.appendChild($cancelBtn);
+    $footer.appendChild(
+      Craft.ui.createSubmitButton({
+        class: 'secondary',
+        label: Craft.t('app', 'Apply'),
+        spinner: true,
+      })[0]
+    );
+
+    // Craft.Slideout is a jQuery widget — pass a jQuery wrapper at the seam.
+    const slideout = new Craft.Slideout(
+      $([$body, $footer]),
+      Object.assign(
+        {
+          containerElement: 'form',
+          containerAttributes: {
+            action: '',
+            method: 'post',
+            novalidate: '',
+            class: 'fld-element-settings',
+          },
+        },
+        settings
+      )
+    );
+    slideout.on('open', () => {
+      // Hold off a sec until it's positioned...
+      requestAnimationFrame(() => {
+        // Focus on the first text input
+        (
+          slideout.$container[0].querySelector('.text') as HTMLElement | null
+        )?.focus();
+      });
+    });
+
+    $cancelBtn.addEventListener('click', () => {
+      slideout.close();
+    });
+
+    if (data.headHtml) {
+      await Craft.appendHeadHtml(data.headHtml);
+    }
+    if (data.bodyHtml) {
+      await Craft.appendBodyHtml(data.bodyHtml);
+    }
+    if (js) {
+      eval(js);
+    }
+
+    Craft.initUiElements(slideout.$container);
+
+    return slideout;
+  }
+}
diff --git a/resources/js/modules/field-layout-designer/README.md b/resources/js/modules/field-layout-designer/README.md
new file mode 100644
index 00000000000..65d1b91d102
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/README.md
@@ -0,0 +1,109 @@
+# Field Layout Designer (FLD)
+
+A native, jQuery-free port of the legacy jQuery `Craft.FieldLayoutDesigner`
+(`packages/craftcms-legacy/cp/src/js/FieldLayoutDesigner.js`) onto the modern
+**`@craftcms/garnish`** package. FLD's own DOM/data work is plain DOM + WeakMaps;
+jQuery (`$`) survives **only** at the boundary with Craft's still-jQuery widgets.
+
+## What changed
+
+- **Class system.** `Garnish.Base.extend({...})` → `class extends Base`,
+  `Garnish.Drag.extend({...})` → `class extends Drag`, `init()` →
+  `constructor()`, `this.base(...)` → `super.method(...)`, `new Garnish.HUD(...)`
+  → `new HUD(...)`. Garnish utilities/constants
+  (`hasAttr`, `getDist`, `hitTest`, `getOffset`, `getOuterWidth/Height`,
+  `firstFocusableElement`, `prefersReducedMotion`,
+  `getUserPreferredAnimationDuration`, `requestAnimationFrame`, `FX_DURATION`,
+  `ESC_KEY`, `RETURN_KEY`, `bod`) are named imports.
+- **All of FLD's own jQuery is now native DOM:**
+  - `$('<div>')` / `$(html)` → `document.createElement` / a `<template>`-based
+    `htmlToElement()` helper.
+  - `.addClass/.removeClass/.hasClass` → `classList`; `.is('.x')`/`.not()` →
+    `matches()`/`filter`.
+  - `.text()` → `textContent`; `.html()` → `innerHTML`; `.val()` → `.value`.
+  - tree ops (`.append/.before/.after/.detach/.remove`,
+    `.children/.find/.closest/.parent/.siblings/.next/.prev`) → native `append`/
+    `before`/`after`/`remove`/`children`/`querySelector(All)`/`closest`/
+    `parentElement`/`*ElementSibling`. jQuery `.children(sel)` becomes
+    `querySelectorAll(':scope > sel')`; `.find(sel)` becomes the bare
+    `querySelectorAll(sel)`.
+  - `.attr/.removeAttr` → `get/set/removeAttribute`; `.prop` → property;
+    `.css()` → `.style`; `.offset()`/`.outerHeight()` → `getOffset`/
+    `getOuterHeight` (and `clientHeight`-based content height where the legacy
+    used `.height()`).
+  - `.each` → `for...of`; `.toArray()` → the native array directly.
+  - `.animate()` / Velocity → the **Web Animations API** (`el.animate(...)`),
+    gated on `prefers-reduced-motion`.
+- **`.data()` is gone** (see below).
+- **Garnish `Drag` interop:** the parent-owned `$items`, `$draggee`, and
+  `helpers` are already native `Element[]`/`HTMLElement[]`, so the `$(...)`
+  wrappers the first port put around them were removed — they're used as native
+  arrays/elements directly. FLD's own `$insertion`/`$caboose` are native too
+  (`HTMLElement | null` / `HTMLElement[]`).
+
+## How `.data()` was replaced
+
+- **Object back-references** (legacy `$.data` cache) → module-level `WeakMap`s in
+  `support.ts`, mirroring how `@craftcms/garnish` itself replaced `$.data`:
+  `fldTabData` (`fld-tab`), `fldElementData` (`fld-element`), `hudData` (`hud`,
+  keyed on `hud.$hud`), `cvdData` (`cvd`). The drag midpoints
+  (`$item.data('midpoint')`) use a `WeakMap` local to `drags.ts`.
+- **Plain `data-*` reads** (`uid`, `id`, `attribute`, `default-handle`, `type`,
+  `ui-label`, `library`, `value`) → `element.dataset.*`.
+- **JSON `data-*` reads** (`config`, `preview-options`, `thumb-options`) →
+  `JSON.parse(element.dataset.…)` (jQuery's implicit JSON-parse made explicit).
+
+## What deliberately stays jQuery (Craft seams)
+
+Craft itself is still jQuery, so at these boundaries we call the Craft API and
+immediately unwrap to native (`Craft.ui.x(...)[0]`, `slideout.$container[0]`) or
+pass a `$(nativeEl)` wrapper in where Craft requires one. jQuery is confined to
+the single call:
+
+- **`Craft.Grid`** on `.fld-tabs` — instantiated and fed via `$(...)`
+  (`tabGrid.addItems/removeItems`). _TODO:_ a later pass can replace it with CSS
+  Grid (out of scope here).
+- **`Craft.Listbox`**, **`Craft.SlidePicker`**, **`Craft.SortableCheckboxSelect`**,
+  **`Craft.Slideout` / `Craft.CpScreenSlideout`** — instantiated at the seam;
+  their jQuery `$container` is unwrapped with `[0]` for native DOM work.
+- The **`.disclosureMenu()` jQuery plugin** + `.data('disclosureMenu')`, and
+  `.data('sortableCheckboxSelect')` — Craft stores/reads these via jQuery.
+- **`slideout.$container.serialize()`** (jQuery-only form serialize) and the
+  `Craft.ui.addErrorsToField`/`clearErrorsFromField` error path, which require
+  jQuery fields.
+- Plain (non-jQuery) Craft calls — `Craft.t`, `Craft.sendActionRequest`,
+  `Craft.cp.*`, `Craft.escapeHtml`, `Craft.uuid`, `Craft.appendHead/BodyHtml`,
+  `Craft.initUiElements` — are left as-is.
+
+The module still assigns `window.Craft.FieldLayoutDesigner` (plus `.Tab`,
+`.Element`, `.CardViewDesigner`, `.BaseDrag`, `.TabDrag`, `.ElementDrag`) so the
+existing PHP `registerJs("new Craft.FieldLayoutDesigner('#id', settings)")` keeps
+working unchanged.
+
+## Porting note: the "fade in place" drag branch
+
+The legacy "fade the draggee in place" branch of `BaseDrag.onDragStop` relied on
+`Drag._showDraggee` (private in modern Garnish) and the jQuery Velocity plugin.
+It's replicated FLD-locally via `_showDraggeeFallback()` + a small `_fade()`
+helper built on the **Web Animations API** (reduced-motion gated), with no change
+to the `@craftcms/garnish` package.
+
+## Files
+
+- `FieldLayoutDesigner.ts` — the main designer class (+ static `defaults` /
+  `createSlideout`).
+- `Tab.ts` — a tab.
+- `Element.ts` — a layout element (field / UI element).
+- `CardViewDesigner.ts` — the card view designer.
+- `drags.ts` — `BaseDrag` / `TabDrag` / `ElementDrag`.
+- `support.ts` — the `.data()`-replacement WeakMaps and the `htmlToElement` /
+  `firstFocusableInSiblings` DOM helpers.
+- `index.ts` — wires the sub-classes onto the constructor and assigns
+  `window.Craft.FieldLayoutDesigner`. Imported from `resources/js/cp.ts`.
+- `types.ts` — settings + config types.
+
+## Deferred
+
+Behavioral/browser verification (rendering the FLD in the CP and exercising
+tabs, drag-sort, the field-library HUD, settings HUDs, and the card view
+designer) is left to manual testing.
diff --git a/resources/js/modules/field-layout-designer/Tab.ts b/resources/js/modules/field-layout-designer/Tab.ts
new file mode 100644
index 00000000000..d9a64b8d7d7
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/Tab.ts
@@ -0,0 +1,411 @@
+import {Base, HUD} from '@craftcms/garnish';
+import {FieldLayoutDesigner} from './FieldLayoutDesigner';
+import {Element as FldElement} from './Element';
+import {
+  fldTabData,
+  fldElementData,
+  hudData,
+  firstFocusableInSiblings,
+} from './support';
+
+declare const Craft: any;
+declare const $: any;
+
+/**
+ * A single tab within the {@link FieldLayoutDesigner}. Native DOM port of the
+ * legacy `Craft.FieldLayoutDesigner.Tab`. jQuery survives only at the Craft
+ * seams (`Craft.Grid`, the `.disclosureMenu()` plugin, `Craft.Slideout`).
+ */
+export class Tab extends Base {
+  designer: FieldLayoutDesigner;
+  uid: any = null;
+  $container: any = null;
+  $addBtn: any = null;
+  $actionBtn: any = null;
+  slideout: any = null;
+  settingsNamespace: any = null;
+  destroyed = false;
+
+  constructor(designer: FieldLayoutDesigner, $container: any) {
+    super();
+    this.designer = designer;
+    this.$container = $container;
+    fldTabData.set(this.$container, this);
+    this.uid = this.$container.dataset.uid;
+
+    // New tab?
+    if (!this.uid) {
+      this.uid = Craft.uuid();
+      this.config = {
+        uid: this.uid,
+        name:
+          this.$container.querySelector('.tabs .tab .fld-tab__name')
+            ?.textContent ?? '',
+        elements: [],
+      };
+    }
+
+    if (this.designer.settings!.customizableTabs) {
+      this.createMenu();
+    }
+
+    // initialize the elements
+    const $tabContent = this.$container.querySelector(
+      ':scope > .fld-tabcontent'
+    );
+
+    this.addListener($tabContent, 'resize', () => {
+      this.designer.tabGrid.refreshCols(true);
+    });
+
+    this.$addBtn = $tabContent.querySelector(':scope > .fld-add-btn');
+
+    const hud = new HUD(this.$addBtn, {
+      hudClass: 'hud fld-library-hud',
+      listenToMainResize: false,
+      showOnInit: false,
+      orientations: ['right', 'bottom', 'left'],
+    });
+    // The legacy HUD stored itself via jQuery `.data('hud', this)`; mirror that
+    // with the FLD WeakMap so `designer.getActiveHud()` can find it.
+    hudData.set(hud.$hud!, hud);
+    hud.on('show', () => {
+      hud.$main!.appendChild(this.designer.$libraryContainer);
+      this.designer.libraryPicker?.select(0);
+      this.designer.$fieldSearch.focus();
+      this.designer.clearSearch();
+      this.designer.$fieldLibrary.scrollTop = 0;
+    });
+    hud.on('hide', () => {
+      this.$addBtn.focus();
+    });
+
+    this.addListener(this.$addBtn, 'activate', () => {
+      hud.show();
+    });
+
+    const $elements = (
+      Array.from($tabContent.children) as HTMLElement[]
+    ).filter((el) => el !== this.$addBtn);
+
+    for (const el of $elements) {
+      this.initElement(el);
+    }
+  }
+
+  createMenu(): void {
+    const $tab = this.$container.querySelector('.tabs .tab');
+    const menuId = `actionmenu${Math.floor(Math.random() * 1000000)}`;
+    const $btn = document.createElement('button');
+    $btn.setAttribute('type', 'button');
+    $btn.className = 'btn action-btn';
+    $btn.setAttribute('data-disclosure-trigger', 'true');
+    $btn.setAttribute('aria-controls', menuId);
+    $btn.setAttribute('aria-haspopup', 'true');
+    $btn.setAttribute('aria-label', Craft.t('app', 'Actions'));
+    $btn.setAttribute('title', Craft.t('app', 'Actions'));
+    if (this.designer.settings!.readOnly) {
+      $btn.disabled = true;
+    }
+    $tab.appendChild($btn);
+
+    const $menu = document.createElement('div');
+    $menu.id = menuId;
+    $menu.className = 'menu menu--disclosure';
+    $menu.setAttribute('data-disclosure-menu', 'true');
+    $tab.appendChild($menu);
+
+    // The `.disclosureMenu()` jQuery plugin is a Craft seam.
+    const disclosureMenu = $($btn).disclosureMenu().data('disclosureMenu');
+
+    disclosureMenu.addItem(
+      {
+        label: Craft.t('app', 'Settings'),
+        icon: async () => await Craft.ui.icon('gear'),
+        onActivate: () => {
+          this.createSettings();
+        },
+      },
+      disclosureMenu.addGroup()
+    );
+
+    const moveUl = disclosureMenu.addGroup();
+    const moveLeftBtn = disclosureMenu.addItem(
+      {
+        label:
+          Craft.orientation === 'ltr'
+            ? Craft.t('app', 'Move to the left')
+            : Craft.t('app', 'Move to the right'),
+        icon: async () =>
+          await Craft.ui.icon(
+            Craft.orientation === 'ltr' ? 'arrow-left' : 'arrow-right'
+          ),
+        onActivate: () => {
+          this.moveLeft();
+        },
+      },
+      moveUl
+    );
+
+    const moveRightBtn = disclosureMenu.addItem(
+      {
+        label:
+          Craft.orientation === 'ltr'
+            ? Craft.t('app', 'Move to the right')
+            : Craft.t('app', 'Move to the left'),
+        icon: async () =>
+          await Craft.ui.icon(
+            Craft.orientation === 'ltr' ? 'arrow-right' : 'arrow-left'
+          ),
+        onActivate: () => {
+          this.moveRight();
+        },
+      },
+      moveUl
+    );
+
+    disclosureMenu.addItem(
+      {
+        label: Craft.t('app', 'Remove'),
+        icon: async () => await Craft.ui.icon('xmark'),
+        destructive: true,
+        onActivate: () => {
+          this.destroy();
+        },
+      },
+      disclosureMenu.addGroup()
+    );
+
+    disclosureMenu.on('show', () => {
+      const prev = this.$container.previousElementSibling;
+      const next = this.$container.nextElementSibling;
+      disclosureMenu.toggleItem(
+        moveLeftBtn,
+        !!(prev && prev.matches('.fld-tab'))
+      );
+      disclosureMenu.toggleItem(
+        moveRightBtn,
+        !!(next && next.matches('.fld-tab'))
+      );
+    });
+  }
+
+  async createSettings(): Promise<void> {
+    let data;
+    try {
+      const response = await Craft.sendActionRequest(
+        'POST',
+        'fields/render-layout-component-settings',
+        {
+          data: {
+            uid: this.uid,
+            layoutConfig: this.designer.config,
+            elementType: this.designer.settings!.elementType,
+          },
+        }
+      );
+      data = response.data;
+    } catch (e: any) {
+      Craft.cp.displayError(e?.response?.data?.message);
+      throw e;
+    }
+
+    this.settingsNamespace = data.namespace;
+    this.slideout = await FieldLayoutDesigner.createSlideout(data, null, {
+      triggerElement: this.$actionBtn,
+    });
+
+    // slideout.$container is a Craft jQuery object; bind on the native form.
+    this.addListener(this.slideout.$container[0], 'submit', (ev: any) => {
+      ev.preventDefault();
+      this.applySettings();
+    });
+    this.slideout.on('close', () => {
+      this.slideout.destroy();
+      this.slideout = null;
+    });
+  }
+
+  applySettings(): void {
+    const $container = this.slideout.$container[0];
+    const $nameInput = $container.querySelector('[name$="[name]"]');
+    if (!$nameInput?.value) {
+      Craft.cp.displayError(Craft.t('app', 'You must specify a tab name.'));
+      return;
+    }
+
+    // update the UI
+    const $submitBtn = $container.querySelector('button[type=submit]');
+    $submitBtn?.classList.add('loading');
+
+    const config = Object.assign({}, this.config);
+    delete config.elements;
+
+    Craft.sendActionRequest('POST', 'fields/apply-layout-tab-settings', {
+      data: {
+        uid: this.uid,
+        layoutConfig: this.designer.config,
+        elementType: this.designer.settings!.elementType,
+        config,
+        settingsNamespace: this.settingsNamespace,
+        // .serialize() is a jQuery-only form helper — keep it at the seam.
+        settings: this.slideout.$container.serialize(),
+      },
+    })
+      .then((response: any) => {
+        this.updateConfig((config) =>
+          Object.assign(response.data.config, {elements: config.elements})
+        );
+        const $label = this.$container.querySelector('.tabs .tab');
+        const $actionBtn = $label.querySelector(':scope > button');
+        $actionBtn?.remove();
+        $label.innerHTML = response.data.labelHtml;
+        if ($actionBtn) {
+          $label.appendChild($actionBtn);
+        }
+        this.slideout.close();
+      })
+      .catch((e: any) => {
+        Craft.cp.displayError();
+        console.error(e);
+      })
+      .finally(() => {
+        $submitBtn?.classList.remove('loading');
+        this.slideout.close();
+      });
+  }
+
+  moveLeft(): void {
+    const $prev = this.$container.previousElementSibling;
+    if ($prev && $prev.matches('.fld-tab')) {
+      $prev.before(this.$container);
+      this.updatePositionInConfig();
+    }
+  }
+
+  moveRight(): void {
+    const $next = this.$container.nextElementSibling;
+    if ($next && $next.matches('.fld-tab')) {
+      $next.after(this.$container);
+      this.updatePositionInConfig();
+    }
+  }
+
+  initElement($element: any): FldElement {
+    return new FldElement(this, $element);
+  }
+
+  get index(): number {
+    return this.designer.config.tabs.findIndex((c: any) => c.uid === this.uid);
+  }
+
+  get config(): any {
+    if (!this.uid) {
+      throw 'Tab is missing its UID';
+    }
+    let config = this.designer.config.tabs.find((c: any) => c.uid === this.uid);
+    if (!config) {
+      config = {
+        uid: this.uid,
+        elements: [],
+      };
+      this.config = config;
+    }
+    return config;
+  }
+
+  set config(config: any) {
+    if (this.destroyed) {
+      return;
+    }
+
+    // Is the name changing?
+    if (config.name && config.name !== this.config.name) {
+      const $name = this.$container.querySelector('.tabs .tab .fld-tab__name');
+      if ($name) {
+        $name.textContent = config.name;
+      }
+    }
+
+    const designerConfig = this.designer.config;
+    const index = this.index;
+    if (index !== -1) {
+      designerConfig.tabs[index] = config;
+    } else {
+      const siblings = Array.from(
+        this.$container.parentElement.querySelectorAll(':scope > .fld-tab')
+      );
+      const newIndex = siblings.indexOf(this.$container);
+      designerConfig.tabs.splice(newIndex, 0, config);
+    }
+    this.designer.config = designerConfig;
+  }
+
+  updateConfig(callback: (config: any) => any): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    const config = callback(this.config);
+    if (config !== false) {
+      this.config = config;
+    }
+  }
+
+  updatePositionInConfig(): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.designer.updateConfig((config) => {
+      const tabConfig = this.config;
+      const oldIndex = this.index;
+      const siblings = Array.from(
+        this.$container.parentElement.querySelectorAll(':scope > .fld-tab')
+      );
+      const newIndex = siblings.indexOf(this.$container);
+      if (oldIndex !== -1) {
+        config.tabs.splice(oldIndex, 1);
+      }
+      config.tabs.splice(newIndex, 0, tabConfig);
+      return config;
+    });
+  }
+
+  override destroy(): void {
+    if (this.destroyed) {
+      return;
+    }
+
+    this.destroyed = true;
+
+    this.designer.updateConfig((config) => {
+      const index = this.index;
+      if (index === -1) {
+        return false;
+      }
+      config.tabs.splice(index, 1);
+      return config;
+    });
+
+    // First destroy the tab's elements
+    this.$container
+      .querySelectorAll('.fld-element')
+      .forEach((el: HTMLElement) => fldElementData.get(el)?.destroy());
+
+    // Set focus to the closest tab's first focusable element
+    const $focusElement = firstFocusableInSiblings(this.$container);
+    if ($focusElement) {
+      $focusElement.focus();
+    } else {
+      this.designer.$newTabBtn.focus();
+    }
+
+    this.designer.tabGrid.removeItems($(this.$container));
+    this.designer.tabDrag!.removeItems(this.$container);
+    this.$container.remove();
+    this.designer.refreshSelectedFields();
+
+    super.destroy();
+  }
+}
diff --git a/resources/js/modules/field-layout-designer/drags.ts b/resources/js/modules/field-layout-designer/drags.ts
new file mode 100644
index 00000000000..6d02b6fa20d
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/drags.ts
@@ -0,0 +1,598 @@
+import {
+  Drag,
+  FX_DURATION,
+  bod,
+  getDist,
+  getOffset,
+  getOuterHeight,
+  getOuterWidth,
+  getUserPreferredAnimationDuration,
+  hasAttr,
+  hitTest,
+  prefersReducedMotion,
+} from '@craftcms/garnish';
+import {fldTabData, fldElementData} from './support';
+import type {FieldLayoutDesigner} from './FieldLayoutDesigner';
+
+// jQuery (`$`) survives only at the Craft.Grid seam (`tabGrid.addItems/removeItems`
+// require jQuery). All other DOM work here is native.
+declare const $: any;
+
+/**
+ * Drag-sort logic for tabs and elements. Native DOM port of the legacy
+ * `Craft.FieldLayoutDesigner.BaseDrag` / `.TabDrag` / `.ElementDrag` onto the
+ * modern `@craftcms/garnish` `Drag`.
+ *
+ * The parent-owned `$items`, `$draggee`, and `helpers` are already native
+ * `Element[]`/`HTMLElement[]` arrays (not jQuery collections), so the array math
+ * uses {@link union}/{@link without}/`filter`. FLD's own `$insertion`/`$caboose`
+ * are native elements too.
+ */
+
+/** Coerce an array / element / null into a native `Element[]`. */
+function toEls(x: any): Element[] {
+  if (x == null) {
+    return [];
+  }
+  if (Array.isArray(x)) {
+    return x;
+  }
+  return [x];
+}
+
+/** Union of a native array with anything coercible, deduped (legacy `$().add()`). */
+function union(a: Element[], b: any): Element[] {
+  const set = new Set<Element>(a);
+  for (const el of toEls(b)) {
+    set.add(el);
+  }
+  return [...set];
+}
+
+/** `a` minus anything coercible (legacy `$items.not(b)`). */
+function without(a: Element[], b: any): Element[] {
+  const remove = new Set<Element>(toEls(b));
+  return a.filter((el) => !remove.has(el));
+}
+
+/** jQuery `.height()` — content-box height (excludes padding/border). */
+function getContentHeight(el: HTMLElement): number {
+  const cs = getComputedStyle(el);
+  return (
+    el.clientHeight -
+    parseFloat(cs.paddingTop || '0') -
+    parseFloat(cs.paddingBottom || '0')
+  );
+}
+
+interface Midpoint {
+  left: number;
+  top: number;
+}
+
+/** Native replacement for the legacy `$item.data('midpoint', …)`. */
+const midpointData = new WeakMap<Element, Midpoint>();
+
+export class BaseDrag extends Drag {
+  designer: FieldLayoutDesigner;
+  $insertion: HTMLElement | null = null;
+  showingInsertion = false;
+  $caboose: HTMLElement[] = [];
+
+  /**
+   * Constructor — `super(null, settings)` first (we can't reference
+   * `this.designer` before `super()`), then resolve the initial item set.
+   */
+  constructor(designer: FieldLayoutDesigner, settings?: any) {
+    super(null, settings);
+    this.designer = designer;
+    this.addItems(this.findItems());
+  }
+
+  /** Overridden by subclasses. */
+  findItems(): any {
+    return [];
+  }
+
+  /** Overridden by subclasses. */
+  createInsertion(): HTMLElement | null {
+    return null;
+  }
+
+  /** Overridden by subclasses. */
+  createCaboose(): HTMLElement[] {
+    return [];
+  }
+
+  /**
+   * On Drag Start
+   */
+  override onDragStart(): void {
+    super.onDragStart();
+
+    // Create the insertion
+    this.$insertion = this.createInsertion();
+
+    // Add the caboose
+    this.$caboose = this.createCaboose();
+    this.$items = union(this.$items, this.$caboose);
+
+    bod.classList.add('dragging');
+  }
+
+  removeCaboose(): void {
+    this.$items = without(this.$items, this.$caboose);
+    this.$caboose.forEach((el) => el.remove());
+  }
+
+  swapDraggeeWithInsertion(): void {
+    this.$draggee[0]!.before(this.$insertion!);
+    this.$draggee.forEach((el) => el.remove());
+    this.$items = union(without(this.$items, this.$draggee), this.$insertion);
+    this.showingInsertion = true;
+  }
+
+  swapInsertionWithDraggee(): void {
+    this.$insertion!.replaceWith(...this.$draggee);
+    this.$items = union(without(this.$items, this.$insertion), this.$draggee);
+    this.showingInsertion = false;
+  }
+
+  /**
+   * Sets the item midpoints up front so we don't have to keep checking on every mouse move
+   */
+  setMidpoints(): void {
+    for (const item of this.$items as HTMLElement[]) {
+      // Skip library elements
+      if (item.classList.contains('unused')) {
+        continue;
+      }
+
+      const offset = getOffset(item);
+      midpointData.set(item, {
+        left: offset.left + getOuterWidth(item) / 2,
+        top: offset.top + getOuterHeight(item) / 2,
+      });
+    }
+  }
+
+  /**
+   * Returns the closest item to the cursor.
+   */
+  getClosestItem(): Element | null {
+    let closestItem: Element | null = null;
+    let closestItemMouseDiff: number | null = null;
+
+    for (const item of this.$items) {
+      const midpoint = midpointData.get(item);
+      if (!midpoint) {
+        continue;
+      }
+
+      const mouseDiff = getDist(
+        midpoint.left,
+        midpoint.top,
+        this.mouseX!,
+        this.mouseY!
+      );
+
+      if (closestItem === null || mouseDiff < closestItemMouseDiff!) {
+        closestItem = item;
+        closestItemMouseDiff = mouseDiff;
+      }
+    }
+
+    return closestItem;
+  }
+
+  checkForNewClosestItem(): void {
+    // Is there a new closest item?
+    const closestItem = this.getClosestItem();
+
+    if (closestItem === this.$insertion) {
+      return;
+    }
+
+    if (closestItem) {
+      if (
+        this.showingInsertion &&
+        this.$items.indexOf(this.$insertion!) <
+          this.$items.indexOf(closestItem) &&
+        !this.$caboose.includes(closestItem as HTMLElement)
+      ) {
+        closestItem.after(this.$insertion!);
+      } else {
+        closestItem.before(this.$insertion!);
+      }
+    }
+
+    // we only want to do it all if there's at least one tab in the layout
+    if (this.designer.tabGrid.$items.length > 0) {
+      this.$items = union(this.$items, this.$insertion);
+      this.showingInsertion = true;
+      this.setMidpoints();
+    }
+  }
+
+  /**
+   * On Drag Stop
+   */
+  override onDragStop(): void {
+    if (this.showingInsertion) {
+      this.swapInsertionWithDraggee();
+    }
+
+    this.removeCaboose();
+
+    // return the helpers to the draggees
+    const first = this.$draggee[0];
+    const offset = first ? getOffset(first) : null;
+    if (!offset || (offset.top === 0 && offset.left === 0)) {
+      for (const el of this.$draggee) {
+        el.style.display = this.draggeeDisplay ?? '';
+        el.style.visibility = 'visible';
+        this._fade(el, 0, 1);
+      }
+      const helper = this.helpers[0];
+      if (helper) {
+        this._fade(helper, 1, 0, () => {
+          this._showDraggeeFallback();
+        });
+      } else {
+        this._showDraggeeFallback();
+      }
+    } else {
+      this.returnHelpersToDraggees();
+    }
+
+    super.onDragStop();
+
+    bod.classList.remove('dragging');
+  }
+
+  /**
+   * Opacity tween via the Web Animations API (reduced-motion gated), replacing
+   * the legacy jQuery `.animate({opacity})`. Runs `onDone` when it lands.
+   */
+  private _fade(
+    el: HTMLElement,
+    from: number,
+    to: number,
+    onDone?: () => void
+  ): void {
+    el.style.opacity = String(to);
+    if (prefersReducedMotion() || typeof el.animate !== 'function') {
+      onDone?.();
+      return;
+    }
+    const anim = el.animate([{opacity: from}, {opacity: to}], {
+      duration: getUserPreferredAnimationDuration(FX_DURATION),
+      fill: 'forwards',
+    });
+    if (onDone) {
+      anim.addEventListener('finish', onDone, {once: true});
+      anim.addEventListener('cancel', onDone, {once: true});
+    }
+  }
+
+  /**
+   * Replicates the modern (private) `Drag._showDraggee` for the legacy
+   * "fade in place" branch above: remove the helpers, restore the draggee(s),
+   * then fire the return hook.
+   */
+  private _showDraggeeFallback(): void {
+    for (const helper of this.helpers) {
+      helper.remove();
+    }
+    this.helpers = [];
+
+    const hideDraggee = (this.settings as any)?.hideDraggee;
+    this.$draggee.forEach((el) => {
+      el.style.display = this.draggeeDisplay ?? '';
+      el.style.visibility = hideDraggee ? 'hidden' : '';
+    });
+
+    this.onReturnHelpersToDraggees();
+  }
+}
+
+export class TabDrag extends BaseDrag {
+  /**
+   * Constructor
+   */
+  constructor(designer: FieldLayoutDesigner) {
+    super(designer, {
+      handle: '.tab',
+    });
+  }
+
+  override findItems(): any {
+    return Array.from(
+      this.designer.$tabContainer.querySelectorAll(':scope > div.fld-tab')
+    );
+  }
+
+  /**
+   * On Drag Start
+   */
+  override onDragStart(): void {
+    super.onDragStart();
+    this.swapDraggeeWithInsertion();
+    this.setMidpoints();
+  }
+
+  override swapDraggeeWithInsertion(): void {
+    super.swapDraggeeWithInsertion();
+    this.designer.tabGrid.removeItems($(this.$draggee));
+    this.designer.tabGrid.addItems($(this.$insertion));
+  }
+
+  override swapInsertionWithDraggee(): void {
+    super.swapInsertionWithDraggee();
+    this.designer.tabGrid.removeItems($(this.$insertion));
+    this.designer.tabGrid.addItems($(this.$draggee));
+  }
+
+  /**
+   * On Drag
+   */
+  override onDrag(): void {
+    this.checkForNewClosestItem();
+    super.onDrag();
+  }
+
+  /**
+   * On Drag Stop
+   */
+  override onDragStop(): void {
+    super.onDragStop();
+
+    // "show" the tab, but make it invisible
+    for (const el of this.$draggee) {
+      el.style.display = this.draggeeDisplay ?? '';
+      el.style.visibility = 'hidden';
+    }
+
+    fldTabData.get(this.$draggee[0]!)?.updatePositionInConfig();
+  }
+
+  /**
+   * Creates the caboose
+   */
+  override createCaboose(): HTMLElement[] {
+    const $caboose = document.createElement('div');
+    $caboose.className = 'fld-tab fld-tab-caboose';
+    this.designer.$tabContainer.appendChild($caboose);
+    this.designer.tabGrid.addItems($($caboose));
+    return [$caboose];
+  }
+
+  /**
+   * Removes the caboose
+   */
+  override removeCaboose(): void {
+    super.removeCaboose();
+    this.designer.tabGrid.removeItems($(this.$caboose));
+  }
+
+  /**
+   * Creates the insertion
+   */
+  override createInsertion(): HTMLElement {
+    const $draggee = this.$draggee[0]!;
+    const $tab = $draggee.querySelector('.tab') as HTMLElement;
+    const $tabContent = $draggee.querySelector(
+      '.fld-tabcontent'
+    ) as HTMLElement;
+
+    const template = document.createElement('template');
+    template.innerHTML = `
+<div class="fld-tab fld-insertion" style="height: ${getContentHeight(
+      $draggee
+    )}px;">
+  <div class="tabs"><div class="tab sel draggable" style="width: ${getOuterWidth(
+    $tab
+  )}px; height: ${getOuterHeight($tab) + 2}px;"></div></div>
+  <div class="fld-tabcontent" style="height: ${
+    getContentHeight($tabContent) - 2
+  }px;"></div>
+</div>
+`.trim();
+    return template.content.firstElementChild as HTMLElement;
+  }
+}
+
+export class ElementDrag extends BaseDrag {
+  draggingLibraryElement = false;
+  draggingField = false;
+  draggingMultiInstanceElement = false;
+  originalTab: any = null;
+
+  /**
+   * On Drag Start
+   */
+  override onDragStart(): void {
+    super.onDragStart();
+
+    const $draggee = this.$draggee[0]!;
+
+    // Are we dragging an element from the library?
+    this.draggingLibraryElement = $draggee.classList.contains('unused');
+
+    // Is it a field?
+    this.draggingField = $draggee.classList.contains('fld-field');
+
+    // Can the element have multiple instances?
+    this.draggingMultiInstanceElement = hasAttr(
+      $draggee,
+      'data-is-multi-instance'
+    );
+
+    // keep UI elements visible
+    if (this.draggingLibraryElement && this.draggingMultiInstanceElement) {
+      for (const el of this.$draggee) {
+        el.style.display = this.draggeeDisplay ?? '';
+        el.style.visibility = 'visible';
+      }
+    }
+
+    // Swap the draggee with the insertion if dragging a selected item
+    if (!this.draggingLibraryElement) {
+      const tabEl = $draggee.closest('.fld-tab');
+      this.originalTab = tabEl ? fldTabData.get(tabEl) : null;
+      this.swapDraggeeWithInsertion();
+    } else {
+      this.originalTab = null;
+    }
+
+    this.setMidpoints();
+  }
+
+  /**
+   * On Drag
+   */
+  override onDrag(): void {
+    if (this.isDraggeeMandatory() || this.isHoveringOverTab()) {
+      this.checkForNewClosestItem();
+    } else if (this.showingInsertion) {
+      this.$insertion?.remove();
+      this.$items = without(this.$items, this.$insertion);
+      this.showingInsertion = false;
+      this.setMidpoints();
+    }
+
+    super.onDrag();
+  }
+
+  isDraggeeMandatory(): boolean {
+    return hasAttr(this.$draggee[0]!, 'data-mandatory');
+  }
+
+  isHoveringOverTab(): boolean {
+    for (let i = 0; i < this.designer.tabGrid.$items.length; i++) {
+      if (
+        hitTest(this.mouseX!, this.mouseY!, this.designer.tabGrid.$items.get(i))
+      ) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  override findItems(): any {
+    // Return all of the in-use layout elements. (We'll add the library elements via initLibraryElement().)
+    return Array.from(
+      this.designer.$tabContainer.querySelectorAll('.fld-element')
+    );
+  }
+
+  /**
+   * Creates the caboose
+   */
+  override createCaboose(): HTMLElement[] {
+    const $caboose: HTMLElement[] = [];
+    const $fieldContainers = this.designer.$tabContainer.querySelectorAll(
+      ':scope > .fld-tab > .fld-tabcontent'
+    );
+
+    for (const $fieldContainer of $fieldContainers) {
+      const $div = document.createElement('div');
+      const $addBtn = $fieldContainer.querySelector(':scope > .fld-add-btn');
+      if ($addBtn) {
+        $addBtn.before($div);
+      } else {
+        $fieldContainer.appendChild($div);
+      }
+      $caboose.push($div);
+    }
+
+    return $caboose;
+  }
+
+  /**
+   * Creates the insertion
+   */
+  override createInsertion(): HTMLElement {
+    const $insertion = document.createElement('div');
+    $insertion.className = 'fld-element fld-insertion';
+    $insertion.style.height = `${getOuterHeight(this.$draggee[0]!)}px`;
+    return $insertion;
+  }
+
+  /**
+   * On Drag Stop
+   */
+  override onDragStop(): void {
+    const showingInsertion = this.showingInsertion;
+    if (showingInsertion) {
+      if (this.draggingLibraryElement) {
+        // Clone the element and set this.$draggee to the clone, as if we were dragging that all along
+        this.$draggee = [
+          this.designer.cloneLibraryElementForSelection(this.$draggee[0]),
+        ];
+      }
+    } else if (!this.draggingLibraryElement) {
+      const $draggee = this.$draggee[0]!;
+      const $libraryElement = this.draggingField
+        ? this.designer.$fields.find((el: HTMLElement) =>
+            el.matches(`[data-attribute="${$draggee.dataset.attribute}"]`)
+          )
+        : this.designer.$uiLibraryElements.find((el: HTMLElement) =>
+            el.matches(`[data-type="${$draggee.dataset.type}"]`)
+          );
+
+      if (this.draggingField && $libraryElement) {
+        // show the field in the library
+        $libraryElement.classList.remove('hidden');
+        $libraryElement.closest('.fld-field-group')?.classList.remove('hidden');
+      }
+
+      // Destroy the original element
+      fldElementData.get($draggee)?.destroy();
+
+      // Set this.$draggee to the library element, as if we were dragging that all along
+      this.$draggee = $libraryElement ? [$libraryElement] : [];
+    }
+
+    super.onDragStop();
+
+    for (const el of this.$draggee) {
+      el.style.display = this.draggeeDisplay ?? '';
+      el.style.visibility =
+        this.draggingField || showingInsertion ? 'hidden' : 'visible';
+    }
+
+    if (showingInsertion) {
+      const tabEl = this.$draggee[0]?.closest('.fld-tab');
+      const tab = tabEl ? fldTabData.get(tabEl) : undefined;
+      let element: any;
+
+      if (this.draggingLibraryElement) {
+        element = tab!.initElement(this.$draggee[0]);
+        element.onSelect();
+      } else {
+        element = fldElementData.get(this.$draggee[0]!);
+
+        // New tab?
+        if (tab !== this.originalTab) {
+          const config = element.config;
+
+          this.originalTab.updateConfig((config: any) => {
+            const index = element.index;
+            if (index === -1) {
+              return false;
+            }
+            config.elements.splice(index, 1);
+            return config;
+          });
+
+          element.tab = tab;
+          element.config = config;
+        }
+      }
+
+      element.updatePositionInConfig();
+    }
+  }
+}
diff --git a/resources/js/modules/field-layout-designer/index.ts b/resources/js/modules/field-layout-designer/index.ts
new file mode 100644
index 00000000000..51c99967283
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/index.ts
@@ -0,0 +1,33 @@
+import {FieldLayoutDesigner} from './FieldLayoutDesigner';
+import {Tab} from './Tab';
+import {Element} from './Element';
+import {CardViewDesigner} from './CardViewDesigner';
+import {BaseDrag, TabDrag, ElementDrag} from './drags';
+
+// Re-expose the sub-classes on the constructor, exactly as the legacy bundle
+// did (`Craft.FieldLayoutDesigner.Tab`, `.Element`, `.CardViewDesigner`,
+// `.BaseDrag`, `.TabDrag`, `.ElementDrag`).
+const FLD = FieldLayoutDesigner as any;
+FLD.Tab = Tab;
+FLD.Element = Element;
+FLD.CardViewDesigner = CardViewDesigner;
+FLD.BaseDrag = BaseDrag;
+FLD.TabDrag = TabDrag;
+FLD.ElementDrag = ElementDrag;
+
+// Assign onto the legacy `Craft` global so the PHP-emitted
+// `new Craft.FieldLayoutDesigner("#id", settings)` keeps working unchanged. The
+// `Craft` global is created by the legacy cp bundle; we only assign onto it.
+const craft = (window as any).Craft ?? ((window as any).Craft = {});
+craft.FieldLayoutDesigner = FieldLayoutDesigner;
+
+console.log('hey from the new code');
+export {
+  FieldLayoutDesigner,
+  Tab,
+  Element,
+  CardViewDesigner,
+  BaseDrag,
+  TabDrag,
+  ElementDrag,
+};
diff --git a/resources/js/modules/field-layout-designer/support.ts b/resources/js/modules/field-layout-designer/support.ts
new file mode 100644
index 00000000000..7907fd93cce
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/support.ts
@@ -0,0 +1,56 @@
+import {firstFocusableElement} from '@craftcms/garnish';
+import type {Tab} from './Tab';
+import type {Element as FldElement} from './Element';
+
+/**
+ * Native replacements for the legacy jQuery `$.data()` back-references the FLD
+ * used to stash object instances on DOM nodes. Each key the legacy code stored
+ * (`fld-tab`, `fld-element`, `hud`, `cvd`) becomes a module-level WeakMap keyed
+ * by the element, exactly mirroring how `@craftcms/garnish` replaced `$.data`.
+ *
+ * Simple string/JSON values that lived in `data-*` attributes are NOT here —
+ * those are read straight off `element.dataset` (JSON-parsed where needed).
+ */
+
+/** Legacy `$container.data('fld-tab', tab)` / `.data('fld-tab')`. */
+export const fldTabData = new WeakMap<Element, Tab>();
+
+/** Legacy `$container.data('fld-element', element)` / `.data('fld-element')`. */
+export const fldElementData = new WeakMap<Element, FldElement>();
+
+/** Legacy `$(hud.$hud).data('hud', hud)` — looked up via `getActiveHud()`. */
+export const hudData = new WeakMap<Element, any>();
+
+/** Legacy `$container.data('cvd', cvd)`. */
+export const cvdData = new WeakMap<Element, any>();
+
+/**
+ * Native equivalent of jQuery `$(html)` — parse an HTML string and return its
+ * first element. Uses a `<template>` so any tag (option, tr, …) parses.
+ */
+export function htmlToElement(html: string): HTMLElement {
+  const template = document.createElement('template');
+  template.innerHTML = html.trim();
+  return template.content.firstElementChild as HTMLElement;
+}
+
+/**
+ * Native equivalent of jQuery `$(el).siblings().find(':focusable:first')` — the
+ * first focusable element found among `el`'s siblings' descendants.
+ */
+export function firstFocusableInSiblings(el: Element): HTMLElement | null {
+  const parent = el.parentElement;
+  if (!parent) {
+    return null;
+  }
+  for (const sibling of Array.from(parent.children)) {
+    if (sibling === el) {
+      continue;
+    }
+    const focusable = firstFocusableElement(sibling);
+    if (focusable) {
+      return focusable;
+    }
+  }
+  return null;
+}
diff --git a/resources/js/modules/field-layout-designer/types.ts b/resources/js/modules/field-layout-designer/types.ts
new file mode 100644
index 00000000000..0e0791fa6c4
--- /dev/null
+++ b/resources/js/modules/field-layout-designer/types.ts
@@ -0,0 +1,24 @@
+import type {GarnishBaseSettings} from '@craftcms/garnish';
+
+/**
+ * Settings accepted by {@link FieldLayoutDesigner}. Mirrors the `$jsSettings`
+ * JSON emitted by `src/Cp/FieldLayoutDesigner/FieldLayoutDesigner.php`.
+ */
+export interface FieldLayoutDesignerSettings extends GarnishBaseSettings {
+  elementType: string | null;
+  customizableTabs: boolean;
+  customizableUi: boolean;
+  withCardViewDesigner: boolean;
+  alwaysShowThumbAlignmentBtns: boolean;
+  readOnly: boolean;
+}
+
+/**
+ * The serialized field-layout config that round-trips through the hidden
+ * `input[data-config-input]`. Very dynamic on the PHP side, so kept loose.
+ */
+export interface FieldLayoutConfig {
+  uid?: string;
+  tabs: any[];
+  [key: string]: any;
+}