Here’s a little sideproject I’ve been spending my tokens on: https://gtajs.wtf/

It’s a reimplementation of the 1997 Grand Theft Auto engine in JavaScript and WebGL.

The project is not entirely finished, but since I am leaving on vacation right now (I am currently at the airport), I might as well just publish what I have — and it’s already quite a lot I think 😀

Note that because this is a reimplementation (it’s not a DOSBox wrapper / emulator / decompiled version / …) there are differences compared to the original 1997 game in certain physics behaviors, animations, etc.

The mission engine is accurate though, as that is publicly documented (the almighty mtd.doc) 😊

And yes, I totally asked Gemini to implement most things, referring Gemini to open source reimplementations, public documentation and community notes, or by simply telling it how I recall the game from playing it (and editing it!) a lot back in the day.

Still a lot of things to do (cops!) but it’s already playable. Enjoy!

~

~

# Demo

To jump right in, here’s a video of the extension in action:

The extension adds a new pane named “Scroll-Triggered Animations” to Chrome DevTools’s Elements Panel and offer the following debugging features:

• Visualize the Scroll-Triggered Animation’s scroller, element, and subject in an interactive minimap
• Supports both ScrollTimeline (scroll()) and ViewTimeline (view()).
• Shows an active/inactive status light indicator that switches from red (Inactive) to green (Active) when the trigger activates.
• Plays nice with position: sticky.
• Visualize the timeline-trigger-activation-range (blue) and timeline-trigger-active-range (green) debug lines and boxes.
• Edit the timeline-trigger-activation-range and timeline-trigger-active-range values live.

~

# Get the extension

The extension is available on the Chrome Web Store:

If you like this extension, please leave a review on the Chrome Web Store.

There is also a repository on GitHub where you can report issues and file feature requests.

~

# Backstory

While exploring CSS Scroll-Triggered Animations earlier, I built a set of demos that included an in-page debug overlay to help me make sense of what was going on, such as this debug demo on CodePen:

See the Pen Scroll-Triggered Animations: Trigger Ranges Visualizer by Bramus (@bramus)on CodePen.

That demo visualizes the activation range (in blue), the active range (in green), and also includes a little status light that switches from red (Inactive) to green (Active) whenever the subject crosses the trigger boundaries.

Back in 2023, I had built the Scroll-Driven Animations Debugger DevTools Extension which solved a very similar problem for Scroll-Driven Animations by adding a minimap and range editor to Chrome DevTools’s Elements Panel.

So I fired up Antigravity, pointed it to the source code of my Scroll-Driven Animations Debugger extension along with the Scroll-Triggered Animations visualizations I had explored on CodePen, and tasked it with combining the two into a dedicated DevTools extension for Scroll-Triggered Animations.

Because the architecture for communicating between the inspected page and the DevTools sidebar pane was already figured out in the Scroll-Driven Animations Debugger, and the visualization was already prototyped in the CodePen, Gemini had all the info it needed to build this new Scroll-Triggered Animations extension in no time 🙂

~

# Known Issues and Limitations

While the extension is mature enough to be released as version 1.0.0, there are a few things I could not work around due to browser and API limitations. These are collected in the FAQ for the extension:

• Issue #1: Ranges declared with relative or viewport units — such as 90vh — get reported as calculated pixel values in the Range Editor.

  This is not a bug in the extension, but a limitation of how the browser exposes these values: both the Animation instance and getComputedStyle($element) resolve specified relative values into computed px values. Short of parsing the raw stylesheets and running my own CSS cascade, there is no API to retrieve the authored units.

  Ideally, I want to have a function (in DevTools, but preferably DOM) that allows me to get the specified styles for an element. This request is tracked in w3c/csswg-drafts#10002 and crbug//447469710

• Issue #2 and Issue #3: The extension doesn’t work with elements inside an iframe, either showing a “Could not read the required data from the element.” error or falsely claiming that there are no Scroll-Triggered Animations attached to the element even though there are.

  This is caused by a bug in Chrome DevTools (crbug/1480418): when querying $0 via chrome.devtools.inspectedWindow.eval for an element inside an iframe, DevTools either reports undefined or lies and returns the last selected node from outside the iframe. Because of this browser limitation, the extension won’t work on CodePen’s Editor View directly — you’ll need to open the demo in CodePen’s standalone Debug View first.

~

# Future Plans

The short-term plan is to fix any bugs that might surface once people start using the extension and look into a few planned enhancements (feel free to file an idea in the repo).

Just like with the Scroll-Driven Animations Debugger Extension I built, the long-term plan is for this extension to eventually become obsolete once Chrome DevTools gets built-in debugging support for Scroll-Triggered Animations. Until then, this extension exists to fill that gap.

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~

~

# Why CSS Typed OM? (And why a polyfill?)

If you’ve ever read or manipulated styles in JavaScript using element.style or window.getComputedStyle(), you know the pain of dealing with strings. Want to read an element’s width and add 20px to it? You have to parse the string, strip the unit, convert it to a number, do the math, and concatenate it back into a string. Throw calc(), transform matrices, or modern color spaces into the mix, and string manipulation quickly falls apart.

const styles = getComputedStyle($el);
const opacity = styles.getPropertyValue('opacity');

console.log(opacity); // '0.2'
console.log(typeof opacity); // String!?

That’s where the CSS Typed Object Model (CSS Typed OM) comes in. Instead of strings, it exposes CSS values as typed JavaScript objects — such as CSSUnitValue, CSSMathSum, CSSTransformValue, and CSSKeywordValue — through element.attributeStyleMap, element.computedStyleMap(), and unit factory functions like CSS.px(20).

