Forem: SEN LLC

The Three Conditions for Seeing the ISS — A Browser-Only Visibility Calculator with Spherical Trigonometry

SEN LLC — Fri, 01 May 2026 23:08:04 +0000

When ISS passes overhead at the right moment, you can step outside and watch a bright point of light streak from west to east at ~7 km/s — apparent magnitude around −5, brighter than Venus, no telescope needed. The interesting part of building a "is it visible right now?" tool is that just plotting the dot on a map doesn't answer the question. Three independent conditions all have to be true:

ISS above your horizon (geometry)

ISS sunlit (not in Earth's shadow)

Your sky dark enough (sun far enough below your horizon)

All three fall out of one REST API call plus ~200 lines of spherical trig. Here's the math.

🛰️ Demo: https://sen.ltd/portfolio/iss-tracker/
📦 GitHub: https://github.com/sen-ltd/iss-tracker

The API: wheretheiss.at gives you everything you need in one shot

There are several ISS position APIs. The one that's HTTPS-friendly, no-auth, and returns all the fields the visibility math needs is api.wheretheiss.at:

$ curl -s https://api.wheretheiss.at/v1/satellites/25544 | jq
{
  "name": "iss",
  "id": 25544,
  "latitude": 28.857,
  "longitude": -6.671,
  "altitude": 416.42,            # km
  "velocity": 27603.81,          # km/h
  "visibility": "eclipsed",      # ← is the satellite sunlit or in shadow?
  "footprint": 4489.21,          # km
  "solar_lat": 15.30,            # ← sub-solar point (where the sun is overhead)
  "solar_lon": 197.78,
  "timestamp": 1777675555
}

Two fields are gold:

visibility is a satellite-side property — the API does the Earth-shadow geometry for you. "daylight" means ISS is in sunlight; "eclipsed" means it's in Earth's shadow. That's condition 2 done.
solar_lat, solar_lon is the sub-solar point — the (lat, lon) where the sun is directly overhead at this instant. With the observer's lat/lon, the sun's altitude above the observer's horizon is one trig formula away. That's the input for condition 3.

The older api.open-notify.org is HTTPS-broken and doesn't even return altitude. Use wheretheiss.

Condition 1: ISS above the observer's horizon

Treat Earth as a sphere of radius R. Given satellite altitude h and the great-circle distance d from observer to ISS sub-point, the slant range and elevation come from the OES triangle (Observer, Earth-centre, Satellite) via the law of cosines:

slant² = R² + (R+h)² − 2R(R+h)·cos(d/R)
sin(elevation) = ((R+h)·cos(d/R) − R) / slant

elevation > 0 means ISS is above the observer's horizon — physically possible to see. Negative means it's on the far side of the planet, no chance.

export function elevationDeg(observerLat, observerLon, subLat, subLon, altitudeKm) {
  const d = haversineKm(observerLat, observerLon, subLat, subLon);
  const θ = d / EARTH_RADIUS_KM;
  const R = EARTH_RADIUS_KM, h = altitudeKm;
  const slantSq = R*R + (R+h)**2 - 2*R*(R+h)*Math.cos(θ);
  const sinE = ((R+h)*Math.cos(θ) - R) / Math.sqrt(slantSq);
  return Math.asin(Math.max(-1, Math.min(1, sinE))) * 180 / Math.PI;
}

The footprint radius drops out

The locus of points where elevation = 0 (line-of-sight tangent to the Earth at the observer's feet) is a small circle on the sphere — the satellite's "footprint." Geometry:

cos α = R / (R + h)
footprint_km = R · α

For ISS at 408 km, α ≈ 20° and the footprint radius is ~2222 km. Anyone outside that radius from the sub-point is below the horizon, full stop.

export function footprintKm(altitudeKm) {
  const cosAlpha = EARTH_RADIUS_KM / (EARTH_RADIUS_KM + altitudeKm);
  return EARTH_RADIUS_KM * Math.acos(cosAlpha);
}

Condition 2: ISS in sunlight, not Earth's shadow

Even if ISS is directly overhead at midnight, if it's in Earth's shadow it's invisible. It has no light source. ISS reflects sunlight off its solar panels — that's why it's bright when sunlit.

ISS orbits Earth every ~90 minutes, so each orbit it passes through Earth's shadow for some fraction of the loop. That "ISS overhead but eclipsed" case is exactly why a midnight pass over your head can fail to be visible.

The API handles this for you: iss.visibility === "daylight" ⇒ sunlit ⇒ condition 2 met.

Condition 3: the observer's sky is dark enough

Daytime ISS isn't visible — the bright sky drowns out a 5th-magnitude moving point. We need the observer to be in twilight or darker.

Sun altitude from sub-solar point is one formula:

sin(sun_altitude) = sin(obs_lat) · sin(sun_lat)
                  + cos(obs_lat) · cos(sun_lat) · cos(obs_lon − sun_lon)

Astronomical convention:

Sun altitude	Phase	ISS visible?
> 0°	Day	No
0° to −6°	Civil twilight	Sky still too bright
−6° to −12°	Nautical twilight	Marginal
−12° to −18°	Astronomical twilight	Yes
< −18°	Full night	Best

The practical threshold for ISS visibility is sun altitude < −6° (civil twilight or darker).

export function sunAltitudeDeg(observerLat, observerLon, sunLat, sunLon) {
  const φo = deg2rad(observerLat);
  const φs = deg2rad(sunLat);
  const dλ = deg2rad(observerLon - sunLon);
  const sinH = Math.sin(φo)*Math.sin(φs) + Math.cos(φo)*Math.cos(φs)*Math.cos(dλ);
  return rad2deg(Math.asin(Math.max(-1, Math.min(1, sinH))));
}

The combined verdict:

const visible = elevation > 0
             && iss.visibility === "daylight"
             && sunAltitudeDeg(obs.lat, obs.lon, iss.solar_lat, iss.solar_lon) < -6;

What this tool deliberately doesn't do

heavens-above.com and NASA's spotthestation tell you "ISS will pass over your location at 19:42 UTC tomorrow, max elevation 67°, visible from 19:43 to 19:47." To do that yourself you need:

Two-Line Element sets (TLEs) from celestrak.com
SGP4 orbital propagator — the standard NORAD model for satellites in low Earth orbit, ~2000 lines of dense numerical code (atmospheric drag, J2/J3/J4 perturbations, geopotential)
A sweep over the next 24-48 hours sampling at minute resolution
Apply the three-condition visibility check at each sample to find the windows

satellite.js is ~50 KB of bundled SGP4 if you want it. But spotthestation already does this perfectly, so this tool stays focused on right now: 200 lines, no library, no orbital propagator.

Map rendering — no coastlines, on purpose

The expected ISS-tracker visual is "moving icon on a Mercator world map." Shipping coastline data costs ~50-100 KB of bundled GeoJSON and brings projection-distortion problems near the poles. Equirectangular x = lon, y = -lat is one line of code; a graticule (lat/lon grid) gives the eye anchor points; the data overlay (ISS dot + footprint cap + observer + sub-solar) carries the visual weight. Cleaner, no dependency, fits the "the math is the show" angle.

<svg viewBox="-180 -90 360 180">
  <g id="graticule"></g>
  <g id="footprint"></g>
  <g id="iss"></g>
  <g id="observer"></g>
  <g id="sun"></g>
</svg>

Takeaways

ISS visibility = AND of three independent conditions: above-horizon (geometry), sunlit (API field), observer-sky-dark (sun altitude < −6°).
api.wheretheiss.at is the right API — HTTPS, no auth, returns altitude / velocity / visibility / sub-solar point in one call.
The geometry: haversine distance, OES triangle for elevation, cos α = R/(R+h) for footprint, sin·sin + cos·cos·cos for sun altitude.
Pass prediction (next time ISS will be visible) deliberately out of scope — that needs TLEs and an SGP4 propagator. NASA's spotthestation already nails it.

Full source on GitHub — iss.js is the 200-line geometry module, tests/iss.test.js is 24 cases. MIT.

Live demo updates every 5 s. The "Use geolocation" button pre-fills the observer to your current location.

Sample-Free Drum Synthesis in Web Audio — Building Kick, Snare, and Hi-Hat from Oscillators in 60 Lines

SEN LLC — Thu, 30 Apr 2026 23:04:48 +0000

Most drum machines on the web load .wav or .mp3 samples and play them back. That works, but you can also synthesise every voice from OscillatorNode, BufferSource-as-noise, and BiquadFilter — no audio files needed, no fetch wait, instant click-to-play.

Here's a 16-step drum machine where every voice is built in code (≈20 lines each), plus the acoustic reasoning behind why the recipes work.

🥁 Demo: https://sen.ltd/portfolio/drum-machine/
📦 GitHub: https://github.com/sen-ltd/drum-machine

Three knobs that make a sound feel like a drum

Three properties matter when synthesising a percussive hit:

Property	What it controls	How to set it
Energy curve	How sharp the attack is, how fast it decays	`GainNode.gain` with `setValueAtTime` + `exponentialRampToValueAtTime`
Spectrum	The "colour" of the sound — dull, bright, metallic	`OscillatorNode.type` (sine/triangle/square) + `BiquadFilter`
Pitch motion	High at the attack, dropping into the body (the essence of a kick)	`frequency.exponentialRampToValueAtTime`

Sample playback locks all three to "however the recording captured them." Synthesis lets you tune each one independently — small adjustments like "sharper attack" or "thicker body" become parameter changes.

Kick — sine sweep + fast amp decay

A real kick drum is "click" → "boom": the beater hits the head with a sharp transient, and the resonance of the shell decays into a low fundamental. One sine oscillator with a fast pitch sweep does this convincingly:

osc.frequency.setValueAtTime(150, time);                       // attack
osc.frequency.exponentialRampToValueAtTime(48, time + 0.05);   // body (50 ms)
amp envelope: 1.0 → 0.0001 over 450 ms (exponential)

What matters:

The 150 Hz → 48 Hz drop creates the "click → boom." 150 alone is too pitched, 48 alone has no attack.
The 50 ms ramp is fast — humans hear sub-30-ms events as a single click, not as motion.
The 450 ms amp decay sits in the right pocket. Shorter sounds tinny ("pip"); longer drags the boom and crowds the next beat.
The waveform is always sine. Triangle or square add audible upper harmonics that read as "synth," not "drum."

export function playKick(ctx, time, dest, gain = 1) {
  const osc = ctx.createOscillator();
  osc.type = "sine";
  osc.frequency.setValueAtTime(150, time);
  osc.frequency.exponentialRampToValueAtTime(48, time + 0.05);

  const ampEnv = ctx.createGain();
  ampEnv.gain.setValueAtTime(0, time);
  ampEnv.gain.linearRampToValueAtTime(gain, time + 0.001);
  ampEnv.gain.exponentialRampToValueAtTime(0.0001, time + 0.45);

  osc.connect(ampEnv).connect(dest);
  osc.start(time);
  osc.stop(time + 0.5);
}

Gotcha: exponentialRampToValueAtTime cannot reach 0 — it works in log space internally, where 0 is −∞. Aim for 0.0001 (or finish with an explicit setValueAtTime(0, end)). Forgetting this leaks audio between hits.

Snare — pitched body + bandpassed noise, mixed in parallel

A real snare is mostly noise. But noise alone reads as "ssshhh," not "snare." The trick is to layer a small pitched component that gives the hit a tonal centre:

[ triangle 200 Hz, 50 ms decay ] ─┐
                                   ├─→ master
[ noise → bandpass 1.5 kHz Q=0.6, 180 ms decay ] ─┘

In code:

// Body: 200 Hz triangle, fast decay
const body = ctx.createOscillator();
body.type = "triangle";
body.frequency.setValueAtTime(200, time);
const bodyEnv = envelopedGain(ctx, time, 0.55, 0.05);  // 50 ms
body.connect(bodyEnv).connect(dest);
body.start(time);
body.stop(time + 0.07);

// Noise: white noise → bandpass → longer decay
const noise = ctx.createBufferSource();
noise.buffer = whiteNoiseBuffer;       // pre-allocated Float32Array
const filter = ctx.createBiquadFilter();
filter.type = "bandpass";
filter.frequency.value = 1500;
filter.Q.value = 0.6;
const noiseEnv = envelopedGain(ctx, time, 0.6, 0.18);  // 180 ms
noise.connect(filter).connect(noiseEnv).connect(dest);
noise.start(time);

Key choices:

Bandpass at 1.5 kHz — the frequency range where snare "snap" lives. Move it lower and you get a tom; higher and it turns into a hi-hat.
Q = 0.6 is gentle filtering. Crank Q up to 5+ and it starts ringing like a struck cymbal — useful for percussion, wrong for a snare.
Triangle, not sine, for the body. Triangle adds odd-harmonic content; the snare reads firmer.
Cache the noise buffer. Allocate one Float32Array of white noise at start, reuse for every hit. Allocating per hit is several KB per beat, which the GC will eventually decide to handle inconveniently.

Hi-hat — square wave through a high-Q bandpass

The hi-hat sound is metal-on-metal: a dense cluster of high partials, decaying fast. Recipe:

osc.type = "square";          // square has rich odd harmonics → metallic
osc.frequency.setValueAtTime(7800, time);

filter.type = "bandpass";
filter.frequency.value = 7500;  // 7-8 kHz where cymbals live
filter.Q.value = 12;            // narrow band → "ringing" timbre

decay: closed = 40 ms / open = 320 ms

What's load-bearing:

Square wave, not sine. Square's odd harmonics produce the metallic sheen; sine alone is a pure "blip."
Q = 12 is high — this filter rings, which is exactly what a cymbal does.
Closed and open hi-hats differ only in decay length — same oscillator, same filter, different envelope. No second voice needed.

export function playHat(ctx, time, dest, open = false, gain = 1) {
  const osc = ctx.createOscillator();
  osc.type = "square";
  osc.frequency.setValueAtTime(7800, time);

  const filter = ctx.createBiquadFilter();
  filter.type = "bandpass";
  filter.frequency.value = 7500;
  filter.Q.value = 12;

  const decay = open ? 0.32 : 0.04;
  const env = envelopedGain(ctx, time, 0.45 * gain, decay);

  osc.connect(filter).connect(env).connect(dest);
  osc.start(time);
  osc.stop(time + decay + 0.02);
}

The lookahead scheduler — why `setInterval` doesn't work

Voicing is half the problem; the other half is firing the voices on time. The naive shape:

setInterval(() => playStep(currentStep++), 60000 / bpm / 4);

…drifts. The JS event loop has no commitment to firing on schedule. GC, layout, another extension's content script — any of them can delay the callback by 5-50 ms, and the error accumulates.

The fix from Chris Wilson's "A Tale of Two Clocks" is to schedule against the audio clock, not the JS clock:

function tick() {
  while (state.nextStepTime < audioCtx.currentTime + 0.1) {
    onStep({ step: state.step, time: state.nextStepTime });
    state.nextStepTime += secondsPerStep();
    state.step = (state.step + 1) % stepsPerBar;
  }
}
setInterval(tick, 25);   // 25 ms poll, 100 ms lookahead = 75 ms of slack

The mental model:

audioCtx.currentTime is the actual audio renderer's clock — sample-accurate.
osc.start(t) can take a future time; the audio thread renders the sample at t exactly, regardless of what JS is doing.
The JS timer's only job is to keep the queue topped up with the next 100 ms of events.
Even if JS stalls for 50 ms, the audio thread has already received the next several hits and renders them on time.

The result is drift-free timing, audible immediately if you A/B against the naive version on anything other than a quiet, idle browser tab.

Tests — fake the AudioContext

Synthesis correctness ("does the kick sound like a kick?") is verified by ear in real Chrome. The scheduler, however, is fully testable without an audio engine — inject a fake audioCtx (just a currentTime field) and a fake setInterval:

function makeFakes() {
  const audio = { currentTime: 0 };
  const intervals = [];
  const setIntervalFn = (fn) => {
    intervals.push({ fn, cleared: false });
    return intervals.length - 1;
  };
  const advance = (sec) => {
    audio.currentTime += sec;
    for (const slot of intervals) if (!slot.cleared) slot.fn();
  };
  return { audio, setIntervalFn, advance, /* ... */ };
}

test("at 120 BPM, 16 steps per bar = 0.125 s per step", () => {
  const fakes = makeFakes();
  const queued = [];
  const sched = createScheduler({
    audioCtx: fakes.audio,
    bpm: 120, stepsPerBar: 16, beatsPerBar: 4,
    onStep: ({ time }) => queued.push(time),
    setIntervalFn: fakes.setIntervalFn,
    clearIntervalFn: fakes.clearIntervalFn,
  });
  sched.start();
  fakes.advance(1.0);
  for (let i = 1; i < queued.length; i++) {
    assert.ok(Math.abs(queued[i] - queued[i - 1] - 0.125) < 1e-9);
  }
});

17 tests run under node --test in 70 ms. No browser, no jsdom.

Takeaways

Kick: sine 150 Hz → 48 Hz exponential sweep, 450 ms amp decay. The pitch sweep is the magic; the decay length is the pocket.
Snare: triangle 200 Hz body (50 ms) layered with bandpassed white noise at 1.5 kHz Q=0.6 (180 ms). Noise alone reads as "shhh"; the body gives the hit a tonal centre.
Hi-hat: square 7.8 kHz through bandpass 7.5 kHz Q=12. Closed (40 ms) and open (320 ms) differ only in envelope decay — same nodes, two voices.
exponentialRampToValueAtTime(0, …) doesn't work — log space has no zero. Use 0.0001 or finish with setValueAtTime(0, end).
Lookahead scheduler (Chris Wilson pattern): 25 ms JS poll, 100 ms ahead queue, drift-free under main-thread jitter.
Inject the audio clock for tests so the scheduler is verified deterministically without booting an AudioContext.

Full source on GitHub. MIT.

Third in the Web Audio series: metronome (timing) → pitch-detector (analysis) → drum-machine (synthesis).

A Per-URL TODO List Chrome Extension in 150 Lines — Single-Key chrome.storage Design, URL Normalization, and Three Sync Paths for the Toolbar Badge

SEN LLC — Wed, 29 Apr 2026 22:57:08 +0000

A flat TODO app forces you to paste in URLs every time you want to remember "three things to come back to in this PR" or "where I left off in this article." A Chrome extension that pins the list to whichever page you're on is the obvious shape — but the design choices around URL identity, storage layout, and badge sync are interesting enough to be worth writing up.

150 lines + 21 tests + zero host_permissions.

🧩 Demo: https://sen.ltd/portfolio/page-todo/
📦 GitHub: https://github.com/sen-ltd/page-todo

Storage shape: pick one key

Three plausible layouts for chrome.storage.local:

Option	Shape	Pros	Cons
A	`{ "https://...": [...todos] }` at the top level	Flat, write-per-URL	Top level pollution; `storage.get(null)` mixes data with anything else
B	`{ todos: { url: [...] } }` under a single top key	One read covers everything; `onChanged` listener watches one key	Whole-store rewrites on every edit
C	One key per URL (`url:https://...`)	Partial writes	Listener glue is messy; no clean "list all"

B wins for this size of data. A typical user holds a few KB to tens of KB. The "rewrite the whole thing every edit" cost is a few milliseconds; the simplicity of chrome.storage.onChanged triggering on a single named key is worth it.

const KEY = "todos";

// Storage shape
{
  todos: {
    "https://example.com/post/42": [
      { id, text, done, created },
      ...
    ],
    "https://github.com/sen-ltd/page-todo/pulls": [...]
  }
}

URL normalisation — eat the `?utm_source` and `#section`

What counts as "the same page"? If you store the raw URL as the key, these all become different pages:

https://example.com/post/42
https://example.com/post/42?utm_source=newsletter
https://example.com/post/42#comments

That's clearly wrong UX. Tracking parameters land you on the same article from a Twitter click; in-page anchors take you to a different section but the same article. The list should be one list.

The normalisation: origin + pathname, drop query and hash:

function urlKey(rawUrl) {
  if (!rawUrl) return null;
  try {
    const u = new URL(rawUrl);
    if (u.protocol === "chrome:" || u.protocol === "about:" || u.protocol === "file:") {
      return rawUrl;  // internal-page schemes pass through verbatim
    }
    let path = u.pathname;
    if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
    return u.origin + path;
  } catch {
    return null;
  }
}

Trailing slash is also normalised (so /post/ and /post share a list), but the root path / keeps its slash so the key is non-empty.

chrome://, about:, and file:// URLs aren't worth disassembling and are rare enough that "verbatim" is fine.

When query is the page

For older ?id=42-driven web apps, dropping the query loses the page identity. v1 doesn't try to be clever about this — supporting it would mean a per-host allow-list or a manual "save as separate page" flag, both of which are complexity buying very little. SPA-only sites are a strong majority now; the few pre-SPA cases that suffer can paste raw URLs into a flat note app instead.

Toolbar badge — three sync paths into one helper

The badge shows the open-TODO count for the active tab's URL. That value can change for three reasons:

The user switches tabs → chrome.tabs.onActivated
A tab's URL changes (link click, SPA navigation) → chrome.tabs.onUpdated
The storage changes (popup adds/removes/toggles a TODO) → chrome.storage.onChanged

All three call the same helper:

async function refreshBadgeForTab(tabId, url) {
  const count = await openCountFor(storage, url);
  const text = count > 0 ? String(count) : "";
  await chrome.action.setBadgeText({ tabId, text });
  if (count > 0) {
    await chrome.action.setBadgeBackgroundColor({ tabId, color: "#58a6ff" });
  }
}

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const tab = await chrome.tabs.get(tabId);
  if (tab?.url) await refreshBadgeForTab(tabId, tab.url);
});

