async function onReadyAsync() {
    // for the intro.html page
    //
    // this function is run when the DOM for the page has loaded
    // summary
    //  if the current protocol is http rather than https, redirect to https
    //  if login features are enabled, show login and logout buttons as appropriate
    //      otherwise hide login and logout buttons
    //  assign click handlers to buttons

    const logHdr = 'Intro.onReadyAsync: ';
    log(logHdr + 'enter');

    const PAGE_URL = urlUtils.getUrl('/intro.html');
    // get a URL for this page, to use for redirects

    var auth0Client = null;
    var authenticated = false;

    var theProtocol = location.protocol;
    // get the protocol (http or https) for the current URL

    log(logHdr + 'theProtocol=' + theProtocol);

    // if the current protocol is http, redirect to https
    // most mobile browsers will not allow access to location services without https
    if (theProtocol === 'http:') {

        log(logHdr + 'protocal is http, so we will set location.href to redirect to https');
        log(logHdr + 'about to set location.href');

        location.href = location.href.replace(/^http:/, 'https:')
        // we need HTTPS for the gelocation call
        // yes, it's safer to handle this server-side, but we may use Azure static websites
        // to host this site.  these web sites do not have a redirect feature.
        // they do have a "require https" feature, but if that is enabled the user gets an error
        // and we don't get a chance to redirect.

        log(logHdr + 'back from setting location.href');
        log(logHdr + 'leave');

        return;
    }

    const urlParams = new URLSearchParams(window.location.search);
    // parse the query string

    //var idProvided = securityStateUtils.getAllowed();
    //// has the user already provided the id?

    //idProvided = true;
    //// STUB, for local testing

    //log(logHdr + 'onReadyAsync: idProvided=' + idProvided);

    //if (!idProvided) {
    //    // if not

    //    log(logHdr + 'id not provided previously, so we check the query string');

    //    var hasId = urlParams.has(QUERY_STRING_KEY_ID);
    //    // does the query string have an id value?

    //    log(logHdr + 'hasId=' + hasId);

    //    if (!hasId) {
    //        // if not, redirect

    //        location.href = SECURITY_REDIRECT_URL;
    //        // redirect

    //        return;
    //    }

    //    log(logHdr + 'the query string has an id value');

    //    const qsId = urlParams.get(QUERY_STRING_KEY_ID);
    //    // get the id from the query string

    //    log(logHdr + 'qsId=' + qsId);

    //    if (qsId === QUERY_STRING_ID_VALUE) {
    //        // if the id is correct

    //        log(logHdr + 'storing the allowed flag, for next time');

    //        securityStateUtils.setAllowed(true);
    //        // set the value, for next time
    //    }
    //    else {
    //        // if the id is NOT correct

    //        location.href = SECURITY_REDIRECT_URL;
    //        // redirect

    //        return;
    //    }
    //}

    var hasClear = urlParams.has(QUERY_STRING_KEY_CLEAR_STORAGE);
    // does the query string have a clear storage value?

    if (hasClear) {
        // if so

        const clearValue = urlParams.get(QUERY_STRING_KEY_CLEAR_STORAGE);

        if (clearValue === 'true') {
            log(logHdr + 'we received a clear storage command in the query string, so we will clear all local storage');

            globalStateUtils.clearAll();
        }
    }

    $('#aLogin').click(async function () { await authUtils.doLoginAsync(PAGE_URL); });
    $('#btnLogout').click(async function () { await authUtils.doLogoutAsync(); });

    viewWidth = document.documentElement.clientWidth;
    viewHeight = document.documentElement.clientHeight;
    // store view width and height

    // alert('viewWidth, viewHeight = ' + viewWidth + ' x ' + viewHeight);

    // mutation-summary
    //$domObserver = $(document);
    //// get a jQuery object for the document
    //$domObserver.mutationSummary("connect", msCallback, [{ element: "div" }]);
    //// subscribe changes in the DOM relating to a div

    log(logHdr + 'view width=' + viewWidth + ', viewHeight=' + viewHeight);

    viewWide = (viewWidth >= 649);
    // is the view wide enough to show at least two lens cards across?

    const topBtnParents = $('.div-top-btns-nav');

    if (viewWide) {
        // if we will show more than one column of lenses

        topBtnParents.removeClass('justify-content-center');
        topBtnParents.addClass('justify-content-left');
        // left justify the buttons
    }
    else {
        // if we will show one column of lenses

        topBtnParents.removeClass('justify-content-left');
        topBtnParents.addClass('justify-content-center');
        // center the buttons
    }

    const showTabs = lensHtmlUtils.showTabsOrNot();
    // will the lenses page show tabs in lens cards?

    log(logHdr + 'showTabs=' + showTabs);

    if (showTabs) {
        // if the lenses page will show tabs

        $('#divSmScrnParent').hide();
        $('#divLgScrnParent').show();
        // hide small screen contents
        // show large screen contents
    }
    else {
        // if the lenses page will not show tabs

        $('#divSmScrnParent').show();
        $('#divLgScrnParent').hide();
        // show small screen contents
        // hide large screen contents
    }

    //$('#divParent').show();
    //$('#divFooter').show();
    //// show the site

    if (enableLoginFeatures) {
        // if login features are enabled

        if (authUtils._auth0Client === null) {
            // if we haven't yet stored in Auth0 client object

            auth0Client = await createAuth0Client({ domain: authUtils.AUTH0_DOMAIN, client_id: authUtils.AUTH0_CLIENT_ID });
            // allocate an Auth0 object
            // if the user has already authenticated, the auth0 object will be populated with an access token and user profile

            authUtils.setAuth0Client(auth0Client);
            // store the client
        }

        const tmrIsAuth = tmrUtils.newTimer('isUserAuthenticatedAsync').start();

        authenticated = await authUtils.isUserAuthenticatedAsync();
        // is the current user authenticated?

        tmrIsAuth.stop();
        log(logHdr + 'TIME: ' + tmrIsAuth);

        log(logHdr + 'authenticated=' + authenticated);

        if (!authenticated) {
            // if the user is not authenticated

            log(logHdr + 'onReadyAsync: user is NOT authenticated');

            var authCode = '';
            var authState = '';

            var hasCode = urlParams.has(QUERY_STRING_KEY_AUTH_CODE);
            var hasState = urlParams.has(QUERY_STRING_KEY_AUTH_STATE);
            // are the Auth0 values present in the query string?
            // if so, Auth0 put them there

            log(logHdr + 'onReadyAsync: hasCode=' + hasCode);
            log(logHdr + 'onReadyAsync: hasState=' + hasState);

            if (hasCode && hasState) {
                // if both values are in the query string

                log(logHdr + 'the query string has values for auth values state and code, so we will store those values in cookies');

                authCode = urlParams.get(QUERY_STRING_KEY_AUTH_CODE);
                authState = urlParams.get(QUERY_STRING_KEY_AUTH_STATE);

                authUtils.setAuthCode(authCode);
                authUtils.setAuthState(authState);
                // store auth code and auth state in cookies

                hasCode = true;
                hasState = true;
                // we have them now
            }

            if (hasCode && hasState) {
                // if the user has both of these query string parameters, we have data we can convert to tokens

                const tmrCreateAuth = tmrUtils.newTimer('createAuth0Client').start();

                auth0Client = await createAuth0Client({ domain: authUtils.AUTH0_DOMAIN, client_id: authUtils.AUTH0_CLIENT_ID });
                // allocate an Auth0 object
                // if the user has already authenticated, the auth0 object will be populated with info about the user

                tmrCreateAuth.stop();
                log(logHdr + 'TIME: ' + tmrCreateAuth);
                log(logHdr + 'atc auth0Client.handleRedirectCallback');

                await auth0Client.handleRedirectCallback();
                // process this data

                log(logHdr + 'bf auth0Client.handleRedirectCallback');

                authUtils.setAuth0Client(auth0Client);
                // store the client

                log(logHdr + 'onReadyAsync: atc auth0Client.isAuthenticated');

                authenticated = await auth0Client.isAuthenticated();
                // read the authenticated value again

                log(logHdr + 'onReadyAsync: bf auth0Client.isAuthenticated');
                log(logHdr + 'onReadyAsync: authenticated=' + authenticated + '(after call to handleRedirectCallback)');

                window.history.replaceState({}, document.title, PAGE_URL);
                // remove the querystring parameters
            }
        }

        log(logHdr + 'after if (!authenticated) block');

        if (authenticated) {
            // if the user is logged in

            log(logHdr + 'the user is logged in');

            const user = await authUtils.logUserAsync();

            $('#divLogin').hide();

            log(logHdr + 'hid the Login button');

            if (user !== null) {
                authUIUtils.updateUIForUser(user.given_name, user.picture);
                // update the Login menu with the user's name and picture
            }

            $('#divAccount').show();
            // show the account menu

            log(logHdr + 'showed the Account menu');
        }
        else {
            // if the user is NOT logged in

            log(logHdr + 'the user is NOT logged in');
            log(logHdr + 'hide the Logout button');

            $('#divAccount').hide();
            // hide the account menu
        }

        if (authenticated) {
            // if the user is authenticated now

            await licenseUIUtils.updtTrialMenuAsync(auth0Client);
            // update the Trial menu
        }
        else {
            // otherwise, hide the trial menu

            $('#divTrial').hide();
        }
    }
    else {
        // if login features are disabled

        $('#divLogin').hide();
        $('#divAccount').hide();
        // hide login and account menus
    }

    videoUtils.subscribeToEventsForVideo('video-1');
    videoUtils.subscribeToEventsForVideo('video-2');
    // subscribe to events for the videos

    $('#navPlaceholder').css('display', 'none');
    $('#navMain').css('display', 'flex');
    // now that we have updated the top nav, swap the real nav bar for the placeholder

    log(logHdr + 'SWAPPED the real menu for the placeholder menu');
    log(logHdr + 'leave');
}