@christianirack/brainllm-runtime 0.8.5 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christianirack/brainllm-runtime",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "The BRAINLLM runtime for the Rust-built web compiler for LLMs: dependency-free ES modules (signals, DOM, router, data, forms, channels). The brain binary embeds this same version.",
   "type": "module",
   "exports": {

package/server/server.mjs

@@ -396,7 +396,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
   let proxyBytes = 0, streams = 0
   // A file transfer lasts as long as the client needs, so streams have their own sockets and budget and never hold API slots.
   const streamAgent = new HttpAgent({ keepAlive: false, maxSockets: 32, maxTotalSockets: 32 })
-  const REQUEST_HEADERS = ['origin','authorization','x-api-key','content-type','content-length','x-brain-rpc','accept','if-match','if-none-match','x-brain-webhook-id','x-brain-webhook-timestamp','x-brain-webhook-signature','user-agent','dnt','sec-gpc','cf-ipcountry']
+  const REQUEST_HEADERS = ['origin','authorization','x-api-key','content-type','content-length','x-brain-rpc','x-brain-captcha','x-brain-login-grant','accept','if-match','if-none-match','x-brain-webhook-id','x-brain-webhook-timestamp','x-brain-webhook-signature','user-agent','dnt','sec-gpc','cf-ipcountry']
   const FILE_HEADERS = ['range','if-range','if-modified-since','if-unmodified-since']
   const RESPONSE_HEADERS = ['content-type','content-disposition','allow','retry-after','www-authenticate','location','etag','last-modified','clear-site-data','cache-control']
   const FILE_RESPONSE_HEADERS = ['content-length','content-range','accept-ranges','vary','content-security-policy','x-content-type-options','cross-origin-resource-policy','referrer-policy']
@@ -531,6 +531,22 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       } catch { outgoing?.destroy(); finish(true) }
     })
   }
