gina 0.5.12 → 0.5.13

package/CHANGELOG.md

@@ -6,9 +6,13 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
 and is generated by [Changie](https://github.com/miniscruff/changie).
 
 
+## 0.5.13 - 2026-07-08
+### Added
+* Gina now warns at bundle boot when a `_validator` label in a locale catalog cannot be rendered. Built-in rule labels accept only the placeholders `%l` (field label), `%n` (field name) and `%s` (size); any other `%`-token — including a literal percent glued to letters, as in `20%sur le prix` — is substituted with the string "undefined" in the message shown to the user, and a non-string label makes the validator throw. The catalog still loads, and the warning names the offending rule and the catalog file, so a translation typo surfaces in the boot log instead of in production copy.
+
 ## 0.5.12 - 2026-07-08
 ### Added
-* FormValidator built-in rule error messages can now be localised per culture on the client. The negotiated request culture is exposed to the browser as `gina.config.culture`, and an app registers its own per-culture label overrides via `gina.validator.setErrorLabels(labels[, culture])`; English defaults fill any untranslated rule, with a culture -> base-language -> English fallback. This matches the framework per-bundle i18n model — custom rule messages were already localisable, and this closes the gap for the built-in labels without the framework shipping translations. Server-side rendering keeps the English defaults for now.
+* FormValidator built-in rule error messages can now be localised per culture on the client. The negotiated request culture is exposed to the browser as `gina.config.culture`, and an app registers its own per-culture label overrides via `gina.validator.setErrorLabels(labels[, culture])`; English defaults fill any untranslated rule, with a culture -> base-language -> English fallback. This matches the framework per-bundle i18n model — custom rule messages were already localisable, and this closes the gap for the built-in labels without the framework shipping translations.
 * Per-bundle i18n message catalogs (`bundle/locales/<culture>.json`) are now loaded at bundle boot, activating URL-prefix, cookie, and Accept-Language culture negotiation and `t()` / the `t` template filter for any bundle that ships a `locales/` directory. Loading is opt-in and non-fatal: a bundle with no `locales/` directory is unaffected, and a malformed catalog is warned rather than blocking boot.
 * Forms declaring `data-gina-form-rule` with a matching rule set now validate in the browser automatically at page load — the client bundle boots the form validator itself, so no per-page boot code is required (the same batteries-included behaviour the built-in `data-gina-dialog` popin already has). Bundle code constructs the validator explicitly only to attach submit/lifecycle handlers; that still works and is idempotent with the auto-boot.
 * Server-side FormValidator built-in rule error labels now localise from the bundle catalog, mirroring the client side. Pass the negotiated culture to the validator and the built-in labels (isEmail, isRequired, and the rest) resolve from `bundle/locales/<culture>.json` under the `_validator.<rule>` namespace, with the English defaults filling any gaps and a culture -> base-language -> English fallback. A per-field or per-rule error message still takes precedence.

package/README.md

@@ -42,6 +42,10 @@ 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.13
+
+- **Added — unrenderable `_validator` catalog labels are caught at bundle boot.** Gina now warns when a `_validator` label in a locale catalog cannot be rendered. Built-in rule labels accept only the placeholders `%l` (field label), `%n` (field name) and `%s` (size); any other `%`-token — including a literal percent glued to letters, as in `20%sur le prix` — is substituted with the string `undefined` in the message shown to the user, and a non-string label makes the validator throw. The catalog still loads, and the warning names the offending rule and the catalog file, so a translation typo surfaces in the boot log instead of in production copy.
+
 ## What's in 0.5.12
 
 - **Added — FormValidator built-in rule labels localise from the i18n catalog, client and server.** The built-in rule messages (`isEmail`, `isRequired`, and the rest) now resolve per culture from `bundle/locales/<culture>.json` under the `_validator.<rule>` namespace, on both the server-rendered and client-side validation paths — English defaults fill any gaps, with a culture → base-language → English fallback. An app can still override per key with `gina.validator.setErrorLabels(labels[, culture])` (precedence: `setErrorLabels` > bundle catalog > English), and a per-field or per-rule message still wins over all of it.

package/ROADMAP.md

@@ -37,6 +37,7 @@ This roadmap covers planned features, architectural improvements, new connectors
 | **Q3 2026** | `0.5.10` ✅ | **Fixed**: server-side cross-bundle `getRoute('route@bundle').toUrl()` now resolves the public host on reverse-proxied deployments — a controller building a cross-bundle URL server-side (e.g. via `self.redirect`) could emit an unreachable internal host with a doubled web root on a proxied request; it now resolves the public host for both the Isaac and Express engines. Completes the `0.5.9` client-side cross-bundle URL fix on the server side (#B67) |
 | **Q3 2026** | `0.5.11` ✅ | `image:build` — first-class OCI packaging: synthesizes a Containerfile + build context from the project's registered state (bundles, entry, ports, env model, node floor) and builds with buildah, natively on Linux or on a container host over ssh (env override → native → `container.host` settings fallback); dev/prod parity (a non-dev env ships the release tree built in-image), deterministic `EXPOSE`, `${secret:KEY}` placeholders never baked; `--emit` / `--format=json` / `--stream` NDJSON for CI and GUI consumers · **Fixed**: framework-emitted redirects on proxied requests carry no-store cache headers, so a browser never caches a proxy-context-derived redirect (the inter-bundle query 3xx forward path inherits the set; direct production redirects unchanged) |
 | **Q3 2026** | `0.5.12` ✅ | FormValidator built-in rule labels localise from the per-bundle i18n catalog (`_validator.<rule>`) on both the client and server, with a `gina.validator.setErrorLabels()` per-key override · per-bundle i18n catalogs activate URL-prefix / cookie / `Accept-Language` culture negotiation and `t()` at boot, and the negotiated culture now reaches every request (it previously resolved to `en`/empty #B83, and was dropped on warm/cached reloads #B84) · `data-gina-form-rule` forms auto-boot the client validator · **Fixed**: validator correctness (empty-required single message #B78, cross-field `is` empty operand #B82, submit trigger stays operable via `aria-disabled` #B76), popin / redirect robustness (#B80 / #B77 / #B75, static directory-to-index 301 outside dev), and CLI robustness (malformed `@<project>` rejected #B69, `GINA_HOMEDIR` re-export across child commands, `project:start` / `service:start` delegation, zero-bundle bulk commands, `framework:add` install hint #B81) |
+| **Q3 2026** | `0.5.13` ✅ | Unrenderable `_validator` catalog labels are caught at bundle boot — an unknown `%`-token (anything but `%l` / `%n` / `%s`, including a literal percent glued to letters as in `20%sur le prix`), a non-string label, or a non-object `_validator` section now warns and names the offending rule and catalog file. Warn-only: the catalog still loads, so a translation typo surfaces in the boot log instead of in production copy |
 | **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 |
 

package/framework/v0.5.13/VERSION

@@ -0,0 +1 @@
+0.5.13

package/framework/{v0.5.12 → v0.5.13}/lib/i18n/src/main.js

@@ -69,6 +69,41 @@ var DEFAULT_FALLBACK_LANG = 'en';
  */
 var CULTURE_FILENAME = /^([a-z]{2,3})(_([A-Z]{2,3}))?\.json$/;
 
+/**
+ * Reserved catalog namespace holding gina's built-in FormValidator rule labels.
+ * Both label overlays resolve this node — the server engine
+ * (`core/plugins/lib/validator/src/form-validator.js`) and the client whisper
+ * (`core/controller/controller.js`, which ships the subset to the browser).
+ *
+ * @memberof module:gina/lib/i18n
+ * @constant
+ * @type {string}
+ */
+var VALIDATOR_NAMESPACE = '_validator';
+
+/**
+ * Placeholder tokens the validator engine substitutes inside a rule label.
+ * MUST mirror `local.keys` in `core/plugins/lib/validator/src/form-validator.js`
+ * (`%l` -> label, `%n` -> name, `%s` -> size). Case-sensitive on purpose: the
+ * engine looks each matched token up verbatim, so `%L` resolves to `undefined`
+ * exactly as `%d` does.
+ *
+ * @memberof module:gina/lib/i18n
+ * @constant
+ * @type {string[]}
+ */
+var VALIDATOR_LABEL_TOKENS = ['%l', '%n', '%s'];
+
+/**
+ * Token shape the validator engine's `replace()` scans for. Kept identical to
+ * the engine's own regex so this lint sees exactly what will be substituted.
+ *
+ * @memberof module:gina/lib/i18n
+ * @constant
+ * @type {RegExp}
+ */
+var VALIDATOR_TOKEN_RE = /%[a-z]+/gi;
+
 /**
  * Track bundles for which a missing-catalog warn has already fired
  * (one warn per bundle per process lifetime, regardless of how many
@@ -199,6 +234,72 @@ function splitCulture(culture) {
     return [s.substring(0, i), s.substring(i + 1)];
 }
 
+/**
+ * Warn on `_validator` labels the FormValidator engine cannot render correctly.
+ *
+ * The engine substitutes every token matching {@link VALIDATOR_TOKEN_RE} it finds
+ * in a label, looking each one up verbatim in its `local.keys` map. An unknown
+ * token — `%d`, `%L`, or a bare percent glued to letters as in `20%sur le prix` —
+ * resolves to `undefined` and is spliced into user-facing copy; a non-string label
+ * makes the engine's `replace()` throw (`target.match is not a function`). Both are
+ * catalog-authoring mistakes, and the catalog is parsed only here, so this is the
+ * one place to surface them before a request renders them.
+ *
+ * Warns once per offending label at boot and never throws — a translation typo
+ * must not take a bundle down. This covers the client too: the browser's
+ * `gina.config.validatorLabels` is a subset of this same boot-loaded catalog.
+ * It does NOT cover labels supplied at runtime via `gina.validator.setErrorLabels()`.
+ *
+ * @memberof module:gina/lib/i18n
+ * @inner
+ * @param   {object} catalog  - Parsed catalog root.
+ * @param   {string} filePath - Absolute path to the catalog, for the operator message.
+ * @returns {number} Number of warnings emitted; `0` when the catalog is clean.
+ *
+ * @example
+ *   // locales/fr.json -> { "_validator": { "isRequired": "Remise 100%sur le prix" } }
+ *   warnOnSuspectValidatorLabels(catalog, '/srv/app/dashboard/locales/fr.json');
+ *   // -> [i18n] `_validator.isRequired` in ... contains unknown placeholder `%sur` ...
+ */
+function warnOnSuspectValidatorLabels(catalog, filePath) {
+    var node = catalog[VALIDATOR_NAMESPACE];
+    if ( typeof node === 'undefined' || node === null ) {
+        return 0; // absent: the normal case for a bundle that translates nothing else
+    }
+    if ( typeof node !== 'object' || Array.isArray(node) ) {
+        console.warn('[i18n] `' + VALIDATOR_NAMESPACE + '` in ' + filePath
+            + ' must be an object mapping rule names to labels — ignoring it');
+        return 1;
+    }
+    var count = 0;
+    for (var rule in node) {
+        if ( !Object.prototype.hasOwnProperty.call(node, rule) ) {
+            continue;
+        }
+        var label = node[rule];
+        if ( typeof label !== 'string' ) {
+            console.warn('[i18n] `' + VALIDATOR_NAMESPACE + '.' + rule + '` in ' + filePath
+                + ' must be a string — the validator throws when it renders a non-string label');
+            count++;
+            continue;
+        }
+        var tokens = label.match(VALIDATOR_TOKEN_RE);
+        if ( !tokens ) {
+            continue;
+        }
+        for (var t = 0; t < tokens.length; t++) {
+            if ( VALIDATOR_LABEL_TOKENS.indexOf(tokens[t]) < 0 ) {
+                console.warn('[i18n] `' + VALIDATOR_NAMESPACE + '.' + rule + '` in ' + filePath
+                    + ' contains unknown placeholder `' + tokens[t] + '` — it renders as "undefined".'
+                    + ' Known tokens: ' + VALIDATOR_LABEL_TOKENS.join(', ')
+                    + ' (a literal percent must not be followed by letters)');
+                count++;
+            }
+        }
+    }
+    return count;
+}
+
 /**
  * Eager-load every culture catalog under `<dir>/locales/`. Called once per
  * bundle at boot. Files must match {@link CULTURE_FILENAME}; non-matching
@@ -263,6 +364,8 @@ function loadCatalogs(bundleName, dir) {
         if ( parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) ) {
             throw new Error('[i18n] catalog root must be an object: ' + filePath);
         }
+        // Surface unrenderable built-in validator labels while the catalog is in hand.
+        warnOnSuspectValidatorLabels(parsed, filePath);
         store[bundleName][culture] = parsed;
         loaded.push(culture);
     }

package/framework/{v0.5.12 → v0.5.13}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina-framework",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "dependencies": {
     "@rhinostone/swig": "^2.7.2",
     "intl-messageformat": "^11.2.4",

package/gna.js

@@ -15,14 +15,14 @@
 'use strict';
 
 // Framework core — the main gna module (lifecycle hooks, lib, etc.)
-var _gna = require('./framework/v0.5.12/core/gna');
+var _gna = require('./framework/v0.5.13/core/gna');
 
 // SuperController and EntitySuper — loaded from their source modules
-var SuperController = require('./framework/v0.5.12/core/controller');
-var EntitySuper     = require('./framework/v0.5.12/core/model/entity');
+var SuperController = require('./framework/v0.5.13/core/controller');
+var EntitySuper     = require('./framework/v0.5.13/core/model/entity');
 
 // uuid — from the lib registry
-var uuid = require('./framework/v0.5.12/lib/uuid');
+var uuid = require('./framework/v0.5.13/lib/uuid');
 
 module.exports = {
 

package/llms.txt

@@ -973,7 +973,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 221. **FormValidator marks an invalid submit trigger with `aria-disabled` + `.gina-form-submit-disabled`, NOT native `disabled` (#B76, 2026-07-06).** `updateSubmitTriggerState`'s invalid + live-check-on branch used to set the submit `<button>`'s native `.disabled = true`, but a natively-disabled `<button>` emits no click event — so the form-level `validate.<id>` guard (which renders every field's errors + focuses the first invalid field, and only `send()`s when `isValid()`) never fired, and the button was a dead no-op with zero feedback. The HIDE branch now sets `aria-disabled="true"` + adds the class `gina-form-submit-disabled` (keeping the trigger OPERABLE so the click still runs the guard) while `isValid()` stays the real send gate; the SHOW branch KEEPS clearing native `disabled` so a `<button disabled>` in markup still enables on valid / when live-check is off. Tag-agnostic (works for `<button>` and `<a>`; `.disabled=false` on an anchor is a harmless expando). The Enter-key/native-submit DOMParser proxy that read `submitTrigger.disabled` off a re-parsed copy simply never cancels on the invalid path now — harmless: the native submit is still cancelled by the `withRules || isBinded` branch and the `isValid()` gate still blocks the send. **Consumers must style the `[aria-disabled="true"]` / `.gina-form-submit-disabled` submit-trigger state — the framework ships no button CSS.** `main.js` is browser-bundled → a prod dist rebuild is required. Two testing gotchas: jsdom does NOT model "a disabled control emits no click" (it dispatches click on disabled buttons), so the bug is asserted via the pre-fix disabled STATE in a subtract replica; and the consumer-styling comment names the class, so pin the `classList.(add|remove)('gina-form-submit-disabled')` code form (==2), not a bare string count (==3). Tests: `validator-submit-trigger-state.test.js` (18).
 
-222. **FormValidator built-in rule labels localise per culture from ONE per-bundle catalog on BOTH client and server — app-owned, the framework ships NO translations (0.5.x, validator i18n Slices 1–3).** The 26 English defaults live in `form-validator.js` as `_defaultErrorLabels`; each rule resolves `this.error || local.errorLabels[rule]` (per-field app override wins, else the default), and the engine seeds `local.errorLabels` from the defaults then overlays the negotiated culture's labels from the same `_validator.<rule>` catalog namespace both sides read. **CLIENT overlay** (`isGFFCtx`-gated) applies two layers over English with precedence **app `setErrorLabels()` > server-whispered bundle catalog > English**: layer 3 reads the `setErrorLabels()` registry `gina.validator._errorLabelsByCulture[gina.config.culture]` (exact `fr_FR` → base `fr` fallback); layer 2 reads `gina.config.validatorLabels` — the culture's `_validator` subset from `bundle/locales/<culture>.json` whispered by the render path (`controller.js` resolves it via `lib.i18n` walkFallback→getCatalog→resolveKey, `encodeRFC5987ValueChars`-encoded into `page.environment.validatorLabels`; `loader.js` reads it into `gina.config.validatorLabels` with a GUARDED `JSON.parse(decodeURIComponent(…))` IIFE — NOT a bare parse like `routing`, an empty whisper would throw and kill `onGinaLoaded` → whole-page JS dead — plus `@js_externs validatorLabels`). Each layer is `merge(JSON.clone(layer), local.errorLabels)` (lib/merge is target-wins/source-fills, so a higher layer wins per key and lower layers fill), catalog applied FIRST then registry; an empty `{}` catalog is skipped (own-key guard) so it degrades to registry/English. **SERVER overlay** (`!isGFFCtx`): passing a string `culture` to `gina.plugins.Validator` resolves the same `_validator` node (same walkFallback→getCatalog→resolveKey chain) and merges it over English. Apps register client overrides through the public `gina.validator.setErrorLabels(labels[, culture])`. Matches the framework's per-bundle "app owns catalogs" i18n stance (`bundle/locales` + `t()`); custom user rules already carry app messages and are untouched; a per-field/rule `error` still wins. **Two SERVER constraints (measured):** routing.json `validator::{}` requirement labels stay English (those validators run during route-matching, BEFORE culture negotiation → `req.culture` undefined there), and the auto-validation path (pass a rules object) has a pre-existing null-`$fields` crash at `forEachField` orthogonal to i18n — so the working server path is the MANUAL `new gina.plugins.Validator({}, data, formId, req.culture)` + `v.field.rule(...)`. Closure keeps the cross-module property names via the quoted-literal-decl + dot-read + `@js_externs` pattern; both files browser-bundled → any edit needs a prod dist rebuild (the 4 `gina.*` + 3 `gina.onload.*`). Tests: `test/lib/validator-label-i18n.test.js` (client registry layer) + `test/lib/validator-label-i18n-server.test.js` (server) + `test/lib/validator-label-i18n-client-catalog.test.js` (client catalog + 3-layer precedence).
+222. **FormValidator built-in rule labels localise per culture from ONE per-bundle catalog on BOTH client and server — app-owned, the framework ships NO translations (0.5.x, validator i18n Slices 1–3).** The 26 English defaults live in `form-validator.js` as `_defaultErrorLabels`; each rule resolves `this.error || local.errorLabels[rule]` (per-field app override wins, else the default), and the engine seeds `local.errorLabels` from the defaults then overlays the negotiated culture's labels from the same `_validator.<rule>` catalog namespace both sides read. **CLIENT overlay** (`isGFFCtx`-gated) applies two layers over English with precedence **app `setErrorLabels()` > server-whispered bundle catalog > English**: layer 3 reads the `setErrorLabels()` registry `gina.validator._errorLabelsByCulture[gina.config.culture]` (exact `fr_FR` → base `fr` fallback); layer 2 reads `gina.config.validatorLabels` — the culture's `_validator` subset from `bundle/locales/<culture>.json` whispered by the render path (`controller.js` resolves it via `lib.i18n` walkFallback→getCatalog→resolveKey, `encodeRFC5987ValueChars`-encoded into `page.environment.validatorLabels`; `loader.js` reads it into `gina.config.validatorLabels` with a GUARDED `JSON.parse(decodeURIComponent(…))` IIFE — NOT a bare parse like `routing`, an empty whisper would throw and kill `onGinaLoaded` → whole-page JS dead — plus `@js_externs validatorLabels`). Each layer is `merge(JSON.clone(layer), local.errorLabels)` (lib/merge is target-wins/source-fills, so a higher layer wins per key and lower layers fill), catalog applied FIRST then registry; an empty `{}` catalog is skipped (own-key guard) so it degrades to registry/English. **SERVER overlay** (`!isGFFCtx`): passing a string `culture` to `gina.plugins.Validator` resolves the same `_validator` node (same walkFallback→getCatalog→resolveKey chain) and merges it over English. Apps register client overrides through the public `gina.validator.setErrorLabels(labels[, culture])`. Matches the framework's per-bundle "app owns catalogs" i18n stance (`bundle/locales` + `t()`); custom user rules already carry app messages and are untouched; a per-field/rule `error` still wins. **Two SERVER constraints (measured):** routing.json `validator::{}` requirement labels stay English (those validators run during route-matching, BEFORE culture negotiation → `req.culture` undefined there), and the auto-validation path (pass a rules object) has a pre-existing null-`$fields` crash at `forEachField` orthogonal to i18n — so the working server path is the MANUAL `new gina.plugins.Validator({}, data, formId, req.culture)` + `v.field.rule(...)`. **`%`-token contract (measured 2026-07-08).** `replace()` substitutes tokens in the MERGED `local.errorLabels`, so a CATALOG label interpolates exactly like an English default — load-bearing because length bounds arrive as ARRAY args (`"isString": [5]`, spread through `apply()` in `main.js`) and therefore reach `isStringMinLength`/`isStringMaxLength`, keys no rule file ever names (grepping rule files for them returns 0 and wrongly reads as dead). The vocabulary is CLOSED and CASE-SENSITIVE: `replace()` matches `/%[a-z]+/gi` GREEDILY and looks each hit up verbatim in `local.keys` (`%l`→label, `%n`→name, `%s`→size), so an unknown token (`%d`, `%L`) — or a literal percent glued to letters (`20%sur le prix` matches `%sur`) — splices the literal string `undefined` into user-facing copy, and a NON-STRING label makes `replace()` throw `target.match is not a function`. `%l` is frontend-only (it reads the DOM `data-gina-form-field-label`), so a catalog label using it renders EMPTY server-side rather than `undefined`. `lib/i18n loadCatalogs` LINTS the `_validator` node at boot (warns per offending label, never throws, catalog still loads); it covers the client too (the whisper is a subset of the same boot-loaded catalog) but NOT runtime `setErrorLabels()` labels, and its token set is drift-pinned against `local.keys`. **Labels are LATE-BOUND per validation pass (measured).** The overlay lives in the `FormValidatorUtil` CONSTRUCTOR, and `validate()` builds a FRESH engine on every pass (`main.js` ~`:7145`/`:7154`/`:7157`) — not once at bind time — so `setErrorLabels()` called AFTER `new FormValidator(...)`, canonically inside a `ready` handler (which fires immediately after `gina.validator = instance`), applies from the NEXT pass; it does NOT retroactively change a pass already in flight, since the message string is interpolated at rule-evaluation time. **Catalog-load signal (measured correction).** A `locales/*.json` filename failing `CULTURE_FILENAME` (`fr-FR.json`, `fr_fr.json`) DOES warn and is skipped; the genuinely SILENT case is a MISSING `locales/` dir (`config.js` `fs.existsSync` with no `else`) — opt-in by design. Catalogs are boot-loaded with no hot reload, so a catalog edit needs a bundle restart. Closure keeps the cross-module property names via the quoted-literal-decl + dot-read + `@js_externs` pattern; both validator files browser-bundled → any edit needs a prod dist rebuild (the 4 `gina.*` + 3 `gina.onload.*`), but `lib/i18n` is server-only so the boot lint needs none. Tests: `test/lib/validator-label-i18n.test.js` (client registry layer) + `test/lib/validator-label-i18n-server.test.js` (server) + `test/lib/validator-label-i18n-client-catalog.test.js` (client catalog + 3-layer precedence) + `test/lib/validator-label-i18n-runtime.test.js` (%-token interpolation from a catalog label, the boot lint, late binding).
 
 223. **Per-request culture negotiation was INERT framework-wide until 0.5.x — `req.culture` / the whispered `gina.config.culture` always `'en'`/`''` regardless of bundle or environment culture, and `t()` / the `t` template filter returned keys — now activated (#I18N Slice 1).** The #I18N1 catalog + negotiation machinery shipped but three legs were dead: `lib/i18n loadCatalogs` had ZERO runtime callers (so `process.gina._i18nCatalogs` stayed empty → `core/server.js availableCultures` `[]` → `matchAvailable` null on an empty list → URL-prefix / cookie / `Accept-Language` never matched); the per-request `negotiateCulture` call passed `defaultCulture: null` (step-4 bundle default skipped); and 8 sites read `process.env.GINA_CULTURE`, which `utils/helper.js` moves into `process.gina` and DELETEs from `process.env` at init (`getEnvVar` reads `process.gina`), so `negotiateCulture` step 5, the `server.js` catch, both swig + both nunjucks `t`/`tIcu` filter fallbacks, and the `i18n:add` CLI all read an always-undefined var → negotiation fell to step 6 = `'en'`. Fix (server-side, NO dist rebuild): `config.js loadBundleConfig` (after the `secrets.resolve` seam) calls `i18n.loadCatalogs(bundle, <bundleRoot>/locales)` guarded by `fs.existsSync` (opt-in; also avoids loadCatalogs' empty-entry + background ICU-loader side effects) + `try/catch`→`console.warn` (a malformed catalog is warned, not boot-fatal — loadCatalogs THROWS on bad JSON); `server.js` reads the matched bundle `content.settings.region.culture` (format-guarded vs an unresolved `${culture}`) as `defaultCulture`; the 8 dead reads → the live `getEnvVar('GINA_CULTURE')` (`typeof getEnvVar === 'function'`-guarded in the strict global-free `lib/i18n` + the filter modules so an isolated unit-require never ReferenceErrors). Precedence now live: URL / cookie / `Accept-Language` > bundle `settings.region.culture` > operator `GINA_CULTURE` > `'en'`. **`settings.region.culture` is the REAL per-bundle culture key** — bundle scaffold `core/template/boilerplate/bundle/config/settings.json` `"culture":"${culture}"` (full underscore culture resolved at `bundle:add`; the merged config carries it — `server.js`/`controller.js` already read `content.settings.region.{timeZone,shortCode}`), NOT `settings.locale.region` (a country code in the framework `settings.json`'s separate CLDR `locale` block). Blast radius: framework-wide — `req.culture`/`gina.config.culture` now reflect the configured culture, `t()` resolves real strings for any bundle shipping a `locales/` dir (others unaffected via the `existsSync` guard). Makes the #222 client validator-label overlay (gated on a truthy `gina.config.culture`) actually reachable; Slice 1 of the validator + i18n unification. **#B84 (same day) completes the activation on the WARM route path:** Slice 1 negotiated `req.culture` only on the COLD (uncached) path — `core/server.js handle()`'s cached-route fast-path (`if ( hasCachedRoute ) { isRoute = hasCachedRoute; … break; }` ~`:4964`) breaks the routing loop BEFORE the cold-path negotiation site (~`:5115`), and the route cache persists across requests (the module-scoped `routingLib` at `:91` is a stable gen-0 binding — server.js is load-once; `Routing._cached` is set at `:5198` on the cold request and read at `:4964` on every later hit to the same `method:pathname`), so the SECOND hit to any URL is warm and left `req.culture` unset → `controller.js` embeds `''` into `page.environment.culture` → `gina.config.culture === ''` → the #222 client overlay inert on warm reloads (a warm BROWSER reload reproduces; `curl` masks it — a fresh cold-only hit after a restart still negotiates). Fixed by extracting the negotiation into a per-request `var _negotiateReqCulture = function(req, routeBundle)` closure in `handle()` scope, called on BOTH the warm (`( req.routing && req.routing.bundle ) || bundle` — `getCached` already ran `compareUrls`→`checkRouteParams`, so `req.routing` incl. `bundle`/`culturePrefix` is populated) and cold (`routing[name].bundle`) paths. **The resolved culture is NEVER cached with the shared route entry** — it's per-request (cookie / Accept-Language), so pinning it would cross-request-bleed (the #B65/#B66 per-request-vs-worker-global class); the consumer's first suggestion "cache `req.culture` with the route" was rejected for exactly this, their second "re-negotiate on the warm path" shipped. **Rule: any per-request state derived after a route match must be re-derived on the cached fast-path too — `if ( hasCachedRoute ) { … break; }` bypasses everything below it in the loop.** Server-side, NO dist rebuild; surfaced by a consumer report-back that Slice 1's cold-only activation had missed. Tests: `test/core/server-culture-negotiation.test.js` (two-path source pins + a behavioural replica of the fast-path-breaks-before-cold-site structure driving the real `negotiateCulture` + a subtract proving the warm-path call is load-bearing) + a daemonless cold→warm `gina-container` boot (`req.culture === 'xx_XX'` on cold AND warm over real HTTP; `''` pre-fix). Established 2026-07-07.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gina",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
   "keywords": [
     "nodejs",
@@ -73,12 +73,12 @@
     "gina-container": "bin/gina-container",
     "gina-init": "bin/gina-init"
   },
-  "main": "./framework/v0.5.12/core/gna",
+  "main": "./framework/v0.5.13/core/gna",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
       "import": "./index.mjs",
-      "require": "./framework/v0.5.12/core/gna.js"
+      "require": "./framework/v0.5.13/core/gna.js"
     },
     "./gna": {
       "types": "./types/gna.d.ts",

package/framework/v0.5.12/VERSION

@@ -1 +0,0 @@
-0.5.12