hdoc-tools 0.62.5 → 0.63.0

package/ui/js/doc.hornbill.js

@@ -2,808 +2,3213 @@
 //-- THIS CONTROLS NAVIGATION
 //-- loaded in index.html
 
-let jqContentContainer = null;
-let jqDocumentHeader = null;
-let jqLeftNav = null;
-const global = { stateParams: {}, lastLayoutClass: "" };
+var bInitialPageLoad = true;
+var global = {stateParams:{},session:{}};
+var arrSearchResponseTimes = {};
+var arrSearchResponseTimesByWordCount = {};
+
+//-- Search request tracking. The debounce in searchDocuments only cancels a pending
+//-- TIMER - once a fetch is away it runs to completion, so two overlapping searches
+//-- resolved in arrival order and a slow earlier query could land last and clobber
+//-- the newer results. searchRequestSeq is a monotonic id: the .then compares its
+//-- captured id against the current one and drops the response if it has been
+//-- superseded. searchAbortController additionally cancels the older request so we
+//-- aren't paying for a response we would only throw away. //-- SG
+var searchRequestSeq = 0;
+var searchAbortController = null;
+
+var docAppMethods = {
+    setSessionInfo:function(info)
+    {
+        let self = this;
+        self.docApp.userSession = info;
+        global.session = info;
+    },
+
+    switchSettingsView:function()
+    {
+        // Store current page so we can return to it
+        sessionStorage.setItem("hdoc-settings-return-url", document.location.href);
+        const currUrl = new URL(document.location.href);
+        document.location.href = currUrl.origin + "/settings";
+    },
+    switchViewTheme:function()
+    {
+        if(ThemePreference)document.documentElement.classList.remove(ThemePreference);
+
+        if(ThemePreference === 'dark')
+        {
+            ThemePreference = 'light';
+        }
+        else{
+            ThemePreference = 'dark';
+        }
+
+        localStorage.setItem('hdocbook-theme-appearance',ThemePreference);
+        document.documentElement.classList.add(ThemePreference);
+
+        //-- so can show different theme button icon need to store pref against view app
+        //-- ThemePreference is declared in data(), so this assignment re-renders the two theme
+        //-- buttons on its own - no $forceUpdate() needed. //-- SG
+        let self = this;
+        self.docApp.ThemePreference = ThemePreference;
+
+    },
+    renderNavigation:function()
+    {
+        let self = this;
+
+        //-- Seed expand:false on every node before handing the tree to Vue. hdocbook.json has no
+        //-- expand key, so it was previously created on first click. Vue 3 tracks late-added
+        //-- properties so that worked, but declaring it up front means the collapse state is part
+        //-- of the shape Vue observes from the outset rather than appearing mid-flight - which is
+        //-- what lets toggleNavCollapse() drop its $forceUpdate(). //-- SG
+        let seedExpand = function(items)
+        {
+            if(!Array.isArray(items)) return;
+            for(let x=0;x<items.length;x++)
+            {
+                if(items[x].expand === undefined) items[x].expand = false;
+                seedExpand(items[x].items);
+            }
+        };
+        seedExpand(self.docApp.book.navigation.items);
+
+        self.docApp.navSections = self.docApp.book.navigation.items; //-- show be an array of nav groups
+    },
+    toggleTocMenu:function()
+    {
+        view.docApp.tocMobileOpen = !view.docApp.tocMobileOpen;
+    },
+    closeTocMenu:function()
+    {
+        view.docApp.tocMobileOpen = false;
+    },
+    toggleMobileMenu:function()
+    {
+        view.docApp.bookNavOpen = !view.docApp.bookNavOpen;
+    },
+    resetMobileMenu:function(ev)
+    {
+        //-- Runs on EVERY click anywhere in the app, via data-root-click on the mount host.
+        //--
+        //-- Both panels it governs are Vue-rendered, so their open state is Vue state and this
+        //-- function only ever writes that state - never a class. It used to toggle .open on
+        //-- .DocSidebar directly while keeping a second copy of the flag in
+        //-- $(".mobile-menu-btn").data("isopen"): two sources of truth over DOM that Vue
+        //-- rewrites on re-render. That is exactly what made the search Filters button look
+        //-- dead - the class was stripped here on the same click that opened it, while Vue
+        //-- still believed the panel was open and so never re-added it. //-- SG
+        if(!ev || !ev.target || !ev.target.closest) return;
+
+        let target = ev.target;
+
+        //-- a click on a content link (a.DocLink) should dismiss the menu - the user has picked a
+        //-- page. Group expand/collapse rows are .navSectionGroupItem divs, not .DocLink anchors,
+        //-- so they still fall through to the keep-open clause below. //-- SG
+        //--
+        //-- closest() matches the element itself as well as its ancestors, which is why the old
+        //-- hasClass(...) || closest(...) pairs collapse to one test each. //-- SG
+        let clickedNavLink = !!target.closest("a.DocLink");
+        let keepBookNavOpen = view.docApp.bookNavOpen && !clickedNavLink && !!target.closest(".hdoc-nav");
+
+        if(!(keepBookNavOpen || target.closest(".mobile-menu-btn") || target.closest(".navSectionGroupItem")))
+        {
+            view.docApp.bookNavOpen = false;
+        }
+
+        //-- the search filter panel dismisses on an outside click too. Its own button is excluded
+        //-- or it would close on the very click that opened it. //-- SG
+        if(view.docApp.searchFiltersOpen
+            && !target.closest(".LibrarySearch .DocSidebar")
+            && !target.closest(".search-filter-btn"))
+        {
+            view.docApp.searchFiltersOpen = false;
+        }
+    },
+    organiseLibraryByGroup:function(oGroupMode,registerUrlState)
+    {
+        //-- coming from event - so want to change url state so can click back to last lib view mode
+        if(registerUrlState)
+        {
+            //-- set url to root
+            let urlToSet = window.location.origin + "/?mode=" + oGroupMode.mode;
+            const url = new URL(urlToSet);
+            window.history.pushState(null, null, url);
+        }
+        organiseLibrary(oGroupMode);
+    },
+    loadProductHome:function(productGroup,registerUrlState)
+    {
+        //-- coming from event - so want to change url state so can click back to last lib view mode
+        if(registerUrlState)
+        {
+            //-- set url to root
+            let urlToSet = window.location.origin + "/?mode=product&product="+productGroup.id;
+            const url = new URL(urlToSet);
+            window.history.pushState(null, null, url);
+        }
+        view.docApp.libraryHomeViewProduct = productGroup;
+
+    },
+    loadLibraryHome:function()
+    {
+        //-- will reset view
+        view.docApp.boolSearchInProgress = false;
+        view.docApp.searchMode = false;
+        view.docApp.mcpCatalogMode = false;
+        view.docApp.searchResponse = null;
+        view.docApp.searchFilterBySpecificBookId = "";
+
+        resetCheckedProducts();
+        view.docApp.searchFilteredProducts = {};
+        
+        view.docApp.altSearchText = "";
+        view.docApp.searchText = "";
+        view.docApp.book = {};
+        view.docApp.libraryHomeViewProduct = null;
+        
+        document.title = "Hornbill Documentation";
+
+        //-- set url to root
+        let urlToSet = window.location.origin + "/";
+        const url = new URL(urlToSet);
+        window.history.pushState(null, null, url);
+
+        //-- remove hidden class
+        revealApp();
+
+    },
+    clearSearchFilters:function($ev)
+    {
+
+      
+        resetCheckedProducts();
+        view.docApp.searchFilteredProducts = {};
+        view.docApp.hasFilterByProducts = false;
+        view.docApp.searchFilterBySpecificBookId = "";
+        view.docApp.searchFilterBySpecificBookTitle = "";
+        view.docApp.searchAudienceFilter = "";
+        view.docApp.searchDocTypeFilter = "";
+        //-- clearing the filters is an explicit choice of "no content-type filter", so it
+        //-- persists like any other pick - otherwise the remembered value would silently
+        //-- come back on the next auto-widen restore //-- SG
+        rememberDocTypeFilter("");
+        view.searchDocuments(view.docApp.altSearchText,false,$ev,true);
+
+    },
+    filterSearchByAudience:function($ev)
+    {
+        //-- v-model has already written the selected value to searchAudienceFilter;
+        //-- this is a server-side filter so re-run the search //-- SG
+        view.searchDocuments(view.docApp.altSearchText,false,$ev,true);
+    },
+    toggleSearchFilters:function()
+    {
+        //-- Below 1020px the filter sidebar is hidden and this view has no burger, so
+        //-- the filters were unreachable. The panel is already styled to slide in via
+        //-- .DocSidebar.open; this just drives that class.
+        //--
+        //-- Bound through Vue rather than jQuery like the book-page burger: this state
+        //-- is reactive, so a jQuery-applied class is patched straight back off on the
+        //-- re-render that setting it triggers. The book nav gets away with jQuery only
+        //-- because nothing re-renders that element. //-- SG
+        view.docApp.searchFiltersOpen = !view.docApp.searchFiltersOpen;
+    },
+    closeSearchFilters:function()
+    {
+        view.docApp.searchFiltersOpen = false;
+    },
+    filterSearchByDocType:function(docType,$ev)
+    {
+        //-- server-side soft filter; re-run so the counts come back whole-corpus //-- SG
+        view.docApp.searchDocTypeFilter = docType;
+        rememberDocTypeFilter(docType);
+        view.docApp.searchDocTypeRescue = null;
+        docTypeAutoWidenedForQuery = null;
+        view.closeSearchFilters();
+        view.searchDocuments(view.docApp.altSearchText,false,$ev,true);
+    },
+    filterSearchByProducts:function(product,$ev)
+    {
+        let productId = product.id;
+        if(view.docApp.searchFilteredProducts[productId])
+        {
+            view.docApp.searchFilteredProducts[productId].checked = !view.docApp.searchFilteredProducts[productId].checked;
+        }
+        else
+        {
+
+            view.docApp.searchFilteredProducts[productId] = {checked:true};
+        }
+
+        //-- so check or uncheck the flag in ui
+        product.checked = view.docApp.searchFilteredProducts[productId].checked;
+
+        //-- client side filtering
+        if(view.docApp.searchResponse && Array.isArray(view.docApp.searchResponse.results))
+        {
+            prepareSearchResultItems(view.docApp.searchResponse.results || []);
+        }
+
+        let checkedProducts = getCheckedProductFilterArray();
+        view.docApp.hasFilterByProducts = checkedProducts.length > 0; //-- declared boolean, keep it one
+
+
+
+    },
+    filterSearchByBook:function(aBook,$ev)
+    {
+        view.docApp.searchFilterBySpecificBookId = aBook.bookId;
+        view.docApp.searchFilterBySpecificBookTitle = aBook.title;
+        //-- an explicit pick replaces whatever bad id the rescue reported on
+        view.docApp.searchBookRescue = null;
+        //-- going to re-search
+        view.searchDocuments(view.docApp.altSearchText,false,$ev,true);
+
+    },
+    toolbarSearch:function(strOnLoadSearch,initalBookIdFilter,boolFromPop)
+    {
+        //-- "|| \"\"": index.html binds keyup.enter="toolbarSearch()" with no arguments, so an
+        //-- empty toolbar box used to hand undefined through to searchDocuments, which threw on
+        //-- .match() before it could take its own empty-search exit //-- SG
+        if(!view.docApp.searchText)view.docApp.searchText = strOnLoadSearch || "";
+        view.docApp.altSearchText = view.docApp.searchText;   
+        view.docApp.currentResultsSearchText = "";
+        view.docApp.searchFilterBySpecificBookId = initalBookIdFilter || "";
+        view.searchDocuments(view.docApp.searchText,boolFromPop);
+
+    },
+
+    openMcpCatalogView:function()
+    {
+        //-- /mcp - the catalog of MCP servers this site exposes. Same shape as
+        //-- openSearchView: clear the other views, push the url, then load. The data
+        //-- comes from _api/mcp_catalog, which is generated from the servers actually
+        //-- mounted rather than a hand-kept list. //-- SG
+        view.docApp.book = {};
+        view.docApp.searchMode = false;
+        view.docApp.libraryHomeViewProduct = null;
+        view.docApp.mcpCatalogMode = true;
+        document.title = "Connect an AI assistant - Hornbill Documentation";
+
+        if(window.location.pathname !== "/mcp")
+        {
+            window.history.pushState({}, "", "/mcp");
+        }
+
+        revealApp();
+        view.loadMcpCatalog();
+    },
+
+    loadMcpCatalog:function()
+    {
+        //-- static enough to fetch once per page load
+        if(view.docApp.mcpCatalog.loaded) return;
+
+        fetchJsonFile("_api/mcp_catalog").then(function(data)
+        {
+            if(data && data.servers)
+            {
+                view.docApp.mcpCatalog.servers = data.servers;
+                view.docApp.mcpCatalog.loaded = true;
+                view.docApp.mcpCatalog.error = false;
+            }
+            else
+            {
+                //-- keep the model shape and flag the error; the template dereferences
+                //-- mcpCatalog.* at render time, so nulling it would be a blank view //-- SG
+                view.docApp.mcpCatalog.error = true;
+            }
+        });
+    },
+
+    mcpToolDescriptionParts:function(text)
+    {
+        //-- tool descriptions are written for the MODEL, so they mark identifiers with
+        //-- backticks. Split on them so the page can render real <code> spans without
+        //-- v-html - the descriptions are ours, but nothing here needs to compile HTML
+        //-- from data, and this site deliberately never does. //-- SG
+        return String(text || "").split("`").map(function(part, i)
+        {
+            return { text: part, code: (i % 2) === 1 };
+        });
+    },
+
+    mcpCopy:function(key, text)
+    {
+        //-- Copy a connection field. Feedback is a reactive flag per field rather than
+        //-- DOM poking, so the icon swap is just a binding. navigator.clipboard needs a
+        //-- secure context; the docs sites are https and localhost counts, but fall back
+        //-- to the execCommand approach the code-block badge uses so a plain-http
+        //-- deployment still works. //-- SG
+        var settle = function(ok)
+        {
+            view.docApp.mcpCopied[key] = ok;
+            setTimeout(function(){ delete view.docApp.mcpCopied[key]; }, 1600);
+        };
+
+        if(navigator.clipboard && window.isSecureContext)
+        {
+            navigator.clipboard.writeText(text).then(function(){ settle(true); }, function(){ settle(false); });
+            return;
+        }
+
+        var el = document.createElement("textarea");
+        el.value = text;
+        el.setAttribute("readonly", "");
+        el.style.position = "absolute";
+        el.style.left = "-9999px";
+        document.body.appendChild(el);
+        el.select();
+        var ok = false;
+        try { ok = document.execCommand("copy"); } catch(e) { ok = false; }
+        document.body.removeChild(el);
+        settle(ok);
+    },
+
+    mcpServerUrl:function(path)
+    {
+        return window.location.origin + path;
+    },
+
+    openSearchView:function()
+    {
+        //-- narrow-viewport search button: below 602px the inline toolbar search box
+        //-- (.toolbar-search-bar) is hidden, so this takes the user to the search page,
+        //-- which has the full-width banner search input. With no query yet this renders
+        //-- the same view as loading /search directly - the library home with the banner
+        //-- box - so refresh and back/forward behave consistently. Clearing book drops the
+        //-- document view; the back button restores it via popstate. //-- SG
+        view.docApp.book = {};
+        view.docApp.searchMode = false;
+        view.docApp.mcpCatalogMode = false;
+        view.docApp.searchText = "";
+        view.docApp.altSearchText = "";
+        view.docApp.currentResultsSearchText = "";
+        view.docApp.libraryHomeViewProduct = null;
+        document.title = "Hornbill Documentation Search";
+        if(window.location.pathname !== "/search")
+        {
+            window.history.pushState(null, null, window.location.origin + "/search");
+        }
+        //-- focus the banner search box once Vue has painted the library/search layout
+        //-- (setTimeout runs after Vue's microtask render flush)
+        setTimeout(function(){ let inp = document.querySelector(".library-banner-hug input"); if(inp) inp.focus(); },0);
+    },
+
+    searchDocuments:function(inAltSearchText,inBoolFromPopState,ev,inBoolFromBookFilter)
+    {
+        if(!inAltSearchText) inAltSearchText = ""; //-- callers can legitimately pass nothing
+        //-- kept for the length-gate exit below, which may have to put the view back the way
+        //-- it found it (the title is rewritten before the gate is reached) //-- SG
+        let titleBeforeSearch = document.title;
+        //-- note: despite the name, validSearch is TRUE when the quote count is odd, i.e. when
+        //-- the search is INVALID - index.html uses it to show the unbalanced-quotes warning
+        view.docApp.validSearch = ((inAltSearchText.match(/"/g) || []).length  % 2 === 1);
+        let waitTime = 1;
+        let boolWasEnterKeyOrSearchButton = false;
+        if(ev)
+        {
+            ev.stopImmediatePropagation();
+            ev.preventDefault();
+            boolWasEnterKeyOrSearchButton = (ev.key==="Enter" || ev.type==="click"); //-- we will store url state on enter or search btn click
+        }
+
+        //-- clear any pending search
+        clearTimeout(view.searchTimeoutId);
+
+
+       
+
+        //-- if there is a http search inprogress then store this one to do once response is returned
+        view.docApp.nextSearchCriteria = {};
+        view.docApp.nextSearchCriteria.altSearchText = inAltSearchText;
+        view.docApp.nextSearchCriteria.boolFromPopState = inBoolFromPopState;
+        view.docApp.nextSearchCriteria.eventInfo = ev;
+        view.docApp.nextSearchCriteria.boolWasEnterKeyOrSearchButton = boolWasEnterKeyOrSearchButton;
+        
+        //-- do we have anything to search
+        view.docApp.searchMode = (inAltSearchText || view.docApp.searchText)?true:false;
+        
+        if(!view.docApp.searchMode)
+        {
+            document.title = "Hornbill Documentation";
+            //-- set url home index 
+            view.docApp.currentResultsSearchText = "";
+            view.docApp.searchTooShort = false;
+            hideSearchTooShortHint();
+
+            //-- set url to root (only if the current url is a search url)
+            if(window.location.href.indexOf("?q=") !== -1)
+            {
+                let urlToSet = window.location.origin + "/";
+                const url = new URL(urlToSet);
+                window.history.replaceState(null, null, url);
+            }
+            return;
+        }
+        document.title = "Hornbill Documentation Search";
+
+        //-- single-character queries never fetch: the server drops unquoted single-char
+        //-- terms (they can only return noise), so the round-trip per keystroke would buy
+        //-- an empty result set. Raw length check on purpose - a QUOTED single char ("e")
+        //-- is three characters and goes through, matching the server's phrase exemption.
+        //-- boolSearchInProgress may be true from a just-cancelled pending search, so put
+        //-- it back down or the results list stays dimmed //-- SG
+        if(inAltSearchText.trim().length === 1)
+        {
+            view.docApp.boolSearchInProgress = false;
+            //-- Returning without touching the view left whatever was on screen standing, and
+            //-- the header names currentResultsSearchText, not what is in the box: typing "qq"
+            //-- then backspacing showed "0 results for: qq" for a one-character query, and a
+            //-- single character typed after any earlier search showed that search's hits as
+            //-- though they matched. A first character showed nothing at all - no results, no
+            //-- header, no reason. Clear the previous answer and say why there is none. //-- SG
+            //-- A document is open (the toolbar search box is on every book page): a single
+            //-- character has nothing to show, so leave the document alone rather than half
+            //-- opening the search over it. searchMode was set above, and the book view is
+            //-- rendered off book.docId - which the gate never reaches the code that clears -
+            //-- so both panels were on screen at once, the article squeezed into the corner.
+            //-- No notice here: the box still holds what was typed, and destroying what the
+            //-- user is reading to say "keep typing" is the worse trade. //-- SG
+            if(view.docApp.book && view.docApp.book.docId)
+            {
+                view.docApp.searchMode = false;
+                view.docApp.searchTooShort = false;
+                //-- nothing on screen changes on this path, so pressing Enter looked like a dead
+                //-- key. Say why, next to the box that was typed in, and take it away again on its
+                //-- own - a hint the user has to dismiss is worse than the silence it replaces //-- SG
+                showSearchTooShortHint();
+                document.title = titleBeforeSearch;
+                return;
+            }
+
+            view.docApp.searchTooShort = true;
+            view.docApp.searchResponse = null;
+            view.docApp.searchResultFilteredItems = [];
+            view.docApp.currentResultsSearchText = "";
+            view.docApp.searchError = "";
+            view.docApp.searchDocTypeRescue = null;
+            view.docApp.searchBookRescue = null;
+            docTypeAutoWidenedForQuery = null;
+            resetFilteredProductsListCounters();
+            //-- the url described the results we just dropped, so it must not keep claiming them
+            if(window.location.href.indexOf("?q=") !== -1)
+            {
+                window.history.replaceState(null, null, window.location.origin + "/search");
+            }
+            return;
+        }
+
+        //-- past the length gate, so any "too short" notice belongs to a previous keystroke
+        view.docApp.searchTooShort = false;
+        hideSearchTooShortHint();
+
+        //-- searching same thing so leave
+        if(inAltSearchText===view.docApp.currentResultsSearchText && !boolWasEnterKeyOrSearchButton && !inBoolFromPopState && !inBoolFromBookFilter) return;
+
+        //-- set a wait time. The debounce exists to let a typing user finish their word -
+        //-- filter changes (doc type / book / audience radios and selects, which arrive as
+        //-- "change" events, not "click") are a completed intent, so they'd only be slowed
+        //-- by it: the facet click already paid the full search round-trip, and the extra
+        //-- 250ms+ here was most of the perceived lag //-- SG
+        if(!boolWasEnterKeyOrSearchButton && !inBoolFromPopState && !inBoolFromBookFilter)
+        {
+            waitTime = calculateSearchWaitTimeBasedOnQueryText(inAltSearchText);
+            hslDocLog.log("SEARCH: SETTING FETCH DELAY: " + waitTime + "ms");
+        }
+
+        //-- Committed to the search view now, so drop the document here rather than inside the
+        //-- debounced callback below. The search panel renders off searchMode (set above) while
+        //-- the book panel renders off book.docId, so for the whole debounce + fetch the article
+        //-- was still mounted and shared the viewport with the search layout - the page visibly
+        //-- squeezed into the bottom-right corner until the results skeleton replaced it. The
+        //-- skeleton needs boolSearchInProgress, set immediately below, so the swap is one frame
+        //-- with nothing in between. //-- SG
+        if(view.docApp.book && view.docApp.book.docId) view.docApp.book = {};
+
+        view.docApp.boolSearchInProgress = true;
+        view.searchTimeoutId = setTimeout(function(altSearchText,boolFromPopState,boolWasEnterKeyOrSearchButton,srcEvent)
+        {
+            view.docApp.searchError = "";
+
+            resetFilteredProductsListCounters();
+
+            if(view.docApp.nextSearchCriteria)
+            {
+                altSearchText = view.docApp.nextSearchCriteria.altSearchText;
+                boolFromPopState =view.docApp.nextSearchCriteria.boolFromPopState;
+                boolWasEnterKeyOrSearchButton =view.docApp.nextSearchCriteria.boolWasEnterKeyOrSearchButton;
+                srcEvent =view.docApp.nextSearchCriteria.eventInfo;
+                
+                //-- log the fields, not a deep copy of the criteria object. copyObject is a
+                //-- JSON.parse(JSON.stringify()) round-trip and nextSearchCriteria holds eventInfo,
+                //-- a jQuery event - so this ran a full serialise per keystroke for output that is
+                //-- only read if someone calls hslDocLog.dump(), and it was one property away from
+                //-- throwing on a circular structure (target / originalEvent) inside the search
+                //-- callback, which would have aborted the search. //-- SG
+                hslDocLog.log("SEARCH: NEW CRITERIA DETECTED: There is new search criteria waiting before current http search request takes place....using new criteria",
+                    {altSearchText:altSearchText,boolFromPopState:boolFromPopState,boolWasEnterKeyOrSearchButton:boolWasEnterKeyOrSearchButton})
+                
+                view.docApp.nextSearchCriteria = null;
+            }
+
+
+            //-- user has typed in search
+            if(altSearchText)
+            {
+                //-- only search if search is different to current one
+                if(altSearchText===view.docApp.currentResultsSearchText && !boolWasEnterKeyOrSearchButton &&  !inBoolFromBookFilter)return;
+            }
+            else
+            {
+                //-- we did search on the main landing page - so clear search results and filters
+                view.docApp.searchResultFilteredItems = [];
+                view.docApp.searchResponse = null;
+                view.docApp.searchFilterBySpecificBookId = "";
+
+                //-- if search is empty then do nothing
+                if(!view.docApp.searchText)
+                {
+                    view.docApp.searchMode = false;
+                    view.docApp.mcpCatalogMode = false;
+                    view.docApp.currentResultsSearchText = "";
+                    view.docApp.boolSearchInProgress = false;
+                    return;
+                }
+            }
+
+            view.docApp.book = {};            
+            
+            //-- set url to search/or update search term
+            let urlToSet = window.location.origin + "/search";
+            let searchText = (altSearchText)?altSearchText:view.docApp.searchText;
+            
+            //-- clear small search box
+            view.docApp.searchText = "";
+
+            //-- so can show in # result for {{docApp.currentResultsSearchText}}
+            view.docApp.currentResultsSearchText = searchText;
+
+            //-- NOTE: the previous results are deliberately NOT cleared here. Emptying the array
+            //-- at request time unmounted the whole results list (its v-if tests length), so every
+            //-- query destroyed and rebuilt all 300 rows even when the new results were nearly the
+            //-- same. The list now stays mounted and dimmed until the response replaces it in one
+            //-- assignment; the header switches to "Searching for:" so nothing claims the old count
+            //-- belongs to the new query. Cleared on the no-search and error paths instead. //-- SG
+            if(searchText)
+            {                  
+                //-- include bid if one is selected, and the audience filter when the
+                //-- (internal-only) picker has a value //-- SG
+                //-- restore the default once the query moves on from the one that was
+                //-- auto-widened, so the content-type filter keeps working for the next
+                //-- search instead of staying open because one query needed everything
+                if(docTypeAutoWidenedForQuery !== null && searchText !== docTypeAutoWidenedForQuery)
+                {
+                    view.docApp.searchDocTypeFilter = docTypeUserDefaultFilter();
+                    docTypeAutoWidenedForQuery = null;
+                }
+
+                let searchterm=encodeQueryData(buildSearchQueryParams(searchText));
+                urlToSet += "?" + searchterm;
+                
+                hslDocLog.log("SEARCH: TRIGGER: perform search on ", urlToSet)
+
+                //-- we will keep trak of last response time for a search of this many words and length
+                let searchInfoKey = "s_w" + searchText.split(" ").length + "_l" + searchText.length;
+                arrSearchResponseTimes[searchInfoKey] = Date.now();
+
+                //-- supersede any request still in flight, then claim this id
+                if(searchAbortController) searchAbortController.abort();
+                searchAbortController = new AbortController();
+                let requestSeq = ++searchRequestSeq;
+
+                fetchJsonFile("_search?"+searchterm,{signal:searchAbortController.signal}).then(function(data)
+                {
+                    //-- a newer search has been issued since this one left - drop the response
+                    //-- rather than letting it overwrite fresher results. Deliberately does NOT
+                    //-- touch boolSearchInProgress: the newer request still owns that. //-- SG
+                    if(requestSeq !== searchRequestSeq)
+                    {
+                        hslDocLog.log("SEARCH: RESPONSE: discarded stale response (req " + requestSeq + " of " + searchRequestSeq + ")");
+                        return;
+                    }
+
+                    //-- No body, or one fetchJsonFile could not parse - it resolves null for a bad
+                    //-- JSON body rather than rejecting (item 20), so this lands in the SUCCESS
+                    //-- handler. Without this guard `data.query` threw here, and a throw inside
+                    //-- onFulfilled is not caught by the onRejected passed to the same .then(), so
+                    //-- the failure was silent and boolSearchInProgress stuck true - the spinner
+                    //-- never cleared and no error was shown. Same class as item 19. //-- SG
+                    if(!data)
+                    {
+                        hslDocLog.log("SEARCH: RESPONSE: no usable response body");
+                        view.docApp.searchResultFilteredItems = [];
+                        view.docApp.boolSearchInProgress = false;
+                        view.docApp.nextSearchCriteria = null;
+                        view.docApp.searchError = "Failed to search for books. The server search response is invalid";
+                        revealApp();
+                        return;
+                    }
+
+                    hslDocLog.log("SEARCH: RESPONSE: completed",data)
+                    if(data.query)
+                    {
+                        //-- telemetry only, and it picks apart the server's echoed query string. Any
+                        //-- change to that shape made [1] undefined and threw here, aborting the rest
+                        //-- of the handler - results never rendered and boolSearchInProgress stuck
+                        //-- true. Guarded so it can never take the render down with it. //-- SG
+                        try
+                        {
+                            let searchedText = data.query.split("MATCH '")[1].split("*' ORDER")[0];
+                            let searchTextKey = "s_w" + searchedText.split(" ").length + "_l" + searchedText.length;
+                            if(arrSearchResponseTimes[searchTextKey])
+                            {
+                                //-- store the overrall ms taken (also for word count)
+                                arrSearchResponseTimes[searchTextKey] = Date.now() - arrSearchResponseTimes[searchTextKey];
+                                arrSearchResponseTimesByWordCount[searchTextKey.split("_l")[0]] = arrSearchResponseTimes[searchTextKey];
+                                hslDocLog.log("SEARCH: RESPONSE: total UI http response time " +  arrSearchResponseTimes[searchTextKey] + "ms");
+                            }
+                        }
+                        catch(e)
+                        {
+                            hslDocLog.log("SEARCH: RESPONSE: could not parse echoed query for timing telemetry",data.query);
+                        }
+                    }
+                    
+                    view.docApp.boolSearchInProgress=false;
+                    view.docApp.nextSearchCriteria = null;
+                    view.docApp.searchResponse = data;
+
+                    //-- an unknown bid in the url must not dead-end the search with an
+                    //-- unexplained empty page. See evaluateBookFilterRescue //-- SG
+                    if(evaluateBookFilterRescue())
+                    {
+                        view.searchDocuments(view.docApp.altSearchText,false,null,true);
+                        return;
+                    }
+
+                    //-- the content-type filter defaults ON, so it must never turn a
+                    //-- findable answer into an empty page. See evaluateDocTypeRescue //-- SG
+                    if(evaluateDocTypeRescue())
+                    {
+                        view.searchDocuments(view.docApp.altSearchText,false,null,true);
+                        return;
+                    }
+
+                    var resultsFoundinCurrentFilteredBook = false;
+                    if(view.docApp.searchResponse.booksInfo && view.docApp.searchResponse.booksInfo.length)
+                    {
+                        //-- associate book title to each searched book
+                        for(let x=0;x<view.docApp.searchResponse.booksInfo.length;x++)
+                        {
+                            let book_info = getBookById(view.docApp.searchResponse.booksInfo[x].bookId);
+
+                            if(book_info !== undefined && book_info.title !== undefined) 
+                            {
+                                view.docApp.searchResponse.booksInfo[x].title = book_info.title;
+                                if(view.docApp.searchFilterBySpecificBookId && view.docApp.searchFilterBySpecificBookId===book_info.docId)
+                                {
+                                    resultsFoundinCurrentFilteredBook = true;
+                                    view.docApp.searchFilterBySpecificBookTitle = book_info.title; //-- set disaply title for filtered results by book
+                                    //-- for when user presses f5 - browser refresh for any reason
+                                    localStorage.setItem('hdocbook-last-filterbooktitle', book_info.title);
+                                    localStorage.setItem('hdocbook-last-filterbookid', book_info.docId);
+                                }
+                            }
+                        }
+
+                        //-- alphabetical by display title for the Books filter list (server order
+                        //-- is relevance-ish and reads as random)
+                        sortBooksInfoByTitle();
+                    }
+
+                    if(view.docApp.searchResponse.results)
+                    {
+                        if(!resultsFoundinCurrentFilteredBook && view.docApp.searchFilterBySpecificBookId)
+                        {
+                            //-- the selected book has no results for this query, so it is absent from
+                            //-- booksInfo - show it as a selected zero-count entry, or the Books list
+                            //-- renders with NOTHING selected (not even All) and the user cannot tell
+                            //-- a book filter is active. Title resolution: the title stored when the
+                            //-- user picked the book, else the library (valid book, no matches), else
+                            //-- the raw bid - a pasted url with an unknown/mistyped bid shows the bad
+                            //-- id itself as the selected filter, which is the diagnostic //-- SG
+                            let dummyTitle = null;
+                            if(view.docApp.searchFilterBySpecificBookId===localStorage.getItem('hdocbook-last-filterbookid'))
+                            {
+                                dummyTitle = localStorage.getItem('hdocbook-last-filterbooktitle');
+                            }
+                            if(!dummyTitle)
+                            {
+                                let book_info = getBookById(view.docApp.searchFilterBySpecificBookId);
+                                dummyTitle = (book_info && book_info.title) ? book_info.title : view.docApp.searchFilterBySpecificBookId;
+                            }
+
+                            view.docApp.searchFilterBySpecificBookTitle = dummyTitle;
+
+                            //-- a zero-result response may carry no booksInfo at all
+                            if(!Array.isArray(view.docApp.searchResponse.booksInfo)) view.docApp.searchResponse.booksInfo = [];
+
+                            let dummyBook = {bookId:view.docApp.searchFilterBySpecificBookId,title:dummyTitle,foundCount:0};
+                            view.docApp.searchResponse.booksInfo.push(dummyBook);
+                            //-- keep the list alphabetical with the dummy slotted in place
+                            sortBooksInfoByTitle();
+                        }
+                        prepareSearchResultItems(view.docApp.searchResponse.results);
+                    }
+                    
+
+                    view.$nextTick(function()
+                    {
+                        //-- no rebinding needed: link clicks are handled by one delegated
+                        //-- handler on document, so freshly rendered result links just work
+                        revealApp();
+
+                        setTimeout(function()
+                        {
+                            if(view.docApp.currentResultsSearchText && !view.docApp.boolSearchInProgress)
+                            {
+                                //-- getSearchUrlLink() builds the same q/bid url this used to
+                                //-- construct inline (third copy of the same expression)
+                                let newUrlToSet = getSearchUrlLink();
+                                if( window.location.href!==newUrlToSet) window.history.pushState(null, null, newUrlToSet);
+                            }
+                        },1000);
+                        
+                    });
+            
+
+                },function(err)
+                {
+                    //-- an abort is us superseding our own request, not a failure - and a stale
+                    //-- rejection must not surface an error over newer results. //-- SG
+                    if(err && err.name === "AbortError") return;
+                    if(requestSeq !== searchRequestSeq) return;
+                    //-- results are no longer cleared at request time, so drop the previous ones
+                    //-- here rather than leaving them under an error message //-- SG
+                    view.docApp.searchResultFilteredItems = [];
+                    view.docApp.boolSearchInProgress = false;
+                    view.docApp.searchError = "Failed to search for books. The server search response is invalid";
+                    revealApp();
+                });
+            }
+            else
+            {
+                view.docApp.searchMode = false;
+                view.docApp.mcpCatalogMode = false;
+                view.docApp.boolSearchInProgress = false;
+
+                //-- show prompt to enter search criteria
+                view.$nextTick(function()
+                {
+                    revealApp();
+                });
+            }
+
+            //-- update browser url
+            if(!boolFromPopState || boolWasEnterKeyOrSearchButton)
+            {
+                const url = new URL(urlToSet);
+                window.history.pushState(null, null, url);
+            }
+
+        },waitTime,inAltSearchText,inBoolFromPopState,boolWasEnterKeyOrSearchButton,ev); //-- passing in params
+    },
+    loadLibraryBook:function(aBook,fromPopState,ev)
+    {
+        view.docApp.boolSearchInProgress = false;
+        view.docApp.loadingBookInfo = true;
+        if(ev)
+        {
+            //-- if a url that is part of this doc site then handle loading content inline else let link do whatever (i.e. its an external link)                
+            ev.stopImmediatePropagation();
+            ev.preventDefault();                
+        }
+
+        // Get hdocbook.json
+        //-- hide the current document while the next one loads. Was $(".HTL-doc").addClass
+        //-- ("hb-hidden"), which wrote to Vue-owned elements and also caught the MCP catalog
+        //-- wrapper and the inline toolbar - both .HTL-doc, neither intended. //-- SG
+        view.docApp.contentLoading = true;
+        
+
+        fetchJsonFile("_books/" + aBook.docId + "/hdocbook.json").then(function(data)
+        {
+            view.docApp.book = data;
+            view.docApp.title = data.title || "";
+            view.docApp.description = data.description || "";
+                      
+
+            view.docApp.loadingBookInfo = false; //-- move this here into timeout to avoid loading glitch that shows main landing page     
+
+            //-- now render out the nav menu
+            view.renderNavigation();
+
+            //-- This was a hard-coded setTimeout(...,200) "wait for Vue to render the nav".
+            //-- renderNavigation() is synchronous, so $nextTick is the correct primitive: it
+            //-- fires as soon as Vue has flushed the DOM patch instead of guessing, which
+            //-- takes a flat 200ms off every book open. Kept as $nextTick rather than dropped
+            //-- so the nav DOM is in place before content loading starts. //-- SG
+            view.$nextTick(function()
+            {
+                //-- title band is now rendered - centre the floating TOC button against it
+                positionTocMobileBtn();
+
+                //-- check if url is not root - in which case we need to load content for url
+                if(fromPopState)
+                {
+                    loadContentUrl(fromPopState,false,fromPopState);
+                }
+                else
+                {
+                    const loadUrl = new URL(window.location.href);                
+                    var initialLoadContentHref = removeStartingSlash(loadUrl.pathname.replace(window.location.origin+"/",""));
+                    //if(initialLoadContentHref==="")initialLoadContentHref = findFirstClickableBookLink(initialLoadContentHref);
+                    let foundLinkHref = findFirstClickableBookLink(initialLoadContentHref);
+                    if(foundLinkHref)
+                    {
+                        //-- find the link we are going to show and make sure parent/s are set to .expand=true
+                        loadContentUrl(foundLinkHref + loadUrl.hash,false,fromPopState);
+                    }
+                    else
+                    {
+                        hslDocLog.log("could not find matching link or parent link in navigation menu");
+                        loadContentUrl(initialLoadContentHref + loadUrl.hash,false,fromPopState);
+                    }
+                }
+            });
+        });
+    }
+};
+
+ 
+ //--
+ //-- user clicked back or forwards
+ var currentPopState = null;
+ window.addEventListener('popstate', function (event) 
+ {
+    const loadUrl = new URL(event.target.location.href);
+    //loadContentUrl(loadUrl.pathname + loadUrl.hash,{},false,true);
+    currentPopState = event;
+    loadLibraryOrBookFromCurrentUrl(loadUrl.pathname + loadUrl.hash)    
+});
+
+
+//--- GLOBAL FUNCTIONS
 
-//-- Mermaid theme lives in js/mermaid-theme.json — the SINGLE source shared
-//-- with the server-side PDF SVG bake (hdoc build reads the same file). Fetch
-//-- failure falls back to the plain base theme rather than blocking rendering.
-function hbFetchMermaidTheme() {
-	return fetch("js/mermaid-theme.json") //-- resolves against <base href>
-		.then((r) => (r.ok ? r.json() : null))
-		.catch(() => null);
+//-- vertically centre the floating in-page TOC button (.toc-mobile-btn) against the book title
+//-- band. The button is position:fixed inside .DocContent, so CSS alone cannot centre it on a
+//-- band whose height varies with viewport width and title wrapping - measure the band and
+//-- publish the result as a CSS variable consumed by content.css (tablet range only; the <=602px
+//-- rules dock the button bottom-right and ignore the variable). Called after book render and on
+//-- window resize. 48 = the button's CSS height. //-- SG
+function positionTocMobileBtn()
+{
+    let band = document.querySelector(".title-band");
+    if(band && band.offsetHeight)
+    {
+        let bandRect = band.getBoundingClientRect();
+        let btnTop = Math.round(bandRect.top + ((bandRect.height - 48) / 2));
+        document.documentElement.style.setProperty("--toc-mobile-btn-top", btnTop + "px");
+    }
+    else
+    {
+        //-- no band (library view) - fall back to the stylesheet default
+        document.documentElement.style.removeProperty("--toc-mobile-btn-top");
+    }
 }
+window.addEventListener("resize", positionTocMobileBtn);
+
+//-- Minimum debounce between keystrokes and the search request going out. The adaptive
+//-- times below learn from server response times, but never go below this: with hybrid
+//-- (keyword + semantic) search each request costs the server an AI inference, so firing
+//-- on nearly every keystroke wastes server work for results the next keystroke replaces.
+//-- 250ms sits under the perceived-as-instant threshold while letting a steady typer
+//-- finish the word. //-- SG
+const SEARCH_DEBOUNCE_MIN_MS = 250;
+
+function calculateSearchWaitTimeBasedOnQueryText(strSearchQuery)
+{
+    let arrWords = strSearchQuery.split(" ");
+    //-- check length of each word
+    let waitTime = 0;
+
+    //-- do we have a last wait time for a similar search word length and text length?
+    let searchInfoKey = "s_w" + arrWords.length + "_l" + strSearchQuery.length;
+    let wordCountSearchKey = "s_w" + arrWords.length;
+    //-- do we have exact match (same word count and same number of chars?)
+    if(arrSearchResponseTimes[searchInfoKey] && arrSearchResponseTimes[searchInfoKey]<1000)
+    {
+        //-- lets just use this + 20ms, but never below the floor
+        return Math.max(arrSearchResponseTimes[searchInfoKey] + 20, SEARCH_DEBOUNCE_MIN_MS);
+    }
+    delete arrSearchResponseTimes[searchInfoKey];
+
+    if(arrSearchResponseTimesByWordCount[wordCountSearchKey] && arrWords.length>1 && arrSearchResponseTimesByWordCount[wordCountSearchKey]<1000)
+    {
+        return Math.max(arrSearchResponseTimesByWordCount[wordCountSearchKey] + 20, SEARCH_DEBOUNCE_MIN_MS);
+    }
+
+    delete arrSearchResponseTimesByWordCount[wordCountSearchKey];
+    
+    //-- we have no reference to use
+    //-- set initial waittime based of search text length
+    switch(strSearchQuery.length) {
+        case 0:
+        case 1: 
+        case 2: 
+            waitTime = 400;
+            break;
+        case 3: 
+            waitTime = 300;
+            break;
+        case 4: 
+            waitTime = 200;
+            break;
+        case 5: 
+            waitTime = 100;
+            break;
+        default:
+            waitTime = 50;
+            break;
+    }
+
+    //-- now divide by number of words, for example searching for "apple" takes longer than searching for "ap ple";
+    waitTime = waitTime / arrWords.length;
+    if(waitTime<SEARCH_DEBOUNCE_MIN_MS)waitTime=SEARCH_DEBOUNCE_MIN_MS;
+
+    return waitTime;
+
+}
+
+//-- copyObject() lived here. Its only caller was the per-keystroke search log (item 13), which
+//-- now logs the three fields it wanted rather than deep-copying a jQuery event. //-- SG
+
+function encodeQueryData(data) {
+    const ret = [];
+    for (let d in data)
+      ret.push(encodeURIComponent(d) + '=' + encodeURIComponent(data[d]));
+    return ret.join('&');
+ }
+function removeTrailingSlash(str) {
+    return str.endsWith('/') ? str.slice(0, -1) : str;
+} 
+function removeStartingSlash(str) {
+    return str.startsWith('/') ? str.slice(1, str.length) : str;
+
+    //if(linkRef.indexOf("/")===0)linkRef = linkRef.replace("/","");
+} 
+
+function urlGetParam(locationSearch,paramName)
+{
+    let params = new URLSearchParams(locationSearch);
+    return params.get(paramName); 
+}
+
+function toSeoUrl(url) {
+
+    return url.toString()               // Convert to string
+        .normalize('NFD')               // Change diacritics
+        .replace(/[\u0300-\u036f]/g,'') // Remove illegal characters
+        .replace(/\s+/g,'-')            // Change whitespace to dashes
+        .toLowerCase()                  // Change to lowercase
+        .replace(/&/g,'-and-')          // Replace ampersand
+        .replace(/[^a-z0-9\-]/g,'')     // Remove anything that is not a letter, number or dash
+        .replace(/-+/g,'-')             // Remove duplicate dashes
+        .replace(/^-*/,'')              // Remove starting dashes
+        .replace(/-*$/,'');             // Remove trailing dashes
+}
+
+
+function getMeta(metaName) {
+    const metas = document.getElementsByTagName('meta');
+  
+    for (let i = 0; i < metas.length; i++) {
+      if (metas[i].getAttribute('name') === metaName) {
+        return metas[i].getAttribute('content');
+      }
+    }
+  
+    return '';
+  }
+
+function getAnchorFromHash(strHash,strHasClass)
+{
+    try{
+        let strSelector = toSeoUrl(strHash.replace("#",""));
+        if (strSelector === '') return null;
+        if(strHasClass)strSelector += "." + strHasClass;
+
+        //-- returns a DOM element (was a jQuery collection, so the caller unwrapped [0])
+        return document.querySelector("#"+strSelector) || null;
+    }
+    catch(e)
+    {
+        hslDocLog.log("Get document anchor element by hash failed ["+strHash+"]",e);
+        return null;
+    }
+
+}
+
+//-- Resolve a hash fragment to a DOM element on the current page. Tolerant of headings that
+//-- were never assigned an id: generateTableOfContentsFromDoc() only gives ids to H2/H3 that
+//-- have a text label and no .no-auto-anchor class, so links to H1/H4-H6 (or those headings)
+//-- would otherwise fail and dump the reader at the top of the page. As a last resort we scan
+//-- every heading, match on its slugified text, and back-fill the id so scroll + future lookups
+//-- work. Returns a DOM element or null. //-- SG
+function resolveAnchorElement(strHash)
+{
+    try
+    {
+        let frag = (strHash || "").replace(/^#/, "");
+        if(!frag) return null;
+        let slug = toSeoUrl(frag);
+        if(!slug) return null;
+
+        //-- 1) direct id match (SEO slug, or an id the author set verbatim)
+        let ele = document.getElementById(slug) || document.getElementById(frag);
+        if(ele) return ele;
+
+        //-- 2) legacy <a name="..."> / [name] targets
+        let named = document.querySelector('[name="' + ((window.CSS && CSS.escape) ? CSS.escape(frag) : frag) + '"]');
+        if(named) return named;
+
+        //-- 3) match any heading by its slugified text and back-fill the id
+        let container = vueContentContainer() || document;
+        let headings = container.querySelectorAll("h1,h2,h3,h4,h5,h6");
+        for(let i=0; i<headings.length; i++)
+        {
+            //-- native .trim(): jQuery 4 removed $.trim() //-- SG
+            if(toSeoUrl(headingText(headings[i]))===slug)
+            {
+                if(!headings[i].id) headings[i].id = slug;
+                return headings[i];
+            }
+        }
+        return null;
+    }
+    catch(e)
+    {
+        hslDocLog.log("Resolve document anchor element by hash failed ["+strHash+"]",e);
+        return null;
+    }
+}
+
+//-- Accessibility fixes over freshly-injected article content. These used to live inside
+//-- listenForHrefClicks(), so they re-scanned the whole document every time a click handler
+//-- was rebound - several times per navigation - even though the DOM they fix only changes
+//-- when new content is injected. Note the attribute-substring selectors below cannot use
+//-- any index and walk every element, so keeping this to once per page matters. //-- SG
+function applyContentAccessibilityFixes()
+{
+    //-- Accessibility fix: add aria-label and id to menu popper anchors
+    document.querySelectorAll(".documentation-menu-popper").forEach(function(el,index) {
+        if(!el.getAttribute("aria-label")) {
+            el.setAttribute("aria-label", "Document options menu");
+            el.setAttribute("id", "doc-menu-popper-" + index);
+            el.querySelectorAll("i").forEach(function(i){ i.setAttribute("aria-hidden","true"); });
+        }
+    });
+
+    //-- Accessibility fix: add aria-label to edit links (GitHub pencil icon)
+    document.querySelectorAll(".toolbar-action").forEach(function(link) {
+        let href = link.getAttribute("href") || "";
+        if(href.includes("github.com") && link.querySelector(".bi-pencil") && !link.getAttribute("aria-label")) {
+            link.setAttribute("aria-label", "Edit this page on GitHub");
+            link.querySelectorAll("i").forEach(function(i){ i.setAttribute("aria-hidden","true"); });
+        }
+    });
+
+    //-- Accessibility fix: override inline gray colors for WCAG AAA compliance
+    var isDarkMode = document.documentElement.classList.contains('dark');
+    var accessibleGray = isDarkMode ? "#C4C4C4" : "#525252"; /* C4C4C4 = 7.5:1 on #242424 */
+    document.querySelectorAll("[style*='color: gray'], [style*='color:gray'], [style*='color: rgb(82'], [style*='color:rgb(82']").forEach(function(el) {
+        el.style.color = accessibleGray;
+    });
+}
+
+//-- Trap link clicks so we can cancel them and load content inline instead.
+//-- Bound ONCE on document as a delegated handler by bindDelegatedLinkHandler() below.
+//-- It used to be attached directly to every matching element and torn down/rebound on
+//-- every content injection - thousands of unbind/bind cycles per navigation on a large
+//-- API reference page - which is also why every code path that injected markup had to
+//-- remember to re-run the binder. Delegation removes that constraint entirely: anchors
+//-- created later (by Vue, by the tab strip, by anything) are handled with no rebinding.
+//--
+//-- `this` is still the matched element, so the body is unchanged from the bound version.
+//-- Ordering note: Vue's own @click handlers sit directly on their elements and therefore
+//-- run first now. The ones that matter (loadLibraryBook, searchDocuments) call
+//-- stopImmediatePropagation(), so they still suppress this handler - more reliably than
+//-- before, when it came down to which handler happened to be registered first. //-- SG
+function handleDocumentLinkClick(ev)
+{
+        let ele =  this;
+        ///hslDocLog.log("OnAClick: ", ele.getAttribute("href"));
+
+        //-- clicked the header - so get teh child link
+        if(ele.tagName==="H2" || ele.tagName==="H3") 
+        {
+            ele = ele.querySelector(".header-anchor");
+        }
+
+        if(ele && ele.href)
+        {
+            //hslDocLog.log("XXX: ", ele.getAttribute("href"));
+            const checkUrl = new URL(ele.href);
+
+            //-- same-page fragment link (raw href starts with #). Because <base href> is the
+            //-- site root, a bare "#anchor" resolves ele.href to the site root + hash (not the
+            //-- current page), so the book-loading logic below can't detect it. Handle it here:
+            //-- just scroll to the matching anchor on the current page. //-- SG
+            let rawHref = ele.getAttribute("href");
+            if(rawHref && rawHref.charAt(0) === "#")
+            {
+                ev.stopImmediatePropagation();
+                ev.preventDefault();
+                let anchorEle = resolveAnchorElement(rawHref);
+                if(anchorEle)
+                {
+                    GotoAndHighlightAnchorContent(anchorEle, false); //-- false = also run border highlight animation, like a direct anchor visit
+                    let currUrl = new URL(document.location.href);
+                    currUrl.hash = rawHref;
+                    if(currUrl.href !== document.location.href) window.history.pushState(null, null, currUrl); //-- add state so back button works
+                }
+                return false;
+            }
+
+            //-- clicking on a hash tag header link element - so jsut scroll to element
+            if(checkUrl.href===siteBaseLocation)
+            {
+                //-- we want to go to home page
+            }
+            else if(checkUrl.origin +"/"===siteBaseLocation && ele.getAttribute("target")!=="_blank")
+            {
+                
+                //-- if a url that is part of this doc site then handle loading content inline else let link do whatever (i.e. its an external link)
+                ev.stopImmediatePropagation();
+                ev.preventDefault();
+
+                //-- a search result click always loads its book, whatever the url shape - this
+                //-- test used to be duplicated token-for-token inside both arms of the anchor
+                //-- check below, so it is hoisted in front of it //-- SG
+                if(ele.classList.contains("searchresult-href"))
+                {
+                    //-- we are loading a search result from a book
+                    let loadBookId = ele.getAttribute("bookid");
+                    hslDocLog.log("Search Result Click : Load Book ("+loadBookId+") Then ContentURL: ", ele.getAttribute("href"));
+
+                    //-- remember search history
+                    storeUrlInHistory(getSearchUrlLink());
+
+                    //-- now set new url for doc we want to load
+                    storeUrlInHistory(ele.getAttribute("href"));
+
+                    view.docApp.searchMode = false;
+                    view.docApp.mcpCatalogMode = false;
+                    view.loadLibraryBook({docId:loadBookId},ele.getAttribute("href"));
+                    return false;
+                }
+
+                //-- do we need to scroll into view element on this page
+                //-- add fix make use url clicked on is same path as current one
+                let eleAnc = (checkUrl.pathname===document.location.pathname && checkUrl.hash)?getAnchorFromHash(checkUrl.hash,"faq-toc-item"):null;
+                if(eleAnc)
+                {
+                    GotoAndHighlightAnchorContent(eleAnc,true);
+                    if(checkUrl.pathname==="/")
+                    {
+                        //-- going to element on current page so just update current browser url with new #
+                        let currUrl = new URL(document.location.href);
+                        currUrl.hash=checkUrl.hash;
+                        if(currUrl.href!==document.location.href) window.history.pushState(null, null, currUrl); //-- user has clicked a link so we want to add state to history so we can click back
+                    }
+                    else if(ele.href!==document.location.href)
+                    {
+                        window.history.pushState(null, null, ele.href); //-- user has clicked a link so we want to add state to history so we can click back
+                    }
+                }
+                else
+                {
+                    //-- we need to check if the bookId is the same as current one -if it is not then need to do a full load
+                    let targetUrl = checkUrl.href.replace("/_books/","/");
+                    let targetBookId = targetUrl.replace(checkUrl.origin +"/","").split("/",1)[0];
+                    let currentBookId = document.location.href.replace(document.location.origin +"/","").split("/",1)[0];
+                    if(targetBookId==currentBookId)
+                    {
+                        //-- load content inline - no need to change book
+                        hslDocLog.log("LoadContentURL: ", targetUrl);
+                        loadContentUrl(targetUrl,false,false);
+                    }
+                    else
+                    {
+                        //-- load new book
+                        hslDocLog.log("Load new book ("+targetBookId+") URL : ", targetUrl);
+                        findBookByIdAndLoad(targetBookId,targetUrl);
+
+                    }
+                }
+                return false;
+            }
+            else
+            {
+                //-- if not part of this website then always open in new tab as considered an external site
+                ele.setAttribute("target","_blank");
+            }
+        }
+}
+
+//-- Attach the single delegated click handler. Called once from intialiseApp().
+var boolDelegatedLinkHandlerBound = false;
+function bindDelegatedLinkHandler()
+{
+    if(boolDelegatedLinkHandlerBound) return;
+    boolDelegatedLinkHandlerBound = true;
+    document.addEventListener("click",function(ev){
+        //-- native equivalent of jQuery's delegated .on(selector,...): find the nearest matching
+        //-- ancestor of the event target and invoke the handler with `this` set to it, which is
+        //-- what the handler body reads. //-- SG
+        let matched = ev.target && ev.target.closest ? ev.target.closest("a, h2.faq-toc-item, h3.faq-toc-item") : null;
+        if(matched) handleDocumentLinkClick.call(matched,ev);
+    });
+}
+
+var lastSavedUrl = window.location.href;
+function storeUrlInHistory(strUrl)
+{
+    if(strUrl!==lastSavedUrl) 
+    {
+        window.history.pushState(null, null, strUrl);
+        lastSavedUrl = strUrl;
+    }
+}
+
+//-- The one place the /search query params are assembled, for BOTH the _search request and
+//-- the browser url, so the two can never disagree. They did: this used to build q/bid only
+//-- while searchDocuments built q/bid/audience/dt, and the delayed pushState in the response
+//-- handler then overwrote the correct url with the short one - a filtered search could not
+//-- be copied, bookmarked or back-buttoned, and popstate (which does read dt/audience) had
+//-- nothing to restore. Add any new facet here, not at a call site. //-- SG
+function buildSearchQueryParams(searchText)
+{
+    let queryParams = {q:searchText};
+    if(view.docApp.searchFilterBySpecificBookId) queryParams.bid = view.docApp.searchFilterBySpecificBookId;
+    if(view.docApp.showAudienceFilter && view.docApp.searchAudienceFilter) queryParams.audience = view.docApp.searchAudienceFilter;
+    if(view.docApp.searchDocTypeFilter) queryParams.dt = view.docApp.searchDocTypeFilter;
+    return queryParams;
+}
+
+//-- based on current search criteria return what the window url would be
+function getSearchUrlLink()
+{
+    let urlToSet = window.location.origin + "/search";
+    let searchText = view.docApp.currentResultsSearchText;
+    if(searchText)
+    {
+        urlToSet += "?" + encodeQueryData(buildSearchQueryParams(searchText));
+    }
+    return urlToSet;
+}
+
+
+//-- getProductFamilyCount() lived here. Its only caller, resetFilteredProductsListCounters(),
+//-- now builds one Map of the counts instead of rescanning productFamiliesInfo per product. //-- SG
+
+function resetCheckedProducts()
+{
+    for(let x=0;x<view.docApp.products.length;x++)
+    {
+        view.docApp.products[x].checked=false;
+    }    
+}
+function resetFilteredProductsListCounters()
+{
+    //-- one pass over productFamiliesInfo instead of getProductFamilyCount() rescanning it per
+    //-- product //-- SG
+    let familyCounts = new Map();
+    if(view.docApp.searchResponse && view.docApp.searchResponse.productFamiliesInfo)
+    {
+        let productFamiliesInfo = view.docApp.searchResponse.productFamiliesInfo;
+        for(let x=0;x<productFamiliesInfo.length;x++) familyCounts.set(productFamiliesInfo[x].productFamilyId,productFamiliesInfo[x].foundCount);
+    }
+
+    view.docApp.searchFilteredProducts["unknown"] = {checked:false,returnedCount:0};
+    for(let x=0;x<view.docApp.products.length;x++)
+    {
+        let strProductID = view.docApp.products[x].id;
+        if(!view.docApp.searchFilteredProducts[strProductID])
+        {
+            view.docApp.searchFilteredProducts[strProductID] = {};
+        }
+        view.docApp.searchFilteredProducts[strProductID].checked = view.docApp.products[x].checked || false;
+        view.docApp.searchFilteredProducts[strProductID].returnedCount = familyCounts.get(strProductID) || 0;
+    }
+}
+
+function updateBooksEnableDisableStateBasedOnFilteredProducts(checkedProdArray)
+{
+    //-- booksInfo is a field on the server's search response, so treat it as optional rather than
+    //-- assuming every response carries one //-- SG
+    if(!view.docApp.searchResponse || !view.docApp.searchResponse.booksInfo) return;
+
+    //-- only enable/disable books filter options depending on if book.productFamilyId is one of the checked products
+    view.docApp.searchResponse.booksInfo.forEach( function(aBook){
+        if(checkedProdArray.length)
+        {
+            aBook.productFilterDisable = true;
+            //-- one or more products checked so only enable books that match checked products
+            checkedProdArray.forEach(function(aProductId)
+            {
+                //-- this book belongs to a product family that is checked so enable it's selection
+                if(view.docApp.searchFilteredProducts[aProductId] && view.docApp.searchFilteredProducts[aProductId].checked && aBook.productFamilyId===aProductId)aBook.productFilterDisable = false;
+            });
+        }
+        else
+        {
+            aBook.productFilterDisable = false;
+        }
+    });
+
+
+
+}
+
+//-- Books filter list order - alphabetical, case-insensitive, by display title (bookId fallback
+//-- covers entries whose title did not resolve from the library) //-- SG
+function sortBooksInfoByTitle()
+{
+    if(!view.docApp.searchResponse || !Array.isArray(view.docApp.searchResponse.booksInfo)) return;
+    view.docApp.searchResponse.booksInfo.sort(function(a,b)
+    {
+        return (a.title || a.bookId || "").localeCompare(b.title || b.bookId || "", undefined, {sensitivity:"base"});
+    });
+}
+
+function prepareSearchResultItems(arrSearchResults)
+{
+    let checkedProdArray = getCheckedProductFilterArray();
+    resetFilteredProductsListCounters();
+    updateBooksEnableDisableStateBasedOnFilteredProducts(checkedProdArray);
+    
+
+
+    
+    //hslDocLog.log(view.docApp.searchFilteredProducts)
+    //-- built locally and assigned once at the end: pushing onto the reactive array fired 300
+    //-- separate reactive triggers, and left the model briefly empty part-way through. //-- SG
+    let filteredItems = [];
+    for(let x=0;x<arrSearchResults.length;x++)
+    {
+        //-- if we don't have a title get it from content ?? bit flakey
+        if(!arrSearchResults[x].title)
+        {
+            arrSearchResults[x].title = arrSearchResults[x].content.split("\n\n",1)[0];
+        }
+        
+        //-- create link from url (remove the index.html)
+        arrSearchResults[x].url = arrSearchResults[x].url.replace("/index.html","");
+        
+        //-- Replace snippet highlights. The snippet is rendered with v-html (the only way to
+        //-- show the <mark> highlights), and doc content can contain literal HTML - example
+        //-- code, event handlers - so it MUST be escaped first or it executes in the searcher's
+        //-- browser (stored XSS). Escape everything, then turn the plain-text highlight markers
+        //-- into the only tags allowed through.
+        //-- Once per record only: this function re-runs over the SAME response array on every
+        //-- product/book filter click, and escaping is not idempotent - a second pass turned
+        //-- the first pass's <mark> tags into visible "&lt;mark&gt;" text, worse each click,
+        //-- until a fresh search replaced the records. //-- SG
+        if(!arrSearchResults[x].content)arrSearchResults[x].content = "";
+        if(!arrSearchResults[x].contentPrepared)
+        {
+            arrSearchResults[x].content = arrSearchResults[x].content
+                .replaceAll('&','&amp;').replaceAll('<','&lt;').replaceAll('>','&gt;').replaceAll('"','&quot;').replaceAll("'",'&#39;')
+                .replaceAll('[hb_search_highlight]', '<mark class="highlight">').replaceAll('[/hb_search_highlight]', '</mark>');
+            arrSearchResults[x].contentPrepared = true;
+        }
+        
+        //-- increase count for product so we can show on search filters
+        let resProdId = arrSearchResults[x].productFamily || "unknown";
+        //-- nwj - 15th Oct 2024 - we have to do this manually as counts for products returned from search arent useful
+        //if(view.docApp.searchFilteredProducts[resProdId])view.docApp.searchFilteredProducts[resProdId].returnedCount++;
+
+        let includeInResults =  true;
+        
+        if(checkedProdArray.length) //-- are nay checked
+        {
+            if(view.docApp.searchFilteredProducts[resProdId])
+            {
+                includeInResults = view.docApp.searchFilteredProducts[resProdId].checked;
+            }
+            else
+            {
+                includeInResults = false;
+            }
+        }
+
+        //-- need to filter by checked book if have any checked
+        if(includeInResults && view.docApp.searchFilterBySpecificBookId)
+        {
+            includeInResults = (arrSearchResults[x].bookId === view.docApp.searchFilterBySpecificBookId);
+        }
+
+        if(includeInResults)
+        {
+            filteredItems.push(arrSearchResults[x]);
+        }
+    }
+
+    //-- one assignment, one render, and the list is replaced rather than emptied then refilled
+    view.docApp.searchResultFilteredItems = filteredItems;
+
+    //- if we have filter by products update the counts of books to 0 or # of results in books
+}
+
+function getCheckedProductFilterArray()
+{
+
+    
+
+    let retArray = [];
+    //-- now check if result is ok if we have any product filter set
+    for(let productId in view.docApp.searchFilteredProducts)
+    {
+        if(view.docApp.searchFilteredProducts[productId].checked)
+        {
+            retArray.push(productId);
+        }
+    }
+    return retArray;
+}
+
+//-- Lookup indexes for the two lists that get scanned per search response. getBookById was
+//-- called once per entry in booksInfo and scanned all of library.books each time - O(n*m) on
+//-- every keystroke-triggered search. The index is rebuilt lazily whenever the underlying array
+//-- is replaced (identity) or changes length, so no load path has to remember to invalidate it.
+//-- //-- SG
+let libraryBooksIndex = null;
+let libraryBooksIndexSource = null;
+function getLibraryBooksIndex()
+{
+    let books = (view.docApp.library && view.docApp.library.books) || [];
+    if(libraryBooksIndexSource !== books || !libraryBooksIndex || libraryBooksIndex.size !== books.length)
+    {
+        libraryBooksIndex = new Map();
+        for(let x=0;x<books.length;x++) libraryBooksIndex.set(books[x].docId,books[x]);
+        libraryBooksIndexSource = books;
+    }
+    return libraryBooksIndex;
+}
+
+function getBookById(strBookId)
+{
+    return getLibraryBooksIndex().get(strBookId);
+}
+
+//-- based on content url highlight match navigation menu item
+function highlightNavigationLinkFromUrl(matchLinkHref)
+{
+    
+    matchLinkHref = removeStartingSlash(matchLinkHref).split("#")[0]; //-- remvoe # link
+    document.querySelectorAll("a.DocLink").forEach(function(el){ el.classList.remove("active"); });
+    
+    let arrItems = document.querySelectorAll('a.DocLink');
+    
+    for(let x=0;x<arrItems.length;x++)
+    {       
+        let el = arrItems[x];
+        let checkUrl = null;
+        try{
+            checkUrl = new URL(el.href);
+        }
+        catch(e)
+        {
+            //hslDocLog.log("BAD navigation menu item found",el);
+        }
+
+        if(checkUrl)
+        {
+            let testCurrPath = removeStartingSlash(checkUrl.pathname);
+            if(testCurrPath===matchLinkHref || testCurrPath.indexOf(matchLinkHref)===0 || matchLinkHref.indexOf(removeStartingSlash(checkUrl.pathname) + "/")===0)
+            {
+                //-- exact match
+                el.classList.add("active")
+                if(!elementIsOnVisibleScreen(el))el.scrollIntoView();
+                return false;//break out
+            }
+        }
+    }
+}
+
+//-- create items to stick in toc from current loaded content
+//-- searches for H2,H3
+//-- Heading text for slugging, WITHOUT depending on the heading being rendered.
+//--
+//-- This used to read innerText in both callers. innerText is layout-dependent: it returns ""
+//-- for anything not currently rendered. That was safe only while the content reveal was a
+//-- synchronous class removal ($(".hb-hidden").removeClass). The reveal is now reactive state
+//-- (docApp.contentLoading), which Vue applies on the NEXT tick - and generateTableOfContents-
+//-- FromDoc runs on the tick before it, while the article is still visibility:hidden. Every
+//-- heading therefore read as empty: no ids assigned, so no #anchor deep links resolved and no
+//-- section highlight fired, and the table of contents came back empty so the right-hand nav
+//-- never rendered.
+//--
+//-- textContent has no layout dependency. It is equivalent for these headings because the only
+//-- thing appended to them is <a class="header-anchor"><i></i></a>, which carries no text.
+//-- Whitespace is collapsed so the slug matches what innerText produced. //-- SG
+function headingText(el)
+{
+    return ((el && el.textContent) || "").replace(/\s+/g," ").trim();
+}
+
+function generateTableOfContentsFromDoc()
+{
+    let container = vueContentContainer();
+    if(container)
+    {
+        const currUrl = new URL(document.location.href);
+        view.docApp.tableOfContents = [];
+        for (let i=2; i<=3; i++) 
+        {
+            let headers = container.getElementsByTagName("h"+i);
+            for (let j=0; j<headers.length; j++) 
+            {
+                //-- only process headers that do not have this class
+                if(!headers[j].classList.contains("no-auto-anchor")) headers[j].classList.add("faq-toc-item");
+            }
+        }
+
+        //-- track ids handed out on this page so two headings with the same text do not
+        //-- both claim the same anchor - deep links used to always land on the first. //-- SG
+        let usedHeadingIds = {};
+
+        var headersTocItem = container.getElementsByClassName("faq-toc-item");
+        for (let k = 0; k < headersTocItem.length; k++)
+        {
+            let item = headersTocItem[k];
+            let strLabel = headingText(item);
+
+            //-- Handle badge-only headings (accessibility fix)
+            if(!strLabel) {
+                let badge = item.querySelector("[class*='badge-endpoint-'], [class*='badge-user-'], [class*='badge-portal-']");
+                if(badge) {
+                    let badgeClass = badge.getAttribute("class") || "";
+                    let badgeText = "API Type";
+                    if(badgeClass.includes("internal")) badgeText = "Internal API";
+                    else if(badgeClass.includes("api")) badgeText = "API Endpoint";
+                    else if(badgeClass.includes("user")) badgeText = "User API";
+                    else if(badgeClass.includes("portal")) badgeText = "Portal API";
+                    badge.insertAdjacentHTML("beforeend","<span class='visually-hidden'>" + badgeText + "</span>");
+                    strLabel = badgeText;
+                }
+            }
+
+            if(strLabel)
+            {
+                let seoSafeId = toSeoUrl(strLabel); //-- will use SEO to set in url so can scroll to element from url
+
+                //-- de-dupe repeated heading text with a suffix counter
+                if(usedHeadingIds[seoSafeId] === undefined)
+                {
+                    usedHeadingIds[seoSafeId] = 0;
+                }
+                else
+                {
+                    usedHeadingIds[seoSafeId]++;
+                    seoSafeId = seoSafeId + "-" + usedHeadingIds[seoSafeId];
+                }
+
+                let linkUrl = currUrl.pathname + "#" + seoSafeId;
+                item.id = seoSafeId;
+
+                view.docApp.tableOfContents.push({ele:item,eleText:strLabel,tagName:item.tagName,href:linkUrl});
+
+                //-- add link icon to header (using seo id). Set the href on the appended anchor
+                //-- only - a find("a") here overwrote the href of any author-written link inside
+                //-- the heading as well. //-- SG
+                //-- built as an element rather than an HTML string. The label is heading text and
+                //-- was interpolated straight into markup, which is why it needed the quote-stripping
+                //-- hack beside it - and it would still have broken on an angle bracket.
+                //-- setAttribute escapes, so the hack goes with it. //-- SG
+                let anchorEl = document.createElement("a");
+                anchorEl.className = "header-anchor";
+                anchorEl.setAttribute("aria-label","Link to this section: " + strLabel);
+                anchorEl.setAttribute("href",linkUrl);
+                anchorEl.innerHTML = "<i class='bi bi-link' aria-hidden='true'></i>";
+                item.appendChild(anchorEl);
+
+            }
+        }
+    }
+}
+
+
+function formatBytes(val)
+{
+    //-- the old <1024 special case divided anyway and hard-coded 'KB', so a 500-byte file
+    //-- rendered as "0.49KB" and units[0] ('B') was unreachable //-- SG
+    var units = ['B', 'KB', 'MB', 'GB', 'TB'],
+        bytes = val,
+        i;
+
+    for (i = 0; bytes >= 1024 && i < units.length-1; i++) {
+        bytes /= 1024;
+    }
+
+    return bytes.toFixed(2) + units[i];
+}
+
+//-- one app per embedded component in the current article - see below for why
+let currentVueContentApps = [];
+function convertDocumentContentToVueSafeComponents(strHtml){
+
+    let vueComponentsSelector = "hdoc-approve"; //-- comma sep
+
+    //-- This used to compile the whole article as one app: blanket-apply v-pre to every element so
+    //-- authored {{...}} in prose stayed literal, then removeAttr("v-pre") from the embedded
+    //-- component tags to let those compile. That last step never actually worked. v-pre is
+    //-- INHERITED by the whole subtree, so clearing it on a descendant does nothing once an
+    //-- ancestor has stopped compilation - any embedded component that was not a direct child of
+    //-- .vue-document-body was silently inert. Verified against Vue 2.7.16 as well as Vue 3: a
+    //-- nested <hdoc-approve> rendered under neither. It was a live bug, not a migration casualty.
+    //--
+    //-- So we stop compiling the article altogether. Author HTML is left exactly as injected -
+    //-- which makes {{...}} in prose literal by construction rather than by directive, and keeps
+    //-- arbitrary author markup out of the template compiler - and we mount one small app per
+    //-- embedded component element instead. Those work at any nesting depth, which also fixes the
+    //-- inert-nested-component bug. //-- SG
+
+    //-- tear down last article's component apps (Vue 3 has no vm.$destroy(); teardown is an
+    //-- app-level operation, so hbVue.unmount looks up the app that owns the vm)
+    currentVueContentApps.forEach(function(vm){ hbVue.unmount(vm); });
+    currentVueContentApps = [];
+
+    let vueContainer = vueContentContainer();
+    if(!vueContainer) return;
+
+    vueContainer.innerHTML = strHtml;
+
+    vueContainer.querySelectorAll(vueComponentsSelector).forEach(function(el){
+
+        let componentName = el.tagName.toLowerCase();
+
+        //-- carry the element's attributes over as props. hdoc-approve declares no props, so they
+        //-- arrive on $attrs, which is where it already reads reference/assignee from.
+        let props = {};
+        for(let x=0;x<el.attributes.length;x++){
+            props[el.attributes[x].name] = el.attributes[x].value;
+        }
+
+        //-- mounting on the element itself keeps the DOM position; a render function means Vue
+        //-- ignores the element's innerHTML rather than treating it as a template. resolveComponent
+        //-- has to be called during render so it sees this app's component registry.
+        currentVueContentApps.push(hbMount({
+            render:function(){
+                return Vue.h(Vue.resolveComponent(componentName), props);
+            }
+        }, el));
+
+    });
+}
+//-- processing to do after book content has been injected into view
+//-- Mermaid client-side rendering config — mirrors hdoc-tools templates/mermaid-theme.yaml.
+//-- (PDFs are still rendered to SVG server-side by hdoc build; this is HTML-only.)
+var HB_MERMAID_CONFIG = {
+    startOnLoad: false,
+    theme: "base",
+    themeVariables: {
+        background: "transparent",
+        fontSize: "14px",
+        primaryColor: "#85D2FF",
+        primaryColorLight: "#85D2FF",
+        primaryColorDark: "#0065CB",
+        secondaryColor: "#219BFF",
+        secondaryColorLight: "#85D2FF",
+        secondaryColorDark: "#0C4C8C",
+        tertiaryColor: "#219BFF",
+        tertiaryColorLight: "#85D2FF",
+        tertiaryColorDark: "#0C4C8C",
+        lineColor: "#808080",
+        border1: "#606060",
+        textColor: "#A0A0A0",
+        titleColor: "#A0A0A0",
+        labelColor: "#404040",
+        loopTextColor: "#A0A0A0",
+        nodeTextColor: "#404040",
+        labelTextColor: "#404040",
+        pieSectionTextColor: "#404040",
+        nodeBorder: "#219BFF",
+        nodeBg: "transparent"
+    }
+};
 
 //-- Lazy-load the Mermaid bundle (~3MB) only when a page actually contains a
 //-- diagram. Resolves to window.mermaid, initialised once.
-let hbMermaidLoadPromise = null;
-function hbLoadMermaid() {
-	if (window.mermaid) return Promise.resolve(window.mermaid);
-	if (hbMermaidLoadPromise) return hbMermaidLoadPromise;
-	hbMermaidLoadPromise = hbFetchMermaidTheme().then(
-		(theme) =>
-			new Promise((resolve, reject) => {
-				const el = document.createElement("script");
-				el.src = "js/mermaid.min.js"; //-- resolves against <base href> (site root)
-				el.onload = () => {
-					try {
-						window.mermaid.initialize(
-							Object.assign(
-								{ startOnLoad: false },
-								theme || { theme: "base" },
-							),
-						);
-						resolve(window.mermaid);
-					} catch (e) {
-						reject(e);
-					}
-				};
-				el.onerror = () =>
-					reject(new Error("failed to load js/mermaid.min.js"));
-				document.head.appendChild(el);
-			}),
-	);
-	return hbMermaidLoadPromise;
+var hbMermaidLoadPromise = null;
+function hbLoadMermaid()
+{
+    if(window.mermaid) return Promise.resolve(window.mermaid);
+    if(hbMermaidLoadPromise) return hbMermaidLoadPromise;
+    hbMermaidLoadPromise = new Promise(function(resolve,reject)
+    {
+        var el = document.createElement("script");
+        el.src = "js/mermaid.min.js"; //-- resolves against <base href> (site root)
+        el.onload = function()
+        {
+            try{ window.mermaid.initialize(HB_MERMAID_CONFIG); resolve(window.mermaid); }
+            catch(e){ reject(e); }
+        };
+        el.onerror = function(){ reject(new Error("failed to load js/mermaid.min.js")); };
+        document.head.appendChild(el);
+    });
+    return hbMermaidLoadPromise;
 }
 
+//-- Render any not-yet-processed <pre class="mermaid"> blocks in the current doc.
+//-- mermaid.run() tags each node with data-processed, so re-running after a
+//-- navigation only renders freshly-injected diagrams.
 //-- Inject the spinner styles once. While a <pre class="mermaid"> has no
 //-- data-processed attr (set by mermaid.run() once rendered) we collapse its raw
 //-- source text and show a spinner in its place.
-function hbEnsureMermaidStyles() {
-	if (document.getElementById("hb-mermaid-style")) return;
-	const style = document.createElement("style");
-	style.id = "hb-mermaid-style";
-	style.textContent =
-		"pre.mermaid:not([data-processed]){font-size:0!important;line-height:0!important;min-height:140px;display:flex;align-items:center;justify-content:center;background:none!important;border:none!important;}" +
-		'pre.mermaid:not([data-processed])::after{content:"";width:32px;height:32px;border:3px solid rgba(33,155,255,.25);border-top-color:#219BFF;border-radius:50%;animation:hbMermaidSpin .8s linear infinite;}' +
-		"@keyframes hbMermaidSpin{to{transform:rotate(360deg);}}";
-	document.head.appendChild(style);
+function hbEnsureMermaidStyles()
+{
+    if(document.getElementById("hb-mermaid-style")) return;
+    var style = document.createElement("style");
+    style.id = "hb-mermaid-style";
+    style.textContent =
+        "pre.mermaid:not([data-processed]){font-size:0!important;line-height:0!important;min-height:140px;display:flex;align-items:center;justify-content:center;background:none!important;border:none!important;}" +
+        'pre.mermaid:not([data-processed])::after{content:"";width:32px;height:32px;border:3px solid rgba(33,155,255,.25);border-top-color:#219BFF;border-radius:50%;animation:hbMermaidSpin .8s linear infinite;}' +
+        "@keyframes hbMermaidSpin{to{transform:rotate(360deg);}}";
+    document.head.appendChild(style);
 }
 
-//-- Render any not-yet-processed <pre class="mermaid"> blocks in the current doc.
-//-- mermaid.run() tags each node with data-processed, so re-running after a
-//-- navigation only renders freshly-injected diagrams.
-function hbRenderMermaidDiagrams() {
-	hbEnsureMermaidStyles();
-	const nodes = document.querySelectorAll(
-		"#DocContent pre.mermaid:not([data-processed])",
-	);
-	if (!nodes.length) return;
-	//-- On any failure, mark nodes processed so the spinner stops (reveals source
-	//-- rather than spinning forever).
-	const reveal = (err) => {
-		hslDocLog.log("Mermaid render failed", err);
-		for (const n of nodes) n.setAttribute("data-processed", "true");
-	};
-	hbLoadMermaid()
-		.then((mermaid) => mermaid.run({ nodes }))
-		.catch(reveal);
-}
-
-//-- Warm the Mermaid bundle (~4.5MB) immediately on first script run so it's
-//-- downloading/parsing in the background regardless of whether THIS page has a
-//-- diagram. By the time the user reaches a diagram page it's ready and the swap
-//-- is instant. The bundle is served with a long cache header, so it downloads
-//-- once per browser, not once per page.
-hbEnsureMermaidStyles();
-hbLoadMermaid().catch(() => {});
-
-const docAppMethods = {
-	setSessionInfo: function (info) {
-		this.docApp.userSession = info;
-	},
-
-	showInlineDocumentList: function (ev) {
-		if (ev) {
-			ev.stopImmediatePropagation();
-			ev.preventDefault();
-		}
-		this.docApp.showInlineDocumentsMarkup = true;
-		this.$forceUpdate();
-	},
-	popupInlineDocument: function (ev, navSectionItem) {
-		if (ev) {
-			ev.stopImmediatePropagation();
-			ev.preventDefault();
-		}
-
-		$("#inlineModal").modal("show");
-		this.docApp.inlinePopupDocumentHref = navSectionItem.link;
-	},
-	switchViewTheme: () => {
-		if (ThemePreference)
-			document.documentElement.classList.remove(ThemePreference);
-
-		if (ThemePreference === "dark") {
-			ThemePreference = "light";
-		} else {
-			ThemePreference = "dark";
-		}
-
-		localStorage.setItem("hdocbook-theme-appearance", ThemePreference);
-		document.documentElement.classList.add(ThemePreference);
-	},
-	renderNavigation: function () {
-		this.docApp.navSections = this.docApp.book.navigation.items; //-- show be an array of nav groups
-	},
-	toggleMobileMenu: () => {
-		const isOpen = $(".mobile-menu-btn").data("isopen");
-		if (isOpen) {
-			$(".DocSidebar").removeClass("open");
-		} else {
-			$(".DocSidebar").addClass("open");
-		}
-		//-- store new mode
-		$(".mobile-menu-btn").data("isopen", !isOpen);
-	},
-	resetMobileMenu: (ev) => {
-		if (
-			ev &&
-			($(ev.srcElement).hasClass("mobile-menu-btn")[0] ||
-				$(ev.srcElement).closest(".mobile-menu-btn")[0])
-		) {
-			//-- skp as have clikc no menu btn
-		} else {
-			$(".mobile-menu-btn").data("isopen", false);
-			$(".DocSidebar").removeClass("open");
-		}
-	},
-};
+function hbRenderMermaidDiagrams()
+{
+    hbEnsureMermaidStyles();
+    var nodes = document.querySelectorAll("#DocContent pre.mermaid:not([data-processed])");
+    if(!nodes.length) return;
+    //-- On any failure, mark nodes processed so the spinner stops (reveals source
+    //-- rather than spinning forever).
+    var reveal = function(err){
+        hslDocLog.log("Mermaid render failed",err);
+        for(var i=0;i<nodes.length;i++) nodes[i].setAttribute("data-processed","true");
+    };
+    hbLoadMermaid().then(function(mermaid){ return mermaid.run({ nodes: nodes }); }).catch(reveal);
+}
 
+//-- Warm the Mermaid bundle (~3.5MB) in the background so that by the time the
+//-- user reaches a diagram page it's ready and the swap is instant. The bundle
+//-- should be served with a long cache header, so it downloads once per browser,
+//-- not once per page.
 //--
-//-- user clicked back or forwards
-window.addEventListener("popstate", (event) => {
-	const loadUrl = new URL(event.target.location.href);
-	loadContentUrl(loadUrl.pathname + loadUrl.hash, {}, false, true);
-});
+//-- Deferred to idle time: this used to fire at script-eval time, which put a
+//-- 3.5MB fetch + parse in direct competition with first render on every page,
+//-- the vast majority of which contain no diagram at all. requestIdleCallback
+//-- yields until the browser has nothing better to do; the timeout option caps
+//-- how long we'll wait on a permanently busy page. Safari <17 has no
+//-- requestIdleCallback, hence the setTimeout fallback. //-- SG
+//--
+//-- A diagram page does NOT depend on this: hbRenderMermaidDiagrams() calls
+//-- hbLoadMermaid() itself, and hbLoadMermaid() de-dupes on hbMermaidLoadPromise,
+//-- so an early navigation just promotes the same in-flight load.
+hbEnsureMermaidStyles();
+(function()
+{
+    var warm = function(){ hbLoadMermaid().catch(function(){}); };
+    if(window.requestIdleCallback) requestIdleCallback(warm,{timeout:5000});
+    else setTimeout(warm,3000);
+})();
+
+function postProcessBookContentRender(linkRef,frontmatterData,direct_BooksLinkRef)
+{
+        //-- do we have a pdf file dl to put into header
+        addPdfIconToHeader(direct_BooksLinkRef);        
+
+        //-- get document body mark up - make a clone and add pre-v to all the elements apart from known vue components
+        //-- test vue comps in doc
+        //jqContentContainer().prepend(`<hdoc-approve reference="1234" assignee="gerrysw"></hdoc-approve><hdoc-approve reference="1234" assignee="neilwj"></hdoc-approve>`)
+
+        let bodyEl = contentContainer();
+        convertDocumentContentToVueSafeComponents(bodyEl ? bodyEl.innerHTML : "");
+        if(bodyEl) bodyEl.innerHTML = ""; //-- empty old body
+
+        revealApp();
+
+        //-- Layout class on the content container, from frontmatter - the CSS uses it to size
+        //-- table/list views. One reactive value replaces an add/remove pair against a
+        //-- Vue-rendered element plus global.lastLayoutClass, which was a hand-maintained second
+        //-- copy of the same state purely so the previous class could be taken off again. Vue
+        //-- swaps it for us, so there is nothing to remember. //-- SG
+        view.docApp.layoutClass = frontmatterData.layout || "";
+
+        //--generate toc for all layouts that have h2/h3 
+        view.docApp.keepTocLayout = (frontmatterData.layout == "article-no-toc");
+        if(!frontmatterData.layout || frontmatterData.layout==="article" || frontmatterData.layout==="article-toc")
+        {
+            view.docApp.keepTocLayout = true;
+            generateTableOfContentsFromDoc();
+        }
+
+
+        //-- set actual html document title - based on the first h1 found in content
+        let docContentEl = document.getElementById("DocContent");
+        let firstH1 = docContentEl ? docContentEl.querySelector("h1") : null;
+        let docTitle = firstH1 ? firstH1.textContent.trim() : "";
+        let fullTitle = view.docApp.title;
+        if(docTitle){
+            fullTitle += " - " + docTitle;
+        }
+        else{
+            fullTitle += (view.docApp.frontmatterData && view.docApp.frontmatterData.title)? " - " + view.docApp.frontmatterData.title:"";
+        }
+        document.title = fullTitle;
+
+        //-- Set the canonical link - the url we want search engines to treat as authoritative.
+        //-- Reuse the existing tag rather than appending a new one. This used to append on every
+        //-- render, so a session that visited N articles left N <link rel="canonical"> tags in
+        //-- <head>, all but the first stale. Crawlers take the first one, so every article
+        //-- navigated to in-app advertised the canonical of whichever page was loaded first.
+        //--
+        //-- Also strip the query string and hash: ?theme=dark and #section are view state, not
+        //-- distinct documents, and leaving them in invites duplicate-content splitting. //-- SG
+        const canonicalUrl = document.location.origin + document.location.pathname;
+        let linkTag = document.head.querySelector('link[rel="canonical"]');
+        if(!linkTag)
+        {
+            linkTag = document.createElement('link');
+            linkTag.setAttribute('rel', 'canonical');
+            document.head.appendChild(linkTag);
+        }
+        linkTag.href = canonicalUrl;
+        hslDocLog.log("Set canonical link to",canonicalUrl);
+
+        //-- find any <tabs> and andd a bootstrap tab item strip
+       (document.getElementById("DocContent") || document).querySelectorAll("tabs").forEach((el) => {
+
+            let tabClass = el.getAttribute("tabstyle");
+            let tabMarkup = "<ul class='nav nav-tabs'>";
+            //-- for each tab we need to create a tab link
+            el.querySelectorAll("tab").forEach((aTab,idx) => {
+
+                let activeClass=(idx===0)?" active":"";
+                tabMarkup += `<li class='nav-item c-pointer' contentidx='${idx}'><span class='nav-link${activeClass}'>${aTab.getAttribute("name")}</span></li>`;
+
+                //-- hide the tab element if it is not the active one (first)
+                if(idx>0)aTab.classList.add("d-none");
+
+            });
+
+            tabMarkup += "</ul>";
+            //-- inject markup
+            el.insertAdjacentHTML("afterbegin",tabMarkup);
+            let tabStrip = el.querySelector(".nav.nav-tabs");
+            if(!tabStrip) return;
+            if(tabClass) tabStrip.classList.add(tabClass);
+
+            //-- Handlers bound on the strip we just built, NOT on every <li> descendant of <tabs>.
+            //-- The jQuery version used find("li"), which also matched list items inside the tab
+            //-- CONTENT: clicking one of those ran this handler with contentidx null, which cleared
+            //-- .active from every tab and highlighted none. //-- SG
+            tabStrip.querySelectorAll("li").forEach((li) => {
+                li.addEventListener("click",function()
+                {
+                    let contentIdx = this.getAttribute("contentidx");
+                    let tabsContainer = this.closest("tabs");
+                    if(!tabsContainer) return;
+                    let tabs = tabsContainer.querySelectorAll("tab");
+
+                    //-- hide other tab content and show this tabs content
+                    tabs.forEach(function(t){ t.classList.add("d-none"); });
+                    if(tabs[contentIdx-0]) tabs[contentIdx-0].classList.remove("d-none");
+
+                    //-- set clicked tab item to active
+                    tabsContainer.querySelectorAll(".nav-link").forEach(function(nl){ nl.classList.remove("active"); });
+                    this.querySelectorAll(".nav-link").forEach(function(nl){ nl.classList.add("active"); });
+                });
+            });
+        });
+
+
+        //-- do any code highlighting
+        if(hljs)
+        {
+            //-- scoped to the document view rather than the whole page. Same set of blocks in
+            //-- practice (both .document-body and .vue-document-body live under #DocContent), but
+            //-- it stops the scan walking the shell, the sidebar and the search UI on every
+            //-- render, and it means a code block added to the chrome later cannot be
+            //-- accidentally highlighted. //-- SG
+            let highlightRoot = document.getElementById("DocContent") || document;
+            highlightRoot.querySelectorAll('pre code').forEach((el) => {
+
+                //-- Don't hand Mermaid blocks to highlight.js. There is no mermaid grammar, so it
+                //-- logs "Could not find the language 'mermaid'" and no-highlights anyway; worse,
+                //-- the build-time variant of these blocks holds a pre-rendered <img> rather than
+                //-- text, and hljs 11 warns "code block includes unescaped HTML ... potentially
+                //-- serious security risk" for any element it is asked to highlight that contains
+                //-- child elements. Both were silent under hljs 9 but are pure console noise, and
+                //-- highlighting an image was never meaningful. //-- SG
+                if(el.classList.contains("language-mermaid") || el.querySelector("img")) return;
+
+                //-- Skip anything already highlighted. Content reaches this loop more than once per
+                //-- navigation (it is highlighted in .document-body, then the HTML is copied into
+                //-- .vue-document-body), and re-highlighting an element whose children are hljs's
+                //-- own <span class="hljs-*"> output is what triggers the "unescaped HTML"
+                //-- security warning in hljs 11. Test the class, not data-highlighted: the copied
+                //-- markup keeps the "hljs" class but not always the attribute. //-- SG
+                if(el.classList.contains("hljs") || el.getAttribute("data-highlighted") === "yes") return;
+
+                //-- highlightElement, not highlightBlock: deprecated in highlight.js 10 and
+                //-- REMOVED in 11, so the old name is now undefined. //-- SG
+                hljs.highlightElement(el);
+            });
+        }
+        else
+        {
+            hslDocLog.log("code highlighting js could not be loaded. code block highlighting will not be enabled");
+        }
+
+        //-- render any Mermaid diagrams client-side (lazy-loads the bundle)
+        hbRenderMermaidDiagrams();
+        
+        //-- show copy button by any code blocks
+        var options = {
+            contentSelector: ".injected-document-content",
+            // Delay in ms used for `setTimeout` before badging is applied
+            // Use if you need to time highlighting and badge application
+            // since the badges need to be applied afterwards.
+            // 0 - direct execution (ie. you handle timing
+            loadDelay:0,
+
+            // CSS class(es) used to render the copy icon.
+            copyIconClass: "bi bi-clipboard",
+            // CSS class(es) used to render the done icon.
+            checkIconClass: "bi bi-clipboard-check --htl-c-brand",
+
+            // intercept text copying - passed in text return text out
+            onBeforeCodeCopied: function(text) {                
+                return text;
+            }
+        };
+
+        highlightJsBadge(options);
+
+        
+        //-- THIS IS A SPECIAL CALL TO ANY TOP WHERE UI MIGHT EMBED DOC IN IFRAME - THIS ALLOWS THAT SRC TO RESIZE IFRAME 
+        if(parent && parent.postMessage)
+        {
+            let dataMessage = {};
+            dataMessage.type = "HornbillHelpDocLoaded";
+            dataMessage.info = {height: document.getElementById("DocContent").scrollHeight,
+                                width: document.getElementById("DocContent").scrollWidth,
+                                frontmatter:frontmatterData};
+
+            parent.postMessage(dataMessage,"*");
+        }
+
+        //-- highlight the nav link for this page and honour any #hash in the url. The same four
+        //-- statements used to be duplicated across both arms below; only the $nextTick wrapper
+        //-- differed. No updateCounter++ / $forceUpdate() in either path: the `expand = true`
+        //-- writes in expandNavParentSectionBySelectedLinkHref go through the reactive proxy and
+        //-- schedule the patch on their own, and nav "active" highlighting is applied with jQuery
+        //-- classes in this app, not a Vue binding, so it never depended on a forced repaint. //-- SG
+        let finishRender = function()
+        {
+            //-- find any navigation links that match url and highlight
+            applyContentAccessibilityFixes();
+            highlightNavigationLinkFromUrl(linkRef);
+
+            //-- scroll to element that matches hash (if have one)
+            //-- this is scrolling the content view
+            if(document.location.hash)
+            {
+                let gotoEle = resolveAnchorElement(document.location.hash);
+                if(gotoEle) GotoAndHighlightAnchorContent(gotoEle,false); //-- hash present = user targeted a section, so always run the highlight animation
+            }
+            else if(!bInitialPageLoad)
+            {
+                //-- no target anchor: present the new page from the top. The article is swapped
+                //-- inside the SAME scroll container, so the previous page's scroll offset
+                //-- survived the swap and in-book navigation showed new pages part-scrolled-down.
+                //-- Skipped on initial load/refresh - the browser owns scroll restoration there. //-- SG
+                let scrollableParent = getScrollParent(document.getElementById("DocContent"));
+                if(scrollableParent) scrollableParent.scrollTop = 0;
+            }
+
+            bInitialPageLoad = false;
+        };
+
+        //-- make sure selected link parents are set to .expand=true, then ALWAYS wait for Vue to
+        //-- flush before finishRender runs.
+        //--
+        //-- This used to wait only when a nav group had expanded, and go straight through
+        //-- otherwise. That was safe while everything finishRender depends on was applied by a
+        //-- synchronous DOM write. It is not any more: the content reveal (contentLoading) and
+        //-- the layout class above are both reactive now, and both land on the next tick -
+        //-- while finishRender scrolls to an anchor and measures the section it highlights.
+        //-- Measuring before the layout class applies means measuring against the wrong layout.
+        //-- Waiting unconditionally costs one tick and removes the whole class of problem.
+        //-- //-- SG
+        expandNavParentSectionBySelectedLinkHref(linkRef);
+        view.$nextTick(finishRender);
 
-//--- GLOBAL FUNCTIONS
-function removeTrailingSlash(str) {
-	return str.endsWith("/") ? str.slice(0, -1) : str;
 }
-function removeStartingSlash(str) {
-	return str.startsWith("/") ? str.slice(1, str.length) : str;
 
-	//if(linkRef.indexOf("/")===0)linkRef = linkRef.replace("/","");
+//-- return t/f is the element is actually visible on the screen
+function elementIsOnVisibleScreen(oEle)
+{
+
+    const item = oEle.getBoundingClientRect(); 
+    return ( 
+        item.top >= 0 && 
+        item.left >= 0 && 
+        item.bottom <= ( 
+            window.innerHeight || 
+            document.documentElement.clientHeight) && 
+        item.right <= ( 
+            window.innerWidth || 
+            document.documentElement.clientWidth) 
+    ); 
 }
 
-function toSeoUrl(url) {
-	return (
-		url
-			.toString() // Convert to string
-			.normalize("NFD") // Change diacritics
-			// biome-ignore lint/suspicious/noMisleadingCharacterClass: Ignoring this as it's required
-			.replace(/[\u0300-\u036f]/g, "") // Remove illegal characters
-			.replace(/\s+/g, "-") // Change whitespace to dashes
-			.toLowerCase() // Change to lowercase
-			.replace(/&/g, "-and-") // Replace ampersand
-			.replace(/[^a-z0-9\-]/g, "") // Remove anything that is not a letter, number or dash
-			.replace(/-+/g, "-") // Remove duplicate dashes
-			.replace(/^-*/, "") // Remove starting dashes
-			.replace(/-*$/, "")
-	); // Remove trailing dashes
-}
-
-function listenForHrefClicks() {
-	//-- trap all link click events - we want to handle links so can cancel and load content ourselves
-	$("A")
-		.off("click")
-		.on("click", function (ev) {
-			if (this.href) {
-				const checkUrl = new URL(this.href);
-
-				view.resetMobileMenu();
-
-				//-- clicking on a hash tag header link element - so jsut scroll to element
-				if (`${checkUrl.origin}/` === siteBaseLocation) {
-					//-- if a url that is part of this doc site then handle loading content inline else let link do whatever (i.e. its an external link)
-					ev.stopImmediatePropagation();
-					ev.preventDefault();
-
-					//-- do we need to scroll into view element on this page
-					if (
-						checkUrl.hash &&
-						getAnchorFromHash(checkUrl.hash, "faq-toc-item")
-					) {
-						const eleAnc = getAnchorFromHash(checkUrl.hash, "faq-toc-item");
-						if (eleAnc[0]?.scrollIntoView) eleAnc[0].scrollIntoView();
-
-						if (checkUrl.pathname === "/") {
-							//-- going to element on current page so just update current browser url with new #
-							const currUrl = new URL(document.location.href);
-							currUrl.hash = checkUrl.hash;
-							if (currUrl.href !== document.location.href)
-								window.history.pushState(null, null, currUrl); //-- user has clicked a link so we want to add state to history so we can click back
-						} else if (ele.href !== document.location.href) {
-							window.history.pushState(null, null, this.href); //-- user has clicked a link so we want to add state to history so we can click back
-						}
-					} else {
-						loadContentUrl(this.getAttribute("href"), false, false);
-					}
-					return false;
-				}
-				//-- if not part of this website then always open in new tab as considered an external site
-				this.setAttribute("target", "_blank");
-			}
-		});
+function getScrollParent(node) {
+    if (!node) {
+      return null;
+    }
+  
+    if (node.scrollHeight > node.clientHeight) {
+      return node;
+    } else {
+      return getScrollParent(node.parentNode);
+    }
+  }
+
+//-- pending teardown for the section-highlight overlay (item 23) //-- SG
+let sectionHighlightTimer = null;
+
+//-- Remove the section-highlight overlay, if one is up. Safe to call at any time. //-- SG
+function removeSectionHighlightOverlay()
+{
+    if(sectionHighlightTimer)
+    {
+        clearTimeout(sectionHighlightTimer);
+        sectionHighlightTimer = null;
+    }
+    document.querySelectorAll(".hb-section-highlight").forEach(function(el){ el.remove(); });
 }
 
-//-- return t/f is the element is actually visible on the screen
-function elementIsOnVisibleScreen(oEle) {
-	const item = oEle.getBoundingClientRect();
-	return (
-		item.top >= 0 &&
-		item.left >= 0 &&
-		item.bottom <=
-			(window.innerHeight || document.documentElement.clientHeight) &&
-		item.right <= (window.innerWidth || document.documentElement.clientWidth)
-	);
+function GotoAndHighlightAnchorContent(currentActiveAnchor,boolScrollToOnly)
+{
+    //-- remove any current highlighting
+    removeSectionHighlightOverlay();
+
+    if(currentActiveAnchor && currentActiveAnchor.scrollIntoView){
+
+        //-- adjust scroll point for anchor so is not cut off at the top.
+        //-- offsetTop was used here and is measured from the nearest POSITIONED ancestor, not
+        //-- from the scroll container, so any heading inside a positioned wrapper (a video
+        //-- embed, a layout div, a component) scrolled to the wrong place - usually to the top
+        //-- of the document. Measure the real delta between the two boxes instead. //-- SG
+        let scrollableParent = getScrollParent(document.getElementById("DocContent"));
+        if(scrollableParent)
+        {
+            //-- a root scroller (documentElement/body) has no useful client rect of its own -
+            //-- its content box origin IS the viewport origin, so the offset to compare against is 0
+            let boolRootScroller = (scrollableParent === document.documentElement || scrollableParent === document.body);
+            let containerTop = boolRootScroller ? 0 : (scrollableParent.getBoundingClientRect().top + scrollableParent.clientTop);
+            let deltaToTop = currentActiveAnchor.getBoundingClientRect().top - containerTop;
+            scrollableParent.scrollTop += deltaToTop - 30;
+        }
+        else
+        {
+            currentActiveAnchor.scrollIntoView({block:"center"});
+        }
+
+        if(boolScrollToOnly) return; //-- only want to scroll to
+
+        //-- highlight the section for any heading (H1-H6): the heading plus everything up to the
+        //-- next heading of the same-or-higher level.
+        //--
+        //-- This used to WRAP those elements in a .highlight-container div and animate that. The
+        //-- wrapper was never unwrapped (the timeout that did it was commented out), so every
+        //-- hash click wrapped again - containers accumulated and nested, the sibling walk for
+        //-- later clicks swallowed earlier containers whole, the section crept 2px left per
+        //-- trigger, and docApp.tableOfContents[].ele ended up pointing at relocated nodes.
+        //--
+        //-- Now nothing in the article is moved or re-parented at all: we measure the section's
+        //-- bounding box and draw one absolutely-positioned overlay over it, inside
+        //-- .injected-document-container (already position:relative, in both the main and inline
+        //-- shells). The overlay is pointer-events:none and removes itself. //-- SG
+        let headingMatch = /^H([1-6])$/.exec(currentActiveAnchor.tagName || "");
+        if(headingMatch)
+        {
+            let currentLevel = parseInt(headingMatch[1], 10);
+            //-- loop next siblings - stop at the next heading of same-or-higher level (or end of collection)
+            let arrSectionElements = [currentActiveAnchor];
+            let nextSibling = currentActiveAnchor.nextElementSibling;
+            while(nextSibling)
+            {
+                //-- exit - a heading of same-or-higher level starts a new section, so stop here
+                let siblingMatch = /^H([1-6])$/.exec(nextSibling.tagName || "");
+                if(siblingMatch && parseInt(siblingMatch[1], 10) <= currentLevel) break;
+                arrSectionElements.push(nextSibling);
+                nextSibling = nextSibling.nextElementSibling;
+            }
+
+            if(arrSectionElements.length > 1) showSectionHighlightOverlay(arrSectionElements,currentActiveAnchor.tagName);
+        }
+    }
 }
 
-//-- based on content url highlight match navigation menu item
-function highlightNavigationLinkFromUrl(matchLinkHref) {
-	const clean_matchLinkHref = removeStartingSlash(matchLinkHref).split("#")[0]; //-- remvoe # link
-	$("a.DocLink").removeClass("active");
-
-	const arrItems = document.querySelectorAll("a.DocLink");
-
-	for (let x = 0; x < arrItems.length; x++) {
-		const el = arrItems[x];
-		let checkUrl = null;
-		try {
-			checkUrl = new URL(el.href);
-		} catch (e) {
-			//hslDocLog.log("BAD navigation menu item found",el);
-		}
-
-		if (checkUrl) {
-			const testCurrPath = removeStartingSlash(checkUrl.pathname);
-			if (
-				testCurrPath === clean_matchLinkHref ||
-				testCurrPath.indexOf(clean_matchLinkHref) === 0 ||
-				clean_matchLinkHref.indexOf(
-					`${removeStartingSlash(checkUrl.pathname)}/`,
-				) === 0
-			) {
-				//-- exact match
-				$(el).addClass("active");
-				if (!elementIsOnVisibleScreen(el)) el.scrollIntoView();
-				return false; //break out
-			}
-		}
-	}
+//-- Draw the highlight box over a section without touching the article DOM. //-- SG
+function showSectionHighlightOverlay(arrSectionElements,strHeadingTag)
+{
+    let overlayHost = document.querySelector(".injected-document-container");
+    if(!overlayHost) return;
+
+    //-- union of the section's boxes, expressed in the host's coordinate space
+    let hostRect = overlayHost.getBoundingClientRect();
+    let top = null, bottom = null;
+    arrSectionElements.forEach(function(ele)
+    {
+        let rect = ele.getBoundingClientRect();
+        if(!rect.height && !rect.width) return; //-- skip anything not laid out
+        if(top === null || rect.top < top) top = rect.top;
+        if(bottom === null || rect.bottom > bottom) bottom = rect.bottom;
+    });
+    if(top === null) return;
+
+    let overlay = document.createElement("div");
+    overlay.className = "hb-section-highlight " + strHeadingTag;
+    overlay.style.top = (top - hostRect.top + overlayHost.scrollTop - 4) + "px";
+    overlay.style.height = (bottom - top + 8) + "px";
+    overlayHost.appendChild(overlay);
+
+    //-- tear down after the animation. animationend is the accurate signal; the timeout is the
+    //-- fallback for a hidden tab or a browser that skips the animation entirely.
+    let cleanup = function(){ removeSectionHighlightOverlay(); };
+    overlay.addEventListener("animationend",cleanup,{once:true});
+    sectionHighlightTimer = setTimeout(cleanup,5000);
 }
 
-function getAnchorFromHash(strHash, strHasClass) {
-	try {
-		let strSelector = toSeoUrl(strHash.replace("#", ""));
-		if (strHasClass) strSelector += `.${strHasClass}`;
+async function loadContentUrl(linkRef,fromPageRefresh,fromPopState)
+{
+    //-- empty vue enabled doc content
+    let vueBody = vueContentContainer();
+    if(vueBody) vueBody.innerHTML = "";
+
+    //-- the section-highlight overlay is a sibling of the content, so emptying the content does
+    //-- not take it with it - drop it here or it hangs over the next document. //-- SG
+    removeSectionHighlightOverlay();
+
+
+    //-- reset search mode
+    view.docApp.searchMode = false;
+    view.docApp.mcpCatalogMode = false;
+    view.docApp.searchResponse = null;
+
+    //-- clear table of contents
+    view.docApp.tableOfContents = [];
+    view.docApp.tocMobileOpen = false;
+    //-- hide footer while loading
+    view.docApp.contentLoading = true;
+
+    if(linkRef.indexOf(window.location.origin +"/")===0)
+    {
+        linkRef = linkRef.replace(window.location.origin  +"/","");
+    }
+
+    //-- remove trailing / if has one
+    linkRef = removeTrailingSlash(linkRef);
+    //-- remove starting / if link starts with it
+    linkRef = removeStartingSlash(linkRef);
+
+    let frontmatterData = {};
+    let urlInfo = linkRef.split("#"); //-- remove data hash
+    let hash = (urlInfo[1])?"#"+urlInfo[1] : "";
+    
+    linkRef = urlInfo[0];
+    let booksLinkRef = linkRef.includes('_books/') ? linkRef : "_books/"+linkRef;        
+
+    //-- coming for initial browser load or refresh - so make sure have content load (which the http server should have already injected)
+    let initialBody = contentContainer();
+    if(bInitialPageLoad && initialBody && initialBody.textContent)
+    {
+        //-- content is already loaded - but we need to get the front matter data (for layout etc).
+        //-- NOTE: assign to the OUTER frontmatterData - a shadowing `let` here used to mean the
+        //-- meta-absent case passed "" (getMeta's miss value) into postProcessBookContentRender
+        //-- instead of the normalised {} declared above. //-- SG
+        let metaFrontmatter = getMeta("hdoc:frontmatter");
+        if(metaFrontmatter)
+        {
+            frontmatterData = JSON.parse(atob(metaFrontmatter));
+            let baseUrl = removeTrailingSlash(window.location.origin);
+            let bookId = window.location.href.split(baseUrl+"/")[1].split("/")[0];
+
+            frontmatterData.formattedCommitDate = new Date(frontmatterData["last-commit"]).toLocaleDateString();
+            frontmatterData.readTime = frontmatterData["reading-time"] + " minute to read";
+            frontmatterData.contributorCount = frontmatterData["contributor-count"]-0;
+
+            view.docApp.book = frontmatterData;
+            view.docApp.book.docId = bookId;
+            view.docApp.inlineTitle =frontmatterData.title;
+
+            // fetch hdocbook.json to get book level fields (e.g. version) that are missing from frontmatter header
+            fetchJsonFile(`_books/${bookId}/hdocbook.json`).then((hdocbook) => {
+                if (hdocbook) {
+                    view.docApp.book = Object.assign({}, hdocbook, view.docApp.book);
+                    //-- the title band binds docApp.title/description, which only loadLibraryBook
+                    //-- used to set - so on a direct page load / refresh it rendered empty //-- SG
+                    view.docApp.title = hdocbook.title || "";
+                    view.docApp.description = hdocbook.description || "";
+                }
+            });
+        }
+
+        let buildData = getMeta("hdoc:build");
+        if(buildData)
+        {
+            view.docApp.build = buildData;
+        }
+
+        let nodeData = getMeta("hdoc:node");
+        if(nodeData)
+        {
+            view.docApp.node = nodeData.split(".")[0];
+        }
+
+        //-- load the book info json
+        view.docApp.bookInfo = null;
+        let jsonFileUrl = booksLinkRef+ ".info";
+        view.docApp.bookInfo = await fetchJsonFile(jsonFileUrl);
+        if(!view.docApp.bookInfo)view.docApp.bookInfo = null;
+        
+		view.docApp.frontmatterData = frontmatterData;
+        postProcessBookContentRender(linkRef+hash,frontmatterData,booksLinkRef);
+    }
+    else
+    {
+        //-- we are doing a content load from A tag link or back btn - so ftch content and inject mark up
+        //-- update url in browser
+        setBrowserViewUrl(linkRef+hash,{},fromPageRefresh);
+
+        //-- destroy any existing content children and events properly
+        let clearBody = contentContainer();
+        if(clearBody) clearBody.innerHTML = "";
+
+        //-- Fire the .info JSON and the content HTML together instead of awaiting .info
+        //-- first. They are independent requests, so serialising them cost a full extra
+        //-- round-trip on every in-book navigation. postProcessBookContentRender still
+        //-- needs bookInfo (addPdfIconToHeader reads it), so we join both before
+        //-- injecting and the ordering it depends on is unchanged. //-- SG
+        view.docApp.bookInfo = null;
+
+        //-- for now just load whatever the href prop is (we can add actions to perform specific processing and then load content based on element atts etc)
+        view.docApp.build = 0;
+        view.docApp.node = "N/A";
+
+        let infoPromise = fetchJsonFile(booksLinkRef + ".info");
+        let contentPromise = fetch(booksLinkRef).then(response =>
+        {
+            //-- the server 301s renamed pages (book-declared redirects) on the _books
+            //-- content endpoint and fetch follows it transparently, so the content is
+            //-- already right - but linkRef/booksLinkRef and the history entry we pushed
+            //-- above still point at the old page. Rewrite them from the final response
+            //-- url so nav highlight, pdf link and the address bar show the new page.
+            //-- replaceState (not push) - the old-url entry is dead, back should skip it. //-- SG
+            if(response.redirected && response.url)
+            {
+                let redirectedPath = removeStartingSlash(new URL(response.url).pathname);
+                if(redirectedPath.indexOf("_books/") === 0)
+                {
+                    booksLinkRef = redirectedPath;
+                    linkRef = redirectedPath.substring("_books/".length);
+                    window.history.replaceState(null, null, window.location.origin + "/" + linkRef + hash);
+                }
+            }
+
+            if(response.headers.has("X-esp-node"))
+            {
+                view.docApp.node = response.headers.get("X-esp-node").split(".")[0];
+            }
+
+            if(response.headers.has("X-esp-build"))
+            {
+                view.docApp.build = response.headers.get("X-esp-build");
+            }
+            if(response.headers.has("X-frontmatter"))
+            {
+                frontmatterData = response.headers.get("X-frontmatter");
+                frontmatterData = JSON.parse(atob(frontmatterData));
+				view.docApp.frontmatterData = frontmatterData;
+            } else {
+				//-- the fallback path used to parse into the local only and never write it back
+				//-- to docApp, so the previous page's frontmatter stayed live - addPdfIconToHeader
+				//-- reads docApp.frontmatterData['pdf-path'] and served the wrong PDF. getMeta
+				//-- returns "" when the tag is absent, so normalise to an object. //-- SG
+				let metaFrontmatter = getMeta("hdoc:frontmatter");
+				frontmatterData = metaFrontmatter ? JSON.parse(atob(metaFrontmatter)) : {};
+				view.docApp.frontmatterData = frontmatterData;
+			}
 
-		const jqEle = $(`#${strSelector}`);
-		if (jqEle[0]) {
-			return jqEle;
-		}
-		return null;
-	} catch (e) {
-		hslDocLog.log(`Get document anchor element by hash failed [${strHash}]`, e);
-		return null;
-	}
+            return response.text();
+        });
+
+        try
+        {
+            let contentResults = await Promise.all([infoPromise,contentPromise]);
+            view.docApp.bookInfo = contentResults[0] || null;
+            let injectBody = contentContainer();
+            if(injectBody) injectBody.innerHTML = contentResults[1]; //-- inject content if not from initial load
+            postProcessBookContentRender(linkRef+hash,frontmatterData,booksLinkRef);
+        }
+        catch(e)
+        {
+            //-- previously an unhandled rejection - log it rather than failing silently. Same
+            //-- visible outcome as before: nothing injected, no post-processing. //-- SG
+            hslDocLog.log("Failed to load content for ["+booksLinkRef+"]",e);
+        }
+    }
+    //console.log(view.docApp)
 }
 
-//-- create items to stick in toc from current loaded content
-//-- searches for H2,H3
-function generateTableOfContentsFromDoc() {
-	const container = jqContentContainer[0];
-	if (container) {
-		const currUrl = new URL(document.location.href);
-		view.docApp.tableOfContents = [];
-		for (let i = 2; i <= 3; i++) {
-			const headers = container.getElementsByTagName(`h${i}`);
-			for (let j = 0; j < headers.length; j++) {
-				const jqCurrHeader = $(headers[j]);
-				//-- only process headers that do not have this class
-				if (!jqCurrHeader.hasClass("no-auto-anchor"))
-					jqCurrHeader.addClass("faq-toc-item");
-			}
-		}
-
-		const headersTocItem = container.getElementsByClassName("faq-toc-item");
-		for (let k = 0; k < headersTocItem.length; k++) {
-			const item = headersTocItem[k];
-			const strLabel = $.trim(item.innerText);
-			if (strLabel) {
-				const seoSafeId = toSeoUrl(strLabel); //-- will use SEO to set in url so can scroll to element from url
-				const linkUrl = `${currUrl.pathname}#${seoSafeId}`;
-				item.id = seoSafeId;
-
-				view.docApp.tableOfContents.push({
-					ele: item,
-					eleText: strLabel,
-					tagName: item.tagName,
-					href: linkUrl,
-				});
-
-				//-- add link icon to header (using seo id)
-				$(item).append(
-					`<a class="header-anchor" aria-label="Link to this section: ${strLabel}"><i class="bi bi-link" aria-hidden="true"></i></a>`,
-				);
-				$(item).find("a").attr("href", linkUrl);
-			}
-		}
-	}
-}
-
-function loadContentUrl(
-	linkRef,
-	fromPageRefresh,
-	fromPopState,
-	fromBook = true,
-) {
-	let downloadFile = false;
-	if (linkRef.includes('_books/')) {
-		downloadFile = linkRef.split('').length > 1;
-		console.log('downloadFile', downloadFile);
-	}
-
-	//-- clear table of contents
-	view.docApp.tableOfContents = [];
-	let clean_linkRef = linkRef;
-	if (clean_linkRef.indexOf(`${window.location.origin}/`) === 0) {
-		clean_linkRef = clean_linkRef.replace(`${window.location.origin}/`, "");
-	}
-
-	//-- remove trailing / if has one
-	clean_linkRef = removeTrailingSlash(clean_linkRef);
-	//-- remove starting / if link starts with it
-	clean_linkRef = removeStartingSlash(clean_linkRef);
-	
-	let booksLinkRef = clean_linkRef;
-	if (fromBook) {
-		booksLinkRef = clean_linkRef.includes("_books/")
-			? clean_linkRef
-			: `_books/${clean_linkRef}`;
-	}
-
-	if (downloadFile) {
-		//-- open in new tab to download
-		window.open(booksLinkRef, '_blank');
-	} else {
-		//-- update url in browser
-		if (fromBook) {
-			setBrowserViewUrl(clean_linkRef, {}, fromPageRefresh, fromPopState);
-		}
-		
-		//-- destroy any existing content children and events properly
-		jqContentContainer.empty();
-		jqDocumentHeader.find(".document-title").empty();
-	
-		//-- for now just load whatever the href prop is (we can add actions to perform specific processing and then load content based on element atts etc)
-		let frontmatterData = {};
-		fetch(booksLinkRef)
-		.then((response) => {
-			if (response.headers.has("X-frontmatter")) {
-				frontmatterData = response.headers.get("X-frontmatter");
-				frontmatterData = JSON.parse(atob(frontmatterData));
-			}
-			return response.text();
-		})
-		.then((html) => {
-			jqContentContainer.html(html);
-
-			//-- remove previous layoutclass if have one
-			if (global.lastLayoutClass) {
-				$("#DocContent").removeClass(global.lastLayoutClass);
-				global.lastLayoutClass = "";
+function addPdfIconToHeader(direct_BooksLinkRef)
+{
+    //-- do we have a pdf
+    if(view.docApp.bookInfo && view.docApp.bookInfo.pdf_size)
+    {
+		let tooltipSize = "Download (" + formatBytes(view.docApp.bookInfo.pdf_size) +")";
+        let bodyForToolbar = contentContainer();
+        let tbRight = bodyForToolbar ? bodyForToolbar.querySelector(".toolbar-right") : null;
+        if(tbRight)
+        {
+			let pdfUrl = direct_BooksLinkRef + ".pdf";
+			if (view.docApp.frontmatterData['pdf-path'] && view.docApp.frontmatterData['pdf-path'] !== '') {
+				pdfUrl = '/_books/' + view.docApp.frontmatterData['pdf-path'];
 			}
+            
+            if(!tbRight.querySelector(".pdffile"))
+            {
+                tbRight.insertAdjacentHTML("afterbegin",`<span class="toolbar-action pdffile me-1" ><a target="_blank" title="${tooltipSize}" href="${pdfUrl}" download rel="nofollow"><span>Download</span><span>PDF</span></a></span>`);
+            }
+        }
+    }
+}
 
-			//-- if have layoutclass add it to content container - this is so we can specify table list view sizes etc
-			if (frontmatterData.layout) {
-				$("#DocContent").addClass(frontmatterData.layout);
-				global.lastLayoutClass = frontmatterData.layout;
-			}
+function findFirstClickableBookLink(findByLinkRef,currentNavSection)
+{
+    if(currentNavSection === undefined) 
+        currentNavSection = view.docApp.navSections;
+
+
+    for(let x=0;x<currentNavSection.length;x++)
+    {
+        if(currentNavSection[x].items)
+        {
+            let clickableItem = findFirstClickableBookLink(findByLinkRef,currentNavSection[x].items);
+            if(clickableItem)
+            {
+                return clickableItem;
+            }
+        }
+        else if(currentNavSection[x].link)
+        {
+            if(findByLinkRef && findByLinkRef.indexOf("/")>-1)
+            {               
+                if(removeStartingSlash(removeTrailingSlash(currentNavSection[x].link)) == findByLinkRef)  return currentNavSection[x].link;
+            }
+            else 
+            {
+                return currentNavSection[x].link;
+            }
+        }
+    }    
+}
 
-			//--generate toc for all layouts that have h2/h3
-			view.docApp.keepTocLayout = frontmatterData.layout === "article-no-toc";
-			if (
-				!frontmatterData.layout ||
-				frontmatterData.layout === "article" ||
-				frontmatterData.layout === "article-toc"
-			) {
-				view.docApp.keepTocLayout = true;
-				generateTableOfContentsFromDoc();
-			}
+function expandNavParentSectionBySelectedLinkHref(findByLinkRef, currentNavSection)
+{
+    findByLinkRef = findByLinkRef.split("#")[0];
+    if(currentNavSection === undefined)
+    {
+        currentNavSection = view.docApp.navSections;
+    }
+
+    for(let x=0;x<currentNavSection.length;x++)
+    {
+        if(currentNavSection[x].items)
+        {
+            let res = expandNavParentSectionBySelectedLinkHref(findByLinkRef,currentNavSection[x].items);
+            if(res)
+            {
+                currentNavSection[x].expand=true;
+                return res;
+            }
+        }
+        else if(currentNavSection[x].link)
+        {
+            //-- check item to see if it matches url. The .link guard matches the one in
+            //-- findFirstClickableBookLink - a nav leaf with no link used to throw here. //-- SG
+            if(removeStartingSlash(removeTrailingSlash(currentNavSection[x].link)) == findByLinkRef)
+            {
+                return true;
+            }
+        }
+    }
 
-			//-- find any <tabs> and andd a bootstrap tab item strip
-			$("#DocContent")
-				.find("tabs")
-				.each((idx, el) => {
-					const tabClass = el.getAttribute("tabstyle");
-					let tabMarkup = "<ul class='nav nav-tabs'>";
-					//-- for each tab we need to create a tab link
-					$(el)
-						.find("tab")
-						.each((idx, aTab) => {
-							const activeClass = idx === 0 ? " active" : "";
-							tabMarkup += `<li class='nav-item c-pointer' contentidx='${idx}'><span class='nav-link${activeClass}'>${aTab.getAttribute("name")}</span></li>`;
-
-							//-- hide the tab element if it is not the active one (first)
-							if (idx > 0) $(aTab).addClass("d-none");
-						});
-
-					tabMarkup += "</ul>";
-					//-- inject markup
-					$(el).prepend(tabMarkup).find(".nav.nav-tabs").addClass(tabClass);
-
-					//-- add event handler for switching tab items
-					$(el)
-						.find("li")
-						.off("click")
-						.on("click", function () {
-							const contentIdx = this.getAttribute("contentidx");
-							const tabsContainer = $(this).closest("tabs").eq(0);
-							const tabs = tabsContainer.find("tab");
-
-							//-- hide other tab content and show this tabs content
-							tabs.addClass("d-none");
-							tabs.eq(contentIdx - 0).removeClass("d-none");
-
-							//-- set clicked tab item to active
-							tabsContainer.find(".nav-link").removeClass("active");
-							$(this).find(".nav-link").addClass("active");
-						});
-				});
-
-			//-- do any code highlighting
-			if (hljs) {
-				for (const el of document.querySelectorAll("pre code")) {
-					hljs.highlightBlock(el);
-				}
-			} else {
-				hslDocLog.log(
-					"code highlighting js could not be loaded. code block highlighting will not be enabled",
-				);
-			}
+}
+
+function setBrowserViewUrl(strHrefToLoad,viewData,fromPageRefresh)
+{
+   
+   let urlToSet = window.location.origin + "/" + strHrefToLoad;
+   const url = new URL(urlToSet);
+   
+   //-- remove any old params
+   for(let strKey in global.stateParams)
+   {
+       url.searchParams.delete(strKey);
+   }
+
+   //-- now set new data params in url
+   for(let strKey in viewData)
+   {
+       url.searchParams.set(strKey,viewData[strKey]);
+   }    
+
+   //-- store global params
+   global.stateParams = viewData;
+
+   //-- if havent clicked back or forwards, and this isn't a refresh/first paint (where the
+   //-- browser already holds the right entry), record the navigation. Push only when the url
+   //-- actually changes, compared against the LIVE location - the old "lastUrlDynamicallySet"
+   //-- string went stale after back-button trips (home -> book -> back -> back -> same book
+   //-- again matched the stale value and replaceState'd over the home entry, so the second
+   //-- back skipped the book page). Same-url re-clicks now simply do nothing: the entry the
+   //-- user is on is already correct. //-- SG
+   if(!currentPopState && !fromPageRefresh)
+   {
+        if(url.href !== window.location.href)
+        {
+            window.history.pushState(null, null, url); //-- add entry
+        }
+    }
+    currentPopState = null;
+}
 
-			//-- render any Mermaid diagrams client-side (lazy-loads the bundle)
-			hbRenderMermaidDiagrams();
-
-			//-- show copy button by any code blocks
-			const options = {
-				contentSelector: ".injected-document-content",
-				// Delay in ms used for `setTimeout` before badging is applied
-				// Use if you need to time highlighting and badge application
-				// since the badges need to be applied afterwards.
-				// 0 - direct execution (ie. you handle timing
-				loadDelay: 0,
-
-				// CSS class(es) used to render the copy icon.
-				copyIconClass: "bi bi-clipboard",
-				// CSS class(es) used to render the done icon.
-				checkIconClass: "bi bi-clipboard-check --htl-c-brand",
-
-				// intercept text copying - passed in text return text out
-				onBeforeCodeCopied: (text) => text,
-			};
-
-			highlightJsBadge(options);
-
-			//-- get first H1 and put it into our header section header
-			const docHeader = jqContentContainer.find("H1").eq(0);
-			jqDocumentHeader.find(".document-title").append(docHeader);
-
-			setGitHubBookUrl(clean_linkRef);
-
-			//-- make sure selected link parents are set to .expand=true
-			if (expandNavParentSectionBySelectedLinkHref(clean_linkRef)) {
-				view.updateCounter++;
-				view.$nextTick(() => {
-					//-- find any navigation links that match url and highlight
-					//                listenForHrefClicks();
-					highlightNavigationLinkFromUrl(clean_linkRef);
-
-					//-- scroll to element that match hash (if have one)
-					if (document.location.hash) {
-						const gotoEle = getAnchorFromHash(document.location.hash);
-						if (gotoEle) gotoEle[0].scrollIntoView();
-					}
-				});
-				view.$forceUpdate();
-			}
 
-			listenForHrefClicks();
-		});
-	}
-	
+//-- Decide whether the content-type filter has dead-ended the search.
+//--
+//-- The filter defaults to Documentation because reference material is ~85% of the
+//-- corpus. That is right for most searches and wrong for some: "userGetInfo" has no
+//-- documentation answer at all. Without this the default would turn a findable result
+//-- into a blank page, which is worse than the noise it was added to remove.
+//--
+//-- One outcome: shown === 0 -> widen automatically and say why. Never show an empty
+//-- page when the answer exists one filter away. A filter that is merely hiding
+//-- results is left alone - the Information type facet counts show what is hidden.
+//--
+//-- Returns true when the caller should re-run the search. Cannot loop: widening sets
+//-- the filter to "" and this returns early when no filter is active. //-- SG
+//-- Set for exactly one evaluation after an automatic widen. The widen triggers a
+//-- second search, and that response carries no filter - without this the explanation
+//-- would be cleared before the user ever read it. //-- SG
+let docTypeAutoWidened = false;
+
+//-- The query an automatic widen was applied to. A widen is a rescue for the query that
+//-- needed it, not a new preference, so the next DIFFERENT query goes back to the
+//-- default. A filter the user picked themselves is left alone - that is an explicit
+//-- choice and should persist the way any other facet does. //-- SG
+let docTypeAutoWidenedForQuery = null;
+
+//-- Content type shown when the user has not chosen otherwise: 0 = Documentation
+const docTypeDefaultFilter = "0";
+
+//-- On the INTERNAL site only, the Information type the user last picked is remembered
+//-- across sessions, so the facet comes back the way they left it. Internal users
+//-- search the whole corpus (api/db reference included) and re-picking "All" on every
+//-- visit was pure friction; public visitors keep the Documentation default, which is
+//-- tuned for them (see the note on searchDocTypeFilter in the data block).
+//--
+//-- Stored in localStorage, NOT in the /search url - a pasted search link must keep
+//-- meaning exactly what its params say, whoever opens it. A dt in the url still wins
+//-- for that page load, and does not overwrite the stored preference.
+//--
+//-- Gated the same way as showAudienceFilter / showSearchMatchBadges: everything that is
+//-- not the public site, so docs-internal AND the dev boxes behave alike - behaviour that
+//-- cannot be reproduced on a dev host cannot be tested there either. //-- SG
+const docTypeFilterPersisted = window.location.hostname !== "docs.hornbill.com";
+const docTypeFilterStorageKey = "hdocbook-search-doctype";
+
+//-- Transient "needs two characters" hint by the toolbar search box. Self-clearing: the hint
+//-- is feedback on one key press, so it must not outlive it and must never need dismissing.
+//-- Any search that actually runs cancels it. //-- SG
+let searchTooShortHintTimeoutId = null;
+function showSearchTooShortHint()
+{
+    clearTimeout(searchTooShortHintTimeoutId);
+    view.docApp.searchTooShortHint = true;
+    searchTooShortHintTimeoutId = setTimeout(function(){ view.docApp.searchTooShortHint = false; },3500);
+}
+function hideSearchTooShortHint()
+{
+    clearTimeout(searchTooShortHintTimeoutId);
+    if(view.docApp.searchTooShortHint) view.docApp.searchTooShortHint = false;
 }
 
-function setGitHubBookUrl(linkRef) {
-	let bookRef = linkRef.split(siteBaseLocation);
-	bookRef = bookRef[1] ? bookRef[1] : bookRef[0];
-	const bookId = bookRef.split("/")[0];
-	view.docApp.documentGithubUrl = `https://github.com/Hornbill-Docs/${bookId}/blob/main/${bookRef}.md`;
-	//--https://github.com/Hornbill-Docs/hdoc-guide/blob/main/hdoc-guide/overview.md
+//-- localStorage access throws outright in some privacy modes, so every read/write is
+//-- guarded and a failure just means the plain default //-- SG
+function docTypeUserDefaultFilter()
+{
+    if(!docTypeFilterPersisted) return docTypeDefaultFilter;
+    try
+    {
+        let stored = localStorage.getItem(docTypeFilterStorageKey);
+        //-- "" is a real stored choice (All); only absent or malformed falls back
+        if(stored === "" || (typeof stored === "string" && /^[0-9]+$/.test(stored))) return stored;
+    }
+    catch(e){}
+    return docTypeDefaultFilter;
 }
 
-function loadBookDefaultLink() {
-	$(".DocLink.link").first().click();
+//-- Only ever called from an explicit user pick. An automatic widen is a rescue for one
+//-- query, not a preference, so it must never be written here. //-- SG
+function rememberDocTypeFilter(docType)
+{
+    if(!docTypeFilterPersisted) return;
+    try { localStorage.setItem(docTypeFilterStorageKey,docType); } catch(e){}
 }
 
-function findFirstClickableBookLink(findByLinkRef, currentNavSection) {
-	let currNav = currentNavSection;
-	if (currNav === undefined) currNav = view.docApp.navSections;
+function evaluateDocTypeRescue()
+{
+    let app = view.docApp;
+
+    if(docTypeAutoWidened)
+    {
+        docTypeAutoWidened = false;
+        return false;
+    }
+
+    app.searchDocTypeRescue = null;
+
+    let resp = app.searchResponse;
+    if(!resp || !resp.docTypesInfo || !resp.docTypesInfo.length || !app.searchDocTypeFilter) return false;
+
+    let shown = 0;
+    let hidden = 0;
+    let best = null;
+
+    for(let i=0;i<resp.docTypesInfo.length;i++)
+    {
+        let dt = resp.docTypesInfo[i];
+        if(String(dt.docType) === app.searchDocTypeFilter)
+        {
+            shown = dt.foundCount;
+        }
+        else
+        {
+            hidden += dt.foundCount;
+            if(best === null || dt.foundCount > best.foundCount) best = dt;
+        }
+    }
+
+    if(hidden === 0) return false;
+
+    //-- only the dead-end case widens; a filter that is merely hiding results is
+    //-- left alone. The old "Show all N results" offer promised the whole hidden
+    //-- count but the server caps at 300 returned, so it could never deliver -
+    //-- the Information type facet counts already show what is hidden. //-- SG
+    if(shown === 0)
+    {
+        app.searchDocTypeFilter = "";
+        app.searchDocTypeRescue = {auto:true, hidden:hidden, best:best};
+        docTypeAutoWidened = true;
+        docTypeAutoWidenedForQuery = app.altSearchText || app.searchText || "";
+        return true;
+    }
+
+    return false;
+}
 
-	for (let x = 0; x < currNav.length; x++) {
-		if (currNav[x].items) {
-			const clickableItem = findFirstClickableBookLink(
-				findByLinkRef,
-				currNav[x].items,
-			);
-			if (clickableItem) {
-				return clickableItem;
-			}
-		} else if (currNav[x].link) {
-			if (findByLinkRef) {
-				if (
-					removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
-					findByLinkRef
-				)
-					return currNav[x].link;
-			} else {
-				return currNav[x].link;
-			}
-		}
-	}
-}
-
-function expandNavParentSectionBySelectedLinkHref(
-	findByLinkRef,
-	currentNavSection,
-) {
-	let currNav = currentNavSection;
-	if (currNav === undefined) {
-		view.docApp.bookBreadCrumb = []; //-- reset bread crumb
-		currNav = view.docApp.navSections;
-	}
-
-	for (let x = 0; x < currNav.length; x++) {
-		if (currNav[x].items) {
-			const res = expandNavParentSectionBySelectedLinkHref(
-				findByLinkRef.split("#")[0],
-				currNav[x].items,
-			);
-			if (res) {
-				currNav[x].expand = true;
-				view.docApp.bookBreadCrumb.unshift({
-					title: currNav[x].text,
-					link: currNav[x].items[0].link,
-				});
-				return res;
-			}
-		} else {
-			//-- check item to see if it matches url
-			if (
-				removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
-				findByLinkRef.split("#")[0]
-			) {
-				return true;
-			}
-		}
-	}
-}
-
-function old_expandNavParentSectionBySelectedLinkHref(
-	findByLinkRef,
-	currentNavSection,
-) {
-	let currNav = currentNavSection;
-	if (currNav === undefined) currNav = view.docApp.navSections;
-
-	for (let x = 0; x < currNav.length; x++) {
-		if (currNav[x].items) {
-			const res = expandNavParentSectionBySelectedLinkHref(
-				findByLinkRef.split("#")[0],
-				currNav[x].items,
-			);
-			if (res) {
-				currNav[x].expand = true;
-				return res;
-			}
-		} else {
-			//-- check item to see if it matches url
-			if (
-				removeStartingSlash(removeTrailingSlash(currNav[x].link)) ===
-				findByLinkRef.split("#")[0]
-			) {
-				return true;
-			}
-		}
-	}
-}
-
-let lastUrlDynamicallySet = "";
-function setBrowserViewUrl(
-	strHrefToLoad,
-	viewData,
-	fromPageRefresh,
-	fromPopState,
-) {
-	const urlToSet = `${window.location.origin}/${strHrefToLoad}`;
-	const url = new URL(urlToSet);
-
-	//-- remove any old params
-	for (const strKey in global.stateParams) {
-		url.searchParams.delete(strKey);
-	}
-
-	//-- now set new data params in url
-	for (const strKey in viewData) {
-		url.searchParams.set(strKey, viewData[strKey]);
-	}
-
-	//-- store global params
-	global.stateParams = viewData;
-
-	if (!fromPageRefresh) {
-		if (fromPopState) {
-			//-- so user has clicked on a link - always add entry
-			window.history.pushState(null, null, url); //-- add entry
-		} else {
-			if (lastUrlDynamicallySet) {
-				if (lastUrlDynamicallySet !== strHrefToLoad) {
-					window.history.pushState(null, null, url); //-- add entry
-				} else {
-					window.history.replaceState(null, null, url); //-- user has refreshed page or jsut visited page
-				}
-			} else {
-				window.history.replaceState(null, null, url); //-- user has clicked a link so we want to add state to history so we can click back
-			}
-		}
-	}
-	lastUrlDynamicallySet = strHrefToLoad;
+//-- Decide whether the bid book filter names a book that does not exist - a mistyped or
+//-- stale pasted url (`/search?q=spf&bid=esp-confi`). A real book with zero matches keeps
+//-- its filter and shows as a selected zero-count entry; an unknown id would leave the
+//-- Books list with NOTHING selected and an unexplained empty result page. Same shape as
+//-- evaluateDocTypeRescue: clear the filter, say why, re-run once. //-- SG
+//-- One evaluation of grace after the automatic clear, or the re-run's own response
+//-- would wipe the explanation before the user read it. //-- SG
+let bookFilterAutoCleared = false;
+
+function evaluateBookFilterRescue()
+{
+    let app = view.docApp;
+
+    if(bookFilterAutoCleared)
+    {
+        bookFilterAutoCleared = false;
+        return false;
+    }
+
+    app.searchBookRescue = null;
+
+    if(!app.searchFilterBySpecificBookId) return false;
+
+    //-- only judge the id against a LOADED library - an empty book list means the
+    //-- library fetch has not landed, not that every id is bad //-- SG
+    if(!view.docApp.library || !Array.isArray(view.docApp.library.books) || !view.docApp.library.books.length) return false;
+
+    if(getBookById(app.searchFilterBySpecificBookId) !== undefined) return false;
+
+    app.searchBookRescue = {bid: app.searchFilterBySpecificBookId};
+    app.searchFilterBySpecificBookId = "";
+    app.searchFilterBySpecificBookTitle = "";
+    bookFilterAutoCleared = true;
+    return true;
+}
+
+function loadLibraryOrBookFromCurrentUrl(loadingUrl)
+{
+
+    //-- check if we are loading base url
+    view.docApp.searchMode=false;
+    view.docApp.mcpCatalogMode = false;
+    view.docApp.searchFilteredProducts={};
+
+    let baseUrl = removeTrailingSlash(window.location.origin);
+    let currentUrl = removeTrailingSlash(loadingUrl || window.location.href);
+    if(currentUrl && currentUrl!==baseUrl && currentUrl.indexOf("/?mode=")===-1)
+    {
+        //-- we are trying to load a book
+        let bookId = window.location.href.split(baseUrl+"/")[1].split("/")[0];
+        if(bookId.indexOf("mcp?")===0 || bookId==="mcp")
+        {
+            //-- /mcp - the MCP server catalog. Mirrors the search branch below,
+            //-- including the currentPopState clear: this branch never reaches
+            //-- setBrowserViewUrl(), which is the only place that consumes and clears
+            //-- it, and a stale value silently suppresses the NEXT link click's
+            //-- pushState. //-- SG
+            bInitialPageLoad = false;
+            view.docApp.book = {};
+            view.docApp.mcpCatalogMode = true;
+            document.title = "Connect an AI assistant - Hornbill Documentation";
+
+            view.loadMcpCatalog();
+
+            revealApp();
+
+            currentPopState = null;
+        }
+        else if(bookId.indexOf("search?")===0 || bookId==="search")
+        {
+            //-- we are in search mode.
+            bInitialPageLoad = false;
+            view.docApp.book = {};
+
+            //-- do we have a search term to search for
+
+            view.docApp.searchFilterBySpecificBookId = "";
+
+            //-- parse the search criteria properly. The old split("?q=")/split("&bid=") parse
+            //-- swallowed every OTHER param into the q value, so back-button onto a filtered
+            //-- search (?q=workflow&dt=5) re-ran the search as q="workflow&dt=5" and the
+            //-- rebuilt url showed q=workflow%26dt%3D5. //-- SG
+            let searchUrlParams = new URL(window.location.href).searchParams;
+            let initialSearch = searchUrlParams.get("q") || "";
+            let initalBookIdFilter = searchUrlParams.get("bid") || "";
+
+            //-- restore the filters this history entry was made with. Only when present:
+            //-- an absent dt is ambiguous (first load default vs auto-widened "everything"),
+            //-- so leave the current filter state alone in that case //-- SG
+            if(searchUrlParams.has("dt")) view.docApp.searchDocTypeFilter = searchUrlParams.get("dt");
+            if(searchUrlParams.has("audience")) view.docApp.searchAudienceFilter = searchUrlParams.get("audience");
+
+            view.toolbarSearch(initialSearch,initalBookIdFilter,true);
+
+            //-- remove hidden class
+            revealApp();
+
+            //-- this branch never reaches setBrowserViewUrl (the only place that consumes and
+            //-- clears currentPopState), so clear it here - a stale value suppressed the
+            //-- pushState of the NEXT normal link click, leaving the url stuck. //-- SG
+            currentPopState = null;
+        }
+        else if(bookId)
+        {
+
+            if(!findBookByIdAndLoad(bookId,loadingUrl))
+            {
+                //-- if we get here url was not found so goto base library
+                view.loadLibraryHome();
+                currentPopState = null; //-- see note in the search branch above //-- SG
+            }
+        }
+    }
+    else
+    {
+        //-- will reset view to home lib
+        bInitialPageLoad = false;
+        view.docApp.book = {};
+        view.docApp.altSearchText = "";
+
+        //-- we have come from a back or forward browser button
+        let startingLibraryProduct = urlGetParam(window.location.search,"product");
+        let startingLibraryMode = urlGetParam(window.location.search,"mode");
+
+        let selectLayoutMode = getLibraryLayoutByModeParam(startingLibraryMode);
+        organiseLibrary(selectLayoutMode,startingLibraryProduct);
+
+        //-- remove hidden class
+        revealApp();
+
+        //-- see note in the search branch above: without this, back-button to the library
+        //-- home left currentPopState set, and the next book click never updated the url
+        //-- (then the click after that pushed onto the wrong base entry, so back skipped a
+        //-- page). This was the reported "back button misses out the How-to page" defect. //-- SG
+        currentPopState = null;
+    }
+
+}
+
+function findBookByIdAndLoad(bookId,fromPopStateUrl)
+{
+    //-- we have a book id fronm link like https://docs.hornbill.com/itom-config#itom-subscription-tiers instead of https://docs.hornbill.com/itom-config/index#itom-subscription-tiers
+    if(bookId.indexOf("#")>0)
+    {
+        bookId = bookId.split("#",1)[0];
+    }
+
+    let book = getLibraryBooksIndex().get(bookId);
+    if(book)
+    {
+        view.loadLibraryBook(book,fromPopStateUrl);
+        return true;
+    }
+
+    return false;
+}
+
+
+function setLibraryGroupTitleAndDescription(aGroup)
+{
+    //-- need to get the title and description somehow
+    if(aGroup.mode==="audience")
+    {
+        aGroup.title = (aGroup.id==="public")?"Public Library":"Internal Library";
+        //aGroup.description = (aGroup.id==="public")?"Explore all documents, guides and articles.":"Documents for internal user only, relating to internal processes, operations and technical information."
+        aGroup.description = (aGroup.id==="public")?"Explore here. Use the toggle to the right to browse by audience or product.":"Documents for internal users only."
+    }
+    else if(aGroup.mode==="productFamilyId")
+    {
+        for(let x=0;x<view.docApp.products.length;x++)
+        {
+            if(aGroup.id == view.docApp.products[x].id)
+            {
+                aGroup.title = view.docApp.products[x].name;
+                
+                
+                if(view.docApp.products[x].icon)
+                {
+                    aGroup.icon = view.docApp.products[x].icon.replace("images/","images/products/");
+                }
+                else{
+                    aGroup.icon = "images/products/hornbill-square.svg";
+                }
+                return aGroup;
+            }
+        }
+    }
+    
+    return aGroup;
+}
+
+function getLibraryLayoutByModeParam(groupByModeParam)
+{
+    for(let x=0;x<view.docApp.groupModes.length;x++)
+    {
+        if(view.docApp.groupModes[x].mode===groupByModeParam)
+        {
+            return view.docApp.groupModes[x]
+        }
+    }
+
+    return view.docApp.groupModes[0];
 }
 
-async function fetchContentFile(strFilePath) {
-	return await fetch(strFilePath)
-		.then((response) => response.text())
-		.then((fileContent) => {
-			return fileContent;
-		});
+
+function organiseLibrary(oGroupByMode,homeProductToShow)
+{
+    view.docApp.selectedLibraryGroup = oGroupByMode;
+
+    //-- build the whole map in a local first, then assign it to the model in one go. Adding keys
+    //-- straight onto view.docApp.libraryGroups leaves every group after "unknown" unobserved by
+    //-- Vue 2 (it cannot see properties added to an already-reactive object), so in-place edits to
+    //-- a group - adding/removing a book, changing a count - would never re-render. //-- SG
+    let builtGroups = {"unknown":{title:"Other",description:"",icon : "images/products/hornbill-square.svg", books:[]}};
+
+    //-- loop library content and put into groups
+    let groupByMode = oGroupByMode.name;
+    for(let x=0;x<view.docApp.library.books.length;x++)
+    {
+        if(view.docApp.library.books[x].hasOwnProperty(groupByMode))
+        {
+            //-- 11//07/2023 - fix audience so either public or internal (because at moment we have some books where audience is set to private and private.dev etc)
+            if(groupByMode==="audience" && view.docApp.library.books[x].audience!=="public")
+            {
+                view.docApp.library.books[x].audience = "internal";
+            }
+
+            let groupingName = view.docApp.library.books[x][groupByMode];
+            if(!builtGroups.hasOwnProperty(groupingName))
+            {
+                 let newGrouping = {id:groupingName,mode:groupByMode,title:groupingName,description:"",icon : "images/products/hornbill-square.svg",books:[]};
+                 builtGroups[groupingName] = setLibraryGroupTitleAndDescription(newGrouping);
+            }
+
+            builtGroups[groupingName].books.push(view.docApp.library.books[x]);
+
+        }
+        else
+        {
+            //-- needs to go into "uncagtegorised" or "other"
+            builtGroups["unknown"].books.push(view.docApp.library.books[x]);
+        }
+    }
+
+    //-- single assignment - Vue observes builtGroups in place, so every group is now reactive
+    view.docApp.libraryGroups = builtGroups;
+
+    if(homeProductToShow &&  view.docApp.libraryGroups[homeProductToShow])
+    {
+        view.docApp.libraryHomeViewProduct = view.docApp.libraryGroups[homeProductToShow];
+    }
+    else
+    {
+        view.docApp.libraryHomeViewProduct = null;
+    }
+
 }
 
-async function fetchJsonFile(strFilePath) {
-	return await fetch(strFilePath)
-		.then((response) => response.json())
-		.then((jsonObject) => {
-			return jsonObject;
-		});
+
+//-- fetchOptions is optional and passed straight to fetch() - used to hand in an
+//-- AbortController signal for the search request. //-- SG
+function fetchJsonFile(strFilePath,fetchOptions)
+{
+  //-- the try/catch that used to sit around response.json() could never fire: json()
+  //-- returns a promise and rejects asynchronously, long after the try block has exited,
+  //-- so a malformed body became an unhandled rejection and the caller's await never
+  //-- resolved usefully. Catch on the promise instead. //-- SG
+  return fetch(strFilePath,fetchOptions).then(function(response)
+  {
+    if(response && response.ok)
+    {
+        return response.json().catch(function(e)
+        {
+            hslDocLog.log("fetchJsonFile: bad JSON body from ["+strFilePath+"]",e);
+            return null;
+        });
+    }
+
+    return null;
+  });
 }
 
+
 //-- THE INIT APP CALLED FROM index.html
-//$(".document-body").attr("v-pre", "");
-
-const view = new Vue({
-	el: "#vDocDevApp",
-	data: {
-		userSession: {},
-		updateCounter: 0,
-		bookId: "",
-		docApp: {
-			error: "",
-			inlinePopupDocumentHref: "",
-			showInlineDocumentsMarkup: false,
-			keepTocLayout: false,
-			book: {},
-			navSections: [],
-			inlineDocumentItems: [],
-			tableOfContents: [],
-			bookBreadCrumb: [],
-		},
-	},
-	methods: docAppMethods,
-	directives: {
-		somedirectivename: {
-			bind(el, binding, vnode) {
-				//-- do something when created on element
-			},
-		},
-	},
-	mounted: () => {},
-});
 
-//-- repeatable conmponent for nav sections
-Vue.component("nav-section-component", {
-	props: ["asection"],
-	template: "#nav-section-template",
-	methods: {
-		toggleNavCollapse: function (navSection) {
-			navSection.expand = !navSection.expand;
-			this.$forceUpdate();
-		},
-	},
-});
+//-- here it is important to add v-pre to document-body content div so that vue does not process any vue type sytnax in the document content i.e. without this vue would try parse out {{dob}}
+//$(".injected-document-content").attr("v-pre","");
+document.querySelectorAll(".document-body").forEach(function(el){ el.setAttribute("v-pre",""); });
+
+//-- repeatable conmponent for nav sections.
+//-- registered BEFORE the app is created: Vue 3 resolves components from the app instance, and
+//-- hbCreateApp copies the registry at creation time, so anything registered afterwards would
+//-- not be visible to this app. (Vue 2 had a global registry and did not care about order.)
+hbVue.component('nav-section-component', {
+    props: ['asection'],
+    template: '#nav-section-template',
+    methods:{
+        toggleNavCollapse:function(navSection)
+        {
+            //-- no $forceUpdate() needed: navSection reaches us through the reactive proxy, and
+            //-- renderNavigation() seeds expand, so this assignment triggers a targeted re-render
+            //-- rather than needing a forced repaint of the whole component. //-- SG
+            navSection.expand=!navSection.expand;
+        }
+    }
+ });
+
+//-- `data` is a function in Vue 3 - an object literal is no longer accepted, because every app
+//-- created from the same options object would otherwise share one state object. //-- SG
+//-- Reveal the app once a view is ready.
+//--
+//-- hb-hidden is a PRE-VUE guard: visibility:hidden !important from a static <style> so the
+//-- uncompiled template - raw mustaches, v-if markup - is never painted while Vue boots. That
+//-- is exactly why it cannot be a Vue binding: before Vue runs, a :class attribute does nothing
+//-- and the flash comes back.
+//--
+//-- So it belongs on the mount host and nowhere else. The host is the one element Vue does not
+//-- own - it renders INTO it - which is what makes removing the class here safe. The same class
+//-- on elements INSIDE the template was redundant (visibility inherits) and was a latent copy of
+//-- the bug that killed the search Filters button: Vue rewrites the static class list on every
+//-- re-render and puts the flag straight back. //-- SG
+function revealApp()
+{
+    //-- index.html loads its stylesheets non-render-blocking (media="print" flipped on load) so
+    //-- the boot splash can paint without waiting for all 15 of them. The trade is that the app
+    //-- must not be revealed before they have applied, or it appears unstyled - so the wait moved
+    //-- from the browser's first paint to here. Re-entrant: queue once, and hbCssMarkReady() calls
+    //-- us back.
+    //-- Guarded on hbCssWaiters existing because _inline.html shares this file and does NOT set up
+    //-- any of this - there, and anywhere else without the globals, reveal is immediate as before.
+    if(window.hbCssWaiters && !window.hbCssReady)
+    {
+        if(window.hbCssWaiters.indexOf(revealApp) === -1) window.hbCssWaiters.push(revealApp);
+        return;
+    }
+
+    let host = document.getElementById("vDocDevApp");
+    if(host) host.classList.remove("hb-hidden");
+
+    //-- the old global $(".hb-hidden") sweep also cleared the content-loading hide, so this
+    //-- keeps that coupling rather than making every caller remember two things. Guarded
+    //-- because init calls this before `view` is assigned. //-- SG
+    if(typeof view !== "undefined" && view && view.docApp) view.docApp.contentLoading = false;
+
+    hbHideBootSplash();
+}
 
+//-- Tear down the #hbBootSplash boot state (markup and CSS both in index.html). Called from
+//-- revealApp(), which every success AND every failure path already funnels through - that matters
+//-- more than it looks: a splash that outlives a failed boot is a permanently spinning page, which
+//-- is worse than the blank one it replaced. The 20s CSS-only stall message is the last resort for
+//-- a boot that never reaches here at all.
+//--
+//-- Two-stage removal so the fade actually runs: class first (CSS transitions opacity to 0), then
+//-- display:none once it is done. The display:none is not cosmetic - the element is a fixed,
+//-- full-viewport layer, so leaving it at opacity 0 would swallow every click on the site. Belt
+//-- and braces on the teardown timer because transitionend does not fire if the element was still
+//-- inside its 250ms opacity hold (no transition to end) or if motion is reduced. //-- SG
+function hbHideBootSplash()
+{
+    let splash = document.getElementById("hbBootSplash");
+    if(!splash || splash.classList.contains("hbBootSplashGone")) return;
+
+    splash.classList.add("hbBootSplashGone");
+    splash.setAttribute("aria-hidden","true");
+
+    let removed = false;
+    let finish = function()
+    {
+        if(removed) return;
+        removed = true;
+        splash.style.display = "none";
+    };
+
+    splash.addEventListener("transitionend", finish, { once:true });
+    setTimeout(finish, 400);
+}
 
-const hslDocLog = {
-	_entry: [],
-	log: function (strMessage, varData) {
-		if (varData !== undefined) console.log(strMessage, varData);
-		else console.log(strMessage);
+var view = hbMount({
+    data: function(){ return {
+            docApp:{
+                //-- These 14 were previously never declared here, only assigned at runtime with a
+                //-- plain view.docApp.x = ..., yet every one of them is bound in index.html or
+                //-- _inline.html. Under Vue 2 that meant none of them were reactive and the app
+                //-- only repainted because of the scattered $forceUpdate() calls; Vue 3's Proxy
+                //-- tracks late-added properties, so declaring them is no longer a bug fix - it is
+                //-- for discoverability, and it is what lets the $forceUpdate() calls go.
+                //--
+                //-- Initial values are deliberately falsy-equivalent to the undefined they replace,
+                //-- so first render is byte-identical. loadingBookInfo especially MUST start false:
+                //-- the toolbar renders on v-if="!docApp.loadingBookInfo", so seeding it true would
+                //-- hide the toolbar until a book load finished. //-- SG
+                ThemePreference:"",
+                //-- content hidden while the next document loads - see revealApp() //-- SG
+                contentLoading:false,
+                //-- book navigation sidebar, open state on narrow viewports //-- SG
+                bookNavOpen:false,
+                //-- frontmatter layout class applied to #DocContent //-- SG
+                layoutClass:"",
+                userSession:null,
+                products:[],
+                title:"",
+                description:"",
+                node:"",
+                build:"",
+                inlineTitle:"",
+                loadingBookInfo:false,
+                altSearchText:"",
+                currentResultsSearchText:"",
+                validSearch:false, //-- TRUE = odd number of quotes, i.e. the search is INVALID (feeds the warning in index.html)
+                searchFilterBySpecificBookTitle:"",
+
+                boolSearchInProgress:false,
+                nextSearchCriteria:null,
+                searchText:"",
+                searchError:"",
+                //-- TRUE while the box holds a single character: no search can run (see the
+                //-- length gate in searchDocuments), so the results area says so rather than
+                //-- showing nothing or the previous query's hits //-- SG
+                searchTooShort:false,
+                //-- transient hint under the toolbar search box, for the one case where the
+                //-- length gate changes nothing on screen (Enter on a single character while
+                //-- reading a document) - see showSearchTooShortHint() //-- SG
+                searchTooShortHint:false,
+                searchMode:false,
+                //-- MCP catalog view (/mcp). Mutually exclusive with the search, library
+                //-- and book views - cleared wherever searchMode is. //-- SG
+                mcpCatalogMode:false,
+                mcpCatalog:{servers:[],loaded:false,error:false},
+                //-- key -> true/false while the "copied" tick shows on a connection field
+                mcpCopied:{},
+                searchResponse:null,
+                hasFilterByProducts:false,
+                searchFilteredProducts:{},
+                searchFilterBySpecificBookId:"",
+                searchResultFilteredItems:[],
+                //-- diagnostic keyword/semantic/both badges on search results are internal-only:
+                //-- hidden on the public site, visible on docs-internal and dev/localhost //-- SG
+                showSearchMatchBadges: window.location.hostname !== "docs.hornbill.com",
+                //-- audience filter is internal-only too: the public site hosts public books
+                //-- only, so a picker there is meaningless. Session-only state, deliberately
+                //-- not persisted to the /search url. Values mirror the hdocbook.json
+                //-- audience enum (hdocbook.schema.json in hdoc-tools) //-- SG
+                showAudienceFilter: window.location.hostname !== "docs.hornbill.com",
+                searchAudienceFilter:"",
+                //-- Content-type facet. Defaults to "0" (Documentation) because reference
+                //-- material is ~85% of the corpus, so an unfiltered search buries plain
+                //-- answers: "reset a password" returned four API pages before anything a
+                //-- non-technical user could act on. "" means All.
+                //-- On docs-internal only, the user's last explicit pick is restored from
+                //-- localStorage instead - see docTypeUserDefaultFilter() //-- SG
+                searchDocTypeFilter:docTypeUserDefaultFilter(),
+                //-- set when the default filter is hiding better matches than it is showing;
+                //-- drives the offer above the results so filtering never dead-ends
+                searchDocTypeRescue:null,
+                //-- set when the url's bid named a book that does not exist and the filter
+                //-- was cleared automatically - drives the explanation above the results
+                searchBookRescue:null,
+                //-- narrow-viewport filter panel visibility
+                searchFiltersOpen:false,
+                searchAudienceOptions:[
+                    {value:"",label:"All"},
+                    {value:"public",label:"Public"},
+                    {value:"private",label:"Private"},
+                    {value:"private.cloud",label:"Private: Cloud"},
+                    {value:"private.dev.platform",label:"Private: Platform Dev"},
+                    {value:"private.dev.apps",label:"Private: Apps Dev"},
+                    {value:"private.hdocs",label:"Private: HDocs"},
+                    {value:"private.elearning",label:"Private: eLearning"}
+                ],
+                frontmatterData:{}, //-- always an object, was initialised as [] //-- SG
+                keepTocLayout:false,
+                tocMobileOpen:false,
+                library:{},
+                libraryGroups:{},
+                libraryHomeViewProduct:null,
+                book:{},
+                bookInfo:null,
+                navSections:[],
+                tableOfContents:[],
+                selectedLibraryGroup : null,
+                groupModes:[
+                    {name:"audience",mode:"audience",title:"By Audience",layout:"column-list"},
+                    {name:"productFamilyId",mode:"product",title:"By Product", layout:"tiles"}
+                ]
+            }
+        };
+    },
+    methods:docAppMethods
+}, '#vDocDevApp');
+
+//-- Vue 3 compiles the mount element's innerHTML and leaves the element itself alone, so the
+//-- v-on:click that used to sit on #vDocDevApp is no longer compiled. index.html declares it as
+//-- data-root-click and we attach it here; _inline.html omits the attribute and so gets no
+//-- handler, matching what it did before. //-- SG
+hbBindRootHandler(view, '#vDocDevApp', 'click');
+
+//-- One delegated click handler for every link on the page, for the life of the session.
+//-- Bound here alongside the root handler so it is in place before any content is injected.
+bindDelegatedLinkHandler();
+
+var hslDocLog={
+    _entry:[],
+    //-- ring buffer. This used to push forever, and search entries retain whole response objects
+    //-- (300 results each), so a long-lived tab leaked steadily for output nobody reads unless
+    //-- they call dump(). //-- SG
+    _maxEntries:500,
+    log:function(strMessage,varData)
+    {
+        //if(varData!==undefined) console.log(strMessage,varData)
+        //else  console.log(strMessage);
+
+        this._entry.push({msg:strMessage,data:varData})
+        if(this._entry.length > this._maxEntries) this._entry.splice(0,this._entry.length - this._maxEntries);
+    },
+    dump:function()
+    {
+        for(let x=0;x<this._entry.length;x++)
+        {
+            console.log(this._entry[x].msg,this._entry[x].data || null);
+        }
+    }
+}
 
-		this._entry.push({ msg: strMessage, data: varData });
-	},
-	dump: function () {
-		for (let x = 0; x < this._entry.length; x++) {
-			console.log(this._entry[x].msg, this._entry[x].data || null);
-		}
-	},
-};
+//-- Both return a DOM element or null. They returned jQuery collections, which no-op when
+//-- empty; callers must now null-check, and every one of them does. //-- SG
+function vueContentContainer(){
+    return document.querySelector(".injected-document-content .vue-document-body");
+}
+function contentContainer(){
+    return document.querySelector(".injected-document-content .document-body");
+}
 
 async function intialiseApp() {
-	// set theme switch
-	$(".theme-switch-checkbox").prop("checked", ThemePreference === "dark");
-
-	jqDocumentHeader = $(".injected-document-content .document-header");
-	jqContentContainer = $(".injected-document-content .document-body");
-	//jqContentContainer = $(".injected-document-content");
-	jqLeftNav = $("#DocSidebarNav");
-
-	await fetchJsonFile("_books/library.json")
-		.then((data) => {
-			// Get docbook library list
-			view.docApp.library = data;
-			view.docId = view.docApp.library.books[0].docId;
-		})
-		.then(() => {
-			// Get hdocbook.json
-			fetchJsonFile(`_books/${view.docId}/hdocbook.json`)
-				.then((data) => {
-					view.docApp.book = data;
-					view.bookId = data.docId;
-					view.docApp.title = data.title || "";
-					view.docApp.description = data.description || "";
-
-					view.docApp.inlineDocumentItems = [];
-					view.docApp.inlinePopupDocumentHref = "";
-					view.docApp.showInlineDocumentsMarkup = false;
-					view.docApp.hasInlinePopupDocuments =
-						!!view.docApp.library.books[0].nav_inline?.items?.length;
-					if (view.docApp.hasInlinePopupDocuments) {
-						view.docApp.inlineDocumentItems =
-							view.docApp.library.books[0].nav_inline.items;
-						view.docApp.book.navigation.items.push(
-							view.docApp.library.books[0].nav_inline,
-						);
-					}
-
-					//-- now render out the nav menu
-					view.renderNavigation();
-
-					setTimeout(() => {
-						listenForHrefClicks();
-
-						//-- check if url is not root - in which case we need to load content for url
-						let initialLoadContentHref = window.location.href.replace(
-							`${window.location.origin}/`,
-							"",
-						);
-						const newInitialLoadContentHref = findFirstClickableBookLink(
-							initialLoadContentHref,
-						);
-						if (newInitialLoadContentHref !== undefined) initialLoadContentHref = newInitialLoadContentHref;
-						if (initialLoadContentHref) {
-							//-- find the link we are going to show and make sure parent/s are set to .expand=true
-							loadContentUrl(initialLoadContentHref, true, false);
-						} else {
-							hslDocLog.log("initial first view link to load is not present");
-						}
-						$(".hb-hidden").removeClass("hb-hidden");
-					}, 200);
-				})
-				.catch((data) => {
-					view.docApp.error = data;
-					$(".hb-hidden").removeClass("hb-hidden");
-				});
-		});
-}
+
+    document.title = "Hornbill Documentation";
+
+    view.docApp.ThemePreference = ThemePreference;
+
+    //-- get session info
+    hslDocLog.log("Hornbill docs get session");
+    await fetchJsonFile("_api/session/").then(function(sessionData)
+    {  
+        hslDocLog.log("Hornbill docs get session response",sessionData);        
+        if(sessionData && sessionData.type==="user")
+        {
+            hslDocLog.log("Hornbill docs set session set expires date time to browser locale")
+            sessionData.expiresDateTime = new Date(sessionData.validUntil).toLocaleDateString() + ' ' + new Date(sessionData.validUntil).toLocaleTimeString();
+            hslDocLog.log("Hornbill docs update vue session object model",sessionData);
+            //-- userSession is declared in data(), so assigning it re-renders the profile dropdown
+            //-- and the admin gear on its own - no $forceUpdate() needed. //-- SG
+            view.setSessionInfo(sessionData);
+        }
+    });
+    //-- eof session stuff
+
+
+    await fetchJsonFile("_books/products.json").then(function(data){
+
+        //-- alphabetical by display name - drives the Products filter list order; everything
+        //-- else looks products up by id, so sort order is free to be presentational
+        view.docApp.products = (data.products || []).sort(function(a,b)
+        {
+            return (a.name || "").localeCompare(b.name || "", undefined, {sensitivity:"base"});
+        });
+
+        return fetchJsonFile("_books/library.json").then(function(data){
+
+            // Get docbook library list
+            view.docApp.library = data;
+
+            //-- NOTE: book order is whatever the server returns; there is no client-side sort.
+
+            let startingLibraryProduct = urlGetParam(window.location.search,"product");
+            let startingLibraryMode = urlGetParam(window.location.search,"mode");
+            let selectLayoutMode = getLibraryLayoutByModeParam(startingLibraryMode);
+            organiseLibrary(selectLayoutMode,startingLibraryProduct);
+           
+        }).then(function(){
+
+            loadLibraryOrBookFromCurrentUrl()
+        });
+    });
+ }