chrome.tabs.onUpdated.addListener(async (tabId, changeInfo, tab) => {
  if (changeInfo.url || changeInfo.status === "complete") {
    if (tab?.url) await refreshBadgeForTab(tabId, tab.url);
  }
});

chrome.storage.onChanged.addListener(async (changes, area) => {
  if (area !== "local" || !changes.todos) return;
  const tabs = await chrome.tabs.query({ active: true });
  for (const t of tabs) {
    if (t.url && t.id !== undefined) await refreshBadgeForTab(t.id, t.url);
  }
});

The onUpdated filter — changeInfo.url || changeInfo.status === "complete" — is the small thing that makes this feel right:

SPA in-place navigation fires only changeInfo.url.
Full navigations end with changeInfo.status === "complete".

Listening to either alone leaves the other case stale.

The changes.todos check on onChanged keeps unrelated keys from triggering recompute, in case you ever add other state.

Pruning empty URL keys keeps the store tight

Removing a TODO leaves an empty array. Letting those accumulate makes the store bloat with URLs the user effectively cleared:

async function removeTodo(storage, rawUrl, id) {
  const all = await loadAll(storage);
  const list = all[key];
  list.splice(idx, 1);
  if (list.length === 0) delete all[key];   // prune
  else all[key] = list;
  await saveAll(storage, all);
}

clearDone does the same. After a year of normal use, the URL key set stays bounded by currently relevant pages, not every page ever visited.

ID generation — `crypto.getRandomValues` over `Date.now()`

Two adds in the same millisecond — easy to trigger from the popup if the user spams Enter — would collide on a Date.now()-based ID. Use the WebCrypto random instead:

function makeId() {
  const arr = new Uint8Array(5);
  crypto.getRandomValues(arr);
  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("").slice(0, 9);
}

A test (one of 21) explicitly proves "100 rapid adds in the same millisecond all get unique IDs."

Tests — no chrome polyfill, no jsdom

