@yuneta/gobj-ui 3.0.0 → 5.0.0

package/src/c_yui_shell.js

@@ -42,6 +42,7 @@ import {
     gobj_read_attr, gobj_read_pointer_attr, gobj_write_attr,
     createElement2, empty_string, is_object, is_array, is_string,
     refresh_language,
+    is_gobj,
 } from "@yuneta/gobj-js";
 
 import {
@@ -59,7 +60,8 @@ import {
     validate_toolbar_item,
 } from "./shell_toolbar_helpers.js";
 
-import { resolve_route } from "./route_resolver.js";
+import { resolve_route, normalize_route } from "./route_resolver.js";
+import { build_nav_map } from "./route_map_model.js";
 import {
     section_index_target,
     secondary_nav_renders,
@@ -102,11 +104,73 @@ SDATA(data_type_t.DTP_BOOLEAN,  "use_hash",       0,  true,  "Bind navigation to
 SDATA(data_type_t.DTP_POINTER,  "mount_element",  0,  null,  "HTMLElement to mount shell into (default: document.body)"),
 
 SDATA(data_type_t.DTP_POINTER,  "$container",     0,  null,  "Root HTMLElement of the shell"),
-SDATA(data_type_t.DTP_POINTER,  "priv",           0,  null,  "Private runtime state (zones/layers/stages/navs)"),
 SDATA_END()
 ];
 
-let PRIVATE_DATA = {};
+let PRIVATE_DATA = {
+    zones:           {},
+    layers:          {},
+    stages:          {},
+    navs:            [],
+    item_index:      {},
+    /*  Sub-route contributor registry (ROUTING.md): a mounted view
+     *  declares the deep, view-owned children of its base route
+     *  (topics, /info, /schema, focus topics — subpaths that are NOT
+     *  declared routes) so the site map can show the full tree. Keyed
+     *  by base route → ordered [{route,label,icon,children?}]. */
+    sub_routes:      {},
+    /*  Event → handler GClass(es) registry (ROUTING.md): a gclass that
+     *  handles a toolbar/account action event self-declares so the site
+     *  map can show WHERE the action is implemented. Keyed by event name
+     *  → array of gclass names. */
+    event_handlers:  {},
+    hash_handler:    null,
+    keydown_handler: null,
+    /*  Escape priority chain: array of { layer, handler }.  Each
+     *  interactive overlay (drawer today, modal/popup tomorrow)
+     *  pushes its close handler when it opens and pops it when
+     *  it closes.  Escape calls the top handler only — LIFO. */
+    escape_stack:    [],
+    /*  Overlay history integration (Back button ↔ modals/windows).
+     *  Each history-participating overlay (modal, floating window)
+     *  pushes a { id, close } record here when it opens, plus a
+     *  synthetic browser-history entry (pushState).  The browser Back
+     *  button then closes the TOP overlay instead of navigating; and
+     *  an overlay dismissed by any other path (X, Escape, backdrop,
+     *  code) retires its history entry via history.back().  Gated on
+     *  `use_hash` — see push_overlay_history / overlay_dismissed. */
+    overlay_stack:   [],
+    overlay_seq:     0,
+    /*  Count of history.back() calls WE issued to retire a dismissed
+     *  overlay; the popstate they trigger is expected and ignored. */
+    expected_pops:   0,
+    popstate_handler: null,
+    /*  Avatar item support — every toolbar item with type:"avatar"
+     *  registers its <span> here so refresh_avatars() can repaint
+     *  the initials when the host (wattyzer, hidraulia, …) calls
+     *  yui_shell_set_avatar_provider() / yui_shell_refresh_avatars().
+     *  The provider is a () => string callback owned by the host. */
+    avatar_provider: null,
+    avatar_nodes:    [],
+    /*  Optional i18n translator (t-function) the host registers via
+     *  yui_shell_set_translator().  The host translates the static
+     *  shell tree by calling refresh_language($container, t) once,
+     *  but LAZILY-built DOM (the toolbar dropdown panel) is mounted
+     *  on the popup layer, OUTSIDE $container, AFTER that call — so
+     *  it would never be translated.  When a translator is set the
+     *  shell re-applies it to each freshly built panel. */
+    translator:      null,
+    /*  Connection-indicator support — every toolbar item with
+     *  type:"connection" registers its dot <span> here so
+     *  yui_shell_set_connection_state(shell, bool) can repaint the
+     *  backend-connected state.  State is host/event-driven (unlike
+     *  the avatar provider it is a setter, not a pull callback). */
+    conn_nodes:      [],
+    /*  Currently open toolbar dropdown panel, if any.  Tracked here
+     *  so a second click on any trigger (or programmatic close) can
+     *  tear down the previous one through the same code path. */
+    active_dropdown: null
+};
 
 let __gclass__ = null;
 
@@ -133,47 +197,6 @@ function mt_create(gobj)
         gobj_subscribe_event(gobj, null, {}, subscriber);
     }
 
-    /*  Per-instance private state (avoid the gclass-level PRIVATE_DATA). */
-    gobj_write_attr(gobj, "priv", {
-        zones:           {},
-        layers:          {},
-        stages:          {},
-        navs:            [],
-        item_index:      {},
-        hash_handler:    null,
-        keydown_handler: null,
-        /*  Escape priority chain: array of { layer, handler }.  Each
-         *  interactive overlay (drawer today, modal/popup tomorrow)
-         *  pushes its close handler when it opens and pops it when
-         *  it closes.  Escape calls the top handler only — LIFO. */
-        escape_stack:    [],
-        /*  Avatar item support — every toolbar item with type:"avatar"
-         *  registers its <span> here so refresh_avatars() can repaint
-         *  the initials when the host (wattyzer, hidraulia, …) calls
-         *  yui_shell_set_avatar_provider() / yui_shell_refresh_avatars().
-         *  The provider is a () => string callback owned by the host. */
-        avatar_provider: null,
-        avatar_nodes:    [],
-        /*  Optional i18n translator (t-function) the host registers via
-         *  yui_shell_set_translator().  The host translates the static
-         *  shell tree by calling refresh_language($container, t) once,
-         *  but LAZILY-built DOM (the toolbar dropdown panel) is mounted
-         *  on the popup layer, OUTSIDE $container, AFTER that call — so
-         *  it would never be translated.  When a translator is set the
-         *  shell re-applies it to each freshly built panel. */
-        translator:      null,
-        /*  Connection-indicator support — every toolbar item with
-         *  type:"connection" registers its dot <span> here so
-         *  yui_shell_set_connection_state(shell, bool) can repaint the
-         *  backend-connected state.  State is host/event-driven (unlike
-         *  the avatar provider it is a setter, not a pull callback). */
-        conn_nodes:      [],
-        /*  Currently open toolbar dropdown panel, if any.  Tracked here
-         *  so a second click on any trigger (or programmatic close) can
-         *  tear down the previous one through the same code path. */
-        active_dropdown: null
-    });
-
     __last_shell__ = gobj;
 
     build_ui(gobj);
@@ -185,7 +208,7 @@ function mt_create(gobj)
 function mt_start(gobj)
 {
     let config = gobj_read_attr(gobj, "config") || {};
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
 
     /*  Validate the declarative config before anything reads it. This is a
      *  system boundary (app-supplied JSON); validation makes shape errors
@@ -217,6 +240,69 @@ function mt_start(gobj)
             }
         };
         window.addEventListener("hashchange", priv.hash_handler);
+
+        /*  Back button ↔ overlays.  A synthetic overlay history entry
+         *  keeps the same hash, so Back over it fires popstate WITHOUT a
+         *  hashchange: close the top overlay and consume the event.  A
+         *  real route Back changes the hash and is handled by hash_handler
+         *  above. */
+        priv.popstate_handler = (ev) => {
+            let p = gobj.priv;
+            if(!p) {
+                return;
+            }
+            if(p.expected_pops > 0) {
+                /*  A history.back() we issued to retire a dismissed
+                 *  overlay — the teardown already happened. */
+                p.expected_pops--;
+                return;
+            }
+            if(p.overlay_stack.length === 0) {
+                return;
+            }
+            let top = p.overlay_stack[p.overlay_stack.length - 1];
+            /*  Did this traversal step OFF the top overlay's marker?
+             *  That is the only landing that closes it, and the marker's
+             *  OWN hash is what says so: pushState() with no URL keeps
+             *  the current one, so stepping off a marker always lands on
+             *  the marker's hash.  A landing on any OTHER hash is a route
+             *  traversal (fragment pushes fire popstate too) and belongs
+             *  to the hashchange handler — navigate_to() closes the
+             *  transient overlays when the RESTING route changes, so a
+             *  subpath move keeps them open.
+             *
+             *  Compare against the MARKER's hash, never against the
+             *  resting route's: an action route (ROUTING.md §7.1) is
+             *  transient — `current_route` stays on the underlying
+             *  resting view while the URL sits on the action route — so
+             *  a `stay` modal's marker legitimately lives on a hash that
+             *  is NOT the resting one, and matching on the resting route
+             *  left Back unable to close it. */
+            if(window.location.hash !== top.hash) {
+                return;
+            }
+            /*  Which entry did it land ON?  Markers ({__yui_overlay__:
+             *  id}) tag synthetic entries; route entries have a null
+             *  state.
+             *    - Landing ON the top overlay's OWN entry (a Back from a
+             *      subpath entry pushed above it, or an odd
+             *      history.go(n)): the overlay is at its home entry —
+             *      keep it open.
+             *    - Any other landing (the route entry below, or a lower
+             *      overlay's marker) closes the top overlay: strict
+             *      LIFO. */
+            let st = ev && ev.state;
+            if(st && st.__yui_overlay__ === top.id) {
+                return;
+            }
+            p.overlay_stack.pop();
+            try {
+                top.close();
+            } catch(e) {
+                log_warning(`C_YUI_SHELL: overlay close on Back failed: ${e}`);
+            }
+        };
+        window.addEventListener("popstate", priv.popstate_handler);
     }
 
     /*  Global Escape: route to the top handler of the escape stack,
@@ -264,7 +350,7 @@ function mt_start(gobj)
  ***************************************************************/
 function mt_stop(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv) {
         return;
     }
@@ -278,6 +364,10 @@ function mt_stop(gobj)
         window.removeEventListener("hashchange", priv.hash_handler);
         priv.hash_handler = null;
     }
