Add hx-vals support along with configurable SSE (POST + Auth)/WS connections

[XChikuX]

Summary

This update enhances the SSE and WS extensions to provide full control over the connection request, addressing limitations regarding query parameters, custom headers, and polyfill integration for methods like POST.

Description

Previously, the SSE and WS extensions offered no mechanism to influence the connection handshake, making it impossible to pass hx-vals as query parameters (#34), inject Authorization headers (#132), or support POST-capable polyfills like sse.js (#139, #143).

Changes:

• SSE/WS hx-vals handling: ensureEventSource now collects hx-vals/hx-vars via api.getExpressionVars and appends them (URL-encoded) to the connect URL.
• htmx:sseConfigConnect & htmx:wsConfigConnect: New cancelable events fired before connection creation. Handlers can modify the URL, mutate options, or call preventDefault() to abort.
• htmx.createEventSource API: The signature is extended to pass an options object, allowing polyfills to receive method, headers, and payload.
• Documentation: Replaced README files with comprehensive reference docs and clear examples for sse.js integration.

Example: POST SSE connection with Authorization header via sse.js

htmx.createEventSource = function (url, options) {
  return new SSE(url, options) // sse.js polyfill
}

document.body.addEventListener('htmx:sseConfigConnect', function (evt) {
  evt.detail.options.method  = 'POST'
  evt.detail.options.headers = { Authorization: 'Bearer ' + getToken() }
  evt.detail.options.payload = JSON.stringify(evt.detail.parameters)
  evt.detail.url = evt.detail.url.split('?')[0] // move hx-vals into the body
})

<div hx-ext="sse"
     sse-connect="/api/stream"
     hx-vals='{"query": "kittens"}'
     sse-swap="result">Waiting…</div>

Htmx version: Latest
Used extension(s) version(s): SSE, WS

Corresponding issue: #34, #132, #139, #143

Testing

• New Tests: Added 9 new Mocha tests for SSE and 6 for WS, covering URL construction, payload verification, event handling, and connection cancellation.
• Manual Testing: Verified that hx-vals are correctly appended to the URL and that the htmx:sseConfigConnect event correctly intercepts the connection lifecycle.

Checklist

• I have read the contribution guidelines
• I ran the test suite locally (npm run test) and verified that it succeeded

[netlify]

✅ Deploy Preview for htmx-extensions canceled.

Name	Link
🔨 Latest commit	c8c52c5
🔍 Latest deploy log	https://app.netlify.com/projects/htmx-extensions/deploys/6a0f50cf462a8d00082aaff6

[XChikuX]

Full Discosure:

This is a PR generated by the github copilot subscription using Claude: opus 4.7

PR passes existing tests, as well as additional tests added for both SSE and WS.

I reviewed the changes and they seem minimally invasive with useful additions. It should close all the mentioned issues above.

@Telroshan @adonespitogo @GrimalDev @bradleyjkemp @elieobeid7

Please let me know if there are any concerns with code quality.

Recommended SSE polyfill: https://github.com/mpetazzoni/sse.js/ (Apache 2.0 license)

Possible future additions to this PR:
#27