Forem: Daniel Schulz

Tend (and about Vibe Coding)

Daniel Schulz — Wed, 25 Mar 2026 09:23:52 +0000

It’s been a while since I’ve coded for myself. I did push an update on Ssstyles and JSSynth every now and then, but I haven’t done something new.

Why?

I needed a habit tracker to get on top of my health again. It needed to be easy to use and sync across devices without selling my data to ad companies, which means selfhosting. The awesome selfhosted list has a few projects, but…

Habitica looks really nice, but it’s a bit much. I didn’t want to gamify things.
Beaver Habits doesn’t support personal goals.
OpenHabitTracker just looks really clunky.

I also wanted to brush off my Vue skills. Time to do it myself, then!

Building it

I started with a very minimalistic approach: HTML, CSS and Typescript with Petite Vue on top for reactive components. Not only did things go out of hand quickly, with the entire content of the app being driven by user-defined input, but Petite Vue itself hasn’t been maintained in years (which is a shame - i really liked the project).

So I went to the other extreme and set up Nuxt. If all the content was dynamic anyway, why not go all the way. I know that Nuxt has some performance and accessibility problems, but my performance target is a bit lower when building an “app-like” project, as opposed to a traditionally content driven one. It turned out I could still reach good performance metrics, thanks to caching user content to an IndexedDB and SSR’ing the app skeleton. Wrangling Hydration issues was an ongoing problem, though.

I figured I could mitigate accessibility problems as best as I can with enough testing. Marcus’ book Accessible Vue was a great help, too.

I used my own CSS framework Ssstyles as the foundation and I really love having a functioning system. I did find some caveats that I fixed during the development process, but most of the base styles and components worked out of the box and were a breeze to use.

Deploying

I tried something new here. Tend deploys directly to Netlify, where it’s usable as a PWA. There are no accounts or tracking and everything stays on your device. That also means there’s no sync across devices. That’s why every new release also creates a new docker container with a database and a simple single-account-login. It doesn’t deploy anywhere, but it’s self-hostable.

I did read a lot about backend security and learned one or two things about attack vectors. I hope it holds up!

So if you have a home server, you can use the docker setup, or else install the PWA.

On Vibe Coding

At some point midway through, my employer gave me access to Claude Code. I tried it here and I have some thoughts.

I think, Claude can be a welcome help to unwelcome tasks. Figuring out what the unwelcome tasks are is the harder part. If you use it to write a some syntax you rarely use - fine (though you can just use MDN for that as well). But using it to write your entire app? That’s for people who don’t like coding. In that case: please don’t. You’ll ship code that you don’t understand, full of bugs, problems and security risks.

I used Claude to write JSDocs and Tests. Those are unwelcome tasks to me and the LLM is fairly competent at documenting. Tests needed some more guidance. I found that Context Rot was a major problem. If the list of things that it needs to keep in mind gets too large, it becomes forgetful. I mean, so do I, but the things I forget are “updating the version number” or “writing a JSDoc”, not “how does the app work” and - more importantly even “what did I already try”. Claude went in circles multiple times when the context was approaching its limit, proposing fixes, testing and reverting them, when the correct solution was a simple missing import.

Struggles continued with anything regarding accessibility. The amount of misinformation it gave me and the faulty code it wanted to write is baffling. Claude seems to love aria. Whenever I described a problem (e.g. “label xy is ignored by VoiceOver on MacOS”), it completely ignored the underlying issue and slapped some aria on top of it. At this point I can only discourage from trusting AI tools when coding barrier-free content.

Would I use Claude again? For my job, yes. For private projects - maybe not. I did find it helpful for testing and documenting, but the price (both monetary and in resources) is still very steep with no signs of coming down.

View Transitions outside the Viewport

Daniel Schulz — Thu, 14 Nov 2024 18:35:16 +0000

CSS View Transitions have landed in Chrome and are (for better or worse) widely available to most end users now. Safari is not far behind, with the feature being available in TP and Firefox is at least working on it.

I love how much simpler the implementation of multi-page transitions have become, but at the same time, I realized a big poet-peeve with them: Elements that are out-of-viewport start swooshing around wildly.

My blog deals with this with some Javascript. An IntersectionObserver sets the view-transition-name in a custom property while it’s visible. As long as it’s out of sight, the property is unset and the transition won’t trigger. It works, but it needs the HTML, Javascript, and CSS to depend on one another. In the spirit of keeping presentation matters to CSS, I’d like a simpler solution.

Another feature that might be able to help out has landed in Chrome recently: Scroll-driven animations. Sadly, this is only available in Chrome yet. Firefox has it behind a flag and Safari shows no signs of activity here. But we can fall back gracefully, either to the Javascript solution mentioned before or even to simply ignore viewport detection and show the animation anyway (This would be the case in Safari at the time of writing).

A simple transition

Let’s put it all together, starting with the view transition itself:

@media (prefers-reduced-motion: no-preference) {
    @view-transition {
        navigation: auto;
    }

    [data-view-transition] {
        view-transition-name: var(--view-transition-name, default-view-transition);
    }
}

<!-- on page1.html: -->
<div data-view-transition>Whoosh!</div>

<!-- on page2.html: -->
<div data-view-transition>Whoosh!</div>

Now you’ll see the div from page1.html transform into its version on page2.html upon navigation. The @view-transition at-rule in CSS initiates a crossfade on the whole document as well. The transition duration is set by default to 0.4s, but we can ass a few lines to control this:

@property --view-transition-duration {
    syntax: "<time>";
    inherits: true;
    initial-value: 0.4s;
}

::view-transition-group(*) {
    animation-duration: var(--view-transition-duration);
}

The duration is set by --view-transition-duration The @property rule at the top is entirely optional, but it lets the animation-duration fall back to 0.4s instead of an invalid value when we set --view-transition-duration: bogus.

Dealing with the viewport

Still, when an element is outside of the viewport at the time of a page transition, it will still animate, and sometimes pass into or over the entire visible screen without indicating where it hass come from or where it’s going. I find that behavior very irritating.

With scroll-driven animations, we now have a tool that can control styles based on a scroll and viewport-relative position. So we can also control the trigger for view transitions:

@property --view-transition-duration {
    syntax: "<time>";
    inherits: true;
    initial-value: 0.4s;
}

@keyframes enable-vt {
    0%,
    100% {
        --enable-view-transitions: none;
    }
    0.1%,
    99.9% {
        --enable-view-transitions: var(--view-transition-name, default-view-transition);
    }
}

@media (prefers-reduced-motion: no-preference) {
    @view-transition {
        navigation: auto;
    }

    ::view-transition-group(*) {
        animation-duration: var(--view-transition-duration);
    }

    [data-view-transition] {
        view-timeline-name: --enable-vt;
        view-timeline-axis: block;
        animation: linear enable-vt both;
        animation-timeline: --enable-vt;
        animation-range: cover;

        view-transition-name: var(--view-transition-name, default-view-transition);
        @supports (animation-timeline: --enable-vt) {
            view-transition-name: var(--enable-view-transitions);
        }
    }
}

The enable-vt keyframe animation can’t transition smoothly from none to a custom property with a text string, so it will do a hard cut. The animation-range triggers when the element enters or leaves the viewport even partially. The animation itself sets --enable-view-transition on 0.1% and 99.9% to trigger as promptly as it can. I want to enable view transitions as soon as we can get a hint of where the animation started or ended.

Finally --enable-view-transitions is set by the scroll driven animation to either none or a new custom property called --view-transition-name. It’s being set between being 0.1% and 99.9% of screen coverage, disabling view transitions both above and below the viewport (or left and right, whichever way you want to hold it). This new property is useful for setting individual animations on different elements. Each element can get its own transition by setting a unique value to --view-transition-name.

<div data-view-transition style="--view-transition-name: my-new-transition">Whoosh</div>

This needs to be done on both the source and the target page. If no value is set, it defaults to default-view-transition which controls all remaining data-view-transition elements uniformly.

Real-world implementation

I added this implementation to my little CSS boilerplate, Ssstyles. Giving an element the data-view-transition attribute on the source and target page will let it transition between both. Giving it a --view-transition-name will let it have its own unique animation, independent from other similar elements. Setting the --view-transition-duration controls the duration of the transition.

Building a MIDI instrument in TypeScript

Daniel Schulz — Mon, 15 Apr 2024 07:00:00 +0000

I recently put some work into my web synthesizer and even gave it its own domain at jssynth.xyz. I added some convenience features, but I also worked on a MIDI integration.

As with most of the more fringe APIs, the Web MIDI API is built as a mirror image of it’s non-web counterpart. It doesn’t support fully specced out events like onClick and its messages might be raw byte streams of hex numbers. There aren’t even unambiguous input events. Oh boy!

Anyways it is a way to connect a MIDI keyboard to a website and vice versa.

Before I go through the code, let’s state that the whole MIDI feature is wrapped up in a class. In the following snippets this will be the class context.

Permissions

The Web MIDI API requires permissions to work. Users are prompted with a dialog to grant or deny those permissions. I’m not a big fan of those prompts. They often come unsolicited and tend to get in the way. If a user doesn’t need MIDI functionality, there’s no need to annoy them. So I wait for them to select a MIDI in or out channel. Now I can ensure the user has interacted with the site in a way that they probably know how to respond to the MIDI permission prompt.

First, let’s deal with browsers that don’t support the MIDI API. It’s a bit ironic that those browsers are made by the company that markets heavily towards creatives.

Unsupported features shouldn’t be available in the UI.

if (!navigator.requestMIDIAccess) {
    this.disableMidi();
}

I consider undefined or negative values for MIDI channels as off. This is also the default value. Users have to actively select a channel to use this.

if (
    (this.inChannel < 0 || this.inChannel === undefined) &&
    (this.outChannel < 0 || this.outChannel === undefined)
) { return; }

Only then I will request MIDI Access, which will prompt the user for permissions.

navigator
    .requestMIDIAccess()
    .then(this.onMIDISuccess.bind(this))
    .catch((e) => {
        this.disableMidi();
    });

Now I can start listening for events.

Input

An arrow labeled with the MIDI logo points from a black keyboard towards a computer with the JSSynth logo on its screen.

MIDI doesn’t only work on multiple channels, it also supports those channels on multiple devices. I chose to ignore those devices. Instead, I handle all events from all devices as if it was one. I get enough granularity with MIDI channels (at least for now). I do understand that the proper solution would have been the other way around, as this is an existing convention called Omni Mode. But now I built it this way and it works for me 🤷

The MIDI API exposes an onmidimessage callback on its input devices, which provides a MIDI message.

inputDevice.onmidimessage = (message: string) => this.onMIDIMessage(message);

Those messages look something like this:

0x90 0x3c 0x2b

This command corresponds to to a keypress of the middle C on channel 0 with a key velocity of 33%.

A Diagram. The MIDI message 0x90 0x3c 0x2b gets converted to the decimal numbers 144 60 43, which then gets converted into the signal “play on channel 0 a middle C on 33% velocity.

This is how we can decode the message into human readable values:

parseMidiMessage(message: string): MidiMessage {
        const arr = message.split(" ");
        return {
            command: parseInt(arr[0]) >> 4,
            channel: parseInt(arr[0]) & 0xf,
            note: parseInt(arr[1]),
            velocity: parseInt(arr[2]) / 127,
        };
    }

With that, I can pass the information along to the synthesizer and start playing the note.

