Microblog

Here’s a code sample from a project I am working on.

const readAsset = (relativePath: string) =>
  readFile(join(options.assetRoot, relativePath), "utf8");

const [
  registry,
  launcherHtml,
  launcherScript,
  launcherStyles,
  workspaceHtml,
  workspaceScript,
] = await Promise.all([
  loadWorkspaceRegistry(options.registryPath),
  readAsset("index.html"),
  readAsset("assets/launcher.js"),
  readAsset("assets/launcher.css"),
  readAsset("workspace.html"),
  readAsset("assets/workspace.js"),
]);

AFAIK this is the bog standard approach to awaiting a bunch of things at the same time. When its two to three items this is relatively ergonomic, but once you get past 5 I think it really just looks kind of gross.

All I want is a bunch of things to run concurrently, and for the name of the thing to be right next to the thing!

Because none of my problems or ideas are original, there is certainly many many approaches to obviate this “define over under instead of side by side” friction.

Here’s a sketch of what I thought would look the best.

const loaded = await resolveProperties({
  registry: loadWorkspaceRegistry(options.registryPath),
  launcher: resolveProperties({
    html: readAsset("index.html"),
    script: readAsset("assets/launcher.js"),
    styles: readAsset("assets/launcher.css"),
  }),
  workspace: resolveProperties({
    html: readAsset("workspace.html"),
    script: readAsset("assets/workspace.js"),
  }),
});

loaded.registry;
loaded.launcher.html;
loaded.workspace.script;

One benefit is that you can nest your calls into groups if you wanted to. Yes, I am aware this is now a materially different execution pattern, it’s just an option!

So it’s kind of like a structured concurrency nursery, except you don’t really have a way to cancel promises when siblings fail.

The helper is small:

async function resolveProperties<
  const T extends Record<string, unknown>,
>(properties: T): Promise<{ [K in keyof T]: Awaited<T[K]> }> {
  const entries = await Promise.all(
    Object.entries(properties).map(async ([key, value]) => [
      key,
      await value,
    ] as const),
  );

  return Object.fromEntries(entries) as {
    [K in keyof T]: Awaited<T[K]>;
  };
}

I didn’t end up actually using this because I only had the one case of the longer-than-three promise chain in the repo. I’d rather stick to the gross conventions for a one-off, but it sure is pretty!

So after reducing the Flash of Unstyled Text caused by the text re-rendering when the custom fonts load, I was still getting some flashing on the “heros” (the post banners with the abstract space images).

The first attempt I originally did was to ensure that the image element was pre-sized with the dimensions of the images, that way the renderer could have the same rect size prior to it loading. This helped the layout not shift, but didnt prevent the image from flashing on load. I tried to mitigate this a bit by setting the element background to be black, so that only the white elements in the hero flashed. This was also a bit of an improvement, but it still would flash visibly.

Then I remembered coming across the website catalog for McMaster-Carr which was going around tech circles a while ago for having some tight optimizations. This helped me recall that I could simply just prefetch the images on the recent posts when you load the home page.

Using Prefetch is much lower priority than Preload and in both optional for the browser to execute and will not impact the current page’s asset loading or rendering cycle.

It’s just a link type like this

<link rel="prefetch" as="image" href="/generated/heroes/example-post.png">

Since I am using hugo, I build the recent posts lists dynamically already, so I added a prefetch to the images found in the posts alongside of it.

{{ $posts := where .Site.RegularPages "Section" "posts" }}

{{ range first 5 $posts.ByDate.Reverse }}
  {{ $slug := .Title | urlize }}
  <link rel="prefetch" as="image"
    href="{{ printf "generated/heroes/%s.png" $slug | relURL }}">
{{ end }}

This technique only makes a difference if you happen to land on my front page hank.bond/.

Where we do use Preload instead is in the base html mixin for site pages to load the base fonts that make up above-the-fold page copy. This helps make sure that no matter which page you are linked to the fonts are loaded high priority upfront and not only after loading the style sheet.

Since I use a lot of unique fonts on my site (I love bitmap fonts!) and I have not put much effort into optimizing the page loads, I was noticing quite a bit of Flash of Unstyled Text.

Before the browser downloads your custom fonts, it will first draw the page with the system default fonts it already has available (which are platform specific). Then after it downloads your fonts, it will repaint the website. The problem is that rarely do your custom fonts match the shape and size of the defaults.

Font Loading

Here is what it looks like in practice.

