gina 0.6.3 → 0.6.4

package/CHANGELOG.md

@@ -6,6 +6,35 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.6.4 - 2026-08-05
+### Added
+* Submit-like triggers now carry a framework-owned loading state. Clicking a `<button type="submit">`, an `<input type="submit">` or an `<a data-gina-form-submit>` sets `data-gina-loading="true"` on that trigger, and the attribute flips to `"false"` as soon as the action completes or is interrupted — settled, errored, timed out, aborted, rate-limited, or rejected by validation. That last case is the one that stranded loading state on forever (#B247): a submit refused before it starts sends no request at all, so nothing in the XHR lifecycle could ever release it, and only the framework knows the submit was refused. Enter-key and programmatic submits arm the form's registered trigger, and a click on a wrapped label such as `<button type="submit"><span>Save</span></button>` arms the button rather than the span. A project already built on `data-loading` renames the attribute with `gina.setOptions({ loadingAttribute: 'data-loading' })`; there is no auto-detection, so nothing changes for anyone who does not opt in. Style the running state with `[data-gina-loading="true"]` and never with a bare `[data-gina-loading]` — the attribute stays present when released, carrying `"false"`, so a presence selector would pin the loading style on permanently.
+* Bundle configs can resolve `${secret:KEY}` placeholders from `.env`-style files as well as from the environment. Declare `secrets.file` in the bundle `settings.json` — one path, or an array of them — using the usual config tokens, e.g. `["${homedir}/secrets.env", "${homedir}/${scope}/secrets.env"]`. Files are layered UNDER the environment: a non-empty environment variable always wins, so a Kubernetes secret, a `sops exec-env` invocation or a CI-exported value can never be shadowed by a stale file left on disk. A variable that is set but EMPTY counts as absent and the file fills it — which keeps the common `environment: ["X=${X}"]` passthrough working — and that fall-through warns, naming the key. Within the array, later entries win over earlier ones, so a shared base file and a per-scope file combine. A declared file that does not exist contributes nothing rather than failing, resolution stays fail-closed when a key is in neither source, and a config that does not declare `secrets.file` behaves exactly as before. `lib.secrets` also gains `parseEnv` / `parseEnvFile`, which `secrets:check --env-file` now shares so that the CI gate and the runtime can never disagree about how a file is read. This is a convenience for plaintext and pre-decrypted deployments, not a secrets-management integration: for SOPS, Vault or a KMS, keep decrypting at the container entrypoint so values land in the environment.
+* `gina.config.a11y` overrides the accessibility status strings gina announces on its own behalf, for example `gina.config.a11y = { submitting: 'Envoi…' }`. English defaults ship for anything a project does not translate, mirroring how `setErrorLabels` already handles built-in rule labels. These are distinct from rule error labels: `setErrorLabels` is keyed by rule name, while these describe what the framework itself is doing.
+* Links bound with `data-gina-link` now carry the same loading state as submit triggers. Clicking one sets `data-gina-loading="true"` on the anchor and flips it to `"false"` once the request settles — including the two outcomes that reach your handlers as silence today: a link superseded by a second click, and a request that fails at the network level. The state lands on the anchor itself even when the click hits an element nested inside it, and a link driven programmatically through `gina.link.request()` is armed the same way. One limit worth knowing before you style it: a link request that hangs never settles and so never releases, because link requests still have no deadline. As with submit triggers, style the running state with `[data-gina-loading="true"]` and never with a bare `[data-gina-loading]` — the attribute stays present when released, carrying `"false"`.
+* Gina now ships a default look for the loading state it writes, so the feature is visible without you writing any CSS. A trigger carrying `data-gina-loading="true"` gets a `progress` cursor and a gentle opacity pulse. The pulse is gated on `prefers-reduced-motion: no-preference`; anyone who has asked for reduced motion gets a static dimmed state instead, rather than no signal at all. It is deliberately minimal, and two omissions are on purpose: there is no injected spinner, because one would stack with a spinner you already ship and would force a positioning change on a trigger gina does not own; and there is no `pointer-events: none`, because a link deliberately accepts a second click while its request is running and supersedes the first. Overriding takes one rule of your own — the selector is a single attribute, so any class beats it — and `animation: none` drops just the motion. Renaming the attribute with `gina.setOptions({ loadingAttribute: 'data-loading' })` opts out of the default styling entirely, since it is keyed on the default name.
+* A popin trigger now carries the same loading state as submit controls and links. The control that opened a popin gets `data-gina-loading="true"` while the popin loads and `"false"` once it settles, so one stylesheet covers every busy control on a page whichever plugin started the work. This is in addition to the popin container's own `data-gina-popin-loading`, which is unchanged: the two live on different elements and answer different questions — the container attribute says the popin is filling, the trigger attribute says that control is busy. The trigger is released on response completion whatever the status, on close, and on the routing teardown that tears a popin down without closing it. One gap remains and is deliberate: a popin opened from a hover or focus preload that is still in flight does not yet arm its trigger, so that click shows no busy affordance until the content lands. It cannot leave anything stuck — nothing is armed, so nothing is left behind — and it is tracked separately.
+### Fixed
+* A submit trigger marked disabled by live form validation (aria-disabled="true" plus the gina-form-submit-disabled class) could still be clicked, and that click ran the entire submit cycle — field collection, validation, the submit latch, and the isValid() send gate. The trigger was inert in appearance only, so a control announced as disabled to assistive technology stayed fully operable. A click on a disabled trigger is now intercepted before the submit dispatch: the submit cycle is never entered and no request can start from it. The click is still answered by a display-only validation pass that renders every invalid field and moves focus to the first one, so the reason the trigger is disabled remains discoverable; that pass also re-syncs the trigger state, so a stale disabled marker on a form that has since become valid now heals itself. The check reads the clicked element rather than the form registered submit trigger, so forms carrying several submit buttons behave correctly.
+* Built-in HTML error pages are now conforming documents. The fallback page served when a project has no custom error template emitted no doctype (so browsers rendered it in quirks mode), no head, no title and no lang attribute — and on HTTP/1.1 it closed the body with an *opening* `<html>` tag, so the document never terminated. Both engine branches now ship a doctype, an `<html lang>`, a `<title>`, and a `<main>` landmark; the status and incident ref the page already showed are unchanged. This is the default path: a scaffolded project ships no `templates/html/errors/` directory, so it is what an unhandled 500 actually serves. Separately, the `lang` value gina emits is now normalised to BCP-47 wherever it appears — `en_CM` becomes `en-CM` and an `accept-language` q-value such as `fr;q=0.9` is reduced to `fr`, falling back to `en` rather than emitting a tag assistive technology cannot parse. This covers `page.view.lang`, the layoutless/iframe wrapper and the three nunjucks error fallbacks. Server-side only — running bundles pick it up at restart, with no rebuild required.
+* `gina secrets:check` now looks in the same two places a bundle would, in the same order. It previously cross-referenced the environment only, so once a bundle declared `settings.secrets.file` the command reported `UNSET` — and exited non-zero — for a key that bundle would have started with perfectly well, turning a pre-deploy gate into a false alarm. It now resolves the bundle's declared file chain and consults it beneath the environment, reusing the runtime's own token substitution and the shared `lib.secrets` parser so the two sides cannot disagree about where a file lives or what it contains. An explicit `--env-file` still wins, because it stands in for the environment tier which outranks the files. The report gained a per-bundle chain listing that marks each declared path `loaded` or `ABSENT`, and each key now names the tier it was satisfied from, so a value coming from a plaintext file on the local disk is never mistaken for one the deployment will inject. `${scope}` and `${env}` inside a declared path are values the launcher supplies and this command cannot read, so the report names the ones it assumed, a new `--env` flag selects which env block `homedir` is read from, and a path whose tokens cannot be resolved is reported and skipped rather than opened blindly — which can only make the gate stricter than the runtime, never laxer. A bundle that declares no `secrets.file` reports exactly as before.
+* Blur-time validation errors are now reliably announced to assistive technology the first time a form reports one. The form's polite live region was created, inserted into the page and given its text in a single synchronous step, which reaches a screen reader as one change on an element it has never seen before and is commonly not spoken at all; the practical effect was that the first error announced on any form, the one most likely to matter, was the one least likely to be heard, while every later announcement worked. The region is now stood up when the form is bound, so by the time an error occurs it has been present all along. A region that still has to be created at announcement time defers its first write by a tick so the insertion and the text no longer land together. That second half matters because the region lives inside the form and a subtree replacement destroys it: a popin re-render or a fragment swap leaves the next announcement to re-create the region, which previously reproduced the original problem silently. Announcements on an already-bound region are unchanged and still write synchronously, and while a deferred write is pending a newer error replaces the pending text so the most recent message is the one spoken. The region deliberately remains a child of the form rather than moving to document level: a popin renders its form inside a native dialog opened with showModal(), which leaves everything outside the top layer inert, so a document-level region would go unspoken for exactly those forms. Browser-bundled - consumers re-bake at pickup.
+* `gina secrets:check` could not resolve a `settings.secrets.file` path that used the project version or relied on the default scope, so for those chains it skipped the file tier and went back to reporting `UNSET` for keys the bundle would have started with — the same false alarm the previous fix set out to remove, returning through tokens the command did not carry. It now seeds `${projectVersion}` and `${projectVersionMajor}` from the project manifest, matching how the runtime obtains them, so a path such as `${homedir}/v${projectVersionMajor}/credentials/secrets.env` resolves. `${scope}` now falls back to the project's default scope when `--scope` is absent, which is what the runtime uses when nothing overrides it, so a scope-templated chain resolves without the flag; `--scope` is still required to apply the read-only `config_<scope>/` overlay, which is never applied by default. The project name behind `${homedir}` is now derived from the project path rather than the resolved command argument, so the all-projects form no longer builds a path from an undefined name and reports every layer of it missing. Tokens the command genuinely cannot derive are still left in place and the tier reported and skipped, so the check can only ever be stricter than the runtime, never laxer.
+* Submitting a form no longer loses the keyboard user's place. gina disables the submit trigger for the duration of the request, which makes the browser drop focus to the document body; focus is now returned to that trigger once the request settles, and only when nothing else claimed it in the meantime. Assistive technology is also told that a submit is under way: the trigger carries `aria-busy` while the request is in flight, and the form's polite live region announces the start once. Completion announces nothing, so an errored response still announces its field errors uninterrupted, and a submit rejected by validation announces nothing at all.
+* Validation messages stay reachable to assistive technology while they are hidden from view. gina hides a committed error's message whenever the field it belongs to regains focus, but it kept `aria-invalid="true"` asserted on that field — so the `aria-errormessage` association pointed at an element that `display: none` had removed from the accessibility tree, announcing a field as invalid with no retrievable reason. Both hide paths now clip the message out of view instead of out of the tree, and the `.hidden` class is still applied so consumer CSS keyed on it keeps matching. Re-announcing the same error also works now: a polite live region ignores a byte-identical rewrite, so blurring a field that still fails the same rule announced nothing the second time. Finally, moving focus to the first invalid field no longer stops on a control that cannot take focus — every element has a `focus` method, including a custom element with neither `tabindex` nor `delegatesFocus` whose `focus()` does nothing, so the search now confirms focus actually moved and continues otherwise.
+* When an environment variable is SET but EMPTY, the `${secret:KEY}` file tier now warns as it falls through to the file. The fall-through itself is deliberate and unchanged: an empty value counts as absent, which is what keeps the ordinary `environment: ["X=${X}"]` passthrough working when the outer variable is unset. But the same shape appears when a container entrypoint runs `export X="$(fetch …)"` and the fetch FAILS — and there a file quietly supplying a stale value is exactly the shadowing the environment-wins ordering exists to prevent. Because the two are indistinguishable from inside the process, the file tier no longer stays silent about it: it emits a warning naming the key (never the value) at a level that survives the default log hierarchy. The documented precedence is also corrected throughout — it is a NON-EMPTY environment value that always wins.
+* A declared `secrets.file` layer that EXISTS but cannot be read — wrong permissions or ownership, or a path that is actually a directory — is no longer mistaken for a layer that is simply absent. Previously both collapsed to "not there", so a chain like `["${homedir}/secrets.env", "${homedir}/${scope}/secrets.env"]` whose per-scope file lost read permission silently fell back to the shared base file: the bundle booted healthily on the wrong credential, with only a debug line — labelled ABSENT, which was itself misleading — to say so, and that line is suppressed at the default log level. Boot now refuses and names the path and the error code. A genuinely missing file is unchanged: it still contributes nothing and is not an error, so shipping a base file and adding the per-scope one only on some targets keeps working. `gina secrets:check` reports the same distinction (UNREADABLE rather than ABSENT) so the gate and the runtime cannot disagree, and `lib.secrets` gains `readEnvFile`, the discriminated read both now share.
+* Requiring gina outside a bundle context now fails cleanly instead of hanging the process. The framework bootstrap has always thrown when it cannot find the bundle context the CLI provides, but the logger — a load-time singleton — had already opened its MQ socket by then, and that socket kept the event loop alive: catching the error did not let the process exit, so a plain node process (a test runner, a one-off script, a codegen pass) stalled with no output wherever an MQ listener happened to be running. The speaker now unrefs its connection, so a logging transport can never be the reason a process stays alive. The error itself also names the boundary it hit, and points at SuperController.createTestInstance() for exercising controller code without booting a bundle, instead of reporting an internal path-registry failure (setPath("gina.home", path): path cannot be empty or undefined).
+* Upload preview images built by the staged-upload client layer now carry an `alt` text alternative taken from the original filename. Previously neither preview branch set `alt` at all, so assistive technology fell back to reading the temporary upload URI aloud, once per staged file. The name used is the one the user chose, not the server-generated preview variant, and an image with no available name falls back to an empty `alt` so it is ignored rather than announced.
+* A bundle that starts in an environment its env.json does not declare now reliably prints why. The refusal was written with console.error and the boot then ended through a callback, so on a loaded or short-lived pipe — a container start, CI — the explanation could be truncated away and the operator was left with an exit code and no reason. The message is now flushed synchronously before the boot unwinds, matching the other boot-refusal sites in the same file.
+* Clicking a second `data-gina-link` no longer kills the first click's response. The link plugin built one `XMLHttpRequest` when it initialised and reused it for every click, and re-opening a request that is still running aborts it — an aborted request arrives with status `0`, which the completion path has no branch for, so the first click ended in total silence: no success callback, no error callback, nothing. Each link request now gets its own transport and carries a sequence number, so a superseded response is discarded rather than acted upon and a slow first response can never overwrite a newer one. Two related gaps are deliberately unchanged for now, because both would alter what your handlers receive: a link request that fails at the network level is still silent, and a link request that hangs still has no deadline.
+* A gina command no longer dies when an MQ speaker disconnects abruptly. Every CLI invocation starts the MQ listener on the shared log port, so commands running side by side connect to one another as speakers. When one of them ended or was killed, the listener still held its connection socket and the next write to it raised EPIPE or ECONNRESET on that socket — which had no error listener, so Node threw the event and took the whole command down mid-run. The failure was silent and looked like the command had simply not done its work: a bundle:add killed this way exited non-zero after registering its ports but before writing the rest of its state, leaving a half-created bundle. Connection sockets now handle their own errors, dropping the departed speaker's session (an abruptly-killed peer may never emit end, which is what otherwise clears it) and carrying on. The listener-wide error handler was never a substitute: in Node every accepted connection is its own emitter, so it never saw these.
+* A popin opened while another one is still open no longer leaves the first reachable behind it. Non-modal is the framework default for the `data-gina-dialog` API, and opening a popin never closes the one it supersedes, so both stay in the page — but a non-modal `<dialog>` gets none of the background `inert` that native `showModal()` provides, and gina restores it by hand. That restoration skipped the shared popin container wholesale, and every popin lives inside that container, so a superseded dialog kept its links, buttons and form fields in the tab order behind the dialog actually on screen: a keyboard or screen-reader user could tab straight out of the popin they were looking at and into a stale one. The container is now descended into, and sibling open dialogs are inerted individually. Closed ones are deliberately left alone — a `<dialog>` without the `open` attribute is already `display: none` per the user-agent stylesheet, so it is unreachable without help. Teardown needed no change and still restores everything it marked, including an `inert` a project set itself, which gina never claims.
+* A trailing `#` comment in a declared secrets file is no longer read as part of the secret. `DB_PASSWORD=s3cret # rotated May` resolved to the literal `s3cret # rotated May`, and a quoted value followed by a comment kept its quote characters too — `DB_PASSWORD="s3cret" # note` became `"s3cret"`. The parser now strips a trailing comment the way a POSIX shell does when sourcing the same file, which is what the documented container-entrypoint pattern (`set -a; . secrets.env; set +a`) already did — so the same file no longer means two different things depending on which route delivered it. Two cases deliberately keep their hash, because stripping them would corrupt a legitimate password: a `#` with no whitespace before it (`abc#def`) and any `#` inside quotes (`"abc # def"`), which makes quoting a complete escape hatch. One consequence is worth checking before you upgrade: `KEY= # comment` is now an empty value rather than the string `# comment`, and an empty value counts as unset — so a key written that way now fails closed at bundle start, and `gina secrets:check` reports it `UNSET` instead of `SET`. That reversal is the point: the shell always delivered it empty, and the previous `SET` was a false green.
+* Staged uploads are now announced and operable for assistive technology. A progress indicator that is not a native `<progress>` element carries `role="progressbar"` with `aria-valuemin`, `aria-valuemax` and `aria-valuenow`; the value is dropped rather than zeroed while the upload is indeterminate or has errored, so a screen reader reports an unknown state instead of stalled progress. A native `<progress>` is left untouched, since it already exposes all of this. The start and the successful completion of an upload are announced through the polite live region gina already owns — per-tick progress deliberately is not, as one announcement per progress event would bury everything else on the page. An upload error announces the server's own message through that same region, rather than only writing it into a container that is hidden when the text lands and revealed by a fade-in. The auto-generated reset control is now announced as a button instead of a link, activates with Space as well as Enter, and names the file it acts on, with the visible label kept as a prefix so the accessible name still contains it; focus moves to the file input before the control is removed from the page, instead of dropping to the document with no signal. The three new strings are overridable per project through `gina.config.a11y`: `uploadStarted`, `uploadComplete` and `fileRemoved` (which takes a `%s` placeholder for the file name).
+### Security
+* Ignore rules for secret files now match by glob rather than by exact name, in both the repository ignore list and the published-package ignore list. The previous single `.env` entry matched only that exact name. Dot-prefixed variants such as `.env.production` were already covered by the pre-existing `.*` catch-all, but a secret file whose name does not begin with a dot — `secrets.env`, `db.env`, `production.env` — matched nothing and was committable by default. `.env`, `.env.*` and `*.env` are now all covered, which closes that gap.
+
 ## 0.6.3 - 2026-08-04
 ### Added
 * Added a Couchbase SDK soak harness — `script/soak/couchbase-soak.js` screens a Couchbase Node SDK candidate against a caller-chosen Couchbase Server before a consuming project adopts it (#CN12). The harness scaffolds a fully isolated throwaway project (the real `~/.gina` and real projects are never touched), installs the candidate SDK into it (`--sdk=<version>` or `--sdk-path=<dir>` — the install is the version selector, since the connector resolves `couchbase` from the project node_modules), builds and boots the bundle for the prod env, then drives the three connector surfaces under sustained concurrent load for `--duration`: N1QL entity queries (including a `request_plus` scan-consistency arm), KV through the entity collection handle in both the promise and the 4-arg optional-callback form, and the couchbase express-session store. Pass criteria target the silent-death class where a process under SDK load dies without a JS stack: the bundle must survive the full duration (a premature clean exit 0 counts as FAILURE), RSS growth must stay bounded, the error rate must not drift, and every requested arm must complete real work. Exit codes 0/1/2 with a JSON + text report under `tmp/couchbase-soak-<stamp>/`; a generic soak is a screen, not proof — run it as the first filter on an SDK bump, with a workload-shaped soak of the consuming application as the second gate.

package/README.md

@@ -60,51 +60,43 @@ 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.6.3
+## What's in 0.6.4
 
 > **Re-bake your bundles, not just restart them.** The browser bundle changed in
-> this release. Several of the fixes below — the client-side validator work, the
-> boot-time routing fetch guard, and the new navigation module — ship *only* in
-> the bundle, so a restart alone will not deliver them. Rebuild each bundle
-> (`gina bundle:build`) as well as restarting.
+> this release. The new loading state, the form and staged-upload accessibility
+> work, and the link-transport fix ship *only* in the bundle, so a restart alone
+> will not deliver them. Rebuild each bundle (`gina bundle:build`) as well as
+> restarting.
 
-> **No settings reset.** `0.6.3` is a patch — the `shortVersion` stays `0.6`, so
+> **No settings reset.** `0.6.4` is a patch — the `shortVersion` stays `0.6`, so
 > your `~/.gina/0.6/settings.json` is untouched. (`0.6.0` was the reset.)
 
-> **Two enforcement tightenings to review before upgrading.** Several validator
-> fixes convert silent passes into real verdicts: rules authored on
-> bracket-notation keys now enforce server-side, `isBoolean` and `isInteger`
-> stop accepting values they used to coerce, and required radio groups now gate
-> submission. Forms that relied on the old silent behaviour will start rejecting.
-> Each bullet below discloses its direction; the [Changelog](./CHANGELOG.md) has
-> the per-rule detail.
-
-- **Added — opt-in SPA-style client-side navigation.** A route can now declare `negotiate: true` in `routing.json`; a request carrying `X-Gina-Navigate: fragment` then receives that route rendered **without its layout** — the content region alone — over the same URL, with no second route, duplicated controller or query-string convention. The new `gina/nav` module turns that into navigation: a page carrying a `data-gina-nav` region fetches same-origin links as fragments and swaps them in, with history, scroll, focus, title, fragment script re-injection and validator form rebinding handled for you. Every uncertainty — a non-2xx, a timeout, an un-negotiated answer, a JSON redirect — falls back to a normal full-page navigation, and a page without the marker is byte-identical. Negotiable routes advertise `Vary: X-Gina-Navigate` and deliberately opt out of the render cache (the cache key carries no shape dimension, so a stored entry could otherwise replay a fragment to a browser asking for a full page). `{% extends %}` templates render their blocks correctly as fragments via a dedicated cache namespace. Browser-bundled — **re-bake**. (#SPA1)
-- **Security — the client-served routing map no longer discloses server-side contracts.** `/_gina/assets/routing.json` is now built from an **allowlist** instead of a denylist: controller dispatch keys (`param.control`/`file`/`path`/`title`), `namespace`, `scopes`, `cache` configuration including invalidation event names, `csrfExempt`, `middlewareIgnored` and `validator::` requirement bodies all stay server-side — and structurally, so does every *future* route key until it is deliberately added to the roster (`schema/routing.json` allows additional properties, which is how several of these reached the wire in the first place). What ships is the measured client contract: `url`, `method`, `webroot`, `bundle`, `hostname`/`host`, the `negotiate` flag, plain-regex `requirements`, URL-placeholder `param` bindings, and a derived `isRedirect` boolean. Client URL building (`getRoute`/`toUrl`, including cross-bundle `rule@bundle` references) is unaffected; **code reading other keys off `gina.config.routing` must move that logic server-side.**
-- **Changed — a restart's new route table reaches returning browsers immediately.** `/_gina/assets/routing.json` is now served with a per-variant weak `ETag` and `cache-control: no-cache` (was `max-age=86400`) on both engines, so each page boot revalidates with one conditional GET — normally answered `304`. Previously a restart's route changes could take up to 24 hours to reach a returning browser. The proxied variant keeps its `private` marking.
-- **Fixed — the client routing map serves under every engine, and a failed fetch is no longer installed as the route table.** The maps were built and served by the isaac engine only, so an `engine: "express"` bundle answered a 404 for the URL every browser fetches at boot (#B212). And because `fetch` resolves on error statuses and the framework's 404 page is valid JSON, that answer was silently installed *as* the client routing table, breaking every later client-side `getRoute`/`toUrl`; the boot fetch now checks the status first (#B213). Browser-bundled — **re-bake**.
-- **Fixed — server-side validation now enforces rules authored on bracket-notation and nested keys.** Rules keyed `account[username]`, and nested rule trees, were **silently skipped** server-side — fail-open, with no warning, for checks, the `exclude` drop and value transforms alike. Both production wire shapes now join: flat bracket keys and nested objects. Error keys come back under the DOM-name bracket form the client renders against. **Enforcement tightening — a bracket-keyed rule that never fired now enforces**, so a form relying on the old silent skip will start rejecting or dropping those fields. (#B241)
-- **Fixed — the validator's empty-value contract is now uniform across every rule.** Five sites tested emptiness with loose equality, so `0`, `-0`, `false` and `[]` all rode the empty bypass: `isEmail`, `isJsonWebToken` and `isFloat` reported such values **valid outright** (a JSON body carrying `{"email": 0}` passed email validation), and `isInteger`/`isNumber` digit bounds were skipped for zero. All five now compare strictly. Separately, `is` (custom condition) and `isBoolean` joined the same contract, so a required-but-empty field records `Cannot be left empty` once rather than a second, contradictory message beside it. **Enforcement tightening** — review `isEmail`/`isJsonWebToken`/`isFloat` fields that can receive a numeric or boolean value from a JSON body, and bounds-carrying `isInteger`/`isNumber` fields that can receive zero. (#B233, #B235)
-- **Fixed — `isBoolean` is the single adjudicator on every surface, and `isInteger` bounds enforce on real numbers.** Server auto-validation coerced every non-boolean string to `false` *before* the rule could run, so junk like `nope`, the HTML checkbox default `on`, and the strings `"1"`/`"0"` validated clean and **persisted as `false`** — and the number `1` stored as `false`. The engine now accepts `true`/`'true'`/`1` and `false`/`'false'`/`0` and errors on anything else, matching what the routing requirements surface always enforced and the reference always promised. Likewise `isInteger`'s digit bounds were silently ignored whenever the value arrived as a real number rather than a string — from a JSON body, a `validator::{}` requirement, or a preceding `toInteger` — and now measure the string form, as `isNumber` always has. **Enforcement tightening in both cases.** (#B236)
-- **Fixed — a `$` token in a rule no longer crashes the whole validation pass.** A rule set still carrying a `$` after field substitution — a regex end-anchor in an `is` condition (`/^(alpha|beta)$/`), a `$` inside a human-readable message, or a `$` in a later array element — threw a `TypeError` on the server, because a DOM-fallback substitution loop bare-dereferenced a DOM the server does not have (#B234). And an array-form rule whose first argument carries a `$` token resolving to no field threw on **both** client and server; such a token now stays literal, so `isInList: ['$100', '$200']` accepts the literal `$100` and rejects a non-member with the rule's own message (#B239). No rule set that already validated changes verdict.
-- **Fixed — required radio groups now gate, and the submit trigger re-enables on a pick.** No collector admitted a radio group with no checked member, so an `isRequired` rule on the group never ran — and a form whose only named controls were radio groups **skipped client validation entirely** and submitted its XHR unvalidated (#B221). With that fixed, a second defect surfaced: the radio live-check listener was registered under an event name nothing dispatches, so picking a value never re-ran the pass and the trigger kept its `aria-disabled` state while submit-time validation let the send through anyway (#B228). **Enforcement tightening — forms that silently submitted with nothing picked now genuinely gate on the pick.** Browser-bundled — **re-bake**.
-- **Fixed — a field that drives its own `_case_` block is validated, and keeps the value the user picked.** When a rule file declared both a rule for a field and a `_case_<field>` block keyed on that same field, the client validator skipped that field entirely in every whole-form pass, so a required radio group selecting its own case was never adjudicated (#B229). Separately, any such driver except the last-declared had its collected value dropped mid-pass, and later readers re-read it from the DOM — for a radio group, the *first* member regardless of which was picked — so conditions could match a choice the user never made (#B230). Browser-bundled — **re-bake**.
-- **Fixed — a rejected submit no longer kills a form's live check for the rest of the page's life.** The submit path arms an internal latch before validating, but only the XHR settle cleared it — and a rejected submit renders errors without sending anything. One invalid attempt therefore swallowed every later keystroke and left the trigger `aria-disabled="true"`, hard-blocking keyboard and assistive-technology users while mouse users saw a disabled-looking trigger that still submitted. Rebinding the form did not restore it either. Browser-bundled — **re-bake**.
-- **Fixed — the documented `setFlash` `[null, "message"]` form works in the browser.** `lib/merge` classified a `null` array element as an object (the `typeof null` trap) and refused to carry it through no-override merges, so the client received a one-element array, bound the message to the ignored first argument and rendered the built-in label instead. Merges now preserve `null` array elements framework-wide. (#B226)
-- **Fixed — `pauseRequest()`/`resumeRequest()` replay the byte-exact halted URL, query string included.** The recomposed replay URL only carried query keys declared in *both* a rule's `requirements` and `param` blocks, so a key bound in `param` only — or an entirely undeclared one like `?returnTo=…` — was dropped; the replay then matched anyway and rendered literal `:key` template paths as a **500**, including on the framework's own `requireAuth` login replay (#B215). And on the isaac engine the snapshot itself was path-only, since the engine strips the query from `req.url` before controllers run (#B219). Both engines now replay the full URL, verified over HTTP/1.1 and HTTP/2. Middleware comparing `haltedRequestUrlResumed` to `req.url` by equality should compare against `req.originalUrl || req.url`.
-- **Fixed — `Controller.store()` publishes each file atomically and surfaces the real error.** Failures were reported as a fabricated `No file to upload` Error, masking the actual ENOSPC/EACCES/ENOENT diagnostics; a source-side stream error had no listener at all and **killed the bundle process**; a destination failure unlinked the caller's staged source file after the failed move and settled the callback a second time as a success; and the copy streamed straight to the final name after pre-deleting any existing destination, so a concurrent reader could observe a truncated file. Each file now streams to a temp sibling and is published with an atomic rename, the callback settles exactly once with the real Error, and a failed move leaves both the staged source and any pre-existing destination intact. (#B223)
-- **Fixed — custom error pages answer with their real HTTP status.** A page configured through the routing error param / `errorFiles` mechanism was rendered with **status 200** by the nunjucks and async render delegates, so a configured 500 or 404 answered 200 on the wire (#B190). Separately, the custom-error renderer discarded its resolved error template whenever the dispatch reset flag was absent, so the delegates fell back to the failing route's own file and produced a bare-path "could not open" error plus a routing-rule dump that misdirected diagnosis. The resolved template now reaches the render unconditionally, the dispatch works on a clone rather than mutating shared routing configuration, and an unopenable error template falls back to the built-in page naming the template.
-- **Added — the `Cache-Status` identifier is configurable.** `server.cache.name` sets the RFC 9211 identifier the render/output cache reports on the wire (default `gina-cache`; byte-identical when unset). With `server.hidePoweredBy` true and the cache enabled, leaving it unset now logs a boot warn naming the remaining framework disclosure — set any token to close it, or explicitly `gina-cache` to keep the current wire and silence the warn. Resolved once at boot, so it can never disagree across engines or between hit and miss. (#B238)
-- **Fixed — session stores no longer write an immortal record for an already-expired session.** When the resolved TTL is ≤ 0 — a cookie `maxAge` of 0, or the decaying remainder truncating to zero in a session's final second — `set()` is now a no-op in every store. Previously redis wrote an expiry-less `SET` and the couchbase and scylladb stores stored the record with a **zero (never-expires) expiry**, leaving a zombie session that still validated if its id was replayed. **Behaviour change:** a configured `ttl: 0` now refuses at bundle init naming the offending channel, instead of silently behaving as unset.
-- **Fixed — Couchbase: an unserializable query parameter no longer kills the bundle, and range SDK pins resolve.** A parameter the SDK cannot serialize (a bare `undefined`, a function, a Symbol) made the native driver abort the process from an internal thread — uncatchable by `try/catch`, `uncaughtException` or `unhandledRejection` — so the bundle **died outright** instead of the request failing with a 500. The most reachable case needed no misuse: a query method called one argument short with a trailing callback put the *callback* into a parameter slot. The connector now refuses it before dispatch with a `GINA_COUCHBASE_UNSERIALIZABLE_PARAM` TypeError naming the position and likely cause (#B243). Separately, the SDK-major resolvers now take the pin's first integer, so range pins like `~4.5.0` or `>=4.5` no longer mangle, slip past the v2 floor and refuse to boot with a misdirecting error.
-- **Added — a Couchbase SDK soak harness.** `script/soak/couchbase-soak.js` screens an SDK candidate against a caller-chosen Couchbase Server before a consuming project adopts it: it scaffolds a fully isolated throwaway project (your real `~/.gina` and projects are never touched), installs the candidate, and drives N1QL entity queries, KV through the entity collection handle, and the express-session store under sustained concurrent load — targeting the silent-death class where a process dies with no JS stack. A generic soak is a screen, not proof: run it as the first filter on an SDK bump. (#CN12) The published `schema/connectors.json` description of the couchbase `useScopeAndCollections` option was also corrected — it claimed to enable scope/collection support while the option is accepted but currently inert.
-- **Fixed — `lib/math` `checkSumSync`, three defects.** Every **array** input collapsed to the checksum of the empty string (the serializer assigned to the wrong variable), and the caller's array was sorted in place (#B208). Any input whose serialized form ended in a dot plus three lowercase letters — an email domain, a URL, a filename mentioned in text — was passed to `fs.readFileSync` and threw ENOENT, with the error naming the caller's own data as a path (#B209). And real file paths whose extension was *not* exactly dot-plus-three-lowercase were hashed as path strings, never tracking content (#B210). **Stored checksums change** for arrays and for those file paths.
-- **Fixed — `GINA_*` environment variables are visible everywhere they should be.** `GINA_HOMEDIR=/path gina env:list` now resolves the home directory, settings file and host from that value during the CLI's own bootstrap instead of falling back to the default home — no more null-laden seeded settings, no more `Cannot override Env variable` warnings, and no junk `gina` variable leaking into every spawned child's environment. The MQ speaker and file logger containers now honour `GINA_HOMEDIR` too, instead of silently mixing an isolated home with the real home's MQ port and host. `${secret:GINA_*}` placeholders resolve in CLI contexts (`mcp.json`, connector CLI commands, `audit:verify`). And the MCP HTTP transport's dead `GINA_HOST_V4` bind tier is replaced by `GINA_BIND_HOST` read through the framework environment, so a connect address can no longer become the bind.
-- **Fixed — a sub-directory in the configured run directory no longer aborts every gina command.** The `framework:init` pid cleanup read every entry as a pidfile with no guard, so one unreadable entry threw `EISDIR` out of the loop and failed the whole command. Unreadable entries are skipped — and deliberately never pruned, since stale-pidfile removal is only safe for entries actually read.
-- **Inspector — bundle-following, per-tab restore, and six scope/display fixes.** The Inspector now **follows the monitored tab across bundles** of a proxy-routed multi-bundle project, re-pointing its server-side channels at the bundle actually serving the page, so the Flow and Query tabs stop reporting "No timeline data" for every page served by a bundle it was not opened from (#B205). A window opened by direct URL or bookmark now adopts the statusbar-advertised tab channel instead of silently falling back to bundle-global data, with a new footer badge naming the active mode (#B231), and warmed (hover/focus-preloaded) popin opens now set the XHR overlay exactly as cold opens always did (#B225). Hidden tabs can be restored **one at a time** by clicking their dimmed preview pill. Also fixed: the tab-layout preview rendered the two newest tabs as literal "undefined" and silently rejected custom layouts above six tabs; the Query pane and its badge froze on the first page whose queries lacked index data (#B222); multi-index Couchbase queries were reported as "no index — full bucket scan", inviting a needless index build for an already-fully-indexed query; and the footer memory gauge's unfilled track was invisible in both themes (#B237). Dev-tool only — reopen the Inspector window.
-- **Fixed — `bundle:openapi` and `bundle:mcp` no longer drop three declared bound forms.** Un-collapsing a `validator::{}` routing requirement into a parameter schema silently discarded them: scalar `"isString": N` now maps to `minLength`, and `isInteger`/`isNumber` digit bounds reach the schema as a human-readable `description` plus a machine-readable `x-gina-digitBounds` extension. They are deliberately *not* emitted as `minimum`/`maximum` (wrong for any negative value, whose sign counts toward the length) nor `minLength`/`maxLength` (string-only keywords, inert on numeric types). Schemas generated from bare `true` rules are byte-identical.
-- **Fixed — the scaffolded bundle template taught an impossible session-store selection.** `bundle:add` emitted `expressSession.name = 'myRedis'` — `Function.prototype.name` is read-only, so the assignment silently no-ops and the factory always resolved the literal `"session"` entry, meaning the template's own `"myRedis"`/`"myDb"` examples could never be found and boot failed with `[SessionStore] Could not be loaded`. The template now shows the documented shape: one `connectors.json` entry named `"session"` whose `connector` field selects the backend.
-- **Changed — the dormant transitive `object-assign` dependency is overridden.** `engine.io` → `cors` → `object-assign@4.1.1` (unmaintained since 2017) is replaced by `@socketregistry/object-assign` via npm `overrides`, with zero runtime change. **Scope, so nobody reads more into this than it does:** npm and bun alike honour `overrides` only in a project's *own root* manifest, so this cleans the gina tree and **not your install** — a project depending on gina still resolves `object-assign@4.x` beneath `cors`. Add the same `overrides` entry to your own root `package.json` to get it in your tree; the consumer-reaching fix is upstream ([expressjs/cors#430](https://github.com/expressjs/cors/pull/430), filed).
+> **One visual change arrives with no opt-in.** Gina now ships a default look for
+> the loading state it writes, so a submit trigger picks up a `progress` cursor
+> and a gentle opacity pulse while its request runs. Overriding takes one rule of
+> your own — the selector is a single attribute, so any class beats it — and the
+> pulse is already gated on `prefers-reduced-motion`.
+
+- **Added — a framework-owned loading state for busy controls.** Clicking a `<button type="submit">`, an `<input type="submit">`, an `<a data-gina-form-submit>`, a `data-gina-link` anchor or a popin trigger sets `data-gina-loading="true"` on that control, and the attribute flips to `"false"` as soon as the work completes or is interrupted — settled, errored, timed out, aborted, rate-limited, or rejected by validation. That last case is the one that stranded loading state on forever: a submit refused before it starts sends no request at all, so nothing in the XHR lifecycle could ever release it (#B247). One stylesheet now covers every busy control on a page whichever plugin started the work. Enter-key and programmatic submits arm the form's registered trigger; a click on a wrapped label such as `<button type="submit"><span>Save</span></button>` arms the button rather than the span; and the state lands on the anchor itself even when the click hits a nested element. A project already built on `data-loading` renames the attribute with `gina.setOptions({ loadingAttribute: 'data-loading' })`. **Style the running state with `[data-gina-loading="true"]` and never with a bare `[data-gina-loading]`** — the attribute stays present when released, carrying `"false"`, so a presence selector would pin the loading style on permanently. Two limits are deliberate and tracked: a link request that hangs never settles and so never releases, and a popin opened from a still-in-flight hover/focus preload does not yet arm its trigger (it cannot leave anything stuck — nothing is armed). Browser-bundled — **re-bake**.
+- **Added — a default look for that loading state, so the feature is visible without writing any CSS.** Deliberately minimal, with two omissions on purpose: no injected spinner, because one would stack with a spinner you already ship and would force a positioning change on a trigger gina does not own; and no `pointer-events: none`, because a link deliberately accepts a second click while its request runs and supersedes the first. Anyone who has asked for reduced motion gets a static dimmed state rather than no signal at all. `animation: none` drops just the motion, and renaming the attribute opts out of the default styling entirely, since it is keyed on the default name.
+- **Added — `gina.config.a11y` translates what gina says on its own behalf.** For example `gina.config.a11y = { submitting: 'Envoi…' }`. English defaults ship for anything a project does not translate, mirroring how `setErrorLabels` already handles built-in rule labels. These are distinct from rule error labels: `setErrorLabels` is keyed by rule name, while these describe what the framework itself is doing.
+- **Added — `${secret:KEY}` can resolve from `.env`-style files as well as the environment.** Declare `secrets.file` in the bundle `settings.json` — one path or an array — using the usual config tokens, e.g. `["${homedir}/secrets.env", "${homedir}/${scope}/secrets.env"]`. **Files are layered UNDER the environment**, which inverts the usual `.env` intuition on purpose: a non-empty environment variable always wins, so a Kubernetes secret, a `sops exec-env` invocation or a CI-exported value can never be shadowed by a stale file left on disk. A variable that is set but *empty* counts as absent and the file fills it — which keeps the common `environment: ["X=${X}"]` passthrough working — and that fall-through warns, naming the key. Within the array, later entries win, so a shared base file and a per-scope file combine. A declared file that does not exist contributes nothing rather than failing, resolution stays fail-closed when a key is in neither source, and a config that does not declare `secrets.file` behaves exactly as before. `lib.secrets` gains `parseEnv` / `parseEnvFile`, which `secrets:check --env-file` shares, so the CI gate and the runtime can never disagree about how a file is read. **This is a convenience for plaintext and pre-decrypted deployments, not a secrets-management integration:** for SOPS, Vault or a KMS, keep decrypting at the container entrypoint so values land in the environment.
+- **Security — secret files are ignored by glob, not by exact name.** The previous single `.env` entry matched only that exact name. Dot-prefixed variants such as `.env.production` were already covered by the pre-existing `.*` catch-all, but a secret file whose name does not begin with a dot — `secrets.env`, `db.env`, `production.env` — matched nothing and was committable and publishable by default. `.env`, `.env.*` and `*.env` are now all covered in both the repository ignore list and the published-package ignore list.
+- **Fixed — a submit trigger disabled by live validation is no longer operable.** A trigger marked disabled (`aria-disabled="true"` plus the `gina-form-submit-disabled` class) could still be clicked, and that click ran the entire submit cycle — field collection, validation, the submit latch and the send gate. The control was inert in appearance only, so one announced as disabled to assistive technology stayed fully operable. The click is now intercepted before the submit dispatch, and answered by a display-only validation pass that renders every invalid field and moves focus to the first, so the reason it is disabled stays discoverable; that pass also re-syncs the trigger, so a stale disabled marker on a form that has since become valid heals itself. The check reads the clicked element rather than the form's registered trigger, so forms carrying several submit buttons behave correctly. (#B246)
+- **Fixed — a form's first validation error is now reliably announced.** The polite live region was created, inserted and given its text in a single synchronous step, which reaches a screen reader as one change on an element it has never seen and is commonly not spoken at all — so the first error on any form, the one most likely to matter, was the one least likely to be heard, while every later announcement worked. The region is now stood up when the form is bound. A region that still has to be created at announcement time defers its first write by a tick, which matters because the region lives inside the form and a subtree replacement destroys it: a popin re-render or fragment swap otherwise reproduced the original problem silently. The region deliberately stays a child of the form rather than moving to document level — a popin renders its form inside a native dialog opened with `showModal()`, which leaves everything outside the top layer inert, so a document-level region would go unspoken for exactly those forms. Browser-bundled — **re-bake**.
+- **Fixed — submitting a form no longer loses the keyboard user's place.** Gina disables the submit trigger for the duration of the request, which makes the browser drop focus to the document body; focus is now returned to that trigger once the request settles, and only when nothing else claimed it meanwhile. The trigger also carries `aria-busy` while the request is in flight, and the form's polite live region announces the start once. Completion announces nothing, so an errored response still announces its field errors uninterrupted, and a submit rejected by validation announces nothing at all.
+- **Fixed — validation messages stay reachable while they are hidden from view.** Gina hides a committed error's message when its field regains focus, but kept `aria-invalid="true"` asserted — so the `aria-errormessage` association pointed at an element `display: none` had removed from the accessibility tree, announcing a field as invalid with no retrievable reason. Both hide paths now clip the message out of view instead of out of the tree, and the `.hidden` class is still applied so consumer CSS keyed on it keeps matching. Re-announcing the same error works now too (a polite region ignores a byte-identical rewrite), and moving focus to the first invalid field no longer stops on a control that cannot take focus — every element has a `focus` method, including a custom element whose `focus()` does nothing, so the search confirms focus actually moved and continues otherwise.
+- **Fixed — staged uploads are announced and operable.** A progress indicator that is not a native `<progress>` carries `role="progressbar"` with `aria-valuemin`/`aria-valuemax`/`aria-valuenow`; the value is **dropped rather than zeroed** while an upload is indeterminate or errored, so a screen reader reports an unknown state instead of stalled progress. A native `<progress>` is left untouched. Upload start and successful completion are announced through the polite live region gina already owns — per-tick progress deliberately is not, as one announcement per progress event would bury everything else on the page — and an upload error announces the server's own message there rather than only writing it into a container that is hidden when the text lands. The auto-generated reset control is now announced as a button, activates with Space as well as Enter, and names the file it acts on; focus moves to the file input before the control is removed. Preview images finally carry an `alt` taken from the user's own filename, where assistive technology previously read the temporary upload URI aloud once per staged file. The three new strings — `uploadStarted`, `uploadComplete` and `fileRemoved` (which takes a `%s` for the file name) — are overridable through `gina.config.a11y`. Browser-bundled — **re-bake**.
+- **Fixed — a superseded popin no longer stays reachable behind the one on screen.** Non-modal is the framework default for the `data-gina-dialog` API and opening a popin never closes the one it supersedes, so both stay in the page — but a non-modal `<dialog>` gets none of the background `inert` that native `showModal()` provides, and gina restores it by hand. That restoration skipped the shared popin container wholesale, and every popin lives inside it, so a superseded dialog kept its links, buttons and fields in the tab order: a keyboard or screen-reader user could tab straight out of the popin they were looking at and into a stale one. The container is now descended into and sibling open dialogs are inerted individually. Closed ones are deliberately left alone — a `<dialog>` without `open` is already `display: none` per the user-agent stylesheet. Teardown still restores everything it marked, including an `inert` a project set itself, which gina never claims.
+- **Fixed — built-in HTML error pages are conforming documents.** The fallback page served when a project has no custom error template emitted no doctype (so browsers rendered it in quirks mode), no head, no title and no `lang` — and on HTTP/1.1 it closed the body with an *opening* `<html>` tag, so the document never terminated. Both engine branches now ship a doctype, an `<html lang>`, a `<title>` and a `<main>` landmark. This is the default path: a scaffolded project ships no `templates/html/errors/` directory, so it is what an unhandled 500 actually serves. Separately, the `lang` value gina emits is normalised to BCP-47 wherever it appears — `en_CM` becomes `en-CM`, and an `accept-language` q-value such as `fr;q=0.9` reduces to `fr` — falling back to `en` rather than emitting a tag assistive technology cannot parse.
+- **Fixed — clicking a second `data-gina-link` no longer kills the first click's response.** The link plugin built one `XMLHttpRequest` at initialisation and reused it for every click, and re-opening a request that is still running aborts it — an aborted request arrives with status `0`, which the completion path has no branch for, so the first click ended in total silence: no success callback, no error callback, nothing. Each link request now gets its own transport and carries a sequence number, so a superseded response is discarded rather than acted upon and a slow first response can never overwrite a newer one. Two related gaps stay unchanged for now because both would alter what your handlers receive: a link request that fails at the network level is still silent, and one that hangs still has no deadline. Browser-bundled — **re-bake**.
+- **Fixed — `gina secrets:check` looks in the same two places a bundle would, in the same order.** It previously cross-referenced the environment only, so once a bundle declared `settings.secrets.file` the command reported `UNSET` — and exited non-zero — for a key that bundle would have started with perfectly well, turning a pre-deploy gate into a false alarm. It now resolves the declared file chain beneath the environment, reusing the runtime's own token substitution and the shared parser. An explicit `--env-file` still wins, because it stands in for the environment tier. The report gained a per-bundle chain listing marking each path `loaded` or `ABSENT`, and each key names the tier it was satisfied from, so a value coming from a plaintext file on the local disk is never mistaken for one the deployment will inject. `${projectVersion}`/`${projectVersionMajor}` are seeded from the project manifest and `${scope}` falls back to the project's default scope, so version- and scope-templated chains resolve; a path whose tokens still cannot be resolved is reported and skipped rather than opened blindly — which can only make the gate stricter than the runtime, never laxer. A bundle declaring no `secrets.file` reports exactly as before. (#B263, #B266)
+- **Fixed — a declared secrets file that exists but cannot be read now refuses the boot.** Wrong permissions or ownership, or a path that is actually a directory, were all mistaken for a layer that is simply absent — so a chain whose per-scope file lost read permission silently fell back to the shared base file and **the bundle booted healthily on the wrong credential**, with only a debug line, itself mislabelled `ABSENT`, to say so at a level suppressed by default. Boot now refuses and names the path and the error code, and `secrets:check` reports the same distinction. A genuinely missing file is unchanged: it contributes nothing and is not an error, so shipping a base file and adding the per-scope one only on some targets keeps working. (#B267)
+- **Fixed — an environment variable that is set but empty warns as it falls through to the file.** The fall-through itself is deliberate and unchanged — an empty value counts as absent, which is what keeps the `environment: ["X=${X}"]` passthrough working when the outer variable is unset. But the same shape appears when a container entrypoint runs `export X="$(fetch …)"` and the fetch *fails*, and there a file quietly supplying a stale value is exactly the shadowing that the environment-wins ordering exists to prevent. Since the two are indistinguishable from inside the process, the file tier now emits a warning naming the key — never the value — at a level that survives the default log hierarchy. (#B268)
+- **Fixed — a trailing `#` comment in a secrets file is no longer read as part of the secret.** `DB_PASSWORD=s3cret # rotated May` resolved to the literal `s3cret # rotated May`, and a quoted value followed by a comment kept its quote characters too. The parser now strips a trailing comment the way a POSIX shell does when sourcing the same file — which is what the documented container-entrypoint pattern (`set -a; . secrets.env; set +a`) already did, so the same file no longer means two different things depending on which route delivered it. Two cases deliberately keep their hash, because stripping them would corrupt a legitimate password: a `#` with no whitespace before it (`abc#def`), and any `#` inside quotes (`"abc # def"`) — which makes quoting a complete escape hatch. **One consequence to check before upgrading:** `KEY= # comment` is now an empty value rather than the string `# comment`, and an empty value counts as unset — so a key written that way fails closed at bundle start and `secrets:check` reports it `UNSET` instead of `SET`. That reversal is the point: the shell always delivered it empty, and the previous `SET` was a false green.
+- **Fixed — requiring gina outside a bundle context fails cleanly instead of hanging the process.** The bootstrap has always thrown when it cannot find the bundle context the CLI provides, but the logger — a load-time singleton — had already opened its MQ socket by then, and that socket kept the event loop alive: catching the error did not let the process exit, so a plain node process (a test runner, a one-off script, a codegen pass) stalled with no output wherever an MQ listener happened to be running. The speaker now unrefs its connection, so a logging transport can never be the reason a process stays alive. The error also names the boundary it hit and points at `SuperController.createTestInstance()` for exercising controller code without booting a bundle, instead of reporting an internal path-registry failure. (#B276, #B277)
+- **Fixed — a bundle starting in an environment its `env.json` does not declare reliably prints why.** The refusal was written with `console.error` and the boot then ended through a callback, so on a loaded or short-lived pipe — a container start, CI — the explanation could be truncated away and the operator was left with an exit code and no reason. The message is now flushed synchronously before the boot unwinds, matching the other boot-refusal sites in the same file. (#B278)
+- **Fixed — a gina command no longer dies when an MQ speaker disconnects abruptly.** Every CLI invocation starts the MQ listener on the shared log port, so commands running side by side connect to one another as speakers. When one ended or was killed, the listener still held its connection socket and the next write raised `EPIPE` or `ECONNRESET` on a socket that had no error listener — so Node threw the event and took the whole command down mid-run. The failure was silent and looked like the command had simply not done its work: a `bundle:add` killed this way exited non-zero after registering its ports but before writing the rest of its state, leaving a half-created bundle. Connection sockets now handle their own errors, dropping the departed speaker's session and carrying on. The listener-wide error handler was never a substitute — in Node every accepted connection is its own emitter, so it never saw these. (#B279)
 
 See the full [Changelog](./CHANGELOG.md) and [Roadmap](./ROADMAP.md).
 

package/ROADMAP.md

@@ -55,6 +55,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q4 2026** | `0.6.1` ✅ | **Security**: the dev-mode Inspector no longer serves files outside its asset root — a request to `/_gina/inspector/*` carrying a literal `../` escaped the asset directory and read any file the bundle process could reach, application config and credentials included, on both engines; only dev-mode bundles ever served the handler, and the URL-encoded `%2e%2e` form was never affected (#B179) · **Added**: DuckDB connector — embedded analytical (columnar / OLAP) SQL over the standard entity wiring, with analytical-dialect row detection (`WITH` CTEs, `SUMMARIZE`, `PIVOT`), direct Parquet / CSV / JSON querying with no ETL hop, and a `readOnly` mode so any number of processes can share one database file (#CN11) · **Added**: SQLite under the Bun runtime — the ORM connector, session store, async-job store and framework state store resolve Bun's built-in `bun:sqlite` behind a `node:sqlite`-shaped adapter whenever `node:sqlite` is absent; Node resolution is unchanged · **Fixed**: two Bun-only crashes that stopped any connector-declaring bundle from booting, both no-ops on Node by construction, with the release smoke now booting a SQLite-backed bundle on every Node leg and on Bun · **Fixed**: query files whose names collide with an inherited prototype member were silently skipped by six ORM connectors and now warn at startup with a rename hint, while Couchbase — which attaches unconditionally — warns on the overwrite or shadow instead (#B173/#B174) · **Fixed**: `renderJSON()`'s `status` key now reaches the wire over HTTP/2, where the body path hardcoded a 200 status frame and served every JSON error as HTTP 200 with the error payload in the body (#B172) · **Fixed**: FormValidator — each submit builds its own XHR with a fail-safe release, so a completed form no longer re-disables a sibling form's submit button; the live-check opt-out attribute is honored consistently; error labels for the keys an app can observe are translatable; and byte-identical messages render once, with sentence-separated screen-reader announcements (#B175/#B176/#B178) |
 | **Q4 2026** | `0.6.2` ✅ | **Changed**: render and request-path CPU overhead sharply reduced — the per-render deep copies of the request options (template-filter configuration and render envelope) are passed by reference after each one's write surface was measured empty, per-request locale lookups are memoized with the request-local copy materialized lazily on first read, and the id generator right-sizes its entropy batch to the requested length; measured on the profiling harness at **4.4× render throughput** (10.7 → 2.4 ms per render), deep-clone CPU share 50.31% → 1.81%, GC time down ~18× — no API change, but the browser bundle changed so bundles pick the id-generator half up on rebuild (#P39) · **Added**: opt-in 503 + `Retry-After` rendering for transient datastore failures — with `server.transientErrors.enabled`, a connector error stamped `isTransient` that would render as HTTP 500 through `throwError` renders as 503 carrying `Retry-After`, with a configurable retry delay and user-facing message, on both engines across JSON and HTML error surfaces; off by default and byte-identical when off, and a malformed block warns at boot rather than refusing it (#CE1) · **Fixed**: an `env.json` block that omits `host` no longer leaves the `${host}` token unsubstituted inside the TLS credentials paths, which refused https and HTTP/2 boots with an ENOENT naming a literal `${host}` segment under an error pointing at the server settings — `host` was the only per-bundle value with no framework-side default, so a hand-written or partial block never received one (#B181) · **Fixed**: a bundle whose project `env.json` carries no block for the environment it starts in now refuses with the bundle, the environment, the resolved path and whether the file was found all named — covering the absent, empty and unlisted-bundles shapes — instead of an opaque `Cannot read properties of undefined` crash, exiting 1 so an external supervisor can retry (#B181) · **Fixed**: starting a bundle in an environment its `env.json` block does not cover refuses cleanly at exit 1 rather than dying at exit 143 on `Cannot set properties of undefined (setting 'bundlesPath')`, and a bundle declared only for other environments is now reported as skipped instead of taking every sibling bundle down with it (#B183) · **Fixed**: dead process records are removed from the `~/.gina/procs.json` registry under the right key — `removeRunningProc()` matched the entry by pid but deleted under the constructing bundle key, rewriting dead records back to disk and able to destroy a live one, degrading `gina stop`'s graceful-kill path (#B180) |
 | **Q4 2026** | `0.6.3` ✅ | **Security**: the client-served routing map (`/_gina/assets/routing.json`) is now built from an ALLOWLIST instead of a denylist — controller dispatch keys (`param.control`/`file`/`path`/`title`), `namespace`, `scopes`, `cache` configuration including invalidation event names, `csrfExempt`, `middlewareIgnored` and `validator::` requirement bodies all stay server-side, and structurally so does every future route key until deliberately added to the roster; client URL building is unaffected, but code reading other keys off `gina.config.routing` must move server-side · **Added**: opt-in SPA-style client-side navigation — a route declares `negotiate: true` and answers `X-Gina-Navigate: fragment` layoutlessly over the same URL, while the new `gina/nav` module swaps same-origin link targets into a `data-gina-nav` region with history, scroll, focus, title, script re-injection and validator rebinding, falling back to a full-page navigation on every uncertainty; negotiable routes advertise `Vary: X-Gina-Navigate` and opt out of the render cache (#SPA1) · a configurable RFC 9211 `Cache-Status` identifier (`server.cache.name`), with a boot warn naming the residual framework disclosure when `hidePoweredBy` is set (#B238) · a Couchbase SDK soak harness that screens a candidate SDK in a fully isolated throwaway project before a consuming project adopts it (#CN12) · **Changed**: `/_gina/assets/routing.json` now revalidates on each page boot (per-variant weak `ETag` + `no-cache`, was `max-age=86400`), so a restart's new route table reaches returning browsers immediately instead of up to 24 hours later · the dormant transitive `object-assign` dependency overridden to a maintained re-export (gina's own tree only — `overrides` are root-manifest-scoped; the consumer-reaching fix is upstream) · **Fixed**: server-side form-body validation now enforces rules authored on bracket-notation (`account[username]`) and nested keys — previously skipped silently, fail-open, for checks, `exclude` and transforms alike (#B241) · the validator's empty-value contract made uniform: five loose-equality sites let `0`, `false` and `[]` ride the empty bypass so `isEmail`/`isJsonWebToken`/`isFloat` reported them VALID outright, and `is`/`isBoolean` joined the same contract (#B233, #B235) · `isBoolean` is now the single adjudicator on every surface — server auto-validation coerced junk to `false` and persisted it — and `isInteger` digit bounds enforce on real numbers, not only strings (#B236) · a `$` token in a rule no longer crashes the validation pass on either surface (#B234, #B239) · required radio groups now gate, and the submit trigger re-enables on a pick (#B221, #B228) · a field driving its own `_case_` block is validated and keeps the value the user picked (#B229, #B230) · a rejected submit no longer kills a form's live check for the rest of the page's life · the documented `setFlash` `[null, "message"]` form works in the browser (#B226) · `pauseRequest()`/`resumeRequest()` replay the byte-exact halted URL, query string included, on both engines (#B215, #B219) · `Controller.store()` publishes each file atomically and surfaces the real filesystem error instead of a fabricated `No file to upload`, where a source-stream error previously killed the bundle process (#B223) · custom error pages answer with their real HTTP status and keep their resolved template instead of falling back to the failing route's own file (#B190) · session stores no longer write an immortal record for an already-expired session (redis wrote an expiry-less SET; couchbase and scylladb stored a never-expires zero expiry) · a Couchbase N1QL parameter the SDK cannot serialize no longer aborts the whole bundle process (#B243), and range SDK pins like `~4.5.0` resolve instead of mangling past the version floor · `lib/math` `checkSumSync` — every array collapsed to the empty-string checksum, data ending in an extension shape was misrouted to the filesystem, and real file paths were hashed as path strings (#B208, #B209, #B210) · `GINA_*` environment variables are visible to the CLI's own bootstrap, the MQ and file logger containers, the MCP bind tier and `${secret:}` resolution · the client routing map serves under every engine, and a non-2xx boot fetch is no longer installed as the client routing table (#B212, #B213) · Inspector bundle-following across a proxy-routed project, per-tab restore, advertised-channel adoption and six scope/display fixes (#B205, #B222, #B225, #B231, #B237) · `bundle:openapi`/`bundle:mcp` no longer drop three declared bound forms when un-collapsing a `validator::{}` requirement · a sub-directory in the run directory no longer aborts every gina command · the scaffolded bundle template's impossible session-store selection (`expressSession.name = 'myRedis'` silently no-ops) |
+| **Q4 2026** | `0.6.4` ✅ | **Added**: a framework-owned loading state for busy controls — clicking a submit trigger, a `data-gina-link` anchor or a popin trigger sets `data-gina-loading="true"` on that control and flips it to `"false"` when the work settles, errors, times out, aborts or is rejected by validation (the case that stranded the state on forever, since a refused submit sends no request at all), with a shipped default look gated on `prefers-reduced-motion` and an opt-in attribute rename (#B247) · `gina.config.a11y` overrides for the status strings gina announces on its own behalf · an opt-in `secrets.file` layer resolving `${secret:KEY}` from `.env`-style files **beneath** the environment, so a non-empty environment value can never be shadowed by a stale file on disk, with later array entries winning, empty-value fall-through warning, and fail-closed resolution · **Security**: secret-file ignore rules now match by glob (`.env`, `.env.*`, `*.env`) in both the repository and published-package ignore lists, where the previous exact `.env` entry left `secrets.env` or `db.env` committable and publishable by default · **Fixed**: a submit trigger disabled by live validation was inert in appearance only and still ran the whole submit cycle when clicked (#B246) · a form's first validation error was the one least likely to be heard, because the polite live region was created, inserted and written in a single synchronous step · submitting a form dropped the keyboard user's focus to the document body, and nothing told assistive technology a submit was under way · validation messages kept `aria-invalid` asserted while `display: none` removed the message from the accessibility tree, and the first-invalid focus loop could stop on a control that never actually took focus · staged uploads gained progressbar semantics with the value dropped rather than zeroed while indeterminate, spoken start/complete/error, an operable reset control, and preview `alt` text taken from the user's own filename · a popin opened over another left the superseded one reachable in the tab order behind it · built-in error pages emitted no doctype, head, title or `lang` and never terminated the document on HTTP/1.1, and the `lang` gina emits is now normalised to BCP-47 · the link plugin reused one `XMLHttpRequest` for every click, so a second click aborted the first and its response vanished in total silence · `gina secrets:check` reported `UNSET` for keys a bundle would have started with once `secrets.file` was declared, and could not resolve version- or scope-templated paths (#B263, #B266) · a declared secrets file that exists but cannot be read was mistaken for an absent one, so a bundle booted healthily on the wrong credential (#B267) · an environment variable that is set but empty now warns as it falls through to the file (#B268) · a trailing `#` comment was read as part of the secret, diverging from the POSIX shell that sources the same file · requiring gina outside a bundle context hung the process instead of failing cleanly, because the logger's MQ socket kept the event loop alive (#B276, #B277) · a bundle starting in an undeclared environment could lose its refusal message to a truncated pipe (#B278) · a gina command died mid-run when an MQ speaker disconnected abruptly, leaving a half-created bundle (#B279) |
 | **Q1 2027** | `0.6.x` | HTTP/2 priorities (blocked on Node scheduler hooks) · Beemaster admin + visual translation editor |
 | **2027** | `0.7.0` | Performance — remaining measure-gated candidates: multipart & WebSocket fast paths, render/log cleanups, SIMD scanner (the render-path deep-clone & id-mint reduction shipped early in `0.6.2` with a measured 4.4× render-throughput gain; the profiling baseline itself also shipped in `0.6.2`) |
 | **2027** | `0.8.0` | Financial-messaging foundations — XML request/response handling · pluggable message-schema validation · IBAN/BIC validation rules · money & ISO 4217 minor-unit utilities · idempotency keys · sequence primitive · OAuth2 client-credentials egress |
@@ -255,11 +256,12 @@ Client-side form-validation accessibility — keeping `FormValidator`'s ARIA sta
 
 ## Secrets & Configuration
 
-Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with `process.env` as the default; the reserved API surface allows future Vault / SOPS / K8s Secrets backends to slot in without changing call sites or the placeholder syntax.
+Secrets handling for bundle JSON configs without baking plaintext values into source. Pluggable-backend design with the environment as the default, plus an opt-in file tier beneath it (`settings.secrets.file`). The backend seam is real — the file tier ships on it, without changing call sites or the placeholder syntax — but a **network-backed** backend (Vault, SOPS with a cloud KMS) is structurally blocked today, not merely unwritten; decrypt at the container entrypoint instead.
 
 | Status | Feature | Version | Target |
 | --- | --- | --- | --- |
 | ✅ | **`${secret:KEY}` placeholder substitution** — `lib/secrets` resolves `${secret:KEY}` placeholders embedded in bundle JSON configs (`settings.json`, `app.json`, `connectors.json`, `mcp.json`, etc.) at config-load time. Anchored regex matches the entire string value only — mixed strings (`"prefix-${secret:K}-suffix"`) pass through unchanged. Default backend reads `process.env[KEY]`; pluggable-backend interface reserved for a future iteration. Fails closed (throws `Error('Secret resolution failed')`) when an env var is unset or empty; the error message intentionally omits the key name. Resolution is once per config-load cycle (in-place mutation). `WeakMap`-backed path tracking enables a future log-redaction wrapper at merged-conf print sites. Hooked inside `core/config.js::loadBundleConfig`, so downstream readers (`getConfig()`, plugin factories) see resolved values transparently. **Consumers shipped**: `gina.plugins.Csrf()` reads `settings.csrf.secret` (precedence `opts.secret` > `settings.csrf.secret` > `process.env.GINA_CSRF_SECRET` for back-compat); `gina bundle:mcp-start` re-runs the resolver on the parsed `mcp.json` immediately after `requireJSON()` so `server.authToken` and any future placeholder field gets filled before downstream readers; bundle scaffolding (`project:add` / `bundle:add`) recommends the placeholder shape in `core/template/conf/settings.json` and `core/template/boilerplate/bundle/index.js`. 33 tests in `test/core/config-secrets-resolver.test.js`. | `0.3.13-alpha` | 2026-05-13 |
+| ⏸ | **Network-backed secret backends** — Vault, SOPS with a cloud KMS, or a Kubernetes Secrets API client resolving `${secret:KEY}` directly at bundle start. **Blocked, not merely unwritten.** The backend seam (`resolve(config, backend?)`) is real and the opt-in file tier (`settings.secrets.file`) ships on it, but `lib/secrets` is fully synchronous and the config loader holds a synchronous initialisation contract — so a network-backed backend would put a round-trip inside a synchronous boot path, where a KMS hiccup becomes a *hung* boot rather than a failed one. Delivering this requires making config-init asynchronous first, a far larger change. *Interim (and the recommended answer regardless):* decrypt at the container entrypoint so values land in the environment, which the resolver already reads first — this is what keeps a KMS call off the boot path. | — | blocked |
 
 ---
 

package/framework/v0.6.4/VERSION

@@ -0,0 +1 @@
+0.6.4

package/framework/v0.6.4/core/asset/plugin/dist/vendor/gina/css/gina.min.css

@@ -0,0 +1 @@
+@charset "UTF-8";@keyframes gina-loading-pulse{0%{opacity:1}to{opacity:.55}}@keyframes gina-popin-skeleton-shimmer{0%{background-position:200%0}to{background-position:-200%0}}[data-gina-loading=true]{cursor:progress}@media (prefers-reduced-motion:no-preference){[data-gina-loading=true]{animation:gina-loading-pulse .9s ease-in-out infinite alternate}}@media (prefers-reduced-motion:reduce){[data-gina-loading=true]{opacity:.7}}@font-face{font-family:"have_heart_oneregular";src:url(fonts/have_heart_one-webfont.woff2)format("woff2"),url(fonts/have_heart_one-webfont.woff)format("woff");font-weight:400;font-style:normal}.gina-popin-container{background:#fff}.gina-popins-overlay,div.gina-popin-container{visibility:hidden;opacity:0;z-index:1;transition:opacity .3s,visibility 0 .3s}.gina-popins-overlay.gina-popin-is-active,div.gina-popin-container.gina-popin-is-active{opacity:1;visibility:visible;transition-delay:0}dialog.gina-popin-container{padding:0;border:0;z-index:1}@media (prefers-reduced-motion:no-preference){dialog.gina-popin-container{opacity:0;transform:translateY(-.5rem);transition:opacity .2s ease,transform .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]{opacity:1;transform:translateY(0)}@starting-style{dialog.gina-popin-container[open]{opacity:0;transform:translateY(-.5rem)}}dialog.gina-popin-container::backdrop{opacity:0;transition:opacity .2s ease,overlay .2s ease allow-discrete,display .2s ease allow-discrete}dialog.gina-popin-container[open]::backdrop{opacity:1}@starting-style{dialog.gina-popin-container[open]::backdrop{opacity:0}}}body[data-gina-popin-scroll-lock]{overflow:hidden}.gina-popins-overlay{position:fixed;left:0;top:0;display:grid;place-items:center;width:100%;height:100%;transition:opacity .3s,visibility .3s;overflow:auto;background:rgba(0,0,0,.75)}.gina-popins-overlay.gina-popin-is-active{backdrop-filter:blur(6px)}dialog::backdrop{background-color:rgba(0,0,0,.75);backdrop-filter:blur(6px)}.gina-popin-skeleton{padding:1.5rem;min-width:18rem;max-width:90vw}.gina-popin-skeleton .gina-popin-skeleton-line{height:.85rem;margin-bottom:.75rem;border-radius:4px;background:linear-gradient(90deg,#ededed 25%,#f7f7f7 50%,#ededed 75%);background-size:200% 100%;animation:gina-popin-skeleton-shimmer 1.4s ease-in-out infinite}.gina-popin-skeleton .gina-popin-skeleton-line:last-child{margin-bottom:0}.gina-popin-skeleton .gina-popin-skeleton-title{height:1.4rem;width:60%;margin-bottom:1.25rem}.gina-popin-skeleton .gina-popin-skeleton-line--short{width:40%}@media (prefers-reduced-motion:reduce){.gina-popin-skeleton .gina-popin-skeleton-line{animation:none}}