The interesting part here is the first part of the message, indicating the command and channel. MIDI can provide all sorts of commands and has been adapted even well beyond musical information (like stage lights and such). But there are some well defined commands, like play note on channel 1. This will always be MIDI command 144. As the command is being encoded in the hexadecimal number 90 and we only get 16 MIDI channels (from 0 to f), I can split it up into two hexadecimal digits: 9 being they play command and 0 being the channel.

Playing a note is only half the work though. As with my on-screen and keyboard controls, I need to register key releases as well, or else I’d play infinite notes. Key releases can come in two ways: Either as a release command (0x80 through 0x8f) or as a play command (0x90 through 0x9f) with a velocity of 0.

Now all of the input handling looks like this:

const data = this.parseMidiMessage(str);

if (data.channel === this.inChannel && data.command === 9 && data.velocity > 0) {
    this.playCallback(data.note, data.velocity);
}

if (
    (data.channel === this.inChannel && data.command === 8) ||
    (data.channel === this.inChannel && data.command === 9 && data.velocity === 0)
) {
    this.releaseCallback(data.note);
}

if (data.channel === this.inChannel && data.command === 8) {
  this.releaseCallback(data.note);
}

I don’t really support velocity in the synthesizer yet, but it felt better to built this in now. The callbacks look similar to the other play triggers in the synth code:

// in the Synth class
onMidiPlay(midiCode: number, velocity: number): void {
    const note = Object.keys(this.keys).find((x) => this.keys[x].midiIn === midiCode);

    if (!note) { return; }
    if (!this.keys[note]?.key || this.nodes[note]) { return; }

    this.playNote(note);
}

onMidiRelease(midiCode: number): void {
    const note = Object.keys(this.keys).find((x) => this.keys[x].midiIn === midiCode);

    if (!note) { return; }
    if (!this.keys[note]?.key || !this.nodes[note]) { return; }

    this.endNote(this.nodes[note]);
}

Output

An arrow labeled with the MIDI logo points from a computer with the JSSynth logo on its screen towards a black keyboard.

MIDI out woks basically the same, but the other way around. I let the Synth class hook into the MIDI adapter and call a function:

/**
 * Callback for MIDI-out from in-browser inputs.
 *
 * @param key - The key, e.g. 'c2'.
 * @param velocity - The velocity of the key.
 */
public onPlayNote(key: string, velocity: number): void {
    this.sendMidiMessage("play", key, velocity);
}

Then I need to put together a MIDI message, like the one I got above. I get the MIDI code for the note from a big ol’ object matching the two. Calculating the notes programmatically is possible. but I had the object anyways, because it also holds information for keyboard shortcuts (keyboard meaning the computer input device).

The MIDI command is compiled from the out channel and the playNote command code (0x90 through 0x9f). The velocity gets passed through, but will always be 1 for now. Convert the three values into hexadecimals and push them out across all devices.

/**
 * Sends out a MIDI message.
 *
 * @param command - The MIDI command.
 * @param note - The MIDI note.
 * @param velocity - The velocity.
 * @returns
 */
sendMidiMessage(command: string, note: string, velocity = 0): void {
    if (this.outChannel < 0 || command !== "play" || !this.midi) {
        return;
    }

    const midiCode = Keys[note].midiIn;
    const midiCommand = "0x" + ((9 << 4) | this.outChannel).toString(16);
    const midiVelocity = "0x" + (velocity * 127).toString(16);

    this.midi!.outputs.forEach((outputDevice) => {
        outputDevice.send([midiCommand, midiCode, midiVelocity]);
    });
}

Since MIDI key releases can be either the release command or the play command with a velocity of 0, I can save a few lines of code and use the same function to send key releases. The synth just needs to pass a 0 velocity along.

this.MidiAdapter.onPlayNote(key, 1); // play
this.MidiAdapter.onPlayNote(key, 0); // release

UI Changes

The obvious additions are select fields for the MIDI channels, but that’s not all.

Before, the Synthesizer supported one whole octave. That was enough to play around a bit, but not really useful for anything. I support MIDI input now, but it wouldn’t be fair to provide all those extra notes only to dedicated hardware. So I added two more octaves, showing up as the screen width increases.

The JSSSynth UI in three different viewport sizes. The left-hand one shows one octave and vertically stack controls. The middle one shows one active with horizontally stacked controls. It’s keys are labeled with keyboard shortcuts. The right-hand one is the same, but wider and showing two octaves.

In the process, I got rid of my Sass workflow. I only used it for nesting anyway and CSS supports that natively now.

Demo

You can try it out yourself on https://jssynth.xyz.

Code

As always, the full code can be found on GitHub.

Ssstyles - a classless stylsheet

Daniel Schulz — Mon, 08 Jan 2024 09:26:13 +0000

I really like the idea of a classless CSS stylesheet that can be applied to just about any website. There are already a few examples out there, as listed below. But none of them really ticked all the boxes for me. I wanted to have my own shot, so I made Ssstyles.

Classless stylesheets are ones that apply directly to HTML tags. I like their spirit of simplicity and separation of concerns. You can even mix and match styles looks across websites.

Most of the projects I stumbled upon work really well already, but there was still something missing, like themes for dark and high contrast mode, or configuration options. Some other features I included are:

Color theme and high contrast mode
Seamless Font scaling
Configurable fonts
Definition lists
Dialog and Details/Summary
Accent colors

When I put it together, I started experimenting and built some UI elements, that didn't fit into a classless stylesheet. But they were still handy to have. I added them as optional components, tree-shakeable via css imports.

Comparing Classless Stylesheets

Here’s a comparison between things that I wanted in a classless stylesheet. It favors Ssstyles, of course, because I made it fit my own needs. Take this table with few big grains of salt.

Name	File Size (gzip)	Configurable	Color Schemes	High Contrast Mode	Font Scaling	Extensions	Opinionated *
https://iamschulz.github.io/ssstyles/base-styles/	2.4 kB	Fonts, Colors, Border radius, Container width	✅	✅	✅ (seamless)	✅	very
https://watercss.kognise.dev/	3.5 kB	Colors, Scrollbars, Animation duration	✅	❌	❌	❌	a bit
https://codepen.io/mblode/pen/JdYbJj	2.9 kB	Fonts, Colors, Spacing, Border radius	❌	✅ (default)	❌	❌	very little
https://simplecss.org/	3.7 kB	Fonts, Colors, Border radius	✅	❌	✅ (breakpoint)	❌	very
https://v2.picocss.com/docs/classless	9.3 kB	only in Sass	✅	❌	❌	✅	a little
https://github.com/edwardtufte/tufte-css	2.2 kB, but loads fonts	❌	✅	✅ (default)	❌	❌	very
https://github.com/marcop135/bullframe.css	4.2 kB	only in Sass	✅	✅ (default)	❌	✅	very little
https://newcss.net/	1.9 kB	Fonts, Colors	✅	✅ (default)	❌	❌	very little
https://boltcss.com/	2.3 kB	Colors, Border radius	✅	✅ (default)	❌	❌	very little
https://yegor256.github.io/tacit/	1.8 kB	❌	❌	✅ (default)	❌	❌	a little
https://writ.cmcenroe.me/	1.0 kB	❌	❌	✅ (default)	❌	❌	very
https://raj457036.github.io/attriCSS/	1.4 kB, but calls a google font	❌	❌	❌	❌	❌	very

(I got most of those projects from this CSS-Tricks article.)

(By opinionated I mean extravagant design choices that look like they take some extra steps to overwrite.)

I think I struck a good balance between a small file size and features.

Color theme and high contrast mode
Seamless Font scaling
Configurable fonts
Definition lists
Dialog and Details/Summary
Accent colors

Components

Ssstyles brings a classless base package, but can be extended with optional components that hook into the base styles, so it all comes together seamlessly. That keeps the file size of the base package low and lets me experiment with UI components a bit more freely. The base package is meant to provide some baseline styles for new projects, as well as enhancing existing websites. That’s why I kept it classless, I want it to just work with plain old HTML.

However, just a classless Stylesheet wasn’t enough for me as a boilerplate for new projects. So I figured, I can just add some optional components and split the code. Now there’s the base stylesheet, the complete stylesheet and an npm package that lets you import individual components.

npm install ssstyles

@layer base, layout, components;
@import "ssstyles" layer(base);
@import "ssstyles/css/transition.css" layer(base);
@import "ssstyles/css/basegrid.css" layer(layout);
@import "ssstyles/css/headline.css" layer(components);

Since my stylesheet is meant as a baseline for projects to build upon, CSS Layers are an excellent tool to encapsulate my styles from project-specific ones. Having everything inside a layer keeps specificity low, so everything can be overwritten. Having my base, layout and components layers lets me put my code inside components and still sort by their level of styling granularity:

base includes rules which affect the whole website. The classless stylesheet, including the config variables go here, so do some variables I need for combined transitions across components.
layout includes rules which affect their children. This would include the base layout, but also grid components, breakouts, and so on.
components include rules which affect only their respective UI element.

On top of that comes everything specific to the project itself. You could even put something like Tailwind of top.

Fun with variables

I think variables were the single largest improvement in CSS in a very long time. They’re the answer to so many problems that would have been impossible to solve without. I use them to solve dependency across layers for two different aspects: transitions and border radius.

Transitions are grouped together into one property:

transition: box-shadow 0.2s, translate 0.2s;

That means that each component can only set one transition. That’s a problem, because some components are meant to be combined, for example Card and Shadow. A clickable card has a transition on its translate, because it raises a few pixels when hovered. A shadow can be enlarged when hovered. This will set the transition to box-shadow, overriding the translate.

What I’ve done is set a transition for lots of animatable properties on a global selector. The transition time is set to a variables that defaults to 0s, which disables the transition altogether.

Now I can set the transition time variable for position to 0.2s in the Card component and do the same for box-shadow in the Shadow component. This will activate the transition for only the properties with a corresponding variable.