const styles = $el.computedStyleMap();
const opacity = styles.get('opacity');

console.log(opacity); // CSSUnitValue
console.log(opacity.value); // 0.2
console.log(opacity.unit); // 'number

However, browser support isn’t 100% uniform yet. While Chromium and Safari ship CSS Typed OM, Firefox’s native implementation is still a work in progress behind the layout.css.typed-om.enabled flag (see Firefox bug 1278697). And even in browsers that do support Typed OM, some newer parts of the spec — like the CSSColorValue subclasses (CSSRGB, CSSOKLCH, etc.) — aren’t available everywhere yet.

~

# Enter css-typed-om

Building a standalone CSS Typed OM polyfill has been sitting on my backlog for years — especially when seeing other projects like the (partial) scroll-timeline polyfill having to roll and bundle parts of the CSS Typed OM implementation themselves just to support unit values like CSS.percent() or CSS.px().

However, the CSS Typed OM specification is huge, covering everything from a full CSS tokenizer and calc() expression simplifier to 2D/3D matrix math and WebIDL interface rules. Writing all of that by hand was simply too big of an undertaking for a side project. But now, thanks to AI, that long-standing goal finally came within reach: meet css-typed-om. Guided by the specification and the official Web Platform Tests, css-typed-om is a complete, standalone, and full tested polyfill that you can drop into any project. 🚀

~

# Installation & Usage

You can install the package from npm:

npm install css-typed-om

Depending on your setup, you can use css-typed-om in two ways.

~

1. As a Global Polyfill

Import the package once at the entry point of your application to automatically patch window.CSS, Element.prototype.computedStyleMap, HTMLElement.prototype.attributeStyleMap, and all CSS Typed OM classes:

import 'css-typed-om';

// Read computed styles as typed objects
const element = document.querySelector('.my-element');
const width = element.computedStyleMap().get('width');

console.log(width.value); // e.g., 100
console.log(width.unit);  // e.g., 'px'

// Set inline styles using CSS unit factories
element.attributeStyleMap.set('opacity', CSS.number(0.5));
element.attributeStyleMap.set('margin-top', CSS.px(20).add(CSS.em(2)));

~

2. As an Explicit ES Module

If you prefer importing the classes directly (for example in unit tests or modular libraries):

import { CSSUnitValue, CSSKeywordValue } from 'css-typed-om';

const width = new CSSUnitValue(100, 'px');
const display = new CSSKeywordValue('block');

~

# Tested against Web Platform Tests (WPT)

When building a polyfill for a spec as sprawling as CSS Typed OM, custom unit tests alone aren’t enough. There are hundreds of edge cases around calc() simplification, serialization order, out-of-range value clamping, shorthand properties, and WebIDL interface rules.

To make sure the polyfill behaves just like a native implementation, I wired the repository directly up to the official Web Platform Tests (WPT) suite. Running npm run test:wpt spins up headless Firefox (with its experimental native layout.css.typed-om.enabled flag explicitly disabled), injects the IIFE build of the polyfill, and runs all 400+ WPT test files in /css/css-typed-om/.

At the time of writing, the polyfill passes 12,479 out of 13,134 WPT subtests (~95%)! 🙂

~

# Acknowledgements & Links

First of all, a shout-out to Johannes Odland, who had PR’d some significant CSS Typed OM parts into the scroll-timeline polyfill back in the day. It’s his work that first sparked the idea of writing a full, standalone CSS Typed OM polyfill.

A special shout-out and thank you goes to Jonathan Neal, who kindly handed over the css-typed-om package name on npm (which previously housed the now-archived csstools/css-typed-om project). Thanks, Jonathan! 🙌

• css-typed-om on GitHub →
• css-typed-om on npm →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~

~

# The need for a smarter numeric input field

I’m currently building a web app that has a lot of numeric inputs whose values need to be sourced from a different document. Sometimes filling in a field is a direct copy-paste of a number, but oftentimes there’s a calculation that needs to be done first — like taking one number, dividing it by 3, and subtracting another number from it.

With a standard <input> element, doing this means constantly round-tripping to a separate calculator app, crunching the numbers there, and copying the result back into the browser. Even worse: if you come back to the form later to double-check your entries, you only see the final number and have no clue which formula or source numbers produced it 😬

Instead of having to do that calculator dance over and over again, I thought of creating a more powerful input element that lets you type the formula directly into the field: <calc-input>

~

# Enter <calc-input>

<calc-input> is a custom input element that accepts mathematical formulas — such as 2 + 3 or (2 + 3) * 4 — and automatically toggles between showing the formula on focus and the calculated result on blur.

To use it, install calc-input from npm (or load it via a CDN) and drop the <calc-input> tag right into your HTML <form>:

<script type="module" src="calc-input"></script>

<form>
	<calc-input name="size" value="2 + 3"></calc-input>
	<button type="submit">Submit</button>
</form>

When focused, the input shows the entered formula (2 + 3). Upon blurring the field, it evaluates the expression and displays the calculated result (5). Re-focusing the field brings back the original formula so you can easily inspect or tweak it 🙂

Out of the box, it supports standard arithmetic operators (+, -, *, /, %, ^ / **), nested parentheses like (2 + 3) * 4, unary operators, decimals, and common math functions (sqrt, abs, round, floor, ceil, min, max, pow). All expressions are evaluated using a safe recursive-descent parser — so no eval() is involved!