/* Custom webfont */
@font-face {
  font-family: 'Espy Sans 12';
  src: url('/fonts/EspySansRevived-12px-Bold.woff2')
    format('woff2');
  font-weight: bold;
  font-style: normal;
  font-display: swap;
}

/* Metric-matched local fallback */
@font-face {
  font-family: 'Espy Sans 12 Matched Fallback';
  src: local('Verdana Bold');
  /* The important bits! */
  size-adjust: 106.9219%;
  ascent-override: 70.1446%;
  descent-override: 23.3815%;
  line-gap-override: 23.3815%;
  font-weight: bold;
  font-style: normal;
}

/* Use the adjusted fallback until Espy loads */
:root {
  --font-espy-12:
    'Espy Sans 12',
    'Espy Sans 12 Matched Fallback',
    /* Another option if Verdana is not available */
    'Espy Sans 12 Arial Fallback',
    'Espy Sans 12 Roboto Fallback',
    sans-serif;
}

So the idea is that you can use a system font and change the styling with these overrides that allow you to closer align its overall page size to your custom font. You can take this a step further by finding the system font that already is the closest shape, so that even the individual character shifts are minimized.

Since there was a clear success criteria (minimize visual differences) this seemed like a perfect goal for an LLM to automate. I didn’t do any fancy harness engineering, I just asked for it to minimize the differences and prodded it a few times. I already have a local headless chromium so it used that to render the pages. Because this would otherwise be a very laborious process of tweak-check-tweak-check, I am very thankful that was able to automate this.

So mark this down as one of the tasks the clankers are especially well suited to tackle.

This one is a bit of a ramble but I have some loose questions bouncing around rn.

Who owns the Agentic capabilities you create for yourself in the course of working somewhere? When you learn something during your day job, it’s tacitly agreed upon that the knowledge in your meat machine is yours to keep. It’s not like the company has direct access to it anyway, they have to use You as an Interface to get access to it anyway. They own the code you create, but not the knowledge of how to re-create that code (outside of some strict trade-secret agreements I guess).

Can the same be said of personal Harness artifacts you create? Do they own the skills you create for yourself to use? The lawyers can figure that one out, and judging every employment agreement I have signed I would assume yes since it was created on company time and created with company resources (tokens + laptop).

So lets say that you air-gap your Harness customization and re-create the important bits into your non-work-truly-personal Harness. Do you then bring that to a new company directly? Is the expectation that all modern Software Engineers come with some level of tooling off the jump, If so, do they own that version?

If the Harness was really only meant to be useful to you, does it get thrown out when you leave? Do you have to re-create a new work harness from scratch when you start working at a new place? Even if a lot of it is already wired up for general use, surely you want to customize it to fit your tastes more closely.

Creative vs Assertive

This is not really a hot take, but I was just thinking about how in The Before Times we already had different developer setups when we did work. I’m pretty basic and just raw dog VS Code without any meaningful extensions. Plenty of coworkers have used JetBrains flavors, Vim, EMacs, some even use Sublime Text because they like the simplicity.

The human aspect of the code creation was also very different person to person. Each team member had their own affinity for certain design patterns, and as long as it was understandable to the others pretty much anything goes. Names of Things are also relatively arbitrary, so variance there was to be expected as well.

However, on any given project we would usually commit to one linter tool (or at least ruleset) so all the code would stay consistent and we didn’t have to Nit syntax at review time. We needed to use one testing framework, CI runner, and code doc format. So already we have this split between the Creative bucket where variance is acceptable (and maybe even beneficial a-la “diversity is our strength”), and the Assertive bucket where rules are required because the system will not work without it.

But we were still largely un-opinionated in how the code was created, just that it produced the correct result (accuracy) and the shape of it was consistent with the rest of the code and the team’s expectations (precision).

“I don’t really care how you create the code, just that the code is Good.”

Agents as an Extension of You

It seems to me that Agentic tooling for the purpose of code generation probably staddles both Creative and Assertive buckets, although certainly less assertive than one might think.

If you use a local indexer to chunk and vectorize your code, or if you use an LSP to traverse your code with graphs, or if you are just a token burning grep-aholic, its not really anyone elses concern how you and your Agents work your way around the repo. You can likely plan the way you want to (as long as you use the required ticket fields/tags), you can steer the model to generate code the way you prefer, and you can build your own review skills and tooling however it is that suits you.

Now some teams may focus more on persisting the knowledge and guidance and workflows into the common repo instead of the personal harness. This is probably better for anything that the team can agree upon. If one team mate discovers some external context in the course of doing work, its certainly better for everyone else to have their context updated so they don’t have to rediscover it on their own. I think this is especially true as a way to improve the onboarding experience. You could say then the Agent should also be an extension of Your Team.