* {
    transition: 
        transform var(--t-box-shadow, 0s) ease-out, 
        translate var(--t-translate, 0s) ease-out,
        /* ... *(
}

[data-card] {
    --t-translate: 0.2s;
}

[data-shadow] {
    --t-box-shadow: 0.2s;
}

And now <div data-card data-shadow> can have two different transitions.

I had a related problem with border-radius. Normally I want to set it at the component level. Except for that one case when it’s dictated by its parent element: the Group. I want grouped elements to stick together and eliminate rounded edges in between. But since the component layer comes after the layout layer, the former would always overwrite the latter. I could use the infamous !important on the group, but that would mean that no-one ever could enable them again for whatever reason without using !important again later in the code.

Variables to the rescue!

I set the border radius in my components to variables with the pre-defined --border-radius as a fallback:

border-radius: var(--br-tl, var(--border-radius)) var(--br-tr, var(--border-radius))
        var(--br-br, var(--border-radius)) var(--br-bl, var(--border-radius));

When --br-xx is unset, the --border-radius from the config file is used in the respective corner (-tl refers to top-left). That means that anything could set the --br- variable without affecting the border-radius property directly - even the Group that normally loses to elements on the component layer.

[data-group] > *:first-child {
    --br-tr: 0;
    --br-br: 0;
}

[data-group] > *:last-child {
    --br-tl: 0;
    --br-bl: 0;
}

Now elements within a group only have rounded corners on the outside edges of the group itself.

Future plans

I’d like to include a thing that calculates themes automatically based on only a given hue and saturation value. I built something like that before, but it needed some correctional values for changing hues. Now that OKLCH is available and we have Level 5 color functions, that should be more manageable. Maybe also include a few themes as well, while I’m at it.

I also really wanted to build on typed CSS properties. Having type safe config variables sounds awesome! Sadly, I’m a bit early. Firefox will release the @property ruleset with version 124, which is set to release in early 2024. As a typed config will be the very foundation of the stylesheet, I would end up either with duplicate code for a fallback, or have it not working at all in Firefox. I don’t like either way, so I’ll just wait a bit for some wider adoption of typed properties.

I'd also like to have a solution for variables in media queries. Right now I'm using a media query in the Base Layout, to break the navigation out of the content area to the side, when enough space is available. CSS variables in media queries don't work, because you could circle-reference variables. But that argument didn't hold water in the discussion about container queries either. I'm holding my hopes for the future. Until then, I can't really provide a way to configure this media query.

View Transition API

Daniel Schulz — Fri, 26 May 2023 06:46:40 +0000

The view Transition API is probably one of the most exciting new CSS mechaninsms. It's currently only available in Chrome Canary, but that's okay. It's designed from the ground up to be a progressive enhancement. It promises to provide a native way to build SPA-like page transitions. (Heck, forget about SPAs. Think of cinematic wipes. Video game manus! Remember fancy DVD menus?)

Basic setup

First of all, we need to enable two flags on Chrome Canary, because View Transitions are still an experimental feature. The flags you’re looking for are view-transition and view-transition-on-navigation.

To get it running on our page we need to set a meta tag on both the document we're navigating from and the one we're navigating to.

<meta content="same-origin" name="view-transition" />

When navigation from one oage to the other, we see a crossfade between the sites. This is the default transition. We can also assign custom ones:

::view-transition-old(root), ::view-transition-new(root) {
    animation: var(--my-fancy-animation-out);
}

We can also assign animations to selected elements. That's the way to those bespoke transitions where elements swoop magically into place.

::view-transition-old(swoop),
::view-transition-new(swoop) {
    animation: var(--my-fancy-animation);
}

.element {
    view-transition: swoop;
}

(Website mock-up and image by the Chrome Dev team)

Speaking of magically, elements morph their position and crossfade their content. This happens automatically by fading out the old element and fading in the new ones instead. We can also set custom animations to both the disappearing and the apperaing content:

::view-transition-old(root) {
    /* let the old element disappear in some form */
    animation: var(--my-fancy-animation-out);
}

::view-transition-new(root) {
    /* show the new element instead */
    animation: var(--my-fancy-animation-in);
}

Fine tuning

For now, animations will always trigger whenever they can. This may have some unwanted side effects. It's nice to see where similar elements come from and go to between navigations, but when they're coming from out of screen, things get confusing quickly.

We can use an Intersection Observer to set the element's view transition only when it's in screen:

const observer = new IntersectionObserver(
    (entries) => {
        entries.forEach((entry) => {
            const el = entry.target as HTMLElement;
            const transitionName = el.dataset.transitionName;
            (el as HTMLElement).style.setProperty(
                "--transition-name",
                entry.isIntersecting ? `${transitionName}` : "none"
            );
        });
    }
);

const animatables = Array.from(document.querySelectorAll('.animatable'));
animatables.forEach((animatable) => {
    observer.observe(animatable);
});

.animatable {
    view-transition: var(--transition-name, none);
}

Sometimes we want to play the transition only in one direction, but not into the other. As an example, I see how the full page crossfade is necessary to support custom transitions on selected elements, but on pages that have no custom transitions, the crossfade loses its right to exist. I could simply remove the meta tag on the target page, but if the target page itself needs to act as a trigger for another view transition to somewhere else, that won’t work either. My solution is to register an event listener on anchor element clicks and remove the meta tag before the browser navigates, cancelling the view transition on all but some selected trigger elements:

const triggers = Array.from(document.querySelectorAll('[data-transition-trigger="true"]'));

(Array.from(document.querySelectorAll("a[href]")) as HTMLAnchorElement[]).forEach((el) => {
    if (triggers.includes(el)) {
        return;
    }

    el.addEventListener("click", () => {
        document.querySelector('meta[name="view-transition"]')?.remove();
    });
});

Now I can fine tune which transitions start on which elements by setting data-transition-trigger="true" on <a href=""> tags.

Jank

Some things feel a bit weird or buggy.

Like described above, it’s hard to create specific transition triggers and endpoints. Sometimes it makes sense for an animation to play only one way, But setting the view-transition property acts as both a trigger and receiver, all the time.

Elements in a transition seem to ignore the stacking context in some cases. Absolutely positioned and sticky elements will display underneath transitioning ones, even when applying (and forcing) z-index.

Scaling an element up doesn’t work properly yet. I can set transform: scale() to positive values, but it will just disable the animation and skip to the new state instead.

Sometimes I can’t overwrite properties that are set to an element. Transitioning background-colors only works of opacity is set. opacity can’t be overwritten whatsoever, but visibility works.

I’m sure most of those bugs are actually just bugs in Chromes current implementation. It’s experimental after all.

Na na na na na na na na Batman!

When I think of transitions, I think of cinematic ones. There are a few iconic ones, like the slow soft wipe in Star Wars or that weird back-and-forth in Easy Rider. But 60’s Batman swirls are probably the most fun ones, to watch and to implement.

Rotating the document should be straightforward enough with a spin animation:

@keyframes spin {
    to {
        transform: rotate(2turn);
    }
}

But that Batman logo zooming around? Remember how scaling elements up didn’t work properly? There’s a hack we can use to work around that problem. Upscaling doesn’t need to be a transform: scale() function. We can also use transform: translateZ(). This one needs to stay at 1px, or else it bugs out again, but we can animate the perspective freely, making it something like the web equivalent of a vertigo shot. I’ll use the animatable visibility property to hide it outside the animation, because opacity - you guessed it - is buggy. It will substract the element’s base opacity from the animation’s opacity and thus never become visible at all.

@keyframes scale-up {
    from {
        visibility: visible;
        transform: perspective(400px) translateZ(1px);
        background: url(./logo.png) center no-repeat;
        background-size: contain;
    }

    to {
        visibility: visible;
        transform: perspective(1px) translateZ(1px);
        background: url(./logo.png) center no-repeat;
        background-size: contain;
    }
}

::view-transition-old(batman) {
    animation: 0.5s linear both scale-up;
}

::view-transition-new(batman) {
    animation: 0.5s linear both scale-down;
    animation-delay: 0.5s;
}

#logo {
    position: absolute;
    top: calc(50% - 50px);
    left: calc(50% - 50px);
    width: 100px;
    height: 100px;
    visibility: hidden;
    view-transition-name: batman;
}

Try it out here!

The language that grew up with me

Daniel Schulz — Sun, 22 Jan 2023 21:55:26 +0000

You know those kid’s bikes that you can upgrade from a balance bike to a something that will take your child to elementary school? CSS did something like that for me.

I can still remember the days of floating layouts. We used a lot of hacks to get things to behave like we wanted them to, like the Clearfix or browser-detecting media queries. The designs were just starting to move from table-based layouts to the box model, which allows a bit more freedom and flexibility in its implementation, but pixel-perfectness was still the gold standard of layout execution.

I felt clever writing CSS under those limitations. My code was illegible, my hacks were obscure and I got the thing working somehow. CSS just wasn’t as good at getting the job done in a clean and efficient way (which is probably where it picked up its bad reputation that it still has today).

But CSS grew up and so did I.

Webfonts were a huge milestone for me. I could do some typography on the internet without using images, and their sprites respectively. Gradients and rounded corners as well for similar reasons. It felt like taking the training wheels off my code.

I recently explained to a younger developer what image sprites were. He was baffled that we needed something like this and amazed at the ingenuity and jank of it in equal parts. Hey, skeuomorphism can be really hard with just SVGs! Speaking of which, SVGs have only been natively supported in Internet Explorer since version 9.

I don’t need dirty hacks anymore just to code basic layouts. grid and flex are powerful tools (Firefox is even pushing for native masonry). Layouts have become more complex, but media queries help to adapt to the user’s needs. Websites aren’t as monolithic anymore. We’re putting them together component by component. I still love BEM and I really like CUBE as methodologies to do so, and I’m very looking forward to introduce and container and style queries to my workflow.

Over time, I added parts that helped me achieve more mature projects fast and efficiently. I replaced the training wheels with a crankset, and shifters, and proper brakes… I learned to use the right tool for the job and CSS kept providing me with them.

Not knowing things

Daniel Schulz — Thu, 12 Jan 2023 23:00:00 +0000

Chris Coyier updates his stance on his Great Divide theory:

"Since there is too much for any web developer to know, what is the most graceful and professionally acceptable way of not knowing things?"

I think the answer is honesty.

It's okay to say that you don't know stuff. My workplace pits me against the Great Unknown all the time: a huge complex monster of a core product. Internal tooling inherited from another team. Custom hacked docs generation, all undocumented. Legacy Code. Almost all of it is written in TypeScript, which I don't even consider my strongest language.

While I can always look up syntax I don't know online, I can't do the same for our own concepts. That's when I ask for help. I admit that I don't know all the things. And that's okay.

SpeedKit is the largest and most complicated project I’ve ever worked on. It took me half a year of onboarding (and struggling with Impostor Syndrome) to become somewhat productive and stop feeling like a chain on my coworkers legs. To implement features on my own. And that's when my coworkers started asking me question about my features. Turns out they don't know everything all at once either. And we are just on the JavaScript-side of the divide. Imagine if we started to write CSS on the job!

It's okay to ask questions. It's normal to not know all the things. If I can be honest about the things I don’t know, so can others. And if everyone does, it creates a office culture of helping each other out - gracefully and professionally.

From Notion to Eleventy, but faster

Daniel Schulz — Fri, 23 Dec 2022 10:08:36 +0000

I don’t usually do multipart posts, but this one grew a bit after I published the initial article. The setup I’ve got there describes how to import content from Notion to Eleventy and render a site. But it’s getting very slow very soon.

Webhooks

I described how to use Zapier as a deployment method. Two weeks later I found out that their generic webhooks are free only in their grace period. I don’t make any money with my site, so I think it’s fair to stay on free services all around. I switched to Pipedream, which provides generic webhooks in its free plan indefinitely.

Caching

As I started to import all my content into my new blog setup, build times grew to a slouch, easily exceeding 15 minutes. All those Notion requests were taking their toll. I needed one request against the page containing all blog posts, one request to get the blog post page and one request for each post’s content. One or two additional ones for long articles, because they’re paginated (which I didn’t take into account before, either). Multiply that by 3 for each of my sections and you get a lot of time to play Memory.

Eleventy has this nice caching plugin called Eleventy-Fetch, which will fetch and cache the request for a given duration. It takes a URL and will fetch that. There’s just one problem: I was using the Notion Client, which will only take an ID. There are no URLs involved:

const { Client } = require("@notionhq/client");
const notion = new Client({ auth: process.env.NOTION_KEY });

const db = await notion.databases.query({
    database_id: process.env.NOTION_BLOG_ID,
    sorts: [
        {
            property: "Date",
            direction: "descending",
        },
    ],
});

There’s a feature request in Eleventy-Fetch to work with functions like that, but as far as I can see, no one’s working at the at the moment. It’s nice to work with the client, but in order to cache those results, I need to switch to plain old URLs that I can feed to Eleventy-Fetch. Notion’s docs describe how to curl page content:

curl https://api.notion.com/v1/blocks/16d8004e-5f6a-42a6-9811-51c22ddada12/children?page_size=100 \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2022-06-28"

Translated into javascript and cached by Eleventy:

const db = await EleventyFetch(
    `https://api.notion.com/v1/databases/${process.env.NOTION_BLOG_ID}/query`,
    {
        duration: "7d",
        type: "json",
        fetchOptions: {
            method: "POST",
            withCredentials: true,
            credentials: "include",
            body: JSON.stringify({
                sorts: [
                    {
                        property: "Date",
                        direction: "descending",
                    },
                ],
            }),
            headers: {
                Authorization: `Bearer ${process.env.NOTION_KEY}`,
                "Notion-Version": "2022-06-28",
                "Content-Type": "application/json",
            },
        },
    }
);

The results should be identical, meaning that I can still move on with NotionToMarkdown from here, like I did before.

I’m doing the same thing again to actually fetch the content:

const url = `https://api.notion.com/v1/blocks/${id}/children?page_size=100`;
const response = await EleventyFetch(url, {
    duration: "7d",
    type: "json",
    {
        headers: {
            Authorization: `Bearer ${process.env.NOTION_KEY}`,
            "Notion-Version": "2022-06-28",
            "Content-Type": "application/json",
        },
    },
});

Pagination

You see that page_size query parameter up there in the URL? That’s going to be bad news. I’m only fetching the first 100 blocks of the notion document, which is the largest page size available to me. The Notion Client manages all that by itself, but when I do it manually, I need to loop that.

I need that function in all of my data sources anyway, so I refactored it into a helper function:

const fetchNotionBlocks = async (
    id,
    blocks = [],
    cursor = null,
) => {
    let url = `https://api.notion.com/v1/blocks/${id}/children?page_size=100`;
    if (cursor) {
        url += `&start_cursor=${cursor}`;
    }

    const fetchOptions = {
        headers: {
            Authorization: `Bearer ${process.env.NOTION_KEY}`,
            "Notion-Version": "2022-06-28",
            "Content-Type": "application/json",
        },
    };

    const response = await EleventyFetch(url, {
        duration: "7d",
        type: "json",
        fetchOptions,
    });

    blocks.push(...response.results);
    if (response.has_more) {
        blocks = await fetchNotionBlocks(
            id,
            blocks,
            response.next_cursor,
        );
    }
    return blocks;
};

This will loop through the pages by moving the cursor for each iteration until Notion tells me that I’m on the last one. Now I’ve got everything I had with the Notion Client, but cached.

No Caching

Caching everything all the time is a problem though. I’ve overshot the mark. When I change anything in an article, I won’t get the updates. Even entirely new articles won’t appear, because Notion’s overview is cached as well. I need to be smarter about it:

For regular deployments, I want to have cached Notion responses for all articles but the latest one. I never want to have cached overview responses, so I can see new articles. I’ll use those deployments the most by far.
Full non-cached deployments can already be triggered via Netlify. I’ll use them only for edge cases.
There’s also a dev mode, which will cache all Notion requests. I’ll use that locally when I want to have fast build times and don’t care about up-to-date content.
I also want to have a per-article deployment method. That one will not cache the overview and a given article

To get that I need to switch from Eleventy-Fetch to fetch for requests that I don’t want to cache. I also need to know which article I want to un-cache.

So far, I have one central deploy button in my Notion Space that triggers a Pipedream Webhook (from GET to POST), which triggers a Netlify Deploy Hook. Netlify’s hook can read the POST body and use it as an environment variable in the build script. That means that I can add the Notion ID in the Pipedream Hook as a Query Parameter, move it to the POST body and finally read it in the build script to exclude this exact ID from being cached.

Now I can use the ID from Netlifys Environment Variable INCOMING_HOOK_BODY as process.env.INCOMING_HOOK_BODY in my Eleventy Data file:

const id = posts[i].id.replaceAll('-', '');
        const skipCache = (!process.env.INCOMING_HOOK_BODY && i === 0) || process.env.INCOMING_HOOK_BODY === id; // don't cache latest or specified article
        if (skipCache) {
            console.log('skipping cache for:', posts[i].title);
        }
        const blocks = await fetchNotionBlocks(posts[i].id, [], null, skipCache);
        const post = await getContent(blocks);

…and push it through to the Notion API code:

const fetchNotionBlocks = async (
    id,
    blocks = [],
    cursor = null,
    skipCache = false
) => {
    // ...

    const response = skipCache
        ? await (await fetch(url, fetchOptions)).json()
        : await EleventyFetch(url, {
                duration: "7d",
                type: "json",
                fetchOptions,
          });

    //...
};

Tada! Incremental Deploy Hooks with Eleventy and Netlify!

Visiting https://$PIPEDREAM_HOOK_ID.m.pipedream.net?id=$NOTION_PAGE_ID will now trigger a deployment that requests only the given article.

From Notion to Eleventy

Daniel Schulz — Tue, 11 Oct 2022 08:00:33 +0000

Static Site Generators are a great tool to generate a JAM Stack website from a data feed. That feed can be markdown files, or like in the case of Eleventy, an API endpoint that returns its data as an object. I thought It would be simple enough to attach Notion, as it makes an awesome CMS. The two seem like they could pair up really well, but getting them actually to play nice with each other takes some work.

Notion Structure

I'm a beginner in Notion. I use it at work to write some documentation, but that's about the extent of what I know about it.

I first tried to add each article as a separate page, but soon realized I have no way of managing properties of blog posts, or as it's called in static site generators - front matter. The way to go is databases in Notion. They can be set up to have as many properties as you want. Each entry is also automatically a page.

The Notion API gives me an endpoint to fetch the database and a further endpoint for each post. Eleventy has its _data structure, in which it can fetch data from the API and use it to populate a site with content. So my first try was to simply fetch pages from the Notion database and go on with that. If pure text is all you want, it's pretty straightforward. But Notion has a lot more to offer than that. There's formatting, images, embeds, code blocks... And most of them come with a little hurdle.

Formatting

Notion works with content blocks. Each paragraph and each formatted section is a block on its own. Fetching that from Notion gets me a load of nested objects that are cumbersome to work with. I'm using NotionToMarkdown to take care of that. This will give me a markdown string from a Notion page that's easy to work with. Beware it’s just a markdown string, though. Using it in a template will output the unrendered string. But if we put that into a markdown file, from which eleventy will generate pages, it will also render the markdown string to HTML.

// data
require("dotenv").config();
const { Client } = require("@notionhq/client");
const { NotionToMarkdown } = require("notion-to-md");

module.exports = async () => {
    const notion = new Client({ auth: process.env.NOTION_KEY });
    const n2m = new NotionToMarkdown({ notionClient: notion });

    const databaseId = process.env.NOTION_BLOG_ID;
    const db = await notion.databases.query({
        database_id: databaseId,
        filter: {
            property: "Draft",
            checkbox: { equals: false },
        },
        sorts: [
            {
                property: "Date",
                direction: "descending",
            },
        ],
    });

    const getContent = async (id) => {
        const mdblocks = await n2m.pageToMarkdown(id);
        return n2m.toMarkdownString(mdblocks);
    };

    const posts = db.results.map((result) => ({
        id: result.id,
        title: result.properties["Title"].title.pop().plain_text,
        content: undefined,
        cover: result.cover?.file?.url || result.cover?.external?.url,
        coverAlt:
            result.properties["Cover Alt"]?.rich_text.pop()?.plain_text || "",
        date: result.properties["Date"]?.date.start,
    }));

    for (i = 0; i < posts.length; i++) {
        posts[i].content = await getContent(posts[i].id);
    }

    return posts;
};

// foo.md

layout: 'foo.njk'
pagination:
data: foo
size: 1
alias: post

---

{{ post.content }}

// foo.njk
{% extends "base.njk" %}

{%block content %}
        <p>This will not render markdown:</p>
        {{ post.content }}
{% endblock %}

{% block content %}
        <p>But this will:</p>
    {{ content | safe }}
{% endblock %}

Images

Let’s take a look at images. The ones I upload to Notion are stored in Notion’s cloud. But I want to serve them from the same origin as my static site for reasons like performance and security. Eleventy has a really good Image Plugin, but it won’t replace my Notion images out of the box. I need a custom shortcode for images that invokes the image plugin. The plugin documentation suggests two ways to go about this: an asynchronous and a synchronous function. The asynchronous one works out of the box, but can't be used in Nunjucks macros, because they don't like unresolved Promises when they render HTML. The synchronous one needs some tweaking.

It calls statsSync which does not support remote images and asks me to use statsByDimensionSync. That one needs manual input for the image width and height, which I don’t know either. But it only uses the image dimensions to write the width and height attributes on the <img> tag. I can manage without that and simply remove them again. The dimensions I give into the statsByDimensionsSync call are basically meaningless now.

const Image = require("@11ty/eleventy-img");

module.exports = function imageShortcode(src, alt) {
    let options = {
        widths: [300, 600],
        formats: ["avif", "webp", "jpeg"],
        outputDir: "./dist/img/",
    };

    // generate images, while this is async we don’t wait
    Image(src, options);

    let imageAttributes = {
        alt,
        sizes: "(min-width: 30em) 50vw, 100vw",
        loading: "lazy",
        decoding: "async",
    };

    // get metadata even the images are not fully generated
    const metadata = Image.statsByDimensionsSync(src, 600, 600, options);
    let html = Image.generateHTML(metadata, imageAttributes);
    html = html.replace(/(?:width|height)="[0-9]+"/gm, "");
    return html;
};

I did have to work around a bug for this to work. Apparently, this method will not process all images correctly, leading to broken image links. Thankfully, this has already been reported and solved. The fix is inside the node package zeroby0/eleventy-img#issue-146. I expect this workaround to be obsolete soon.

Rendering, again

Now I have a custom shortcode in my Nunjucks parser, which can even process remote images, and the matching images in the markdown I get from Notion. But the custom shortcode won't trigger on ![alt text](image/location.jpg). because it's a custom shortcode, it needs to be invoked with {% image src="image/location.jpg", alt="alt text" %}. I’m replacing the markdown image tags for custom shortcuts in the API adapter in _data.

(markdown) => {
    let result = markdown;

    const regex = /!\[(?<alt>[^\]]+)?\]\((?<url>[^\)]+)\)/gm;
    match = regex.exec(markdown);

    while (match != null) {
        const mdImage = match[0];
        const alt = match[1];
        const url = match[2];

        if (!url) {
            console.error(`url missing for ${mdImage}`);
            return;
        }

        if (!alt) {
            console.error(`alt missing for ${mdImage}`);
            return;
        }

        // replace with new url
        result = result.replace(mdImage, `{% image "${url}", "${alt}" %}`);

        match = regex.exec(markdown);
    }

    return result;
};

But it’s still not doing its thing. Jed Fox on Eleventy’s Discord server helped me figure that out. Eleventy’s render pipeline looks a bit like this:

What I’m doing now is this:

The custom shortcode is inserted after my markdown has been converted. I need to re-render it, luckily there’s a solution for that: the Render Plugin.

So I installed it, but all I got back was an error inside Eleventy’s Template Renderer. A config key containing the project root had no value, but it all was outside of my scope.

[11ty] Unhandled rejection in promise: (more in DEBUG output)
[11ty] EleventyShortcodeError is not defined (via ReferenceError)
[11ty]
[11ty] Original error stack trace: ReferenceError: EleventyShortcodeError is not defined
[11ty]     at /home/iamschulz/blorb/node_modules/@11ty/eleventy/src/Plugins/RenderPlugin.js:225:21
[11ty]     at processTicksAndRejections (node:internal/process/task_queues:96:5)