~

# Demo

Give the component a try in the interactive demo below:

See the Pen
<calc-input> demo by Bramus (@bramus)
on CodePen.

For more extended demos, check out the project website.

~

# How it works under the hood

Behind the scenes, <calc-input name="size"> renders three standard <input type="text"> elements in the Light DOM, toggling which one is visible upon focus:

<calc-input name="size" value="2 + 3">
	<input type="text" name="size" hidden>
	<input type="text" name="size--formula" hidden>
	<input type="text" name="size--result">
</calc-input>

At any given time, two of these inputs have the hidden attribute so the user only ever sees one input field. When blurred, the --result input is visible; when focused, --formula input takes its place for the user to edit.

Because these are regular Light DOM inputs, native HTML form submissions and constraint validation work seamlessly out of the box. When you enter an incomplete or unparsable formula like 2 + and blur the field, <calc-input> keeps showing the formula input, highlights it with an invalid border, and calls setCustomValidity() to prevent the parent <form> from being submitted.

~

# Configuration & Styling

What actually gets submitted to the server is configurable through the submit attribute:

• submit="formula" (default): Submits all three fields, with the raw formula in the primary name="size" input.
• submit="result": Submits all three fields, with the evaluated result in the primary name="size" input.
• submit="formula-only" / submit="result-only": Omits the --formula and --result inputs from form submission so only the primary name="size" field is sent.

If the default -- delimiter in size--formula and size--result doesn’t match your backend naming conventions, you can customize it via the separator attribute (e.g. separator="_" or even separator="").

For styling, <calc-input> uses display: contents and lets its inner <input> elements inherit box and typography properties (border, border-radius, padding, background, color, font, etc.). That way, any CSS styles you apply directly onto calc-input automatically style the underlying inputs:

calc-input {
	border: 2px solid #3b82f6;
	border-radius: 9999px;
	padding: 0.625rem 1.25rem;
}

~

# More info

Check out the links below for the full documentation, more examples, and the source code:

• <calc-input> Live Demo & Documentation →
• <calc-input> on GitHub →
• calc-input on npm →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~

~

# The need

As the classic saying goes, there are only two hard things in Computer Science — and one of them is naming things. And once you have finally found a good name for your new project (like I recently had to do for <show-keystrokes> and <rich-input>), it can be pretty disappointing when that name ends up being taken already on NPM or as a domain on Netlify — something that you typically only find out upon publishing 😭

To save myself from manually checking both services over and over again, I built caniname.

~

# The CLI tool

There’s no need to install anything globally — you can run it straight via npx:

npx caniname my-fancy-new-project

For each name — yes, you can pass in multiple ones — caniname reports whether the Netlify subdomain and NPM package are available (✔) or already taken (✖, along with a link to the existing site or package). If you want to use it in scripts or CI, pass the --json (or -j) flag for structured JSON output, or import checkName and checkNames directly in Node.js.