+  const readCache = new Map()
+  let readCacheBytes = 0
+  const rememberRead = (path, etag, body) => {
+    readCacheBytes -= readCache.get(path)?.body.length || 0
+    readCache.delete(path)
+    if (body.length > 1024 * 1024) return
+    readCache.set(path, { etag, body })
+    readCacheBytes += body.length
+    while (readCache.size > 256 || readCacheBytes > 16 * 1024 * 1024) {
+      const oldest = readCache.keys().next().value
+      readCacheBytes -= readCache.get(oldest).body.length
+      readCache.delete(oldest)
+    }
+  }
+  // Reaches the request helper of a resource client without adding a method anyone can see on it.
+  const OPERATION_CALL = Symbol('operation')
   const resource = (incoming, response, rid, name, serviceKey) => {
     if (typeof name !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(name)) throw new HttpError(400, 'Invalid native resource name')
     const idPath = id => {
@@ -538,7 +554,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       return '/api/' + name + '/' + id
     }
     const request = async (method, path, body, notFound) => {
-      if (response.writableEnded || response.destroyed) throw new HttpError(409, 'The server request has ended')
+      if (response.writableEnded || response.destroyed) throw Object.assign(new HttpError(409, 'The server request has ended'), { clientGone: true })
       if (method !== 'GET' && incoming.method !== 'POST') throw new HttpError(405, 'Native writes require a server function called through POST')
       let bytes = Buffer.alloc(0)
       if (body !== undefined) {
@@ -559,7 +575,18 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       }
       let req = outgoing()
       let value
+      // Revalidated reads (ETag/304): a read made without any credential remembers its body, so an unchanged answer is not
+      // sent or parsed again. Each answer is parsed afresh, so `load` can change what it gets. Signed-in reads stay out.
+      const remembers = method === 'GET' && !req.headers.authorization && !req.headers.cookie
+      const known = remembers ? readCache.get(path) : undefined
+      const conditional = r => (known ? (r.headers['if-none-match'] = known.etag, r) : r)
+      conditional(req)
       const answered = (_res, status, data, headers) => {
+          if (status === 304 && known) {
+            readCache.delete(path); readCache.set(path, known)
+            value = JSON.parse(known.body)
+            return
+          }
           if (status === 422) {
             // the backend's own field messages (never driver text): a server function that rethrows answers 422 {errors}
             let fields
@@ -574,11 +601,13 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
             try { answer = JSON.parse(data.toString('utf8'))?.error } catch {}
             const code = typeof answer?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(answer.code) ? answer.code : undefined
             const fix = code && typeof answer.fix === 'string' ? answer.fix.slice(0, 512) : undefined
-            throw new HttpError(status >= 400 && status < 500 ? status : 503, NATIVE_FAILED, { code, fix })
+            const wait = Number(headers['retry-after'])
+            throw new HttpError(status >= 400 && status < 500 ? status : 503, NATIVE_FAILED, { code, fix, temporary: status === 429 || status === 503, ...(wait > 0 ? { retryAfter: wait } : {}) })
           }
           if (status === 204) { value = null; return }
           if (!String(headers['content-type'] || '').startsWith('application/json')) throw new HttpError(502, 'Native resource response must be JSON')
           try { value = JSON.parse(data.toString('utf8')) } catch { throw new HttpError(502, 'Native resource response is invalid') }
+          if (remembers && typeof headers.etag === 'string') rememberRead(path, headers.etag, data)
       }
       try {
         // A restarting backend refuses connections for a few seconds: a read waits for it instead of failing the page.
@@ -590,20 +619,23 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
             if (method !== 'GET' || wait > 2000 || stopped || response.destroyed || !['ECONNREFUSED', 'ECONNRESET'].includes(e?.transport)) throw e
             req.destroy()
             await new Promise(done => setTimeout(done, wait))
-            req = outgoing()
+            req = conditional(outgoing())
           }
         }
       } catch (e) {
         // A read that failed: `load` may catch it and render anyway, so the page answer says what happened (ssr below).
-        if (method === 'GET' && !(e?.status >= 400 && e.status < 500)) {
-          const seen = incoming.$brainFailedReads || (incoming.$brainFailedReads = { reads: 0, backendCode: undefined, transport: undefined })
+        // "Not now" is the backend limiting or unavailable: the same request can succeed later, so a page must not stand in for it.
+        if (e && (e.transport || e.status === 504 || e.code === 'BRIDGE_BUSY')) e.temporary = true
+        if (method === 'GET' && (e?.temporary || !(e?.status >= 400 && e.status < 500))) {
+          const seen = incoming.$brainFailedReads || (incoming.$brainFailedReads = { reads: 0, backendCode: undefined, transport: undefined, temporary: false, retryAfter: undefined })
           seen.reads++
           seen.backendCode ??= e?.code
           seen.transport ??= e?.transport
+          if (e?.temporary) { seen.temporary = true; seen.retryAfter = Math.max(seen.retryAfter || 0, e.retryAfter || 0) || undefined }
         }
         throw e
       } finally { req.destroy() }
-      if (response.destroyed || response.writableEnded) throw new HttpError(409, 'The server request has ended')
+      if (response.destroyed || response.writableEnded) throw Object.assign(new HttpError(409, 'The server request has ended'), { clientGone: true })
       return value
     }
     const names = (value, label) => {
@@ -613,6 +645,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       return list.join(',')
     }
     return Object.freeze({
+      [OPERATION_CALL]: (operation, input) => request('POST', '/_brain/operations/' + operation, input),
       // the HTTP list contract (docs/backend/filters.md, sorting.md, pagination.md): the backend validates declared
       // filters and sorts and answers 422 {errors}; this only rejects shapes the query string cannot express
       list(options = {}) {
@@ -690,17 +723,32 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       },
     })
   }