According to the docs, this shouldn’t happen. Turns out I stumbled onto another known bug and the solution is to use the canary build.

yarn remove @11ty/eleventy
yarn add -D @11ty/eleventy@2.0.0-canary.16

Just like the Image Plugin, the Render Plugin needs its own custom shortcode as well. I went with the following:

eleventyConfig.addNunjucksAsyncShortcode(
    "render",
    async (content) =>
        await eleventyConfig.javascriptFunctions.renderTemplate(content, "njk")
);

Use this at your own discretion. eleventyConfig.javascriptFunctions is not documented and might only be working by accident. It might not be there in the next major release. Again, thanks to Jed Fox for guiding me through this.

And finally I got it working. Text, formatting and images from Notion to Eleventy. And even a blueprint on how to integrate other embeds as well, following the image example.

Deployment

The one thing I really miss in Notion is webhooks, so I can auto-deploy my site on page changes. Or any ability to send POST requests on demand. Netlify has a build hook, and it only accepts POST requests, so I need some adaptation.

My workaround is a Zapier integration. Zapier works natively with Notion, but it only provides a trigger on new database items. It won't fire on database entry changes. That would deploy my blog once I add a new post, even as a draft. But once I set the draft property to false, it wouldn't update and the post won't be published.

I work around that with a generic GET endpoint in Zapier. It has a key attached as a query parameter, which Zapier will check. It then sends a POST request to Netlify’s build hook. The GET endpoint works as a normal link in my Notion blog page.

That won’t provide me will full automation, but at least I’ll have a one-click solution to export a blog from Notion to a live website.

Writing a Game in Typescript

Daniel Schulz — Tue, 14 Jun 2022 06:31:49 +0000

I know people make all kinds of stuff with <canvas> but that's all black magic to me. Time to change that. This is how I built Attacke!, a simple 2D fighting game in JavaScript.

Before we dig in further, I should clarify that most of my code snippets in this article are truncated to the relevant lines. The entire code can be found on GitHub.

I want it to be a top-down fighting game. Top-down specifically for avoiding jumps and gravity. I started a proof-of-concept as a side-scroller, but that was the point where I went for an easier approach. For now, it's gonna be two players on the same device, but I want my code to be flexible enough to expand on the player number and input options in the future.

I also want the graphics of the game to be easily interchangeable. The first release will only have one theme, but I plan to include more in the future.

The Project Setup

I want this to be very simple, and use as few build steps and dependencies as possible. But I also want some goodies, like hot reloading and types.

This project is going to be very light on the CSS side of things, so I'm sticking to native CSS and spare me the build step.

Having types defaults to use TypeScript. That means I also need a build tool to compile JavaScript out of that. I ended up with ESBuild. I heard that Vite is really fast. Vite is built on top of ESBuild, so using it without Vite should be even faster, right?

#!/usr/bin/env node

const watchFlag = process.argv.indexOf("--watch") > -1;

require("esbuild")
    .build({
        entryPoints: ["src/ts/main.ts", "src/ts/sw.ts"],
        bundle: true,
        outdir: "public",
        watch: watchFlag,
    })
    .catch(() => process.exit(1));

➜  attacke git:(main) yarn build
yarn run v1.22.10
$ ./esbuild.js
✨  Done in 0.47s.

Awesome!

The HTML Foundation

The website that provides the <canvas> is nothing special. The single most important element is the canvas itself. It's not focusable on its own and needs a tabindex to be accessible by keyboard. Hitting up and down will move the page up and down. I need to avoid that while the canvas has focus, or else the page jumps up and down with character movements. The width and height are also fixed. The canvas may not be displayed at FullHD, but its dimensions are the endpoints of the canvases coordinate system and are needed to calculate positions within it.
I also added a loading indicator for a more streamlined boot-up experience.

<div class="loader">
    <progress value="0" max="100"></progress>
</div>
<canvas tabindex="0" id="canvas" width="1920" height="1080"></canvas>

Game Loop

A real-time game in JavaScript requires a game loop: a recursive function calling itself for every frame. That means we have a performance budget of 16ms to render one frame if we want to keep it at 60fps or 33ms for a 30fps target. There's no game logic inside the loop itself. Instead, I send out a tick event for every frame. All other parts of the game can listen to that and perform their logic whenever needed.

My first try failed at that.

export class Renderer {
    ctx: CanvasRenderingContext2D;
    ticker: number;

    constructor(ctx: CanvasRenderingContext2D) {
        this.ctx = ctx;
        this.ticker = setInterval(() => {
            const tick = new Event("tick", {
                bubbles: true,
                cancelable: true,
                composed: false,
            });
            ctx.canvas.dispatchEvent(tick);
        }, 1000 / 60); // aim for 60fps
    }
}

I used an Interval Timer to call the game loop. That worked okay on Chrome but fell apart on Firefox and Safari. Firefox performs poorly with drawImage(), which I'll use to draw my sprites. Fair enough, that's a straightforward reason. Safari, though, is very capable of rendering 60fps even when drawing huge images every frame, but sometimes decides not to. Apparently, Macbooks have a battery saver mode enabled by default, which limits Safari to 30fps whenever the power cable is not connected. Took me a while to find that out.

The workaround for both issues is to use requestAnimationFrame instead of setInterval.

constructor(ctx: CanvasRenderingContext2D, theme: Theme) {
    this.ctx = ctx;
    this.theme = theme;
    this.fps = 60; // aim for 60fps
    this.counter = 0;
    this.initTicker();
}

private initTicker() {
    window.requestAnimationFrame(() => {
        this.tick();
        this.initTicker();
    });
}

Now the game runs fluently in every browser, but the game speed still varies, because I'm calculating and executing every action (like moving, attacking, etc.) on every frame. A 30fps browser will run the game at half speed. I'm going to counter that by measuring the time between frames and inject the number of skipped frames into the calculations.

private tick() {
    const timeStamp = performance.now();
    const secondsPassed = (timeStamp - this.oldTimeStamp) / 1000;
    this.oldTimeStamp = timeStamp;

    // Calculate fps
    const fps = Math.round(1 / secondsPassed);
    const frameSkip = clamp(Math.round((60 - fps) / fps), 0, 30);

    // to allow for animations lasting 1s
    if (this.counter >= this.fps * 2) {
        this.counter = 0;
    }

    const tick: TickEvent = new CustomEvent("tick", {
        bubbles: true,
        cancelable: true,
        composed: false,
        detail: {
            frameCount: this.counter,
            frameSkip: frameSkip,
        },
    });
    this.ctx.clearRect(0, 0, this.ctx.canvas.width, this.ctx.canvas.height);
    this.ctx.canvas.dispatchEvent(tick);

    this.counter++;
}

Playable Characters

Each playable character gets invoked in their own instance of a character class. It controls the players' movement, actions, appearance, and sounds. You can probably guess it's a handful. I'll try to break it down into manageable sections.

Move fast

As real-world objects, when characters move around, they don't go from zero to top speed instantly. They accelerate and decelerate. When moving, they have a certain velocity. This is reflected in the class by:

class Character {
    position: coordinates;
    orientation: number;
    speed: number;
    maxVelocity: number;
    velocity: coordinates;
    obstacle: Obstacle;
    action: {
        movingX: number;
        movingY: number;
    };
    //...
}

When a movement key is hit, the action.movingX|Y property is set to +-1. When the key is released, the property is set to 0. This serves as an indicator if the player should start or keep moving.

// move left
config.controls[this.player].left.forEach((key: string) => {
    document.addEventListener("keydown", (event: KeyboardEvent) => {
        this.captureEvent(event);
        if (event.code === key && event.repeat === false) {
            this.action.movingX = -1;
        }
    });
    document.addEventListener("keyup", (event: KeyboardEvent) => {
        this.captureEvent(event);
        if (event.code === key) {
            this.action.movingX = 0;
        }
    });
});

// repeat for up, down, and right.

Note that the key mappings are stored inside config.controls as an array with controls for each player.

We can ignore captureEvent for now. That only prevents the page from scrolling when cursor keys are pressed. Now we know when a character should start or stop moving, but nothing's happening yet. That's when I hook into the game loop. Remember how a tick event is sent for every frame? I'm listening to that here. For every frame, I update the position before re-drawing the character.

private move(): void {
    const { position, velocity, action } = this;
    const newX = position.x + action.movingX * this.speed + velocity.x * this.speed;
    const newY = position.y + action.movingY * this.speed + velocity.y * this.speed;

    position.x = newX;
    position.y = newY;

    if (position.x < 0) {
        position.x = 0;
    } else if (newX > this.ctx.canvas.width - this.size) {
        position.x = this.ctx.canvas.width - this.size;
    }

    if (position.y < 0) {
        position.y = 0;
    } else if (newY > this.ctx.canvas.height - this.size) {
        position.y = this.ctx.canvas.height - this.size;
    }

    this.velocity.x = clamp(
        (action.movingX ? this.velocity.x + action.movingX : this.velocity.x * 0.8) * this.speed,
        this.maxVelocity * -1,
        this.maxVelocity
    );
    this.velocity.y = clamp(
        (action.movingY ? this.velocity.y + action.movingY : this.velocity.y * 0.8) * this.speed,
        this.maxVelocity * -1,
        this.maxVelocity
    );
}

This is where velocity comes in. Velocity is a value that keeps incrementing over time as the player holds a movement key, up to maxVelocity, which acts as top speed. When the player releases the movement key, the character doesn't stop abruptly but decelerates until it comes to a halt. The velocity gently reaches 0 again.

But characters don't just move around, they can also turn. In my case, I want them to face each other directly at all times. Since there's only one opponent, for now, players should concentrate on timing a hit on their adversary, instead of turning to their sole target all the time. That also helps keep the game speed high.

private turn(): void {
    const otherPlayer = this.player === 0 ? 1 : 0;
    const orientationTarget: coordinates = this.players[otherPlayer]?.position || { x: 0, y: 0 };
    const angle = Math.atan2(orientationTarget.y - this.position.y, orientationTarget.x - this.position.x);
    this.orientation = angle;
}

My little fighting game is a dancing game now!

Break things

Characters should be able to attack each other. To add more depth to the game, defending against an attack should also be an option. Both are defined to be character actions, and each has a cooldown period to prevent spamming them.

class Character {
    range: number;
    attackDuration: number;
    blockDuration: number;
    cooldownDuration: number;
    action: {
        attacking: boolean;
        blocking: boolean;
        cooldown: boolean;
    };
    // ...
}

Triggering those actions works the same as moving around — by listening for the keyboard event, then setting the action value to true…

// attack
config.controls[this.player].attack.forEach((key: string) => {
    document.addEventListener("keydown", (event: KeyboardEvent) => {
        if (
            this.active &&
            event.code === key &&
            event.repeat === false &&
            !this.action.cooldown
        ) {
            this.action.attacking = true;
        }
    });
});

// block
config.controls[this.player].block.forEach((key: string) => {
    document.addEventListener("keydown", (event: KeyboardEvent) => {
        if (
            this.active &&
            event.code === key &&
            event.repeat === false &&
            !this.action.cooldown
        ) {
            this.action.blocking = true;
        }
    });
});

…and finally executing the action in the game loop.

private attack(): void {
    if (!this.active || !this.action.attacking || this.action.cooldown) {
        return;
    }

    this.action.cooldown = true;

    // strike duration
    window.setTimeout(() => {
        this.action.attacking = false;
    }, this.attackDuration);

    // cooldown to next attack/block
    window.setTimeout(() => {
        this.action.cooldown = false;
    }, this.cooldownDuration);

    this.strike();
}