todos.js takes its storage argument (anything matching chrome.storage.local's get / set Promise shape). The test mock is ten lines:

function makeStorage(initial = {}) {
  const data = JSON.parse(JSON.stringify(initial));
  return {
    async get(keys) {
      const out = {};
      const arr = Array.isArray(keys) ? keys : [keys];
      for (const k of arr) if (k in data) out[k] = data[k];
      return out;
    },
    async set(items) { Object.assign(data, items); },
  };
}

node --test runs 21 cases in 0.08 seconds. No @types/chrome, no sinon-chrome, no jsdom.

The reasoning: dependency-injecting storage covers ~90% of the LOC under unit tests; the remaining 10% (popup DOM operations, service-worker listener wiring) is smoke-tested manually in a real Chrome with "Load unpacked." Polyfills for the bits we don't actually use buy nothing.

Takeaways

Single top-level key in chrome.storage.local keeps onChanged listeners and writes simple. The "rewrite the whole thing per edit" cost is invisible at this data size.
URL key = origin + pathname, drop query and hash. chrome:// / about: / file:// pass through verbatim. Trailing slash on non-root paths gets normalised.
Badge stays in sync via three triggers (tabs.onActivated, tabs.onUpdated filtered for URL change OR status complete, storage.onChanged) all calling one helper.
Empty URL keys are pruned from storage so long-term use doesn't bloat the store.
Random IDs, not Date.now() — covered by an explicit unique-id test.
No chrome polyfill in tests — dependency-inject the storage shim, mock it in 10 lines, run under node --test.

Full source on GitHub. MIT licensed.

This is the second entry in the browser-extension series, after copy-as-md (entry #214, HTML→Markdown clipboard).

A 150-Line `whentime tokyo london ny` CLI in Rust — and Why You Need IANA tzdata, Not 'UTC + N'

SEN LLC — Tue, 28 Apr 2026 22:41:20 +0000

When you're working across time zones and someone asks "what time is it in Tokyo?", the answer should be one terminal command away:
$ whentime tokyo london ny utc
Here's a 150-line zero-deps Rust CLI that does exactly that, plus the gotchas you discover when you stop pretending UTC offsets are integers.

🦀 Source on GitHub: https://github.com/sen-ltd/whentime
📦 Build & run: see below

Requirements

Four constraints I gave myself:

Friendly aliases — typing Asia/Tokyo every time loses to typing tokyo.
IANA names too — when an alias isn't in the table (Europe/Sofia), still let the user pass the IANA name directly.
Honest DST — London is +01:00 in July and +00:00 in January. No averaging to "+0.5".
A "From me" column — the actual delta from the user's wall clock, not yet another absolute UTC offset.

That last one means the program needs to know the user's own zone. Rust's chrono::Local reads TZ and the system config, so this is essentially free.

chrono and chrono-tz, in roles

chrono does time math; it doesn't ship IANA tzdata. chrono-tz adds the database — every zone exposed as a static Tz value:

use chrono::{Utc, TimeZone};
use chrono_tz::Asia;

let now = Utc::now();
let tokyo = now.with_timezone(&Asia::Tokyo);
println!("{}", tokyo.format("%H:%M %Z"));   // 07:36 JST

The magic is in with_timezone: it consults Asia::Tokyo's zoneinfo for the offset at this exact instant, not a static "UTC+9". Pass a January datetime to Europe::London and you get +00:00; pass a July datetime and you get +01:00. That makes the DST round-trip a one-line test:

#[test]
fn build_row_handles_dst_transition() {
    let summer: DateTime<Utc> = "2026-07-15T06:00:00Z".parse().unwrap();
    let winter: DateTime<Utc> = "2026-01-15T06:00:00Z".parse().unwrap();
    let s = build_row("London", "Europe/London", chrono_tz::Europe::London, summer, 0);
    let w = build_row("London", "Europe/London", chrono_tz::Europe::London, winter, 0);
    assert_eq!(s.utc_offset, "+01:00");
    assert_eq!(w.utc_offset, "+00:00");
}

Aliases — a flat table beats a fuzzy matcher

The IANA database has 600+ zones, including places nobody asks about. The set of cities engineers actually look up is more like 60. So the alias table is a curated static array:

static ALIASES: &[(&[&str], &str)] = &[
    (&["tokyo", "jst", "tyo", "japan"], "Asia/Tokyo"),
    (&["seoul", "kst", "korea"], "Asia/Seoul"),
    (&["nyc", "ny", "new-york", "manhattan", "est", "edt"], "America/New_York"),
    // ~60 rows
];

A fuzzy matcher would have to deal with tokio (typo for tokyo) vs Pacific/Tongatapu vs ambiguous prefixes. Failing closed is better. The user gets a clean error and a hint:

$ whentime mars venus
error: unknown city or IANA timezone: mars
error: unknown city or IANA timezone: venus
hint: try a city name (tokyo, ny, london), a 3-letter zone (jst, est, gmt),
      or an IANA name (Asia/Tokyo).

(Both typos collected into one report — see below.) The lookup is linear over ~60 entries, which is faster than a HashMap due to cache locality.

pub fn lookup(input: &str) -> Option<(&'static str, Tz)> {
    let normalized = input.trim().to_ascii_lowercase().replace('_', "-");
    for (aliases, tz_name) in ALIASES {
        for &alias in *aliases {
            if alias == normalized {
                return Some((tz_name, tz_name.parse::<Tz>().ok()?));
            }
        }
    }
    // Fallback: try parsing as a literal IANA name.
    input.trim().parse::<Tz>().ok().map(|tz| (/* ... */))
}

Normalising _ and - is a small ergonomic win: whentime new_york and whentime new-york both work.

Half-hour and quarter-hour zones — UTC offsets aren't `i32` hours

The world has zones that are not whole-hour offsets. If you've only worked Asia/America/Europe big cities you may not have hit them; here's the list to keep in mind:

Place	Offset
Mumbai (IST)	+05:30
Kathmandu	+05:45
Tehran	+03:30 (winter)
Adelaide	+09:30 / +10:30 (DST)
Newfoundland	−03:30 / −02:30 (DST)
Chatham Islands	+12:45 / +13:45 (DST)

Storing offsets as i32 hours is a footgun. chrono::FixedOffset uses seconds, so this is fine; but the formatter has to acknowledge fractional hours:

fn format_relative_offset(minutes: i32) -> String {
    if minutes == 0 { return "0h".to_string(); }
    let sign = if minutes < 0 { '-' } else { '+' };
    let abs = minutes.unsigned_abs();
    let h = abs / 60;
    let m = abs % 60;
    if m == 0 { format!("{}{}h", sign, h) }
    else      { format!("{}{}h{}m", sign, h, m) }
}

So Tokyo → Sapporo prints 0h, Tokyo → Delhi prints -3h30m, Adelaide → London prints -9h30m. Honest, not accidentally rounded.

Collecting all errors before exit

If a user types whentime tokio londn (both typos), exiting at the first failure means two round trips. Better: collect everything, report it together, exit once.

let mut errors = Vec::new();
for input in &cli.cities {
    match lookup(input) {
        Some(pair) => resolved.push(pair),
        None => errors.push(format!("unknown city or IANA timezone: {}", input)),
    }
}
if !errors.is_empty() {
    for e in &errors { eprintln!("error: {}", e); }
    eprintln!("hint: try a city name…");
    return ExitCode::from(2);
}

Exit code 2 because that's the shell convention for "usage error" (1 is generic failure).

Dynamic column widths in the table

Hard-coding column widths breaks when America/Argentina/Buenos_Aires arrives. Compute the max from the actual rows:

let w_iana = rows.iter().map(|r| r.iana.len()).max().unwrap_or(8).max(8);
let line = format!(
    "{:w_city$}  {:w_iana$}  {:>w_clock$}  {:w_date$}  {:>w_offset$}  {:>w_from$}",
    r.city, r.iana, r.local_clock, r.local_date, r.utc_offset, r.from_base,
);

The {:>} modifier right-aligns numeric columns (clock, offset, from-me); city/IANA stay left-aligned. Reads as a human-friendly table.

Colour is opt-in via --color auto|always|never. The auto path checks is_terminal() and respects NO_COLOR (the convention for CI logs that don't render ANSI).

Single static binary via Alpine + chrono-tz

chrono-tz compiles the IANA zoneinfo into the binary. There's no runtime dependency on /usr/share/zoneinfo. Build with the size-optimised profile and it's about 4.5 MB:

[profile.release]
strip = true
lto = true
codegen-units = 1
opt-level = "z"
panic = "abort"

opt-level = "z" is "minimise size", lto = true lets the linker discard unused sections, strip = true removes debug symbols. Default release was 8.7 MB; this gets it to 4.5.

The Dockerfile is the boilerplate rust:1.85-alpine builder + alpine:3.20 runtime:

FROM rust:1.85-alpine AS builder
RUN apk add --no-cache musl-dev
WORKDIR /build
COPY Cargo.toml Cargo.lock* ./
RUN mkdir -p src && echo 'fn main(){}' > src/main.rs && cargo build --release && rm -rf src
COPY src ./src
COPY tests ./tests
RUN touch src/main.rs && cargo build --release && cargo test --release

FROM alpine:3.20
COPY --from=builder /build/target/release/whentime /usr/local/bin/whentime
ENTRYPOINT ["/usr/local/bin/whentime"]

The two-step COPY Cargo.toml ... && cargo build trick caches dependency compilation in a separate Docker layer — very useful when iterating.

Takeaways

chrono-tz ships the IANA database compiled into your binary so a single static executable handles every zone correctly, including historical offsets.
DST and half-hour / quarter-hour offsets (India, Nepal, Newfoundland, Chatham) demand seconds-precision offsets, not hours.
A flat curated alias table beats a fuzzy matcher for this kind of CLI — typos fail closed with a hint instead of finding ambiguous matches.
Collect all errors before exiting so the user can fix every typo in one round trip.
Size-optimised release profile (opt-level = "z", LTO, strip) gets the binary under 5 MB, small enough to ship as a CI image.

Full source on GitHub — src/main.rs (CLI), src/cities.rs (alias table), src/format.rs (pure formatting), tests/cli.rs (assert_cmd black-box). MIT.

This is the first entry in a "same problem, different layer" pair — the web version was cron-tz-viewer (entry #001).

Three Address Checksums, Three Engineering Philosophies — Verifying Base58Check, Bech32m, and EIP-55 in 250 Lines of Browser JS

SEN LLC — Tue, 28 Apr 2026 00:11:24 +0000

When you paste a wallet address into something, the something either typo-checks it or it doesn't. Most engineers reach for validate_address(addr) from a library and move on. Spend an hour writing the verifiers from scratch and you discover something interesting: Bitcoin and Ethereum have completely different engineering philosophies about address checksums, and the differences are visible at the byte level.

Here's a 250-line browser-only verifier for Base58Check (BTC legacy), Bech32 / Bech32m (BTC SegWit), and EIP-55 (Ethereum), and what writing each one taught.

🔐 Demo: https://sen.ltd/portfolio/address-decoder/
📦 GitHub: https://github.com/sen-ltd/address-decoder

Three formats, three worldviews

Format	Example	Checksum	Year	Stance
Base58Check	`1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa`	4 bytes from SHA256²	2009	Defensive paranoia
EIP-55	`0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed`	1 bit per nibble via letter case	2016	Bolted-on, backwards-compatible
Bech32 / Bech32m	`bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4`	30-bit polynomial mod	2017 / 2021	QR + voice friendly

Working through them in order:

Bitcoin Base58Check — defensive paranoia

Satoshi's original design. An address is exactly:

[version (1 byte)] [payload (20 bytes)] [checksum (4 bytes)] = 25 bytes total

Encoded in Base58 (Bitcoin's alphabet). The checksum is the first 4 bytes of SHA256(SHA256(version || payload)) — SHA-256 squared. Verification is six lines:

const versioned = decoded.slice(0, decoded.length - 4);
const expected = (await dsha256(versioned)).slice(0, 4);
const valid = bytesEqual(checksum, expected);

async function dsha256(b) {
  return new Uint8Array(
    await crypto.subtle.digest("SHA-256",
      await crypto.subtle.digest("SHA-256", b))
  );
}

The hashing-twice was a 2009-era hedge against length-extension attacks on plain SHA-256 — by today's threat model, single-pass would be fine, but Bitcoin can't change without a hard fork.

4 bytes = 32 bits of checksum means the false-positive rate for a typo is 1 in 4 billion. Effectively zero. The price you pay is that addresses look like radio static (1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa).

The Base58 trap

The Base58 alphabet excludes 0, O, I, and l to avoid visual confusion — 58 = 64 minus 6 ambiguous characters. The implementation gotcha: leading 1 characters encode leading 0x00 bytes, separately from the actual base-58 conversion.

let leadingZeros = 0;
while (leadingZeros < s.length && s[leadingZeros] === "1") leadingZeros++;
// ... base-58 → base-256 conversion of the rest ...
return new Uint8Array([...zeros(leadingZeros), ...converted]);

Forget that and you decode addresses one byte short for any address whose first byte is 0x00 (which includes mainnet P2PKH — most real addresses). I tripped on it on the first test.

Ethereum EIP-55 — bolted-on case checksum

When Ethereum launched in 2015, addresses had no checksum. They were literal hex:

0xde709f2102306220921060314715629080e2fb77

Hex is case insensitive at the bytes level (0xa and 0xA decode to the same nibble), so letter case was a free 1-bit-per-character of unused signal. EIP-55 (2016) used it for a checksum:

Lowercase the address; treat the hex string as ASCII bytes; hash with keccak-256.
Walk each character of the lowercase address. If it's a letter and the corresponding hash nibble is >= 8, uppercase that letter. Digits stay digits.

function checksumHex(lowerHex, hashBytes) {
  let out = "";
  for (let i = 0; i < lowerHex.length; i++) {
    const c = lowerHex[i];
    if (c >= "0" && c <= "9") { out += c; continue; }
    const byte = hashBytes[i >>> 1];
    const nibble = (i % 2 === 0) ? (byte >>> 4) : (byte & 0x0f);
    out += nibble >= 8 ? c.toUpperCase() : c;
  }
  return out;
}

The elegance is in what happens to existing tools:

Pre-EIP-55 wallets send all-lowercase. Receivers treat that as "no checksum present" and accept it.
EIP-55-aware wallets send mixed-case; receivers verify the mixed-case matches the recomputed pattern.
The spec is explicit: addresses uniformly cased one way are accepted without checksum verification.

This is a textbook "don't break the world" upgrade. The cost is that lowercase Ethereum addresses still ship today with no integrity check at all.

The keccak-256 trap — it's not NIST SHA3

Ethereum's "keccak-256" is not NIST SHA3-256. The two share the Keccak-f[1600] permutation underneath but the padding byte differs:

Keccak-256 (Ethereum): 0x01
SHA3-256 (NIST): 0x06

That single-byte difference produces completely different digests. Anyone who reaches for crypto.subtle.digest("SHA3-256", ...) to verify EIP-55 fails immediately — the Web Crypto API has SHA-3 but not Keccak, so a 150-line hand-rolled implementation is required.

The implementation core:

function keccakF(state) {
  for (let round = 0; round < 24; round++) {
    // θ — column parity, XOR with neighbouring columns
    // ρ + π — lane rotation + permutation across the 5×5 state
    // χ — non-linear within each row: a[x] ^= ~a[x+1] & a[x+2]
    // ι — XOR a per-round constant into lane (0,0)
  }
}

JavaScript's bitwise ops cap at 32 bits, so each 64-bit lane is stored as a (lo, hi) pair. BigInt would dominate the hot loop, so it's manual.

The eight official EIP-55 vectors made debugging painless: each one is an address that should round-trip to itself when re-checksummed. My first version had one wrong round constant — the high half of RC[2] was zero when it should have been 0x80000000 — and all eight vectors failed with different garbage. Fix one byte, all eight pass. Cryptographic test vectors at their best.

const EIP55_VECTORS = [
  "0x52908400098527886E0F7030069857D2E4169EE7",
  "0x8617E340B3D01FA5F11F306F4090FD50E238070D",
  "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
  // ... 5 more
];
for (const addr of EIP55_VECTORS) {
  test(`EIP-55: ${addr.slice(0, 12)}…`, () => {
    const r = decodeEthereumAddress(addr);
    assert.equal(r.eip55_checksum, addr); // recompute matches input
  });
}

Bitcoin SegWit's Bech32 / Bech32m — QR-friendly with a twist

Bech32 (BIP-0173, 2017) was designed for SegWit native addresses (bc1...) with three explicit goals:

All-lowercase so QR codes stay small (case-sensitive Base58 hurts QR error correction)
A voice-friendly alphabet of 32 characters (drops b, i, o, and 1)
Strong adjacent-error detection via a polynomial checksum

Structure:

[hrp (e.g. "bc")] "1" [data (5-bit groups)] [checksum (6 chars = 30 bits)]

The 1 is a separator that's been excluded from the alphabet, so it can never appear in the HRP or the data. The checksum is a BCH code modulo a generator over GF(2³⁰):

function bech32Polymod(values) {
  const GEN = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3];
  let chk = 1;
  for (const v of values) {
    const top = chk >>> 25;
    chk = ((chk & 0x1ffffff) << 5) ^ v;
    for (let i = 0; i < 5; i++) {
      if ((top >>> i) & 1) chk ^= GEN[i];
    }
  }
  return chk >>> 0;
}

This catches 100% of single-character errors and the vast majority of two-character errors. The choice of generator polynomial isn't arbitrary; it was derived to maximise that error-detection guarantee against the most common typing mistakes (sipa's notes on the math are worth a read).

The Bech32m post-mortem (BIP-0350)

In 2020, a class of two-character "insertion + deletion" errors was found to slip past Bech32. The fix: a new variant Bech32m with a different final XOR constant (0x2bc830a3 instead of Bech32's 1). Crucially, the BIP-0350 deployment plan split by witness version:

Witness version	Encoding
0 (P2WPKH, P2WSH)	bech32 (legacy, kept for compatibility)
1+ (Taproot)	bech32m (new)

Both formats coexist in the wild. The implementation must check both polymod constants, then verify the variant matches the witness version:

const variant =
  poly === BECH32_CONST  ? "bech32"  :
  poly === BECH32M_CONST ? "bech32m" : null;
const variantOk =
  (witnessVersion === 0 && variant === "bech32") ||
  (witnessVersion >= 1 && variant === "bech32m");

Accepting bech32m for v0 (or vice versa) is technically a wallet bug — it means an address that looks valid but came from a buggy generator might be accepted, leading to lost funds. Worth the discipline to keep the check strict.

A dispatcher false-positive worth knowing

The tool guesses the format from the input. The first version's bech32 decoder false-fired on Bitcoin Genesis (1A1zP1eP5...) because:

bech32 looks for the last 1 in the input as a separator
Bitcoin legacy P2PKH addresses contain plenty of 1 characters
The mixed-case rejection check fired before the HRP was validated, returning {format: "bech32", valid: false, error: "mixed case is forbidden"}

Fix: reject anything whose computed HRP isn't pure lowercase letters.

const hrp = lc.slice(0, idx);
if (!/^[a-z]+$/.test(hrp)) return null;

The spec technically allows digits in the HRP, but every real-world HRP (bc, tb, bcrt, ltc, tltc) is pure lowercase. For an address verifier, Postel's "be liberal in what you accept" is the wrong default — you want to be strict to avoid sending money to a structurally-valid-but-wrong-format address.

Takeaways

Base58Check (Bitcoin legacy) is paranoid by design: 32 bits of double-SHA-256 catches every typo. The ugliness is the cost.
EIP-55 (Ethereum) is pragmatic: a 1-bit-per-letter checksum sneaked into the existing case-insensitive hex format, with a deliberate "all-one-case = no checksum" carve-out that kept the Ethereum ecosystem from breaking when it shipped in 2016.
Bech32 / Bech32m (Bitcoin SegWit) is engineering-textbook: requirements (QR, voice, error detection) drove a custom alphabet, a mathematically-derived polynomial, and — when a flaw was found in 2020 — a compatible split into a new variant tied to witness version.

Three formats, three lessons in cryptographic design under different constraints. The fact that it all fits in 250 lines of browser JavaScript is a reminder that the math is small; the policy is what the spec is really about.

Full source on GitHub — decoder.js (250 lines), keccak256.js (150 lines), 30 tests covering all 8 EIP-55 vectors plus BIP-0173/0350 references plus BTC mainnet/testnet. MIT licensed.

Live demo — six example addresses one click away.

A 230-Line Chrome MV3 Extension That Copies the Page Selection as Markdown — Without ``

SEN LLC — Mon, 27 Apr 2026 00:06:06 +0000

Engineers paste into Markdown destinations all day — GitHub Issues, dev.to, Notion, Obsidian — but the browser's "Copy" command writes HTML to the clipboard, and that HTML lands as escaped tags or stripped formatting. Here's a Chrome MV3 extension that does the obvious thing: convert the selection to Markdown before it hits the clipboard.

230 lines of vanilla JS, 35 jsdom-backed tests, no host_permissions.

🧩 Demo: https://sen.ltd/portfolio/copy-as-md/
📦 GitHub: https://github.com/sen-ltd/copy-as-md

Why the browser's clipboard isn't enough

Chrome's "Copy" puts both text/plain and text/html on the clipboard. Whichever the destination accepts, Chrome serves. The problem is that almost every text destination engineers care about ignores both:

Destination	What it actually wants
GitHub issues / PRs	Markdown
dev.to / Zenn / Qiita	Markdown
Notion	Notion's own format (Markdown is plain text on paste)
Obsidian / Bear / Joplin	Markdown
Slack	a Markdown subset

Pasting HTML into a GitHub issue gets you escaped tags. Pasting into Notion gets you plain text with the formatting stripped. The fix is obvious: write Markdown to the clipboard before the paste happens.

Architecture — MV3 service worker + executeScript

Three triggers all funnel into the same code:

[ user action ]
   │
   ├─ Right-click → "Copy selection as Markdown"  (contextMenus)
   ├─ Cmd/Ctrl + Shift + M                         (commands)
   └─ Toolbar icon → popup → "Copy" button         (runtime.sendMessage)
              │
              ▼
   [ service worker (background.js) ]
              │
              ▼
   chrome.scripting.executeScript twice:
     1) files: ["html-to-md.js"]   ← inject the converter
     2) func: runner                ← read selection, convert, write clipboard

The combined helper:

async function runOnTab(tabId) {
  await chrome.scripting.executeScript({
    target: { tabId },
    files: ["html-to-md.js"],   // defines globalThis.htmlToMarkdown
  });
  const [{ result }] = await chrome.scripting.executeScript({
    target: { tabId },
    func: runner,
  });
  return result;
}

function runner() {
  const sel = window.getSelection();
  if (!sel || sel.rangeCount === 0 || sel.isCollapsed) {
    const md = globalThis.htmlToMarkdown(document.body);
    navigator.clipboard.writeText(md).catch(() => {});
    return { source: "page", markdown: md };
  }
  const fragment = sel.getRangeAt(0).cloneContents();
  const md = globalThis.htmlToMarkdown(fragment);
  navigator.clipboard.writeText(md).catch(() => {});
  return { source: "selection", markdown: md };
}

Important: no `host_permissions`

The default reflex for "an extension that runs on every site" is "host_permissions": ["<all_urls>"]. That's a strong permission. Chrome Web Store reviewers flag it. The user sees "Read and change all your data on the websites you visit" at install time and bounces.

Replace it with activeTab + scripting:

No host_permissions declaration at all
The install warning is much milder
Semantically: the extension can only touch a tab the user just acted on — clicking the toolbar icon, hitting the keyboard shortcut, or selecting the context menu item. That's exactly what activeTab was designed for

{
  "manifest_version": 3,
  "permissions": ["activeTab", "scripting", "contextMenus"],
  "background": { "service_worker": "background.js" },
  "action": { "default_popup": "popup.html" },
  "commands": {
    "copy-selection-as-markdown": {
      "suggested_key": { "default": "Ctrl+Shift+M", "mac": "Command+Shift+M" }
    }
  }
}

No host_permissions, no web_accessible_resources. This is the modern minimum-permission shape for this category of extension.

Popup → service worker, not popup → tab

The popup is its own browsing context. Calling chrome.tabs.query({active: true, currentWindow: true}) from the popup can return the popup window itself depending on browser timing. Route through the service worker:

// popup.js
chrome.runtime.sendMessage({ type: "copy-as-md/run" }, (resp) => { /* … */ });

// background.js
chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
  if (msg?.type !== "copy-as-md/run") return;
  (async () => {
    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
    const md = await runOnTab(tab.id);
    sendResponse({ ok: true, markdown: md });
  })();
  return true;  // keep the message channel open for async sendResponse
});

