Update deprecation notice.

It now:

- Links to the built-in JSON parsing functions on MDN (which contain explanations, examples, and links to specs).
- Provides encouragement and rationale to stop using `@github/webauthn-json`.
- Includes useful examples of how to handle the transition, with code that:
  - Loads a fallback only when needed.
  - Avoids top-level `await` (which is well-supported by browsers but still errors in TypeScript unless you specifically configure it).
  - Uses JSDoc comments which ensure that the functions receive the correct types in TypeScript, while still allowing the code to be pasted into vanilla JS.

Author: lgarron

README.md

@@ -1,8 +1,58 @@
-⚠️ ⚠️ ⚠️
+# ⚠️ `@github/webauthn-json` is deprecated ⚠️
 
-WebAuthn-json has been sunset. Now that [all major browsers support WebAuthn](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API#browser_compatibility) we recommend invoking the native APIs
+As of March 2025, stable versions of all major browsers now support the following methods:
 
-⚠️ ⚠️ ⚠️
+- [`PublicKeyCredential.parseCreationOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static)
+- [`PublicKeyCredential.parseRequestOptionsFromJSON(…)`](https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/parseCreationOptionsFromJSON_static)
+
+By design, these are compatible with `@github/webauthn-json` encoding, so you can use them as a drop-in substitute. We strongly recommend doing so, since:
+
+- The browser-native JSON parsing functions are increasingly receiving fields and features (such as user-agent hints and the `prf` extension) that `@github/webauthn-json` will never receive.
+- Removing `@github/webauthn-json` from your codebase will remove code from your authentication pages, reducing load times for your users and reducing the chance you will need to debug issues.
+
+## Fallback (not recommended)
+
+If you need to support older browsers in the short-term, consider loading this library only as a fallback:
+
+```js
+async function register() {
+  const parseCreationOptionsFromJSON =
+    PublicKeyCredential.parseCreationOptionsFromJSON ??
+      /* @type PublicKeyCredential.parseCreationOptionsFromJSON */
+      (await import("@github/webauthn-json/browser-ponyfill")).parseCreationOptionsFromJSON;
+
+  const publicKey = parseCreationOptionsFromJSON({ /* … */ });
+  return navigator.credentials.create({publicKey});
+}
+
+async function authenticate() {
+  const parseRequestOptionsFromJSON =
+    PublicKeyCredential.parseRequestOptionsFromJSON ??
+      /* @type PublicKeyCredential.parseRequestOptionsFromJSON */
+      (await import("@github/webauthn-json/browser-ponyfill")).parseRequestOptionsFromJSON;
+
+  const publicKey = parseRequestOptionsFromJSON({ /* … */ });
+  return navigator.credentials.get({publicKey});
+}
+```
+
+If you think you need such a fallback, consider testing or instrumenting your code to test if this is really needed for the small percentage of affected users.
+
+If you have any other authentication methods available, it is likely that your users will still be able to authenticate without this fallback in place. They will also receive the browser-native functionality the next time rheir browser updates.
+
+<br>
+
+--------
+
+<br>
+
+This project's old README contents are below:
+
+<br>
+
+--------
+
+<br>
 
 # `@github/webauthn-json`