Attacking is only half of the work. The other half makes sure the opponent is hit — that means they mustn't block the attack and the weapon is in range. That's handled in the strike() method.

private strike(): void {
    const otherPlayerId = this.player === 0 ? 1 : 0;
    const otherPlayer: rectangle = this.players[otherPlayerId].obstacle?.getObject();

    const blocked = this.players[otherPlayerId].action.blocking;
    if (blocked) {
        // opponent blocked the attack
        return;
    }

    // attack hits

    const otherPlayerPolygon = new Polygon(new Vector(0, 0), [
        new Vector(otherPlayer.a.x, otherPlayer.a.y),
        new Vector(otherPlayer.b.x, otherPlayer.b.y),
        new Vector(otherPlayer.c.x, otherPlayer.c.y),
        new Vector(otherPlayer.d.x, otherPlayer.d.y),
    ]);

    const weaponPosition = this.getWeaponPosition();
    const weaponPolygon = new Polygon(new Vector(0, 0), [
        new Vector(weaponPosition.a.x, weaponPosition.a.y),
        new Vector(weaponPosition.b.x, weaponPosition.b.y),
        new Vector(weaponPosition.c.x, weaponPosition.c.y),
        new Vector(weaponPosition.d.x, weaponPosition.d.y),
    ]);

    const hit = this.collider.testPolygonPolygon(weaponPolygon, otherPlayerPolygon) as boolean;
    if (hit) {
        // finish this round
        this.finish();
    }
}

This creates a hitbox around the player that reaches out by 150% into the opponent's direction. If the weapon hitbox collides with the opponent's hitbox, the attack lands and the player wins the round.

But what's that about hitboxes? What are Vectors and Polygons? Let's talk about…

Collision Detection

Collision detection isn't as straightforward as I assumed it would be. Starting with two rectangles on a canvas, you can simply compare their x and y coordinates. But that doesn't work anymore once you rotate the rectangles. My next try was to create linear functions from the rectangles' bordering lines and check for intersections. That still left some edge cases unaccounted for. It would also be quite inefficient.

That's when I turned to Google for solutions. I found this Codepen and the matching description on StackOverflow:

That solution is clever, elegant, efficient, and — most importantly — way above my skill level in geometry. It's also the method that Collider2D uses to check for intersections between two objects. That's it! Collision Detection is a solved problem. I neither want nor need to deal with that, at least for now.

yarn add collider2d

I added Collider Polygons as hitboxes around every relevant object, including the playable characters, the borders of the canvas, and possible obstacles in the arena. Those Polygons consist of Vectores that describe their circumference. The character Polygons are stored inside a property inside the character class and updated in the move(), turn() and strike() methods.

// inside character.strike()
const otherPlayerPolygon = new Polygon(new Vector(0, 0), [
    new Vector(otherPlayer.a.x, otherPlayer.a.y),
    new Vector(otherPlayer.b.x, otherPlayer.b.y),
    new Vector(otherPlayer.c.x, otherPlayer.c.y),
    new Vector(otherPlayer.d.x, otherPlayer.d.y),
]);

const weaponPosition = this.getWeaponPosition();
const weaponPolygon = new Polygon(new Vector(0, 0), [
    new Vector(weaponPosition.a.x, weaponPosition.a.y),
    new Vector(weaponPosition.b.x, weaponPosition.b.y),
    new Vector(weaponPosition.c.x, weaponPosition.c.y),
    new Vector(weaponPosition.d.x, weaponPosition.d.y),
]);

const hit = this.collider.testPolygonPolygon(
    weaponPolygon,
    otherPlayerPolygon
) as boolean;

Now we have our first glance at some actual gameplay!

But the characters can still clip through each other. I want them to bump around instead. Collider2D can return some information about the collision, like its vector and location. That plays very well together with my velocity solution. I can simply direct the existing velocity in the direction of the collision deflection:

private collide(): void {
    const obstacles = this.obstacles.filter((obstacle) => obstacle.getId() !== this.obstacle.getId());
    obstacles.forEach((obstacle) => {
        const collision = this.obstacle.collidesWith(obstacle);
        const friction = 0.8;

        if (!collision) {
            return;
        }

        this.velocity.x = (this.velocity.x + collision.overlapV.x * -1) * friction;
        this.velocity.y = (this.velocity.y + collision.overlapV.y * -1) * friction;
    });
}

collide() now gets called in the game loop together with move(), turn() and their friends, so every frame has a poll for collision detection.

Graphics

Dancing squares with magenta faces might be functional, but they're not pretty. I want some personality. It's been a while since I worked with Photoshop, especially in the retro pixel art style I was going for. I wanted to invoke some nostalgic GameBoy feelings and went for a greyish-green screen (which I later tinted greyish-blue) and drop-shadows on enlarged pixels.

My characters measure 16x16px. The weapon range is 150%, which makes 40x16px. A photoshop canvas that accommodates all sprites with the character centered in the middle would be 64x64px. I scale them up to a 100x100px character size when exporting the images. 16px characters on a full HD screen would be way too small. I ordered my sprites in grouped layers by direction, since every sprite needs eight variations — one for each compass direction. Then multiply that by the number of frames for animated sprites.

I need control over every pixel and anti-aliasing is my enemy since it affects neighboring pixels by definition. I stuck to the pen tool instead of the brush and used the Pixel Repetition mode whenever I needed to transform, scale or rotate something.

Exporting images is a bit of a fight. I need to export 8bit pngs. They have an alpha channel and turned out smaller in byte size than gifs (with a hard g) and even webp. For some reason, Photoshop's batch export doesn't support 8bit png. It also can't auto-crop single layers. So manual export it is.

Themeability

For now, I've got only one set of sprites, but I plan to do more in the future. At some point, I want to load a different set every round. That means each need to adhere to a specific set of rules. I need a theme definition.

Now I have a bunch of JavaScript and a bunch of pngs. Let's marry them, and while we're at it, reach some secondary goals:

All sprites must be able to be animated
Everything related to the theme must be interchangeable. I want to be able to switch the whole style out later on.

Animating a sprite within a canvas isn't as simple as loading in a gif. drawImage() will only draw the first frame. There are some techniques to implement a gif viewer inside the canvas, but they are overly complex for my use case. I can simply use an array with the individual frames.

declare type Sprite = {
    name: string;
    images: string[];
    animationSpeed: number; // use next image every N frames, max 60
    offset: coordinates;
};

Then write a wrapper for drawImage() that'll use consolidated sprites and switch out animation steps based on the frame count:

public drawSprite(ctx: CanvasRenderingContext2D, name: string, pos: coordinates, frameCount = 0) {
    const sprite = this.sprites.find((x) => x.name === name);
    if (!sprite) {
        return;
    }

    const spriteFrame = Math.floor((frameCount / sprite.animationSpeed) % sprite.images.length);

    const img = this.images.find((x) => x.src.endsWith(`${sprite.images[spriteFrame].replace("./", "")}`));

    if (!img) {
        return;
    }

    ctx.drawImage(img, pos.x + sprite.offset.x, pos.y + sprite.offset.y);
}

Great, we can now animate things! Getting this to work released a huge chunk of endorphins in me.

Interchangeability requires conformity. I'm creating a theme config that defines which sprites will be used, and how.

declare type SpriteSet = {
    n: Sprite; // sprite facing north
    ne: Sprite; // sprite facing north-east
    e: Sprite; // etc
    se: Sprite;
    s: Sprite;
    sw: Sprite;
    w: Sprite;
    nw: Sprite;
};

declare type themeConfig = {
    name: string; // has to match folder name
    scene: Sprite; // scene image, 1920x1080
    obstacles: rectangle[]; // outline obsacles within the scene
    turnSprites?: boolean; // whether to turn sprites with characters
    players: {
        default: SpriteSet; // player when standing still, 100x100
        move: SpriteSet; // player when moving, 100x100
        attack: SpriteSet; // player when attacking, 250x100
        block: SpriteSet; // player when blocking, 100x100
    }[]; // provide sprites for each player, else player 1 sprites will be re-used
};

This config gets fed to all the parts that need to know what theme we're dealing with and select all their assets from it. For example, the character class can now draw a themed asset like this:

this.theme.drawSprite(
    this.ctx,
    "p1_move_s",
    { x: this.size / -2, y: this.size / -2 },
    frameCount
);

Remember when I added that turning part to moving characters? That might be useful for themes that actually allow turning — think of Asteroids for example. But my theme has an up and down. Turning a sprite would just look silly.

I need a method that assigns sprites to orientation values. I have to map 8 compass directions to a full circle of orientation values. Circle segments are the way to go. Since the start and end points are right in the middle of a direction, I simply assign this overlapping direction twice — as first and last.

private getSprite(): Sprite {
    const directions = ["w", "nw", "n", "ne", "e", "se", "s", "sw", "w"];
    const zones = directions.map((z, i) => ({
        zone: z,
        start: (Math.PI * -1) - (Math.PI / 8) + (i * Math.PI) / 4,
        end: (Math.PI * -1) - (Math.PI / 8) + ((i + 1) * Math.PI) / 4,
    }));

    const direction = zones.find((zone) => this.orientation >= zone.start && this.orientation < zone.end);

    // action refers to moving, attacking, blocking...
    return this.theme.config.players[this.player][action][direction.zone];
}

And finally, I'll use this.theme.config.turnSprites inside the character class to toggle between turn and direction-based themes.

Sounds

Visuals are only one aspect of themes. The other is sounds. I want a specific sound for attacking, blocking, bumping into things, and of course some background music. My theme is 8bit styled, so I went for some chiptune to accompany that. My music production skills are next to non-existent and I've never done anything with chiptune, so I went to itch.io to acquire some sounds made by people who actually know what they're doing.

I thought I could go the easy, straightforward way and use the <audio> element. Whenever a sound is needed, create an element, autoplay it, then remove it.

const audio = new Audio("./sound.mp3");
audio.play();

And that works great, at least in Chrome and Firefox. But Safari… oh Safari… There's always a delay before the sound plays. I tried prefetching the file, I tried caching it in a service worker and I tried creating the audio element beforehand and just setting the player position when needed. Safari simply won't have it. Alright, gotta do it the proper way then.

Like I set up the canvas context for visual things, I'm setting up an AudioContext for sounds. One context that is shared by all other parts of the game to play out whatever's needed.

The Web Audio API is built up like an actual modular synthesizer. We need to connect one device to the next. In this case, we use audio files as an input source, buffer them, connect to a Gain Node to set the volume, and finally play them out.

this.ctx = new (window.AudioContext || window.webkitAudioContext)();

async function play(sound: string): Promise<void> {
    if (this.sounds[this.getAudioUrl(sound)].playing) {
        return;
    }

    this.sounds[this.getAudioUrl(sound)].playing = true;

    const arrayBuffer = await this.getSoundFile(this.getAudioUrl(sound));
    const source = this.ctx.createBufferSource();

    this.ctx.decodeAudioData(arrayBuffer, (audioBuffer) => {
        source.buffer = audioBuffer;
        source.connect(this.vol);
        source.loop = false;
        source.onended = () => {
            this.terminateSound(source);
            this.sounds[this.getAudioUrl(sound)].playing = false;
        };
        source.start();
    });
}

That way I can register sounds with:

// theme config
{
    // ...
    bgAudio: "./assets/bgm.mp3",
    attackAudio: "./assets/attack.mp3",
    blockAudio: "./assets/block.mp3",
    collideAudio: "./assets/bump.mp3",
    winAudio: "./assets/win.mp3",
}

…and invoke them with:

this.audio.play(this.theme.config.collideAudio);

Finally, even Safari submits to having sounds play out when I need them to, not when the browser feels like it.

Using a gamepad

I love using obscure Browser APIs. This is a prime candidate for the Gamepad API, which interfaces with up to four connected Gamepads.

Working with it feels a bit janky, though. Unlike more common input methods like keyboard and mouse, Gamepads don't send events. Instead, it populates a Gamepad object as soon as the site detects a Gamepad Interaction.

interface Gamepad {
    readonly axes: ReadonlyArray<number>;
    readonly buttons: ReadonlyArray<GamepadButton>;
    readonly connected: boolean;
    readonly hapticActuators: ReadonlyArray<GamepadHapticActuator>;
    readonly id: string;
    readonly index: number;
    readonly mapping: GamepadMappingType;
    readonly timestamp: DOMHighResTimeStamp;
}

interface GamepadButton {
    readonly pressed: boolean;
    readonly touched: boolean;
    readonly value: number;
}

Every interaction mutates the object. Since there are no browser-native events being sent, I need to listen for changes on the gamepad object.

if (
    this.gamepads[gamepadIndex]?.buttons &&
    gamepadButton.button.value !==
        this.gamepads[gamepadIndex]?.buttons[gamepadButton.index]?.value &&
    gamepadButton.button.pressed
) {
    // send press event
    this.pressButton(gamepadIndex, b.index, gamepadButton.button);
} else if (
    this.gamepads[gamepadIndex]?.buttons &&
    gamepadButton.button.value !==
        this.gamepads[gamepadIndex]?.buttons[gamepadButton.index]?.value &&
    !gamepadButton.button.pressed
) {
    // send release event
    this.releaseButton(gamepadIndex, b.index, gamepadButton.button);
}

pressButton and releaseButton send custom events, which I can use in the character class and expand my input methods to recognize gamepads.

I only have Xbox 360 controllers, so that's what I built and tested this with. As far as I unterstood it, the keymaps work the same for playstation controllers. Stick one and two map to the left and right stick, regardless of their hardware layout. The Xbox' ABXY buttons are mapped the same way as the Playstation's geometric shapes.

I couldn't get the GamepadHapticActuator (also known as Rumble or Vibration) to work with my 360 controllers. I'm not sure if Chrome and Firefox don't support it just with my controllers or at all. I might have to get my hands on more recent controllers to test that out. I'd also like to test the Gamepad API a bit more with more obscure controllers like ones with the Nintendo 64 layout or the Steam Controller.

Gameplay

Let's bring things into order. I have some bits and pieces of the game, but nothing's working together properly yet.

When we register a hit, nothing's happening as of now. That's a very boring game. I want to give some feedback as to who won and then restart the round. Since it's a pretty fast-paced game with short rounds, a score display would be nice to have.

We can determine the winner of a round in the character.strike() method. Whoever calls the method and registers an actual hit, wins. I'm gonna send an event with that information and trigger the following calls:

Show a winner indication
Increment the score counter
Reset the characters
Start a countdown to a new round

declare interface FinishEvent extends Event {
    readonly detail?: {
        winner: number;
    };
}

this.ctx.canvas.addEventListener("countdown", ((e: FinishEvent) => {
    if (typeof e.detail?.winner === "number") {
        this.gui.incrementScore(e.detail.winner);
    }

    this.startCountdown(e.detail?.winner);
    this.togglePlayers(false);
}) as EventListener);

this.ctx.canvas.addEventListener("play", () => {
    this.togglePlayers(true);
});

I could bet better of with a proper state machine at this point, but my event mechanic isn't convoluted enough to annoy me into a refactoring. As long as it fits nicely into a diagram, it can't be so bad, right?

Loading

When booting up the game and starting the first round, it still shows its laggy side. The sounds and graphics aren't loaded yet and keep popping up as they're landing in the browser cache. I need a loading strategy.

I'm pretty sure of what I need to load before starting the game. I already have the web site's assets, as I'm already executing JavaScript when starting the game. No need to take that into account. But I do need to load all the graphics and sounds. Otherwise, they would come in as needed, introducing loading times.

I can load an image by creating a new Image prototype and providing it with the src. The browser will start fetching it automatically.

private loadImage(src: string): Promise<HTMLImageElement> {
    const url = `./themes/${this.config.name}/${src}`;
    return fetch(url).then(() => {
        const img = new Image();
        img.src = url;
        if (!this.images.includes(img)) {
            this.images.push(img);
        }
        return img;
    });
}

I can now iterate over every image found in the theme config and load everything. The promised images are stored inside an array.

this.config.players.forEach((player) => {
    const spriteSets = ["default", "move", "attack", "block"];
    spriteSets.forEach((spriteSet) => {
        Object.keys(player[spriteSet]).forEach((key: string) => {
            player[spriteSet][key].images.forEach(async (image: string) => {
                const imageResp = await this.loadImage(image);
                if (toLoad.includes(imageResp)) {
                    return;
                }
                imageResp.onload = () => {
                    this.onAssetLoaded(toLoad);
                };
                toLoad.push(imageResp);
            });
            this.sprites.push(player[spriteSet][key]);
        });
    });
});

Every time an image loads, I check if all promises in the array are resolved. If they are, all images are loaded and I can send an event that tells how much of the game assets are already loaded.

private onAssetLoaded(assetList: HTMLImageElement[]) {
    const loadComplete = assetList.every((x) => x.complete);
    const progress = Math.floor(
        ((assetList.length - assetList.filter((x) => !x.complete).length) / assetList.length) * 100
    );
    const loadingEvent: LoadingEvent = new CustomEvent("loadingEvent", { detail: { progress } });
    this.ctx.canvas.dispatchEvent(loadingEvent);

    if (loadComplete) {
        this.assetsLoaded = true;
    }
}

The progress information gets mapped to a <progress> element. Whenever it reaches 100% I fade in the <canvas> and start the game.

Finishing touches

Strictly speaking, the game is now finished. But it's also still a website and I should do my best to keep it as fast, compatible, and accessible as I can. While I have no way to add a11y-specific features to the gameplay (at least that I know of), I can concentrate on the website part. Let's start with some automated linting.

Lighthouse and Validator

I didn't add a description <meta> tag yet. I had the canvas tabindex set to 1 when it should be 0 (just to have it focusable). I still had an SVG favicon, which still isn't supported by Safari (of course), and while I was at it, I also added an apple-touch-icon. There was also a missing <label> to an <input>.

Progressive Web App

There's one lighthouse category left out: PWA. It even makes sense to add PWA features to this project. Where blogs offer PWAs with questionable benefits at most (why would I want your blog on my home screen?), a game should absolutely bin installable and offline-capable.

The first step is a manifest. That doesn't need to do a lot, just include the necessary icons, colors, and title strings to format the home screen icons, splash screen, and Browser UI when installed. And specify that the PWA runs in fullscreen mode and therefore hides all browser UI elements.

