Add support for app shell navigation via AMP Shadow DOM

[westonruter]

Note: This is somewhat of a prototype for what could be supported in AMP itself as seamless page transitions: https://github.com/ampproject/amphtml/issues/12981 / https://github.com/ampproject/amphtml/issues/14738

---

For a theme to support app shell via the AMP plugin, the bare minimum that needs to be done is:

0. Activate on PWA plugin.
1. Ensure your theme (and plugins) work entirely in the AMP plugin's Transitional mode. You must use Transitional mode as opposed to Standard mode for now. Make sure that you have “Serve all templates as AMP regardless of what is being queried” enabled.
2. Identify the element that contains the markup that changes as you navigate from page to page and wrap it with two function calls to indicate where the app shell container is:

<?php amp_start_app_shell_content(); ?>
    <?php get_template_part( 'content' ); ?>
<?php amp_end_app_shell_content(); ?>

3. Opt-in to AMP theme support for app shell by adding the following to your functions.php:

add_theme_support( 'amp', array(
    'paired' => true,
    'app_shell' => true,
) );

4. You should define an offline.php template in your theme.
5. [Deprecated] ~You should mark for precaching any scripts and stylesheets needed by the app shell. This can be done via:~

wp_style_add_data( 'foo-special-colors', 'precache', true );
wp_script_add_data( 'bar-special-behavior', 'precache', true );

For theme which adds support for AMP app shell see https://github.com/xwp/twentyseventeen-westonson. Note that this theme copies some code from the Twenty Seventeen parent theme in order to add make the necessary modifications. For example, the js/global.js file modified as per this diff. The theme has app shell behind a theme mod flag, so make sure you do wp theme mod set service_worker_navigation amp_app_shell via WP-CLI. See also how it adds skeleton content to the app shell. See also plugin to enable stale-while-revalidate caching strategy for navigation requests.

This was presented at CDS 2018; see related portion of talk.

For a demo of the app shell theme in action, see https://dev-showcase-pwa.pantheonsite.io/

See also this short screen cast: https://youtu.be/oAiIbhHdoXM

For some more background on this, see https://github.com/xwp/pwa-wp/issues/12#issuecomment-401843173

Todo

• [x] Identify the element that contains the content
• [x] Add a query var which is used to obtain the document without the content being populated; add another query var which is used to omit the content for the shell response. Make sure this is done before sanitizers run.
• [x] Preserve admin bar in shadow DOM.
• [x] Add dedicated element which contains the content regardless of the id.
• [x] Ensure all style and link elements get preserved during content isolation.
• [x] Add Shadow DOM JS in outer shell request.
• [x] Let shadow root element be direct child of content element. This avoids styling problems.
• [x] Synchronize title.
• [x] Synchronize body classes.
• [x] Synchronize nav menu item classes.
• [x] Add JS which is responsible for history management, navigation, fetching, and invoking Shadow DOM API. Intercept the clicks on links in the shell and in the shadow to then load the new shadow doc.
• [x] Bootstrap spa onto frontend, automatically swap out content with shadow DOM AMP doc when navigating to another page? This handles case of smooth transition when navigating after landing on a site for the first time before the service worker is installed. Afterward, the app she would be served instead.
• [x] Fix lack of trailing slash causes redirect which drops the required app shell query param.
• [x] Trigger an event on the document when a page is transitioned.
• [x] Transfer admin bar from shadow to shell document.
• [x] Use AMP Shadow streaming API.
• [x] Update the class name for the menu item the instant that it is clicked.
• [x] ~Flag that the deprecation of the non-streaming API would break this.~
• [x] Use async external script. Include in precache.
• [x] ~When declaring theme support, include the script handles to print in addition to shadow API script.~
• [x] Make sure that the AMP runtime does not conflict with our custom script which intercept clicks.
• [x] When content is extracted in shell, make sure that shell serves skeleton initially.
• [x] Make sure app shell has revision. Vary cache by navigation menus, theme mods, etc.
• [x] Figure out injecting into service worker for navigation. Disable preload and then override entirely the URL that is served.
• [x] Make sure app shell is precached, as well as offline and error inners
• [x] Implement two methods of integrating app shell: bootstrapping app shell onto SW-unmanaged page, and another where app shell loads the content from the start.
• [ ] Synchronize meta (link, meta, JSON-LD, etc)
• [ ] Omit admin bar from shell? Or rather, prevent app shell entirely if user is logged-in?
• [ ] Allow shadow doc request to respond with 400 if amp is disabled and so then cause navigation at top? No, just do not follow redirects from ?amp to not-?amp. If such a redirect happens, navigate the entire page.
• [ ] Stale while revalidate will be able to update. This can be done even on streaming by leaving script in the page which listens for broadcast update.
• [ ] Make sure that the app shell serves the appropriate initial body class based on whether or not the homepage is initially requested.
• [ ] Preserve amp-analytics in shadow DOM; analytics needs to be excluded from app shell.
• [ ] When requesting app shell contents force accepting sanitization
• [ ] How can we handle a case where a user navigate to a URL that has amp disabled. Add a fury fragment to indicate that the service worker should bypass the use of the app shell
• [ ] Scroll to content of it is out of view on mobile.
• [ ] Prevent navigation when # anchor link.
• [ ] Add support for navigating to anchors on other URLs.
• [ ] Download web components API JS to serve locally.

[westonruter]

Note that travis is failing due to Gutenberg being merged into core.

[westonruter]

We'll need to merge the updates to the underlying service worker code in #1261, as it will be merged before this is.

[googlebot]

So there's good news and bad news.

:thumbsup: The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

:confused: The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

[googlebot]

A Googler has manually verified that the CLAs look good.

(Googler, please make sure the reason for overriding the CLA status is clearly documented in these comments.)

[googlebot]

So there's good news and bad news.

:thumbsup: The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

:confused: The bad news is that it appears that one or more commits were authored or co-authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this state. It's up to you to confirm consent of all the commit author(s), set the cla label to yes (if enabled on your project), and then merge this pull request when appropriate.

ℹ️ Googlers: Go here for more info.

[mehigh]

@miina I've handled the 8 conflicts and issued a PR against this branch here which handles them: https://github.com/ampproject/amp-wp/pull/3931 This is an effort towards getting it closer to being merged.

[github-actions[bot]]

Plugin builds for 77fca7dee343477fb9fac1ea3a7bc2f0dbb79a61 are ready :bellhop_bell:!

• Download development build
• Download production build

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
4 out of 6 committers have signed the CLA.

:white_check_mark: westonruter
:white_check_mark: mehigh
:white_check_mark: delawski
:white_check_mark: dero
:x: indieisaconcept
:x: miina
_{You have signed the CLA already but the status is still pending? Let us recheck it.}