-  async function login(incoming,response,rid,credentials) {
+  // The token of the captcha widget: passed by the server function, or the header the page sent with this request.
+  const captchaHeaders = (incoming,options) => {
+    const token = options?.captcha ?? incoming.headers['x-brain-captcha']
+    if (token === undefined) return {}
+    if (typeof token !== 'string' || !token || Buffer.byteLength(token) > 8192 || /[\x00-\x1f\x7f]/.test(token)) throw new HttpError(403,'Complete the captcha again',{code:'CAPTCHA_FAILED'})
+    return {'x-brain-captcha':token}
+  }
+  const captchaRefusal = (status,data) => {
+    let code
+    try {code=JSON.parse(data.toString('utf8'))?.error?.code}catch{}
+    if(status===403&&code==='CAPTCHA_FAILED')return new HttpError(403,'Complete the captcha again',{code})
+    if(status===503&&code==='CAPTCHA_UNAVAILABLE')return new HttpError(503,'The captcha could not be verified. Nothing was changed; retry shortly',{code})
+    return null
+  }
+  async function login(incoming,response,rid,credentials,options) {
     if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'B0742: Sign in through a same-origin POST server function')
     if (incoming.$nativeLoginStarted || incoming.$nativeLogout) throw new HttpError(409,'Use one authentication change per server request')
     if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials) || Object.keys(credentials).some(key=>!['email','password'].includes(key)) || typeof credentials.email !== 'string' || typeof credentials.password !== 'string' || Buffer.byteLength(credentials.email)>254 || Buffer.byteLength(credentials.password)>1024) throw new HttpError(422,'Enter a valid email and password')
     const origin=bridgeOrigin(incoming,rid,'Sign in through a same-origin POST server function')
     incoming.$nativeLoginStarted=true
     const bytes=Buffer.from(JSON.stringify({email:credentials.email,password:credentials.password}))
-    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length)}
+    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);const grant=incoming.$nativeLoginGrant?.email===credentials.email?{'x-brain-login-grant':incoming.$nativeLoginGrant.grant}:captchaHeaders(incoming,options);delete incoming.$nativeLoginGrant;request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length),...grant}
     let user
     try {
       await proxy(request,response,new URL('/_brain/auth/login',target),rid,(_res,status,data,headers)=>{
+        const refusal=captchaRefusal(status,data);if(refusal)throw refusal
         if(status===403)throw new HttpError(403,"B0740: the backend refused this site's origin; fix: add the site origin to backend.origins in brain.json. The backend log has the seen and allowed origins. Run brain explain B0740")
         if(status!==200)throw new HttpError(status===400||status===401||status===422?401:status===429?429:503,status===429?'Too many attempts. Wait before trying again.':status===400||status===401||status===422?'Wrong email or password':'Sign-in is temporarily unavailable')
         let payload
@@ -718,21 +766,26 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
   // Creates the account and leaves the session alone: `await ctx.backend.signup(v); return ctx.backend.login(v)` signs in
   // too. A refused address is the email field's error: the same 422 for an invalid one and for one already taken, and no
   // more than any signup form reveals by succeeding.
-  async function signup(incoming,response,rid,credentials) {
+  async function signup(incoming,response,rid,credentials,options) {
     if (incoming.method !== 'POST' || response.headersSent || response.writableEnded || response.destroyed) throw new HttpError(403,'B0742: Sign up through a same-origin POST server function')
     if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials) || Object.keys(credentials).some(key=>!['email','password'].includes(key)) || typeof credentials.email !== 'string' || typeof credentials.password !== 'string' || Buffer.byteLength(credentials.email)>254 || Buffer.byteLength(credentials.password)>1024) throw new HttpError(422,'Enter a valid email and password')
     if (Buffer.byteLength(credentials.password) < 12 || Buffer.byteLength(credentials.password) > 1024) throw new HttpError(422,'Use a password of 12 to 1024 bytes',{errors:{password:'Use a password of 12 to 1024 bytes'}})
     const origin=bridgeOrigin(incoming,rid,'Sign up through a same-origin POST server function')
     const bytes=Buffer.from(JSON.stringify({email:credentials.email,password:credentials.password}))
-    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length)}
+    const request=Readable.from([bytes]);request.method='POST';request.$brainForwardedFor=forwardedFor(incoming);request.headers={origin,accept:'application/json','content-type':'application/json','content-length':String(bytes.length),...captchaHeaders(incoming,options)}
     let user
     try {
       await proxy(request,response,new URL('/_brain/auth/signup',target),rid,(_res,status,data)=>{
+        const refusal=captchaRefusal(status,data);if(refusal)throw refusal
         if(status===403)throw new HttpError(403,"B0740: the backend refused this site's origin; fix: add the site origin to backend.origins in brain.json. Run brain explain B0740")
         if(status===422)throw new HttpError(422,'This email cannot be used',{errors:{email:'This email cannot be used'}})
         if(status===429)throw new HttpError(429,'Too many attempts. Wait before trying again.')
         if(status!==200&&status!==201)throw unavailable()
-        try {user=safeUser(JSON.parse(data.toString('utf8'))?.user)}catch{throw unavailable()}
+        try {
+          const payload=JSON.parse(data.toString('utf8'));user=safeUser(payload?.user)
+          // The login that follows in this same request needs no second challenge; the grant never reaches the page.
+          if(typeof payload?.login_grant==='string')incoming.$nativeLoginGrant={email:credentials.email,grant:payload.login_grant}
+        }catch{throw unavailable()}
       },16384)
     } finally {request.destroy();bytes.fill(0)}
     return {user}
@@ -791,8 +844,13 @@ export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
       return bucketClient(target, serviceKey, bucket)
     },
     slugRedirect: (name, slug) => resource(incoming, response, rid, name).slugRedirect(slug),
