gina 0.5.21 → 0.5.22

package/CHANGELOG.md

@@ -6,6 +6,21 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.22 - 2026-07-21
+### Added
+* The `settings.i18n.cultures` allowlist is now honoured: a non-empty array constrains which cultures the user-signal negotiation steps (URL prefix, cookie, Accept-Language) may match — e.g. a staged rollout keeps a shipped-but-unlaunched catalog out of negotiation. `null` or `[]` keep the historical derive-from-loaded-catalogs behavior, and the bundle-default step (`settings.region.culture`) is never constrained. The whole `i18n` block (cookieName, devMissingKey, fallbackChain, cultures) is now declared in the published settings.json schema. Restart to apply.
+### Changed
+* The runtime pins now live under the standard `engines` manifest key (formerly the non-standard singular `engine`, which npm and Bun tooling ignore), so unsupported runtimes get install-time warnings (Node `>= 22 <27`, Bun `>= 1.2`). Scaffolded project manifests — the `project:add` template and the install-time fallback package.json — carry the standard object-form key too, and `image:build` reads `engines` with a legacy `engine` fallback.
+### Fixed
+* Popin: reopening an AJAX popin no longer renders the previous open's content — the preload cache was a one-generation-lagging store (every open after the first paid for a network fetch yet rendered the body fetched around the PREVIOUS open, because the leftover entry blocked the fresh warm's dedup check). The cache entry now dies with the open it warmed: close clears the popin's content-URL slot and re-sweeps it once the teardown has drained (the close-time focus-return and pointer re-hover re-warm the slot with close-era content within a millisecond — measured), so every open renders current content; a trigger annotated data-gina-dialog-preload="false" additionally skips the cache read entirely at open, making "false" a hard always-refetch guarantee (its GET always happens at open time, never from a sibling trigger's warm). Warmed-but-never-opened entries keep the documented page-lifetime semantics. Costs at most one extra idempotent GET per close on default triggers; browser-bundled — rebuild your bundles to pick it up (#B139)
+* FormValidator: numbered `is` aliases no longer collapse onto the bare `is` error key on re-validation — the alias handshake re-arms per invocation instead of once per install, so on conditional (`_case_`) re-evaluations and recursive passes each `is<N>` rule keeps its own distinct error key, and the last-declared rule's message no longer renders twice (its own key plus a mirrored bare `is` key carrying the same string; the digit was irrelevant — whichever numbered rule was declared last doubled). Browser-bundled — rebuild your bundles to pick it up (#B138)
+* Multipart binary uploads now arrive byte-identical: file payloads are no longer string-decoded on their way to disk. The request stream stays raw for multipart bodies and the per-file write pipeline passes chunks through verbatim, so content that is not valid UTF-8 — images, PDFs, archives — is no longer mangled and re-sized (pure-ASCII payloads were unaffected, which is what hid the corruption). req.files[].size now reports the real on-disk byte count instead of a decoded character count.
+* FormValidator #B87 — the `query` rule's async result path is now blanket-guarded so a throw can never hang the submit pass. The XHR result lands asynchronously: by processing time the form may have been unbound or the field detached (e.g. a popin closed mid-flight) and the response body is backend-controlled — any throw while handling it left the `asyncCompleted` waiter unfired and the submit path hung for the whole pass (the old `xhr.onload` catch rethrew instead of releasing). The result handler is now a guarded wrapper that warns and releases the waiter on failure (field state as-is; the server re-validates on submit), `xhr.onerror` is guarded the same way, the query value normalisation only lowercases strings (a boolean checkbox routed through a `query` rule no longer throws), and `compileError()` tolerates a non-string error. Browser-bundled: consumers pick the fixes up at their next bundle re-bake.
+* FormValidator #B125 — the #49 checkbox migration warnings now name the payload-only remedy and can be silenced with an explicit form-level declaration. The tick-direction warn false-positived on legitimate post-#49 markup (a checkbox authored `value="true"` with no `checked`, intended to render unticked) where neither listed remedy applied. Both warn messages now name the measured third remedy — remove the `value` attribute; a boolean-classified checkbox posts its live checked state either way — and an explicit `data-gina-form-checkbox-value-as-state="false"` on the form declares the current state model and silences the migration warnings for that form (any explicit value counts; "false" is otherwise behavior-inert). Browser-bundled: consumers pick the change up at their next bundle re-bake.
+* The per-request country-locale resolution: `page.view.locale` now carries the real region record (country name, currency, capital, …) resolved from the request culture's country code. The lookup filtered on a key the region data has never carried, so the object had always been empty when a country code was present — and an arbitrary first record when the culture had no country part (now an explicit empty object). Lowercase country segments are normalized, and the date stamp is unchanged.
+* `npm install -g gina` no longer dies when the effective npm prefix contains a path segment npm's redactor masks (e.g. a UUID-shaped directory — CI sandboxes, generated workspaces): `npm config get prefix` refuses such a read as protected on every current npm generation (10/11/12), and both install scripts ran that probe unguarded. The probe is now guarded, falling back to the prefix npm itself exports to the install lifecycle.
+* Fixed the link plugin's HTML-callback forwarding — `data-gina-link-event-on-success` / `data-gina-link-event-on-error` now fire, and carrying either attribute no longer breaks the link. Previously, adding one of these attributes to a `data-gina-link` anchor made every click throw `ReferenceError: listenToXhrEvents is not defined` before the XHR was opened: no request left the page, no callback ran, and the link was effectively dead. Three defects were fixed together: the registration helper was trapped inside another function's scope (unreachable from the link plugin), the call site passed no type (so even a reachable helper would have read `data-gina-undefined-event-on-*` and registered nothing), and the internal success/error events were named and targeted inconsistently between registration and dispatch. The helper is now a shared global, the link call site passes its type, and the events address the clicked link's own element and id. The programmatic `gina.link.on('success'/'error')` channel is unchanged. Browser-bundled — rebuild your bundles to pick it up.
+
 ## 0.5.21 - 2026-07-20
 ### Added
 * Popin eager preload — a trigger can opt into warming its AJAX content off the critical path with data-gina-dialog-preload="eager" (case-insensitive): after window load, at browser idle, the popin plugin fetches the content one trigger at a time through the same gate as the hover/focus warm (the "false" opt-out, the disabled skip, and the cache dedup all apply — whichever warm runs second is a no-op), so a later open injects instantly with no second GET. The pass is skipped when the browser signals Save-Data. Default behavior is unchanged: hover/focus warm stays the default and "false" still disables warming entirely. Browser-bundled — rebuild your bundles to pick it up.

package/README.md

@@ -4,11 +4,12 @@
 
 > **Documentation:** [gina.io/docs](https://gina.io/docs/) · **Issues:** [GitHub](https://github.com/gina-io/gina/issues) · **Changelog:** [CHANGELOG.md](./CHANGELOG.md)
 
-Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency.
+MVC framework for Node.js and Bun with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency.
 
 - **HTTP/2 first.** Built-in `isaac` server with TLS, h2c, ALPN, HTTP/1.1 fallback, and full CVE hardening (Rapid Reset, CONTINUATION flood, RST flood, HPACK bomb) — all on by default.
 - **Multi-bundle.** One project hosts multiple independent bundles (API, web, admin, …). Each bundle has its own routing, controllers, models, and config. Share code via the project layer.
 - **Scope isolation.** Run `local`, `beta`, and `production` from the same codebase. Scopes propagate through routing, config interpolation, and data (every DB record is stamped with `_scope`).
+- **Batteries included.** Forms & validation, sessions, uploads, async jobs, response caching, CSRF, security headers, route authorization, audit trail, i18n, OpenAPI + MCP generation — built in, not bolted on.
 
 ## Features
 
@@ -19,14 +20,30 @@ Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope
 | Scope isolation | `local` / `beta` / `production` — per-request and per-record |
 | MVC routing | `routing.json` — declare routes in config, not code; O(m) radix trie lookup |
 | Async/await | Controller actions can be `async`; rejections routed to `throwError` automatically |
+| WebSockets | WS routes in `routing.json` (`"method": "ws"` + channel handlers, `:param` paths); WebSocket-over-HTTP/2 (RFC 8441) |
 | ORM / entities | EventEmitter-based entity system; SQL files auto-wired to entity methods |
 | Connectors | Couchbase, MongoDB, ScyllaDB / Cassandra, MySQL, PostgreSQL, Redis, SQLite, AI (LLM) — loaded from project `node_modules` |
-| AI connector | Any LLM provider via named protocol (`anthropic://`, `openai://`, `ollama://`, …) |
-| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) 2.7.2 — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` or per-section `"ext": ".njk"` |
+| AI connector | Any LLM provider via named protocol (`anthropic://`, `openai://`, `ollama://`, …) — unified `.infer()`, token streaming via `.stream()`, inference-as-a-job via `self.inferAsync()` |
+| Template engine | [`@rhinostone/swig`](https://github.com/gina-io/swig) — maintained fork with CVE-2023-25345 patched; streaming SSE/chunked via `renderStream()`. Nunjucks supported as opt-in via `render.engine = "nunjucks"` or per-section `"ext": ".njk"` |
+| Forms & validation | One rule engine for client and server — live checks, cross-field rules, ARIA states, localised messages; the server enforces the same rules on submit |
+| DTOs | `gina.dto` schema builder — request validation with localised 422s (`param.dto`), response shaping (`param.responseDto`), JSON Schema export |
+| Sessions | Hardened session plugin (SameSite / HttpOnly / Secure defaults) — Redis, SQLite, MongoDB, Couchbase, and ScyllaDB stores |
+| File uploads | Multipart via the maintained [`@rhinostone/busboy`](https://github.com/gina-io/busboy) fork — named upload groups with per-group extension allow-lists, size / count limits, and target dirs |
+| Async jobs | `self.startJob()` background jobs — durable SQLite / MongoDB / Redis stores, retries with backoff, HMAC-signed completion webhooks, `/_gina/jobs/:id` status endpoint |
+| Response caching | Per-route render cache — memory / fs / Redis tiers, cross-replica warm start, event-driven invalidation, RFC 9211 `Cache-Status` |
+| Route authorization | `requireAuth` / `roles` / `policy` per route, login bounce with `resumeRequest()`, `self.hasRole()` |
+| Audit trail | Opt-in append-only JSONL audit log (`self.audit()`), authorization denials auto-recorded, always-on request ids |
+| CSRF protection | Signed double-submit token middleware + Origin/Referer pre-filter + hardened session cookie |
+| Security headers | CSP with per-response nonces, HSTS, COOP / COEP / CORP, Referrer-Policy and the X-* family — per-header plugins or one `SecurityHeaders` wrapper |
+| Secrets | `${secret:KEY}` placeholders in bundle config — fail-closed, env-backed; `secrets:scan` / `secrets:check` CLI |
 | Internationalisation | Per-bundle JSON catalogs, `t()` helper, swig + nunjucks `t` filter, CLDR plurals, ICU MessageFormat opt-in via `t.icu()` |
-| Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — Node.js process metrics + HTTP counter / duration histogram with cardinality-safe route labels |
+| Observability | Built-in `/_gina/metrics` Prometheus endpoint (opt-in, IP-allowlisted) — process metrics + HTTP counter / duration histogram with cardinality-safe route labels; structured JSON logs with request ids (`GINA_LOG_FORMAT=json`) |
+| Dev Inspector | Embedded dev SPA at `/_gina/inspector` — request data, live logs, SQL with index-coverage badges, flow timings, app events, AI token stream |
+| OpenAPI & MCP | `bundle:openapi` emits OpenAPI 3.1 from `routing.json`; `bundle:mcp` emits an MCP tool manifest; built-in MCP runtime server (stdio + Streamable HTTP) |
+| TypeScript & ESM | Typed public surface (shipped `.d.ts`), `bundle:types` generates entity types from DTOs, dual CJS / ESM exports |
 | Hot reload | WatcherService evicts `require.cache` only on file change — zero per-request overhead in dev |
 | K8s ready | `gina-container`, `gina-init`, SIGTERM drain, JSON stdout logging |
+| Container tooling | `image:build` synthesizes an OCI image (buildah), `image:run` / `container:ps` / `container:stop` (podman) — local or over SSH |
 | Dependency injection | Mockable connectors and config for unit testing |
 | Runtime | Node.js 22–26, or **Bun** (`bun add -g gina`) — install + boot validated end-to-end by a CI Bun smoke |
 
@@ -42,15 +59,16 @@ open https://localhost:3100
 
 > **npm 12+** blocks install scripts by default, and gina's post-install bootstraps `~/.gina` and the framework dependencies. Install with `npm install -g gina@latest --allow-scripts=gina`, or allow it once for all global installs with `npm config set allow-scripts=gina --location=user`. (Not needed on npm ≤ 11.)
 
-## What's in 0.5.21
+## What's in 0.5.22
 
-- **Security — 500 bodies no longer carry stack traces outside local scope.** Uncaught controller and middleware errors route through the server-side error responder, which used to serialize the full stack — absolute server paths and frames — into the JSON `error` field, the inline HTML fallback, and custom-error-page data on every scope. Outside local scope the wire now carries only the error's message line (the JSON render delegate's HTTP/1.1 reason-phrase fallback and the cached-file stream error path included); the full stack goes to the server log. Local scope is unchanged — the development toolbar keeps its stack.
-- **Changed — a missing bundle `routing.json` now fails the boot (deliberate).** A bundle whose `config/routing.json` was missing at boot used to start silently with only the framework-synthetic routes — every app route 404'd, and cross-bundle lookups threw hours later. The boot now refuses to start with an error naming the bundle and environment, exactly like a malformed `routing.json` always has; under an external supervisor (Kubernetes, a container restart policy, an init system) the restart retries until the release tree settles, while a bare `gina bundle:start` reports the crash once and stays down until restarted manually. The route-lookup not-found error also names the bundle and its rule count, so a degraded table is tellable from a mistyped rule — that half is browser-bundled, so rebuild your bundles.
-- **Fixed — FormValidator: keyboard shortcuts on `autocomplete="off"` fields, the Safari-only gate, and stale error clearing.** The Safari-autocomplete keydown interception no longer swallows modifier chords (Cmd/Ctrl+A/C/V/X/Z run their native defaults instead of typing the chord letter into the field) and now runs on real Safari only — every Chromium UA carries the `Safari/537.36` token, so Chrome/Edge/Brave were wrongly intercepted. And when a live-check whole-form pass turns valid, every previously-errored field's message is now cleared along with re-enabling the submit trigger, instead of leaving a stale blocking error on screen. Browser-bundled — rebuild your bundles. (#B134/#B135/#B136)
-- **Fixed — cross-bundle links in merged-process projects.** In a project whose bundles share one port (served by one process), the first cross-bundle `getUrl` permanently replaced the target bundle's routing table with the starting app's — every cross-bundle link to that bundle rendered a literal `404:[…]` marker instead of a URL. Each bundle now keeps its own routing table. Server-side only; projects with distinct per-bundle ports were never affected. (#B137)
-- **Fixed — CSP `useNonce` on cache-enabled routes.** The framework-injected inline bootstrap's nonce was frozen at first compile inside the compiled-template and layout caches while the `Content-Security-Policy` header rotated per request, so every cache-path response failed nonce validation under an enforcing policy. The nonce is now injected per response, stale pre-fix layout-cache files heal in place, and cache hits re-mint both the stored header and body with a fresh nonce on both engines.
-- **Fixed — the hardcoded `accept-language` response header is gone.** Accept-Language is a request header, but the framework env template declared it as a response default, so every response — error responses included — emitted it. An env.json that declares its own response headers keeps working verbatim; deployments whose generated env.json copied the old template line should remove it.
-- **Added — popin eager preload.** Mark a trigger with `data-gina-dialog-preload="eager"` and the popin plugin fetches its AJAX content after window load, at browser idle — one trigger at a time, off the critical path — so a later open injects instantly with no second GET. Same safety gates as the hover/focus warm (the `"false"` opt-out, the disabled skip, cache dedup), and the pass is skipped under Save-Data. Default behavior is unchanged. Browser-bundled — rebuild your bundles.
+- **Fixed — multipart binary uploads arrive byte-identical.** Binary file payloads uploaded via native multipart (`FormData`, `curl -F`, hand-built bodies) were string-decoded on their way to disk, so any content that is not valid UTF-8 — images, PDFs, archives — arrived mangled and mis-sized. Pure-ASCII payloads were unaffected, which is what hid the corruption. The request stream now stays raw for multipart bodies and the per-file write pipeline passes chunks through verbatim, so files reach `req.files[].path` byte-identical and `req.files[].size` reports the real on-disk byte count instead of a decoded character count. If you base64-encode binaries over JSON to work around this, you can retire that workaround. Server-side — restart your bundles. (#B103)
+- **Fixed — link HTML callbacks (`data-gina-link-event-on-*`) work, and no longer break the link.** Carrying `data-gina-link-event-on-success` or `data-gina-link-event-on-error` on a `data-gina-link` anchor made every click throw before the XHR was even opened: no request left the page, no callback ran, and the link was effectively dead. Three defects were fixed together — the registration helper was trapped inside another function's scope, the call site passed no type, and the internal success/error events were named and targeted inconsistently between registration and dispatch. Name a `window`-level function (bare identifier, no parentheses) and it now receives `(event, result)`. The programmatic `gina.link.on('success'/'error')` channel is unchanged. Browser-bundled — rebuild your bundles. (#B141)
+- **Fixed — reopening a popin no longer renders the previous open's content.** The AJAX popin content cache outlived the open it warmed, so every open after the first paid for a network fetch yet rendered the body fetched around the *previous* open — a one-generation lag that showed a stale snapshot whenever the content changed between opens. The cache entry now dies with the open it warmed, and a trigger annotated `data-gina-dialog-preload="false"` additionally skips the cache read at open, making `"false"` a hard always-refetch guarantee. Costs at most one extra idempotent GET per close on default triggers. Browser-bundled — rebuild your bundles. (#B139)
+- **Fixed — FormValidator: numbered `is<N>` rules, a hung submit, and the checkbox migration warnings.** Numbered `is` aliases no longer collapse onto the bare `is` error key when validation re-applies rules against the same form (a `_case_` re-evaluation, nested field groups) — each keeps its own distinct key and each message renders once, instead of the last-declared rule's message rendering twice (#B138). A `query` rule's async result path is now blanket-guarded, so a throw while handling a backend result — an unbound form, a malformed body, a boolean checkbox value — warns and releases the pass instead of hanging the submit forever (#B87). And the #49 checkbox migration warnings now name the payload-only remedy (remove the `value` attribute — a boolean-classified checkbox posts its live checked state either way) and can be silenced per form with an explicit `data-gina-form-checkbox-value-as-state` declaration (#B125). Browser-bundled — rebuild your bundles.
+- **Fixed — `page.view.locale` carries the real country record.** The per-request country-locale lookup filtered the region data on a key it has never carried, so the object had always been empty when the culture carried a country code — and an arbitrary first record when it did not. Templates now receive the real record (`countryName`, `currency`, `capital`, …) resolved from the request culture's country code, with lowercase country segments normalized and a country-less culture yielding an explicit empty object. Nothing read the broken object before, so no existing template changes behavior. (#B101)
+- **Fixed — install no longer dies on a redactor-matched npm prefix.** `npm install -g gina` failed whenever the effective npm prefix contained a path segment npm's redactor masks — a UUID-shaped directory is enough (CI sandboxes, generated workspaces): `npm config get prefix` refuses such a read as protected on every current npm generation (10/11/12), and both install scripts ran that probe unguarded. The probe is now guarded, falling back to the prefix npm itself exports to the install lifecycle. The fix ships inside the tarball, so it applies from this version's install onward. (#B126)
+- **Added — the `settings.i18n.cultures` allowlist is honoured.** A non-empty array under `settings.json > i18n` now constrains which cultures the user-signal negotiation steps (URL prefix, cookie, `Accept-Language`) may match, so a staged rollout can ship a `locales/de.json` catalog without `de` becoming reachable until it is listed. `null` or `[]` keep the historical derive-from-loaded-catalogs behavior, and the bundle default (`settings.region.culture`) is never constrained. The whole `i18n` block is now declared in the published settings.json schema. Restart to apply.
+- **Changed — runtime pins moved to the standard `engines` manifest key.** The floors (Node `>= 22 <27`, Bun `>= 1.2`) were declared under a non-standard singular `engine` key that npm and Bun tooling ignore entirely, so unsupported runtimes got no install-time warning at all. They now activate npm's standard `EBADENGINE` warning — a hard failure only where `engine-strict` is set. Scaffolded project manifests — the `project:add` template and the install-time fallback `package.json` — carry the standard object-form key too.
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -46,6 +46,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.19` ✅ | **Added**: route authorization — a `routing.json` rule gates access before the action runs via `param.requireAuth` (a 401 for XHR, a non-cacheable login redirect for a browser navigation, the original request snapshotted for `resumeRequest()`), `param.roles` (ANY-of, implies `requireAuth`), and `param.policy` (a per-bundle function for the ownership/record checks roles can't express, AND-composed after roles); denials stay generic — required roles and the policy name never reach the wire — author mistakes refuse to boot, and `self.hasRole()` authorizes mid-logic · an audit trail — opt-in `self.audit(action, data)` writes a user-attributed append-only JSONL record (its own store, never the logger sinks; an actor snapshot, `X-Forwarded-For` never trusted), route-authorization denials recorded automatically, and an always-on request id correlating audit records to JSON logs · an OCI image/container CLI on the `image:build` host — `image:list` / `image:rm` / `image:run` (podman; publishes the EXPOSEd port, `--env-var` / `--env-file` keep secrets out of argv) and a `container:` group (`container:ps` / `container:stop`, reporting the rung a container came down on) · **Changed**: `redirect()` carries request data through the session by default (a one-shot flash, gone on refresh), the clear-text `?inheritedData=` URL form and its 2000-char cap now session-less-only — removing a plaintext-secret-in-URL disclosure when a session-ful bundle halts a credential-bearing POST · **Fixed**: Prometheus metrics no longer double-count under the isaac engine (#OBS1) · the relative `self.redirect('/path')` form resolves again and an unresolvable target 404s instead of crashing (`redirect()` is now async), and `getRoute()` no longer 500s on a requirements-less GET route with extra params (#B120/#B121) · `image:build` for gina-dependent projects no longer fails at gina-init and the pinned framework wins `require('gina')` (#B118/#B119) · `gina.emit` is an inert stub (#B109) and the checkbox migration warning now covers the un-tick direction (#49) |
 | **Q3 2026** | `0.5.20` ✅ | **Fixed**: region locale data — the generator now emits one standalone file per language with localized country names (a `fr` culture renders `Allemagne` / `États-Unis` / `Royaume-Uni` through the same `getLocales().getCountries()` path, no app changes; rows without an ISO 3166 alpha-2 code are dropped; read once at boot, so restart to pick up), and `getCountries(code)` honors its projection argument — adding the requested field while the four historical fields stay untouched, an empty locale set degrading to an empty list instead of throwing (#50) · **Fixed**: FormValidator — numbered `is` rules (`is1`, `is2`, …) now install and enforce on client and server (previously silently skipped; **sweep rule JSONs before upgrading — forms may begin 422ing**), each alias keying its error distinctly and server-side `$`-cross-field rules no longer crashing; injected/popin forms resolve `data-gina-form-rule` so live checking activates; boolean `_case_` conditions match live (#B127/#B128/#B129) · **Changed**: multipart parsing uses `@rhinostone/busboy` installed from npm instead of a patched vendored copy — a strict superset of upstream busboy 1.6.0, upload behaviour and the wire format unchanged, pickup is the version plus a bundle restart |
 | **Q3 2026** | `0.5.21` ✅ | **Security**: server-side error responses no longer serialize stack traces to HTTP clients outside local scope — the responder logs the full stack server-side and ships the message line only (JSON bodies, the inline HTML fallback, custom-error-page data; local scope keeps the development-toolbar stack) · **Changed**: a bundle whose `config/routing.json` is missing at boot now refuses to start with an error naming the bundle and environment (previously a silent half-boot with only the framework-synthetic routes; an external supervisor's restart retries until the release tree settles — the daemon itself is fail-stop), and the route-lookup not-found error names the bundle and its rule count · **Fixed**: FormValidator — modifier chords (Cmd/Ctrl+A/C/V/X/Z) run their native defaults again on `autocomplete="off"` live-check fields, the Safari-autocomplete interception gates on real Safari only (Chromium UAs no longer intercepted), and a whole-form live-check pass that turns valid clears every previously-errored field's message (#B134/#B135/#B136) · **Fixed**: merged-process (same-port multi-bundle) projects — the first cross-bundle getUrl no longer permanently replaces the target bundle's routing table with the starting app's, which rendered every cross-bundle link as a literal `404:[…]` marker; distinct-port projects were never affected (#B137) · **Fixed**: CSP `useNonce` on cache-enabled routes — the header and inline-bootstrap nonces now match and rotate per response, on cache hits and misses alike · **Fixed**: the env template's hardcoded `accept-language` response header is gone (a request header, wrongly emitted on every response) · **Added**: popin eager preload — `data-gina-dialog-preload="eager"` warms a popin's AJAX content at browser idle after window load, same safety gates as the hover/focus warm, skipped under Save-Data |
+| **Q3 2026** | `0.5.22` ✅ | **Fixed**: multipart binary uploads arrive byte-identical — file payloads are no longer string-decoded on their way to disk, so images, PDFs and archives stop arriving mangled and mis-sized (pure-ASCII payloads were unaffected, which is what hid it), and `req.files[].size` reports the real on-disk byte count (#B103) · link HTML callbacks work and no longer break the link — `data-gina-link-event-on-success` / `-on-error` used to make every click throw before the request was opened, leaving a dead link; both attributes now fire a `window`-level function with `(event, result)`, the programmatic `gina.link.on()` channel unchanged (#B141) · reopening an AJAX popin renders current content instead of the previous open's — the content cache now dies with the open it warmed, and `data-gina-dialog-preload="false"` becomes a hard always-refetch guarantee (#B139) · FormValidator — numbered `is<N>` rules keep their distinct error keys on re-validation instead of collapsing onto a doubled bare `is` (#B138), a `query` rule failure can no longer hang the submit pass (#B87), and the #49 checkbox migration warnings name the payload-only remedy and can be silenced per form (#B125) · `page.view.locale` carries the real country record instead of an empty object (#B101) · `npm install -g gina` no longer dies when the effective npm prefix contains a path segment npm's redactor masks (#B126) · **Added**: the `settings.i18n.cultures` allowlist is honoured — a non-empty array constrains which cultures the user-signal negotiation steps may match, so a shipped-but-unlaunched catalog stays unreachable until listed; the whole `i18n` block is now in the published schema · **Changed**: runtime pins moved to the standard `engines` manifest key, so unsupported runtimes finally get npm's `EBADENGINE` warning |
 | **Q4 2026** | `0.6.0` | Security & compliance controls (technical safeguards mapping to PCI-DSS / SOC2 / HIPAA) |
 | **Q1 2027** | `0.5.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **Q3 2027** | `1.0.0` | First stable release — Windows alpha compatibility is a hard gate |
@@ -392,7 +393,7 @@ A cold audit of the Couchbase connector identified two critical security vulnera
 | --- | --- | --- | --- | --- |
 | ✅ | **`NODE_COMPILE_CACHE` — V8 bytecode startup cache** | `0.2.0` | Q2 2026 | Node.js 22.8+ caches compiled V8 bytecode to disk. Set once at startup — 30–60% faster cold start on subsequent runs with zero code changes to user bundles. No-op on Node < 22.8, so safe to ship unconditionally. |
 | ✅ | **Route radix trie — compile `routing.json` at startup** | `0.3.0-alpha.1` | 2026-04-01 | `lib/routing/src/radix.js` builds a segment-level trie once at startup. O(m) candidate lookup per request (m = segment count). `Set.has()` check skips non-candidates in the `for…in` loop. Internal change — no user-facing API change. |
-| 📋 | **Bun runtime compatibility investigation** | `0.5.x` | Q4 2026 | Prototype Gina under Bun. Two blockers to verify: `require.cache` deletion (dev hot-reload) and `node:http2` completeness. If both pass, Bun gives 3–10x faster startup and meaningful throughput gains. Deliverable: a compatibility report. |
+| ✅ | **Bun runtime support** | `0.5.5` | 2026-06-21 | Gina runs on the [Bun](https://bun.sh) runtime (Bun `>= 1.2`) as a supported, CI-gated target — `bun add -g gina` installs and boots end-to-end, validated by a blocking CI Bun smoke. Both investigated blockers cleared: dev-mode `require.cache` hot-reload and `node:http2` work under Bun (one upstream gap remains: RFC 8441 extended-CONNECT advertisement, affecting only opt-in WebSocket-over-HTTP/2). Gina self-bootstraps on first run; Node `>= 22 < 27` remains fully supported. |
 | ✅ | **V8 pointer compression support** | `0.2.0` | Q2 2026 | Node.js built with `--experimental-enable-pointer-compression` (e.g. [node-caged](https://github.com/platformatic/node-caged) or a custom build) delivers ~50% heap memory reduction across all pointer-heavy structures. Gina is pure JS — compatible out of the box. Adds: startup detection + `GINA_V8_POINTER_COMPRESSED` env var, Dockerfile guide with custom build recipe (full-icu + pointer compression), 4 GB ceiling documentation, N-API-only connector policy. |
 
 ---

package/framework/v0.5.22/VERSION

@@ -0,0 +1 @@
+0.5.22