For better or worse, layers are not a first-class concept in HTML. As far as a web page is concerned, the thing we’re calling a “layer” is just another element.

Fortunately, layers are a first-class concept in compositing engines, also known as “compositors.” Compositors are graphics-processing programs that “compose” the images that you see on the screen, usually from a stack of layers. The layers are often partly transparent, which is why they need to be composited in the first place.

So for our purposes, a “layer” is like a transparency—potentially very large—with some images on it.

It is helpful to think of a layer as a set of flat things suspended in a transparent material. Granted, this is not something you’re likely to encounter in the world, but it is easy enough to imagine.

It’s helpful because this is basically how “layers” work in CSS. Transparent areas are solid—you can’t “reach through” a layer to something behind it. Well, you can, by using pointer-events, but this introduces other problems. And for a layer that scrolls, even pointer-events won’t help you, since it will make the layer basically unusable. This, combined with the fact that pointer-events is not perfectly supported everywhere, and we are compelled to start by considering only such layers, that is, ones which are essentially mounted on glass.

What’s the point of layers?

How do you communicate the existence and relationship of layers?

The relationship between two layers is always that one is in front of the other—otherwise, they are effectively not layered.

So how do you know that you’re looking at two different layers?

• you can see the bottom layer behind the top one
  • because it’s offset
  • because it’s translucent
  • because parts of it are transparent
• because they move independently

<<layers rules>>

By default, user agents make html the scrolling container, and certain special behaviors accrue to this assumption, particularly as relate to mouse and keyboard input. When we break such defaults, we use this condition.

html
	scroll-behavior smooth
	overflow-x hidden
	&.not-scroll-layer
		overflow hidden

Normally, I’d use overflow-y scroll for a layer that supports scrolling, to ensure that the scrollbar is always visible, even when it’s not needed. Without an explicit setting, the default is overflow auto. The only benefit to using auto is that you don’t get a scrollbar when it’s not needed. But layers that are designed to support scrolling pretty much always need it, and using auto has unwanted side-effects as content is added and removed. First, the scrollbar “flickers” when it’s removed and restored, which is ugly and distracting. Second, it causes the recalculation of viewport-based units (chiefly, vw). Reassigning these units will cause unwanted layouts and paints. It turns out that the spec addresses this specifically.

• https://lists.w3.org/Archives/Public/www-style/2013Jan/0616.html
• https://drafts.csswg.org/css-values-3/#viewport-relative-lengths
• https://lists.w3.org/Archives/Public/www-style/2013Jan/0200.html

This is also the reason for using 100vw instead of 100% in full-screen, which is in turn used by scroll-layer(): it prevents elements from changing size just because a scrollbar is added or removed on the root (html) element. Layers should always have the full width of the viewport, and most layers have their own persistent scrollbar, meaning that they will match the width of other layers regardless of which layer is currently scrollable. Putting layers in fixed position also ensures that they get tucked “under” any other scrolling layer, rather than being “parented” by another scrolling container (in which case you’d see two scrollbars—a problem strenuously avoided here).

Note also that using -webkit-overflow-scrolling touch will cause problems, to wit, that the page becomes suddenly blank, among others.

http://patrickmuff.ch/blog/2014/10/01/how-we-fixed-the-webkit-overflow-scrolling-touch-bug-on-ios/

That said, there still major problems with scrolling on iOS.

Layers occupy the entire viewport, always. (At least, as things stand.)

This is kind of like a docking rule. But it’s only useful for layers because only layers can co-opt the entire viewport.

full-screen(left = 0)
	position fixed
	top 0
	left left
	width 100vw
	height 100vh

scroll-layer(compositor = true, smooth = true, left = 0)
	full-screen(left: left)
	overflow-y scroll                  // vs auto to prevent scrollbar flicker
	scroll-behavior smooth if smooth

	// Without this, Chrome is likely to repaint on every scroll.
	if compositor
		transform translateZ(0)

scroll (n.)
c. 1400, “roll of parchment or paper,” altered (by association with rolle “roll”) from scrowe (c. 1200), from Anglo-French escrowe, Old French escroe “scrap, roll of parchment,” from Frankish *skroda “shred” or a similar Germanic source, from Proto-Germanic *skrauth- (cognates: Old English screada “piece cut off, cutting, scrap;” see shred (n.)).¹

Just about all of the problems presented by layers are related to scrolling.

Dealing with scrolling will take some scripting. Let’s make a module.

<require module="space" />

Layers and scrolling scripts

// There are only a couple of jquery references, and I'll probably eliminate
// them.
define(['jquery'], $ => {
	<<closest tag>>
	<<scrolling>>

	// No exports
	return {};
});

In the future, new features could add layers. The objective here has been to deal with layers in a general way, without knowing exactly what layers may exist.