-    login: credentials => login(incoming, response, rid, credentials),
-    signup: credentials => signup(incoming, response, rid, credentials),
+    // A declared operation, as this visitor (docs/backend/transactions.md).
+    operation: (name, input = {}) => {
+      if (typeof name !== 'string' || !/^[a-z][a-z0-9_]{0,47}$/.test(name)) throw new HttpError(400, 'Invalid operation name')
+      return resource(incoming, response, rid, 'operations')[OPERATION_CALL](name, input)
+    },
+    login: (credentials, options) => login(incoming, response, rid, credentials, options),
+    signup: (credentials, options) => signup(incoming, response, rid, credentials, options),
     google: Object.freeze({
       challenge: () => googleChallenge(incoming, response, rid),
       login: values => googleLogin(incoming, response, rid, values),
@@ -1098,6 +1156,7 @@ export function createServer(o = {}) {
   // `<meta cache="N">` (route.cache, #235): the SSR HTML of an anonymous GET is kept N s per URL (and language) and
   // served again; between N and 2N s the copy is served while a fresh one renders in the background
   // (stale-while-revalidate). Never for requests with a session cookie or Authorization, forms or error pages.
+  const FILLING = new Map()
   const SSRC = new Map(), SSRC_MAX = 500, SSRC_BYTES = 32 * 1024 * 1024, SSRC_ENTRY = 1024 * 1024
   let ssrBytes = 0
   async function cached(req, res, route, params, url, rid) {
@@ -1140,10 +1199,29 @@ export function createServer(o = {}) {
       if (age >= ms && !c.busy) (c.busy = true), fill().finally(() => (c.busy = false))
       return serve(c)
     }
-    c = await fill()
-    return c ? serve(c) : ssr(req, res, route, params, url, rid, null, 200, null, true) // a redirect or an error: as usual
-  }
-  const anonymous = req => req.method === 'GET' && !req.headers.authorization && !req.headers.cookie
+    // Cold: the first request renders and the others that arrive meanwhile wait for it, so a burst runs load() once.
+    // Only a shareable result is shared (a private one holds its visitor's cookie); anything else answers as usual, one by one.
+    const running = FILLING.get(key)
+    if (running) {
+      c = await running
+      if (c?.cacheable) return serve(c)
+      return ssr(req, res, route, params, url, rid, null, 200, null, true)
+    }
+    const filling = fill().finally(() => FILLING.delete(key))
+    FILLING.set(key, filling)
+    c = await filling
+    if (c) return serve(c)
+    // the first render already asked the backend and logged why; another would only spend more of a limit it just hit
+    if (req.$brainFailedReads?.temporary) return comeBackPage(req, res, route, params, url, rid)
+    delete req.$brainFailedReads
+    return ssr(req, res, route, params, url, rid, null, 200, null, true) // a redirect or an error: as usual
+  }
+  const comeBackPage = (req, res, route, params, url, rid) => {
+    res.setHeader('retry-after', String(Math.min(Math.ceil(req.$brainFailedReads.retryAfter) || 5, 3600)))
+    res.setHeader('cache-control', 'no-store')
+    return errorPage(req, res, route, params, url, rid, 503)
+  }
+  const anonymous = req => (req.method === 'GET' || req.method === 'HEAD') && !req.headers.authorization && !req.headers.cookie
 
   async function ssr(req, res, route, params, url, rid, forms = null, status = 200, fixed = null, nocache = false) {
     // the route's preloads (the same Link values as _headers): on the response, where hosts turn them into early hints,
@@ -1184,11 +1262,13 @@ export function createServer(o = {}) {
     }
     // what load() thrown or returned instead of props answers: redirect, notFound() (F11), deliberate status, failure
     const loadOutcome = e => {
+      // the visitor left (a closed tab, an aborted prefetch): nobody reads an answer, and it is no failure of the app
+      if (e && e.clientGone && res.destroyed) return log('info', 'client left during load', { rid, path: url.pathname })
       if (e && e.redirect) return send(res, e.status || 303, '', { location: withBase(linkTo(route, redirect(e.redirect, e.status ?? 303).redirect)), ...ctx.session.headers() })
       if ((e instanceof HttpError && e.status === 404) || (e && e.notFound === true)) return missing(req, res, e) // `notFound()` 404 / `gone()` 410
       // the backend or another service said "not now": a temporary 503 tells crawlers to come back, a 500 tells them it broke
       // a status the page chose itself (`new HttpError(429)`) stays as it is, with the same hint to come back
-      if (e && (e.status === 429 || e.status === 503) && !(e instanceof HttpError) && !res.headersSent) {
+      if (e && (e.status === 429 || e.status === 503) && (!(e instanceof HttpError) || e.temporary) && !res.headersSent) {
         log('warn', 'load temporarily unavailable', { rid, path: url.pathname, status: 503, ...trace(e) })
         res.setHeader('retry-after', String(Math.min(Math.ceil(e.retryAfter) || 5, 3600)))
         res.setHeader('cache-control', 'no-store')
@@ -1211,6 +1291,7 @@ export function createServer(o = {}) {
     }
     if (props && (props.redirect || props.notFound === true)) return loadOutcome(props) // `return redirect()` / `return notFound()`
     if (req.$brainFailedReads && !fixed) {
+      if (status === 200 && req.$brainFailedReads.temporary) return loadOutcome(comeBack(req, rid, url))
       softFailure(req, rid, url, status)
       extra = { ...extra, 'cache-control': 'no-store' } // what it rendered instead is not worth keeping
     }
@@ -1242,7 +1323,13 @@ export function createServer(o = {}) {
   // (head, CSS, layout shell) is sent, the view when load() ends. The status and headers are out by then, so a late
   // redirect becomes location.replace and a late failure an inline notice with the request id (both logged); load()
   // cannot change the session on a streamed route.
-  // `load` caught a failed backend read and rendered: the status it asked for stands, the log says what is behind it.
+  // `load` caught a read the backend refused for now (429, 503, unreachable) and rendered without its data: a 200 would put
+  // that page in the index and tell a crawler to keep going, so it answers 503 with Retry-After. The log says what was behind it.
+  const comeBack = (req, rid, url) => {
+    softFailure(req, rid, url, 503)
+    return Object.assign(new Error('A backend read failed for now'), { status: 503, retryAfter: req.$brainFailedReads.retryAfter })
+  }
+  // `load` caught any other failed backend read and rendered: the status it asked for stands, the log says what is behind it.
   const softFailure = (req, rid, url, status) => {
     const { reads, backendCode, transport } = req.$brainFailedReads
     log('warn', 'page rendered after a failed backend read', { rid, path: url.pathname, status, reads, backendCode, transport, fix: 'load caught the failure and returned other props; let it throw for a 503, or show that the data is missing' })
@@ -1257,6 +1344,7 @@ export function createServer(o = {}) {
     const early = await Promise.race([loadP.then(v => ({ v }), e => ({ e })), new Promise(r => (timer = setTimeout(r, STREAM_HOLD)))])
     clearTimeout(timer)
     if (early && (early.e !== undefined || (early.v && (early.v.redirect || early.v.notFound === true)))) return outcome(early.e !== undefined ? early.e : early.v)
+    if (early && req.$brainFailedReads?.temporary) return outcome(comeBack(req, rid, url))
     const seoF = sm.seo || (await load(route.view)).default.seo
     if (route.i18n) await load(route.i18n)
     const nonce = randomBytes(16).toString('base64'), n = h => h.replace(/<script(?![^>]*\bnonce=)/g, `<script nonce="${nonce}"`)
@@ -1313,6 +1401,7 @@ export function createServer(o = {}) {
       if (e && e.redirect) return end(`<meta name="robots" content="noindex"><script>location.replace(${jsonInHtml(withBase(linkTo(route, redirect(e.redirect, e.status ?? 303).redirect)))})</script>`)
       // a streamed page already sent its 200 head: the region gets the not-found notice and the page is noindex
       if (e && e.notFound === true) return end(`<meta name="robots" content="noindex"><p role="alert" class="brain-fallback">Page not found.</p>`, {}, bottom.replace(/<script type="module">(?:(?!<\/script>)[\s\S])*?brain-view[\s\S]*?<\/script>/g, ''))
+      if (e && e.clientGone && res.destroyed) return log('info', 'client left during load', { rid, path: url.pathname })
       log('error', 'load failed (streamed)', { rid, path: url.pathname, status: 200, ...trace(e) }) // headers already out
       return fail()
     }
@@ -1320,8 +1409,10 @@ export function createServer(o = {}) {
     try {
       const { body, failed } = await (queue = queue.then(() => render(route, props, null, at), () => render(route, props, null, at)))
       for (const f of failed || []) log('error', 'component failed during SSR', { rid, path: url.pathname, comp: f.comp, where: f.w, ...trace(f.e) })
+      // the 200 is already out: a page rendered without its data at least stays out of the index
+      const stale = req.$brainFailedReads?.temporary ? '<meta name="robots" content="noindex">' : ''
       const pm = params && Object.keys(params).length ? `<meta name="brain-params" content="${esc(JSON.stringify(params))}">` : ''
-      end(pm + body, props)
+      end(stale + pm + body, props)
     } catch (e) {
       log('error', 'render failed (streamed)', { rid, path: url.pathname, status: 200, ...trace(e) })
       await fail()

package/templates/captcha.js

@@ -0,0 +1,87 @@
+// Application-owned captcha adapter for widgets with the common render/reset/remove API. The token stays in memory, is
+// never logged or stored, and is good for one submit: reset after every submit, whatever it answered.
+const PROVIDERS = {
+  turnstile: { global: 'turnstile', script: 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit' },
+  hcaptcha: { global: 'hcaptcha', script: 'https://js.hcaptcha.com/1/api.js?render=explicit' },
+  recaptcha: { global: 'grecaptcha', script: 'https://www.google.com/recaptcha/api.js?render=explicit' }
+}
+const LOAD_MS = 8000
+const loading = new Map()
+const sdk = provider => {
+  const ready = () => typeof globalThis[provider.global]?.render === 'function'
+  if (ready()) return Promise.resolve(globalThis[provider.global])
+  if (loading.has(provider.script)) return loading.get(provider.script)
+  const started = new Promise((resolve, reject) => {
+    const doc = globalThis.document, existing = doc.querySelector(`script[src="${provider.script}"]`)
+    const script = existing || doc.createElement('script')
+    const done = failed => {
+      clearTimeout(timer); clearInterval(poll); script.removeEventListener('error', fail)
+      loading.delete(provider.script)
+      if (failed) { if (!existing) script.remove(); reject(Error('The captcha could not load')) }
+      else resolve(globalThis[provider.global])
+    }
+    const fail = () => done(true)
+    // The global appears after `load`, and grecaptcha later still, so readiness is polled rather than assumed.
+    const poll = setInterval(() => { if (ready()) done(false) }, 50)
+    const timer = setTimeout(fail, LOAD_MS)
+    script.addEventListener('error', fail)
+    if (!existing) { script.src = provider.script; script.async = true; script.defer = true; doc.head.appendChild(script) }
+  })
+  loading.set(provider.script, started)
+  return started
+}
+/** A same-origin JSON POST with the captcha headers. Answers `{ status, body }`; the caller decides what a failure means. */
+export async function post(path, body, headers = {}) {
+  const base = globalThis.document?.querySelector('meta[name=brain-base]')?.getAttribute('content') || ''
+  if (base && (!base.startsWith('/') || base.startsWith('//') || /[\\?#\x00-\x20]/.test(base))) throw Error('Invalid application base')
+  const response = await fetch(base.replace(/\/$/, '') + path, { method: 'POST', credentials: 'same-origin', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body) })
+  return { status: response.status, body: await response.json().catch(() => null) }
+}
+export default {
+  post,
+  mount(element, initial = {}) {
+    let props = initial, alive = true, api = null, id = null, nonce = 0
+    const report = (status, token = '') => {
+      if (!alive) return
+      element.setAttribute('aria-busy', String(status === 'loading'))
+      if (typeof props.onState === 'function') props.onState({ status, token })
+    }
+    const start = async () => {
+      const mine = ++nonce
+      const provider = PROVIDERS[props.provider || 'turnstile']
+      if (!provider || !props.sitekey) return report('error')
+      report('loading')
+      try {
+        const loaded = await sdk(provider)
+        if (!alive || mine !== nonce) return
+        api = loaded
+        // No provider `ready()`: the poll in `sdk` already waited for `render`, and Turnstile's refuses a script loaded async.
+        id = api.render(element, {
+          sitekey: props.sitekey,
+          callback: token => report('verified', typeof token === 'string' ? token : ''),
+          'expired-callback': () => report('expired'),
+          'timeout-callback': () => report('expired'),
+          'error-callback': () => { report('error'); return true }
+        })
+        report('ready')
+      } catch { if (alive && mine === nonce) report('error') }
+    }
+    const reset = () => {
+      if (id === null) return start()
+      report('ready')
+      try { api.reset(id) } catch { report('error') }
+    }
+    start()
+    return {
+      update(next = {}) {
+        props = { ...props, ...next }
+        if (next.action === 'reset') reset()
+      },
+      destroy() {
+        alive = false; nonce++
+        try { if (id !== null && typeof api?.remove === 'function') api.remove(id) } catch {}
+        element.replaceChildren()
+      }
+    }
+  }
+}