The return true is the magic value that keeps sendResponse alive across the await. Forget it and the popup's callback never fires — every MV3 dev hits this exactly once.

The HTML→Markdown converter — tag dispatch in 230 lines

Pure logic, takes any DOM-like tree (Element / DocumentFragment / Document.body), returns a string:

function htmlToMarkdown(node) {
  const out = [];
  walk(node, { listDepth: 0 }, out);
  return collapseBlankLines(out.join("")).trim() + "\n";
}

const HANDLERS = {
  H1: (n, c, o) => heading(n, 1, c, o),
  // … H2-H6
  P: (n, c, o) => o.push("\n\n", innerMarkdown(n, c).trim(), "\n\n"),
  A: (n, c, o) => {
    const text = innerMarkdown(n, c).trim();
    const href = n.getAttribute("href");
    if (!href) o.push(text);
    else if (text === href) o.push("<", href, ">");
    else o.push("[", text, "](", href, ")");
  },
  STRONG: (n, c, o) => emphasize(n, "**", c, o),
  EM:     (n, c, o) => emphasize(n, "*",  c, o),
  CODE: ..., PRE: ..., BLOCKQUOTE: ...,
  UL:    (n, c, o) => list(n, "ul", c, o),
  OL:    (n, c, o) => list(n, "ol", c, o),
  TABLE: ..., IMG: ..., DEL: ...,
  SCRIPT: () => {}, STYLE: () => {}, NOSCRIPT: () => {},
};

walk visits each node. If HANDLERS[tagName] exists, dispatch; otherwise recurse into children. Edge cases live with their tag, which keeps the diffs small when you find a new one.

Trap 1: pretty-printed inter-block whitespace

Source HTML formatted across multiple lines:

<h1>Title</h1>
  <p>…</p>

Naïve walk emits whitespace text nodes between blocks → # Title\n\n \n\n… — those leading spaces on a blank line make some Markdown parsers think it's an indented code block.

Fix at text-node time: drop pure-whitespace text that contains a newline:

if (/^\s+$/.test(text) && /\n/.test(text)) return;