When you’re moving through space, nearby things pass quickly, and distant things move slowly. This is called the parallax effect.

This is an effect of the things’ physical arrangement in space. But the effect is so familiar that you can simulate a spatial arrangement by showing things (like layers) moving at different speeds.

The parallax effect is not limited to scrolling. It can apply to animations or generally any scripted sequence. But scrolling is a special case because the web has something like native support for parallax scrolling, via the transform-style: preserve-3d property.

This addition to the platform was presumably motivated by the fact that people were using javascript to achieve the effect, with uneven results. Native support for three-dimensional effects would make them smoother and thus more effective at creating the illusion. And indeed, parallax scrolling, such as it is used in games, can be extremely effective at creating a sense of space in two-dimensional projections. But I’d be the first to admit that, on the web in practice, it’s a gimmick with no semantic value. I would be the first, that is, if Dede M. Frederick of Purdue University hadn’t beat me to it. He studied the effects of parallax scrolling on “user experience” on the web and concluded that

although parallax scrolling enhanced certain aspects of the user experience, it did not necessarily improve the overall user experience.⁵

The paper spends a great deal of its attention on the “pleasure” associated with the parallax effect. But much of that pleasure is attributed to its “novelty.” Personally, I find parallax effects pleasing, even when they are pointless. And when it comes to the subject of this domain—Shakespeare—pleasure is the ticket; no other purpose is needed. But this is the architectural level, and architecture has no place for anything pointless. If willshake will use parallax, it will have meaning.

Just like HTML, SVG has a “link” element. Naturally, it’s far more verbose, but it’s a link.

<svg height="50" width="250"
		xmlns="http://www.w3.org/2000/svg"
		xmlns:xlink="http://www.w3.org/1999/xlink">
	<a xlink:href="/plays/Ham"
		 xlink:title="Hamlet">
		<rect x="0" y="0" width="100%" height="100%" fill="#ACE" />
		<text x="0" y="50%">The Tragedie of Hamlet</text>
	</a>
</svg>

When that SVG image is used inside of an HTML document, you’d expect those links to work just like reguar links.

There are several ways to use SVG inside of HTML. It can be inline, meaning that the actual text of the SVG is part of the HTML markup. That comes out like this:

You can also reference the SVG file. One way to do that is with the old img tag.

<img src="/static/images/sample_svg_with_link.svg" />

which comes out looking like this.

You can also “embed” the SVG. That looks like this.

Embedding the image creates a new “browsing context.” That’s the way that most SVG images are used in willshake, because that’s the only way to intercept their links.

It shouldn’t make any difference whether the svg.

Links inside of inline SVG are handled “naturally” by getflow. If we want to treat links inside of external SVG the same way (and of course we do), these extra measures are needed, since “interactive” SVG requires it to be embedded as an object (or embed), and embedded objects will not bubble click events up to the main document (where getflow would handle them).

To accomplish this, we have to check the page for such objects after every state transition (location change), since the change may have introduced new content. Some extra care is taken here to ensure that the requisite handlers wil persist in the face of such changes as well as updates to the objects themselves.

<require module="svg_links" />

function closest_tag(element, tag) {
	while (element) {
		if (element.nodeName == tag)
			return element;
		element = element.parentNode;
	}
	return null;
}

require(['getflow'], getflow => {
	<<closest tag>>

	// This is similar to getflow's document click handler.
	function svg_clicked(event) {
		const link = closest_tag(event.target, 'a');

		if (link && link.href && link.href.baseVal) {
			// This is the getflow from the parent window
			getflow.go(link.href.baseVal);
			event.preventDefault();         
		}
	}

	function ensure_svg_click_handler() {
		const svg = this.getSVGDocument();
		if (svg)
			svg.addEventListener('click', svg_clicked);
	}

	function setup_svg_links() {
		[].slice.call(
			document.querySelectorAll('object[type="image/svg+xml"]'))
			.forEach(obj => {
				ensure_svg_click_handler.apply(obj);

				// If the SVG hasn't loaded yet, try again when it has.  Add
				// this even if it's already loaded, because it might reload
				// later (at least during development).
				obj.addEventListener('load', ensure_svg_click_handler);
			});
	}

	window.navigating.on(setup_svg_links);
	setup_svg_links();
});

Note that duplicate listeners will not be registered even if the above happens multiple times.

If multiple identical EventListeners are registered on the same EventTarget with the same parameters, the duplicate instances are discarded. They do not cause the EventListener to be called twice, and they do not need to be removed manually with the removeEventListener method.⁹

Layers:

Scrolls/scrolling:

• 
• 
• 
• 
• (a pretty picture, though doesn’t illustrate much, I guess)