You could probably extend that out even further to Your Company. Personally, I think the value in using Model based workflows is that they allow for interfacing using Associative Processes that don’t need to match each other exactly.

So if we treat PRs like an API, where the provider doesn’t care what you do with the data, as long as you pull and push according to the schema, we really aren’t in that much of a different place than we used to be. The primary difference is that a larger proportion of the teams automative capacity is the sum of the individual team members’ capacity.

Unlike when I am prototyping a solution using tools, concepts, and frameworks that I already understand, when I am trying to work in an area where I cannot be a reliable judge, I tend to iterate much more carefully. There’s really two frames that I am under when working with Models and they are mostly mutually exclusive. I try to increase either speed of:

1. Output artifact creation by leveraging my expertise and ability to Judge faster than I can Do.
2. Input knowledge acquisition by leveraging the Model’s ability to Explain faster than I can Do.

So in the second frame, the primary goal is that I bring myself up to speed until I feel comfortable defending the directions we have taken. Yes sometimes its just “well that’s the best I can understand this for now”, but when the session is over I am one step closer to reaching the first frame.

The downside is that there are fewer times where I am learning purely through discovery. Often, I am using some other knowledge I already have, to inform whether I should push back/dive in or accept the Model’s Justifications.

Honestly, I think for most things I have been learning lately thats ok. It’s not too different from learning by reading a textbook isntead of just pure experimentation.

As I come to experiment more downstream of that acquisition, I can deviate from the standard approach. For the time being, I’m content probing the Model for what it considers “best practices”.

Was talking with Chat about whether or not we were maximally using HTML tags that are more semantic in nature in this site’s templates and processing. Given that this is currently a Hugo based site, and its pretty easy to improve HTML usage with automation, I thought it would good to explore this.

Here are some cool (by my estimation) HTML tags that I was not aware of before.

abbr is for acronyms and abbreviations. I find this valuable because while I love to use acronyms for the improved information density, I really don’t like assuming that everyone reading will be aware of what they mean. As a reader/learner I find these types of assumptions very freustrating, especially when they are for terms and abbreviations specific to an industry. Using this tag lets me document what abberviations stand for pretty easily.

Now, I figured it would be really annoying to have to dedicate a cycle to updating every post I write with these tags manually, and using an agent would work but we use code for everything we can. So what I did was use a preprocessor on my articles searching for acronyms, and I started keeping a central list of all the acronyms I want defined. This way I can get the first use per-post to have a tooltip and definition the user can click on.

<abbr title="Model Context Protocol">MCP</abbr>
<abbr title="Command Line Interface">CLI</abbr>
<abbr title="Out Of Memory">OOM</abbr>

dfn Is a way to identify a term we want to define. When left alone I tend to settle on my own language for things. Sometimes they are pretty intuitive like the term Gap and sometimes it needs a little explenation like when I say I am talking to Chat (because I guess I’m just a little twitch-rotted). Either way, it’s helpful to have embedded definitions and this lets me also make use of popovers to display the definition on hover.

<dfn>Gap</dfn> is the difference between what I expected and what actually happened.

I think it’s pretty neat.

This one may have been obvious to others but I didn’t know about the <q> tag for “inline quote” formatting. I was thinking of making a parser syntax for markdown to support this (compared to > block quotes) but then realized its already so short I should just turn on raw HTML support in my .md -> .html processing and rip the raw <q> tags.

Why would I want to format this differently you say? 
<q>Because it looks cooler that way</q> I say

Why would I want to format this differently you say? Because it looks cooler that way I say.

samp is for output from a program, tool, model, shell, whatever. In the Reflection post, the commit.md windows are code or prompt text, but the response windows are sample output.

<pre><samp>Update parser

Updated the parser to handle large files better.</samp></pre>

I don’t really know how useful this one is but it was new to me so I thought I would mention it.

aside is for “a side” note. This is a semantic way for me to have sub-text in these code block windows. When I tag a codeblock like such

```text { title="commit.md" caption="Green highlight means we net-added this from the previous entry." }
Write a commit message for this diff. ++Include why the change was made, not just what.++
```

this ends up being

Write a commit message for this diff. ++Include why the change was made, not just what.++

which among other things includes.

<aside class="code-window-note">
  Green highlight means we net-added this from the previous entry.
</aside>

So if I can hide the HTML through markdown preprocessing or Hugo hooks I’m all for it. In the cases where its simplest just to throw some tags into the markdown directly, I just go with that.