diff --git a/fasthtml/_modidx.py b/fasthtml/_modidx.py
index 412a2a14..79d50440 100644
--- a/fasthtml/_modidx.py
+++ b/fasthtml/_modidx.py
@@ -186,6 +186,38 @@
                                   'fasthtml.jupyter.wait_port_free': ('api/jupyter.html#wait_port_free', 'fasthtml/jupyter.py'),
                                   'fasthtml.jupyter.ws_client': ('api/jupyter.html#ws_client', 'fasthtml/jupyter.py')},
             'fasthtml.live_reload': {},
+            'fasthtml.magickey': { 'fasthtml.magickey.MagicKey': ('api/magickey.html#magickey', 'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.__init__': ('api/magickey.html#magickey.__init__', 'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._do_auth': ('api/magickey.html#magickey._do_auth', 'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._finish_passkey_reg': ( 'api/magickey.html#magickey._finish_passkey_reg',
+                                                                                       'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._logout': ('api/magickey.html#magickey._logout', 'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._request_passkey_auth': ( 'api/magickey.html#magickey._request_passkey_auth',
+                                                                                         'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._request_passkey_reg': ( 'api/magickey.html#magickey._request_passkey_reg',
+                                                                                        'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._send_magic_link': ( 'api/magickey.html#magickey._send_magic_link',
+                                                                                    'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._skip_passkey_reg': ( 'api/magickey.html#magickey._skip_passkey_reg',
+                                                                                     'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._verify_magiclink': ( 'api/magickey.html#magickey._verify_magiclink',
+                                                                                     'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey._verify_passkey_auth': ( 'api/magickey.html#magickey._verify_passkey_auth',
+                                                                                        'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.after_magiclink_verify': ( 'api/magickey.html#magickey.after_magiclink_verify',
+                                                                                          'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.get_auth': ('api/magickey.html#magickey.get_auth', 'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.get_passkey': ( 'api/magickey.html#magickey.get_passkey',
+                                                                               'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.get_user_id': ( 'api/magickey.html#magickey.get_user_id',
+                                                                               'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.has_passkey': ( 'api/magickey.html#magickey.has_passkey',
+                                                                               'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.save_passkey': ( 'api/magickey.html#magickey.save_passkey',
+                                                                                'fasthtml/magickey.py'),
+                                   'fasthtml.magickey.MagicKey.update_passkey': ( 'api/magickey.html#magickey.update_passkey',
+                                                                                  'fasthtml/magickey.py'),
+                                   'fasthtml.magickey._webauthn_js': ('api/magickey.html#_webauthn_js', 'fasthtml/magickey.py')},
             'fasthtml.oauth': { 'fasthtml.oauth.AppleAppClient': ('api/oauth.html#appleappclient', 'fasthtml/oauth.py'),
                                 'fasthtml.oauth.AppleAppClient.__init__': ('api/oauth.html#appleappclient.__init__', 'fasthtml/oauth.py'),
                                 'fasthtml.oauth.AppleAppClient.client_secret': ( 'api/oauth.html#appleappclient.client_secret',
@@ -254,6 +286,19 @@
                                'fasthtml.pico.PicoBusy': ('api/pico.html#picobusy', 'fasthtml/pico.py'),
                                'fasthtml.pico.Search': ('api/pico.html#search', 'fasthtml/pico.py'),
                                'fasthtml.pico.set_pico_cls': ('api/pico.html#set_pico_cls', 'fasthtml/pico.py')},
+            'fasthtml.ratelimit': { 'fasthtml.ratelimit.Limiter': ('api/ratelimit.html#limiter', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.Limiter.__call__': ('api/ratelimit.html#limiter.__call__', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.Limiter.__init__': ('api/ratelimit.html#limiter.__init__', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.TokenBucket': ('api/ratelimit.html#tokenbucket', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.TokenBucket.__init__': ( 'api/ratelimit.html#tokenbucket.__init__',
+                                                                                 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.TokenBucket.__repr__': ( 'api/ratelimit.html#tokenbucket.__repr__',
+                                                                                 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.TokenBucket._prune': ( 'api/ratelimit.html#tokenbucket._prune',
+                                                                               'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.TokenBucket.wait': ('api/ratelimit.html#tokenbucket.wait', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.client_ip': ('api/ratelimit.html#client_ip', 'fasthtml/ratelimit.py'),
+                                    'fasthtml.ratelimit.parse_rate': ('api/ratelimit.html#parse_rate', 'fasthtml/ratelimit.py')},
             'fasthtml.starlette': {},
             'fasthtml.stripe_otp': { 'fasthtml.stripe_otp.Payment': ('explains/stripe.html#payment', 'fasthtml/stripe_otp.py'),
                                      'fasthtml.stripe_otp._search_app': ('explains/stripe.html#_search_app', 'fasthtml/stripe_otp.py'),
diff --git a/fasthtml/magickey.py b/fasthtml/magickey.py
new file mode 100644
index 00000000..92d78b2b
--- /dev/null
+++ b/fasthtml/magickey.py
@@ -0,0 +1,165 @@
+"""Passwordless auth combining magic links and passkeys"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/10_magickey.ipynb.
+
+# %% auto #0
+__all__ = ['MagicKey']
+
+# %% ../nbs/api/10_magickey.ipynb #d3fd43fe
+import secrets, time
+from json import loads
+from urllib.parse import urlparse
+
+from webauthn import generate_authentication_options, generate_registration_options, verify_authentication_response, verify_registration_response, options_to_json
+from webauthn.helpers import base64url_to_bytes, bytes_to_base64url
+from webauthn.helpers.structs import AuthenticatorSelectionCriteria, ResidentKeyRequirement, UserVerificationRequirement
+
+from fastcore.utils import *
+from fastcore.xml import *
+from fastlite import *
+from .basics import *
+from .starlette import *
+from .fastapp import *
+from .ratelimit import *
+
+# %% ../nbs/api/10_magickey.ipynb #03d86e44
+# _origin_kw removed; public_origin / rp_id inlined at call sites
+
+
+# %% ../nbs/api/10_magickey.ipynb #02b50590
+def _webauthn_js(opts, action, callback):
+    return Script("SimpleWebAuthnBrowser.%s({ optionsJSON: %s }).then(r => {"
+        "htmx.ajax('POST', '%s', { values: r });});" % (action, options_to_json(opts), callback))
+
+# %% ../nbs/api/10_magickey.ipynb #032d5010
+class MagicKey:
+    def __init__(self,
+                 app,             # FastHTML app instance
+                 send_email,      # `f(email, magic_url)` — sends the magic link
+                 public_origin,   # Full origin URL, e.g. `https://example.com`
+                 rp_id=None,      # WebAuthn relying party ID (default: hostname from `public_origin`)
+                 rp_name=None,    # WebAuthn relying party display name (default: `rp_id`)
+                 skip=None,       # Routes to skip auth beforeware (default: all MagicKey routes)
+                 login_path='/login',   # Login page route
+                 logout_path='/logout', # Logout route
+                 token_expiry=3600,      # Magic link validity in seconds
+                 email_rate='3/m',       # Per-email rate limit on magic link sends (None to disable)
+                 ip_rate='10/m',         # Per-IP rate limit on magic link sends (None to disable)
+                 webauthn_js=None):      # Script tag or URL for SimpleWebAuthn browser JS (default: jsdelivr CDN)
+        "Passwordless auth combining magic links and passkeys"
+        if not rp_id: rp_id = urlparse(public_origin).hostname
+        self.magiclink_db = {}
+        self._email_bucket = TokenBucket(email_rate) if email_rate else None
+        self._ip_bucket = TokenBucket(ip_rate) if ip_rate else None
+        store_attr()
+        async def _before(req, session):
+            if 'auth' not in req.scope: req.scope['auth'] = session.get('auth')
+            if not req.scope['auth']: return RedirectResponse(login_path, status_code=303)
+        if not skip: skip = [login_path, logout_path, '/finish_passkey_reg', '/send_magic_link', 
+                             '/request_passkey_auth', '/request_passkey_reg', '/setup_passkey',
+                             '/skip_passkey_reg', '/verify_magiclink', '/verify_passkey_auth',]
+        app.before.append(Beforeware(_before, skip=skip))
+        if not webauthn_js: webauthn_js = Script(src='https://cdn.jsdelivr.net/npm/@simplewebauthn/browser@13.1.0/dist/bundle/index.umd.min.js')
+        elif isinstance(webauthn_js, str): webauthn_js = Script(src=webauthn_js)
+        app.hdrs += (webauthn_js,)
+        app.get(logout_path)(self._logout)
+        app.post('/send_magic_link')(self._send_magic_link)
+        app.get('/verify_magiclink')(self._verify_magiclink)
+        app.post('/request_passkey_auth')(self._request_passkey_auth)
+        app.post('/verify_passkey_auth')(self._verify_passkey_auth)
+        app.post('/request_passkey_reg')(self._request_passkey_reg)
+        app.post('/finish_passkey_reg')(self._finish_passkey_reg)
+        app.post('/skip_passkey_reg')(self._skip_passkey_reg)
+
+    def _logout(self, session):
+        session.pop('auth', None)
+        return RedirectResponse(self.login_path, status_code=303)
+
+    def _send_magic_link(self, email: str, req):
+        for bucket,key in ((self._ip_bucket, client_ip(req)), (self._email_bucket, email)):
+            if bucket and (w:=bucket.wait(key)): return Response('Too many requests', status_code=429, headers={'Retry-After': str(int(w)+1)})
+        self.magiclink_db = {k:v for k,v in self.magiclink_db.items() if not v['used'] and time.time() - v['timestamp'] <= self.token_expiry}
+        token = secrets.token_urlsafe(32)
+        self.magiclink_db[token] = dict(email=email, timestamp=time.time(), used=False)
+        magic_url = f'{self.public_origin}/verify_magiclink?token={token}'
+        return self.send_email(email, magic_url)
+
+    def _verify_magiclink(self, token: str, session, req):
+        link = self.magiclink_db.get(token)
+        if not link or link['used'] or time.time() - link['timestamp'] > self.token_expiry:
+            return RedirectResponse(f'{self.login_path}?error=invalid_link', status_code=303)
+        link['used'] = True
+        return self.after_magiclink_verify(link['email'], session, req)
+
+    def _request_passkey_auth(self, session):
+        auth_opts = generate_authentication_options(
+            rp_id=self.rp_id, user_verification=UserVerificationRequirement.REQUIRED)
+        session['auth_challenge'] = bytes_to_base64url(auth_opts.challenge)
+        return _webauthn_js(auth_opts, 'startAuthentication', '/verify_passkey_auth')
+
+    def _verify_passkey_auth(self, response: str, id: str, rawId: str, type: str, session):
+        challenge_b64 = session.pop('auth_challenge', None)
+        if not challenge_b64: return HttpHeader('HX-Redirect', f'{self.login_path}?error=no_challenge')
+        stored = self.get_passkey(id)
+        if not stored: return HttpHeader('HX-Redirect', f'{self.login_path}?error=passkey_not_found')
+        try:
+            res = verify_authentication_response(
+                credential=dict(id=id, rawId=rawId, response=loads(response), type=type),
+                credential_public_key=stored['public_key'], 
+                credential_current_sign_count=stored['sign_count'],
+                expected_challenge=base64url_to_bytes(challenge_b64), 
+                require_user_verification=True,
+                expected_origin=self.public_origin, expected_rp_id=self.rp_id)
+        except Exception: return HttpHeader('HX-Redirect', f'{self.login_path}?error=passkey_failed')
+        self.update_passkey(id, res.new_sign_count)
+        session['auth'] = self.get_user_id(stored['email'])
+        return self._do_auth(session['auth'], session, htmx=True)
+
+    def _request_passkey_reg(self, session):
+        email = session.get('pending_email')
+        if not email: return RedirectResponse(f'{self.login_path}?error=no_pending_reg', status_code=303)
+        opts = generate_registration_options(
+            rp_id=self.rp_id, rp_name=self.rp_name or self.rp_id, user_name=email, 
+            user_id=str(self.get_user_id(email)).encode(), 
+            authenticator_selection=AuthenticatorSelectionCriteria(resident_key=ResidentKeyRequirement.REQUIRED))
+        session['reg_challenge'] = bytes_to_base64url(opts.challenge)
+        return _webauthn_js(opts, 'startRegistration', '/finish_passkey_reg')
+
+    def _finish_passkey_reg(self, response: str, id: str, rawId: str, type: str, session):
+        email = session.pop('pending_email', None)
+        if not email: return RedirectResponse(f'{self.login_path}?error=no_pending_reg', status_code=303)
+        challenge_b64 = session.pop('reg_challenge', None)
+        if not challenge_b64: return RedirectResponse('/setup_passkey?error=no_challenge', status_code=303)
+        try: res = verify_registration_response(credential=dict(id=id, rawId=rawId, response=loads(response), type=type),
+                                                expected_challenge=base64url_to_bytes(challenge_b64),
+                                                require_user_verification=True,
+                                                expected_origin=self.public_origin, expected_rp_id=self.rp_id)
+        except Exception: return RedirectResponse('/setup_passkey?error=reg_failed', status_code=303)
+        self.save_passkey(bytes_to_base64url(res.credential_id), email, res.credential_public_key, res.sign_count)
+        session['auth'] = self.get_user_id(email)
+        return self._do_auth(session['auth'], session, htmx=True)
+
+    def _skip_passkey_reg(self, session):
+        email = session.pop('pending_email', None)
+        if not email: return RedirectResponse(self.login_path, status_code=303)
+        session['auth'] = self.get_user_id(email)
+        return self._do_auth(session['auth'], session, htmx=False)
+
+    def _do_auth(self, user_id, session, htmx=False):
+        url = self.get_auth(user_id, session)
+        if htmx: return HttpHeader('HX-Redirect', url)
+        return RedirectResponse(url, status_code=303)
+
+    def get_auth(self, user_id, session): return '/'
+    def get_user_id(self, email): raise NotImplementedError()
+    def has_passkey(self, email): raise NotImplementedError()
+    def get_passkey(self, credential_id): raise NotImplementedError()
+    def save_passkey(self, credential_id, email, public_key, sign_count): raise NotImplementedError()
+    def update_passkey(self, credential_id, sign_count): raise NotImplementedError()
+
+    def after_magiclink_verify(self, email, session, req):
+        if self.has_passkey(email):
+            session['auth'] = self.get_user_id(email)
+            return self._do_auth(session['auth'], session, htmx=False)
+        session['pending_email'] = email
+        return RedirectResponse('/setup_passkey', status_code=303)
diff --git a/fasthtml/ratelimit.py b/fasthtml/ratelimit.py
new file mode 100644
index 00000000..9c3ded92
--- /dev/null
+++ b/fasthtml/ratelimit.py
@@ -0,0 +1,83 @@
+"""Simple token-bucket rate limiting for FastHTML routes"""
+
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/api/07_ratelimit.ipynb.
+
+# %% auto #0
+__all__ = ['parse_rate', 'TokenBucket', 'client_ip', 'Limiter']
+
+# %% ../nbs/api/07_ratelimit.ipynb #b33aec8a
+import asyncio,re,time
+from contextvars import ContextVar
+from functools import wraps
+from math import ceil
+from typing import Callable
+from starlette.responses import Response
+from fastcore.utils import *
+
+# %% ../nbs/api/07_ratelimit.ipynb #1078d10b
+_units = dict(s=1, m=60, h=3600, d=86400)
+
+def parse_rate(s):
+    "Parse rate string like `'5/m'`, `'1 per day'`, `'100/2h'`"
+    m = re.match(r'(\d+)\s*(?:/|per)\s*(\d+)?\s*([smhd])', s, re.I)
+    if not m: raise ValueError(f"Invalid rate: {s}")
+    n,mult,unit = m.groups()
+    return int(n), _units[unit.lower()] * int(mult or 1)
+
+# %% ../nbs/api/07_ratelimit.ipynb #7b28079a
+class TokenBucket:
+    "Token-bucket rate limiter"
+    def __init__(self,
+                 max_reqs:str|int,     # Rate string ('5/m') or max requests per window
+                 window_secs:int=None  # Window in seconds (required if `max_reqs` is int)
+                ):
+        if window_secs is None: max_reqs,window_secs = parse_rate(max_reqs)
+        store_attr()
+        self.rate = max_reqs / window_secs
+        self.buckets = {}
+    def __repr__(self): return f'TokenBucket({self.max_reqs}, {self.window_secs})'
+
+    def _prune(self):
+        cutoff = time.time() - self.window_secs
+        self.buckets = {k:(t,ts) for k,(t,ts) in self.buckets.items() if ts > cutoff}
+    def wait(self, key):
+        "Return 0 if allowed, else seconds to wait"
+        self._prune()
+        now = time.time()
+        tokens, last = self.buckets.get(key, (self.max_reqs, now))
+        tokens = min(self.max_reqs, tokens + (now - last) * self.rate)
+        if tokens < 1: return (1 - tokens) / self.rate
+        self.buckets[key] = (tokens - 1, now)
+        return 0
+
+# %% ../nbs/api/07_ratelimit.ipynb #69b0fb44
+def client_ip(req, **kwargs):
+    "Get client IP from `X-Forwarded-For` header, falling back to `req.client.host`"
+    return req.headers.get('x-forwarded-for', '').split(',')[0].strip() or (req.client and req.client.host) or ''
+
+# %% ../nbs/api/07_ratelimit.ipynb #75b5b395
+class Limiter:
+    "Rate limiter for FastHTML routes"
+    def __init__(self, app):
+        self._req_var = ContextVar('limiter_req')
+        async def _store(req): self._req_var.set(req)
+        app.before.insert(0, _store)
+
+    def __call__(self,
+                 rate:str|tuple,            # Rate string ('5/m') or (max_reqs, window_secs) tuple
+                 key:str|Callable=client_ip, # Key to limit by: route param name, or callable(req, **kwargs)
+                 on_limit:Callable=None     # Optional callback(wait_secs) to return custom response on 429
+                ):
+        "Rate limit decorator: `@limiter('5/m')`"
+        bucket = TokenBucket(*rate) if isinstance(rate, tuple) else TokenBucket(rate)
+        def decorator(f):
+            @wraps(f)
+            async def wrapper(*args, **kwargs):
+                req = self._req_var.get()
+                k = key(req, **kwargs) if callable(key) else str(kwargs.get(key, ''))
+                if w:=bucket.wait(k):
+                    if on_limit: return on_limit(w)
+                    return Response('Too many requests', status_code=429, headers={'Retry-After': str(ceil(w))})
+                return await maybe_await(f(*args, **kwargs))
+            return wrapper
+        return decorator
diff --git a/nbs/api/00_core.ipynb b/nbs/api/00_core.ipynb
index 5232d7e4..e4bfb90d 100644
--- a/nbs/api/00_core.ipynb
+++ b/nbs/api/00_core.ipynb
@@ -136,9 +136,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "datetime"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -159,9 +157,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "bool"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -196,9 +192,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -268,9 +262,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "HtmxHeaders"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -437,9 +429,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -475,9 +465,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "HttpHeader"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -512,9 +500,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "dict"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -537,9 +523,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "dict"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -760,9 +744,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -855,9 +837,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "Foo"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -972,9 +952,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2120,9 +2098,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2187,9 +2163,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2214,9 +2188,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2314,9 +2286,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2383,9 +2353,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2439,9 +2407,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2481,9 +2447,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2508,9 +2472,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2534,9 +2496,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2591,9 +2551,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2691,9 +2649,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2740,9 +2696,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2930,9 +2884,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -2960,9 +2912,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -3287,9 +3237,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "_mk_locfunc.<locals>._lf"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -3941,9 +3889,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "_mk_locfunc.<locals>._lf"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -4396,9 +4342,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "_mk_locfunc.<locals>._lf"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
diff --git a/nbs/api/01_components.ipynb b/nbs/api/01_components.ipynb
index 5f8943f8..31bf97d7 100644
--- a/nbs/api/01_components.ipynb
+++ b/nbs/api/01_components.ipynb
@@ -94,9 +94,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -164,9 +162,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -199,9 +195,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -234,9 +228,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "str"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -358,9 +350,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -389,9 +379,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -420,9 +408,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -461,9 +447,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -508,9 +492,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -539,9 +521,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -600,9 +580,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -646,9 +624,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -679,9 +655,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -711,9 +685,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -963,9 +935,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1006,9 +976,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1050,9 +1018,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "FT"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1099,9 +1065,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "TodoItem"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1146,9 +1110,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "list"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1309,9 +1271,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "Markdown"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
@@ -1374,9 +1334,7 @@
       ]
      },
      "execution_count": null,
-     "metadata": {
-      "__type": "Markdown"
-     },
+     "metadata": {},
      "output_type": "execute_result"
     }
    ],
diff --git a/nbs/api/07_ratelimit.ipynb b/nbs/api/07_ratelimit.ipynb
new file mode 100644
index 00000000..e62b8b42
--- /dev/null
+++ b/nbs/api/07_ratelimit.ipynb
@@ -0,0 +1,682 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6de889b6",
+   "metadata": {},
+   "source": [
+    "# Rate Limiting\n",
+    "> Simple token-bucket rate limiting for FastHTML routes"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ec249d73",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| default_exp ratelimit"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b33aec8a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "import asyncio,re,time\n",
+    "from contextvars import ContextVar\n",
+    "from functools import wraps\n",
+    "from math import ceil\n",
+    "from typing import Callable\n",
+    "from starlette.responses import Response\n",
+    "from fastcore.utils import *"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c1e39599",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "from starlette.testclient import TestClient\n",
+    "from nbdev.showdoc import show_doc\n",
+    "from fastcore.test import *\n",
+    "from fasthtml.fastapp import *"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1078d10b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "_units = dict(s=1, m=60, h=3600, d=86400)\n",
+    "\n",
+    "def parse_rate(s):\n",
+    "    \"Parse rate string like `'5/m'`, `'1 per day'`, `'100/2h'`\"\n",
+    "    m = re.match(r'(\\d+)\\s*(?:/|per)\\s*(\\d+)?\\s*([smhd])', s, re.I)\n",
+    "    if not m: raise ValueError(f\"Invalid rate: {s}\")\n",
+    "    n,mult,unit = m.groups()\n",
+    "    return int(n), _units[unit.lower()] * int(mult or 1)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "23e2936b",
+   "metadata": {},
+   "source": [
+    "`parse_rate` accepts strings in the form `\"{count}/{window}\"` or `\"{count} per {window}\"`, where:\n",
+    "\n",
+    "- **count** — integer number of allowed requests (e.g. `5`, `100`)\n",
+    "- **window** — optional multiplier + unit: `s`econds, `m`inutes, `h`ours, `d`ays\n",
+    "\n",
+    "Examples: `'5/m'`, `'100/2h'`, `'1 per day'`, `5 per 2 hours`"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19fecdf0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_eq(parse_rate('5/m'), (5, 60))\n",
+    "test_eq(parse_rate('100/2h'), (100, 7200))\n",
+    "test_eq(parse_rate('1 per day'), (1, 86400))\n",
+    "test_eq(parse_rate('5 per 2 hours'), (5, 7200))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7b28079a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "class TokenBucket:\n",
+    "    \"Token-bucket rate limiter\"\n",
+    "    def __init__(self,\n",
+    "                 max_reqs:str|int,     # Rate string ('5/m') or max requests per window\n",
+    "                 window_secs:int=None  # Window in seconds (required if `max_reqs` is int)\n",
+    "                ):\n",
+    "        if window_secs is None: max_reqs,window_secs = parse_rate(max_reqs)\n",
+    "        store_attr()\n",
+    "        self.rate = max_reqs / window_secs\n",
+    "        self.buckets = {}\n",
+    "    def __repr__(self): return f'TokenBucket({self.max_reqs}, {self.window_secs})'\n",
+    "\n",
+    "    def _prune(self):\n",
+    "        cutoff = time.time() - self.window_secs\n",
+    "        self.buckets = {k:(t,ts) for k,(t,ts) in self.buckets.items() if ts > cutoff}\n",
+    "    def wait(self, key):\n",
+    "        \"Return 0 if allowed, else seconds to wait\"\n",
+    "        self._prune()\n",
+    "        now = time.time()\n",
+    "        tokens, last = self.buckets.get(key, (self.max_reqs, now))\n",
+    "        tokens = min(self.max_reqs, tokens + (now - last) * self.rate)\n",
+    "        if tokens < 1: return (1 - tokens) / self.rate\n",
+    "        self.buckets[key] = (tokens - 1, now)\n",
+    "        return 0"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f27963b0",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "---\n",
+       "\n",
+       "### TokenBucket\n",
+       "\n",
+       "```python\n",
+       "\n",
+       "def TokenBucket(\n",
+       "    max_reqs:str | int, # Rate string ('5/m') or max requests per window\n",
+       "    window_secs:int=None, # Window in seconds (required if `max_reqs` is int)\n",
+       "):\n",
+       "\n",
+       "\n",
+       "```\n",
+       "\n",
+       "*Token-bucket rate limiter*"
+      ],
+      "text/plain": [
+       "def TokenBucket(\n",
+       "    max_reqs:str | int, # Rate string ('5/m') or max requests per window\n",
+       "    window_secs:int=None, # Window in seconds (required if `max_reqs` is int)\n",
+       "):\n",
+       "\"\"\"Token-bucket rate limiter\"\"\""
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "show_doc(TokenBucket)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "349d2064",
+   "metadata": {},
+   "source": [
+    "Implements the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket). Tokens are added at a steady rate and consumed by requests. When the bucket is empty, requests are rejected and told how long to wait."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f0028515",
+   "metadata": {},
+   "source": [
+    "You can create a bucket with either a rate string or explicit values:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "417a59a6",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "TokenBucket(3, 10)"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "tb = TokenBucket(3, 10)\n",
+    "tb"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "623ac5d8",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "TokenBucket(3, 10)"
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "tb = TokenBucket('3/10s')\n",
+    "tb"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "38712997",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "---\n",
+       "\n",
+       "### TokenBucket.wait\n",
+       "\n",
+       "```python\n",
+       "\n",
+       "def wait(\n",
+       "    key\n",
+       "):\n",
+       "\n",
+       "\n",
+       "```\n",
+       "\n",
+       "*Return 0 if allowed, else seconds to wait*"
+      ],
+      "text/plain": [
+       "def wait(\n",
+       "    key\n",
+       "):\n",
+       "\"\"\"Return 0 if allowed, else seconds to wait\"\"\""
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "show_doc(TokenBucket.wait)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ff831ed1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_eq(tb.wait('x'), 0)\n",
+    "test_eq(tb.wait('x'), 0)\n",
+    "test_eq(tb.wait('x'), 0)\n",
+    "test(tb.wait('x'), 0, operator.gt)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "73587949",
+   "metadata": {},
+   "source": [
+    "Each key gets its own independent token bucket. So if user A exhausts their tokens, user B is unaffected — they still have a full bucket of their own:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6d8039f8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tb2 = TokenBucket(1, 0.5)\n",
+    "test_eq(tb2.wait('old'), 0)\n",
+    "test_eq(tb2.wait('new'), 0)\n",
+    "test   (tb2.wait('old'), 0, operator.gt)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2e48ec6b",
+   "metadata": {},
+   "source": [
+    "Stale keys — inactive longer than the window — are automatically pruned on each wait call:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5276e7bb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tb2.wait('old')\n",
+    "time.sleep(0.6)\n",
+    "tb2.wait('new')\n",
+    "test_eq('old' in tb2.buckets, False)\n",
+    "test_eq('new' in tb2.buckets, True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "69b0fb44",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def client_ip(req, **kwargs):\n",
+    "    \"Get client IP from `X-Forwarded-For` header, falling back to `req.client.host`\"\n",
+    "    return req.headers.get('x-forwarded-for', '').split(',')[0].strip() or (req.client and req.client.host) or ''"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "75b5b395",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "class Limiter:\n",
+    "    \"Rate limiter for FastHTML routes\"\n",
+    "    def __init__(self, app):\n",
+    "        self._req_var = ContextVar('limiter_req')\n",
+    "        async def _store(req): self._req_var.set(req)\n",
+    "        app.before.insert(0, _store)\n",
+    "\n",
+    "    def __call__(self,\n",
+    "                 rate:str|tuple,            # Rate string ('5/m') or (max_reqs, window_secs) tuple\n",
+    "                 key:str|Callable=client_ip, # Key to limit by: route param name, or callable(req, **kwargs)\n",
+    "                 on_limit:Callable=None     # Optional callback(wait_secs) to return custom response on 429\n",
+    "                ):\n",
+    "        \"Rate limit decorator: `@limiter('5/m')`\"\n",
+    "        bucket = TokenBucket(*rate) if isinstance(rate, tuple) else TokenBucket(rate)\n",
+    "        def decorator(f):\n",
+    "            @wraps(f)\n",
+    "            async def wrapper(*args, **kwargs):\n",
+    "                req = self._req_var.get()\n",
+    "                k = key(req, **kwargs) if callable(key) else str(kwargs.get(key, ''))\n",
+    "                if w:=bucket.wait(k):\n",
+    "                    if on_limit: return on_limit(w)\n",
+    "                    return Response('Too many requests', status_code=429, headers={'Retry-After': str(ceil(w))})\n",
+    "                return await maybe_await(f(*args, **kwargs))\n",
+    "            return wrapper\n",
+    "        return decorator"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "066e746b",
+   "metadata": {},
+   "source": [
+    "`Limiter` integrates `TokenBucket` with FastHTML's routing. Decorate routes with `@limiter()` to apply rate limits. Multiple decorators stack — all must pass. The `key` parameter controls what to rate-limit by: by default it uses `client_ip` which extracts the client's IP from `X-Forwarded-For` (falling back to `req.client.host`). Pass a string to match a route parameter name, or a callable for custom logic. Use `on_limit` to customize the 429 response — it receives the wait time in seconds and returns the response to send."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e399153c",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "---\n",
+       "\n",
+       "### Limiter\n",
+       "\n",
+       "```python\n",
+       "\n",
+       "def Limiter(\n",
+       "    app\n",
+       "):\n",
+       "\n",
+       "\n",
+       "```\n",
+       "\n",
+       "*Rate limiter for FastHTML routes*"
+      ],
+      "text/plain": [
+       "def Limiter(\n",
+       "    app\n",
+       "):\n",
+       "\"\"\"Rate limiter for FastHTML routes\"\"\""
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "show_doc(Limiter)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9302a311",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "---\n",
+       "\n",
+       "### Limiter.__call__\n",
+       "\n",
+       "```python\n",
+       "\n",
+       "def __call__(\n",
+       "    rate:str | tuple, # Rate string ('5/m') or (max_reqs, window_secs) tuple\n",
+       "    key:Union=client_ip, # Key to limit by: route param name, or callable(req, **kwargs)\n",
+       "    on_limit:Callable=None, # Optional callback(wait_secs) to return custom response on 429\n",
+       "):\n",
+       "\n",
+       "\n",
+       "```\n",
+       "\n",
+       "*Rate limit decorator: `@limiter('5/m')`*"
+      ],
+      "text/plain": [
+       "def __call__(\n",
+       "    rate:str | tuple, # Rate string ('5/m') or (max_reqs, window_secs) tuple\n",
+       "    key:Union=client_ip, # Key to limit by: route param name, or callable(req, **kwargs)\n",
+       "    on_limit:Callable=None, # Optional callback(wait_secs) to return custom response on 429\n",
+       "):\n",
+       "\"\"\"Rate limit decorator: `@limiter('5/m')`\"\"\""
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "show_doc(Limiter.__call__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3097f9d4",
+   "metadata": {},
+   "source": [
+    "## Example usage"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "19967166",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app, rt = fast_app()\n",
+    "cli = TestClient(app)\n",
+    "limiter = Limiter(app)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d0e3dd93",
+   "metadata": {},
+   "source": [
+    "### IP-based rate limiting (default)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7255f9dc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@rt\n",
+    "@limiter('3/m')  # keys on client IP by default\n",
+    "def index(): return 'ok'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a2c4118b",
+   "metadata": {},
+   "source": [
+    "Requests are allowed until the bucket is exhausted, then a 429 is returned with a `Retry-After` header."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "89f5bfcf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for i in range(3): test_eq(cli.get('/').status_code, 200)\n",
+    "r = cli.get('/')\n",
+    "test_eq(r.status_code, 429)\n",
+    "test(r.headers, 'Retry-After', operator.contains)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5c7a87db",
+   "metadata": {},
+   "source": [
+    "### Parameter-based rate limiting:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6e1b8dc0",
+   "metadata": {},
+   "source": [
+    "Different keys get independent buckets. Here we show `a@test.com` and `b@test.com` each get their own limit."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bbe72069",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@rt('/submit', methods=['POST'])\n",
+    "@limiter('2/m', key='email')\n",
+    "def submit(email: str): return f'hello {email}'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "40d23160",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for i in range(2): test_eq(cli.post('/submit', data={'email': 'a@test.com'}).status_code, 200)\n",
+    "test_eq(cli.post('/submit', data={'email': 'a@test.com'}).status_code, 429)\n",
+    "test_eq(cli.post('/submit', data={'email': 'b@test.com'}).status_code, 200)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "70172d98",
+   "metadata": {},
+   "source": [
+    "### Callable-based rate limiting:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "dffebde9",
+   "metadata": {},
+   "source": [
+    "For full control, pass a callable as `key`. It receives the Starlette `Request` plus any route `**kwargs`, and should return a string to bucket by. Here we rate-limit by the `x-api-key` header — each API key gets its own bucket:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "197fb532",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@rt\n",
+    "@limiter('2/m', key=lambda req, **kwargs: req.headers.get('x-api-key', ''))\n",
+    "def custom(): return 'ok'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6ed4a731",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for i in range(2): test_eq(cli.get('/custom', headers={'x-api-key': 'abc'}).status_code, 200)\n",
+    "test_eq(cli.get('/custom', headers={'x-api-key': 'abc'}).status_code, 429)\n",
+    "test_eq(cli.get('/custom', headers={'x-api-key': 'xyz'}).status_code, 200)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bf91ea45",
+   "metadata": {},
+   "source": [
+    "### Shared limits across routes:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bd9e28c8",
+   "metadata": {},
+   "source": [
+    "Save the decorator and apply it to multiple routes to share a single bucket."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "1fd5a249",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "shared = limiter('2/m')\n",
+    "\n",
+    "@rt\n",
+    "@shared\n",
+    "def users(): return 'users'\n",
+    "\n",
+    "@rt\n",
+    "@shared\n",
+    "def posts(): return 'posts'\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "42e03753",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "test_eq(cli.get('/users').status_code, 200)\n",
+    "test_eq(cli.get('/posts').status_code, 200)\n",
+    "test_eq(cli.get('/users').status_code, 429)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "330b3cba",
+   "metadata": {},
+   "source": [
+    "# Export -"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "84300cc1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "import nbdev; nbdev.nbdev_export()"
+   ]
+  }
+ ],
+ "metadata": {
+  "solveit_dialog_mode": "learning",
+  "solveit_ver": 2
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/nbs/api/10_magickey.ipynb b/nbs/api/10_magickey.ipynb
new file mode 100644
index 00000000..cc011445
--- /dev/null
+++ b/nbs/api/10_magickey.ipynb
@@ -0,0 +1,588 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c01b5481",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| default_exp magickey"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a7f143ec",
+   "metadata": {},
+   "source": [
+    "# MagicKey\n",
+    "> Passwordless auth combining magic links and passkeys"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d3fd43fe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "import secrets, time\n",
+    "from json import loads\n",
+    "from urllib.parse import urlparse\n",
+    "\n",
+    "from webauthn import generate_authentication_options, generate_registration_options, verify_authentication_response, verify_registration_response, options_to_json\n",
+    "from webauthn.helpers import base64url_to_bytes, bytes_to_base64url\n",
+    "from webauthn.helpers.structs import AuthenticatorSelectionCriteria, ResidentKeyRequirement, UserVerificationRequirement\n",
+    "\n",
+    "from fastcore.utils import *\n",
+    "from fastcore.xml import *\n",
+    "from fastlite import *\n",
+    "from fasthtml.basics import *\n",
+    "from fasthtml.starlette import *\n",
+    "from fasthtml.fastapp import *\n",
+    "from fasthtml.ratelimit import *"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cdf42c78",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fastcore.test import *\n",
+    "from starlette.testclient import TestClient"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b7fca791",
+   "metadata": {},
+   "source": [
+    "## Helpers"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9c6b5bcc",
+   "metadata": {},
+   "source": [
+    "`public_origin` and `rp_id` are passed to `MagicKey.__init__` and used directly at both WebAuthn verification call sites — no helper needed.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "03d86e44",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "# _origin_kw removed; public_origin / rp_id inlined at call sites\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0d037d2c",
+   "metadata": {},
+   "source": [
+    "`_webauthn_js` builds an inline `<script>` that calls SimpleWebAuthn's browser API (either `startRegistration` or `startAuthentication`) with the given options, then POSTs the result back to the server via htmx."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "02b50590",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "def _webauthn_js(opts, action, callback):\n",
+    "    return Script(\"SimpleWebAuthnBrowser.%s({ optionsJSON: %s }).then(r => {\"\n",
+    "        \"htmx.ajax('POST', '%s', { values: r });});\" % (action, options_to_json(opts), callback))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e251d84b",
+   "metadata": {},
+   "source": [
+    "## MagicKey class"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cae4a103",
+   "metadata": {},
+   "source": [
+    "Follows the same pattern as `OAuth`: wires up beforeware and backend routes in `__init__`, with overridable methods for app-specific behaviour."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "17d33679",
+   "metadata": {},
+   "source": [
+    "The `MagicKey` class sets up beforeware (redirects unauthenticated users to the login page) and registers all backend routes. The developer subclasses it and overrides `get_auth` (what URL to redirect to after login) and the passkey storage methods."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "032d5010",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| export\n",
+    "class MagicKey:\n",
+    "    def __init__(self,\n",
+    "                 app,             # FastHTML app instance\n",
+    "                 send_email,      # `f(email, magic_url)` — sends the magic link\n",
+    "                 public_origin,   # Full origin URL, e.g. `https://example.com`\n",
+    "                 rp_id=None,      # WebAuthn relying party ID (default: hostname from `public_origin`)\n",
+    "                 rp_name=None,    # WebAuthn relying party display name (default: `rp_id`)\n",
+    "                 skip=None,       # Routes to skip auth beforeware (default: all MagicKey routes)\n",
+    "                 login_path='/login',   # Login page route\n",
+    "                 logout_path='/logout', # Logout route\n",
+    "                 token_expiry=3600,      # Magic link validity in seconds\n",
+    "                 email_rate='3/m',       # Per-email rate limit on magic link sends (None to disable)\n",
+    "                 ip_rate='10/m',         # Per-IP rate limit on magic link sends (None to disable)\n",
+    "                 webauthn_js=None):      # Script tag or URL for SimpleWebAuthn browser JS (default: jsdelivr CDN)\n",
+    "        \"Passwordless auth combining magic links and passkeys\"\n",
+    "        if not rp_id: rp_id = urlparse(public_origin).hostname\n",
+    "        self.magiclink_db = {}\n",
+    "        self._email_bucket = TokenBucket(email_rate) if email_rate else None\n",
+    "        self._ip_bucket = TokenBucket(ip_rate) if ip_rate else None\n",
+    "        store_attr()\n",
+    "        async def _before(req, session):\n",
+    "            if 'auth' not in req.scope: req.scope['auth'] = session.get('auth')\n",
+    "            if not req.scope['auth']: return RedirectResponse(login_path, status_code=303)\n",
+    "        if not skip: skip = [login_path, logout_path, '/finish_passkey_reg', '/send_magic_link', \n",
+    "                             '/request_passkey_auth', '/request_passkey_reg', '/setup_passkey',\n",
+    "                             '/skip_passkey_reg', '/verify_magiclink', '/verify_passkey_auth',]\n",
+    "        app.before.append(Beforeware(_before, skip=skip))\n",
+    "        if not webauthn_js: webauthn_js = Script(src='https://cdn.jsdelivr.net/npm/@simplewebauthn/browser@13.1.0/dist/bundle/index.umd.min.js')\n",
+    "        elif isinstance(webauthn_js, str): webauthn_js = Script(src=webauthn_js)\n",
+    "        app.hdrs += (webauthn_js,)\n",
+    "        app.get(logout_path)(self._logout)\n",
+    "        app.post('/send_magic_link')(self._send_magic_link)\n",
+    "        app.get('/verify_magiclink')(self._verify_magiclink)\n",
+    "        app.post('/request_passkey_auth')(self._request_passkey_auth)\n",
+    "        app.post('/verify_passkey_auth')(self._verify_passkey_auth)\n",
+    "        app.post('/request_passkey_reg')(self._request_passkey_reg)\n",
+    "        app.post('/finish_passkey_reg')(self._finish_passkey_reg)\n",
+    "        app.post('/skip_passkey_reg')(self._skip_passkey_reg)\n",
+    "\n",
+    "    def _logout(self, session):\n",
+    "        session.pop('auth', None)\n",
+    "        return RedirectResponse(self.login_path, status_code=303)\n",
+    "\n",
+    "    def _send_magic_link(self, email: str, req):\n",
+    "        for bucket,key in ((self._ip_bucket, client_ip(req)), (self._email_bucket, email)):\n",
+    "            if bucket and (w:=bucket.wait(key)): return Response('Too many requests', status_code=429, headers={'Retry-After': str(int(w)+1)})\n",
+    "        self.magiclink_db = {k:v for k,v in self.magiclink_db.items() if not v['used'] and time.time() - v['timestamp'] <= self.token_expiry}\n",
+    "        token = secrets.token_urlsafe(32)\n",
+    "        self.magiclink_db[token] = dict(email=email, timestamp=time.time(), used=False)\n",
+    "        magic_url = f'{self.public_origin}/verify_magiclink?token={token}'\n",
+    "        return self.send_email(email, magic_url)\n",
+    "\n",
+    "    def _verify_magiclink(self, token: str, session, req):\n",
+    "        link = self.magiclink_db.get(token)\n",
+    "        if not link or link['used'] or time.time() - link['timestamp'] > self.token_expiry:\n",
+    "            return RedirectResponse(f'{self.login_path}?error=invalid_link', status_code=303)\n",
+    "        link['used'] = True\n",
+    "        return self.after_magiclink_verify(link['email'], session, req)\n",
+    "\n",
+    "    def _request_passkey_auth(self, session):\n",
+    "        auth_opts = generate_authentication_options(\n",
+    "            rp_id=self.rp_id, user_verification=UserVerificationRequirement.REQUIRED)\n",
+    "        session['auth_challenge'] = bytes_to_base64url(auth_opts.challenge)\n",
+    "        return _webauthn_js(auth_opts, 'startAuthentication', '/verify_passkey_auth')\n",
+    "\n",
+    "    def _verify_passkey_auth(self, response: str, id: str, rawId: str, type: str, session):\n",
+    "        challenge_b64 = session.pop('auth_challenge', None)\n",
+    "        if not challenge_b64: return HttpHeader('HX-Redirect', f'{self.login_path}?error=no_challenge')\n",
+    "        stored = self.get_passkey(id)\n",
+    "        if not stored: return HttpHeader('HX-Redirect', f'{self.login_path}?error=passkey_not_found')\n",
+    "        try:\n",
+    "            res = verify_authentication_response(\n",
+    "                credential=dict(id=id, rawId=rawId, response=loads(response), type=type),\n",
+    "                credential_public_key=stored['public_key'], \n",
+    "                credential_current_sign_count=stored['sign_count'],\n",
+    "                expected_challenge=base64url_to_bytes(challenge_b64), \n",
+    "                require_user_verification=True,\n",
+    "                expected_origin=self.public_origin, expected_rp_id=self.rp_id)\n",
+    "        except Exception: return HttpHeader('HX-Redirect', f'{self.login_path}?error=passkey_failed')\n",
+    "        self.update_passkey(id, res.new_sign_count)\n",
+    "        session['auth'] = self.get_user_id(stored['email'])\n",
+    "        return self._do_auth(session['auth'], session, htmx=True)\n",
+    "\n",
+    "    def _request_passkey_reg(self, session):\n",
+    "        email = session.get('pending_email')\n",
+    "        if not email: return RedirectResponse(f'{self.login_path}?error=no_pending_reg', status_code=303)\n",
+    "        opts = generate_registration_options(\n",
+    "            rp_id=self.rp_id, rp_name=self.rp_name or self.rp_id, user_name=email, \n",
+    "            user_id=str(self.get_user_id(email)).encode(), \n",
+    "            authenticator_selection=AuthenticatorSelectionCriteria(resident_key=ResidentKeyRequirement.REQUIRED))\n",
+    "        session['reg_challenge'] = bytes_to_base64url(opts.challenge)\n",
+    "        return _webauthn_js(opts, 'startRegistration', '/finish_passkey_reg')\n",
+    "\n",
+    "    def _finish_passkey_reg(self, response: str, id: str, rawId: str, type: str, session):\n",
+    "        email = session.pop('pending_email', None)\n",
+    "        if not email: return RedirectResponse(f'{self.login_path}?error=no_pending_reg', status_code=303)\n",
+    "        challenge_b64 = session.pop('reg_challenge', None)\n",
+    "        if not challenge_b64: return RedirectResponse('/setup_passkey?error=no_challenge', status_code=303)\n",
+    "        try: res = verify_registration_response(credential=dict(id=id, rawId=rawId, response=loads(response), type=type),\n",
+    "                                                expected_challenge=base64url_to_bytes(challenge_b64),\n",
+    "                                                require_user_verification=True,\n",
+    "                                                expected_origin=self.public_origin, expected_rp_id=self.rp_id)\n",
+    "        except Exception: return RedirectResponse('/setup_passkey?error=reg_failed', status_code=303)\n",
+    "        self.save_passkey(bytes_to_base64url(res.credential_id), email, res.credential_public_key, res.sign_count)\n",
+    "        session['auth'] = self.get_user_id(email)\n",
+    "        return self._do_auth(session['auth'], session, htmx=True)\n",
+    "\n",
+    "    def _skip_passkey_reg(self, session):\n",
+    "        email = session.pop('pending_email', None)\n",
+    "        if not email: return RedirectResponse(self.login_path, status_code=303)\n",
+    "        session['auth'] = self.get_user_id(email)\n",
+    "        return self._do_auth(session['auth'], session, htmx=False)\n",
+    "\n",
+    "    def _do_auth(self, user_id, session, htmx=False):\n",
+    "        url = self.get_auth(user_id, session)\n",
+    "        if htmx: return HttpHeader('HX-Redirect', url)\n",
+    "        return RedirectResponse(url, status_code=303)\n",
+    "\n",
+    "    def get_auth(self, user_id, session): return '/'\n",
+    "    def get_user_id(self, email): raise NotImplementedError()\n",
+    "    def has_passkey(self, email): raise NotImplementedError()\n",
+    "    def get_passkey(self, credential_id): raise NotImplementedError()\n",
+    "    def save_passkey(self, credential_id, email, public_key, sign_count): raise NotImplementedError()\n",
+    "    def update_passkey(self, credential_id, sign_count): raise NotImplementedError()\n",
+    "\n",
+    "    def after_magiclink_verify(self, email, session, req):\n",
+    "        if self.has_passkey(email):\n",
+    "            session['auth'] = self.get_user_id(email)\n",
+    "            return self._do_auth(session['auth'], session, htmx=False)\n",
+    "        session['pending_email'] = email\n",
+    "        return RedirectResponse('/setup_passkey', status_code=303)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "145a5fc2",
+   "metadata": {},
+   "source": [
+    "### Overridable methods\n",
+    "\n",
+    "| Method | Purpose | Default |\n",
+    "|--------|---------|---------|\n",
+    "| `get_auth(user_id, session)` | Return URL to redirect to after successful auth | `/` |\n",
+    "| `get_user_id(email)` | Return user ID for a given email | `NotImplementedError` |\n",
+    "| `has_passkey(email)` | Check if user has a registered passkey | `NotImplementedError` |\n",
+    "| `get_passkey(credential_id)` | Look up passkey by credential ID, return dict with `email`, `public_key`, `sign_count` | `NotImplementedError` |\n",
+    "| `save_passkey(credential_id, email, public_key, sign_count)` | Store a new passkey | `NotImplementedError` |\n",
+    "| `update_passkey(credential_id, sign_count)` | Update sign count after auth | `NotImplementedError` |\n",
+    "| `after_magiclink_verify(email, session, req)` | Called after magic link verified; default offers passkey registration | redirects to `/setup_passkey` |"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "857e710b",
+   "metadata": {},
+   "source": [
+    "## Tests -"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6931f022",
+   "metadata": {},
+   "source": [
+    "We can test the non-WebAuthn parts using FastHTML's test client. The beforeware, magic link flow, and session management are all testable without a browser."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6ee20bb0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "db = database(':memory:')\n",
+    "class User: id:int; email:str\n",
+    "class Passkey: id:str; user_id:int; public_key:bytes; sign_count:int\n",
+    "users = db.create(User)\n",
+    "passkeys = db.create(Passkey)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5a79dd35",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Auth(MagicKey):\n",
+    "    def get_user_id(self, email):\n",
+    "        res = users(where=\"email = ?\", where_args=[email])\n",
+    "        if res: return res[0].id\n",
+    "        return users.insert(User(email=email)).id\n",
+    "    def has_passkey(self, email):\n",
+    "        return bool(passkeys(where=\"user_id = ?\", where_args=[self.get_user_id(email)]))\n",
+    "    def get_passkey(self, cred_id):\n",
+    "        try: r = passkeys[cred_id]\n",
+    "        except NotFoundError: return None\n",
+    "        return dict(email=users[r.user_id].email, public_key=r.public_key, sign_count=r.sign_count)\n",
+    "    def save_passkey(self, cred_id, email, public_key, sign_count):\n",
+    "        uid = self.get_user_id(email)\n",
+    "        passkeys.insert(Passkey(id=cred_id, user_id=uid, public_key=public_key, sign_count=sign_count))\n",
+    "    def update_passkey(self, cred_id, sign_count):\n",
+    "        passkeys.update(Passkey(id=cred_id, sign_count=sign_count))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2dfeebca",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def fake_send_email(email, url): return P(f'Magic link for {email}: ', A(url, href=url))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7ac159c6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app, rt = fast_app()\n",
+    "mk = Auth(app, send_email=fake_send_email, public_origin='http://testserver')\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "6312035f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@rt\n",
+    "def index(auth):\n",
+    "    u = users[auth]\n",
+    "    return P(f'Hello {u.email}!'), A('Log out', href='/logout')\n",
+    "\n",
+    "@rt\n",
+    "def login(error: str=None):\n",
+    "    errmsg = P(error.replace('_', ' ').title(), style='color:red') if error else ''\n",
+    "    return Titled('Sign In', errmsg,\n",
+    "                Button('Sign in with Passkey', hx_post='/request_passkey_auth', target_id='scripts'),\n",
+    "                Hr(),\n",
+    "                Form(method='post', action='/send_magic_link')(\n",
+    "                    Input(name='email', type='email', placeholder='you@example.com'),\n",
+    "                    Button('Send Magic Link')),\n",
+    "                Div(id='scripts'))\n",
+    "\n",
+    "@rt\n",
+    "def setup_passkey(): return Titled('Set Up Passkey',\n",
+    "                            P('Set up a passkey for faster logins next time?'),\n",
+    "                            Button('Register Passkey', hx_post='/request_passkey_reg', target_id='scripts'),\n",
+    "                            Form(Button('Skip'), method='post', action='/skip_passkey_reg'),\n",
+    "                            Div(id='scripts'))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b6f4a9df",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "cli = TestClient(app)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "3d791e8e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.get('/', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login')\n",
+    "\n",
+    "r = cli.get('/login')\n",
+    "test_eq(r.status_code, 200)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7998710c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/send_magic_link', data={'email': 'expired@test.com'})\n",
+    "token = [k for k in mk.magiclink_db.keys()][-1]\n",
+    "mk.magiclink_db[token]['timestamp'] = time.time() - 3601  # older than 1hr\n",
+    "r = cli.get(f'/verify_magiclink?token={token}', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login?error=invalid_link')\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bd3b853b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/send_magic_link', data={'email': 'test@example.com'})\n",
+    "test_eq(r.status_code, 200)\n",
+    "token = list(mk.magiclink_db.keys())[-1]\n",
+    "\n",
+    "r = cli.get(f'/verify_magiclink?token={token}', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test(r.headers['location'], '/setup_passkey', operator.contains)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d8c789cb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/skip_passkey_reg', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/')\n",
+    "\n",
+    "r = cli.get('/')\n",
+    "test_eq(r.status_code, 200)\n",
+    "test(r.text, 'test@example.com', operator.contains)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0e61d425",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.get('/logout', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login')\n",
+    "\n",
+    "r = cli.get('/', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "df715580",
+   "metadata": {},
+   "source": [
+    "Lets add some tests for the unhappy paths"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "e97da597",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.get(f'/verify_magiclink?token={token}', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login?error=invalid_link')\n",
+    "\n",
+    "r = cli.get('/verify_magiclink?token=bogus', follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login?error=invalid_link')\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f5f5a42d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/verify_passkey_auth', data={'response': '{}', 'id': 'fake', 'rawId': 'fake', 'type': 'public-key'}, follow_redirects=False)\n",
+    "test_eq(r.status_code, 200)\n",
+    "test_eq(r.headers['hx-redirect'], '/login?error=no_challenge')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7cc78182",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/request_passkey_auth', headers={'hx-request': 'true'})\n",
+    "r = cli.post('/verify_passkey_auth', data={'response': '{}', 'id': 'fake', 'rawId': 'fake', 'type': 'public-key'}, follow_redirects=False)\n",
+    "test_eq(r.status_code, 200)\n",
+    "test_eq(r.headers['hx-redirect'], '/login?error=passkey_not_found')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2ad79978",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "r = cli.post('/finish_passkey_reg', data={'response': '{}', 'id': 'fake', 'rawId': 'fake', 'type': 'public-key'}, follow_redirects=False)\n",
+    "test_eq(r.status_code, 303)\n",
+    "test_eq(r.headers['location'], '/login?error=no_pending_reg')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "963973cc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "for i in range(4):\n",
+    "    r = cli.post('/send_magic_link', data={'email': 'ratelimit@test.com'})\n",
+    "    if i < 3: test_eq(r.status_code, 200)\n",
+    "    else:\n",
+    "        test_eq(r.status_code, 429)\n",
+    "        test(int(r.headers['retry-after']), 0, operator.gt)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "14bbcb39",
+   "metadata": {},
+   "source": [
+    "## Export -"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9727c7bf",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "#| eval: false\n",
+    "from nbdev.doclinks import nbdev_export\n",
+    "nbdev_export()"
+   ]
+  }
+ ],
+ "metadata": {
+  "solveit_dialog_mode": "learning",
+  "solveit_ver": 2
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/nbs/explains/magickey.ipynb b/nbs/explains/magickey.ipynb
new file mode 100644
index 00000000..bc00ca27
--- /dev/null
+++ b/nbs/explains/magickey.ipynb
@@ -0,0 +1,361 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "a7f143ec",
+   "metadata": {},
+   "source": [
+    "# MagicKey\n",
+    "> Passwordless auth combining magic links and passkeys"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c344c44d",
+   "metadata": {},
+   "source": [
+    "Passwords are a hassle. MagicKey gives your FastHTML app passwordless auth by combining **magic links** (one-time URLs sent to email) with **passkeys** (device-stored cryptographic credentials with optional biometric verification). Magic links handle sign-up and device recovery; passkeys make returning logins instant and phishing-resistant."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "93554945",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#| hide\n",
+    "from nbdev.showdoc import show_doc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b1bbd0e9",
+   "metadata": {},
+   "source": [
+    "## Quick Start"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "34c9e76b",
+   "metadata": {},
+   "source": [
+    "Subclass `MagicKey`, override five storage methods, provide a `send_email` callable, and define two routes (`/login` and `/setup_passkey`). Below we show a minimal working app."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "892c18ea",
+   "metadata": {},
+   "source": [
+    "First, we subclass MagicKey and override the five storage methods:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5c5e8926",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from fasthtml.common import *\n",
+    "from fasthtml.magickey import MagicKey\n",
+    "\n",
+    "db = database(':memory:')\n",
+    "class User: id:int; email:str\n",
+    "class Passkey: id:str; user_id:int; public_key:bytes; sign_count:int\n",
+    "users = db.create(User)\n",
+    "passkeys = db.create(Passkey)\n",
+    "\n",
+    "class Auth(MagicKey):\n",
+    "    def get_user_id(self, email):\n",
+    "        res = users(where=\"email = ?\", where_args=[email])\n",
+    "        if res: return res[0].id\n",
+    "        return users.insert(User(email=email)).id\n",
+    "    def has_passkey(self, email):\n",
+    "        return bool(passkeys(where=\"user_id = ?\", where_args=[self.get_user_id(email)]))\n",
+    "    def get_passkey(self, cred_id):\n",
+    "        try: r = passkeys[cred_id]\n",
+    "        except NotFoundError: return None\n",
+    "        return dict(email=users[r.user_id].email, public_key=r.public_key, sign_count=r.sign_count)\n",
+    "    def save_passkey(self, cred_id, email, public_key, sign_count):\n",
+    "        uid = self.get_user_id(email)\n",
+    "        passkeys.insert(Passkey(id=cred_id, user_id=uid, public_key=public_key, sign_count=sign_count))\n",
+    "    def update_passkey(self, cred_id, sign_count):\n",
+    "        passkeys.update(Passkey(id=cred_id, sign_count=sign_count))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "84c1006d",
+   "metadata": {},
+   "source": [
+    "Second, we create the app and wire up MagicKey. `send_email` receives `(email, url)` — in production you'd send a real email; here we just display the link:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "76fb8fba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "app, rt = fast_app()\n",
+    "def fake_send_email(email, url): return P(f'Magic link for {email}: ', A(url, href=url))\n",
+    "mk = Auth(app, send_email=fake_send_email, public_origin='http://localhost:5001')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "db63ff94",
+   "metadata": {},
+   "source": [
+    "`public_origin` is the full origin URL used for magic link URLs and WebAuthn verification (e.g. `'https://app.example.com'` in production). MagicKey automatically adds beforeware that redirects unauthenticated users to `/login`, and registers all backend routes for magic link and passkey handling."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0ef20a2e",
+   "metadata": {},
+   "source": [
+    "Third, we add the `/login` and `/setup_passkey` routes:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "dc84827b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@rt\n",
+    "def index(auth):\n",
+    "    u = users[auth]\n",
+    "    return P(f'Hello {u.email}!'), A('Log out', href='/logout')\n",
+    "\n",
+    "@rt\n",
+    "def login(error: str=None):\n",
+    "    errmsg = P(error.replace('_', ' ').title(), style='color:red') if error else ''\n",
+    "    return Titled('Sign In', errmsg,\n",
+    "                Button('Sign in with Passkey', hx_post='/request_passkey_auth', target_id='scripts'),\n",
+    "                Hr(),\n",
+    "                Form(method='post', action='/send_magic_link')(\n",
+    "                    Input(name='email', type='email', placeholder='you@example.com'),\n",
+    "                    Button('Send Magic Link')),\n",
+    "                Div(id='scripts'))\n",
+    "\n",
+    "@rt\n",
+    "def setup_passkey(): return Titled('Set Up Passkey',\n",
+    "                            P('Set up a passkey for faster logins next time?'),\n",
+    "                            Button('Register Passkey', hx_post='/request_passkey_reg', target_id='scripts'),\n",
+    "                            Form(Button('Skip'), method='post', action='/skip_passkey_reg'),\n",
+    "                            Div(id='scripts'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "40fed0e8",
+   "metadata": {},
+   "source": [
+    "That's it! This is enough to provide your users with email signup via a magic link and passkey login."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "623e9489",
+   "metadata": {},
+   "source": [
+    "## In Depth"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "03a7cc48",
+   "metadata": {},
+   "source": [
+    "### The Authentication Flow"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3213ac18",
+   "metadata": {},
+   "source": [
+    "Here's how the three main scenarios play out:\n",
+    "\n",
+    "**First visit (magic link → passkey setup):**\n",
+    "\n",
+    "A new user visits `/` and gets redirected to `/login` by the beforeware. They enter their email, this POSTs to `/send_magic_link`, which generates a one-time token, and calls your `send_email` with the link. \n",
+    "\n",
+    "When they click it, `/verify_magiclink` checks and marks the token as used, creates the user if new, and calls `after_magiclink_verify`. Since this user has no passkey yet, they're redirected to `/setup_passkey`, where they can choose to register their passkey via the browser's WebAuthn API prompts for biometric/PIN registration.\n",
+    "\n",
+    "**Returning visit (passkey):**\n",
+    "\n",
+    "The user clicks \"Sign in with Passkey\" on `/login`, which POSTs to `/request_passkey_auth`. The browser prompts for biometric/PIN, and the credential is verified server-side via `/verify_passkey_auth`. No email, fast login.\n",
+    "\n",
+    "**Returning visit (magic link fallback):**\n",
+    "\n",
+    "If the passkey doesn't work (new device, declined prompt, etc.), the user falls back to the email form. Since they already have a passkey registered, `after_magiclink_verify` sees this and logs them in directly, no passkey setup prompt this time."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4c759134",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/markdown": [
+       "---\n",
+       "\n",
+       "[source](https://github.com/AnswerDotAI/fasthtml/blob/main/fasthtml/magickey.py#LNone){target=\"_blank\" style=\"float:right; font-size:smaller\"}\n",
+       "\n",
+       "### MagicKey\n",
+       "\n",
+       "```python\n",
+       "\n",
+       "def MagicKey(\n",
+       "    app, # FastHTML app instance\n",
+       "    send_email, # `f(email, magic_url)` — sends the magic link\n",
+       "    public_origin, # Full origin URL, e.g. `https://example.com`\n",
+       "    rp_id:NoneType=None, # WebAuthn relying party ID (default: hostname from `public_origin`)\n",
+       "    rp_name:NoneType=None, # WebAuthn relying party display name (default: `rp_id`)\n",
+       "    skip:NoneType=None, # Routes to skip auth beforeware (default: all MagicKey routes)\n",
+       "    login_path:str='/login', # Login page route\n",
+       "    logout_path:str='/logout', # Logout route\n",
+       "    token_expiry:int=3600, # Magic link validity in seconds\n",
+       "    email_rate:str='3/m', # Per-email rate limit on magic link sends (None to disable)\n",
+       "    ip_rate:str='10/m', # Per-IP rate limit on magic link sends (None to disable)\n",
+       "    webauthn_js:NoneType=None, # Script tag or URL for SimpleWebAuthn browser JS (default: jsdelivr CDN)\n",
+       "):\n",
+       "\n",
+       "\n",
+       "```\n",
+       "\n",
+       "*Passwordless auth combining magic links and passkeys*"
+      ],
+      "text/plain": [
+       "def MagicKey(\n",
+       "    app, # FastHTML app instance\n",
+       "    send_email, # `f(email, magic_url)` — sends the magic link\n",
+       "    public_origin, # Full origin URL, e.g. `https://example.com`\n",
+       "    rp_id:NoneType=None, # WebAuthn relying party ID (default: hostname from `public_origin`)\n",
+       "    rp_name:NoneType=None, # WebAuthn relying party display name (default: `rp_id`)\n",
+       "    skip:NoneType=None, # Routes to skip auth beforeware (default: all MagicKey routes)\n",
+       "    login_path:str='/login', # Login page route\n",
+       "    logout_path:str='/logout', # Logout route\n",
+       "    token_expiry:int=3600, # Magic link validity in seconds\n",
+       "    email_rate:str='3/m', # Per-email rate limit on magic link sends (None to disable)\n",
+       "    ip_rate:str='10/m', # Per-IP rate limit on magic link sends (None to disable)\n",
+       "    webauthn_js:NoneType=None, # Script tag or URL for SimpleWebAuthn browser JS (default: jsdelivr CDN)\n",
+       "):\n",
+       "\"\"\"Passwordless auth combining magic links and passkeys\"\"\""
+      ]
+     },
+     "execution_count": null,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "show_doc(MagicKey)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "689ff8e9",
+   "metadata": {},
+   "source": [
+    "A few of these parameters deserve more explanation than their docstring provides."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8f886dc",
+   "metadata": {},
+   "source": [
+    "### `rp_id`\n",
+    "\n",
+    "The WebAuthn [Relying Party](https://www.w3.org/TR/webauthn/#relying-party) identifier. This must be a domain that matches your site's origin — browsers will reject passkey operations otherwise. Defaults to the hostname extracted from `public_origin` (e.g. `'app.example.com'` from `'https://app.example.com'`).\n",
+    "\n",
+    "The main reason to override this is the **subdomain pattern**: if your app runs at `app.example.com` but you set `rp_id='example.com'`, passkeys registered there will also work on `api.example.com`, `admin.example.com`, or any other subdomain. WebAuthn allows `rp_id` to be a registrable domain suffix of the current origin. So a passkey created with `rp_id='example.com'` is valid anywhere under `*.example.com`, but one created with `rp_id='app.example.com'` only works on that exact subdomain.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a2fd340d",
+   "metadata": {},
+   "source": [
+    "### `email_rate`, `ip_rate`\n",
+    "\n",
+    "Rate limits on the `/send_magic_link` endpoint to prevent abuse. `email_rate` limits per recipient address (default `'3/m'` — 3 requests per minute), `ip_rate` limits per source IP (default `'10/m'`). Format is `'count/period'` where period is `(s)econds`, `(m)inutes`, `(h)ours`, or `(d)ays`. Set either to `None` to disable that limit."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "70f329ae",
+   "metadata": {},
+   "source": [
+    "### `webauthn_js`\n",
+    "\n",
+    "The SimpleWebAuthn browser library used for passkey ceremonies. Defaults to a jsdelivr CDN script tag. Override this to self-host the JS or pin a specific version — pass either a Script(...) tag or a URL string. Self-hosting avoids a third-party dependency and ensures the script can't change unexpectedly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "beaef428",
+   "metadata": {},
+   "source": [
+    "### Sending Magic Links"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ffb04414",
+   "metadata": {},
+   "source": [
+    "In the example above we provided a fake example that just prints the email. To actually send emails you can use any of the many email libraries available in Python.\n",
+    "\n",
+    "Here's one example available to apps deployed on [Pla.sh](https://pla.sh), an easy to use python web host, by the creators of FastHTML.\n",
+    "\n",
+    "```py\n",
+    "from plash_cli.auth import send_magiclink\n",
+    "def send_email(email,url):\n",
+    "    res = send_magiclink(email,url)\n",
+    "    if res.status_code == 200: return P('Please check your email for your login link')\n",
+    "    else: return P('Something went wrong, please try again later')\n",
+    "mk = Auth(app, send_email=send_email, public_origin='https://example.com')\n",
+    "...\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3fecc70b",
+   "metadata": {},
+   "source": [
+    "### Overridable Methods"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c9e0e11b",
+   "metadata": {},
+   "source": [
+    "Beyond the five required storage methods shown in the Quick Start (`get_user_id`, `has_passkey`, `get_passkey`, `save_passkey`, `update_passkey`), there are two optional methods you can override to customise the auth flow:\n",
+    "\n",
+    "**`get_auth(self, user_id, session)`** — called after successful authentication (both magic link and passkey). Returns the URL to redirect to. Default: `'/'`. Override this to send users to a dashboard, onboarding page, or wherever makes sense for your app.\n",
+    "\n",
+    "**`after_magiclink_verify(self, email, session, req)`** — called after a magic link token is verified. The default behaviour checks `has_passkey(email)`: if the user already has one, it logs them in directly; if not, it redirects to `/setup_passkey`. Override this to skip passkey setup entirely, add custom onboarding logic, or change the redirect flow."
+   ]
+  }
+ ],
+ "metadata": {
+  "solveit_dialog_mode": "concise",
+  "solveit_ver": 2
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/pyproject.toml b/pyproject.toml
index 18348ddd..60351c78 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -12,7 +12,7 @@ license = {text = "Apache-2.0"}
 authors = [{name = "Jeremy Howard and contributors", email = "github@jhoward.fastmail.fm"}]
 keywords = ['nbdev', 'jupyter', 'notebook', 'python']
 classifiers = ["Natural Language :: English", "Intended Audience :: Developers", "Development Status :: 3 - Alpha", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only"]
-dependencies = ['fastcore>=1.12.16', 'python-dateutil', 'starlette~=1.0', 'oauthlib', 'itsdangerous', 'uvicorn[standard]>=0.30', 'httpx', 'fastlite>=0.1.1', 'python-multipart', 'beautifulsoup4']
+dependencies = ['fastcore>=1.12.16', 'python-dateutil', 'starlette~=1.0', 'oauthlib', 'itsdangerous', 'uvicorn[standard]>=0.30', 'httpx', 'fastlite>=0.1.1', 'python-multipart', 'beautifulsoup4','webauthn']
 
 [project.urls]
 Repository = "https://github.com/AnswerDotAI/fasthtml"
diff --git a/tests/magickey_app.py b/tests/magickey_app.py
new file mode 100644
index 00000000..0df7fb5d
--- /dev/null
+++ b/tests/magickey_app.py
@@ -0,0 +1,39 @@
+from fasthtml.common import *
+from fasthtml.magickey import MagicKey
+
+app, rt = fast_app()
+
+passkey_store = {}
+class Auth(MagicKey):
+    def get_auth(self, email, session): return '/'
+    def get_user_id(self, email): return email
+    def has_passkey(self, email): return any(v['email'] == email for v in passkey_store.values())
+    def get_passkey(self, credential_id): return passkey_store.get(credential_id)
+    def save_passkey(self, credential_id, email, public_key, sign_count):
+        passkey_store[credential_id] = dict(email=email, public_key=public_key, sign_count=sign_count)
+    def update_passkey(self, credential_id, sign_count): passkey_store[credential_id]['sign_count'] = sign_count
+
+def _dev_send_email(email, url): return P(f'Magic link for {email}: ', A(url, href=url))
+mk = Auth(app, send_email=_dev_send_email, public_origin='http://localhost:8123', rp_id='localhost')
+
+@rt
+def index(auth): return Titled('Home', P(f'Hello {auth}!'), A('Log out', href='/logout'))
+
+@rt
+def login():
+    return Titled('Sign In',
+        Button('Sign in with Passkey', hx_post='/request_passkey_auth', target_id='scripts'),
+        Hr(),
+        Form(method='post', action='/send_magic_link')(
+            Input(name='email', type='email', placeholder='you@example.com', id='email-input'),
+            Button('Send Magic Link', type='submit')),
+        Div(id='scripts'))
+
+@rt
+def setup_passkey():
+    return Titled('Set Up Passkey',
+        P('Set up a passkey for faster logins next time?'),
+        Button('Register Passkey', hx_post='/request_passkey_reg', target_id='scripts'),
+        Form(Button('Skip', type='submit', id='skip-btn'), action='/skip_passkey_reg', method='post'),
+        Div(id='scripts'))
+
diff --git a/tests/test_magickey_e2e.py b/tests/test_magickey_e2e.py
new file mode 100644
index 00000000..9d7ee70a
--- /dev/null
+++ b/tests/test_magickey_e2e.py
@@ -0,0 +1,91 @@
+"""End-to-end tests for MagicKey using Playwright with virtual WebAuthn authenticator.
+
+To run: `python tests/test_magickey_end2end.py`
+
+"""
+import asyncio, threading, time, uvicorn
+from playwright.async_api import async_playwright
+
+PORT = 8123
+url = f'http://localhost:{PORT}'
+
+def _start_server():
+    import os,sys
+    sys.path.insert(0,os.path.dirname(__file__))
+    from magickey_app import app
+    uvicorn.run(app, host='localhost', port=PORT, log_level='warning')
+
+async def _add_virtual_authenticator(page):
+    cdp = await page.context.new_cdp_session(page)
+    await cdp.send('WebAuthn.enable')
+    await cdp.send('WebAuthn.addVirtualAuthenticator', {
+        'options': {
+            'protocol': 'ctap2',
+            'transport': 'internal',
+            'hasUserVerification': True,
+            'isUserVerified': True,
+            'hasResidentKey': True,
+            'automaticPresenceSimulation': True,
+        }
+    })
+    return cdp
+
+async def _register(page, email, passkey=True):
+    await page.goto(f'{url}/login')
+    await page.wait_for_selector('#email-input')
+    await page.fill('#email-input', email)
+    await page.click('button[type="submit"]')
+    await page.wait_for_selector('a[href*="verify_magiclink"]')
+    link = await page.query_selector('a[href*="verify_magiclink"]')
+    await link.click()
+    await page.wait_for_url('**/setup_passkey**')
+    if passkey: await page.click('text=Register Passkey')
+    else :      await page.click('#skip-btn')
+    await page.wait_for_url('**/')
+
+async def test_magic_link_and_passkey_reg(browser):
+    page = await browser.new_page()
+    await _add_virtual_authenticator(page)
+    await _register(page, email:='alice@test.com')
+    assert email in await page.content()
+    await page.close()
+    print('✅ test_magic_link_and_passkey_reg')
+
+async def test_passkey_login(browser):
+    page = await browser.new_page()
+    await _add_virtual_authenticator(page)
+
+    await _register(page, email:='bob@test.com')
+    assert email in await page.content()
+
+    await page.click('text=Log out')
+    await page.wait_for_url('**/login**')
+    await page.click('text=Sign in with Passkey')
+    await page.wait_for_url('**/')
+    assert 'bob@test.com' in await page.content()
+    await page.close()
+    print('✅ test_passkey_login')
+
+async def test_skip_passkey_reg(browser):
+    page = await browser.new_page()
+    await _register(page, email:='carol@test.com', passkey=False)
+    assert email in await page.content()
+    await page.close()
+    print('✅ test_skip_passkey_reg')
+
+
+async def run_tests():
+    srv = threading.Thread(target=_start_server, daemon=True)
+    srv.start()
+    time.sleep(2)
+
+    async with async_playwright() as pw:
+        browser = await pw.chromium.launch(headless=True)
+        await test_magic_link_and_passkey_reg(browser)
+        await test_passkey_login(browser)
+        await test_skip_passkey_reg(browser)
+        await browser.close()
+    print('🎉 All tests passed!')
+
+if __name__ == '__main__':
+    asyncio.run(run_tests())