bump fixi version in docs for publication

Author: 1cg

README.md

@@ -0,0 +1,147 @@
+# 🚲 The Fixi Project
+
+[The Fixi Project](https://fixiproject.org) is a collection of five small web libraries based on other libraries we work
+on.
+
+Each library in The Fixi Project is constrained to have an *unminified, uncompressed* source size smaller
+than the excellent [Preact](https://preactjs.org) library's [min.gz'd size](https://bundlephobia.com/package/preact) 
+(~ 4.7kb).
+
+## The Libraries
+
+The five libraries each provide independent bits of functionality, but are designed to compose well. You can mix and
+match them as you see fit.
+
+### 🚲 `fixi.js` - supercharged HTML
+
+`fixi.js` is the original and main library in this collection. It is based on [htmx](https://htmx.org) and, like htmx,
+makes it possible to issue HTTP requests from elements in response to events.
+
+Here is a fixi-powered button:
+
+```html
+<button fx-action="/like" fx-method="post">
+    Like
+</button>
+```
+
+This button will issue an HTTP POSt to `/like` when it is clicked and will replace itself with whatever HTML content the
+server responds with. This simple concept is a surprisingly powerful way to build web applications.
+
+You can read more about how fixi works on its [homepage](https://github.com/bigskysoftware/fixi).
+
+### 🥊 `moxi.js` - inline scripting & simple reactivity
+
+`moxi.js` adds inline scripting and DOM-based reactivity. It is based on [hyperscript](https://hyperscript.org) and lets
+you put behavior directly on elements via `on-*` attributes, plus a `live` attribute that re-runs whenever the page
+changes.
+
+Here is a moxi-powered button:
+
+```html
+
+<button on-click="this.disabled = true; this.innerText = 'thanks!'">
+    Click me
+</button>
+```
+
+This button disables itself and updates its text when clicked, without a separate `<script>` block. Each `on-*` handler
+is compiled into an async function with access to helpers like `q()` (a proxy over a set of matched elements), `trigger()`,
+`wait()`, and `debounce()`.
+
+You can read more about how moxi works on its [homepage](https://github.com/bigskysoftware/moxi).
+
+### 📡 `ssexi.js` - streaming HTML & events
+
+`ssexi.js` is a companion library for fixi that
+adds [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) support. It is inspired
+by [htmx's SSE extension](https://github.com/bigskysoftware/htmx/blob/four/src/ext/hx-sse.js): whenever a fixi
+response comes back with `Content-Type: text/event-stream`, ssexi takes over the swap loop and streams each message into
+the target as it arrives.
+
+Here is an ssexi-powered log:
+
+```html
+
+<button fx-action="/events" fx-swap="beforeend" fx-target="#log">
+    Start
+</button>
+<div id="log"></div>
+```
+
+When `/events` responds with an SSE stream, each `data:` line is appended to `#log`. Messages with a named `event:`
+field fire DOM events (`fx:sse:<name>`) instead of swapping, which gives you a clean seam for JavaScript hooks like
+progress or "done" signals.
+
+You can read more about how ssexi works on its [homepage](https://github.com/bigskysoftware/ssexi).
+
+### ♻️ `paxi.js` - DOM patching (morphing)
+
+`paxi.js` adds a `morph` swap strategy to fixi. It is based on [idiomorph](https://github.com/bigskysoftware/idiomorph)
+and patches an existing subtree into the shape of a new one in place, matching elements by id rather than replacing them
+wholesale.
+
+Here is a paxi-powered swap:
+
+```html
+
+<button fx-action="/counter" fx-swap="morph" fx-target="#count">
+    Increment
+</button>
+<span id="count">0</span>
+```
+
+When the server responds with an updated `<span id="count">1</span>`, paxi morphs the existing span instead of replacing
+the node. The practical upshot is that focus, selection, input state, and event listeners survive a swap. It also allows
+you to use CSS transitions.
+
+You can read more about how paxi works on its [homepage](https://github.com/bigskysoftware/paxi).
+
+### 🐕 `rexi.js` - an ergonomic `fetch()` wrapper
+
+`rexi.js` is a small fluent wrapper around `fetch()`, inspired by [hyperscript's
+`fetch` command](https://hyperscript.org/commands/fetch/). It handles the usual boring parts of calling an HTTP endpoint
+from JavaScript: serializing a form or a plain object as a body, throwing on non-2xx responses, decoding the result, and
+aborting on demand.
+
+Here is a rexi-powered POST:
+
+```js
+let user = await post('/users', {name: 'carson'}).json()
+```
+
+rexi serializes the object as a JSON body, throws if the server returns an error status, and decodes the JSON response
+for you. It also accepts `FormData`, `URLSearchParams`, or a form `Element` directly as the body, so it slots neatly
+into moxi handlers and fixi-driven pages.
+
+You can read more about how rexi works on its [homepage](https://github.com/bigskysoftware/rexi).
+
+## 🧰 `the-fixi-project.js`
+
+All five libraries are also published as a single pre-concatenated, minified, and brotli-compressed bundle under the [
+`the-fixi-project`](https://www.npmjs.com/package/the-fixi-project) npm package:
+
+```html
+
+<script src="https://cdn.jsdelivr.net/npm/the-fixi-project/dist/the-fixi-project.min.js"></script>
+```
+
+The entire fixi project comes in at ~4.2kb when brotli-compressed.
+
+## Developing
+
+From a fresh checkout of this repo:
+
+```bash
+npm install         # installs playwright + terser (dev-only)
+npm run clone       # clones each sub-project repo into its directory
+npm test            # runs the full test suite across all libraries (headless)
+npm run build       # builds the all-in-one bundle into dist/
+npm run serve       # serves the project over http://localhost:8000
+```
+
+`npm test` accepts a subset of project names, so `npm test rexi paxi` runs only those two.
+
+## License
+
+BSD-0 (Zero-Clause BSD) across all libraries.

_scripts/status.mjs

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const sh = (cmd) => { try { return execSync(cmd, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() } catch { return null } }
+const fetchPublished = (pkg, version, path) => version ? sh(`curl -sf https://unpkg.com/${pkg}@${version}/${path}`) : null
+
+const rootPkg = JSON.parse(readFileSync(`${ROOT}/package.json`, 'utf8'))
+
+const ENTRIES = [
+    ['fixi-js',     'fixi/fixi.js',              'fixi.js'],
+    ['moxi-js',     'moxi/moxi.js',              'moxi.js'],
+    ['ssexi-js',    'ssexi/ssexi.js',            'ssexi.js'],
+    ['paxi-js',    'paxi/paxi.js',            'paxi.js'],
+    ['rexi-js',     'rexi/rexi.js',              'rexi.js'],
+    [rootPkg.name,  'dist/the-fixi-project.js',  'dist/the-fixi-project.js', rootPkg.version],
+]
+
+console.log('package         published    release?')
+console.log('--------------- ------------ --------')
+
+for (const [pkg, localPath, remotePath, localVersion] of ENTRIES) {
+    const local = readFileSync(`${ROOT}/${localPath}`, 'utf8')
+    const version = sh(`npm view ${pkg} version`) || ''
+    const published = fetchPublished(pkg, version, remotePath)
+    let status
+    if (!version) status = 'yes (unpublished)'
+    else if (published == null) status = '? (fetch failed)'
+    else if (published !== local) status = 'yes (source differs)'
+    else if (localVersion && localVersion !== version) status = `yes (local ${localVersion})`
+    else status = 'no'
+    console.log(`${pkg.padEnd(15)} ${(version || '-').padEnd(12)} ${status}`)
+}

_scripts/test.mjs

@@ -0,0 +1,73 @@
+import { chromium } from 'playwright'
+import { spawn } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const PROJECTS = process.argv.slice(2).length ? process.argv.slice(2) : ['fixi', 'moxi', 'ssexi', 'paxi', 'rexi']
+const PORT = 8765 + Math.floor(Math.random() * 200)
+
+const server = spawn('python3', ['-m', 'http.server', String(PORT), '--directory', ROOT], { stdio: 'ignore' })
+await new Promise((r) => setTimeout(r, 400))
+
+const browser = await chromium.launch()
+let exitCode = 0
+try {
+    for (const project of PROJECTS) {
+        const page = await browser.newPage()
+        const pageErrors = []
+        page.on('pageerror', (e) => pageErrors.push(e.message))
+        try {
+            await page.goto(`http://localhost:${PORT}/${project}/test.html`, { waitUntil: 'load', timeout: 10000 })
+            let prev = -1, stable = 0
+            for (let i = 0; i < 120 && stable < 4; i++) {
+                await new Promise((r) => setTimeout(r, 250))
+                const total = await page.evaluate(() => {
+                    const fixi = document.querySelectorAll('.test.passed, .test.failed').length
+                    const moxi = document.querySelectorAll('.pass, .fail').length
+                    return fixi + moxi
+                })
+                if (total === prev) stable++; else { stable = 0; prev = total }
+            }
+            const { passed, failed, failures } = await page.evaluate(() => {
+                const fixiPassed = document.querySelectorAll('.test.passed').length
+                const fixiFailed = [...document.querySelectorAll('.test.failed')].map((d) => ({
+                    name: d.querySelector('h3')?.textContent.replace(/\s+-\s+run.*$/, '').trim() || '(no h3)',
+                    error: d.querySelector('p:last-child')?.textContent || '',
+                }))
+                const moxiPassed = document.querySelectorAll('.pass').length
+                const moxiFailed = [...document.querySelectorAll('.fail')].map((s) => ({
+                    name: s.textContent.replace(/^[✗✓]\s*/, '').trim(),
+                    error: '',
+                }))
+                return {
+                    passed: fixiPassed + moxiPassed,
+                    failed: fixiFailed.length + moxiFailed.length,
+                    failures: [...fixiFailed, ...moxiFailed],
+                }
+            })
+            const mark = failed === 0 && passed > 0 ? '✓' : '✗'
+            console.log(`${mark} ${project}: ${passed} passed, ${failed} failed`)
+            if (failed > 0) {
+                for (const f of failures) console.log(`    ✗ ${f.name}${f.error ? `\n      ${f.error}` : ''}`)
+                exitCode = 1
+            }
+            if (pageErrors.length) {
+                for (const e of pageErrors) console.log(`    [pageerror] ${e}`)
+            }
+            if (passed === 0 && failed === 0) {
+                console.log(`    (no tests detected: check that ${project}/test.html loaded)`)
+                exitCode = 1
+            }
+        } catch (e) {
+            console.log(`✗ ${project}: runner error: ${e.message.split('\n')[0]}`)
+            exitCode = 1
+        } finally {
+            await page.close()
+        }
+    }
+} finally {
+    await browser.close()
+    server.kill()
+}
+process.exit(exitCode)

demo/README.md

@@ -0,0 +1,54 @@
+# demo
+
+A small Node-backed playground showing what the all-in-one bundle looks like against real
+server endpoints.
+
+## Running
+
+From the project root:
+
+```bash
+npm run demo
+```
+
+This rebuilds `dist/the-fixi-project.js` (so you're always exercising the latest) and starts the
+Node server on [http://localhost:8765](http://localhost:8765). No dependencies beyond
+Node's standard library; zero framework.
+
+## What's here
+
+| page            | exercises                                                                 |
+|-----------------|---------------------------------------------------------------------------|
+| `/` (index)     | landing page                                                              |
+| `/chat.html`    | fixi + ssexi + moxi - real shared chat over SSE broadcast                 |
+| `/bot.html`     | fixi + ssexi + moxi - POST that returns a streaming gibberish response    |
+| `/items.html`   | fixi + paxi + moxi - CRUD with bulk delete/toggle, morph-swap updates    |
+
+All three pages load the same `/dist/the-fixi-project.js` and get every library at once.
+
+## Layout
+
+```
+demo/
+├── server.mjs         # zero-dep Node HTTP server: chat, bot, items CRUD, static
+├── public/            # served from /
+│   ├── index.html
+│   ├── chat.html
+│   ├── bot.html
+│   └── items.html
+└── README.md          # you are here
+```
+
+## Endpoints
+
+| route                    | method | purpose                                                 |
+|--------------------------|--------|---------------------------------------------------------|
+| `/chat/stream`           | GET    | SSE stream of `fx:sse:message` frames, each rendered HTML |
+| `/chat/send`             | POST   | broadcast a new chat message to all subscribers          |
+| `/bot/ask`               | POST   | POST that returns `text/event-stream` of gibberish tokens |
+| `/items`                 | GET    | render the items table as HTML                          |
+| `/items`                 | POST   | add an item, return the updated table                   |
+| `/items/bulk/delete`     | POST   | delete items whose ids are in the `ids` form field      |
+| `/items/bulk/toggle`     | POST   | toggle `done` on items whose ids are in `ids`           |
+| `/dist/*`              | GET    | serves the root `dist/` build output (the bundle)       |
+| everything else          | GET    | served from `public/`                                   |

demo/apps/bot.mjs

@@ -0,0 +1,32 @@
+import { esc, sseStart } from '../lib/util.mjs'
+
+const VOCAB = [
+    'the', 'a', 'and', 'of', 'in', 'that', 'is', 'it', 'for', 'with', 'attention',
+    'transformer', 'vector', 'embedding', 'token', 'latent', 'space', 'context',
+    'model', 'neural', 'gradient', 'optimization', 'emerges', 'operates', 'considers',
+    'synthesizes', 'minimalist', 'hypermedia', 'recursively', 'moreover', 'however',
+    'fundamentally', 'paradigm', 'coherent', 'framework', 'fluidly', 'notably',
+    'when', 'where', 'while', 'therefore', 'which', 'arguably', 'ultimately',
+    'small', 'dense', 'lean', 'composable', 'elegant', 'obvious', 'not-obvious',
+]
+let words = (n) => {
+    let out = []
+    for (let i = 0; i < n; i++) out.push(VOCAB[Math.floor(Math.random() * VOCAB.length)])
+    out[out.length - 1] += '.'
+    return out
+}
+
+export let stream = (req, res, question) => {
+    sseStart(res)
+    if (!question) { res.end(); return }
+    // first frame: the user's question (CSS gives it the "You: " prefix)
+    res.write(`data: <div class="you">${esc(question)}</div>\n\n`)
+    // then stream the gibberish answer one token per frame
+    let ws = words(15 + Math.floor(Math.random() * 25))
+    let i = 0
+    let timer = setInterval(() => {
+        if (i >= ws.length) { clearInterval(timer); res.end(); return }
+        res.write(`data: <span class="tok">${esc(ws[i++])} </span>\n\n`)
+    }, 60)
+    req.on('close', () => clearInterval(timer))
+}

demo/apps/chat.mjs

@@ -0,0 +1,24 @@
+import { esc, sseStart } from '../lib/util.mjs'
+
+let listeners = new Set()
+let history = []
+let renderMsg = (m) => `<div class="msg"><strong>${esc(m.name)}</strong>: ${esc(m.text)} <small>${m.at}</small></div>`
+
+export let send = (name, text) => {
+    let msg = {
+        name: (name || 'anon').slice(0, 40),
+        text: (text || '').slice(0, 400),
+        at:   new Date().toLocaleTimeString(),
+    }
+    history.push(msg)
+    if (history.length > 50) history.shift()
+    let payload = renderMsg(msg)
+    for (let r of listeners) r.write(`data: ${payload}\n\n`)
+}
+
+export let stream = (req, res) => {
+    sseStart(res)
+    for (let m of history) res.write(`data: ${renderMsg(m)}\n\n`)
+    listeners.add(res)
+    req.on('close', () => listeners.delete(res))
+}