gina 0.6.2 → 0.6.3

package/framework/{v0.6.2 → v0.6.3}/core/asset/plugin/dist/vendor/gina/js/gina.js

@@ -2197,6 +2197,7 @@ function Merge() {
      * merge({ a: 1 }, { a: 9 }, true)    // { a: 9 }
      * merge([1, 2],   [3, 4])            // [1, 2, 3, 4]
      * merge([1, 2],   [3, 4], true)      // [3, 4]
+     * merge({ a: [null, 'x'] }, { a: [null, 'x'] })  // { a: [null, 'x'] } — null elements are preserved (#B226)
      */
     var browse = function (_target, _source) {
 
@@ -2401,8 +2402,25 @@ function Merge() {
         return target;
     };
 
-    // Will not merge functions items: this is normal
-    // Merging arrays is OK, but merging collections is still experimental
+    /**
+     * Merge two arrays. Will not merge function items: this is normal.
+     * Merging plain arrays is OK, merging collections is still experimental.
+     *
+     * `null` elements are VALUES and are preserved (#B226): `typeof null ==
+     * 'object'`, so the object-exclusion guards below each carry an explicit
+     * null exception — without it a no-override merge silently dropped `null`
+     * from arrays (while `''` / `false` / `0` survived), which stripped the
+     * first slot of positional argument arrays such as the documented
+     * validator rule `"setFlash": [null, "message"]` on the client-side
+     * rules path.
+     *
+     * @inner
+     * @private
+     * @param {Array} options  - Source array (merged INTO target)
+     * @param {Array} target   - Target array (wins on conflicts unless `override`)
+     * @param {boolean} override - `true` lets `options` win / replace
+     * @returns {Array|undefined} the merged array
+     */
     var mergeArray = function(options, target, override) {
         newTarget = [];
 
@@ -2507,7 +2525,12 @@ function Merge() {
             // ok, but don't merge objects
             a = 0;
             for (; a < target.length; ++a ) {
-                if ( typeof(target[a]) != 'object' && newTarget.indexOf(target[a]) == -1 ) {
+                // #B226 — typeof null == 'object': a null element is a value
+                // (e.g. the first slot of a positional rule-argument array),
+                // not a collection item to exclude; this rebuild dropped it
+                // while '' / false / 0 survived
+                // was: if ( typeof(target[a]) != 'object' && newTarget.indexOf(target[a]) == -1 ) {
+                if ( ( typeof(target[a]) != 'object' || target[a] === null ) && newTarget.indexOf(target[a]) == -1 ) {
                     newTarget.push(target[a]);
                 }
             }
@@ -2592,7 +2615,11 @@ function Merge() {
                     localKeyComparison = ownPropertyNames;
                     if ( target.indexOf(options[a]) > -1 && override) {
                         target.splice(target.indexOf(options[a]), 1, options[a])
-                    } else if ( typeof(newTarget[a]) == 'undefined' && typeof(options[a]) == 'object' ) {
+                    // #B226 — a null source element must not enter the index-merge:
+                    // `for (var k in null)` is a no-op, so null used to surface as
+                    // `{}` here; let it fall through to the primitive push below
+                    // was: } else if ( typeof(newTarget[a]) == 'undefined' && typeof(options[a]) == 'object' ) {
+                    } else if ( typeof(newTarget[a]) == 'undefined' && typeof(options[a]) == 'object' && options[a] != null ) {
                         // merge using index
                         newTarget = target;
 
@@ -2637,7 +2664,9 @@ function Merge() {
                                newTarget[a] = target[a]
                         }
                         // array with string key
-                        else if (newTarget.indexOf(options[a]) == -1 && typeof(options[a]) != 'object') {
+                        // #B226 — same typeof-null exception as the rebuild above
+                        // was: else if (newTarget.indexOf(options[a]) == -1 && typeof(options[a]) != 'object') {
+                        else if (newTarget.indexOf(options[a]) == -1 && ( typeof(options[a]) != 'object' || options[a] === null )) {
                             newTarget.push(options[a]);
                         }
                         // collection without keyComparison
@@ -3009,7 +3038,11 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
         'isStringMaxLength': 'Should not be more than %s characters',
         'isJsonWebToken': 'Must be a valid JSON Web Token',
         'query': 'Must be a valid response',
-        'isApiError': 'Condition not satisfied',
+        // #B233 rider - dropped: `isApiError` is not a rule, so nothing ever consulted this
+        // label. The API-error path assigns the SERVER's message straight onto the error
+        // object (main.js `errorObject[f].isApiError = result.fields[f]`) and never calls
+        // replace(), so the entry only read as a translatable key that silently did nothing.
+        //'isApiError': 'Condition not satisfied',
         'isInList': 'Must be one of: %s'
     };
     /**
@@ -4023,19 +4056,20 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
             var errors      = self[this['name']]['errors'] || {};
             local.data[this.name] = self[this.name].value;
 
-            if (
-                typeof(errors['isRequired']) == 'undefined'
-                && this.value == ''
-                && !/^false$/i.test(this.value)
-                && this.value != 0
-                ||
-                !errors['isRequired']
-                && this.value == ''
-                && !/^false$/i.test(this.value)
-                && this.value != 0
-            ) {
-                isValid = true;
-            } else if (!errors['isRequired'] && typeof(this.value) == 'string' && this.value == '') {
+            // #B233 - an empty value is adjudicated by isRequired alone: bypass on empty so a
+            // required+empty field records only isRequired, not a second 'Condition not
+            // satisfied'. This REVERSES a twice-declined exclusion (#B78 left `is` untouched,
+            // #B82 re-declined it) on measurement: the old bypass was gated on
+            // !errors['isRequired'] — i.e. disabled exactly when #B78 wants it applied — while
+            // optional+empty already self-passed through it; and on required+empty the condition
+            // is verdict-irrelevant (form validity is getErrors().count() and isRequired has
+            // already recorded its error), so only the message list changes.
+            // #B199 - strict: only the literal empty string is "empty". 0, false and null are
+            // VALUES here and still evaluate the condition.
+            // was: a two-disjunct guard whose arms were both DEAD (`x == '' && x != 0` has no
+            // witness — `x == ''` forces ToNumber(x) === 0 for non-strings and x === '' for
+            // strings), followed by the isRequired-gated string-only bypass described above.
+            if ( this.value === '' ) {
                 isValid = true;
             }
 
@@ -4176,7 +4210,8 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
                 //delete errors['stack'];
             }
 
-            this.valid = isValid;
+            // #B78 - keep .valid consistent with a surviving isRequired error.
+            this.valid = isValid && !errors['isRequired'];
             if ( errors.count() > 0 )
                 this['errors'] = errors;
 
@@ -4214,7 +4249,10 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
 
             // #B78 - an empty value is adjudicated by isRequired alone: bypass on empty so a
             // required+empty field records only isRequired, not a second 'invalid' message.
-            if ( this.value == '' ) {
+            // #B199 - strict: only the literal empty string is "empty". The loose ==
+            // let 0, -0, false and [] coerce equal and ride this bypass, so e.g. a
+            // JSON body's 0 in this field PASSED the rule outright.
+            if ( this.value === '' ) {
                 isValid = true;
             }
 
@@ -4256,7 +4294,10 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
 
             // #B78 - an empty value is adjudicated by isRequired alone: bypass on empty so a
             // required+empty field records only isRequired, not a second 'invalid' message.
-            if ( this.value == '' ) {
+            // #B199 - strict: only the literal empty string is "empty". The loose ==
+            // let 0, -0, false and [] coerce equal and ride this bypass, so e.g. a
+            // JSON body's 0 in this field PASSED the rule outright.
+            if ( this.value === '' ) {
                 isValid = true;
             }
 
@@ -4279,35 +4320,58 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
         }
 
         /**
-         * Check if boolean and convert to `true/false` booloean if value is a string or a number
-         * Will include `false` value if isRequired
+         * Check if boolean and convert to `true/false` boolean if value is a string or a number.
+         * Accepts `true`/`'true'`/`1` and `false`/`'false'`/`0` — the documented set.
+         *
+         * #B78 contract (#B235): an EMPTY value is adjudicated by `isRequired`
+         * alone — the rule self-passes on the literal empty string, and the tail
+         * keeps `this.valid` consistent with a surviving isRequired error
+         * (Shape A). An ACCEPTED answer also clears a prior isRequired error:
+         * `false` and `0` are loose-equal to the empty string so isRequired
+         * flags them, but a recognized boolean false is a present answer (an
+         * unchecked-but-required toggle does not fail). The pre-fix rescue ran
+         * BEFORE the switch on a loose equality that also matched the empty
+         * string, deleting the isRequired error a genuinely-empty field had
+         * earned (#B235).
          * */
         self[el]['isBoolean'] = function() {
             var val     = null
                 , errors = self[this['name']]['errors'] || {}
+                , isValid = false
             ;
 
-            if ( errors['isRequired'] && this.value == false) {
+            // #B235 — was (the loose == also matched ''; `isValid = true` was a
+            // dead write into the binding hoisted from below):
+            // if ( errors['isRequired'] && this.value == false) {
+            //     isValid = true;
+            //     delete errors['isRequired'];
+            //     this['errors'] = errors;
+            // }
+
+            if ( this.value === '' ) { // #B78/#B235 — emptiness is isRequired's verdict alone
                 isValid = true;
-                delete errors['isRequired'];
-                this['errors'] = errors;
-            }
+            } else {
+                switch(this.value) {
+                    case 'true':
+                    case true:
+                    case 1:
+                        val = this.value = local.data[this.name] = true;
+                        break;
+                    case 'false':
+                    case false:
+                    case 0:
+                        val = this.value = local.data[this.name] = false;
+                        break;
+                }
 
-            switch(this.value) {
-                case 'true':
-                case true:
-                case 1:
-                    val = this.value = local.data[this.name] = true;
-                    break;
-                case 'false':
-                case false:
-                case 0:
-                    val = this.value = local.data[this.name] = false;
-                    break;
+                isValid = (val !== null) ? true : false;
+                // an engine-ACCEPTED answer clears the error that isRequired's
+                // loose emptiness test recorded on false/0
+                if ( val !== null && errors['isRequired'] ) {
+                    delete errors['isRequired'];
+                }
             }
 
-            var isValid = (val !== null) ? true : false;
-
             if (!isValid) {
                 errors['isBoolean'] = replace(this.error || local.errorLabels['isBoolean'], this, 'isBoolean')
             }
@@ -4317,7 +4381,8 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
                 //delete errors['stack'];
             }
 
-            this.valid = isValid;
+            // #B78 mirror (Shape A): keep .valid consistent with a surviving isRequired error
+            this.valid = isValid && !errors['isRequired'];
             if ( errors.count() > 0 )
                 this['errors'] = errors;
 
@@ -4362,7 +4427,10 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
 
             if ( +val === +val ) {
                 isValid = true;
-                if ( !errors['isRequired'] && val != '' ) {
+                // #B199 - strict !== : the loose != let the Number 0 (and -0/[] — and
+                // '0', which the entry cast turns into 0) coerce equal to '' and skip
+                // the bounds. Only the literal empty string bypasses.
+                if ( !errors['isRequired'] && val !== '' ) {
                     len = val.toString().length;
                     // if so also test max and min length if defined
                     if (minLength && typeof(minLength) == 'number' && len < minLength) {
@@ -4429,6 +4497,33 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
             return self[this.name]
         }
 
+        /**
+         * Check if value is a whole number.
+         *  - valid if the value is a number with no fractional part
+         *  - a numeric string is accepted; the value is cast to a `Number` on the way
+         *    OUT, after the bounds have been evaluated — whereas `isNumber` casts on
+         *    the way IN, before its own bounds. That ordering difference is why the
+         *    two rules must measure length differently at the bound site (see #B198)
+         *  - if the value is blank, no bound test is done: valid if not required
+         *
+         * Optional bounds constrain the LENGTH of the value's string form — the same
+         * arity contract as `isString`/`isNumber`: `[N]` (or the scalar `N`) supplies
+         * `minLength` only, and an exact length needs `[N, N]` since the exact-length
+         * branch fires only when `minLength === maxLength`.
+         *
+         * #B198 — the bounds measure `val.toString().length`, never `val.length`. This
+         * rule accepts a real `Number` (`+val === +val` passes for one), and
+         * `Number.prototype.length` is `undefined`, so `val.length` made both bounds
+         * silently inert on any numeric value — no error, no warn, `valid` left true.
+         * Numbers reach here from JSON request bodies and from a preceding `toInteger`
+         * (which leaves `Math.round()`'s real Number on `this.value`), so the browser
+         * path was affected too. `isNumber` has always measured `toString().length`.
+         *
+         *  @param {number} [ minLength ]
+         *  @param {number} [ maxLength ]
+         *
+         *  @returns {object} result
+         * */
         self[el]['isInteger'] = function(minLength, maxLength) {
             var val             = this.value
                 , isValid       = false
@@ -4440,13 +4535,18 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
             // test if val is a number
             if ( +val === +val && val % 1 === 0 ) {
                 isValid = true;
-                if ( !errors['isRequired'] && val != '' ) {
+                // #B199 - strict !== : the loose != let the Number 0 (and -0/[]) coerce
+                // equal to '' and skip the bounds. Only the literal empty string bypasses.
+                if ( !errors['isRequired'] && val !== '' ) {
                     // if so also test max and min length if defined
-                    if (minLength && typeof(minLength) == 'number' && val.length < minLength) {
+                    // #B198 - was: `val.length`, which is `undefined` on a real Number
+                    // (this rule accepts one, and never casts), so both bounds were
+                    // silently inert. Measure the string form, as `isNumber` does.
+                    if (minLength && typeof(minLength) == 'number' && val.toString().length < minLength) {
                         isMinLength = false;
                         this['size'] = minLength;
                     }
-                    if (maxLength && typeof(maxLength) == 'number' && val.length > maxLength) {
+                    if (maxLength && typeof(maxLength) == 'number' && val.toString().length > maxLength) {
                         isMaxLength = false;
                         this['size'] = maxLength;
                     }
@@ -4618,7 +4718,10 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
 
             // #B78 - an empty value is adjudicated by isRequired alone: bypass on empty so a
             // required+empty field records only isRequired, not a second 'invalid' message.
-            if ( this.value == '' ) {
+            // #B199 - strict: only the literal empty string is "empty". The loose ==
+            // let 0, -0, false and [] coerce equal and ride this bypass, so e.g. a
+            // JSON body's 0 in this field PASSED the rule outright.
+            if ( this.value === '' ) {
                 isValid = true
             }
 
@@ -4723,7 +4826,9 @@ function FormValidatorUtil(data, $fields, xhrOptions, fieldsSet, culture) {
          *      // OR
          *      "isString": [7, 40] // Means at least 7 chars length and maximum 40 chars length
          *      // OR
-         *      "isString": [7] // Means is strickly equal to 7 chars length, same as [7,7]
+         *      "isString": [7] // Means at least 7 chars length, same as 7 above: a one-element array supplies minLength only
+         *      // OR
+         *      "isString": [7, 7] // Means strictly equal to 7 chars length
          *  }
          * }
          * @param {number|undefined} [ minLength ]
@@ -5575,6 +5680,13 @@ function Routing() {
             if ( typeof(routeObject.queryTimeout) != 'undefined' ) {
                 params.queryTimeout = parseTimeout(routeObject.queryTimeout);
             }
+            // #SPA1 — propagate the per-route content-negotiation capability to
+            // req.routing.negotiate (top-level, NOT req.routing.param.* — the #CSRF2
+            // trap). Assigned only when declared, so a routing.json that never mentions
+            // `negotiate` produces a byte-identical params object.
+            if ( typeof(routeObject.negotiate) != 'undefined' ) {
+                params.negotiate = routeObject.negotiate;
+            }
 
             // isRoute
             return self.compareUrls(params, routeObject.url, req);
@@ -6566,7 +6678,12 @@ function Routing() {
         route.toUrl = function (ignoreWebRoot) {
 
             var urlProps = null;
-            if ( /^redirect$/i.test(this.param.control) ) {
+            // Slice 3 (#SPA1) — the client-served map ships the derived boolean
+            // `isRedirect` instead of `param.control` (a dispatch key that stays
+            // server-side); server-side routes still carry the full `param`, so
+            // both forms are honoured. The `this.param &&` guard also keeps a
+            // param-less route from throwing here.
+            if ( this.isRedirect === true || /^redirect$/i.test(this.param && this.param.control) ) {
                 urlProps = self.getUrlProps(this.bundle, (env||GINA_ENV));
             }
 
@@ -10366,13 +10483,205 @@ function ValidatorPlugin(rules, data, formId, culture) {
         'setCustomRules': setCustomRules
     };
 
+    /**
+     * backendIsPlainObject — plain-data-object test for the #B241 alias walk.
+     * Arrays, Date instances and null are LEAF VALUES on the server form-body
+     * path (a rule addresses the array/date itself), never containers to
+     * descend into.
+     *
+     * @inner
+     * @private
+     * @param {*} value
+     * @returns {boolean} true for a non-null, non-array, non-Date object
+     */
+    var backendIsPlainObject = function (value) {
+        return (
+            value !== null
+            && typeof(value) == 'object'
+            && !Array.isArray(value)
+            && !(value instanceof Date)
+        )
+    };
 
     /**
-     * Backend init
+     * backendAliasAugment — #B241: synthesize dotted-canon field entries
+     * ALONGSIDE the raw posted keys so the per-field rule lookup can join.
      *
-     * @param {object} rules
-     * @param {object} [customRule]
-     * */
+     * `parseRules` canonicalizes every rule key to a dotted path (a bracket
+     * key `a[b]` becomes `a.b`, a nested rule tree flattens to its dotted
+     * leaves) while the fields map keeps the RAW posted keys — so a rule
+     * authored on a bracket key, or as a nested tree, never joined on this
+     * path and the field was skipped with no warn (fail-open, check AND
+     * drop directives alike). Both production wire shapes were affected:
+     * flat bracket keys (the client posts the engine's name-keyed data as
+     * JSON, which the server parses verbatim) and nested objects (the
+     * multipart and urlencoded parsers expand bracket names).
+     *
+     * The originals are deliberately KEPT in the map: dollar-token
+     * substitution reads the raw keys, so cross-field references to
+     * bracket-named peers keep resolving exactly as before, and an all-flat
+     * payload synthesizes nothing (identity). An alias is only added when
+     * its key is still free, so a caller that already posts the dotted form
+     * keeps its own entry untouched.
+     *
+     * @inner
+     * @private
+     * @param {object} fields - the fields map to augment IN PLACE
+     * @param {object} data - the raw posted payload (never mutated)
+     * @returns {object} aliases - { count: number, map: { alias: meta } }
+     *   where meta is { kind: 'bracket', original } or
+     *   { kind: 'nested', rootKey, path }
+     */
+    var backendAliasAugment = function (fields, data) {
+        var aliases = { count: 0, map: {} };
+        var addNestedLeafAliases = function (rootKey, base, obj, pathSoFar) {
+            for (var subKey in obj) {
+                var aliasPath = pathSoFar.concat(subKey);
+                var subAlias = base + '.' + subKey;
+                if ( backendIsPlainObject(obj[subKey]) ) {
+                    addNestedLeafAliases(rootKey, subAlias, obj[subKey], aliasPath);
+                } else if ( typeof(fields[subAlias]) == 'undefined' ) {
+                    fields[subAlias] = obj[subKey];
+                    aliases.map[subAlias] = { kind: 'nested', rootKey: rootKey, path: aliasPath };
+                    ++aliases.count;
+                }
+            }
+        };
+        var key = null, alias = null;
+        for (key in data) {
+            if ( /\[/.test(key) ) {
+                alias = key.replace(/\[/g, '.').replace(/\]/g, '');
+                if ( typeof(fields[alias]) == 'undefined' ) {
+                    fields[alias] = data[key];
+                    aliases.map[alias] = { kind: 'bracket', original: key };
+                    ++aliases.count;
+                }
+            } else if ( backendIsPlainObject(data[key]) ) {
+                addNestedLeafAliases(key, key, data[key], [key]);
+            }
+        }
+        return aliases;
+    };
+
+    /**
+     * backendAliasToBracketName — rebuild the client's DOM-name addressing
+     * from a nested alias path (['account','username'] -> account[username]),
+     * so restored error keys match what the browser side renders against.
+     *
+     * @inner
+     * @private
+     * @param {string} rootKey
+     * @param {array} pathArr - path segments, rootKey first
+     * @returns {string} the bracket-notation field name
+     */
+    var backendAliasToBracketName = function (rootKey, pathArr) {
+        var out = rootKey;
+        for (var i = 1, len = pathArr.length; i < len; ++i) {
+            out += '[' + pathArr[i] + ']';
+        }
+        return out;
+    };
+
+    /**
+     * backendRestoreAliases — #B241 egress: fold every alias outcome back
+     * onto the original addressing, so the summary keeps today's contract.
+     *
+     * Error keys move to the DOM-name bracket form (the addressing the
+     * client's error rendering looks up). On `.data` — which the engine has
+     * already materialized (bracket originals arrive nested) — the alias
+     * flat keys are stripped and their outcomes applied at the original
+     * spot: an alias the engine dropped (an `exclude` directive) drops the
+     * original leaf too, an alias a transform rewrote wins over the raw
+     * value. Parents emptied BY AN EXCLUSION are pruned along that alias's
+     * path only — an empty object the caller posted is not this function's
+     * to remove.
+     *
+     * @inner
+     * @private
+     * @param {object} result - the { isValid, error, data } summary (mutated)
+     * @param {object} aliases - backendAliasAugment's return value
+     * @returns {object} result
+     */
+    var backendRestoreAliases = function (result, aliases) {
+        var alias = null, meta = null;
+        var errors = {};
+        for (alias in (result.error || {})) {
+            meta = aliases.map[alias];
+            if ( !meta ) {
+                errors[alias] = result.error[alias];
+            } else if ( meta.kind == 'bracket' ) {
+                errors[meta.original] = result.error[alias];
+            } else {
+                errors[backendAliasToBracketName(meta.rootKey, meta.path)] = result.error[alias];
+            }
+        }
+        result.error = errors;
+
+        var data = result.data;
+        if ( !data || typeof(data) != 'object' ) {
+            return result;
+        }
+        for (alias in aliases.map) {
+            meta = aliases.map[alias];
+            var aliasKept = Object.prototype.hasOwnProperty.call(data, alias);
+            var aliasValue = aliasKept ? data[alias] : undefined;
+            delete data[alias];
+
+            var segments = ( meta.kind == 'bracket' )
+                ? meta.original.replace(/\]/g, '').split(/\[/g)
+                : meta.path;
+            var sLen = segments.length - 1;
+            var parent = data, s = 0;
+            for (; s < sLen && parent; ++s) {
+                parent = parent[ segments[s] ];
+            }
+            if ( !parent || typeof(parent) != 'object' ) {
+                continue;
+            }
+            if ( !aliasKept ) {
+                delete parent[ segments[sLen] ];
+                // walk back up THIS path only, dropping parents the exclusion emptied
+                for (var back = sLen - 1; back >= 0; --back) {
+                    var holder = data, b = 0;
+                    for (; b < back && holder; ++b) {
+                        holder = holder[ segments[b] ];
+                    }
+                    if (
+                        holder
+                        && backendIsPlainObject(holder[ segments[back] ])
+                        && Object.keys(holder[ segments[back] ]).length === 0
+                    ) {
+                        delete holder[ segments[back] ];
+                    } else {
+                        break;
+                    }
+                }
+            } else {
+                parent[ segments[sLen] ] = aliasValue;
+            }
+        }
+        return result;
+    };
+
+    /**
+     * Backend init — the server half of form-body validation.
+     *
+     * Builds the fields map from the posted payload, parses the rule set
+     * into the dotted canon, and runs the engine. #B241: bracket-notation
+     * and nested-authored rule keys join through synthesized dotted aliases
+     * (see backendAliasAugment above); verdict keys and the data egress are
+     * restored to the original addressing before returning. The no-rules
+     * branch is untouched and keeps returning the payload verbatim.
+     *
+     * @inner
+     * @private
+     * @param {object} rules - the form's rule set (authored keys)
+     * @param {object} data - the posted payload
+     * @param {string} [formId]
+     * @param {string} [culture]
+     * @returns {object} the { isValid, error, data } summary, or a bare
+     *   FormValidator instance on the no-rules branch
+     */
     var backendInit = function (rules, data, formId, culture) {
 
         var $form = ( typeof(formId) != 'undefined' ) ? { 'id': formId } : null;
@@ -10386,6 +10695,9 @@ function ValidatorPlugin(rules, data, formId, culture) {
         // parsing rules
         if ( typeof(rules) != 'undefined' && rules.count() > 0 ) {
 
+            // #B241 — join bracket/nested rule keys through dotted aliases
+            var backendAliases = backendAliasAugment(fields, data);
+
             try {
                 parseRules(rules, '');
                 rules = checkForRulesImports(rules);
@@ -10395,7 +10707,16 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
             backendProto.rules = instance.rules;
 
-            return validate($form, fields, null, instance.rules, null, culture)
+            var backendResult = validate($form, fields, null, instance.rules, null, culture);
+            if (
+                backendAliases.count > 0
+                && backendResult
+                && typeof(backendResult.isValid) == 'function'
+                && typeof(backendResult.error) != 'undefined'
+            ) {
+                backendRestoreAliases(backendResult, backendAliases);
+            }
+            return backendResult;
 
         } else {
             // without rules - by hand
@@ -14336,6 +14657,25 @@ function ValidatorPlugin(rules, data, formId, culture) {
         Object.defineProperty($el, 'value', descriptor);
     }
 
+    /**
+     * addLiveForInput
+     * Wires one form control for live checking: registers the gina event
+     * name(s) the control's validation handler consumes, plus the handler
+     * itself (field pass + whole-form silent pass -> updateSubmitTriggerState).
+     * Text-like controls register change./keyup./focusin./focusout.<id>;
+     * radios and checkboxes register changed.<id> (dispatched by their
+     * update relays); a radio ALSO registers change.<id> (#B228) because the
+     * form-level change proxy is the only dispatcher that fires on a user
+     * pick and it only dispatches names that are registered.
+     *
+     * @inner
+     * @param {object} $form - form instance record (`instance.$forms[id]` shape: `.rules`, `.target`)
+     * @param {object} $el - control to wire (DOMObject)
+     * @param {number} liveCheckTimer - shared debounce timer handle
+     * @param {boolean} [isOtherTagAllowed=false] - admit non-input/textarea tags (selects, FACEs)
+     *
+     * @returns {undefined}
+     * */
     var addLiveForInput = function($form, $el, liveCheckTimer, isOtherTagAllowed) {
 
         if (typeof(isOtherTagAllowed) == 'undefined' ) {
@@ -14408,6 +14748,23 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         eventsList[_e] = _evt;
                         ++_e;
                     }
+                    // #B228 -- a RADIO also listens on the proxy-dispatched name: the
+                    // form-level change proxy dispatches `change.<id>` only when that
+                    // exact name is registered, and nothing else fires on a user pick
+                    // (the click proxy short-circuits into updateRadio, which never
+                    // dispatches; the bare-id relay has no live trigger) -- so the
+                    // `changed.<id>` registration above was consume-only dead wiring
+                    // on the pick path and the submit trigger kept its bind-time
+                    // state forever. The handler's radio arm has accepted
+                    // `change.`-typed events all along; checkboxes stay on their
+                    // working relay (change proxy -> updateCheckBox -> `changed.<id>`).
+                    if ( /^radio$/i.test($el.type) ) {
+                        _evt = 'change.'+$el.id;
+                        if ( typeof(gina.events[_evt]) == 'undefined' ) {
+                            eventsList[_e] = _evt;
+                            ++_e;
+                        }
+                    }
                 }
 
                 if (eventsList.length > 0) {
@@ -17308,6 +17665,20 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         $form.send(result['data']);
                     }
                 } else {
+                    // #B192 — release the submit latch. A rejected submit sends nothing, so it
+                    // never reaches the XHR settle (`xhr.onreadystatechange`), which was the only
+                    // other site clearing `isSubmitting`. Left latched, the live-check field
+                    // listener hard-returns on every subsequent keystroke, `updateSubmitTriggerState`
+                    // never runs again and the submit trigger keeps `aria-disabled="true"` +
+                    // `gina-form-submit-disabled` until the page is reloaded — and because the flag
+                    // lives on the `$forms[id]` object rather than a listener closure, it survives a
+                    // full unbind/rebind too. This branch IS the terminal no-send outcome; the valid
+                    // branch above deliberately keeps the latch until send() settles, which is what
+                    // keeps live-check quiet during a real in-flight submit.
+                    if ( instance.$forms[_id] ) {
+                        instance.$forms[_id].isSubmitting = false;
+                    }
+
                     // #A11Y1 (slice 3) — failed submit: move focus to the first invalid field so
                     // assistive tech announces it (accessible name + aria-invalid + the
                     // aria-errormessage text). DOM order; hidden / unfocusable fields are skipped.
@@ -17597,6 +17968,18 @@ function ValidatorPlugin(rules, data, formId, culture) {
                     && !/^(true|false)$/.test($target[i].value)
                     ) {
                         fields[name] = false;
+                    } else if ( // #B221: same collection arm as getFormValidationInfos --
+                        // an unchecked non-boolean radio group with a truthy isRequired
+                        // is collected as an empty value so the submit-path validation
+                        // can adjudicate it (see the twin arm there for the rationale).
+                        $target[i].type == 'radio'
+                        && rules
+                        && typeof(rules[name]) != 'undefined'
+                        && /^true$/i.test(rules[name].isRequired)
+                        && typeof(rules[name].isBoolean) == 'undefined'
+                        && typeof(fields[name]) == 'undefined'
+                    ) {
+                        fields[name] = '';
                     }
 
                 } else {
@@ -17753,8 +18136,17 @@ function ValidatorPlugin(rules, data, formId, culture) {
     /**
      * getFormValidationInfos
      *
+     * Collects a form's named, non-disabled controls into a name->value map
+     * (`fields`) plus a name->DOM-handle map (`$fields`). Radio groups: a
+     * checked member's value is collected by the boolean/legacy arms; an
+     * unchecked non-boolean group whose rule declares a truthy `isRequired`
+     * is collected as an empty string (#B221) so the rule engine can
+     * adjudicate it; any other unchecked group stays absent (native parity;
+     * boolean-declared groups are owned by the force-false arm).
+     *
      * @param {object} $form - form target (DOMObject), not the instance
      * @param {object} [rules]
+     * @param {boolean} [isOnResetMode=false] - resets hidden/text values to their defaults while walking
      *
      * @returns {object} { .fields, .$fields, .rules }
      */
@@ -17910,6 +18302,28 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
                 ) {
                     fields[name] = false;
+                } else if ( // #B221: an unchecked non-boolean radio group with a
+                    // declared truthy isRequired never entered `fields`, so no
+                    // rule (isRequired above all) could adjudicate it -- and a
+                    // radio-group-only form short-circuited the whole pass
+                    // (fields count == 0 reads as nothing-to-validate). Collect
+                    // it as an empty value so the engine's generic emptiness
+                    // test fires. A checked member is always collected by the
+                    // arms above; the already-collected guard keeps this arm
+                    // from resetting it when an unchecked member iterates after
+                    // the checked one. Groups with no rule, isRequired:false,
+                    // or an isBoolean declaration keep the legacy
+                    // absent-when-unchecked shape (boolean groups are owned by
+                    // the force-false arm above; optional groups bypass on
+                    // empty anyway, so their wire shape stays byte-identical).
+                    $form[i].type == 'radio'
+                    && rules
+                    && typeof(rules[name]) != 'undefined'
+                    && /^true$/i.test(rules[name].isRequired)
+                    && typeof(rules[name].isBoolean) == 'undefined'
+                    && typeof(fields[name]) == 'undefined'
+                ) {
+                    fields[name] = '';
                 }
 
             } else {
@@ -17933,6 +18347,26 @@ function ValidatorPlugin(rules, data, formId, culture) {
         }
     }
 
+    /**
+     * getCastedValue
+     * Returns the value to use for `fieldName` — raw for the engine to
+     * adjudicate, or cast/quoted for dynamised-rules substitution.
+     *
+     * Plain mode (`formatFields`): numeric-rule comma normalisation only;
+     * real booleans pass through as-is and every other value stays RAW — the
+     * engine's own rules cast on acceptance (#B236).
+     * Dynamised mode (`getDynamisedRules`): values are spliced into a
+     * stringified condition, so a boolean-ruled field casts to an unquoted
+     * boolean operand, an empty value becomes a quoted empty string, and
+     * other strings are quoted.
+     *
+     * @inner
+     * @param {object} ruleObj - parsed rules (quoted booleans unquoted)
+     * @param {object} fields - collected field values (MUTATED: comma normalisation)
+     * @param {string} fieldName
+     * @param {boolean|string} [isOnDynamisedRulesMode] - truthy/`'true'` in dynamised mode
+     * @returns {*} the raw, cast, or quoted value
+     */
     var getCastedValue = function(ruleObj, fields, fieldName, isOnDynamisedRulesMode) {
 
         var isOnDynamisedRules = (
@@ -17977,7 +18411,16 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
         if ( typeof(fields[fieldName]) == 'boolean') {
             return fields[fieldName]
-        } else if (ruleObj[fieldName].isBoolean) {
+        // #B236 — the boolean pre-cast survives ONLY in dynamised-rules mode, where a
+        // referenced isBoolean field must splice into a stringified condition as an
+        // unquoted boolean operand (`$flag === true`). On the PLAIN pass it funneled
+        // every value not matching the case-insensitive literal `true` to `false`
+        // BEFORE the engine ran, so junk (and the HTML checkbox default `on`, and
+        // the number 1) validated clean and persisted as `false` on the server auto
+        // path. The engine is the single adjudicator now — the same contract the
+        // routing requirements surface always enforced.
+        // was: `} else if (ruleObj[fieldName].isBoolean) {`
+        } else if (isOnDynamisedRules && ruleObj[fieldName].isBoolean) {
             return (/^true$/i.test(fields[fieldName])) ? true : false;
         }
 
@@ -18049,7 +18492,18 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
             stringifiedRules = stringifiedRules.replace(re, fieldValue );
         }
-        if ( /\$(.*)/.test(stringifiedRules) ) {
+        // #B234 — this second loop is a DOM FALLBACK: it re-derives each splice
+        // value from the live element (`$fields[...].value` / `.checked`), and
+        // the server auto path (`backendInit`) passes `$fields = null`, so ANY
+        // `$` surviving loop 1 threw here — a regex end-anchor in an `is`
+        // condition, or a `$` inside a human-readable message string. Loop 1
+        // already replaces every KNOWN field's token, so what reaches loop 2 is
+        // a leftover it structurally cannot match anyway: skipping when there is
+        // no DOM matches what the client does when this re-scan no-ops, and
+        // leaves every previously-working substitution byte-identical. Same
+        // `$fields &&` guard shape as the #B127 precedent one function later.
+        // was: `if ( /\$(.*)/.test(stringifiedRules) ) {`
+        if ( $fields && /\$(.*)/.test(stringifiedRules) ) {
             for (let i = 0, len = arrFields.length; i < len; i++) {
                 _field = arrFields[i].replace(/\-|\_|\@|\#|\.|\[|\]/g, '\\$&');
                 re = new RegExp('\\$'+_field, 'g');
@@ -18114,6 +18568,24 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
 
         var re = null, flags = null, args = null;
+        /**
+         * Apply every rule declared for one field to the FormValidator instance `d`.
+         *
+         * Array-form rules (`isInList: [...]`) get their FIRST argument scanned for
+         * `$`-prefixed tokens; a token resolving to a real field (a `d` key with a
+         * defined `.value`) is substituted with that value, anything else stays
+         * LITERAL (#B239 — the blind deref crashed on unknown names and spliced
+         * "undefined" on engine-method-name collisions). Later elements are never
+         * scanned. Cross-field refs inside array rules are consumed upstream by
+         * getDynamisedRules loop 1 (quoted — #B240), so in practice only leftover
+         * non-field tokens reach the scan here.
+         *
+         * @inner
+         * @param {string} field - field name (key into `rules`, `fields` and `d`)
+         * @param {object} rules - parsed rule set for the whole form
+         * @param {object} fields - collected field values
+         * @returns {void} verdicts land on `d[field]` / `d.error`
+         */
         var checkFieldAgainstRules = function(field, rules, fields) {
             // ignore field if used as a _case_field
 
@@ -18212,7 +18684,25 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         if ( /\$[\-\w\[\]]*/.test(args[0]) ) {
                             var foundVariables = args[0].match(/\$[\-\w\[\]]*/g);
                             for (var v = 0, vLen = foundVariables.length; v < vLen; ++v) {
-                                args[0] = args[0].replace( foundVariables[v], d[foundVariables[v].replace('$', '')].value )
+                                // #B239 — the deref used to be blind, throwing
+                                // `TypeError: Cannot read properties of undefined` on
+                                // BOTH paths for any token naming no field (`d` is the
+                                // FormValidator field map on the client AND the server),
+                                // and splicing the string "undefined" for a token whose
+                                // name collides with an engine METHOD (isValid, toData —
+                                // defined keys with no `.value`). A token that does not
+                                // resolve to a real field now stays LITERAL, so strict
+                                // comparison applies. Cross-field refs inside array
+                                // rules remain owned by #B240 (upstream loop-1 quoting).
+                                // was: args[0] = args[0].replace( foundVariables[v], d[foundVariables[v].replace('$', '')].value )
+                                var _refName = foundVariables[v].replace('$', '');
+                                if (
+                                    typeof(d[_refName]) == 'undefined'
+                                    || typeof(d[_refName].value) == 'undefined'
+                                ) {
+                                    continue;
+                                }
+                                args[0] = args[0].replace( foundVariables[v], d[_refName].value );
                             }
                         }
                         d[field][rule].apply(d[field], args);
@@ -18431,6 +18921,8 @@ function ValidatorPlugin(rules, data, formId, culture) {
             var localRules = null, caseName = null;
             var localRuleObj = null, skipTest = null;
             var localFieldType  = null;
+            var caseValueBackup = null; // #B229 — see the `caseName == field` arm below
+            var baseValueBackup = null; // #B230 — see the base-rule restore below
 
             //console.debug('parsing ', fields, $fields, rules);
             if ( typeof(rules) != 'undefined' ) {
@@ -18815,13 +19307,80 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         }
                     }
 
-                    if (isInCase || caseName == field) continue;
+                    if (isInCase) continue;
+
+                    // #B229 — a field that DRIVES a `_case_` still owns its BASE
+                    // rules. `caseName` is assigned inside the `_case_` scan loop
+                    // above, which runs in full on EVERY field iteration, so at this
+                    // point it always holds the LAST scanned `_case_` key's driver
+                    // name. The old combined tail therefore skipped the whole rest of
+                    // the iteration for that driver — base-rule check included — so a
+                    // rule shape { "group": { "isRequired": true }, "_case_group": {…} }
+                    // never adjudicated `group` on the bind pass, the live-check
+                    // global pass OR the submit pass: the form never gated and an
+                    // empty submit went out unvalidated (the #B221 silent-submit
+                    // class, resurfacing for the self-driving shape — downstream of
+                    // #B221's collection fix, which already admits the group as '').
+                    // The driver's `allFields` entry is restored around the call:
+                    // checkFieldAgainstRules ends every applied rule with
+                    // `delete fields[field]` on the object it is handed, and
+                    // `allFields[caseName]` is the case VALUE the scan block re-reads
+                    // on every later field iteration — a deleted entry re-seeds from
+                    // `$allFields[name].value`, which for a radio group is the FIRST
+                    // member's value regardless of `.checked` (#B230, pre-existing).
+                    // The direct-case block below stays skipped for the driver, so
+                    // WHICH conditions apply is unchanged (measured: that block is
+                    // never entered for a self-driving case, pre-fix or post-fix).
+                    // was:
+                    // if (isInCase || caseName == field) continue;
+                    if ( caseName == field ) {
+                        if ( typeof(rules[field]) != 'undefined' ) {
+                            caseValueBackup = allFields[field];
+                            checkFieldAgainstRules(field, rules, allFields);
+                            if (
+                                typeof(allFields[field]) == 'undefined'
+                                && typeof(caseValueBackup) != 'undefined'
+                            ) {
+                                allFields[field] = caseValueBackup;
+                            }
+                        }
+                        continue;
+                    }
 
+                    // #B230 — a `_case_` driver's entry in `allFields` IS the case
+                    // VALUE every later reader consumes: the scan block above
+                    // re-reads it on every subsequent field iteration (a missing
+                    // entry re-seeds from `$allFields[name].value` — a radio
+                    // group's FIRST member regardless of `.checked`), and the
+                    // direct-case block below reads it in THIS iteration. Site
+                    // 3/3's adjudication deletes it (checkFieldAgainstRules ends
+                    // every applied rule with `delete fields[field]` on the
+                    // object it is handed), so a non-last driver's conditions
+                    // matched a value the user never picked on later scans and
+                    // matched nothing (`undefined`) in its own direct-case pass.
+                    // Back the entry up and restore it after the check — gated
+                    // on the field driving a `_case_` in the live `rules` OR in
+                    // the pass-entry clone `allRules`: inside a direct-case
+                    // recursion `rules` is the condition's own rule set (no
+                    // `_case_` keys), so `hasCase` alone is blind there
+                    // (measured — the union is load-bearing). Non-driver fields
+                    // keep the delete untouched: the pull-in gate, the
+                    // direct-case exclude injection and the async-`query`
+                    // re-validation input all read those absences today.
+                    baseValueBackup = allFields[field];
                     // check each field against rule only if rule exists 3/3
                     if ( typeof(rules[field]) != 'undefined' ) {
                         //checkFieldAgainstRules(field, rules, fields);
                         checkFieldAgainstRules(field, rules, allFields);
                     }
+                    // #B230 restore — see the block comment above
+                    if (
+                        ( hasCase || typeof(allRules['_case_' + field]) != 'undefined' )
+                        && typeof(baseValueBackup) != 'undefined'
+                        && typeof(allFields[field]) == 'undefined'
+                    ) {
+                        allFields[field] = baseValueBackup;
+                    }
 
                     if (hasCase) {
                         ++i; // add sub level
@@ -19812,6 +20371,13 @@ define('gina/popin', [ 'require', 'lib/domain', 'lib/merge', 'utils/events' ], f
          *                                 return true (handled — caller must NOT also load).
          *   - never warmed (undefined) -> return false so the caller loads itself.
          *
+         * Dev toolbar (#B225): both consume branches mirror the cold-click
+         * loaded path's dev gate — GINA_ENV_IS_DEV sets the toolbar overlay
+         * from the body right before the dispatch — so a warmed open surfaces
+         * its rendered data exactly like a cold one. The set lives here and
+         * NOT in handleLoadedBody: the cold path routes through the dispatcher
+         * too, so a set there would double-fire the overlay.
+         *
          * @inner
          * @param {string} url - the resolved popin URL.
          * @param {object} $popin - the registered popin.
@@ -19843,6 +20409,7 @@ define('gina/popin', [ 'require', 'lib/domain', 'lib/merge', 'utils/events' ], f
                         // clear the (repopulated) slot: the completion writes the
                         // cache back even after this adoption consumed the body.
                         $popin._contentUrl = url;
+                        if (GINA_ENV_IS_DEV) { updateToolbar(body); }
                         handleLoadedBody(body, $popin, ensurePopinDialog($popin));
                     }
                 });
@@ -19855,6 +20422,7 @@ define('gina/popin', [ 'require', 'lib/domain', 'lib/merge', 'utils/events' ], f
             // the NEXT open render this open's generation).
             $popin._contentUrl = url;
             var $el = ensurePopinDialog($popin);
+            if (GINA_ENV_IS_DEV) { updateToolbar(body); }
             handleLoadedBody(body, $popin, $el);
             return true;
         }
@@ -22545,6 +23113,783 @@ if ( ( typeof(module) !== 'undefined' ) && module.exports ) {
     // Publish as AMD module
     define('gina/storage', ['helpers/dateFormat', 'helpers/prototypes'],function() { return StoragePlugin })
 };
+define('gina/nav', [ 'require', 'lib/merge', 'lib/uuid', 'utils/events' ], function (require) {
+
+    var merge   = require('lib/merge');
+    var uuid    = require('lib/uuid');
+
+    require('utils/events'); // events
+
+    /**
+     * Gina Navigation Handler (#SPA1 — Tier 1)
+     *
+     * Turns link clicks into fragment swaps on routes that opted into content
+     * negotiation: the matched route must declare `negotiate: true` in
+     * routing.json, and the page must carry a `data-gina-nav` swap region.
+     *
+     * Activation is OPT-IN per page/project: the first element carrying
+     * `data-gina-nav` (with any value but `"false"` — that spelling is the
+     * per-link opt-out) is BOTH the opt-in signal and the region whose content
+     * each fetched fragment replaces. Without the marker the handler stays
+     * inert, so upgrading the framework never changes navigation behaviour on
+     * existing pages.
+     *
+     * What a navigation does:
+     *  1. a delegated document-level click listener resolves the anchor and
+     *     defers to the link plugin (`data-gina-link*`) and to dialog/popin
+     *     triggers (`data-gina-dialog*` / `data-gina-popin-*`), skips modified
+     *     and non-left clicks, `target`/`download` links, cross-origin URLs,
+     *     in-page hash moves and `data-gina-nav="false"` links;
+     *  2. the URL is matched client-side against the served routing table
+     *     (`gina.config.routing`) with the same semantics as the server scan —
+     *     first match in table order wins; interception happens only when that
+     *     route declares `negotiate: true` and accepts GET;
+     *  3. the fragment is fetched over a FRESH XMLHttpRequest carrying
+     *     `X-Gina-Navigate: fragment` (the negotiation signal) AND
+     *     `X-Requested-With: XMLHttpRequest` (without it the render path
+     *     re-wraps a layoutless body into a full `<html>` shell);
+     *  4. a genuine negotiated answer — 2xx, HTML, `Vary` advertising
+     *     `X-Gina-Navigate` — replaces the region's content, re-injects the
+     *     fragment's src-bearing scripts the document does not already have
+     *     (inline scripts are NOT executed — same contract as popin content),
+     *     rebinds id-bearing forms through the live validator, closes any open
+     *     popin (a full navigation would have unloaded it), pushes a history
+     *     entry, restores focus/scroll, and fires `success`;
+     *  5. ANY other answer falls back to a full-page navigation: non-2xx,
+     *     timeout, network error, an un-negotiated 2xx (the `Vary` check —
+     *     a client/server matching disagreement degrades to a normal page
+     *     load), or a JSON `{location}` redirect (hard-followed, the
+     *     established XHR convention).
+     *
+     * Browser floor: `history.pushState` + `Element.closest` (feature-guarded).
+     * The ActiveX/attachEvent branches other plugins carry are unreachable
+     * behind that floor, so this module uses plain `XMLHttpRequest` and a raw
+     * `window.addEventListener('popstate', …)` — `utils/events`' addListener
+     * reads `element.getAttribute` at registration, which `window` lacks.
+     *
+     * Usage — declarative (boot shim constructs when the marker exists):
+     *      <main data-gina-nav>…server-rendered page content…</main>
+     *
+     * Usage — programmatic:
+     *      gina.nav.navigate('/section/item-1');
+     *
+     * Events: `ready`, `navigate` (before the fetch), `success` (after a
+     * swap), `error` (before a fallback navigation).
+     *
+     * @param {object} [options]
+     * @param {number} [options.timeout=10000] - fragment fetch budget in ms; a
+     *        timeout falls back to a full-page navigation
+     * */
+    function Nav(options) {
+
+        this.plugin = 'nav';
+
+        var events  = ['init', 'ready', 'navigate', 'success', 'error'];
+        registerEvents(this.plugin, events);
+
+        var self = { // local use only
+            'options' : {
+                // Fragment fetch budget (ms) — on expiry the navigation falls
+                // back to a full page load of the same URL.
+                'timeout': 10000
+            }
+        };
+
+        var instance        = {
+            plugin          : this.plugin,
+            id              : 'gina-nav-' + uuid(),
+            on              : on,
+            eventData       : {},
+
+            target          : document, // by default; the `data-gina-nav` region once activated
+            isReady         : false,
+            initialized     : false
+        };
+
+        // Navigation sequence — a response is applied only when its sequence is
+        // still current, so an aborted/superseded XHR can never swap stale
+        // content (#B175: the module-scope shared-XHR shape is the defect class
+        // this deliberately avoids — every navigation opens a FRESH XHR).
+        var _navSeq             = 0;
+        var _xhr                = null;
+        // Per-rule compiled matchers + the routing table object they were
+        // compiled from. The table is read LAZILY at each navigation: it
+        // arrives from an async fetch and can land after `isFrameworkLoaded`.
+        var _compiled           = null;
+        var _compiledFor        = null;
+        // Scripts present at activation + scripts nav injected across swaps
+        // (the popin `parentScripts` model): a fragment's src-bearing script is
+        // injected once, never re-executed on later swaps.
+        var _parentScripts      = [];
+        var _injectedScripts    = [];
+        // pathname+search last rendered — popstate events that do not change it
+        // are hash-only moves and are left to the browser.
+        var _currentUrl         = null;
+        // Delegated listeners are installed once per instance lifecycle.
+        var _listenersInstalled = false;
+
+
+        /**
+         * Safe decodeURI — mirrors the server's #B30 discipline (safeDecodeURI):
+         * a malformed percent-sequence falls back to the raw input instead of
+         * throwing, so a hand-typed `%` in a URL can never crash the matcher.
+         *
+         * @inner
+         * @private
+         * @param {string} str
+         * @returns {string} decoded string, or `str` unchanged when malformed
+         */
+        var safeDecode = function(str) {
+            try {
+                return decodeURI(str);
+            } catch (decodeErr) {
+                return str;
+            }
+        };
+
+        /**
+         * Compiles one routing requirement value into a RegExp, mirroring the
+         * server's fitsWithRequirements parsing verbatim: a `/body/flags` value
+         * is split with the same greedy `match(/\/(.*)\//)`  extraction (so both
+         * sides accept identical values), a bare string feeds `new RegExp()`
+         * directly. `validator::` values never reach the client (filtered out
+         * of the served map).
+         *
+         * @inner
+         * @private
+         * @param {string} requirement
+         * @returns {object|null} RegExp, or null when malformed — the variant
+         *          then becomes client-unmatchable (fail-open to a normal
+         *          browser navigation, where the server would 500 instead)
+         */
+        var parseRequirement = function(requirement) {
+            try {
+                if ( /^\//.test(requirement) ) {
+                    var body  = requirement.match(/\/(.*)\//).pop();
+                    var flags = requirement.replace('/' + body + '/', '');
+                    return new RegExp(body, flags);
+                }
+                return new RegExp(requirement);
+            } catch (reErr) {
+                return null;
+            }
+        };
+
+        /**
+         * Compiles ONE url variant of a route into an array of segment
+         * matchers, or null when the variant cannot be matched client-side.
+         *
+         * Mirrored server semantics (parseRouting + fitsWithRequirements):
+         * literal segments compare strict-equal; a pure `:key` segment tests
+         * its requirement when one is declared, otherwise it accepts any
+         * NON-EMPTY segment only when the served `param` block declares the
+         * key (fitsWithRequirements returns false otherwise). A mixed
+         * literal+param segment (`page:number`) is matchable server-side but
+         * deliberately UNMATCHABLE here in Tier 1 — no interception, normal
+         * navigation (false-negative-safe).
+         *
+         * @inner
+         * @private
+         * @param {string} url - one variant (already comma-split)
+         * @param {object} route - the served route object
+         * @returns {array|null} segment matchers ({lit} | {key, re}) or null
+         */
+        var compileVariant = function(url, route) {
+            var segments = String(url).split(/\//);
+            var out = [];
+            for (var i = 0, len = segments.length; i < len; ++i) {
+                var seg = segments[i];
+                if ( seg.indexOf(':') < 0 ) {
+                    out.push({ 'lit': seg });
+                    continue;
+                }
+                if ( !/^\:[-_a-zA-Z0-9]+$/.test(seg) ) {
+                    return null;
+                }
+                var key = seg.substring(1);
+                if ( route.requirements && typeof(route.requirements[key]) != 'undefined' ) {
+                    var re = parseRequirement(String(route.requirements[key]));
+                    if (!re) {
+                        return null;
+                    }
+                    out.push({ 'key': key, 're': re });
+                    continue;
+                }
+                if ( route.param && typeof(route.param[key]) != 'undefined' ) {
+                    out.push({ 'key': key, 're': null });
+                    continue;
+                }
+                return null;
+            }
+            return out;
+        };
+
+        /**
+         * Returns the compiled candidate list for the CURRENT routing table,
+         * (re)compiling when the table object changed identity. Candidate
+         * filtering mirrors the server scan: paramless routes are skipped,
+         * foreign-bundle routes are skipped, and — for a GET navigation —
+         * single-method routes survive only as GET or DELETE (the server's
+         * GET→DELETE override keeps such a route as a BLOCKING candidate so
+         * the client can never intercept across it), while multi-method routes
+         * always reach URL comparison.
+         *
+         * @inner
+         * @private
+         * @returns {array|null} compiled candidates, or null when the routing
+         *          table has not been fetched yet
+         */
+        var getCompiled = function() {
+            var config  = ( window.gina && window.gina.config ) ? window.gina.config : null;
+            var routing = ( config && config.routing && typeof(config.routing) == 'object' ) ? config.routing : null;
+            if ( !routing ) {
+                return null;
+            }
+            if ( _compiledFor === routing && _compiled ) {
+                return _compiled;
+            }
+            var bundle   = config.bundle;
+            var compiled = [];
+            for (var rule in routing) {
+                var route = routing[rule];
+                if ( !route || typeof(route) != 'object' ) continue;
+                if ( typeof(route.param) == 'undefined' ) continue;
+                if ( route.bundle != bundle ) continue;
+                var method      = String(route.method || '');
+                var hasComma    = /\,/.test(method);
+                var singleClean = method.replace(/\s+/g, '');
+                if ( !hasComma && !/^(get|delete)$/i.test(singleClean) ) continue;
+                var isGet = hasComma
+                    ? /(^|,)\s*get\s*(,|$)/i.test(method)
+                    : /^get$/i.test(singleClean);
+                var urls     = String(route.url).split(/\,/g);
+                var variants = [];
+                for (var u = 0, uLen = urls.length; u < uLen; ++u) {
+                    variants.push( compileVariant(urls[u], route) );
+                }
+                compiled.push({
+                    'rule'      : rule,
+                    'route'     : route,
+                    'isGet'     : isGet,
+                    'variants'  : variants,
+                    'rawUrl'    : String(route.url)
+                });
+            }
+            _compiled    = compiled;
+            _compiledFor = routing;
+            return compiled;
+        };
+
+        /**
+         * matchUrl
+         *
+         * Client-side URL→route matcher over the served routing table. First
+         * match in table order wins — the server's own scan order, so both
+         * sides resolve the same rule for the same pathname. The pathname is
+         * matched decoded (safeDecode) with a raw exact-equality short-circuit
+         * per route, both mirroring the server.
+         *
+         * A null return, or a match without `negotiate: true`, means the click
+         * is left to the browser — the matcher is an interception FILTER, and
+         * every uncertainty degrades to a normal navigation.
+         *
+         * @param {string} pathname - location pathname (no query string)
+         * @returns {object|null} { rule, route, isGet } or null
+         * */
+        var matchUrl = function(pathname) {
+            var compiled = getCompiled();
+            if ( !compiled ) {
+                return null;
+            }
+            var decoded = safeDecode(pathname);
+            var segs    = decoded.split(/\//);
+            for (var i = 0, len = compiled.length; i < len; ++i) {
+                var c = compiled[i];
+                if ( pathname === c.rawUrl || decoded === c.rawUrl ) {
+                    return { 'rule': c.rule, 'route': c.route, 'isGet': c.isGet };
+                }
+                for (var v = 0, vLen = c.variants.length; v < vLen; ++v) {
+                    var m = c.variants[v];
+                    if ( !m || m.length !== segs.length ) continue;
+                    var ok = true;
+                    for (var s = 0, sLen = m.length; s < sLen; ++s) {
+                        if ( typeof(m[s].lit) != 'undefined' ) {
+                            if ( m[s].lit !== segs[s] ) { ok = false; break; }
+                            continue;
+                        }
+                        if ( !segs[s] ) { ok = false; break; }
+                        if ( m[s].re && !m[s].re.test(segs[s]) ) { ok = false; break; }
+                    }
+                    if (ok) {
+                        return { 'rule': c.rule, 'route': c.route, 'isGet': c.isGet };
+                    }
+                }
+            }
+            return null;
+        };
+
+        /**
+         * Snapshots the src of every script present in the document at
+         * activation — the popin `parentScripts` model. Scripts already loaded
+         * with the page are never re-injected from a fragment.
+         *
+         * @inner
+         * @private
+         */
+        var snapshotParentScripts = function() {
+            var scripts = document.getElementsByTagName('script');
+            for (var i = 0, len = scripts.length; i < len; ++i) {
+                if ( scripts[i].src ) {
+                    _parentScripts.push(scripts[i].src);
+                }
+            }
+        };
+
+        /**
+         * Re-injects the fragment's src-bearing scripts the document does not
+         * already have (mirrors popinOpen's external-resource loading). Inline
+         * scripts are NOT executed — innerHTML semantics, the same contract
+         * popin content has always had. Injected scripts persist across later
+         * swaps (a page never "closes"); the registry keeps them single-shot.
+         *
+         * @inner
+         * @private
+         * @param {object} $target - the swapped region
+         */
+        var injectFragmentScripts = function($target) {
+            var scripts = $target.getElementsByTagName('script');
+            for (var i = 0, len = scripts.length; i < len; ++i) {
+                var src = scripts[i].src; // resolved absolute URL
+                if ( !src ) continue;
+                if ( _parentScripts.indexOf(src) > -1 || _injectedScripts.indexOf(src) > -1 ) continue;
+                var s = document.createElement('script');
+                s.src = src;
+                document.head.appendChild(s);
+                _injectedScripts.push(src);
+            }
+        };
+
+        /**
+         * Rebinds id-bearing forms of the swapped region through the live
+         * validator (`gina.validator.validateFormById` — the popinBind model).
+         * Id-less forms are skipped: validation rules are keyed by form id, so
+         * no rule can target them. A missing/ruleless validator is a no-op.
+         *
+         * @inner
+         * @private
+         * @param {object} $target - the swapped region
+         */
+        var rebindValidator = function($target) {
+            try {
+                if ( !gina.hasValidator || !gina.validator || typeof(gina.validator.validateFormById) != 'function' ) {
+                    return;
+                }
+                var $forms = $target.getElementsByTagName('form');
+                for (var i = 0, len = $forms.length; i < len; ++i) {
+                    var _id = $forms[i].getAttribute('id');
+                    if ( !_id ) continue;
+                    try {
+                        gina.validator.validateFormById(_id);
+                    } catch (bindErr) {
+                        console.warn('[gina][nav] validator rebind skipped for `'+ _id +'`: '+ (bindErr.message || bindErr));
+                    }
+                }
+            } catch (validatorErr) {}
+        };
+
+        /**
+         * Closes the active popin when one is open: a full-page navigation
+         * would have unloaded it, and after a fragment swap it would sit over
+         * content it no longer belongs to.
+         *
+         * @inner
+         * @private
+         */
+        var closeActivePopin = function() {
+            try {
+                if ( gina.hasPopinHandler && gina.popin && typeof(gina.popin.getActivePopin) == 'function' ) {
+                    var $active = gina.popin.getActivePopin();
+                    if ( $active && $active.isOpen && typeof(gina.popin.close) == 'function' ) {
+                        gina.popin.close($active.name);
+                    }
+                }
+            } catch (popinCloseErr) {}
+        };
+
+        /**
+         * Stores the current scroll position onto the CURRENT history entry
+         * (replaceState) so a later Back restores it. The entry keeps its
+         * `ginaNav` stamp.
+         *
+         * @inner
+         * @private
+         */
+        var saveScrollOnCurrentEntry = function() {
+            try {
+                var st = window.history.state || {};
+                st.ginaNav = true;
+                st.scroll  = [ window.pageXOffset || 0, window.pageYOffset || 0 ];
+                window.history.replaceState(st, '', window.location.href);
+            } catch (histErr) {}
+        };
+
+        /**
+         * Applies a fetched fragment: swaps the region content, re-injects
+         * missing src scripts, applies the optional `[data-gina-nav-title]`
+         * document title, pushes/updates history, restores scroll and focus,
+         * closes any open popin, rebinds validator forms and fires `success`.
+         *
+         * @inner
+         * @private
+         * @param {string} html - the layoutless fragment body
+         * @param {string} url - the navigated URL (pathname + search [+ hash])
+         * @param {boolean} isPopState - popstate re-render (no history push)
+         * @param {object} [navOptions] - { scroll: [x, y] } on popstate
+         */
+        var applyFragment = function(html, url, isPopState, navOptions) {
+            var $target = instance.target;
+            $target.innerHTML = ( typeof(html) == 'string' ) ? html.trim() : '';
+
+            injectFragmentScripts($target);
+
+            // Optional per-page document title: the first element of the
+            // fragment carrying `data-gina-nav-title` (the fragment is
+            // layoutless, so it cannot carry a <title> of its own).
+            var $titled = ( typeof($target.querySelector) == 'function' ) ? $target.querySelector('[data-gina-nav-title]') : null;
+            if ( $titled ) {
+                var _title = $titled.getAttribute('data-gina-nav-title');
+                if (_title) {
+                    document.title = _title;
+                }
+            }
+
+            if ( !isPopState ) {
+                // Store the leaving entry's scroll, then push the new one.
+                saveScrollOnCurrentEntry();
+                try {
+                    window.history.pushState({ 'ginaNav': true }, '', url);
+                } catch (pushErr) {}
+            }
+            _currentUrl = window.location.pathname + window.location.search;
+
+            // Focus first (preventScroll where supported), then the explicit
+            // scroll decision wins: restored position on popstate, `#hash`
+            // target or top on a forward navigation.
+            try {
+                if ( !$target.getAttribute('tabindex') ) {
+                    $target.setAttribute('tabindex', '-1');
+                }
+                $target.focus({ 'preventScroll': true });
+            } catch (focusErr) {
+                try { $target.focus(); } catch (focusRetryErr) {}
+            }
+            var _scroll = ( isPopState && navOptions && navOptions.scroll ) ? navOptions.scroll : null;
+            if ( _scroll ) {
+                window.scrollTo(_scroll[0] || 0, _scroll[1] || 0);
+            } else {
+                var _hash   = ( url.indexOf('#') > -1 ) ? url.substring(url.indexOf('#') + 1) : null;
+                var $anchor = ( _hash ) ? document.getElementById(_hash) : null;
+                if ( $anchor && typeof($anchor.scrollIntoView) == 'function' ) {
+                    $anchor.scrollIntoView();
+                } else {
+                    window.scrollTo(0, 0);
+                }
+            }
+
+            closeActivePopin();
+            rebindValidator($target);
+
+            instance.eventData.success = { 'url': url, 'target': $target, 'isPopState': isPopState };
+            triggerEvent(gina, instance.target, 'success.' + instance.id, instance.eventData.success);
+        };
+
+        /**
+         * Falls back to a full-page navigation, firing `error` first so
+         * consumers can observe/log. On a popstate the address bar already
+         * shows the target, so the fallback is a reload.
+         *
+         * @inner
+         * @private
+         * @param {string} url
+         * @param {boolean} isPopState
+         * @param {object} errorData - { status, error }
+         */
+        var fallback = function(url, isPopState, errorData) {
+            instance.eventData.error = errorData || {};
+            triggerEvent(gina, instance.target, 'error.' + instance.id, instance.eventData.error);
+            if ( isPopState ) {
+                window.location.reload();
+            } else {
+                window.location.href = url;
+            }
+        };
+
+        /**
+         * Handles a completed fragment XHR. Discrimination is protocol-level:
+         * a genuine negotiated answer always advertises `Vary: X-Gina-Navigate`
+         * (the #SPA1 controller contract) — a 2xx WITHOUT it means the server
+         * dispatched a route the client matched differently, and the honest
+         * recovery is a normal page load. A JSON `{location}` body is the
+         * established XHR redirect protocol and is hard-followed.
+         *
+         * @inner
+         * @private
+         * @param {object} xhr
+         * @param {string} url
+         * @param {boolean} isPopState
+         * @param {object} [navOptions]
+         */
+        var onNavResponse = function(xhr, url, isPopState, navOptions) {
+            var status = xhr.status;
+            if ( /^2/.test(String(status)) ) {
+                var contentType = xhr.getResponseHeader('Content-Type') || '';
+                if ( /application\/json/.test(contentType) ) {
+                    var result = null;
+                    try {
+                        result = JSON.parse(xhr.responseText);
+                    } catch (parseErr) {}
+                    if ( result && typeof(result.location) != 'undefined' && result.location ) {
+                        window.location.href = result.location;
+                        return;
+                    }
+                    return fallback(url, isPopState, { 'status': status, 'error': 'unexpected JSON answer to a fragment request' });
+                }
+                var vary = xhr.getResponseHeader('Vary') || '';
+                if ( !/x-gina-navigate/i.test(vary) ) {
+                    return fallback(url, isPopState, { 'status': status, 'error': 'response is not negotiated (no `Vary: X-Gina-Navigate`)' });
+                }
+                return applyFragment(xhr.responseText, url, isPopState, navOptions);
+            }
+            fallback(url, isPopState, { 'status': status || 0, 'error': xhr.statusText || 'network error or timeout' });
+        };
+
+        /**
+         * navigate
+         *
+         * Fetches the URL's negotiated fragment and swaps it into the
+         * `data-gina-nav` region. Every uncertainty (non-2xx, timeout, network
+         * error, un-negotiated answer, JSON redirect) degrades to a full-page
+         * navigation of the same URL, so a programmatic call on a
+         * non-negotiable route behaves like `window.location.href = url`.
+         *
+         * A FRESH XMLHttpRequest is opened per navigation and any in-flight
+         * one is aborted; its handlers observe a stale sequence and drop out,
+         * so two rapid navigations can never interleave content.
+         *
+         * @param {string} url - same-origin URL (pathname + search [+ hash])
+         * @param {object} [navOptions]
+         * @param {boolean} [navOptions.isPopState=false] - popstate re-render
+         * @param {array} [navOptions.scroll] - [x, y] to restore on popstate
+         * */
+        var navigate = function(url, navOptions) {
+            if ( !url || typeof(url) != 'string' ) {
+                return;
+            }
+            if ( !instance.isReady || instance.target === document ) {
+                // Not activated (no marker) — behave like a plain navigation.
+                window.location.href = url;
+                return;
+            }
+            var isPopState = ( navOptions && navOptions.isPopState ) ? true : false;
+            var seq = ++_navSeq;
+            if ( _xhr && _xhr.readyState !== 4 ) {
+                try {
+                    _xhr.abort();
+                } catch (abortErr) {}
+            }
+
+            instance.eventData.navigate = { 'url': url, 'isPopState': isPopState };
+            triggerEvent(gina, instance.target, 'navigate.' + instance.id, instance.eventData.navigate);
+
+            // Fresh XHR per navigation — prevents concurrent navigations from
+            // sharing state (#B175).
+            var xhr = new XMLHttpRequest();
+            _xhr = xhr;
+            xhr.open('GET', url);
+            // Both headers, deliberately:
+            //  - `X-Gina-Navigate` is the #SPA1 negotiation signal (the
+            //    controller resolves the layoutless shape and advertises Vary
+            //    on negotiable routes);
+            //  - `X-Requested-With` keeps the request on the established XHR
+            //    paths — without it the render path re-wraps the layoutless
+            //    body into a full `<html>` shell (render-swig iframe case),
+            //    and redirects/errors leave the proven JSON protocol.
+            xhr.setRequestHeader('X-Gina-Navigate', 'fragment');
+            xhr.setRequestHeader('X-Requested-With', 'XMLHttpRequest');
+            xhr.timeout = self.options.timeout;
+            xhr.onreadystatechange = function() {
+                if ( xhr.readyState !== 4 ) {
+                    return;
+                }
+                if ( seq !== _navSeq ) {
+                    return; // superseded — a newer navigation owns the page
+                }
+                // status 0 with a CURRENT sequence is a network failure or the
+                // timeout's internal abort (a supersede-abort is always stale
+                // by construction: the sequence increments before the abort).
+                onNavResponse(xhr, url, isPopState, navOptions);
+            };
+            xhr.send();
+        };
+
+        /**
+         * The delegated document-level click handler — the popin
+         * bindDelegatedOpen model, so links inside swapped fragments are
+         * covered with no rebinding. Every skip rule below defers to an
+         * existing owner or to the browser; interception happens only for a
+         * same-origin left-click resolving to a first-match route that
+         * declares `negotiate: true` and accepts GET.
+         *
+         * @inner
+         * @private
+         * @param {object} event - the click event
+         */
+        var onDocumentClick = function(event) {
+            if ( event.defaultPrevented ) return;
+            if ( typeof(event.button) == 'number' && event.button !== 0 ) return;
+            if ( event.ctrlKey || event.metaKey || event.shiftKey || event.altKey ) return;
+            var $a = ( event.target && typeof(event.target.closest) == 'function' )
+                ? event.target.closest('a[href]')
+                : null;
+            if ( !$a ) return;
+            // Ownership deference — the link plugin and the dialog/popin
+            // triggers keep their own handlers.
+            if ( $a.getAttribute('data-gina-link') != null || $a.getAttribute('data-gina-link-url') != null ) return;
+            if ( $a.getAttribute('data-gina-dialog') != null || $a.getAttribute('data-gina-dialog-src') != null ) return;
+            if ( $a.getAttribute('data-gina-popin-name') != null || $a.getAttribute('data-gina-popin-url') != null ) return;
+            // Per-link opt-out.
+            if ( /^false$/i.test($a.getAttribute('data-gina-nav')) ) return;
+            var targetAttr = $a.getAttribute('target');
+            if ( targetAttr && !/^_self$/i.test(targetAttr) ) return;
+            if ( $a.getAttribute('download') != null ) return;
+            var href = $a.getAttribute('href');
+            if ( !href || /^#/.test(href) ) return;
+            // Same-origin only — the anchor element is the URL parser.
+            if ( $a.protocol !== window.location.protocol || $a.host !== window.location.host ) return;
+            // In-page hash move on the same document — the browser handles it.
+            if ( $a.pathname === window.location.pathname && $a.search === window.location.search && $a.hash ) return;
+
+            var matched = matchUrl($a.pathname);
+            if ( !matched || matched.route.negotiate !== true || !matched.isGet ) return;
+
+            cancelEvent(event);
+            navigate($a.pathname + $a.search + $a.hash);
+        };
+
+        /**
+         * Installs the delegated click listener and the popstate handler —
+         * once per instance lifecycle.
+         *
+         * @inner
+         * @private
+         */
+        var installListeners = function() {
+            if ( _listenersInstalled ) {
+                return;
+            }
+            _listenersInstalled = true;
+
+            addListener(gina, document, 'click', function(event) {
+                try {
+                    onDocumentClick(event);
+                } catch (navClickErr) {
+                    // An interception error must never eat the click — the
+                    // browser keeps handling it.
+                    console.warn('[gina][nav] click interception skipped: '+ (navClickErr.message || navClickErr));
+                }
+            });
+
+            // Raw addEventListener: utils/events' addListener reads
+            // `element.getAttribute` at registration and `window` has neither
+            // `id` nor `getAttribute`.
+            window.addEventListener('popstate', function(event) {
+                try {
+                    var _url = window.location.pathname + window.location.search;
+                    if ( _url === _currentUrl ) {
+                        return; // hash-only move on the same document
+                    }
+                    var st = event.state;
+                    if ( st && st.ginaNav ) {
+                        navigate(_url + window.location.hash, { 'isPopState': true, 'scroll': st.scroll || null });
+                        return;
+                    }
+                    // A history entry nav did not stamp (external history
+                    // manipulation) — the only honest recovery is a full load
+                    // of what the address bar shows.
+                    window.location.reload();
+                } catch (popErr) {
+                    window.location.reload();
+                }
+            });
+        };
+
+        var init = function(options) {
+
+            setupInstanceProto();
+            instance.on('init', function(event) {
+
+                self.options = merge(options || {}, self.options);
+
+                // Swap-target + page opt-in in one marker. `"false"` is the
+                // per-LINK opt-out spelling and must not opt a page in.
+                var $marker = null;
+                try {
+                    $marker = document.querySelector('[data-gina-nav]:not([data-gina-nav="false"])');
+                } catch (qsErr) {}
+
+                if ( !$marker ) {
+                    // Explicit construction on a page without the marker: warn
+                    // and stay inert — no listeners, no publish, no behaviour
+                    // change (the boot shim never constructs in this state).
+                    console.warn('[gina][nav] no [data-gina-nav] region found — navigation interception stays off');
+                    instance.isReady = true;
+                    triggerEvent(gina, instance.target, 'ready.' + instance.id, instance);
+                    return;
+                }
+
+                instance.target = $marker;
+                _currentUrl     = window.location.pathname + window.location.search;
+                snapshotParentScripts();
+                try {
+                    if ( window.history && 'scrollRestoration' in window.history ) {
+                        window.history.scrollRestoration = 'manual';
+                    }
+                    // Stamp the entry page so a Back onto it is recognised as
+                    // nav-owned and re-rendered as a fragment.
+                    var _st = window.history.state || {};
+                    _st.ginaNav = true;
+                    window.history.replaceState(_st, '', window.location.href);
+                } catch (histErr) {}
+
+                installListeners();
+
+                instance.isReady = true;
+                gina.hasNavHandler = true;
+                // #B90 — publish ONCE: `gina.nav` IS the first activated
+                // instance (a LIVE object); later constructions have nothing
+                // to publish, and re-merging would freeze accessors/state.
+                if ( typeof(gina.nav) == 'undefined' || !gina.nav ) {
+                    gina.nav = instance;
+                }
+                triggerEvent(gina, instance.target, 'ready.' + instance.id, instance);
+            });
+
+            instance.initialized = true;
+
+            return instance;
+        };
+
+        var setupInstanceProto = function() {
+            instance.navigate = navigate;
+            instance.matchUrl = matchUrl;
+        };
+
+        return init(options);
+    }
+
+    return Nav;
+});
+
 /**
  * Object.assign
  * Ref.: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
@@ -24581,6 +25926,7 @@ require([
     "gina/validator",
     "gina/popin",
     "gina/storage",
+    "gina/nav",
 
     // lib
     "utils/dom",
@@ -24672,6 +26018,49 @@ require([
         }
     };
     bootValidator();
+
+    // Boot the navigation handler (#SPA1 — Tier 1) so the declarative
+    // `data-gina-nav` API is active WITHOUT bundle code calling
+    // `new gina.nav()` — the sibling of the popin/validator boots above,
+    // with one deliberate difference: navigation is OPT-IN PER PROJECT
+    // (SPA design decision 3 — upgrading gina must not change navigation
+    // behaviour on existing pages). The shim therefore constructs ONLY when
+    // the page carries a `data-gina-nav` swap-region marker; the `"false"`
+    // value is the per-LINK opt-out spelling and does not opt a page in.
+    // Pages without the marker stay byte-identical: no listener, no
+    // `gina.nav` publish, no history/scroll changes. Gated on
+    // `isFrameworkLoaded` like its siblings — by then the DOM is ready
+    // (onGinaLoaded runs from the DOMContentLoaded-driven scheduler), so the
+    // marker query observes the rendered page.
+    var _navBootTries = 0;
+    var bootNav = function () {
+        try {
+            if ( !window['gina'] || !window['gina']['isFrameworkLoaded'] ) {
+                if ( _navBootTries++ < 100 ) {
+                    (window['setTimeout'] || function (fn) { fn(); })(bootNav, 50);
+                }
+                return;
+            }
+            if ( window['gina']['hasNavHandler'] ) {
+                return;
+            }
+            if (
+                typeof(document.querySelector) != 'function'
+                || !document.querySelector('[data-gina-nav]:not([data-gina-nav="false"])')
+            ) {
+                return;
+            }
+            var Nav = require('gina/nav');
+            if ( typeof(Nav) == 'function' ) {
+                new Nav({}).on('ready', function () {});
+            }
+        } catch (navBootErr) {
+            if ( typeof(console) != 'undefined' && console.error ) {
+                console.error('[gina] nav boot failed', navBootErr.stack || navBootErr);
+            }
+        }
+    };
+    bootNav();
 });
 
 function getDependencies(gina, cb) {
@@ -24689,6 +26078,16 @@ function getDependencies(gina, cb) {
 
         try {
             response    = await fetch(filenameOrUrl);
+            // #B213 — `fetch` resolves on HTTP error statuses (it only rejects on
+            // network failure), and the framework's own 404 page is valid JSON —
+            // so without this guard a 404/5xx body (an engine missing the asset,
+            // a restart window) was silently installed AS the routing table and
+            // every client-side getRoute/toUrl failed from there. Throwing here
+            // routes the failure into the existing catch, which dispatches the
+            // deps.loaded error path instead of poisoning gina.config.
+            if ( !response.ok ) {
+                throw new Error('[ROUTING] HTTP '+ response.status +' fetching '+ filenameOrUrl);
+            }
             result      = await response.text();
             if ( typeof(gina) == 'undefined' ) {
                 gina = {}