The newline check matters. It preserves intentional inline spaces like <span>x</span> <span>y</span> (which don't contain a newline) while killing pretty-print formatting (which does).

Trap 2: nested-list double-indent

<ul><li>a<ul><li>b</li></ul></li></ul>

CommonMark expects:

- a
  - b

Two spaces of indent for the nested item. If both "outer LI continuation lines get indented" and "inner UL emits its own depth-based indent" are turned on, you get - b — four spaces, wrong.

Resolution here: nested lists self-indent via " ".repeat(depth), the outer LI does not add continuation indent. Multi-paragraph LIs become slightly less pretty but still parse correctly under CommonMark; nested lists, which appear far more often in real web content, render exactly right.

Trap 3: GFM tables need a header that the source HTML may not have

GFM requires a header row:

| h1 | h2 |
| --- | --- |
| a | b |

But many <table> elements in the wild ship with no <thead>, or with <th> cells in the first row of <tbody>, or all cells as <td>.

Promotion logic:

let headerRow = null;
const rows = [];
for (const tr of allTrs) {
  const cells = ...;
  const isHeader = Array.from(tr.children).some((c) => c.tagName === "TH");
  if (isHeader && !headerRow) headerRow = cells;
  else rows.push(cells);
}
if (!headerRow && rows.length > 0) headerRow = rows.shift();   // promote first row

The trade-off: a header-less data table loses its first row to the header pretender. Acceptable, because real-world tables almost always have a heading row that just isn't marked as one.

The same code runs in Node tests

Because the converter is pure, you don't need a browser to test it — supply a DOM:

import { test } from "node:test";
import { JSDOM } from "jsdom";
import "../html-to-md.js";  // side effect: sets globalThis.htmlToMarkdown

const { document } = new JSDOM().window;
const md = (html) => {
  document.body.innerHTML = html;
  return globalThis.htmlToMarkdown(document.body);
};

test("nested ul indents inner list", () => {
  assert.equal(md("<ul><li>a<ul><li>b</li></ul></li></ul>"), "- a\n  - b\n");
});

35 cases run under node --test in 0.3 seconds. The MV3 lifecycle bits (service worker boot, popup messaging, context menu registration) still need a manual smoke test in actual Chrome — but the 90% of LOC that's the converter is fully covered without touching a browser.

Takeaways

Skip <all_urls>. activeTab + scripting + contextMenus is enough for this whole class of extension; the install warning shrinks and Chrome Web Store reviewers stop flagging it.
The "two-call executeScript" pattern (inject the library, then a runner) is reusable and avoids any module-loading dance in the content script world.
Popup → service worker → tabs.query is the safe path to "the tab the user was just looking at." onMessage async handlers must return true or sendResponse no-ops.
A tag-dispatch HTML→Markdown converter fits in 230 lines. The traps to know are pretty-print whitespace, nested-list indent doubling, and header promotion for tables without <thead>.
Pure logic + jsdom + node --test covers the converter end-to-end. Browser is for smoke testing only.

Full source on GitHub — html-to-md.js is the converter, background.js is the SW, tests/ is 35 cases. MIT licensed.

Hosted playground lets you try the converter without installing the extension.

BIP39 in 180 Lines of Vanilla JS — Mnemonic Generation, Validation, Seed Derivation, and the Japanese Wordlist Trap

SEN LLC — Sat, 25 Apr 2026 23:10:11 +0000

The 12-to-24 word "seed phrase" inside every hardware wallet and software wallet is BIP39. The spec is short — one file. Implement it from scratch and you discover that the only place where independent implementations actually disagree is the Japanese wordlist edge case, which catches even seasoned crypto libraries.

Here's a zero-dependency, SubtleCrypto-only, 180-line BIP39 implementation, verified against both the Trezor and bip32JP test vectors.

🔐 Demo: https://sen.ltd/portfolio/bip39-tool/
📦 GitHub: https://github.com/sen-ltd/bip39-tool

⚠️ Don't paste a real wallet's mnemonic into any web tool, including this one. Read the source first or — better — clone it and run it offline.

What BIP39 actually defines (and what it doesn't)

BIP39 specifies two things and stops:

A two-way encoding between an entropy buffer and a checksum-protected list of words.
A function that turns the word list into a 64-byte seed.

Everything past that — seed → master key, master key → addresses, HD derivation paths — is BIP32 / BIP44. BIP39 ends at the seed.

That's actually significant: BIP39 is currency-agnostic. Bitcoin, Ethereum, Solana, Cardano, you name it — the same BIP39 phrase produces the same seed for all of them.

The encoding, in four steps

1. Take ENT bits of cryptographically secure entropy (ENT ∈ {128, 160, 192, 224, 256})
2. Compute CS = ENT / 32   (= 4, 5, 6, 7, 8 bits)
3. Take the first CS bits of SHA-256(entropy) and append them to entropy
4. Slice the (ENT + CS)-bit string into 11-bit groups; each is an index into a 2048-word wordlist

11-bit groups because 2¹¹ = 2048. Each word carries about 11 bits.

export async function entropyToMnemonic(entropy, wordlist) {
  const bits = entropy.length * 8;           // 128/160/192/224/256
  const checksumBits = bits / 32;            // 4/5/6/7/8
  const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", entropy));
  const checksumByte = hash[0] >> (8 - checksumBits);

  // Pack entropy || checksum_bits into one buffer
  const totalBits = bits + checksumBits;
  const buf = new Uint8Array(Math.ceil(totalBits / 8));
  buf.set(entropy, 0);
  buf[entropy.length] = checksumByte << (8 - checksumBits);

  // Slice into 11-bit indices
  const wordCount = totalBits / 11;
  const words = [];
  for (let w = 0; w < wordCount; w++) {
    let idx = 0;
    for (let b = 0; b < 11; b++) {
      const bitPos = w * 11 + b;
      const bytePos = bitPos >> 3;
      const bitInByte = 7 - (bitPos & 7);
      idx = (idx << 1) | ((buf[bytePos] >> bitInByte) & 1);
    }
    words.push(wordlist[idx]);
  }
  return words;
}

SHA-256 is crypto.subtle.digest("SHA-256", entropy). Entropy is crypto.getRandomValues(new Uint8Array(bits / 8)). No third-party crypto libraries needed, including for the random source.

Validation is just the same code in reverse

Map each word back to its index, concatenate the bits, peel off the checksum bits at the end, and recompute:

const givenChecksum = buf[entropy.length] >> (8 - checksumBits);
const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", entropy));
const expectedChecksum = hash[0] >> (8 - checksumBits);
if (givenChecksum !== expectedChecksum) throw new Error("invalid checksum");

For a 12-word phrase, only the bottom 4 bits of the last word are checksum. Any "random 12 English words" you type has a 1-in-16 chance of being valid. That's enough for typo detection but carries no security weight — security lives in the entropy, not the checksum.

Seed derivation — the fixed PBKDF2 parameters that you can never change

Mnemonic to 64-byte seed is one PBKDF2 call:

seed = PBKDF2-HMAC-SHA512(
  password = NFKD(mnemonic_phrase),
  salt     = NFKD("mnemonic" + passphrase),
  iter     = 2048,
  keyLen   = 64 bytes
)

In SubtleCrypto:

export async function mnemonicToSeed(words, passphrase = "", separator = " ") {
  const enc = new TextEncoder();
  const phrase = words.join(separator).normalize("NFKD");
  const salt   = ("mnemonic" + (passphrase || "")).normalize("NFKD");

  const key = await crypto.subtle.importKey(
    "raw", enc.encode(phrase), { name: "PBKDF2" }, false, ["deriveBits"]
  );
  const bits = await crypto.subtle.deriveBits(
    { name: "PBKDF2", salt: enc.encode(salt), iterations: 2048, hash: "SHA-512" },
    key, 512    // 64 bytes
  );
  return new Uint8Array(bits);
}

Three things are baked into the spec and you can't move them:

iterations = 2048 — set in 2014 and weak by modern PBKDF2 standards (where you'd want hundreds of thousands). Cannot be changed, because it would break compatibility with every existing wallet. The spec leans on the entropy itself for security
NFKD normalization — Unicode-normalizes the phrase so that combined characters like é (U+00E9) and e + ◌́ (U+0065 + U+0301) produce the same seed
salt = "mnemonic" + passphrase — even with no passphrase, the salt is the constant string "mnemonic". So the entire space of "no-passphrase BIP39 mnemonics" is fixed-salted, leaving a finite rainbow-table surface

The third point is why BIP39 implementations sometimes refer to the passphrase as "the 25th word" — without one, your security is just the 128-256 bits of entropy.

The Japanese wordlist trap — `U+3000` versus `U+0020`

Here's where independent implementations get caught. BIP39 ships a 2048-word Japanese list in its appendix, and the spec specifies a separator the implementation has to remember:

English: ASCII space U+0020
Japanese: ideographic space U+3000

NFKD does not collapse U+3000 into U+0020 — they remain distinct codepoints after normalization. Different join character means different bytes into PBKDF2 means different seed.

The bip32JP test vector that catches this:

entropy:    00000000000000000000000000000000
mnemonic:   あいこくしん あいこくしん あいこくしん あいこくしん
            あいこくしん あいこくしん あいこくしん あいこくしん
            あいこくしん あいこくしん あいこくしん あおぞら
            (joined with U+3000)
passphrase: ㍍ガバヴァぱばぐゞちぢ十人十色
seed:       a262d6fb6122ecf45be09c50492b31f92e9beb7d9a845987a02cefda57a15f9c
            467a17872029a9e92299b5cbdf306e3a0ee620245cbd508959b6cb7ca637bd55

This single vector trips an implementation that does any of:

Hardcodes the join character to ASCII space
Skips NFKD on the mnemonic
Skips NFKD on the passphrase
Normalizes the mnemonic but assumes "the passphrase is ASCII anyway"

That last one is the most insidious. The passphrase contains ㍍ (U+3349, SQUARE METORU) which NFKD decomposes into four characters メートル, and ガ (U+30AC) which decomposes into カ + ゛. Pass the user's literal bytes into PBKDF2 and the seed will not match a wallet that did normalize.

Lock the implementation down with both vector sets

For English coverage, Trezor's vectors.json ships 24 [entropy, mnemonic, seed, xprv] tuples — 128/192/256-bit, all with passphrase "TREZOR". For Japanese, bip32JP/bip32JP.github.io ships vectors with the ㍍-containing passphrase, so you can land all four pitfalls above in one assertion.

This implementation runs both — 34 tests total:

test("japanese vector: seed uses U+3000 separator", async () => {
  const words = await entropyToMnemonic(
    hexToBytes("00000000000000000000000000000000"), JAPANESE,
  );
  const seed = await mnemonicToSeed(
    words, "㍍ガバヴァぱばぐゞちぢ十人十色", "　"
  );
  assert.equal(bytesToHex(seed),
    "a262d6fb6122ecf45be09c50492b31f92e9beb7d9a845987a02cefda57a15f9c" +
    "467a17872029a9e92299b5cbdf306e3a0ee620245cbd508959b6cb7ca637bd55");
});

mnemonicToSeed takes a separator argument so the same code path handles both languages.

Browser-only deployment notes

The end product is a static HTML + one ES module. A few things to know:

Wordlists ship as static files — fetched from ./wordlists/english.txt at runtime. No npm dependency, no CDN, no JSON.
Web Crypto requires https:// (or localhost). On a http:// origin that isn't loopback, crypto.subtle is undefined and everything breaks silently.
Same code runs in Node 18+ — globalThis.crypto points at node:crypto.webcrypto, so crypto.subtle.digest and deriveBits work identically. Tests run under node:test without booting a browser.

$ npm test
✔ english wordlist has 2048 words, sorted, lowercase
✔ japanese wordlist has 2048 words
✔ vector 00000000…: entropy → mnemonic
✔ vector 00000000…: mnemonic → entropy
✔ vector 00000000…: mnemonic → seed (passphrase=TREZOR)
…
ℹ tests 34
ℹ pass 34

Takeaways

BIP39 is small: entropy ↔ mnemonic with a SHA-256 checksum, plus a PBKDF2 seed derivation. ~180 lines.
No external crypto needed: SubtleCrypto's digest("SHA-256") and deriveBits("PBKDF2", ..., "SHA-512") cover everything.
The Japanese list separator is U+3000, NFKD doesn't collapse it, and the ㍍-containing passphrase from bip32JP catches every form of normalization-skipping in a single test.
iterations = 2048 is weak by modern standards but locked by the spec — the security model leans on entropy and passphrase ("the 25th word"), not on key stretching.

Full source on GitHub — bip39.js is the implementation, tests/bip39.test.js runs all 34 vectors, wordlists/ holds the official English and Japanese lists. MIT licensed.

Live demo — and again, please don't paste a real wallet's mnemonic into it (or any other web tool).

Why Your Web Audio Tuner Sucks at Low Notes (and What to Use Instead of FFT)

SEN LLC — Fri, 24 Apr 2026 22:45:19 +0000

The first thing anyone reaches for when building a pitch detector in the browser is AnalyserNode.getFloatFrequencyData() — the FFT magnitude spectrum. It works, and then it fails the instant you plug in a guitar and play the low E. Here's why, and what to do about it.

Sub-cent-accurate tuning from ~80 lines of autocorrelation. No dependencies. Plain JS.

🎙 Demo: https://sen.ltd/portfolio/pitch-detector/
📦 GitHub: https://github.com/sen-ltd/pitch-detector

The symptom — FFT-based tuners can't read low notes

The canonical Web Audio pitch detector looks like this:

const ctx = new AudioContext();           // default sampleRate = 48000
const analyser = ctx.createAnalyser();
analyser.fftSize = 2048;                  // the default
const spectrum = new Float32Array(analyser.frequencyBinCount);

requestAnimationFrame(function loop() {
  analyser.getFloatFrequencyData(spectrum);
  const maxBin = argmax(spectrum);
  const freq = maxBin * ctx.sampleRate / analyser.fftSize;
  // turn freq into a note name…
  requestAnimationFrame(loop);
});

Play an A4 (440 Hz) and it lights up around 440. Perfect. Then play the low E on a guitar (E2 = 82.41 Hz) and the readout jumps between "82 Hz" and "105 Hz" like a broken cursor. The reason is bin width:

bin width = sampleRate / fftSize = 48000 / 2048 = 23.4375 Hz

And the distance between semitones scales with frequency, so low notes are closer together:

Note	Frequency	Distance to next semitone
E2	82.41 Hz	4.90 Hz (to F2)
A2	110.00 Hz	6.54 Hz
A4	440.00 Hz	26.16 Hz
A5	880.00 Hz	52.33 Hz

E2 and F2 are less than one-fifth of a bin apart. The FFT literally cannot tell them apart. That "I tuned my guitar and it sounded wrong" feeling? That was your tuner.

The workarounds and their limits

Crank up fftSize: 32768 gets bin width down to 1.46 Hz, but fftSize >= 2 * N, so you need 32768 samples (~0.68 s at 48 kHz) of latency and memory per frame. Rough for a live display.
Zero padding: increases resolution in appearance only. You're not measuring anything more; you're interpolating.
Parabolic interpolation: fit a quadratic to the three bins around the peak and estimate the apex. Classic trick, gets you closer, but doesn't help if two peaks are blurred into one.

And there's a deeper problem.

Pitch is not frequency

An A4 isn't pure; it contains partials at 880, 1320, 1760 Hz and up. In an FFT magnitude spectrum, depending on the instrument and the moment of the recording, the second harmonic can be louder than the fundamental. Plucked guitar, right after the pick attack, is a famous case. Naïve argmax returns 880 Hz — A5, an octave off.

You can patch around this (HPS = Harmonic Product Spectrum, or peak-picking with harmonic constraints) but none of these patches are about pitch, they're about cleaning up the mess that FFT handed you. And they don't fix the bin-width problem.

The physical definition of pitch is the period at which the waveform repeats. If a signal repeats every 480 samples at 48 kHz, that's a 100 Hz pitch. Harmonics don't change the period — they change the shape of each cycle. So measure the period directly.

Autocorrelation — measuring the period directly

The autocorrelation function (ACF) is the buffer's inner product with a copy of itself shifted by τ samples:

r[τ] = Σ_{i=0..N−τ−1} buffer[i] · buffer[i + τ]

At τ = 0, every term is buffer[i]², so r[0] is the max (signal energy).
When τ hits one period, the shifted copy lines up with itself again and r[τ] peaks.
The location of the first prominent peak is the period.

Frequency = sampleRate / τ. That's the whole idea.

export function detectPitch(buffer, sampleRate) {
  const N = buffer.length;
  const minLag = Math.floor(sampleRate / 1500); // upper freq bound 1500 Hz
  const maxLag = Math.floor(sampleRate / 60);   // lower freq bound 60 Hz

  // RMS gate — don't run on silence
  let sumSq = 0;
  for (let i = 0; i < N; i++) sumSq += buffer[i] * buffer[i];
  if (Math.sqrt(sumSq / N) < 0.01) return null;

  const r0 = acf(buffer, 0, N);

  // Skip past the initial descent from r[0]
  let lag = minLag;
  while (lag < maxLag && acf(buffer, lag, N) > acf(buffer, lag + 1, N)) lag++;

  // Find the highest local maximum in the remaining range
  let bestLag = -1, bestVal = -Infinity;
  while (lag < maxLag - 1) {
    const a = acf(buffer, lag - 1, N);
    const b = acf(buffer, lag, N);
    const c = acf(buffer, lag + 1, N);
    if (b > a && b >= c && b > bestVal) { bestVal = b; bestLag = lag; }
    lag++;
  }
  if (bestLag < 0 || bestVal / r0 < 0.5) return null;  // reject weak periodicity

  // Parabolic interpolation for sub-sample precision
  const a = acf(buffer, bestLag - 1, N);
  const b = bestVal;
  const c = acf(buffer, bestLag + 1, N);
  const shift = (a - c) / (2 * (a - 2*b + c));
  return sampleRate / (bestLag + shift);
}

function acf(buf, lag, N) {
  let s = 0;
  for (let i = 0; i < N - lag; i++) s += buf[i] * buf[i + lag];
  return s;
}

Three things matter:

1. Choose maxLag from your lower frequency bound. A lower limit of 60 Hz means maxLag = 800 samples at 48 kHz. You want at least two periods inside the buffer, so maxLag ≤ N / 2 is the practical cap. Pushing too low starves the estimator.

2. Skip the initial descent. r[τ] is a plateau around τ = 0, then dips, then rises back at the period. Walk forward until the values stop decreasing before you start peak-hunting — otherwise you'll pick τ = 1 and report 48 kHz.

3. Reject weak peaks by ratio to r[0]. Noise doesn't have a clean period, so it doesn't produce a sharp peak. bestVal / r0 < 0.5 says "we don't have a confident period" and returns null. This is what lets the tuner stay quiet on background hiss instead of guessing wildly.

Parabolic interpolation for sub-sample precision

Integer lags are discrete, so raw ACF gives you integer-sample period resolution. For A4 (440 Hz, period ≈ 109 samples) one sample off is 48000/109 - 48000/110 = 4 Hz, about 15 cents. Not good enough.

Fit a parabola through (bestLag-1, bestLag, bestLag+1) and solve for the apex. Standard trick, ~4 lines of code, and the tests show it nails pure sines to under 1 cent.

test("detects 440 Hz sine within 1 cent", () => {
  const buf = sineBuffer(440, 0.04);   // 40 ms ≈ 1920 samples
  const f = detectPitch(buf, 48000);
  const cents = 1200 * Math.log2(f / 440);
  assert.ok(Math.abs(cents) < 1);
});

Wiring it to Web Audio

You want the time-domain buffer, not the FFT. AnalyserNode.getFloatTimeDomainData() hands back a Float32Array of raw samples, exactly what detectPitch consumes.

const stream = await navigator.mediaDevices.getUserMedia({
  audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: false },
});
const ctx = new AudioContext();
const src = ctx.createMediaStreamSource(stream);
const analyser = ctx.createAnalyser();
analyser.fftSize = 2048;
src.connect(analyser);

const buf = new Float32Array(analyser.fftSize);
requestAnimationFrame(function loop() {
  analyser.getFloatTimeDomainData(buf);
  const f = detectPitch(buf, ctx.sampleRate);
  if (f) render(f);
  requestAnimationFrame(loop);
});

Gotcha: echoCancellation, noiseSuppression, and autoGainControl default to true. All three assume "human voice making words" and actively fight pure tones — they'll gate out your test sine wave entirely. Set them to false for any musical application.

Smooth in log-frequency space, not Hz

The readout will wobble if you display raw per-frame estimates, so you'll reach for exponential smoothing. Important: do it in log₂(Hz), not linear Hz. Human pitch perception is logarithmic — a 2 Hz wobble at A2 is a very different problem from a 2 Hz wobble at A5.

const alpha = 0.35;
const sLog = Math.log2(smoothedFreq);
const fLog = Math.log2(newFreq);
smoothedFreq = Math.pow(2, sLog * (1 - alpha) + fLog * alpha);

Result: identical responsiveness and stability across the instrument's range.

Cost vs. the alternative

ACF is O(N · L) where L is the candidate lag range. For N = 2048 and L ≈ 768 that's ~1.5M multiply-adds per frame. On a laptop Chrome this runs in well under 1 ms — negligible inside a 16.7 ms animation frame.

FFT is O(N log N), about 60× cheaper in theory. But when your ACF frame is already sub-millisecond, the win isn't compelling enough to give up the low-note accuracy.

For larger buffers, polyphonic input, or heavier denoising, look at YIN (a refined ACF variant) or CREPE (a small neural net). But for a monophonic tuner, plain autocorrelation is enough, and it fits in 80 lines.

The takeaway

FFT tuners fail at low frequencies because the bin width (sampleRate / fftSize ≈ 23 Hz) is larger than the semitone spacing at E2 (4.9 Hz).
Pitch is the period at which the waveform repeats. Measure it directly with autocorrelation.
Three things make the algorithm robust: skip the initial descent, threshold the peak-to-energy ratio for noise rejection, and parabolic-interpolate the peak for sub-sample precision.
Web Audio integration caveats: use getFloatTimeDomainData(), disable the voice-assistant effects on the getUserMedia constraints, smooth in log space.

Full source on GitHub — detector.js is the algorithm, tests/detector.test.js is 14 tests covering sines, sawtooths, silence, noise, and all the tuner presets. MIT licensed.

Live demo — allow mic access and sing, whistle, or play an instrument at it.

GitHub's Stargazers API Caps at 40,000. Here's How Star-History Tools Fake the Rest

SEN LLC — Fri, 24 Apr 2026 01:06:45 +0000

If you've ever wondered how star-history.com plots the growth curve of a repository with 200,000 stars, the answer is: it doesn't — not exactly. GitHub's stargazers API quietly caps at 40,000 reachable stargazers. Past that, you're sampling and stitching. I built a browser-only version to see what that actually looks like.

📦 GitHub: https://github.com/sen-ltd/github-star-history
🔗 Demo: https://sen.ltd/portfolio/github-star-history/

No server, no proxy. Your browser talks to api.github.com directly; if you paste in a Personal Access Token it lives only in this-device localStorage. About 500 lines of vanilla JS + hand-rolled SVG.

The undocumented `Accept` header

You probably know GET /repos/{owner}/{repo}/stargazers returns a list of users. What you may not know is that with one custom media type, the response shape changes:

GET /repos/{owner}/{repo}/stargazers
Accept: application/vnd.github.star+json

Instead of [{login, id, ...}] you now get [{user, starred_at}]. That starred_at timestamp is the only thing a star-history chart actually needs.

It's documented (buried in GitHub's REST API reference) but I'd never stumbled on it until I went looking. Every other stargazer-history tool out there depends on it.

Pagination: 100 per page, and a `Link` header does the counting for you

GET /repos/facebook/react/stargazers?per_page=100&page=1
Accept: application/vnd.github.star+json

The response includes a Link header like:

<https://api.github.com/...&page=2>; rel="next",
<https://api.github.com/...&page=2320>; rel="last"

Parsing rel="last" tells you the total page count without another request:

export function parseLastPage(linkHeader) {
  if (!linkHeader) return 1;
  const m = linkHeader.match(/<[^>]*[?&]page=(\d+)[^>]*>;\s*rel="last"/);
  return m ? Number(m[1]) : 1;
}

For facebook/react at ~232k stars, that's ~2320 pages. Which is where things get interesting.

The 40,000-stargazer wall

Try ?page=500. GitHub returns an empty array. Try ?page=1000. Still empty. Try ?page=401. Also empty.

GitHub caps the stargazers endpoint at page 400. This isn't in the public docs but it is reproducible and widely known in the star-history ecosystem. Past 40,000 stargazers, the chronological stream is simply not addressable via this endpoint.

What that means for a repo like facebook/react:

stargazers_count from GET /repos/{owner}/{repo} tells you the current total: ~232,000.
Stargazers pages 1–400 give you the first ~40,000 users in chronological order.
Everything after that is invisible to this API.

To plot a growth curve, you have three options:

Ignore it. Show the curve up to 40k and stop. (Wrong-looking: the line plateaus in ~2015 for React.)
Use GitHub Archive / BigQuery. Accurate, but requires a paid Google Cloud project and a batch query. Not doable from a browser.
Sample + anchor. Pick N evenly-spaced pages from [1, 400], take their starred_at timestamps, then pin the right edge of the chart at (now, stargazers_count). The curve is interpolated through your samples.

star-history.com does option 3. This app does option 3. It's a pragmatic lie, but a small one: the shape of a cumulative distribution over hundreds of thousands of data points is extremely well-behaved, so 24 samples give you a curve that's visually indistinguishable from the truth.

The sampling strategy, in code

const HARD_PAGE_LIMIT = 400;

// Read lastPage from page 1's Link header.
const first = await fetchStargazerPage(owner, repo, 1, token);
const reachableLastPage = Math.min(first.lastPage, HARD_PAGE_LIMIT);

let pages;
if (reachableLastPage <= maxSamplePages) {
  // Small repo: fetch every page, full fidelity.
  pages = range(1, reachableLastPage);
} else {
  // Big repo: evenly spaced samples across reachable range.
  pages = evenSample(1, reachableLastPage, maxSamplePages);
}

Where evenSample(1, 400, 24) returns something like [1, 18, 35, 52, ..., 383, 400]. That's 24 API calls regardless of whether the repo has 40k or 400k stars — which matters, because unauthenticated GitHub allows just 60 requests per hour.

Now the cumulative curve. Each page P starting at index (P-1)*100+1, so for page 200 with 100 items, the first item represents stargazer #19,901:

pg.items.forEach((iso, i) => {
  const starIndex = (pg.page - 1) * 100 + i + 1;
  points.push({ t: new Date(iso).getTime(), n: starIndex });
});

Finally, anchor:

const last = points[points.length - 1];
if (meta.stargazersCount > last.n) {
  points.push({ t: Date.now(), n: meta.stargazersCount });
}

That Date.now() anchor is load-bearing. Without it, a sampled-only curve for facebook/react ends in ~2016 at ~40k stars. With it, the curve climbs correctly to today's ~232k. The interpolation between the last sampled page (at maybe 2016) and today is a straight line — technically a lie, but one you're welcome to notice from the "(sampled)" badge in the legend.

Rate limits: the other wall

Unauthenticated: 60 requests per hour. At 24 requests per repo, that's 2 repos before you're locked out.

Authenticated with a PAT: 5000 requests per hour. Classic tokens work; fine-grained tokens work too (no special scopes needed — public read is default). The token is stored in localStorage and only ever sent to api.github.com:

function authHeaders(token) {
  const h = { Accept: "application/vnd.github.star+json" };
  if (token) h.Authorization = `Bearer ${token}`;
  return h;
}

When the cap is hit, GitHub returns HTTP 403 with two useful headers:

x-ratelimit-remaining: 0
x-ratelimit-reset: 1744812000 (Unix seconds)

Surface both to the user:

if (res.status === 403 && Number(res.headers.get("x-ratelimit-remaining")) === 0) {
  const resetSec = Number(res.headers.get("x-ratelimit-reset"));
  throw new RateLimitError(new Date(resetSec * 1000));
}

So the user sees "Rate limit hit. Resets at 2026-04-24 14:40. Add a PAT above to raise the limit" instead of a vague failure.

Drawing the chart without a charting library

The chart is hand-rolled SVG. Why? Because once you're plotting 4 series × up to 100 points each, D3's 90 KB gzipped is bigger than the entire rest of the app. And the problem is genuinely small:

Compute data extents (minX, maxX, maxY).
Round maxY up to a "nice" number (1, 2, 2.5, 5, 10 × 10^k).
Linear scale from data → screen coordinates.
Emit one <path d="M.. L.. L.."> per series, plus <line>s for grid and <text>s for labels.

The "nice number" axis is the only non-obvious piece:

export function niceMaxY(max) {
  if (max <= 1) return 1;
  const exp = Math.floor(Math.log10(max));
  const pow = 10 ** exp;
  const norm = max / pow;
  let nice;
  if (norm <= 1) nice = 1;
  else if (norm <= 2) nice = 2;
  else if (norm <= 2.5) nice = 2.5;
  else if (norm <= 5) nice = 5;
  else nice = 10;
  return nice * pow;
}

For max = 232000: norm = 2.32 → nice = 2.5 → ticks at 0, 50k, 100k, 150k, 200k, 250k. Every tick is a clean human-readable number. Without the 2.5 tier, 232k jumps to 500k and the chart wastes half its vertical space.

localStorage as a 24-hour cache

Stargazers don't change fast. A 24-hour TTL on cached curves means a second visit is instant and uses zero API calls:

const PREFIX = "gsh:v1:";

export function saveCached(owner, repo, data, store = localStorage) {
  store.setItem(
    `${PREFIX}${owner.toLowerCase()}/${repo.toLowerCase()}`,
    JSON.stringify({ savedAt: Date.now(), data }),
  );
}

export function loadCached(owner, repo, ttlMs = 24 * 3600 * 1000, store = localStorage) {
  const raw = store.getItem(`${PREFIX}${owner.toLowerCase()}/${repo.toLowerCase()}`);
  if (!raw) return null;
  const { savedAt, data } = JSON.parse(raw);
  if (Date.now() - savedAt > ttlMs) return null;
  return data;
}

Prefixing the key with a schema version (gsh:v1:) means I can bump to v2: later and old entries become dead weight that the user or a "Clear cache" button can sweep.

What this app deliberately doesn't do

No PNG export from server. canvas.toBlob with an XMLSerializer-stringified SVG drawn into an Image — everything in the browser.
No analytics, no beacon. If you open DevTools' Network tab, the only outbound traffic is to api.github.com.
No sophisticated cache invalidation. 24-hour TTL is fine for "I want a rough curve for my blog post." If you need live precision, add a PAT and click "Clear cache."

The entire JS payload is ~9 KB minified, served as ES modules with no build step. Run it locally with:

python3 -m http.server 8080

That's the whole development setup.

Takeaway

The application/vnd.github.star+json accept header + the 400-page pagination wall + stargazers_count as a right-anchor are the three things you need to build a star-history chart. Plus a Link header parser and a PAT-friendly rate-limit error. The sampling is a lie but a defensible one — the shape of 232k timestamps sampled at 24 evenly-spaced pages is indistinguishable, to the eye, from the truth.

Source: https://github.com/sen-ltd/github-star-history
Live: https://sen.ltd/portfolio/github-star-history/

Built by SEN LLC (sen.ltd). We publish one small open-source tool like this per day as a public résumé; the full list is here.

A 3.7 KB Othello Engine: Bitboards in Rust, Raw WASM, No wasm-bindgen

SEN LLC — Thu, 23 Apr 2026 01:18:00 +0000

Othello legal-move generation is seven lines of bitboard bitwise ops. I knew this existed; I'd never actually written it. So I built a Reversi engine in Rust, compiled it to raw WebAssembly without wasm-bindgen, and ended up with a 3.7 KB .wasm that plays a credible game against you in the browser.

📦 GitHub: https://github.com/sen-ltd/reversi-wasm
🔗 Demo: https://sen.ltd/portfolio/reversi-wasm/

Stack summary:

Rust, no_std, zero heap allocations
Raw WebAssembly.instantiate — no wasm-bindgen, no generated JS glue
Vanilla JS + HTML + CSS for the board UI
Alpha-beta negamax AI, configurable depth 1–5
Final wasm: 3,717 bytes

Bitboards: two u64s carry the entire game

The board is two bitboards, one per color:

static mut BLACK: u64 = 0;
static mut WHITE: u64 = 0;

Bit row * 8 + col — so bit 0 is a1 (top-left) and bit 63 is h8 (bottom-right). Starting position:

const INIT_WHITE: u64 = (1u64 << 27) | (1u64 << 36); // d4, e5
const INIT_BLACK: u64 = (1u64 << 28) | (1u64 << 35); // e4, d5

State is 17 bytes total: two u64s + one byte of turn flag. Legal moves, application of a move, evaluation, all become bitwise operations on these two numbers.

Direction shifts

Each of Othello's eight directions becomes a one-line function:

const NOT_A_FILE: u64 = 0xFEFEFEFEFEFEFEFE; // all bits except column 0
const NOT_H_FILE: u64 = 0x7F7F7F7F7F7F7F7F; // all bits except column 7

fn n(x: u64)  -> u64 { x >> 8 }                       // north
fn s(x: u64)  -> u64 { x << 8 }                       // south
fn e(x: u64)  -> u64 { (x & NOT_H_FILE) << 1 }        // east
fn w(x: u64)  -> u64 { (x & NOT_A_FILE) >> 1 }        // west
fn ne(x: u64) -> u64 { (x & NOT_H_FILE) >> 7 }        // NE (up-right)
fn nw(x: u64) -> u64 { (x & NOT_A_FILE) >> 9 }        // NW (up-left)
fn se(x: u64) -> u64 { (x & NOT_H_FILE) << 9 }        // SE (down-right)
fn sw(x: u64) -> u64 { (x & NOT_A_FILE) << 7 }        // SW (down-left)

The file masks applied before the shift prevent column wraparound — a bit in column 7 shifted right by 1 would otherwise appear in column 0 of the next row. Row overflow takes care of itself because shifting pushes bits off the ends into oblivion.

Legal moves in seven lines

The definition of an Othello legal move: "a square, empty, reached from one of my disks through a run of one-or-more opponent disks in any direction."

In bitboard form, one direction:

fn legal_moves_dir(me: u64, opp: u64, empty: u64, shift: Shift) -> u64 {
    let mut run = shift(me) & opp;          // opp disks adjacent to me
    run |= shift(run) & opp;                 // extend further
    run |= shift(run) & opp;
    run |= shift(run) & opp;                 // max run is 6 (middle 6 of 8)
    run |= shift(run) & opp;
    run |= shift(run) & opp;
    shift(run) & empty                        // the empty square past the run
}

Seven lines, zero branches. The OR'd run variable accumulates all opponent-disk positions reachable from me along this direction; the final shift(run) & empty picks out squares that extend one past the run and are empty — i.e., legal moves.

All eight directions get OR'd together:

fn legal_moves(me: u64, opp: u64) -> u64 {
    let empty = !(me | opp);
    let mut moves = 0u64;
    for shift in DIRECTIONS {
        moves |= legal_moves_dir(me, opp, empty, shift);
    }
    moves
}

This returns a u64 where every set bit is a legal move square. The JS side takes that u64 and uses it to draw the gold hint dots.

Applying a move: the same pattern, different terminator

Computing which opponent disks flip when I play at pos:

fn flips_dir(pos: u64, me: u64, opp: u64, shift: Shift) -> u64 {
    let mut run = shift(pos) & opp;
    run |= shift(run) & opp;
    run |= shift(run) & opp;
    run |= shift(run) & opp;
    run |= shift(run) & opp;
    run |= shift(run) & opp;
    // If the run terminates at one of our disks, flip everything in between.
    if shift(run) & me != 0 { run } else { 0 }
}

Structurally identical to legal-move detection. The only change: check if the run lands on me (sandwich complete, flip) versus empty (open terminus, no flip).

OR across directions → flips_total → apply:

let new_me  = me | pos | flips;
let new_opp = opp & !flips;

That's the entire move-application logic.

AI: negamax + alpha-beta

Othello is a determinate, two-player, zero-sum, perfect-information game — textbook minimax territory. Negamax with alpha-beta pruning:

fn negamax(me: u64, opp: u64, depth: u32, mut alpha: i32, beta: i32) -> (i32, u64) {
    if depth == 0 { return (evaluate(me, opp), 0); }

    let moves = legal_moves(me, opp);
    if moves == 0 { /* handle pass / terminal */ }

    let mut best_score = i32::MIN + 1;
    let mut best_move = 0u64;
    let mut bits = moves;
    while bits != 0 {
        let mv = bits & bits.wrapping_neg();     // extract lowest set bit
        bits ^= mv;
        let flips = flips_total(mv, me, opp);
        let new_me  = me | mv | flips;
        let new_opp = opp & !flips;
        let (s, _) = negamax(new_opp, new_me, depth - 1, -beta, -alpha);
        let score = -s;
        if score > best_score { best_score = score; best_move = mv; }
        if score > alpha       { alpha = score; }
        if alpha >= beta       { break; }
    }
    (best_score, best_move)
}

bits & bits.wrapping_neg() is the Brian Kernighan/LSB isolation trick — extracts the lowest set bit, which we then XOR off. The entire move enumeration is allocation-free.

Evaluation is the classic position weight table + mobility:

const WEIGHTS: [i32; 64] = [
    100, -25,  10,   5,   5,  10, -25, 100,
    -25, -50,  -1,  -1,  -1,  -1, -50, -25,
     10,  -1,   3,   2,   2,   3,  -1,  10,
      5,  -1,   2,   1,   1,   2,  -1,   5,
      5,  -1,   2,   1,   1,   2,  -1,   5,
     10,  -1,   3,   2,   2,   3,  -1,  10,
    -25, -50,  -1,  -1,  -1,  -1, -50, -25,
    100, -25,  10,   5,   5,  10, -25, 100,
];

Corners are +100, X-squares (diagonal adjacents to corners) are -50 because occupying them too early lets the opponent take the corner. Add a 5-points-per-legal-move mobility term. Result: the AI plays corner-hunting, X-square-avoiding, mobility-aware Othello at depth 4.

Why skip wasm-bindgen

wasm-bindgen is lovely when you need to pass strings and structs across the Rust/JS boundary. My engine's API is:

#[no_mangle] pub extern "C" fn reset();
#[no_mangle] pub extern "C" fn legal_moves_bits() -> u64;
#[no_mangle] pub extern "C" fn apply_move(pos: u32) -> u32;
#[no_mangle] pub extern "C" fn ai_choose_move(depth: u32) -> u32;
#[no_mangle] pub extern "C" fn black_discs() -> u64;
#[no_mangle] pub extern "C" fn white_discs() -> u64;

Pure POD, no references, no strings. The JS side just calls the exports:

const res = await fetch('./assets/reversi.wasm');
const { instance } = await WebAssembly.instantiate(await res.arrayBuffer(), {});
const engine = instance.exports;

engine.reset();
const legal = engine.legal_moves_bits();  // returns a BigInt for u64
engine.apply_move(pos);
const ai = engine.ai_choose_move(4);

No generated .js glue file, no import maps, no npm dependencies. The .wasm is all there is.

Release profile + no_std

Cargo.toml release profile is what squeezes 3.7 KB out of the binary:

[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = "abort"
strip = true

Plus #![no_std] and #![no_main] drop the entire std runtime. You provide your own panic handler:

#[cfg(not(test))]
#[panic_handler]
fn panic(_: &PanicInfo) -> ! { loop {} }

The #[cfg(not(test))] exists because cargo test needs std (test's own harness is built on std), and std already defines panic_handler. The conditional lets the same source file build both ways:

#![cfg_attr(not(test), no_std)]
#![cfg_attr(not(test), no_main)]

I want cargo test to work so I can run unit tests on the pure game logic without needing a browser.

Tests as the bug-catcher

Seven unit tests covering:

Initial position has 4 disks, 2-2
Black's opening has exactly four legal moves (d3, c4, f5, e6)
Playing d3 flips d4 (3 black, 1 white, white's turn)
An illegal move returns 0 and doesn't change state
AI at depth 2 returns a legal move from the starting position
AI takes a corner when only that move is available
Pass fails when legal moves exist

I wrote the direction-shift mask (NOT_A_FILE vs NOT_H_FILE) wrong on the first try and the "opening has four legal moves" test caught it in 200 ms. Bitboard bugs are merciless — an off-by-one file mask wraps bits across rows and the whole game gets surreal — but they also tend to fail catastrophically the moment you test them, which is great for fast iteration.

Takeaways

Othello is a showcase for bitboards. Seven lines of shift-and-AND give you legal moves in all eight directions, and the same structure does disc flipping.
Raw WASM is viable for POD-only APIs. WebAssembly.instantiate is three lines; you don't need a toolchain pipeline for a small, pure engine.
no_std + strip = true + panic = abort cuts Rust binaries by an order of magnitude when you don't need the runtime.
#[cfg(not(test))] on your panic handler lets you dual-build: wasm-no_std for the browser, std-with-tests for cargo.
BigInt is your friend on the JS side: wasm u64 exports come back as BigInt, so use (legal & (1n << BigInt(i))) !== 0n for bit testing.

Repository: https://github.com/sen-ltd/reversi-wasm

I Built a Japanese Poetry Quiz and the Web Speech API Showed Me Its Teeth

SEN LLC — Wed, 22 Apr 2026 23:38:25 +0000

A thousand-year-old poetry anthology, a thirty-year-old JavaScript API, and modern TypeScript — what could go wrong?

Answer: the historical Japanese spelling, the browser-specific voice availability, and the queue-that-never-clears behaviour of SpeechSynthesis. I built a tiny quiz around the 百人一首 (the One Hundred Poets, One Poem Each — a canonical anthology compiled in the 13th century), and writing it surfaced three things I wouldn't have guessed from the MDN page alone.

📦 GitHub: https://github.com/sen-ltd/hyakunin-isshu
🔗 Demo: https://sen.ltd/portfolio/hyakunin-isshu/

What it does:

Shows the kami (first 5-7-5 phrase) of a waka poem. You pick the correct shimo (closing 7-7) from four options.
Alternative mode: "who wrote this?" — the choices become four poet names.
Optional read-aloud (kami only, or kami + shimo after answering) via the browser's Web Speech API, with a ja-JP voice.
30 of the 100 poems curated as an MVP — everything else is a pure-data extension of src/data/poems.ts.
Vue 3 + Vite + TypeScript, no runtime deps beyond Vue.

The rest of this post is about the three walls I hit.

Wall 1: "as written" and "what the TTS wants" are different strings

Classical Japanese poetry uses historical kana that most modern TTS engines handle inconsistently. Take Shikishi Naishinnō's famous poem:

玉の緒よ絶えなばたえねながらへば

The spelling ながらへば ends in -he-ba in modern romanization, but the pronunciation is -e-ba. What happens when you feed the literal string to SpeechSynthesis?

Chrome + Google Japanese voice: reads it literally — na-ga-ra-he-ba
macOS Safari + Kyoko: silently normalizes to na-ga-ra-e-ba

Both correct according to their own logic, neither right for the user.

The fix is to store two strings per poem: one for display, one for speech.

{
  kami: '玉の緒よ絶えなばたえねながらへば',          // display (historical kana preserved)
  kamiYomi: 'たまのおよ たえなばたえね ながらえば',  // speech (modern kana, spaced)
}

kami goes into the DOM where a minchō-font serif shows off the kanji + kana mix. kamiYomi goes into SpeechSynthesisUtterance.text where what matters is that every engine gets the same phonemes. Splitting on spaces in kamiYomi also gives the synthesizer slightly more natural phrasing than one long run-on string.

This isn't just a poetry problem. Any JP historical content — Edo-period literature, pre-war newspapers, Heian-era place names — will hit the same fork.

Wall 2: voice enumeration is async and some browsers never finish

You'd think window.speechSynthesis.getVoices() returns voices. On Chrome + macOS it does, on first call, instantly. On most other combinations it returns an empty array and you have to wait for the voiceschanged event.

export function loadJaVoices(): Promise<SpeechSynthesisVoice[]> {
  if (!('speechSynthesis' in window)) return Promise.resolve([]);
  return new Promise((resolve) => {
    const pick = () =>
      window.speechSynthesis.getVoices().filter((v) => v.lang.startsWith('ja'));

    const first = pick();
    if (first.length > 0) {
      resolve(first);
      return;
    }
    const onChange = () => {
      window.speechSynthesis.removeEventListener('voiceschanged', onChange);
      resolve(pick());
    };
    window.speechSynthesis.addEventListener('voiceschanged', onChange);

    // Some browsers (Firefox in certain OS combos) never fire the event.
    // Time out and resolve empty so the UI doesn't wait forever.
    setTimeout(() => {
      window.speechSynthesis.removeEventListener('voiceschanged', onChange);
      resolve(pick());
    }, 1500);
  });
}

The 1.5-second safety timeout is load-bearing. Without it, a user on Firefox + Linux will see a permanently disabled read-aloud button because voiceschanged simply never fires. I spent an embarrassing amount of time debugging this one in a VM before I realized the API just goes silent.

Feature detection goes a step further — I disable the button up front if the API isn't present, and change the label to (音声非対応) ("voice unsupported") so the user understands it's not their fault:

<button class="speak-btn" :disabled="!speechSupported" @click="speakKami">
  {{ speechSupported ? '♪ Listen to kami' : '(Voice unsupported)' }}
</button>

Wall 3: `speak()` queues. `cancel()` is mandatory.

Press the read-aloud button twice in Chrome and the second press doesn't replay — it enqueues a second utterance behind the first. The user will wait through the entire first read, then hear the second one. This is technically correct but unambiguously wrong UX for a quiz.

The fix is boilerplate: cancel before speaking.

export async function speak(text: string, options: SpeakOptions = {}) {
  if (!isSupported()) throw new Error('Web Speech API is not supported.');
  window.speechSynthesis.cancel();   // ← clear anything queued

  const utter = new SpeechSynthesisUtterance(text);
  utter.lang = options.lang ?? 'ja-JP';
  utter.rate = options.rate ?? 0.85;

  return new Promise<void>((resolve, reject) => {
    utter.onend = () => resolve();
    utter.onerror = (e) => reject(new Error(e.error ?? 'speech error'));
    window.speechSynthesis.speak(utter);
  });
}

And a second cancel() when advancing to the next question — otherwise a slow reader who clicks next mid-utterance keeps hearing the previous poem while the new one is on screen.

function nextPoem() {
  selected.value = null;
  cancelAll();            // ← prevent stale read-alouds
  current.value = pickQuestion(POEMS, seen.value);
}

rate: 0.85 is a light slowdown for waka — default speed runs the syllables together in a way that makes the 5-7-5 cadence invisible.

Testable quiz logic: pull it out of Vue

Vue single-file components are nice for markup but painful to unit-test without @vue/test-utils. The quiz logic (pick a target poem, generate distractor choices, shuffle) is pure TypeScript, so I kept it in src/quiz.ts separately:

export function pickQuestion(
  poems: Poem[],
  seen: Set<number>,
  rng: () => number = Math.random,
): Question | null {
  const available = poems.filter((p) => !seen.has(p.number));
  if (available.length === 0) return null;

  const target = pickOne(available, rng);
  const distractors = sampleWithout(poems, target.number, 3, rng);
  const choices = shuffle([target.shimo, ...distractors.map((d) => d.shimo)], rng);
  return { poem: target, choices, correctIndex: choices.indexOf(target.shimo) };
}

Passing rng in means tests can inject a seeded PRNG for determinism:

function seeded(seed: number): () => number {
  let s = seed;
  return () => {
    s = (s * 1664525 + 1013904223) & 0xffffffff;
    return (s >>> 0) / 0x100000000;
  };
}

it('spreads the correct answer across every index', () => {
  const counts = [0, 0, 0, 0];
  for (let seed = 0; seed < 400; seed++) {
    const q = pickQuestion(POEMS, new Set(), seeded(seed))!;
    counts[q.correctIndex]!++;
  }
  for (const c of counts) expect(c).toBeGreaterThan(50);
});

This exact test caught a Fisher-Yates bug early on where the shuffle was biased toward the last slot. If you're shipping any "four random choices, one correct" UX, keep this test in your pocket.

Data trivia: classical Japanese has formulaic closings

While curating the 30 poems I noticed a subtle data problem: multiple poems end with near-identical phrases. Teiji Tennō (#1) ends with わが衣手は露にぬれつつ ("my sleeves are wet with dew"). Kōkō Tennō (#15) ends with わが衣手に雪は降りつつ ("snow falls on my sleeves"). Both start with わが衣手 (waga-koromode, "my sleeves") and end with -tsutsu.

If both appear in the same four-choice set, the quiz gets genuinely hard — arguably too hard, because guessing depends on snow-vs-dew detail more than poet skill. The next iteration should penalize distractors that are edit-distance-close to the correct shimo when building choices, not just ban exact duplicates. For now the dataset test enforces uniqueness-by-string, which is necessary but not sufficient.

Takeaways

For historical Japanese content, carry two strings per entry: the one humans see, and the one TTS hears.
speechSynthesis.getVoices() is async-with-escape-hatches. Always wrap voiceschanged in a promise with a timeout.
speechSynthesis.cancel() before every speak(), and again before any UI navigation, or you'll queue utterances for free.
Keep quiz picking logic out of your component tree. A pure function + a seeded RNG is cheap, fast, and correctness-testable.
"Near-duplicate" data in your content is a distinct problem from "exact-duplicate" data. Edit distance, not string equality.

Repository: https://github.com/sen-ltd/hyakunin-isshu

I Finally Understand the SVG d Attribute — Because I Built an Editor for It

SEN LLC — Tue, 21 Apr 2026 23:27:01 +0000

<path d="M 100 40 C 60 0 0 40 100 140 C 200 40 140 0 100 40 Z" />

Can you read that at a glance? I couldn't. I knew M was "move" but the rest was a blur. The C takes three coordinate pairs — why three? Z takes none — what does it close? Short commands like H and S always turned into "I'll look that up later" and I spent years not looking it up. I finally built a tiny visual editor for it, and the d string stopped being a mystery after about two days. Here's what I learned.

📦 GitHub: https://github.com/sen-ltd/svg-path-editor
🔗 Demo: https://sen.ltd/portfolio/svg-path-editor/

What it does:

Paste any d attribute → the canvas renders it and overlays draggable anchors (green) and cubic/quadratic control points (orange).
Drag a node → the path updates and the d textarea re-emits a clean, rounded string.
Output is normalized to absolute M / L / C / Q / Z only. Round-tripping through parser + serializer is stable.
Svelte 5 + TypeScript + Vite. Zero runtime deps beyond Svelte.

The rest of this article is less "here's how you use it" and more "things the SVG path grammar does that nobody warned me about."

The d attribute is a sequence of pen commands

A d string is a list of instructions for an imaginary pen.

Command	Meaning	Coord pairs
`M x y`	Lift the pen, move to (x, y). No drawing.	1
`L x y`	Line from current point to (x, y)	1
`H x`	Horizontal line to x (y stays)	0.5
`V y`	Vertical line to y (x stays)	0.5
`C x1 y1 x2 y2 x y`	Cubic bezier with controls (x1,y1) and (x2,y2), endpoint (x,y)	3
`S x2 y2 x y`	Cubic bezier with x1 auto-reflected from the previous C	2
`Q x1 y1 x y`	Quadratic bezier with one control, endpoint (x,y)	2
`T x y`	Quadratic bezier with x1 auto-reflected from the previous Q	1
`A rx ry rot large sweep x y`	Elliptical arc	3.5
`Z`	Straight line back to the current subpath's start. Closes the subpath.	0

Uppercase = absolute coordinates. Lowercase = relative to the current point. M and m behave differently enough that you should almost treat them as separate commands.

Here's the first observation that made the editor possible: H, V, S, T, and all relative commands are just shorthand for M/L/C/Q. If you normalize everything to absolute M/L/C/Q/Z up front, the number of node shapes you have to draw drops from ten to five, and the dragging code stops caring which letter the user originally typed.

Gotcha: `M x y x y` is "M then L"

This one bit me immediately.

M 10 10 20 20 30 30

The natural read is "three moveto's in a row." The spec says otherwise: only the first pair is M, the rest are implicit lineto's.

If a moveto is followed by multiple pairs of coordinates, the subsequent pairs are treated as implicit lineto commands.
— SVG 2 Paths §8.3.2

Other commands (L, C, Q) do implicitly repeat themselves — M is the odd one out, substituting a different command for its own repetitions. The parser carries a firstIteration flag just to handle this:

let firstIteration = true;
while (/* coords still coming */) {
  if (upper === 'M') {
    const p = readPoint(cursor);
    const abs = isRelative ? rel(currentPoint, p) : p;
    if (firstIteration) {
      out.push({ kind: 'M', p: abs });
      subpathStart = abs;
    } else {
      out.push({ kind: 'L', p: abs });  // ← the trap
    }
    currentPoint = abs;
  }
  // ... other commands
  firstIteration = false;
}

Gotcha: S and T reflect the previous control point

S is "another cubic bezier, but reuse the previous C's second control point, reflected around the current point." Concretely:

M 0 0 C 10 0 20 10 30 10 S 50 20 60 20
              ^^^^^
              previous c2 = (20, 10)
              reflect through (30, 10)
              → implicit new c1 = (40, 10)

Reflection is algebraically trivial:

function reflect(around: Point, p: Point): Point {
  return { x: 2 * around.x - p.x, y: 2 * around.y - p.y };
}

The spec also says: if the previous command wasn't a C or S (or Q/T for T), the reflection point degenerates to the current point (because there's nothing to reflect). Forgetting that rule ships broken paths when someone mixes L and S.

The parser keeps lastCubicC2 and lastQuadC as nullable cursors and resets them to null whenever a non-bezier command runs, so S and T can look them up without worrying about stale state.

Gotcha: number separators

"Numbers are separated by whitespace or commas" almost covers it — except the spec also allows signs and decimal points to act as separators to save bytes:

M.5.5L1,1    ← valid. Equivalent to M 0.5 0.5 L 1 1
M-1-2L3,4    ← valid. Equivalent to M -1 -2 L 3 4

Modern minifiers emit strings like this and browsers accept them silently. Writing a tokenizer that splits on whitespace and commas won't get you there. My number reader is hand-rolled as [sign][int part][. + frac]?[e + exp]?:

function readNumber(cursor: Cursor): number {
  skipWsAndCommas(cursor);
  const start = cursor.pos;
  const src = cursor.src;
  if (src[cursor.pos] === '+' || src[cursor.pos] === '-') cursor.pos++;
  while (/\d/.test(src[cursor.pos])) cursor.pos++;
  if (src[cursor.pos] === '.') {
    cursor.pos++;
    while (/\d/.test(src[cursor.pos])) cursor.pos++;
  }
  // exponent handling...
  return parseFloat(src.slice(start, cursor.pos));
}

It's 20 lines. Worth it vs. regex gymnastics.

Gotcha: Z resets the current point

Z doesn't just close the subpath — it teleports the current point back to the last M. Otherwise:

M 10 10 L 20 20 Z M 30 30 l 5 0
                         ^^^^^^
                         must resolve to (35, 30)
                         because after Z current point is (30, 30)

A parser that doesn't reset the current point on Z will produce a subtly wrong (25, 20) for that last l 5 0. I caught this one in tests — not by reading the spec first.

The drag loop: clientX/Y → SVG user coords

With parsing sorted, rendering is free (<path d={dString}>). The editor's only non-obvious bit is converting mouse coordinates to SVG user-space coordinates during a drag.

Browsers hand you the inverse matrix for free:

function clientToSvg(clientX: number, clientY: number): Point {
  const ctm = svgEl.getScreenCTM();
  if (!ctm) return { x: 0, y: 0 };
  const inv = ctm.inverse();
  const pt = new DOMPoint(clientX, clientY).matrixTransform(inv);
  return { x: pt.x, y: pt.y };
}

getScreenCTM() returns the page-pixel → SVG-user-space transform, including any viewBox scaling and parent transforms. Invert it and matrixTransform does the rest. This is one of those APIs that has been there for fifteen years and hardly anyone mentions it.

For the drag itself, I use pointer capture so a drag keeps tracking the pointer even when it leaves the node:

function startDrag(e: PointerEvent, t: DragTarget) {
  (e.target as Element).setPointerCapture(e.pointerId);
  dragging = t;
}

setPointerCapture + pointermove + pointerup also unifies mouse and touch with one code path — no separate touch handlers.

Why normalize everything to absolute M/L/C/Q/Z

The editor eats H, V, S, T, and relative coordinates and spits out only absolute M/L/C/Q/Z. Trade-off:

Wins: one node = one AST entry. C and S look identical in the UI (an anchor plus two handles). Output is stable across round-trips — git diff on two saves makes sense.
Loses: you can't preserve the original formatting. H 100 comes back as L 100 0. A minified d loses its minification.

For a learning and editing tool that's the right call. A minifier-preserving editor is a different design.

Why I don't support arcs (A)

A rx ry x-axis-rotation large-arc-flag sweep-flag x y is the one SVG command that can't be losslessly reduced to a handful of Bezier segments. You need 2–4 cubic segments to approximate an elliptical arc, and the quality of the approximation depends on the sweep angle. That forces a design choice:

Treat an arc as one draggable node? Then you need a completely different gesture for editing it (radius? rotation?). Big divergence from the M/L/C/Q uniform UI.
Explode it into Beziers up front? Then the user loses the arc as a concept — re-saving is lossy.

I punted: the parser throws on A, with a helpful message.

case 'A':
  throw new Error(
    'Arc commands (A/a) are not supported in this editor — ' +
    'convert to cubic béziers first.',
  );

Silent data loss is worse than an explicit "please flatten this first." Tools like svgo already do the flattening.

Round-trip tests catch every normalization bug

The cleanest way I've found to test a parser + serializer pair is to verify that parse → serialize → parse → serialize gives the same output the second time. If round-tripping is stable, both sides speak the same dialect.

it.each([
  'M 0 0 L 10 10 Z',
  'M 100 100 C 150 100 200 150 200 200 Z',
  'M 0 0 Q 50 50 100 0',
])('serialize(parse(%s)) stabilizes', (d) => {
  const once = serializePath(parsePath(d));
  const twice = serializePath(parsePath(once));
  expect(twice).toBe(once);
});

That one test exercises four different normalization paths (H→L, relative→absolute, S reflection, number rounding) in every case. Combined with a dozen targeted tests for individual gotchas, I have 18 green assertions covering the whole pipeline.

Svelte 5 notes

Two things surprised me on the framework side:

Mutating $state objects doesn't always trigger reactivity. When I wrote path[i].p.x = newX, the UI didn't re-render because the top-level reference didn't change. path = [...path] after each mutation fixes it. Svelte 5's runes are not deep-reactive on arrays for good performance reasons; you opt in with a spread.
bind:this={svgEl} is shorter than useRef. One line, fully typed as SVGSVGElement | null. Small quality-of-life win.

Bundle size was not something I measured tightly, but another portfolio app on the same stack (Svelte 5 + Vite) ships a 19 kB gzipped bundle for a similarly-sized app. This one has fewer features, so probably less.

Takeaways

The SVG d attribute is a pen-command list. M/L/C/Q/Z are the real primitives; H/V/S/T are shorthand.
The landmines are: M x y x y silently becomes M+L, S/T reflect, Z resets the current point, and numbers can split on signs and decimals.
Normalize everything to absolute M/L/C/Q/Z before editing. The UI code gets dramatically simpler.
Arcs can't be losslessly flattened. It's OK to reject them with an error and ask the user to pre-convert.
Use getScreenCTM().inverse() + setPointerCapture() for the drag loop. Both are stable browser APIs you don't see in tutorials much.

If d="M 100 40 C 60 0 0 40 100 140 C 200 40 140 0 100 40 Z" reads cleanly now, the entry cost to CSS path animations (<animate>, offset-path) dropped a notch. That's the real win.

Repository: https://github.com/sen-ltd/svg-path-editor

Forem: SEN LLC

The Three Conditions for Seeing the ISS — A Browser-Only Visibility Calculator with Spherical Trigonometry

The API: wheretheiss.at gives you everything you need in one shot

Condition 1: ISS above the observer's horizon

The footprint radius drops out

Condition 2: ISS in sunlight, not Earth's shadow

Condition 3: the observer's sky is dark enough

What this tool deliberately doesn't do

Map rendering — no coastlines, on purpose

Takeaways

Sample-Free Drum Synthesis in Web Audio — Building Kick, Snare, and Hi-Hat from Oscillators in 60 Lines

Three knobs that make a sound feel like a drum

Kick — sine sweep + fast amp decay

Snare — pitched body + bandpassed noise, mixed in parallel

Hi-hat — square wave through a high-Q bandpass

The lookahead scheduler — why setInterval doesn't work

Tests — fake the AudioContext

Takeaways

A Per-URL TODO List Chrome Extension in 150 Lines — Single-Key chrome.storage Design, URL Normalization, and Three Sync Paths for the Toolbar Badge

Storage shape: pick one key

URL normalisation — eat the ?utm_source and #section

When query is the page

Toolbar badge — three sync paths into one helper

Pruning empty URL keys keeps the store tight

ID generation — crypto.getRandomValues over Date.now()

Tests — no chrome polyfill, no jsdom

Takeaways

A 150-Line `whentime tokyo london ny` CLI in Rust — and Why You Need IANA tzdata, Not 'UTC + N'

Requirements

chrono and chrono-tz, in roles

Aliases — a flat table beats a fuzzy matcher

Half-hour and quarter-hour zones — UTC offsets aren't i32 hours

Collecting all errors before exit

Dynamic column widths in the table

Single static binary via Alpine + chrono-tz

Takeaways

Three Address Checksums, Three Engineering Philosophies — Verifying Base58Check, Bech32m, and EIP-55 in 250 Lines of Browser JS

Three formats, three worldviews

Bitcoin Base58Check — defensive paranoia

The Base58 trap

Ethereum EIP-55 — bolted-on case checksum

The keccak-256 trap — it's not NIST SHA3

Bitcoin SegWit's Bech32 / Bech32m — QR-friendly with a twist

The Bech32m post-mortem (BIP-0350)

A dispatcher false-positive worth knowing

Takeaways

A 230-Line Chrome MV3 Extension That Copies the Page Selection as Markdown — Without ``

Why the browser's clipboard isn't enough

Architecture — MV3 service worker + executeScript

Important: no host_permissions

Popup → service worker, not popup → tab

The HTML→Markdown converter — tag dispatch in 230 lines

Trap 1: pretty-printed inter-block whitespace

Trap 2: nested-list double-indent

Trap 3: GFM tables need a header that the source HTML may not have

The same code runs in Node tests

Takeaways

BIP39 in 180 Lines of Vanilla JS — Mnemonic Generation, Validation, Seed Derivation, and the Japanese Wordlist Trap

What BIP39 actually defines (and what it doesn't)

The encoding, in four steps

Validation is just the same code in reverse

Seed derivation — the fixed PBKDF2 parameters that you can never change

The Japanese wordlist trap — U+3000 versus U+0020

Lock the implementation down with both vector sets

Browser-only deployment notes

Takeaways

Why Your Web Audio Tuner Sucks at Low Notes (and What to Use Instead of FFT)

The symptom — FFT-based tuners can't read low notes

The workarounds and their limits

Pitch is not frequency

Autocorrelation — measuring the period directly

Parabolic interpolation for sub-sample precision

Wiring it to Web Audio

Smooth in log-frequency space, not Hz

Cost vs. the alternative

The takeaway

GitHub's Stargazers API Caps at 40,000. Here's How Star-History Tools Fake the Rest

The undocumented Accept header

Pagination: 100 per page, and a Link header does the counting for you

The 40,000-stargazer wall

The lookahead scheduler — why `setInterval` doesn't work

URL normalisation — eat the `?utm_source` and `#section`

ID generation — `crypto.getRandomValues` over `Date.now()`

Half-hour and quarter-hour zones — UTC offsets aren't `i32` hours

Important: no `host_permissions`

The Japanese wordlist trap — `U+3000` versus `U+0020`

The undocumented `Accept` header

Pagination: 100 per page, and a `Link` header does the counting for you

Wall 3: `speak()` queues. `cancel()` is mandatory.

Gotcha: `M x y x y` is "M then L"