{
    "theme_color": "#1e212e",
    "background_color": "#1e212e",
    "display": "fullscreen",
    "scope": "/",
    "start_url": "/",
    "name": "Attacke!",
    "short_name": "Attacke!",
    "icons": [
        {
            "src": "assets/icon-192x192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        ...
    ]
}

I want my game PWA to be just the game itself. Any additional links like the credits page and the link to the source code should open inside a new browser window as long as it's opened in fullscreen view. While the app is opened inside a regular browser window, I'm a huge fan of letting the user stay in control over how links behave.

This snippet asks the browser if it's in fullscreen mode and opens all links marked with data-link='external' in a new tab if it is:

if (window.matchMedia("(display-mode: fullscreen)").matches) {
    document.querySelectorAll("[data-link='external']").forEach((el) => {
        el.setAttribute("target", "_blank");
        el.setAttribute("rel", "noopener noreferrer");
    });
}

Offline Mode

The next step is the Service Worker. For a valid PWA, it just needs to be registered and provide an answer for offline requests. In this case, I want to create an offline cache with all the game assets inside. That'll be quite a bit of network traffic when installing, but I think that's okay when installing a game. App Stores work the same after all.

Caching offline requests as they come in is relatively easy, and responding to them is as well. There are tons of articles on how to do that. But because of the chunk of assets coming down the network, I want to cache them only if the user installs the app. Streaming them in when needed is the preferable option otherwise. Since all my themes are going to follow the same schema, I can iterate through them and then return a list of assets:

export const getGameAssets = (): string[] => {
    const assets = [];

    Object.keys(themes).forEach((theme) => {
        const themeConfig = themes[theme] as themeConfig;

        // add player sprites
        ["p1", "p2"].forEach((player, pi) => {
            ["default", "move", "attack", "block"].forEach((action) => {
                const spriteSet = themeConfig.players[pi][action] as SpriteSet;

                ["n", "ne", "e", "se", "s", "sw", "w", "nw"].forEach(
                    (direction) => {
                        const images = spriteSet[direction].images as string[];
                        const paths = images.map(
                            (image) => `/themes/${theme}/${image}`
                        );
                        assets.push(...paths);
                    }
                );
            });
        });

        // add background sprite
        themeConfig.scene.images.forEach((image) => {
            assets.push(`/themes/${theme}/${image}`);
        });

        // add sounds
        [
            "bgAudio",
            "attackAudio",
            "blockAudio",
            "collideAudio",
            "winAudio",
        ].forEach((audio) => {
            assets.push(`/themes/${theme}/${themeConfig[audio]}`);
        });
    });

    // return uniques only
    return [...new Set(assets)];
};

This function gets called in the Service Worker and caches everything that's needed to run the fully-functioning game.

const cacheAssets = () => {
    const assets = [
        "/index.html",
        "/styles.css",
        "/main.js",
        "/assets/PressStart2P.woff2",
        ...getGameAssets(),
    ];

    caches.open(cacheName).then(function (cache) {
        cache.addAll(assets);
    });
};

channel.addEventListener("message", (event) => {
    switch (event.data.message) {
        case "cache-assets":
            cacheAssets();
            break;
    }
});

What's that? A cache-assets message? Where does that come from? Why isn't it the install eventListener?

That's because I don't like the current state of PWA install prompts.

Custom Install Button

Chrome on Android shows you a big ugly install banner. It's not integrated with my design, it's unsolicited and its behavior isn't clear to the user. Chrome on Desktop does the same, but with a popup. Firefox on Android hides it in the browser menu, although at least it's clearly labeled as "Install". The worst offender is Safari (yeah, again). Why would you hide the install button in the share menu?

At least Chrome provides a way to implement my own install UX (Be aware that everything here is off spec. You might not want to do that because of ethical reasons). Their install prompt is triggered by event listeners, and I can hook into them. That lets me hide the prompt altogether and bind its events to a custom button. When the button is clicked, the PWA is installed and all its assets are with it.

window.addEventListener("appinstalled", () => {
    button.setAttribute("hidden", "hidden");
    deferredPrompt = null;
    channel.postMessage({ message: "cache-assets" });
});

No unsolicited install prompt, no spamming the user's device with large downloads without warning, just an old-fashioned install button. Steve Jobs would be happy.

Conclusion

And now there's a game, fully written in typescript and rendered in a <canvas>, even fluently on all major browsers, and packaged inside a PWA. My future plans for it include more themes, more players, and remote multiplayer support, as an excuse to learn some WebRTC.

I had a lot of fun building the game logic and even more drawing the graphics. I definitely need to open Photoshop a lot more. Figuring out all the kinks can be a piece of work (looking at you, Safari) but pays off well in a learning experience.

If you'd like to contribute, here's Attacke! on GitHub.

Web Technology as a Spectrum

Daniel Schulz — Fri, 29 Apr 2022 07:27:45 +0000

Josh W. Comeau talked on Twitter about no-code solutions, specifically for CSS, and how they impact what developers work on after trivial tasks in their workflow have been automated.

Imagine a spectrum. At one end, you have template-focused website builders like SquareSpace. A little further along, you have Webflow. At the opposite end, you have raw HTML/CSS.

This is a very nice perspective on the subject. And one I'd like to talk about, not just in the context of CSS.

The question of when developers would become irrelevant has always come up. Students making websites on the cheap, WYSIWYG editors, Easy-to-setup solutions like Wordpress and Shopify, and last but not least GitHub Copilot have human coders wondering if they'll be pushed out of a job soon. The answer has always been no and will be for a very long time.

Tools for Users

Good automation tools reduce friction and give developers the tools to tackle more complex problems:

Wordpress gave me a CMS so I don't have to worry about that and can create a nice frontend
It also had themes, so backend developers could build sophisticated plugins and not worry about the UX
GitHub Copilot writes Regular Expressions and SQL that works well enough for me, and sometimes lets me second-guess my own code.

I value a custom and purpose-built UI more than a clean backend. Tools like those took the parts that I didn't like (such as server-side programming) and gave me solutions that worked well enough out of the box. In the meantime, I could dig even deeper in frontend development and specialize in the parts that I like. Doing that I quickly overtook the automated solutions and was back to hand-writing my own code. As Josh would take it: I moved up the spectrum, to the end which gave me more flexibility with more general-purpose tools.

Users for Tools

Not all tools allow me to shift go into the direction I want to so easily, though. Sometimes tools create their own set of problems and suddenly you need to become an expert on drywall construction in order to hang a picture. That's how I wound up being more of a full-stack developer than I would have liked a few years ago.

Ever since JavaScript first ran on a server it took on a crusade to swallow more and more aspects of frontend development. While you could score a decent job with HTML, CSS, and a little jQuery on the side 10 years ago, deep JavaScript knowledge is a basic requirement for most positions nowadays. As I learned ES6, Node and Vue, I gradually lost my focus on design and layout, to the point where I have never even touched Figma (or Sketch, speaking of) yet. Those tools have been solving problems for me, sure, but they weren't able to let me move up my spectrum. They weren't as general-purpose as HTML and CSS. Instead of crafting beautiful websites, I now had to care about things like routing and data structures – things I thought the server and the browser were doing for me.

It's tools like these that eventually created what Chris Coyier would later describe as The Great Divide, with engineering-focused front enders on one side and design-focused ones on the other. Reactive frameworks have not only solved their own problem, they created so many new ones that an entire new school of engineers followed in their wake. So much for becoming obsolete!

Josh’s perspective on no-code solutions brings a nice way to evaluate tools with it. Can a tool help me not only with my current task but can it help me become a better developer, or does it try to lock me inside a walled garden?current task but can it help me become a better developer, or does it try to lock me inside a walled garden?

Writing Logic in CSS

Daniel Schulz — Mon, 21 Feb 2022 10:45:41 +0000

CSS is a highly specialized programming language focusing on style systems. Because of this unique use case and its declarative nature, it's sometimes hard to understand. Some folks even deny it's a programming language altogether. Let's prove them wrong by programming a smart, flexible style system.

Control Structures

More traditional, general-purpose languages (like JavaScript) give us tools like Conditions (if/then), Loops (for, while), Logical Gates (===, &&, etc.) and Variables. Those structures are named differently in CSS, their syntax is wildly different to better accommodate the specific use case of styling a document, and some of those simply weren't available in CSS up until a few years ago.

Variables

Variables are the most straightforward ones. They're called Custom Properties in CSS (although everyone calls them variables anyway, even their own syntax).

:root {
    --color: red;
}
span {
    color: var(--color, blue);
}

The double-dash declares a variable and assigns a value. This has to happen in a scope because doing so outside of a selector would break the CSS syntax. Notice the :root selector, which works as a global scope.

Conditions

Conditions can be written in a number of ways, depending on where you want to use them. Selectors are scoped to their elements, media queries are scoped globally, and need their own selectors.

Attribute Selectors:

[data-attr='true'] {
    /* if */
}
[data-attr='false'] {
    /* elseif */
}
:not([data-attr]) {
    /* else */
}

Pseudo Classes:

:checked {
    /* if */
}
:not(:checked) {
    /* else */
}

Media Queries:

:root {
    color: red; /* else */
}
@media (min-width > 600px) {
    :root {
        color: blue; /* if */
    }
}

Loops

Counters are both the most straightforward form of loops in CSS, but also the one with the narrowest use case. You can only use counters in the content property, displaying it as text. You can tweak its increment, its starting point, and its value at any given point, but the output is always limited to text.

main {
    counter-reset: section;
}

section {
    counter-increment: section;
    counter-reset: section;
}

section > h2::before {
    content: 'Headline ' counter(section) ': ';
}

But what if you wanted to use a loop to define a recurring layout pattern? This kind of a loop is a bit more obscure: It's the Grid's auto-fill property.

.grid {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
}

This fills the grid with as many elements as it can fit, while scaling them to fill the available space, but breaking them into multiple rows when it needs. It repeats for as long as it finds items and caps them to a minimum width of 300px and a maximum width of one fraction of its own size. It's probably easier to see than to explain:

And finally, there are looped selectors. They take an argument, which can be a formula to select very precisely.

section:nth-child(2n) {
    /* selects every even element */
}

section:nth-child(4n + 2) {
    /* selects every fourth, starting from the 2nd */
}

For really special edge cases, you can combine :nth-child() with :not(), like:

section:nth-child(3n):not(:nth-child(6)) {
    /* selects every 3rd element, but not the 6th */
}

You can replace :nth-child() with :nth-of-type() and :nth-last-of-type() to change the scope of those last few examples.

Logic Gates

Ana Tudor wrote an article on CSS Logic Gates. Those work on the idea of combining variables with calc. She then goes on 3D modeling and animating objects with that. It kinda reads like arcane magic, gets way more insane as the article goes on, and is generally one of the best explanations why CSS in fact is a programming language.

Techniques

The Owl Selector

* + * {
    margin-top: 1rem;
}

The Owl Selector selects every item that follows an item. Applying a margin-top to that effectively adds a gap between the items, like grid-gap does, but without the grid system. That also means it's more customizable. You can overwrite your margin-top and adapt for any kind of content. Want to have 1rem of space between each item, but 3rem before a headline? That's easier to do with an owl selector than in a grid.

Kevin Pennekamp has an in-depth article on it that even explains its algorithm in pseudo code.

Conditional Styling

We can create toggles in our css code that switch certain rules on and off with variables and calc. This gives us very versatile conditions.

.box {
    padding: 1rem 1rem 1rem calc(1rem + var(--s) * 4rem);
    color: hsl(0, calc(var(--s, 0) * 100%), 80%);
    background-color: hsl(0, calc(var(--s, 0) * 100%), 15%);
    border: calc(var(--s, 0) * 1px) solid hsl(0, calc(var(--s, 0) * 100%), 80%);
}

.icon {
    opacity: calc(var(--s) * 100%);
    transform: scale(calc(var(--s) * 100%));
}

Depending on the value of --s, .box it will either enable or disable its alert styles.

Automatic contrast colors

Let's take the same logic one step further and create a color variable that's dependent on its contrast to the background color:

:root {
    --theme-hue: 210deg;
    --theme-sat: 30%;
    --theme-lit: 20%;
    --theme-font-threshold: 51%;

    --background-color: hsl(var(--theme-hue), var(--theme-sat), var(--theme-lit));

    --font-color: hsl(
        var(--theme-hue),
        var(--theme-sat),
        clamp(10%, calc(100% - (var(--theme-lit) - var(theme-font-threshold)) * 1000), 95%)
    );
}

This snippet calculates a background color from HSL values and a black or white font color, by inverting the background's lightness value. This alone could result in low color contrast (a 40% grey font on a 60% grey background is pretty much illegible), so I'll subtract a threshold value (the point where the color switches from white to black), multiply it by an insanely high value like 1000 and clamp it between 10% and 95%, to get a valid lightness percantage in the end. It's all controllable by editing the four variables at the beginning of the snippet.

This method can also be used to write intricate color logic and automatic themes, based on HSL values alone.

Cleaning up the Stylesheet

Let's combine what we have so far to clean up the stylesheet. Sorting everything by viewports seems a bit spaghetti-like, but sorting it by component doesnt feel any better. With variables we can have the best of both worlds:

/* define variales */
:root {
    --paragraph-width: 90ch;
    --sidebar-width: 30ch;
    --layout-s: "header header" "sidebar sidebar" "main main" "footer footer";
    --layout-l: "header header" "main sidebar" "footer footer";
    --template-s: auto auto minmax(100%, 1fr) auto /
        minmax(70%, var(--paragraph-width)) minmax(30%, var(--sidebar-width));
    --template-l: auto minmax(100%, 1fr) auto /
        minmax(70%, var(--paragraph-width)) minmax(30%, var(--sidebar-width));
    --layout: var(--layout-s);
    --template: var(--template-s);
    --gap-width: 1rem;
}

/* manipulate variables by viewport */
@media (min-width: 48rem) {
    :root {
        --layout: var(--layout-l);
        --template: var(--template-l);
    }
}

/* bind to DOM */
body {
    display: grid;
    grid-template: var(--template);
    grid-template-areas: var(--layout);
    grid-gap: var(--gap-width);
    justify-content: center;
    min-height: 100vh;
    max-width: calc(
        var(--paragraph-width) + var(--sidebar-width) + var(--gap-width)
    );
    padding: 0 var(--gap-width);
}

All the global variables are defined at the very top and sorted by viewport. That section effectively becomes the Definition of Behavior, clearing questions like:

Which global aspects of the stylesheet do we have? I'm thinking of things like font-size, colors, repeating measures, etc.
Which frequently changing aspects do we have? Container widths, Grid layouts and the like come to mind.
How should values change between viewports? Which global styles do apply to which viewport?

Below are the rule definitions, sorted by component. Media Queries aren't needed here anymore, because those are already defined at the top and put into variables. We can just code along in out stylesheets uninterrupted at this point.

Reading the hash parameter

A special case of pseudo classes is the :target selector, which can read the hash fragment of the URL. Here's a demo that uses this mechanic to simulate an SPA-like experience:

I've written a post on that. Just be aware that this has some serious accessibility implications and needs some JavaScript mechanics to actually be barrier free. Don't do this in a live environment.

Setting Variables in JavaScript

Manipulating CSS Variables has become a very powerful tool by now. We can also leverage that in JavaScript:

    // set --s on :root
    document.documentElement.style.setProperty('--s', e.target.value);

    // set --s scoped to #myID
    const el = document.querySelector('#myID');
    el.style.setProperty('--s', e.target.value);

    // read variables from an alement
    const switch = getComputedStyle(el).getPropertyValue('--s');

The codepen examples above work just like that.

Wrapping up

CSS is very much capable of difining smart and reactive layout systems. It's control structures and algorithms may be a bit weird compared to other languages, but they're there and they're up to the task. Let's stop just describing some styles and start making them work.