+    if(priv.popstate_handler) {
+        window.removeEventListener("popstate", priv.popstate_handler);
+        priv.popstate_handler = null;
+    }
     if(priv.keydown_handler) {
         window.removeEventListener("keydown", priv.keydown_handler);
         priv.keydown_handler = null;
@@ -327,7 +417,6 @@ function mt_destroy(gobj)
         $container.parentNode.removeChild($container);
     }
     gobj_write_attr(gobj, "$container", null);
-    gobj_write_attr(gobj, "priv", null);
 
     if(__last_shell__ === gobj) {
         __last_shell__ = null;
@@ -514,7 +603,7 @@ function check_route_unique(route_owner, item, menu_id)
  ************************************************************/
 function build_ui(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let config = gobj_read_attr(gobj, "config") || {};
     let shell_cfg = config.shell || {};
 
@@ -635,7 +724,7 @@ function apply_show_on($el, expr)
  ************************************************************/
 function build_item_index(gobj, config)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     priv.item_index = {};
 
     let menus = (config.menu) || {};
@@ -644,6 +733,11 @@ function build_item_index(gobj, config)
         let items = (menu && menu.items) || [];
         for(let item of items) {
             if(item.route) {
+                /*  Index by the CANONICAL form: requests are normalized
+                 *  (hash_to_route / navigate_to), so a key declared with
+                 *  a trailing or doubled slash would never match its own
+                 *  clicks otherwise. */
+                let item_route = normalize_route(item.route);
                 /*  Section-index landing (submenu.index): the section
                  *  route gets a synthesized target — the submenu itself
                  *  rendered as a "cards" C_YUI_NAV in the stage — so it
@@ -659,9 +753,9 @@ function build_item_index(gobj, config)
                  *  the common case where a `quick` drawer just reuses
                  *  routes declared (with target) in `primary.submenu`.
                  *  Rule: prefer the first entry with a target. */
-                let prev = priv.item_index[item.route];
+                let prev = priv.item_index[item_route];
                 if(!prev || (!prev.target && target)) {
-                    priv.item_index[item.route] = {
+                    priv.item_index[item_route] = {
                         item: item,
                         parent_item: null,
                         stage: target && target.stage || null,
@@ -674,9 +768,10 @@ function build_item_index(gobj, config)
             if(sub && is_array(sub.items)) {
                 for(let sub_item of sub.items) {
                     if(sub_item.route) {
-                        let prev = priv.item_index[sub_item.route];
+                        let sub_route = normalize_route(sub_item.route);
+                        let prev = priv.item_index[sub_route];
                         if(!prev || (!prev.target && sub_item.target)) {
-                            priv.item_index[sub_item.route] = {
+                            priv.item_index[sub_route] = {
                                 item: sub_item,
                                 parent_item: item,
                                 stage: sub_item.target && sub_item.target.stage || null,
@@ -697,13 +792,44 @@ function build_item_index(gobj, config)
      *  route}; their TARGET (view gclass, or kind:"action" event +
      *  redirect) lives here so the route resolves by URL on reload /
      *  deep-link.  Same precedence as menus: only fill or upgrade an
-     *  entry without a target — never clobber a menu's own target.   */
+     *  entry without a target — never clobber a menu's own target.
+     *
+     *  A route IS a path, so only "/…" keys are indexed.  JSON has no
+     *  comments and these configs annotate themselves with sibling
+     *  `_name_comment` string keys (the established idiom — see
+     *  app_config.json); indexing one built a route entry whose target
+     *  was the comment TEXT, which the site map then rendered as a
+     *  clickable row leading nowhere, and which resolve_route would
+     *  happily match.  Anything else under a "/…" key is malformed and
+     *  says so.                                                        */
     let routes = (config.shell && config.shell.routes) || {};
     for(let route in routes) {
+        if(route.charAt(0) !== "/") {
+            /*  String values are the comment idiom and stay silent;
+             *  an OBJECT under a slash-less key can only be a route
+             *  target whose key lost its "/" — dropping it silently
+             *  left the app with a menu entry that "doesn't work". */
+            if(routes[route] !== null && typeof routes[route] === "object") {
+                log_error(
+                    `C_YUI_SHELL: route key '${route}' holds a route ` +
+                    `target but does not start with '/' — ignored ` +
+                    `(a route key is a path)`
+                );
+            }
+            continue;
+        }
+        let route_key = normalize_route(route);
         let t = routes[route] || null;
-        let prev = priv.item_index[route];
+        if(t !== null && typeof t !== "object") {
+            log_error(
+                `C_YUI_SHELL: route '${route}' target is not an object ` +
+                `(${typeof t}) — ignored`
+            );
+            continue;
+        }
+        let prev = priv.item_index[route_key];
         if(!prev || (!prev.target && t)) {
-            priv.item_index[route] = {
+            priv.item_index[route_key] = {
                 item: (prev && prev.item) || null,
                 parent_item: (prev && prev.parent_item) || null,
                 stage: (t && t.stage) || null,
@@ -720,7 +846,7 @@ function build_item_index(gobj, config)
  ************************************************************/
 function instantiate_menus(gobj, config)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let zones_cfg = (config.shell && config.shell.zones) || {};
     let menus = config.menu || {};
 
@@ -835,7 +961,7 @@ function render_to_obj(layout)
 
 function instantiate_nav_in_zone(gobj, menu, menu_id, zone_id, level, nav_label)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let render_cfg = (menu.render && (menu.render[zone_id] || menu.render["*"])) ||
                      { layout: "vertical" };
     if(is_string(render_cfg)) {
@@ -910,11 +1036,9 @@ function hash_to_route(hash)
     if(!hash) {
         return "";
     }
-    let s = String(hash).replace(/^#/, "");
-    if(s.charAt(0) !== "/") {
-        s = "/" + s;
-    }
-    return s;
+    /*  Hashes come from the outside world (typed URLs, shared links):
+     *  normalize so "#/a/b/" hits the same index entry as "#/a/b". */
+    return normalize_route(String(hash).replace(/^#/, ""));
 }
 
 function route_to_hash(route)
@@ -927,11 +1051,38 @@ function route_to_hash(route)
 }
 
 /************************************************************
- *  Navigate: make `route` active
+ *  Navigate: make `route` active.  Both trailing args are internal;
+ *  external callers omit them.
+ *      depth    — the redirect-recursion counter (submenu default,
+ *                 unknown-route default, action redirects).
+ *      no_drain — this hop continues an action route whose event has
+ *                 ALREADY fired, so an overlay on the stack may be the
+ *                 one that event just opened, meant to float above the
+ *                 route we are moving to.  Draining would kill it.
  ************************************************************/
-function navigate_to(gobj, route)
+const MAX_REDIRECT_DEPTH = 8;
+
+function navigate_to(gobj, route, depth, no_drain)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
+    depth = depth || 0;
+    route = normalize_route(route);
+
+    /*  A redirect cycle (submenu default → unknown → default → …) is a
+     *  config error; without a cap it recurses to a stack overflow that
+     *  kills the app with a mute RangeError.  Fail loudly instead. */
+    if(depth > MAX_REDIRECT_DEPTH) {
+        log_error(
+            `C_YUI_SHELL: redirect loop navigating to '${route}' ` +
+            `(depth > ${MAX_REDIRECT_DEPTH}) — check submenu defaults, ` +
+            `default_route and action redirects for a cycle`
+        );
+        show_stage_placeholder(
+            gobj, "main",
+            `C_YUI_SHELL: redirect loop at route '${route}'`
+        );
+        return;
+    }
 
     /*  Audit witness: publish the navigation intent FIRST, before any
      *  validation or DOM work. This guarantees that the FSM trace and
@@ -958,7 +1109,7 @@ function navigate_to(gobj, route)
         let first_routable = sub.items && sub.items.find(it => it && it.route);
         let default_sub = sub.default || (first_routable && first_routable.route);
         if(default_sub) {
-            return navigate_to(gobj, default_sub);
+            return navigate_to(gobj, default_sub, depth + 1);
         }
     }
 
@@ -988,7 +1139,7 @@ function navigate_to(gobj, route)
                 `C_YUI_SHELL: unknown route '${route}', ` +
                 `redirecting to default '${def}'`
             );
-            return navigate_to(gobj, def);
+            return navigate_to(gobj, def, depth + 1);
         }
         log_error(`C_YUI_SHELL: no target for route '${route}'`);
         show_stage_placeholder(
@@ -1022,12 +1173,32 @@ function navigate_to(gobj, route)
      *                later close → back lands on the default instead
      *                of exiting the app.
      *  EV_ROUTE_REQUESTED was already published above, so an auditor
-     *  sees the action route intent too.                              */
+     *  sees the action route intent too.
+     *
+     *  ORDER of event vs URL work: whenever URL work happens, it happens
+     *  BEFORE the event — the overlay a handler opens must register its
+     *  synthetic history entry over the hash it will live on:
+     *    "stay"          → no URL work on a click (the URL stays where
+     *                      the click pushed it; the marker lands on this
+     *                      same hash).  The DEEP-LINK fix-up does do URL
+     *                      work (mount underneath + re-push), so there
+     *                      it runs first and the event fires after.
+     *    "back"/"none"   → restore the URL FIRST, event after.  The old
+     *                      event-first order left the overlay marker on
+     *                      the ACTION hash and the restore rewrote it,
+     *                      stranding the action's own route entry below:
+     *                      closing the overlay then history.back()ed
+     *                      onto that entry and RE-FIRED the action — the
+     *                      "site-map window won't close" loop.
+     *    "<route>"       → event first (logout-style: the handler may
+     *                      tear the shell down; navigate afterwards).   */
     if(entry.target.kind === "action") {
         let t = entry.target;
-        if(!empty_string(t.event)) {
-            gobj_publish_event(gobj, t.event, t.kw || {});
-        }
+        let publish_action = () => {
+            if(!empty_string(t.event)) {
+                gobj_publish_event(gobj, t.event, t.kw || {});
+            }
+        };
         let config = gobj_read_attr(gobj, "config") || {};
         let prev = (priv.stages && priv.stages.main &&
                     priv.stages.main.active_route) ||
@@ -1042,10 +1213,23 @@ function navigate_to(gobj, route)
                                      priv.stages.main.active_route);
                 if(!has_resting && prev && prev !== route) {
                     /*  Deep-link / reload straight onto the overlay
-                     *  route: bring up the default view underneath,
-                     *  then push this hash back on top so close→back
-                     *  returns to the default. */
-                    navigate_to(gobj, prev);
+                     *  route: bring up the default view underneath
+                     *  (rewriting this initial entry), push this hash
+                     *  back on top, and only THEN fire the event — the
+                     *  same restore-then-event rule as `back`/`none`,
+                     *  for the same reason: the overlay the handler
+                     *  opens must register its synthetic entry ABOVE
+                     *  the action hash, giving the history the exact
+                     *  shape of the click path ([resting, action,
+                     *  marker]) so ONE Back closes it.  Event-first
+                     *  here buried the marker (rewritten to the resting
+                     *  hash) UNDER the re-pushed action hash: Back #1
+                     *  landed ON the marker — own-entry check, overlay
+                     *  kept open — while the URL flipped underneath,
+                     *  and Back #2 re-fired the action off the initial
+                     *  entry.  no_drain: internal fix-up hop, not a
+                     *  resting navigation. */
+                    navigate_to(gobj, prev, depth + 1, true);
                     let h = route_to_hash(route);
                     try {
                         window.history.pushState(null, "", h);
@@ -1054,31 +1238,52 @@ function navigate_to(gobj, route)
                     }
                 }
                 /*  else: reached via a click that already pushed this
-                 *  hash — leave the URL exactly as the user sees it. */
+                 *  hash — the URL stays where the user sees it, and
+                 *  nothing was restored, so there is no ordering to
+                 *  keep: the event just fires. */
             }
+            publish_action();
             return;
         }
         if(empty_string(redirect) || redirect === "none") {
             if(gobj_read_attr(gobj, "use_hash")) {
                 let h = route_to_hash(prev);
                 try {
-                    window.history.replaceState(null, "", h);
+                    /*  Keep the current entry's state: if it is an
+                     *  overlay's synthetic entry, nulling the marker
+                     *  would break its Back/dismiss bookkeeping. */
+                    window.history.replaceState(window.history.state, "", h);
                 } catch(e) {
                     window.location.hash = h;
                 }
             }
+            publish_action();
             return;
         }
         if(redirect === "back") {
-            redirect = prev;
+            /*  Full restore of the previous resting view + its URL (the
+             *  replaceState inside rewrites the action's pushed entry),
+             *  THEN the event: an overlay opened by the handler floats
+             *  above the restored view and its synthetic entry shares
+             *  the restored hash — Back/dismiss stay invisible. */
+            if(prev !== route) {
+                navigate_to(gobj, prev, depth + 1);
+            }
+            publish_action();
+            return;
         }
+        publish_action();
         if(redirect === route) {
             log_error(
                 `C_YUI_SHELL: action route '${route}' redirects to itself`
             );
             return;
         }
-        return navigate_to(gobj, redirect);
+        /*  Event-first (logout-style: the handler may tear the shell down),
+         *  so anything the handler just put on the overlay stack belongs to
+         *  the route we are about to mount, not to the one we are leaving —
+         *  no_drain. */
+        return navigate_to(gobj, redirect, depth + 1, true);
     }
 
     /*  A fresh navigation clears any placeholder shown earlier. */
@@ -1094,6 +1299,26 @@ function navigate_to(gobj, route)
     /*  View instances are keyed by the BASE (declared) route so a
      *  subpath-only change reuses the same view (no rebuild). */
     let prev_route = stage.active_route;
+
+    /*  A change of RESTING route closes every Back-dismissable overlay:
+     *  they are transient (§3) and do not outlive the view they float
+     *  above.  (An action route or a subpath-only move never reaches
+     *  here with a different matched_route, so they keep them open.)
+     *  Their synthetic entries are NOT retired — they are buried under
+     *  the new route's entry; popped BEFORE close, so each close's
+     *  overlay_dismissed finds its entry gone and leaves it inert for a
+     *  later Back to absorb.
+     *
+     *  This holds at EVERY redirect depth — a submenu default, an
+     *  unknown-route default and an action's `"<route>"` redirect all
+     *  land the user on a different resting view, and gating the drain
+     *  on depth 0 made the very same click drain or not depending on
+     *  whether the target redirected.  `no_drain` is the one exception,
+     *  and it is about ORDER, not depth: see the `"<route>"` hop. */
+    if(!no_drain && prev_route && prev_route !== matched_route) {
+        drain_overlays(gobj);
+    }
+
     if(prev_route && prev_route !== matched_route) {
         let prev_gobj = stage.items[prev_route];
         let $prev = null;
@@ -1157,9 +1382,18 @@ function navigate_to(gobj, route)
     if(gobj_read_attr(gobj, "use_hash")) {
         let target_hash = route_to_hash(route);
         if(window.location.hash !== target_hash) {
-            /*  Using history.replaceState avoids extra hashchange fire. */
+            /*  Using history.replaceState avoids extra hashchange fire.
+             *  The current entry's state is preserved: if it is an
+             *  overlay's synthetic entry, nulling the marker would break
+             *  its Back/dismiss bookkeeping. */
             try {
-                window.history.replaceState(null, "", target_hash);
+                window.history.replaceState(window.history.state, "", target_hash);
+                /*  This rewrote the hash of the CURRENT entry.  When that
+                 *  entry is a live marker (a replace-navigation issued
+                 *  with an overlay open), its recorded hash just went
+                 *  stale — and a stale hash makes the popstate handler
+                 *  miss the Back that steps off it. */
+                retag_overlay_hash(gobj, window.history.state, target_hash);
             } catch(e) {
                 window.location.hash = target_hash;
             }
@@ -1225,7 +1459,7 @@ function build_view_gobj(gobj, entry, route, stage)
      *  (synthesized "cards" C_YUI_NAV) is SHELL-owned DOM built after
      *  the host's one-shot refresh_language — apply the registered
      *  translator, same policy as lazily-built dropdown panels. */
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(priv && typeof priv.translator === "function" &&
             target.gclass === "C_YUI_NAV") {
         refresh_language($view, priv.translator);
@@ -1265,7 +1499,7 @@ function build_toolbar(gobj, config)
         return;
     }
 
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let zone_id = tb.zone || find_toolbar_zone(config);
     let $zone = priv.zones[zone_id];
     if(!$zone) {
@@ -1440,7 +1674,7 @@ function build_toolbar_brand_item(gobj, it)
  ************************************************************/
 function build_toolbar_avatar_item(gobj, it)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let aria_key = it.aria_label || it.name || it.id || "User menu";
     let i18n_aria = it.aria_label || it.name || "User menu";
     let action_type = (it.action && it.action.type) || "";
@@ -1495,7 +1729,7 @@ function paint_avatar(priv, $node)
 
 function refresh_avatars(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv || !is_array(priv.avatar_nodes)) {
         return;
     }
@@ -1531,7 +1765,7 @@ function attach_context_action(gobj, $item, it)
  ************************************************************/
 function build_toolbar_connection_item(gobj, it)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let aria_key  = it.aria_label || it.name || it.id || "backend connection";
     let i18n_aria = it.aria_label || it.name || "backend connection";
     let attrs = {
@@ -1572,13 +1806,40 @@ function find_toolbar_zone(config)
     return "top";
 }
 
+/************************************************************
+ *  True when a click on `route` resolves to an action route whose
+ *  flavour RESTORES the previous resting URL by rewriting the
+ *  current history entry ("back", "none"/"").  Pushing the action
+ *  hash first would leave that rewritten entry as an exact
+ *  duplicate of the resting entry below it — one dead Back press
+ *  per click.  The click entry points navigate those directly
+ *  instead of going through the hash.  ("stay" and "<route>" keep
+ *  the push: their URL genuinely moves.)
+ ************************************************************/
+function route_restores_url(gobj, route)
+{
+    let priv = gobj.priv;
+    if(!priv || !priv.item_index) {
+        return false;
+    }
+    let r = resolve_route(priv.item_index, normalize_route(route));
+    let target = r && r.entry && r.entry.target;
+    if(!target || target.kind !== "action") {
+        return false;
+    }
+    return target.redirect === "back" ||
+           target.redirect === "none" ||
+           empty_string(target.redirect);
+}
+
 function handle_toolbar_action(gobj, item, $trigger)
 {
     let action = (item && item.action) || {};
     switch(action.type) {
         case "navigate":
             if(!empty_string(action.route)) {
-                if(gobj_read_attr(gobj, "use_hash")) {
+                if(gobj_read_attr(gobj, "use_hash") &&
+                        !route_restores_url(gobj, action.route)) {
                     let h = route_to_hash(action.route);
                     if(window.location.hash !== h) {
                         window.location.hash = h;   /*  fires hashchange  */
@@ -1636,7 +1897,7 @@ function handle_toolbar_action(gobj, item, $trigger)
  ************************************************************/
 function toggle_toolbar_dropdown(gobj, item, action, $trigger)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv) {
         return;
     }
@@ -1651,7 +1912,7 @@ function toggle_toolbar_dropdown(gobj, item, action, $trigger)
 
 function open_toolbar_dropdown(gobj, item, action, $trigger)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv || !priv.layers || !priv.layers.popup) {
         return;
     }
@@ -1751,7 +2012,7 @@ function open_toolbar_dropdown(gobj, item, action, $trigger)
 
 function close_toolbar_dropdown(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv) {
         return;
     }
@@ -1846,7 +2107,7 @@ function build_dropdown_row(gobj, sub, idx)
  ************************************************************/
 function preinstantiate_eager_views(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     for(let route in priv.item_index) {
         let entry = priv.item_index[route];
         let t = entry.target;
@@ -1881,7 +2142,7 @@ function preinstantiate_eager_views(gobj)
  ************************************************************/
 function drawers(gobj, menu_id)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let out = [];
     for(let nav of priv.navs) {
         if(gobj_read_attr(nav, "layout") !== "drawer") {
@@ -1907,7 +2168,7 @@ function drawers(gobj, menu_id)
  ************************************************************/
 function push_escape(gobj, layer, handler)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv || !priv.escape_stack) {
         return;
     }
@@ -1916,7 +2177,7 @@ function push_escape(gobj, layer, handler)
 
 function pop_escape(gobj, handler)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv || !priv.escape_stack) {
         return;
     }
@@ -1926,6 +2187,139 @@ function pop_escape(gobj, handler)
     }
 }
 
+/************************************************************
+ *  Overlay history integration — Back button ↔ modals/windows.
+ *
+ *  An overlay that wants the browser Back button to close it (modal,
+ *  floating window) registers on open with push_overlay_history and
+ *  calls overlay_dismissed when it closes by ANY other path.
+ *
+ *  On open we push a synthetic history entry that keeps the current
+ *  hash, so routing is untouched.  The two close paths converge on the
+ *  same overlay_stack, and membership in it disambiguates which one ran:
+ *
+ *    - Back pressed  → popstate pops the entry and calls entry.close();
+ *      the browser already dropped the history entry, so the later
+ *      overlay_dismissed finds the entry gone and does nothing.
+ *    - X/Escape/code → the overlay's close runs first (entry still on
+ *      the stack), overlay_dismissed removes it and history.back()s to
+ *      retire the still-present browser entry (that popstate is counted
+ *      in expected_pops and ignored).
+ *
+ *  The synthetic entry carries a state marker ({__yui_overlay__: id})
+ *  recording which overlay it belongs to.  Route navigation interplay:
+ *    - fragment navigations fire popstate too (all engines), so the
+ *      popstate handler treats only SAME-HASH landings as overlay pops;
+ *      a hash-changing landing is a route move owned by hashchange.
+ *    - navigate_to() drains (closes) every registered overlay when the
+ *      RESTING route changes — overlays are transient and do not
+ *      outlive the view they float above.  An action route or a
+ *      subpath-only move keeps them open.
+ *    - a drained/buried entry is left INERT: overlay_dismissed only
+ *      history.back()s when the marker is the CURRENT history entry
+ *      (adjacent, so the back() is invisible) — never over real route
+ *      entries (that teleported the user).  A later Back absorbs an
+ *      inert entry as a same-hash no-op.
+ *
+ *  Gated on `use_hash`: an app that manages its own routing gets no
+ *  synthetic entries — a stray history.back() there could exit it.
+ ************************************************************/
+/*  Close every registered overlay because the resting route changed.
+ *  Pop-then-close (the popstate handler's pattern): the overlay's own
+ *  close path then finds its entry gone in overlay_dismissed and does
+ *  NOT history.back() — the buried synthetic entries stay inert. */
+function drain_overlays(gobj)
+{
+    let priv = gobj.priv;
+    if(!priv || !priv.overlay_stack) {
+        return;
+    }
+    while(priv.overlay_stack.length > 0) {
+        let entry = priv.overlay_stack.pop();
+        try {
+            entry.close();
+        } catch(e) {
+            log_warning(`C_YUI_SHELL: overlay close on navigation failed: ${e}`);
+        }
+    }
+}
+
+/*  A URL rewrite moved the entry `st` tags to `hash`.  When `st` is a live
+ *  overlay marker, follow it: its entry's recorded hash is the popstate
+ *  handler's authority and must not drift from the entry it describes. */
+function retag_overlay_hash(gobj, st, hash)
+{
+    let priv = gobj.priv;
+    if(!priv || !priv.overlay_stack || !st || !st.__yui_overlay__) {
+        return;
+    }
+    let entry = priv.overlay_stack.find(e => e.id === st.__yui_overlay__);
+    if(entry) {
+        entry.hash = hash;
+    }
+}
+
+function push_overlay_history(gobj, close)
+{
+    let priv = gobj.priv;
+    if(!priv || !priv.overlay_stack || !gobj_read_attr(gobj, "use_hash")) {
+        return null;
+    }
+    /*  `hash` = the hash the marker entry lives on (pushState with no URL
+     *  keeps the current one).  The popstate handler needs it to tell a
+     *  step OFF this marker from a route traversal; it is NOT the resting
+     *  route (a `stay` action route parks the URL off it).  Kept in sync
+     *  by the silent replaceState fix-up in navigate_to(). */
+    let entry = { id: ++priv.overlay_seq, close: close,
+                  hash: window.location.hash };
+    priv.overlay_stack.push(entry);
+    try {
+        window.history.pushState({ __yui_overlay__: entry.id }, "");
+    } catch(e) {
+        /*  pushState failed (rare): drop the entry so overlay_dismissed
+         *  won't later history.back() past a real route. */
+        priv.overlay_stack.pop();
+        log_warning(`C_YUI_SHELL: overlay pushState failed: ${e}`);
+        return null;
+    }
+    return entry;
+}
+
+function overlay_dismissed(gobj, entry)
+{
+    let priv = gobj.priv;
+    if(!priv || !priv.overlay_stack || !entry) {
+        return;
+    }
+    let idx = priv.overlay_stack.indexOf(entry);
+    if(idx < 0) {
+        /*  Already removed by the popstate handler (closed via Back). */
+        return;
+    }
+    priv.overlay_stack.splice(idx, 1);
+    /*  Retire the synthetic browser entry ONLY when it is the CURRENT
+     *  one — its state marker is live — so history.back() steps off it
+     *  invisibly (same hash, no route change).  In every other case the
+     *  entry is NOT adjacent and a back() would traverse REAL entries:
+     *    - the user route-navigated after opening the overlay (the
+     *      marker sits buried under newer route entries) — a back()
+     *      here would teleport them to the pre-overlay route;
+     *    - a non-LIFO dismissal (a lower overlay closed under a higher
+     *      one) — a back() would pop past the higher overlay's entry.
+     *  Leave the entry inert instead: a later Back lands on it with the
+     *  same hash and is absorbed harmlessly. */
+    let st = window.history.state;
+    if(st && st.__yui_overlay__ === entry.id) {
+        priv.expected_pops++;
+        try {
+            window.history.back();
+        } catch(e) {
+            priv.expected_pops--;
+            log_warning(`C_YUI_SHELL: overlay history.back() failed: ${e}`);
+        }
+    }
+}
+
 /*  Per-drawer open/close.  The escape-stack entry and the focus-
  *  trap release function are parked on the $drawer DOM element so
  *  any close path (Escape, backdrop click, toolbar action, public
@@ -1989,7 +2383,7 @@ function toggle_drawer(gobj, menu_id)
 
 function close_all_drawers(gobj)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     if(!priv) {
         return;
     }
@@ -2011,7 +2405,7 @@ function close_all_drawers(gobj)
  ************************************************************/
 function show_stage_placeholder(gobj, stage_name, message)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let stage = priv.stages[stage_name];
     if(!stage || !stage.el) {
         return;
@@ -2027,7 +2421,7 @@ function show_stage_placeholder(gobj, stage_name, message)
 
 function clear_stage_placeholder(gobj, stage_name)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     let stage = priv.stages[stage_name];
     if(!stage || !stage.el) {
         return;
@@ -2040,7 +2434,7 @@ function clear_stage_placeholder(gobj, stage_name)
 
 function update_secondary_nav_visibility(gobj, entry)
 {
-    let priv = gobj_read_attr(gobj, "priv");
+    let priv = gobj.priv;
     /*  shell.routes entries (root, forms, action routes) have no menu
      *  item — entry.item / entry.parent_item are null.  No active
      *  primary then: the secondary zone collapses (has_secondary
@@ -2135,8 +2529,10 @@ function ac_nav_clicked(gobj, event, kw, src)
 
     /*  When hash routing is on, let the hash drive navigate_to() — that
      *  way back/forward buttons and programmatic hash changes all flow
-     *  through the same code path.  Otherwise call navigate_to directly. */
-    if(gobj_read_attr(gobj, "use_hash")) {
+     *  through the same code path.  Otherwise call navigate_to directly.
+     *  Exception: URL-restoring action routes skip the push — see
+     *  route_restores_url. */
+    if(gobj_read_attr(gobj, "use_hash") && !route_restores_url(gobj, route)) {
         let target_hash = route_to_hash(route);
         if(window.location.hash !== target_hash) {
             window.location.hash = target_hash;  /*  fires hashchange */
@@ -2226,7 +2622,7 @@ function find_primary_item(shell_gobj, menu_id, item_id)
 /*  Drop a route from the index and destroy any mounted view for it. */
 function prune_route(shell_gobj, route)
 {
-    let priv = gobj_read_attr(shell_gobj, "priv");
+    let priv = shell_gobj.priv;
     delete priv.item_index[route];
     for(let stage_name in priv.stages) {
         let stage = priv.stages[stage_name];
@@ -2253,7 +2649,7 @@ function prune_route(shell_gobj, route)
 
 function yui_shell_set_submenu(shell_gobj, parent_item_id, items)
 {
-    let priv = gobj_read_attr(shell_gobj, "priv");
+    let priv = shell_gobj.priv;
     if(!priv) {
         return -1;
     }
@@ -2283,8 +2679,11 @@ function yui_shell_set_submenu(shell_gobj, parent_item_id, items)
     let new_set = {};
     for(let it of items) {
         if(it && it.route) {
-            new_routes.push(it.route);
-            new_set[it.route] = true;
+            /*  Same canonical form as build_item_index: requests are
+             *  normalized, so raw keys would never match their clicks. */
+            let it_route = normalize_route(it.route);
+            new_routes.push(it_route);
+            new_set[it_route] = true;
         }
     }
     for(let route of prev_routes) {
@@ -2298,7 +2697,7 @@ function yui_shell_set_submenu(shell_gobj, parent_item_id, items)
         if(!it || !it.route) {
             continue;
         }
-        priv.item_index[it.route] = {
+        priv.item_index[normalize_route(it.route)] = {
             item: it,
             parent_item: parent_item,
             stage: (it.target && it.target.stage) || null,
@@ -2388,6 +2787,17 @@ function create_gclass(gclass_name)
                                      |event_flag_t.EVF_PUBLIC_EVENT
                                      |event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_ROUTE_CHANGED",          event_flag_t.EVF_OUTPUT_EVENT
+                                     |event_flag_t.EVF_PUBLIC_EVENT
+                                     |event_flag_t.EVF_NO_WARN_SUBS],
+
+        /*  The language changed (the app switched it and called
+         *  yui_shell_language_changed).  refresh_language() re-translates
+         *  every node that CARRIES its key, but a view that COMPOSED a string
+         *  with t() at render time — a title, a row counter, a Tabulator
+         *  header or paginator — holds no key and cannot be reached that way.
+         *  So the fact is published: such a view subscribes to its shell and
+         *  re-renders its own translated parts.  */
+        ["EV_LANGUAGE_CHANGED",       event_flag_t.EVF_OUTPUT_EVENT
                                      |event_flag_t.EVF_PUBLIC_EVENT
                                      |event_flag_t.EVF_NO_WARN_SUBS]
     ];
@@ -2442,13 +2852,96 @@ function yui_shell_of(gobj)
 }
 
 /************************************************************
- *  Programmatic navigation (bypass hash).
+ *  Programmatic navigation.
+ *
+ *  Default — PUSH: the user MOVED somewhere new, so change the URL via
+ *  the hash and let the browser record a Back entry (routed through the
+ *  same hashchange path as a nav click). This is the common case and the
+ *  safe default: a human deliberately chose to go there, so Back must
+ *  return them.
+ *
+ *  `opts.replace:true` — REPLACE: sync the URL WITHOUT a Back entry. Use
+ *  when CODE decided the move for the user: redirects, normalizations,
+ *  submenu-parent → default child, F5-restores (see ROUTING.md §2/§7).
+ *
+ *  `opts.push:true` is redundant now (it IS the default) but stays valid,
+ *  so migrated call sites keep documenting their intent explicitly.
  ************************************************************/
-function yui_shell_navigate(shell_gobj, route)
+function yui_shell_navigate(shell_gobj, route, opts)
 {
+    if(!(opts && opts.replace) && gobj_read_attr(shell_gobj, "use_hash")) {
+        let target_hash = route_to_hash(route);
+        if(window.location.hash !== target_hash) {
+            /*  Push a real history entry; the hashchange handler mounts. */
+            window.location.hash = target_hash;
+            return;
+        }
+        /*  Same hash — hashchange won't fire; fall through to mount. */
+    }
     navigate_to(shell_gobj, route);
 }
 
+/************************************************************
+ *  Nav map — the WHOLE navigation surface as an ordered tree, for
+ *  the "site map" / documentation viewer.  The heavy lifting is the
+ *  pure builder in route_map_model.js (unit-tested there): toolbar
+ *  (incl. the account dropdown), every declared menu (incl. live
+ *  dynamic tabs), each view's contributed sub-routes, the routes
+ *  declared only in the route table (`other`), and the "you are
+ *  here" marker.  Returns {brand, toolbar, nav, other}.
+ ************************************************************/
+function yui_shell_nav_map(shell_gobj)
+{
+    let priv = shell_gobj.priv;
+    return build_nav_map({
+        config:         gobj_read_attr(shell_gobj, "config") || {},
+        item_index:     (priv && priv.item_index) || {},
+        sub_routes:     (priv && priv.sub_routes) || {},
+        event_handlers: (priv && priv.event_handlers) || {},
+        current_route:  gobj_read_attr(shell_gobj, "current_route") || ""
+    });
+}
+
+/************************************************************
+ *  Sub-route contributor protocol (ROUTING.md): a mounted view
+ *  declares the deep, view-owned children of its base route for the
+ *  site map. `nodes` is an ordered array of
+ *  {route, label, icon?, children?} (full hashless routes); pass
+ *  null/[] to clear (call on the view's stop/teardown so the map
+ *  never shows a torn-down view's children).
+ ************************************************************/
+function yui_shell_set_sub_routes(shell_gobj, base_route, nodes)
+{
+    let priv = shell_gobj.priv;
+    if(!priv || !priv.sub_routes || empty_string(base_route)) {
+        return;
+    }
+    if(nodes && nodes.length) {
+        priv.sub_routes[base_route] = nodes;
+    } else {
+        delete priv.sub_routes[base_route];
+    }
+}
+
+/************************************************************
+ *  Event-handler registry (ROUTING.md): a gclass that HANDLES a
+ *  toolbar/account action event self-declares, so the site map can
+ *  show where the action is implemented. Call once (e.g. in mt_start,
+ *  next to the matching `gobj_subscribe_event`). Idempotent per
+ *  (event, gclass); several gclasses may handle the same event.
+ ************************************************************/
+function yui_shell_register_event_handler(shell_gobj, event, gclass)
+{
+    let priv = shell_gobj.priv;
+    if(!priv || !priv.event_handlers || empty_string(event) || empty_string(gclass)) {
+        return;
+    }
+    let list = priv.event_handlers[event] || (priv.event_handlers[event] = []);
+    if(list.indexOf(gclass) < 0) {
+        list.push(gclass);
+    }
+}
+
 /*  Drawer helpers — toggle the off-canvas nav from the outside
  *  (e.g. a hamburger button in the toolbar).  menu_id is optional. */
 function yui_shell_open_drawer(shell_gobj, menu_id)    { open_drawer(shell_gobj, menu_id);   }
@@ -2477,6 +2970,45 @@ function yui_shell_pop_escape(shell_gobj, handler)
     pop_escape(shell_gobj, handler);
 }
 
+/*  Overlay history integration — public API for overlays the shell does
+ *  not own (modals from shell_modals.js, floating C_YUI_WINDOW popups).
+ *
+ *      let overlay = yui_shell_register_overlay(shell, close_fn);
+ *      // ... when the overlay closes by ANY non-Back path, also call:
+ *      yui_shell_overlay_dismissed(shell, overlay);
+ *
+ *  `close_fn` is what the Back button invokes to tear the overlay down.
+ *  Returns null when history integration is off (no shell / use_hash) —
+ *  callers just skip the paired yui_shell_overlay_dismissed then. */
+function yui_shell_register_overlay(shell_gobj, close_fn)
+{
+    return push_overlay_history(shell_gobj, close_fn);
+}
+function yui_shell_overlay_dismissed(shell_gobj, overlay)
+{
+    overlay_dismissed(shell_gobj, overlay);
+}
+
+/************************************************************
+ *  Take the URL back off an action route the app parked it on
+ *  (`redirect:"stay"`), from the overlay's close path — the
+ *  reference `stay` wiring (ROUTING.md §7.1).
+ *
+ *  Guarded on purpose: when the close came from the shell's
+ *  overlay drain (the user navigated to another resting route
+ *  while the overlay was open), the URL has ALREADY moved off
+ *  the route — a blind history.back() there lands on the
+ *  stranded action entries and RE-FIRES the action, reopening
+ *  the overlay and hijacking the navigation the user asked
+ *  for.  Only back() while the URL still sits on the route.
+ ************************************************************/
+function yui_shell_unpark_route(route)
+{
+    if(window.location.hash === route_to_hash(normalize_route(route))) {
+        window.history.back();
+    }
+}
+
 /************************************************************
  *  Avatar provider — toolbar items with type:"avatar" call the
  *  registered provider whenever the shell paints initials.  The
@@ -2489,7 +3021,7 @@ function yui_shell_pop_escape(shell_gobj, handler)
  ************************************************************/
 function yui_shell_set_avatar_provider(shell_gobj, provider)
 {
-    let priv = gobj_read_attr(shell_gobj, "priv");
+    let priv = shell_gobj.priv;
     if(!priv) {
         return;
     }
@@ -2513,13 +3045,35 @@ function yui_shell_refresh_avatars(shell_gobj)
  ************************************************************/
 function yui_shell_set_translator(shell_gobj, t)
 {
-    let priv = gobj_read_attr(shell_gobj, "priv");
+    let priv = shell_gobj.priv;
     if(!priv) {
         return;
     }
     priv.translator = (typeof t === "function") ? t : null;
 }
 
+/************************************************************
+ *  The app switched the language: re-translate the whole document (every
+ *  node carrying data-i18n / data-i18n-title / data-i18n-aria-label) and
+ *  PUBLISH the fact, so the views that build DOM imperatively — Tabulator
+ *  headers and paginators, composed titles, row counters — can re-render
+ *  what no attribute can reach.
+ *
+ *  The app remains the owner of the locales: it switches its i18next and
+ *  calls this. The shell only fans the fact out.
+ ************************************************************/
+function yui_shell_language_changed(shell_gobj)
+{
+    if(!shell_gobj || !is_gobj(shell_gobj)) {
+        return;
+    }
+    let priv = shell_gobj.priv;
+    if(priv && typeof priv.translator === "function") {
+        refresh_language(document.body, priv.translator);
+    }
+    gobj_publish_event(shell_gobj, "EV_LANGUAGE_CHANGED", {});
+}
+
 /************************************************************
  *  Set the backend-connection state painted by every
  *  type:"connection" toolbar item.  Host/event-driven: the
@@ -2529,7 +3083,7 @@ function yui_shell_set_translator(shell_gobj, t)
  ************************************************************/
 function yui_shell_set_connection_state(shell_gobj, connected)
 {
-    let priv = gobj_read_attr(shell_gobj, "priv");
+    let priv = shell_gobj.priv;
     if(!priv || !is_array(priv.conn_nodes)) {
         return;
     }
@@ -2587,14 +3141,21 @@ export {
     register_c_yui_shell,
     yui_shell_of,
     yui_shell_navigate,
+    yui_shell_nav_map,
+    yui_shell_set_sub_routes,
+    yui_shell_register_event_handler,
     yui_shell_open_drawer,
     yui_shell_close_drawer,
     yui_shell_toggle_drawer,
     yui_shell_push_escape,
     yui_shell_pop_escape,
+    yui_shell_register_overlay,
+    yui_shell_overlay_dismissed,
+    yui_shell_unpark_route,
     yui_shell_set_avatar_provider,
     yui_shell_refresh_avatars,
     yui_shell_set_translator,
+    yui_shell_language_changed,
     yui_shell_set_connection_state,
     yui_shell_set_toolbar_item_icon,
     yui_shell_close_dropdown,