Checking availability for my-fancy-new-project…

  ✔ Netlify  my-fancy-new-project.netlify.app is available (https://my-fancy-new-project.netlify.app)
  ✖ NPM      rich-input is taken (https://www.npmjs.com/package/my-fancy-new-project)

Right now the project only checks Netlify and NPM, but adding new service checks is pretty straightforward: every check lives in its own file inside src/checks/ and gets picked up automatically. PRs with extra checks are very welcome 🙂

~

# Go check it out

Check out caniname at the following locations

• caniname Website & Documentation →
• caniname on GitHub →
• caniname on NPM →

~

~

~

# A Quick Trip Down Memory Lane (and Project History)

If you built websites in the late 1990s or early 2000s, you might remember that Microsoft Internet Explorer 4.0 through 8.0 had a proprietary feature called Interpage Transitions. Using a simple <meta> tag in the <head> of your document, you could apply PowerPoint-style transitions — like Box in, Circle out, Vertical blinds, Checkerboard, or Random dissolve — to the entire browser viewport whenever a visitor entered or exited a web page.

<!-- Page entry effect using effect number 7 (Wipe left) -->
<meta http-equiv="Page-Enter" content="revealTrans(Duration=0.5,Transition=7)">

At the end of 2024, it struck me that we now have all the primitives in modern CSS and the View Transition API to recreate those exact transitions cleanly on today’s web. I teased an early prototype on Bluesky back in December 2024 as a little EOY project, and I even showed it off in a few conference talks since.

However, I never got around to actually covering it here on bram.us because the project wasn’t finalized yet: I had only implemented a handful of the 23 effects and still needed to wire up the trickier ones like checkerboard grids, pixel dissolves, and random bars. Recently, thanks to Gemini, I was able to easily knock out the remaining effects, polish up the interactive demo site, and finally get the whole thing over the finish line! 🙂

~

# Bringing the Oldskool Back

Rather than inventing a new configuration format, ie-page-transitions brings the oldskool back by reading the exact same <meta http-equiv="Page-Enter"> and <meta http-equiv="Page-Exit"> tags that Internet Explorer used back in the day.

Under the hood, a tiny script parses the revealTrans(Duration=…,Transition=…) declaration from your <meta> tags and translates it into Selective View Transitions with Active Types (for example, page-enter-effect-7). The accompanying stylesheet then uses the :active-view-transition-type() pseudo-class to animate the ::view-transition-old(root) and ::view-transition-new(root) pseudo-elements using modern CSS clip-path shapes, multi-layer mask-image gradients, and registered custom properties (@property).

To use it on a Multi-Page Application (aka “just a website”), opt in to Cross-Document View Transitions, load the stylesheet and render-blocking module script, and drop in your classic IE <meta> tags:

<!-- 1. Enable Cross-Document View Transitions -->
<style>
	@view-transition {
		navigation: auto;
	}
</style>

<!-- 2. Include Stylesheet and Render-Blocking Script -->
<link rel="stylesheet" href="https://unpkg.com/ie-page-transitions/ie-page-transitions.css">
<script src="https://unpkg.com/ie-page-transitions/ie-page-transitions.mpa.js" type="module" blocking="render"></script>

<!-- 3. Configure IE Page Transitions Effect(s) -->
<meta http-equiv="Page-Enter" content="revealTrans(Duration=0.5,Transition=23)">
<meta http-equiv="Page-Exit" content="revealTrans(Duration=0.5,Transition=23)">

A helper for Single-Page Applications (SPAs) is also included, alongside a set of CSS Custom Properties (like --page-transitions-blinds-bands, --page-transitions-checkerboard-columns, and --page-transitions-random-dissolve-size) in case you want to tweak the geometry of the effects.

Under the hood ie-page-transitions uses View Transition Types. Browser support therefore only starts with Chrome 125+, Safari 18.2+, and Firefox 147+ for the SPA variant. For the MPA variant, Cross-Document View Transition support is required, so that leaves Chrome 126+ and Safari 18.2+.

Because ie-page-transitions reuses the original <meta> tags originally introduced by Internet Explorer, the effects are supported not only in today’s modern browsers, but also in Internet Explorer 5.5 – 8.0 😆. In those versions of IE, the browser’s native DirectX RevealTrans filter will kick in automatically while in modern browsers ie-page-transitions takes over.

~

# Check It Out

I’ve put together a dedicated website at page-transitions.style where you can preview all 23 effects, read the full documentation, and play with both the SPA and MPA demos right inside an embedded browser shell.

• page-transitions.style (Website & Live Demos) →
• ie-page-transitions on GitHub →
• ie-page-transitions on NPM →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~

~

~

# Embed it and you’re good to go

Using <show-keystrokes> is as simple as loading the module from npm (or a CDN) and dropping the custom element onto your page. Embed it on your site and you’re good to go:

<script type="module" src="https://cdn.jsdelivr.net/npm/show-keystrokes/index.js"></script>
<show-keystrokes></show-keystrokes>

Out of the box, <show-keystrokes> listens for keyboard events and displays keyboard shortcuts (such as ⌘ + A or ⇧ + ⌘ + T) and navigational keys (such as ⇥, →, ←, ↵, and ⎋), while ignoring regular typing. If you do want to show every single key press, you can set the keystrokes attribute to all (or narrow it down to shortcuts or navigational).

<script type="module" src="https://cdn.jsdelivr.net/npm/show-keystrokes/index.js"></script>
<show-keystrokes keystrokes="all"></show-keystrokes>

The component automatically adapts to your platform (showing ⌘ and ⌥ on macOS versus CTRL and ALT on Windows/Linux), supports both symbol glyphs and text labels (⌘ vs CMD), and ships with two built-in themes that respond to light and dark mode via light-dark(). And oh, it’s fully styleable through by targeting the exposed ::part()s and custom properties.

~

# Powered by the Popover API and CSS Anchor Positioning

Depending on what you are demoing, you might want the keycaps to appear in different places. Using the position attribute, you can easily position the component in a corner of the viewport (the default is viewport top right), right next to the cursor (position="pointer"), or just inline in normal document flow (position="normal").

<!-- Fixed in the bottom-center of the viewport -->
<show-keystrokes position="viewport bottom center"></show-keystrokes>

<!-- Follow the cursor -->
<show-keystrokes position="pointer"></show-keystrokes>

<!-- Render inline in normal document flow -->
<show-keystrokes position="normal"></show-keystrokes>

Under the hood, <show-keystrokes> leans heavily on modern web platform features to make this work seamlessly without any z-index battles or JavaScript bounding-box math.

First, the component always stays on top of everything else on the page thanks to the Popover API. Its internal container is promoted to the browser’s Top Layer using popover="manual", ensuring that no matter how complex the host page’s stacking contexts are, your keystrokes will never be clipped or hidden behind another element.

Second, the component positions and repositions itself thanks to CSS Anchor Positioning. In viewport mode, it anchors itself inside a full-viewport anchor element and aligns itself using position-area, align-self, and justify-self. In pointer mode, an invisible anchor tracks your cursor coordinates (via custom properties), and the popover anchors itself next to it using position-area. The position-try-fallbacks: flip-inline, flip-block, flip-inline flip-block are set by default, so the browser automatically flips the keystroke overlay to the other side of the cursor whenever you move it too close to the edge of the viewport. 🙂

~

# Run it on any site with the Bookmarklet or Browser Extension

Because you don’t always control the source code of the site you want to demo, the project also comes with both a bookmarklet ⓘ and a Browser Extension (for both Firefox and Chrome) so you can inject <show-keystrokes> onto any webpage on the fly.

The bookmarklet is a quick drag-and-drop button (available on the demo page) that dynamically imports the package from jsDelivr and calls the programmatic create() helper. For sites with a strict Content Security Policy (CSP) or when you want <show-keystrokes> to persist across page navigations, the Chrome Extension (published) or Firefox Extension (pending review) has you covered. It bundles the component locally, lets you configure global defaults as well as per-origin overrides right from the popup, and includes a handy ⇧ + ⌘ + K (or ⇧ + CTRL + K) shortcut to toggle it on or off.

Building the extension was a bit of an afterthought once I had version 1.0.0 of the component ready. But thanks to Modern Web Guidance and its Chrome Extensions skill, creating it was easy-peasy and done in no time (also see this guide) 🙂

~

# Links

• <show-keystrokes> Live Demo & Playground →
• <show-keystrokes> on GitHub →
• show-keystrokes on npm →
• <show-keystrokes> Chrome Extension →
• <show-keystrokes> Firefox Extension →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon

~

~

~

# The Code

To make this work there is a two-way opt-in:

• The embedder (e.g. index.html) needs to set the frame-sizing CSS property with a value of auto, content-height, or content-width (or its logical variants) on the iframe.
• The document loaded in the <iframe> (e.g. iframe.html) needs to include a meta tag to indicate that it’s OK to communicate its size the parent embedder.

In code:

/* In styles.css for index.html */
iframe {
  frame-sizing: content-height;
  width: 100%;
}

<!-- In the iframe.html’s head -->
<meta name="responsive-embedded-sizing" content="allow-origins=*">

The content’s size is communicated from the embedded document after page load. To communicate a new size, the document in the frame must call window.requestResize();

Use allow-origins to limit which origins the document communicates its size info to.

~

# Demo

Here’s a demo that contains a form which is an <iframe>. Whenever you go to a next step of the form, the <iframe> resizes itself to its contents … if your browser suppports frame-sizing that is.

Because the iframe resizes itself, the form is seamlessly embedded, without any scrollbar appearing at all.

~

# Browser Support

Support for responsively size iframes is this:

Chromium (Blink)

✅ Supported in Chrome 154

Firefox (Gecko)

❌ No Support. Follow Bug 2035008 to stay up-to-date.

Safari (WebKit)

❌ No Support. Follow Bug 314713 to stay up-to-date.

~

# Learn More

Get all the details about responsive iframes on developer.chrome.com, in this article I co-authored: Responsive iframes in Chrome 154 →

~

~

The Need: Clean imports without leaking implementation details

When authoring a package, you typically have a directory layout like this:

my-package/
├── src/
│   └── index.js
├── dist/
│   └── index.js
├── package.json
└── README.md

Source code lives in src/, while your a build step typically spits out the distribution files into a dist/ or build/ folder. Or if your package has no build step, because you authored an ES Module in JavaScript, you can even ship src/ as-is. This detail can leak into your public API, which is something you generally want to avoid, especially when loading the files from a CDN.

For example, the very first version of my ie-page-transitions package — which has no build step — shipped the src folder as part of the package structure.

my-package/
├── src/
│   ├── ie-page-transitions.css
│   ├── ie-page-transitions.mpa.js
│   ├── ie-page-transitions.shared.js
│   └── ie-page-transitions.spa.js
├── package.json
└── README.md

To users that use NodeJS (or a bundler) this detail is not visible, thanks to the exports field in the package.json.

{
  "name": "ie-page-transitions",
  "version": "0.0.1",
  …
  "exports": {
    "./spa": "./src/ie-page-transitions.spa.js",
    "./mpa": "./src/ie-page-transitions.mpa.js",
    "./shared": "./src/ie-page-transitions.shared.js",
    "./css": "./src/ie-page-transitions.css"
  },
  …
}

When using NodeJS, users can just import the files straight from the package without needing to know the files live in the ./src folder. For example, the CSS can be imported as follow:

import styles from 'ie-page-transitions/css' with { type: "css" };

But for users loading the package from a CDN, it’s a different story. When loading the package from a CDN like jsDelivr, users needed to import the files from locations that all include that src folder. That same CSS file for example needs to be loaded from this location:

https://cdn.jsdelivr.net/npm/ie-page-transitions@0.0.1/src/ie-page-transitions.css

I don’t like this, because having src/ (or dist/ or build/) in public import paths is an implementation detail that leaked into the public API. It looks clunky, exposes the internal folder structure, and is just annoying to type.

~

The Solution: npm publish ./folder

For my last three packages (hic-pageflip, mermaid-element, and rich-input), which all build their source into a ./dist folder, I’ve been using a little trick to publish only the contents of the dist folder to NPM. This makes the import paths clean and direct. For example, for hic-pageflip, when loading from a CDN like jsDelivr, it does not include dist/-part in the URL:

import { PageFlip } from 'https://cdn.jsdelivr.net/npm/hic-pageflip';

To achieve this, I used a lesser-known capability of the npm CLI: npm publish accepts a folder path as an argument.

npm publish ./dist

When you pass a folder path to npm publish, npm doesn’t package the current working directory. Instead, it treats that target folder as the package root.

Whatever is inside ./dist will be placed directly at the top level of the tarball uploaded to the registry.

For this to work, you do need some extra preparation, but it’s worth it. Let me walk you through how it works.

~

Making It Work: The Missing Pieces

In order to publish the dist folder, there are two main things you need to do once your project has been built:

1. Copy other necessary package files (package.json, README.md, LICENSE, etc.) into ./dist.
2. Rewrite the package.json in ./dist so its paths match the new root (and optionally remove the scripts from that file as well).

Let’s look at both steps.

~

1. Copy files you want to package into ./dist

Because npm publish ./dist treats ./dist as the package root and ignores everything outside of it, that folder needs to contain all the metadata files required for a valid package alongside your built code:

• package.json (so npm knows your package name, version, dependencies, and entry points).
• README.md (so npmjs.com displays your documentation).
• LICENSE (so npm recognizes your license and consumers stay legally safe).

Since all of these typically live in your project root, you need to copy them into ./dist after building. You can also include other files if you want, of course.

~

2. Rewrite the package.json in ./dist

Simply copying your root package.json into ./dist as-is won’t work — the package.json in the build folder needs to be adjusted.

In your root package.json, your entry points typically include the ./dist/ prefix:

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "exports": {
    ".": "./dist/index.js",
    "./submodule": "./dist/submodule.js"
  }
}

If you copy that package.json as-is into ./dist and publish it, everything breaks because for published package, the root is the contents of ./dist itself.

So the paths in the file ./dist/package.json must be rewritten relative to the new root:

{
  "name": "my-package",
  "version": "1.0.0",
  "main": "./index.js",
  "module": "./index.js",
  "exports": {
    ".": "./index.js",
    "./submodule": "./submodule.js"
  }
}

~

The Code: Assembling ./dist

Rather than manually copying files and re-mapping every single export field by hand, you can automate both steps in a small Node.js script. For the package.json adjustments, a quick string replace does the trick: take your root package.json, strip out internal scripts, and replace ./dist/ with ./.

Here’s a clean, zero-dependency Node.js script (scripts/postbuild.js) that does the heavy lifting:

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const rootDir = path.resolve(__dirname, '..');
const distDir = path.join(rootDir, 'dist');
const srcDir = path.join(rootDir, 'src');

console.log('Preparing ./dist package...');

// 1. Clean and recreate the dist directory (if not already handled by your bundler)
fs.rmSync(distDir, { recursive: true, force: true });
fs.mkdirSync(distDir, { recursive: true });

// 2. Copy compiled/source files into dist/
fs.cpSync(srcDir, distDir, { recursive: true });

// 3. Copy essential metadata files from root to dist/
const filesToCopy = ['README.md', 'LICENSE'];
for (const file of filesToCopy) {
  const srcPath = path.join(rootDir, file);
  if (fs.existsSync(srcPath)) {
    fs.copyFileSync(srcPath, path.join(distDir, file));
  }
}

// 4. Prepare and rewrite package.json for dist/
const pkgPath = path.join(rootDir, 'package.json');
if (fs.existsSync(pkgPath)) {
  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

  // Strip scripts so consumers don't get internal build/test scripts
  delete pkg.scripts;

  // Replace ./dist/ with ./ so all paths point to the root of the published package
  const distPkgContent = JSON.stringify(pkg, null, 2).replaceAll('./dist/', './') + 'n';

  // Write out the tailored package.json to dist/
  fs.writeFileSync(
    path.join(distDir, 'package.json'),
    distPkgContent,
    'utf8'
  );
}

console.log('Successfully prepared ./dist for publishing!');

You can (and should) set this up as a postbuild step in your root package.json so that it automatically runs every time npm run build finishes:

{
  "scripts": {
    "build": "…",
    "postbuild": "node scripts/postbuild.js"
  }
}

Now, every time you run npm run build, the files and code in ./dist end up as a self-contained, publication-ready package.

~

# Safeguarding Against Muscle Memory: Prevent npm publish from running

Typically, when authoring a package that has a build step, you have npm run build execute in a prepublishOnly task in your package.json:

{
  "scripts": {
    "build": "…",
    "postbuild": "node scripts/postbuild.js",
    "prepublishOnly": "npm run build"
  }
}

That way, every time you run npm publish, npm automatically builds the project first before publishing.

However, with our subfolder setup, there’s a big catch here: developer muscle memory.

When you’re ready to ship an update and instinctively type npm publish into your terminal, npm will dutifully run prepublishOnly and execute npm run build … but then it’s still gonna try and publish the project root instead of ./dist … uh-oh!

To prevent this from ever happening, you can repurpose prepublishOnly into a safeguard and combine it with a dedicated publish script (npm run pub) that runs npm run build before calling npm publish ./dist.

In your root package.json:

{
  "scripts": {
    "build": "…",
    "postbuild": "node scripts/postbuild.js",
    "prepublishOnly": "if [ -z $PUBLISH ]; then echo 'n🛑 ERROR: This package must be published using `npm run pub`n' && exit 1; fi",
    "pub": "PUBLISH=true npm run build && npm publish ./dist"
  }
}

The trick here is the $PUBLISH environment variable. When you run npm publish directly, $PUBLISH is not set, and the script simply exits — preventing npm publish from running.

In the pub script (invoked via npm run pub), $PUBLISH gets explicitly set to true, which allows the build and npm publish ./dist to go through without being blocked.

This setup is simple, elegant, and completely foolproof 🙂

~

Testing Your Publish: Dry Runs and Tarballs

Before you publish a package to the live registry for the first time with this setup, don’t just push it and hope for the best. Test it locally first.

Here are two essential commands to verify your setup:

1. Perform a dry run with npm publish ./dist --dry-run

You can run npm publish with the --dry-run flag pointing to your folder:

npm publish ./dist --dry-run

This runs the entire publishing pipeline — tarball creation, file filtering, checksum generation — without actually uploading anything to NPM.

It outputs a detailed manifest of everything that will be shipped:

npm notice === Tarball Contents ===
npm notice 1.1kB  LICENSE
npm notice 1.8kB  README.md
npm notice 850B   index.js
npm notice 1.2kB  package.json
npm notice 4.2kB  core/engine.js
npm notice === Tarball Details ===
npm notice name:          hic-pageflip
npm notice version:       1.0.1
npm notice filename:      hic-pageflip-1.0.1.tgz
npm notice package size:  3.2 kB
npm notice unpacked size: 9.1 kB
npm notice total files:   5

Look closely at that file list: notice how index.js, README.md, and LICENSE are all sitting right at the root, with no dist/ prefix in sight? That’s your confirmation that the subfolder structure is working as intended.

~

2. Inspect the created tarball with npm pack

The previous step already generates the tarball for publishing. You can also run npm pack on its own to generate a local tarball (e.g. my-package-1.0.0.tgz) for inspection.

# Be sure to run npm run build first
npm pack ./dist

You can then extract and inspect the contents of the generated tarball:

tar -xzf my-package-1.0.0.tgz ./my-package-1.0.0

Now you’ll see the contents of ./dist sitting right in the folder ./my-package-1.0.0 which confirms that the package was correctly packaged and is ready for publishing.

~

In Closing

Publishing a subfolder instead of your repository root is one of those small tweaks that, I think, makes for a better package, without much added complexity. I’ve successfully used this pattern in multiple projects, including hic-pageflip and rich-input.

It feels a bit stupid that NPM does not have this functionality built in, especially since developers have been asking about this for more than 10 years by now. A new publishDirectory field in the package.json that instructs npm publish to publish that specific subfolder would be welcome here. PNPM has this (publishConfig.directory), and I think it’s long overdue for NPM to support this as well …

Until then, you can use the pattern I detailed here in this post 🙂

~

Spread the word

Feel free to reshare this post on social media to help spread the word:

• 🦋 Bluesky
• 🐘 Mastodon
• 💼 LinkedIn

~

~

~

# The need for a rich search input

If you have ever used search fields on GitHub, Gmail, or modern music databases, you know the pattern: you can type regular free-text words, but you can also narrow things down using structured key:value pairs. For my record collection side-project, I wanted exactly that kind of search engine-grade filter intelligence.

I wanted to be able to type queries such as ambient artist:"Aphex Twin" label:"Warp Records"; year:2024, complete with autocompletion for both the filter keywords and their allowed values. On top of that, I wanted in-input syntax highlighting for the structured filter values, without relying on heavy frontend frameworks or breaking standard form behaviors.

Looking around a bit, it seemed like an easy-to-use, standalone custom element providing this out of the box simply did not exist yet. So I nerd sniped myself into creating one: <rich-input>.

~

# What is <rich-input>?

<rich-input> is a standalone Web Component that gives you smart, keyword-aware search fields. You configure it completely declaratively by nesting standard HTML <datalist> elements inside it:

<script type="module" src="https://cdn.jsdelivr.net/npm/rich-input/index.js"></script>

<rich-input placeholder="Search music catalog...">
  <!-- String filter with rich autocomplete options -->
  <datalist id="label" label="Record Label">
    <option value="Warp Records">
      <img src="assets/warp-records.png" height="50" width="50" alt="Warp Records">
      Warp Records
    </option>
    <option value="Ninja Tune">
      <img src="assets/ninja-tune.jpg" height="50" width="50" alt="Ninja Tune">
      Ninja Tune
    </option>
  </datalist>

  <!-- Numeric filter -->
  <datalist id="year" label="Release Year" data-type="number">
    <option value="2026"></option>
    <option value="2025"></option>
    <option value="2024"></option>
  </datalist>
</rich-input>

With just that markup in place, the component gives you:

• Dual Autocompletion: It automatically suggests filter keywords when you start typing a word (e.g. typing l suggests label:, typing y suggests year:) as well as the values for that keyword (typing label:“W suggests Warp Records).
• Full-String Suggestion Filtering: The suggestion dropdown filters against the full token string rather than a naive slice at the caret position. Whether your caret is at label:“W|arp Records” or right between the colon and quotes at label:|“Warp Records”, the dropdown cleanly matches the actual value.
• Rich Option Markup: You can embed <img> logos or avatars inside your <option> tags. The component extracts them into the autocomplete popover and exposes ::part(suggestion-image) so you can style them (e.g. as circular avatars).
• Validation & Squiggly Underlines: If you enter an unrecognized keyword or a value that is not part of the configured <datalist>, the component marks it as invalid with a wavy red underline via ::highlight(rich-input-invalid) once your cursor moves away or the input loses focus.
• Native Form Participation: It uses formAssociated = true, so it seamlessly submits via standard <form> elements and works with FormData.

Try it out here:

~

# Powering it with the OpaqueRange API

I knew this project would be quite easy to build thanks to the new OpaqueRange API (as recently covered by Ollie Williams), available in Chrome 152+.

Historically, doing any kind of rich interaction inside a native <input> — such as measuring exact caret coordinates to position a popover, or applying styling to substrings within the input — was a notorious exercise in pain. You had to resort to brittle “mirror div” hacks: an off-screen or invisible <div> styled with the exact same font, padding, border, and scroll offsets, replicating the input’s text to measure coordinates.

With OpaqueRange native text inputs gain first-class range capabilities. You can call input.createValueRange(start, end) to get an OpaqueRange representing any text slice inside the control. This unlocks two massive superpowers:

1. Anchoring popovers: You can call range.getBoundingClientRect() directly on an OpaqueRange to get the exact viewport coordinates of the active token or caret, allowing the autocomplete popover to anchor precisely to the start of the token.
2. Custom Highlights: You can register the ranges with the CSS Custom Highlight API via CSS.highlights.set(keyword, new Highlight(range)). That means you can style each keyword’s value directly in your CSS stylesheet!

/* Style record label values */
::highlight(label) {
  background-color: oklch(0.92 0.08 240);
  color: oklch(0.28 0.14 240);
  text-decoration: 2px underline solid oklch(0.5 0.15 240 / 0.5);
}

/* Style release years */
::highlight(year) {
  background-color: oklch(0.93 0.1 85);
  color: oklch(0.35 0.14 85);
}

/* Style invalid tokens with a wavy red squiggly */
::highlight(rich-input-invalid) {
  text-decoration: underline wavy #ef4444;
  text-decoration-skip-ink: none;
}

Because these are native highlights, text selection, copy-pasting, undo/redo stacks, and caret navigation continue to work 100% natively without any layout shifts or DOM synchronization glitches.

~

# The Cross-Browser Fallback

Because OpaqueRange is still brand new and currently only supported in Chromium 152+, the component also comes with a built-in fallback strategy. When OpaqueRange is not supported, the component internally swaps the native <input> inside its Shadow DOM for an adapted, single-line [contenteditable] element and resorts to regular CSS Custom Highlights to do the highlighting — a technique I pioneered in https://brm.us/syntax-highlighting.

For some reason the Custom Highlights do not cross into the Shadow DOM in Firefox and Safari. To fix that, the component also copies over document’s custom highlights from document.stylesheets into the Shadow DOM. Also accepted is a <style> element nested directly inside the <rich-text>.

~

# AI-Assisted with Google Antigravity

Just like my previous two custom element projects (<hic-pageflip> and <mermaid-element>), this component was built with AI assistance using Google Antigravity.

I used stock Antigravity powered by Gemini, configured with the Modern Web Guidance skill and the Chrome DevTools MCP server.

In my prompt, also explicitly pointed Antigravity to my two previous repositories, instructing it to replicate their project layout, demo structure, and styling. Finally, I also included links to resources about OpaqueRange, including Ollie’s post. You can check my initial prompt here:

Create me a rich search component `<rich-search>` that can automplete values for keyword-bases searches.

The component is and acts like a regular `<input type=text>` so you can type in just text. But when typing in specific keywords it should add suggestions for those keywords. Those keyword-searches are in the form  of `keyword:value`

As an example, some keywords and values one could entere for a music application are:
- genre:"<string>"
- style:"<string>"
- year:<number>
- label:"<string>"
- artist:"<string>"
- mix:"<string>"
- mixid:<number>
- playlist:"<string>"
- playlistid:<number>

An example search string could be something like `label:"We Play House Recordings" year:2026 playlist:"WPH Classics"`.

The search field should be able to autocomplete:
- The keywords. E.g. when I type in `m` at the start of a new word, it should suggest `mix:` and `mixid:` which I can choose from a list of suggested options.
- The values for those keywords. E.g. when I start typing `label:"K|` (with | being the current cursor position), then it should suggest the labels “Kranky” and “Keinemusik”.

The configuration of all this happens through `<datalist>` elements that are placed inside the `<rich-search>` element. E.g. this could be the list that suggest values for `label`:

```html
<datalist id=label label="Record Label">
  <option value="Defected"></option>
  <option value="Keinemusik"></option>
  <option value="Kranky"></option>
  <option value="Ninja Tune"></option>
  <option value="We Play House Recordings"></option>
  <option value="XL Recordings"></option>
</datalist>
```

Technically, implement this using the OpaqueRange API. Check these resources for info:
- https://chromestatus.com/feature/6297362687066112
- https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/OpaqueRange/explainer.md
- https://olliewilliams.xyz/blog/opaquerange/

Styling of the values using the Custom Highlights API should be possible (e.g. `::highlight(label)` can be used to style the value set in label:"We Play House Recordings"). Styling of the input itself should be done using `::part()`.

Follow the project structure as seen in the projects https://github.com/bramus/hic-pageflip and https://github.com/bramus/mermaid-element. Also use the same demo structure and style.

Antigravity handled this prompt very well. Like, it came up with adding a little leading icon, added a “clear input” button, added keyboard navigation, added the getParsedQuery() API, etc. all without me asking 🙂

(Later on I renamed it from <rich-search> to <rich-input>, added support for images, added the fallbacks, etc.)

~

If you take a look at the commit history on GitHub, you’ll notice that most commit messages include the exact prompt I used. One commit I really liked is the one where I asked it to generate a visual similar to the one Una made for Customizable Select.

The result (after two extra nudges that got squashed into the commit) is this nice visual:

~

# Get the package

You can use <rich-input> right now or drop it into your own projects:

To install it via npm:

npm install rich-input

Once imported, the custom element is ready to use (the package registers the component all by itself)

import rich-input;

Alternatively, you can load it directly in HTML from a CDN such as jsDelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/rich-input/index.js"></script>

~

# Links and Resources

Check out the following links for more info and demos:

• 🚀 Project Homepage & Live Demo: https://rich-input.netlify.app/ →
• 📦 NPM Package: rich-input on npm →
• 💻 Source Code: bramus/rich-input on GitHub →

~

# Spread the word

Feel free to reshare one of the following posts on social media to help spread the word:

• 🦋 Bluesky
• 🦣 Mastodon
• 💼 LinkedIn

~