DEV Community: Abid Ali

Trimming Audio in the Browser Without the Click: Zero-Crossing Snaps and Short Fades in JavaScript

Abid Ali — Mon, 02 Nov 2026 20:07:25 +0000

You load a sound into the browser, pick a start and an end, slice the samples and play the result. It works, except for a tiny tick at the very start and another at the end. On a long clip you might not notice. On a two-second reaction sound that plays over and over, the tick becomes part of the sound, and it's the part people remember.

This post explains where that click comes from and fixes it with two small ideas: move each cut point to a nearby zero crossing, then apply a very short fade at both ends. Everything works on plain Float32Arrays, so the core runs the same in the browser and in Node, which makes it easy to test.

Where the click comes from

Decoded audio is a list of numbers between -1 and 1, one per sample per channel. A sound wave moves smoothly through those values. When you cut at an arbitrary sample, the clip can start at, say, 0.6. The speaker cone was at rest a moment ago and now has to jump straight to 0.6. That instant jump is a sharp edge, and a sharp edge contains energy across the whole frequency range. You hear it as a click.

The end has the same problem in reverse: the clip stops at some non-zero value and the output drops to silence in one sample.

So the goal is simple: make the clip start and end at (or very near) zero, and make the change gradual.

Step 1: snap the cut to a zero crossing

A zero crossing is a point where the signal changes sign, so the value there is close to zero. If the cut moves a few samples to land on one, the jump mostly disappears. We only search a small window (a few milliseconds) so the cut doesn't drift audibly from where the user put it.

For stereo files there's a catch: the left and right channels cross zero at different places. If you snap each channel separately, the channels end up different lengths and slightly out of sync. The fix is to find the crossing on a mixed-down copy and cut every channel at that same sample.

Step 2: a short fade at both ends

Some sounds don't cross zero near the cut, for example a low hum or a sound that's loud right at the edge. A fade handles those. A few milliseconds is too short to hear as a fade, but long enough to round off the edge.

I use an equal-power curve (a quarter of a sine wave) rather than a straight line. A linear fade works too; the sine curve just rises a little faster at first, so the start of the sound stays punchy.

The code

Here's the whole module. It has no dependencies.

// declick.mjs: cut a clip out of decoded audio without clicks at the edges.
// Works on plain Float32Arrays, so it runs the same in the browser and in Node.

/** Index of the zero crossing nearest to `index`, searching up to `radius` samples each way. */
export function nearestZeroCrossing(samples, index, radius) {
  const last = samples.length - 1;
  const at = (i) => i >= 1 && i <= last &&
    (samples[i] === 0 || Math.sign(samples[i]) !== Math.sign(samples[i - 1]));
  for (let d = 0; d <= radius; d++) {
    if (at(index - d)) return index - d;
    if (at(index + d)) return index + d;
  }
  return index; // nothing close enough: keep the original cut, the fade still helps
}

/** Mix all channels to one array so every channel is cut at the same sample. */
function mixDown(channels) {
  if (channels.length === 1) return channels[0];
  const out = new Float32Array(channels[0].length);
  for (const ch of channels) for (let i = 0; i < out.length; i++) out[i] += ch[i] / channels.length;
  return out;
}

/** Equal-power fade in and out, applied in place. */
export function applyFades(samples, fadeLength) {
  const n = Math.min(fadeLength, Math.floor(samples.length / 2));
  for (let i = 0; i < n; i++) {
    const g = Math.sin((i / n) * (Math.PI / 2));
    samples[i] *= g;
    samples[samples.length - 1 - i] *= g;
  }
  return samples;
}

/**
 * Cut [startSec, endSec) out of `channels` (an array of Float32Array, one per channel).
 * Cut points snap to a nearby zero crossing, then get a short fade.
 */
export function cleanCut(channels, sampleRate, startSec, endSec, { snapMs = 5, fadeMs = 8 } = {}) {
  const length = channels[0].length;
  const clamp = (i) => Math.max(0, Math.min(length, i));
  const radius = Math.round((snapMs / 1000) * sampleRate);
  const mono = mixDown(channels);
  let start = nearestZeroCrossing(mono, clamp(Math.round(startSec * sampleRate)), radius);
  let end = nearestZeroCrossing(mono, clamp(Math.round(endSec * sampleRate)), radius);
  if (end <= start) throw new RangeError('end must be after start');
  const fade = Math.round((fadeMs / 1000) * sampleRate);
  return {
    start, end,
    channels: channels.map((ch) => applyFades(ch.slice(start, end), fade)),
  };
}

/** Largest jump between neighbouring samples in the first and last few samples: a rough click meter. */
export function edgeJump(samples, window = 4) {
  let max = Math.abs(samples[0]) + Math.abs(samples[samples.length - 1]);
  for (const [a, b] of [[0, window], [samples.length - window, samples.length]])
    for (let i = Math.max(1, a); i < b; i++) max = Math.max(max, Math.abs(samples[i] - samples[i - 1]));
  return max;
}

edgeJump is not part of the fix. It's a rough meter for tests: it looks at the first and last few samples and returns the biggest step it finds, including the step from silence to the first sample and from the last sample back to silence. A clean cut should score close to zero.

Testing it in Node

Because the core takes arrays, not an AudioContext, we can test it with a generated sine wave and node:test:

import test from 'node:test';
import assert from 'node:assert/strict';
import { nearestZeroCrossing, applyFades, cleanCut, edgeJump } from './declick.mjs';

const rate = 48000;
const sine = (hz, sec, amp = 0.8) =>
  Float32Array.from({ length: Math.round(rate * sec) }, (_, i) => amp * Math.sin(2 * Math.PI * hz * i / rate));

test('finds the nearest sign change', () => {
  const s = Float32Array.from([0.5, 0.4, 0.2, -0.1, -0.3, -0.2, 0.1]);
  assert.equal(nearestZeroCrossing(s, 1, 3), 3);
  assert.equal(nearestZeroCrossing(s, 5, 3), 6);
});

test('keeps the original index when nothing is in range', () => {
  const s = new Float32Array(100).fill(0.5);
  assert.equal(nearestZeroCrossing(s, 50, 10), 50);
});

test('fades start and end at silence and leave the middle alone', () => {
  const s = applyFades(new Float32Array(1000).fill(1), 100);
  assert.equal(s[0], 0);
  assert.ok(s[999] < 0.02);
  assert.equal(s[500], 1);
});

test('a raw cut mid-wave jumps, a clean cut does not', () => {
  const tone = sine(220, 1);
  const raw = tone.slice(Math.round(0.1234 * rate), Math.round(0.6789 * rate));
  const { channels } = cleanCut([tone], rate, 0.1234, 0.6789);
  const before = edgeJump(raw), after = edgeJump(channels[0]);
  console.log(`edge jump raw=${before.toFixed(3)} clean=${after.toFixed(4)}`);
  assert.ok(before > 0.5);
  assert.ok(after < 0.01);
});

test('stereo channels are cut at the same samples', () => {
  const l = sine(220, 0.5), r = sine(330, 0.5, 0.4);
  const out = cleanCut([l, r], rate, 0.1, 0.4);
  assert.equal(out.channels.length, 2);
  assert.equal(out.channels[0].length, out.channels[1].length);
  assert.equal(out.channels[0].length, out.end - out.start);
});

test('rejects an end before the start', () => {
  assert.throws(() => cleanCut([sine(220, 0.5)], rate, 0.4, 0.1), RangeError);
});

The interesting test cuts a 220 Hz tone at two awkward times, once with a raw slice and once with cleanCut. Running node --test gives:

edge jump raw=1.278 clean=0.0007
✔ finds the nearest sign change (1.735194ms)
✔ keeps the original index when nothing is in range (0.163684ms)
✔ fades start and end at silence and leave the middle alone (0.913533ms)
✔ a raw cut mid-wave jumps, a clean cut does not (13.270115ms)
✔ stereo channels are cut at the same samples (7.195042ms)
✔ rejects an end before the start (3.9841ms)
ℹ tests 6
ℹ suites 0
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 124.60751

The raw cut starts and ends with a big step. The clean cut's edges are close to silence, which is what you want to hear.

Using it in the browser

In the page, the job is to get samples out of a file and an AudioBuffer back in. decodeAudioData does the first half, and copyToChannel does the second:

import { cleanCut } from './declick.mjs';

// Decode a File (from an <input type="file"> or a drop) into an AudioBuffer.
export async function decodeFile(ctx, file) {
  return ctx.decodeAudioData(await file.arrayBuffer());
}

// Cut a clean clip and return it as a new AudioBuffer you can play or export.
export function cutBuffer(ctx, buffer, startSec, endSec) {
  const input = Array.from({ length: buffer.numberOfChannels }, (_, c) => buffer.getChannelData(c));
  const { channels } = cleanCut(input, buffer.sampleRate, startSec, endSec);
  const clip = new AudioBuffer({
    numberOfChannels: channels.length,
    length: channels[0].length,
    sampleRate: buffer.sampleRate,
  });
  channels.forEach((data, c) => clip.copyToChannel(data, c));
  return clip;
}

// Preview just the clip.
export function play(ctx, clip) {
  const node = new AudioBufferSourceNode(ctx, { buffer: clip });
  node.connect(ctx.destination);
  node.start();
  return node;
}

One detail is easy to miss: decodeAudioData resamples to the context's sample rate. In a test in Chrome, an 8 kHz WAV came back at the context's rate:

chrome 156.0.8078.47 {"inSec": "1.000", "rate": 48000, "clipSec": "0.500", "first": "0.0000", "last": "0.0000"}

So always read buffer.sampleRate from the decoded buffer when you convert seconds to sample indexes, never from the original file. The first and last samples of the clip are zero, as the fades intend.

Choosing the numbers

The defaults in cleanCut are a 5 ms snap window and an 8 ms fade. Some guidelines if you change them:

Keep the snap window small. For speech and short effects a few milliseconds is plenty. A larger window finds a crossing more often but moves the cut further from where it was placed, and on a precise edit that's noticeable.
Make the fade shorter than the attack you care about. A drum hit or a sharp "bruh" has its punch in the first few milliseconds. A long fade-in softens it. If the start sounds dull, shorten the fade before anything else.
Fade out a little longer than you fade in, if you want. Endings are more forgiving, and a slightly longer fade-out hides reverb tails that were cut off.
Never fade more than half the clip. The function caps the fade at half the length so a very short clip doesn't fade in and out at the same time.

What this doesn't solve

A clean edge won't fix everything:

Background noise. If the recording has room noise or hiss, the clip still starts with noise. Cutting at a quiet point between words helps more than any fade.
Lossy export. If you encode the clip to MP3, the encoder adds a small amount of padding at the start. That's a property of the format. If timing has to be exact, keep a WAV copy.
Cutting mid-word. No amount of smoothing makes a clipped syllable sound whole. Move the cut.

If you just need the clip

All of this is worth knowing if you're building an editor. If you only need to cut a sound, a tool will do it faster. Meme Tap's online audio trimmer takes an MP3, WAV or OGG up to 40 MB, lets you drag start and end on a waveform or type them to two decimal places, plays only the selection, and downloads a WAV or an MP3. The file is read in the browser tab and isn't uploaded. If the cut still ticks, nudge the start a few hundredths of a second to a quieter spot.

Once the clip is clean, the audio visualizer turns it into a waveform, frequency-bar or circular video in 16:9, 9:16 or 1:1, exported as WebM with the audio. Both are listed with the caption generator on the Meme Tap tools page.

Summary

A click is a sudden jump from silence to a non-zero sample, or back.
Snap each cut to the nearest zero crossing within a few milliseconds, found on a mixed-down copy so all channels stay in sync.
Add an equal-power fade of a few milliseconds at both ends.
Read the sample rate from the decoded buffer, because decodeAudioData resamples.
Keep the core on plain arrays so you can test it in Node.

I'm Abid Ali, a freelance full-stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I built Meme Tap, which has free meme and audio tools that run in the browser.

Estimating Fixed-Price Freelance Work in TypeScript: Three-Point Estimates, Honest Ranges and the Questions Your Proposal Should Ask

Abid Ali — Mon, 02 Nov 2026 08:59:23 +0000

A fixed-price job post asks for one number. You read the description, picture the work, and type a figure into the bid box. The trouble is that the figure is really a guess about several things at once: how long each part takes when it goes well, how long it takes when it doesn't, and which parts you don't understand yet.

A single number hides all of that. If it's too low, you work the extra hours for free. If you pad it to be safe, the client compares it with cheaper bids and moves on. Neither outcome tells you which part of the guess was wrong.

This post builds a small TypeScript script that keeps the guess honest. For each task you write three numbers instead of one. The script turns them into an expected value and a range, adds them up per milestone, and, most usefully, points out the tasks where your best and worst cases are so far apart that you should ask the client a question before you quote. The whole thing is one file with no dependencies, plus a test file that runs on Node's built-in test runner.

Three numbers per task

Three-point estimation is an old technique from project planning (it's often called PERT). For each task you write down:

best: the hours if everything goes right,
likely: the hours you actually expect,
worst: the hours if the usual things go wrong. Not a disaster, just the slow version: the content arrives late, the API docs are out of date, the design needs a second round.

The expected value weights the likely case most heavily:

expected = (best + 4 × likely + worst) / 6
spread   = (worst − best) / 6

The spread is a rough measure of uncertainty. A task you've done many times has a small spread. A task that depends on something you haven't seen yet has a big one.

Nothing about this is precise. The formula doesn't know your work better than you do. What it does is make you think about the bad case separately from the normal case, which is the step a single number lets you skip.

The task file

Tasks live in a plain JSON file, grouped by milestone. Here's an example for a small business website:

[
  { "milestone": "1. Design", "name": "Home page design", "best": 6, "likely": 8, "worst": 12 },
  { "milestone": "1. Design", "name": "Inner page template", "best": 3, "likely": 4, "worst": 6 },
  { "milestone": "2. Build", "name": "Next.js pages and layout", "best": 10, "likely": 14, "worst": 20 },
  { "milestone": "2. Build", "name": "Contact form with email", "best": 2, "likely": 3, "worst": 5 },
  { "milestone": "2. Build", "name": "Import old blog posts", "best": 3, "likely": 6, "worst": 16 },
  { "milestone": "3. Launch", "name": "Domain, hosting and handover", "best": 2, "likely": 3, "worst": 5 }
]

The milestone names matter. On Upwork, fixed-price contracts are commonly split into milestones that the client funds and approves one at a time, so it helps to estimate in the same shape you'll propose. If you're new to how that works from the client's side, Digital Dialogue's explainer on how Upwork works walks through jobs, proposals and contracts.

The script

Here's the whole of estimate.ts:

// estimate.ts: three-point estimates for a fixed-price proposal.
// Run: node estimate.ts tasks.json [hourlyRate]
import { readFileSync } from "node:fs";

type Task = {
  milestone: string;
  name: string;
  best: number;   // hours if everything goes right
  likely: number; // hours you actually expect
  worst: number;  // hours if the usual things go wrong
};

type Estimate = Task & { expected: number; spread: number };

export function validate(tasks: unknown): Task[] {
  if (!Array.isArray(tasks)) throw new Error("tasks file must contain an array");
  return tasks.map((t, i) => {
    const where = `task ${i + 1} (${t?.name ?? "no name"})`;
    for (const k of ["best", "likely", "worst"] as const) {
      if (typeof t?.[k] !== "number" || !(t[k] > 0)) throw new Error(`${where}: ${k} must be a positive number`);
    }
    if (!(t.best <= t.likely && t.likely <= t.worst)) throw new Error(`${where}: expected best <= likely <= worst`);
    if (!t.milestone || !t.name) throw new Error(`${where}: milestone and name are required`);
    return t as Task;
  });
}

export function threePoint(t: Task): Estimate {
  const expected = (t.best + 4 * t.likely + t.worst) / 6;
  const spread = (t.worst - t.best) / 6;
  return { ...t, expected, spread };
}

export function summarise(tasks: Task[]) {
  const rows = tasks.map(threePoint);
  const groups = new Map<string, Estimate[]>();
  for (const r of rows) groups.set(r.milestone, [...(groups.get(r.milestone) ?? []), r]);
  const milestones = [...groups].map(([name, items]) => total(name, items));
  return { rows, milestones, project: total("Whole project", rows) };
}

function total(name: string, items: Estimate[]) {
  const expected = items.reduce((s, r) => s + r.expected, 0);
  // spreads add as variances, not as plain sums
  const spread = Math.sqrt(items.reduce((s, r) => s + r.spread ** 2, 0));
  return { name, expected, low: expected - spread, high: expected + spread };
}

export function questions(rows: Estimate[], ratio = 3): string[] {
  return rows
    .filter((r) => r.worst >= r.best * ratio)
    .map((r) => `"${r.name}" could take ${hrs(r.best)} or ${hrs(r.worst)}. What would narrow it down?`);
}

const hrs = (n: number) => `${Math.round(n)} h`;
const money = (n: number, rate: number) => Math.round((n * rate) / 10) * 10;

export function toMarkdown(tasks: Task[], rate?: number): string {
  const { rows, milestones, project } = summarise(tasks);
  const out: string[] = ["| Milestone | Expected | Range |", "| --- | --- | --- |"];
  const line = (m: ReturnType<typeof total>) => {
    const range = `${hrs(m.low)} to ${hrs(m.high)}`;
    return `| ${m.name} | ${hrs(m.expected)} | ${rate ? `${range} (${money(m.low, rate)} to ${money(m.high, rate)})` : range} |`;
  };
  for (const m of milestones) out.push(line(m));
  out.push(line(project));
  const qs = questions(rows);
  if (qs.length) out.push("", "Questions before a fixed price:", ...qs.map((q) => `- ${q}`));
  return out.join("\n");
}

if (import.meta.main) {
  const [file, rateArg] = process.argv.slice(2);
  if (!file) { console.error("usage: node estimate.ts tasks.json [hourlyRate]"); process.exit(2); }
  const tasks = validate(JSON.parse(readFileSync(file, "utf8")));
  console.log(toMarkdown(tasks, rateArg ? Number(rateArg) : undefined));
}

A few choices are worth explaining.

Validation comes first. validate() rejects anything that isn't a positive number and anything where the three values are out of order. A task with best larger than likely is almost always a typo, and a typo in an estimate is expensive.

Spreads combine as variances. It's tempting to add the best cases together and the worst cases together, but that assumes every task goes badly at once. In total(), the spreads are squared, summed and square-rooted, which is the usual way to combine independent uncertainties. The result is a project range that's wider than any one task's range but narrower than "everything goes wrong". If your tasks are clearly not independent (for example, every page waits on the same late content), treat the range as optimistic and widen it yourself.

Wide tasks become questions. questions() flags any task whose worst case is at least three times its best case. Those are the tasks where you don't know something, and the cheapest way to find out is usually to ask. The ratio is a parameter, so pick one that matches your own comfort.

Money is optional and rounded. Pass an hourly rate as the second argument and the script adds a price range next to each milestone, rounded to the nearest ten. It doesn't add a currency symbol, because it doesn't know which one you quote in, and it shouldn't pretend to.

It uses only erasable TypeScript syntax (types and annotations, no enums or namespaces), so a recent Node release with built-in type stripping can run it directly with node estimate.ts. On an older Node, npx tsx estimate.ts does the same job.

Running it

node estimate.ts tasks.json 25

The output is a Markdown table you can paste straight into a proposal or a project doc:

| Milestone | Expected | Range |
| --- | --- | --- |
| 1. Design | 13 h | 11 h to 14 h (280 to 340) |
| 2. Build | 25 h | 22 h to 27 h (550 to 690) |
| 3. Launch | 3 h | 3 h to 4 h (70 to 90) |
| Whole project | 40 h | 37 h to 43 h (930 to 1080) |

Questions before a fixed price:
- "Import old blog posts" could take 3 h or 16 h. What would narrow it down?

The milestone rows add up to 41 hours while the whole-project row says 40, because each row is rounded on its own and the total is worked out from the unrounded values. The interesting line is the question at the bottom. Importing the old blog posts could take a few hours or most of two days, and the difference depends entirely on something the job post didn't say: how many posts there are, where they live, and whether images come with them.

Turning the output into a proposal

Here's how I'd use the table in a fixed-price proposal, without pasting the whole thing in.

Lead with the question, not the number. Clients skim proposals. One specific question about their project shows you've read the post more convincingly than any summary of your skills. "Roughly how many posts are on the old blog, and is it WordPress or something else?" is the kind of question that only someone thinking about their project would ask.

Quote the milestones, not the hours. Most clients don't want to see hour counts. They want to know what they get at each stage and what each stage costs. Use the milestone ranges to set milestone prices, and keep the hours for yourself.

Choose where in the range to price. The range isn't the quote. If the client answers your questions and the uncertainty goes away, price nearer the expected value. If they can't answer, either price nearer the high end or split the uncertain task into its own milestone so it can be re-scoped once you know more.

Write down what each milestone includes. A range only holds if the scope holds. One line per milestone, like "home page and one inner page design, two rounds of changes", gives both of you something to point at later.

Testing it

Estimates feed straight into money, so the maths deserves tests. estimate.test.ts uses node:test and node:assert, so there's nothing to install:

import { test } from "node:test";
import assert from "node:assert/strict";
import { threePoint, summarise, questions, validate, toMarkdown } from "./estimate.ts";
const close = (a: number, b: number) => assert.ok(Math.abs(a - b) < 1e-9, `${a} != ${b}`);

test("three-point expected value and spread", () => {
  const e = threePoint({ milestone: "m", name: "t", best: 2, likely: 4, worst: 12 });
  assert.equal(e.expected, 5);
  close(e.spread, 10 / 6);
});
test("milestone spreads combine as square root of summed squares", () => {
  const tasks = [
    { milestone: "m", name: "a", best: 0.5, likely: 3, worst: 6.5 },
    { milestone: "m", name: "b", best: 1, likely: 4, worst: 9 },
  ];
  const { milestones } = summarise(validate(tasks));
  close(milestones[0].high - milestones[0].expected, Math.sqrt(1 + (8 / 6) ** 2));
});
test("wide tasks become questions", () => {
  const rows = [threePoint({ milestone: "m", name: "Import", best: 3, likely: 6, worst: 16 }),
                threePoint({ milestone: "m", name: "Form", best: 2, likely: 3, worst: 5 })];
  assert.equal(questions(rows).length, 1);
  assert.match(questions(rows)[0], /Import/);
});
test("validation rejects best > likely", () => {
  assert.throws(() => validate([{ milestone: "m", name: "x", best: 5, likely: 3, worst: 8 }]), /best <= likely <= worst/);
});
test("markdown has one row per milestone plus total", () => {
  const md = toMarkdown(validate([{ milestone: "A", name: "x", best: 1, likely: 2, worst: 3 },
                                  { milestone: "B", name: "y", best: 1, likely: 2, worst: 3 }]));
  assert.equal(md.split("\n").filter((l) => l.startsWith("| ") && !l.startsWith("| ---")).length, 4);
});

Run it with node --test estimate.test.ts. The floating-point comparisons use a small tolerance instead of strict equality, because 10 / 6 and the same value computed another way don't always agree to the last bit.

Where this fits on Fiverr

On Fiverr the shape is different. You usually set package prices in advance, and buyers pick one. The same script still helps, just earlier: estimate the work behind each package once, look at which tasks have the widest ranges, and either leave them out of the package or describe them precisely enough that the range shrinks. If a buyer needs something outside the package, a custom offer is the place for a fresh estimate. Digital Dialogue's guide to how Fiverr works explains gigs, packages and orders from both sides.

Limits

This is a thinking tool, not a forecast. The output is only as good as the three numbers you type, and it can't tell you that a task is missing from the list. Two habits help:

Keep your old task files. After a project, write the actual hours next to each estimate. You'll quickly see which kinds of tasks you underestimate.
Re-run it when the scope changes. If the client adds a page, add a task and send the new milestone range with the change request, before you start the work.

FAQ

Is a three-point estimate only for big projects?
No. It's most useful on small fixed-price jobs, where one badly guessed task can wipe out the margin. Even three or four tasks are enough.

Should I show the range to the client?
Usually not as hours. Show prices per milestone and the questions that would firm them up. Some clients appreciate seeing a low and high figure for an uncertain part, especially if you explain what decides it.

Why not just add a fixed buffer to everything?
A flat buffer treats the content import and the contact form as equally risky. Three numbers per task put the buffer where the risk is, and tell you which question to ask.

I'm Abid Ali, a freelance full-stack developer in Karachi working mostly in TypeScript, Next.js, React and Node.js. I write practical guides on freelancing platforms, proposals and client work on Digital Dialogue.

A Pre-Delivery Check for Freelance Web Projects: One Node Script for Broken Links, Missing Alt Text and Leftover Staging URLs

Abid Ali — Sun, 01 Nov 2026 09:18:16 +0000

The worst feedback on a freelance web project is not "can you change the colour of this button". It's the message that arrives ten minutes after you deliver: "the Contact link on the About page goes nowhere", or "why does the pricing page link to a staging address?" Nothing is really broken, but the client now reads every other page looking for the next mistake.

Most of those messages are about things a machine could have found. So before marking a project as delivered, it's worth running one script against the staging site. This one crawls every internal page and prints a short Markdown report: broken links, pages without a title or meta description, images without alt text, duplicate titles, insecure http:// assets, and leftover text like localhost, lorem ipsum, TODO or the staging hostname.

This post walks through that script. It's about 60 lines of plain JavaScript with no dependencies, it runs on Node 18 or newer (which has fetch built in), and you can change the rules in a minute.

What it checks, and what it doesn't

The checks are deliberately boring. Each one is something a client or their visitors would notice:

Broken internal links. Any internal URL that doesn't return a successful status.
Missing <title> or meta description. These are what show up in browser tabs, search results and link previews.
Images with no alt attribute at all. An empty alt="" is fine for decorative images, so the script only flags a missing attribute.
Duplicate titles. Usually a copy-pasted layout that never got its own title.
Insecure assets. An http:// image, script or stylesheet on an https:// page.
Leftovers. Text you never want a client to see: localhost, 127.0.0.1, lorem ipsum, TODO, plus any hostnames you pass in.

It doesn't run JavaScript, measure performance or replace a proper accessibility audit. Pages that build their content in the browser will look emptier to it than they do to a visitor. For a typical brochure site, landing page or blog theme, though, the server's HTML is what matters, and that's what it reads.

Reading attributes without a parser

To stay dependency-free, the script uses two small regex helpers instead of an HTML parser. tags() finds every opening tag with a given name, and attr() reads one attribute from a tag whether it's double-quoted, single-quoted or unquoted:

const attr = (tag, name) => {
  const m = tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'));
  return m ? (m[1] ?? m[2] ?? m[3]) : null;
};
const tags = (html, name) => html.match(new RegExp(`<${name}\\b[^>]*>`, 'gi')) ?? [];

Regex HTML parsing has well-known limits: an attribute value containing > will confuse it, and so will tags inside comments. For a check that runs against your own templates, that trade-off is fine. If you need more, swap these two functions for a real parser such as parse5 and keep the rest.

Note that attr() returns null when an attribute is missing and an empty string when it's present but empty. That difference is what lets the alt-text rule tell "forgot the alt" from "decorative image".

The per-page checks

checkPage() takes the page's final URL and its HTML, and returns the title (for the duplicate check later) and a list of issues written as plain sentences:

function checkPage(url, html) {
  const issues = [];
  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1].trim();
  if (!title) issues.push('missing <title>');
  const desc = tags(html, 'meta').find((t) => attr(t, 'name')?.toLowerCase() === 'description');
  if (!desc || !attr(desc, 'content')?.trim()) issues.push('missing meta description');
  for (const img of tags(html, 'img')) {
    if (attr(img, 'alt') === null) issues.push(`image without alt: ${attr(img, 'src')}`);
  }
  if (url.protocol === 'https:') {
    for (const t of [...tags(html, 'img'), ...tags(html, 'script'), ...tags(html, 'link')]) {
      const src = attr(t, 'src') ?? (attr(t, 'rel')?.includes('stylesheet') ? attr(t, 'href') : null);
      if (src?.startsWith('http://')) issues.push(`insecure asset (http://): ${src}`);
    }
  }
  const text = html.replace(/<script[\s\S]*?<\/script>/gi, '');
  for (const word of LEFTOVERS) {
    if (text.toLowerCase().includes(word.toLowerCase())) issues.push(`leftover text: "${word}"`);
  }
  return { title, issues };
}

The leftover search strips <script> blocks first, because analytics snippets and framework code often contain words like localhost legitimately. It searches the rest of the HTML, attributes included, which is the point: a staging hostname hiding in an href is exactly what we want to catch.

The TODO rule is case-insensitive, so a to-do list app will trip it on every page. Remove it from the list for projects like that.

The crawl

The crawl is a plain breadth-first loop. It starts at the URL you pass, follows only same-origin links, ignores mailto:, tel:, javascript: and in-page # links, strips fragments so /about#team and /about count as one page, and stops after --max pages so a calendar or a search page with endless links can't keep it running forever:

const queue = [start.href], seen = new Set(queue), pages = [], broken = [], titles = new Map();
while (queue.length && pages.length < MAX) {
  const href = queue.shift();
  const res = await fetch(href, { redirect: 'follow' }).catch((e) => ({ ok: false, status: e.cause?.code ?? 'ERR' }));
  if (!res.ok) { broken.push({ href, status: res.status }); continue; }
  if (!res.headers.get('content-type')?.includes('text/html')) continue;
  const html = await res.text();
  const url = new URL(res.url);
  const { title, issues } = checkPage(url, html);
  pages.push({ href: url.href, issues });
  if (title) titles.set(title, [...(titles.get(title) ?? []), url.pathname]);
  for (const a of tags(html, 'a')) {
    const raw = attr(a, 'href');
    if (!raw || /^(mailto:|tel:|javascript:|#)/i.test(raw)) continue;
    const next = new URL(raw, url); next.hash = '';
    if (next.origin === start.origin && !seen.has(next.href)) { seen.add(next.href); queue.push(next.href); }
  }
}

Two details matter here. Relative links are resolved against res.url, the address after redirects, not the one we asked for, so a page that redirects from /about to /about/ resolves its links correctly. And network errors (a DNS failure, a refused connection) are turned into a "broken" entry with the error code instead of crashing the whole run.

External links aren't fetched at all. Checking them is slow, some sites block scripted requests, and a third-party page being down isn't something you can fix before delivery. If you want it, add a second pass with HEAD requests and a short timeout.

The report

The output is Markdown, so you can paste it straight into an issue, a pull request or your own notes. Sections only appear when they have something in them:

const lines = [`# Pre-delivery check: ${start.origin}`, '', `Checked ${pages.length} page(s).`, ''];
if (broken.length) lines.push('## Broken links', ...broken.map((b) => `- ${b.href} (${b.status})`), '');
const dupes = [...titles].filter(([, p]) => p.length > 1);
if (dupes.length) lines.push('## Duplicate titles', ...dupes.map(([t, p]) => `- "${t}": ${p.join(', ')}`), '');
const flagged = pages.filter((p) => p.issues.length);
if (flagged.length) lines.push('## Page issues', ...flagged.flatMap((p) => [`- ${new URL(p.href).pathname}`, ...p.issues.map((i) => `  - ${i}`)]), '');
if (!broken.length && !dupes.length && !flagged.length) lines.push('No issues found.');
console.log(lines.join('\n'));
process.exitCode = broken.length || dupes.length || flagged.length ? 1 : 0;

The exit code is 1 whenever something is flagged, so the same script can run in CI and fail a build.

The whole script

Here it is in one piece, ready to save as predeliver.mjs:

// predeliver.mjs: crawl a staging site before handover and list what a client would notice.
// Node 18+ (built-in fetch), no dependencies. Usage:
//   node predeliver.mjs https://staging.example.com --leftover=staging.example.com --max=60
const args = process.argv.slice(2);
const start = new URL(args.find((a) => !a.startsWith('--')));
const opt = (name, def) => (args.find((a) => a.startsWith(`--${name}=`)) ?? `=${def}`).split('=').slice(1).join('=');
const MAX = Number(opt('max', 50));
const LEFTOVERS = ['localhost', '127.0.0.1', 'lorem ipsum', 'TODO', ...opt('leftover', '').split(',').filter(Boolean)];

const attr = (tag, name) => {
  const m = tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'));
  return m ? (m[1] ?? m[2] ?? m[3]) : null;
};
const tags = (html, name) => html.match(new RegExp(`<${name}\\b[^>]*>`, 'gi')) ?? [];

function checkPage(url, html) {
  const issues = [];
  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1].trim();
  if (!title) issues.push('missing <title>');
  const desc = tags(html, 'meta').find((t) => attr(t, 'name')?.toLowerCase() === 'description');
  if (!desc || !attr(desc, 'content')?.trim()) issues.push('missing meta description');
  for (const img of tags(html, 'img')) {
    if (attr(img, 'alt') === null) issues.push(`image without alt: ${attr(img, 'src')}`);
  }
  if (url.protocol === 'https:') {
    for (const t of [...tags(html, 'img'), ...tags(html, 'script'), ...tags(html, 'link')]) {
      const src = attr(t, 'src') ?? (attr(t, 'rel')?.includes('stylesheet') ? attr(t, 'href') : null);
      if (src?.startsWith('http://')) issues.push(`insecure asset (http://): ${src}`);
    }
  }
  const text = html.replace(/<script[\s\S]*?<\/script>/gi, '');
  for (const word of LEFTOVERS) {
    if (text.toLowerCase().includes(word.toLowerCase())) issues.push(`leftover text: "${word}"`);
  }
  return { title, issues };
}

const queue = [start.href], seen = new Set(queue), pages = [], broken = [], titles = new Map();
while (queue.length && pages.length < MAX) {
  const href = queue.shift();
  const res = await fetch(href, { redirect: 'follow' }).catch((e) => ({ ok: false, status: e.cause?.code ?? 'ERR' }));
  if (!res.ok) { broken.push({ href, status: res.status }); continue; }
  if (!res.headers.get('content-type')?.includes('text/html')) continue;
  const html = await res.text();
  const url = new URL(res.url);
  const { title, issues } = checkPage(url, html);
  pages.push({ href: url.href, issues });
  if (title) titles.set(title, [...(titles.get(title) ?? []), url.pathname]);
  for (const a of tags(html, 'a')) {
    const raw = attr(a, 'href');
    if (!raw || /^(mailto:|tel:|javascript:|#)/i.test(raw)) continue;
    const next = new URL(raw, url); next.hash = '';
    if (next.origin === start.origin && !seen.has(next.href)) { seen.add(next.href); queue.push(next.href); }
  }
}

const lines = [`# Pre-delivery check: ${start.origin}`, '', `Checked ${pages.length} page(s).`, ''];
if (broken.length) lines.push('## Broken links', ...broken.map((b) => `- ${b.href} (${b.status})`), '');
const dupes = [...titles].filter(([, p]) => p.length > 1);
if (dupes.length) lines.push('## Duplicate titles', ...dupes.map(([t, p]) => `- "${t}": ${p.join(', ')}`), '');
const flagged = pages.filter((p) => p.issues.length);
if (flagged.length) lines.push('## Page issues', ...flagged.flatMap((p) => [`- ${new URL(p.href).pathname}`, ...p.issues.map((i) => `  - ${i}`)]), '');
if (!broken.length && !dupes.length && !flagged.length) lines.push('No issues found.');
console.log(lines.join('\n'));
process.exitCode = broken.length || dupes.length || flagged.length ? 1 : 0;

Running it

Point it at the staging site and pass the staging hostname as a leftover, so any absolute link that still mentions it is caught once the site moves to the real domain:

node predeliver.mjs https://staging.example.com --leftover=staging.example.com --max=60

Here it is tested against a tiny two-page fixture site served locally with python3 -m http.server. The home page had an image without alt text, a TODO paragraph, a link to a missing /contact page and an absolute link to a fake staging hostname; the About page reused the home page's title and had no description. This is the report it printed, with exit code 1:

# Pre-delivery check: http://127.0.0.1:8765

Checked 2 page(s).

## Broken links
- http://127.0.0.1:8765/contact (404)

## Duplicate titles
- "Acme Tiles": /, /about/

## Page issues
- /
  - image without alt: /hero.jpg
  - leftover text: "TODO"
  - leftover text: "staging.acme-test.local"
- /about/
  - missing meta description

The About page's alt="" team photo wasn't flagged, as intended. A clean page in the same folder produced "No issues found." and exit code 0.

One caveat: if your staging site is password-protected, fetch will get the login page or a 401. Either run the check from a machine that can reach staging without the password, or add an Authorization header to the fetch call for that run only, and keep the credentials out of the script.

Where it fits in a freelance workflow

There are two good moments to run it: before you tell the client the work is ready for review, and again after the site moves to its real domain. The second run is the one that catches staging links, because they only become wrong after the move.

How you hand work over depends on where the client found you. On Upwork, delivery usually lines up with a contract milestone the client reviews and approves; on Fiverr, you deliver an order and the buyer either accepts it or asks for a revision. If you're new to either, Digital Dialogue has plain explainers of how Upwork works and how Fiverr works, step by step, from profile to payment. Either way, the moment you click "submit" or "deliver" is the moment the client starts clicking around, and a clean report is a good thing to have done just before it.

The report itself doesn't need to go in the delivery message. Clients don't need a list of things you fixed. A short note saying which pages you checked and how is enough, and it reads much better than a defensive reply to "this link is broken" an hour later.

I'm Abid Ali, a freelance full-stack developer in Karachi. I write practical guides on freelancing platforms, proposals and client work on Digital Dialogue.

Building a Small Link Unfurler in Node.js: Tag Fallbacks, Relative Image URLs, Charsets and Not Fetching Your Own Network

Abid Ali — Sat, 31 Oct 2026 07:16:35 +0000

Most writing about link previews is from the publisher's side: which tags to put in your <head> so your page looks good when shared. This post is from the other side. Say you're building a chat feature, a comment box or a bookmarks app, and you want pasted links to turn into cards. Now you're the one fetching strangers' pages, and you have to decide what to do when the tags are missing, duplicated, relative or in the wrong encoding.

I build OG Scope, a free link preview checker, so I've spent a lot of time looking at how real pages publish (and fail to publish) their share tags. Below is a small unfurler in one Node file with no dependencies. It's not a drop-in replacement for a battle-tested library, but writing it makes every decision visible, and the decisions are the interesting part.

It does five things:

Fetches the page with redirects handled by hand, a timeout and a size limit
Refuses to fetch private or local addresses, on every redirect hop
Decodes the bytes using the right character set
Reads <meta> tags, <title> and the icon from the <head> only
Builds a card with a clear fallback order and absolute URLs

Everything runs on Node 18 or newer (I tested on Node 24), using the built-in fetch and test runner.

The fallback order

Before any code, decide what wins when a page publishes more than one candidate. This is the order I use, which is close to what you'll see most apps do, though each product has its own rules and they change:

Card field	First choice	Then	Last resort
Title	`og:title`	`twitter:title`, then `<title>`	the hostname
Description	`og:description`	`twitter:description`, then `meta name="description"`	nothing
Image	`og:image:secure_url` / `og:image`	`twitter:image`	no image
Site name	`og:site_name`		the hostname without `www.`

Two rules matter as much as the order:

Empty values don't count. <meta property="og:title" content=""> happens more than you'd think (a CMS field left blank). Treat it as missing and fall through.
The first duplicate wins. Pages often print og:title twice, once from the theme and once from an SEO plugin. Pick one rule and stick to it. Taking the first is the common choice, and it's predictable.

Fetching safely

An unfurler is a server that fetches any URL a user types. That's the textbook setup for server-side request forgery (SSRF): someone pastes http://169.254.169.254/ or http://localhost:6379/ and your server politely requests it from inside your network. So the fetch step checks the address before every request, including after each redirect, because a public URL can redirect to a private one.

// unfurl.mjs: fetch a page and build a link preview the way a chat app would
import { lookup } from 'node:dns/promises';
import { isIP } from 'node:net';

const MAX_BYTES = 512 * 1024;   // stop reading after 512 KB
const MAX_REDIRECTS = 5;
const TIMEOUT_MS = 5000;

function isPrivateAddress(ip) {
  if (isIP(ip) === 6) {
    const v = ip.toLowerCase();
    if (v.startsWith('::ffff:')) return isPrivateAddress(v.slice(7));
    return v === '::1' || v === '::' || v.startsWith('fc') || v.startsWith('fd') || v.startsWith('fe80');
  }
  const [a, b] = ip.split('.').map(Number);
  return a === 10 || a === 127 || a === 0 ||
    (a === 169 && b === 254) ||
    (a === 172 && b >= 16 && b <= 31) ||
    (a === 192 && b === 168) ||
    (a === 100 && b >= 64 && b <= 127);
}

async function assertPublicUrl(url) {
  if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new Error('Only http and https links are previewed');
  const host = url.hostname.replace(/^\[|\]$/g, '');
  const addresses = isIP(host) ? [{ address: host }] : await lookup(host, { all: true });
  if (addresses.some(({ address }) => isPrivateAddress(address))) throw new Error('Refusing to fetch a private address');
}

async function fetchHead(startUrl) {
  let url = new URL(startUrl);
  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
    await assertPublicUrl(url);   // check every hop, not just the first
    const res = await fetch(url, {
      redirect: 'manual',
      signal: AbortSignal.timeout(TIMEOUT_MS),
      headers: { 'user-agent': 'ExampleUnfurler/1.0 (+https://example.com/bot)', accept: 'text/html' },
    });
    if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
      url = new URL(res.headers.get('location'), url);
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const type = res.headers.get('content-type') || '';
    if (!type.includes('html')) throw new Error(`Not an HTML page (${type || 'no content-type'})`);
    return { finalUrl: url, contentType: type, bytes: await readLimited(res) };
  }
  throw new Error('Too many redirects');
}

A few choices worth explaining:

redirect: 'manual' so we see each Location and check it. With automatic redirects, fetch would follow a hop to 127.0.0.1 without asking.
A timeout with AbortSignal.timeout(). A slow page shouldn't hold a chat message hostage. Five seconds is generous.
An honest user agent with a URL that explains the bot. Some sites block unknown crawlers; a clear name at least lets site owners decide.
Only HTML. If someone pastes a link to a 2 GB video, we stop at the content type.

One honest limitation: lookup() resolves the name, then fetch resolves it again. A hostile DNS server could answer differently the second time (DNS rebinding). For a production service, fetch through an egress proxy that enforces the allow rules, or pin the resolved IP with a custom agent. The check above still stops the casual cases, which are the common ones.

Reading only what you need

Share tags live in <head>, so there's no reason to download a 3 MB page. The reader stops at 512 KB or as soon as a chunk contains </head>, whichever comes first:

async function readLimited(res) {
  const chunks = [];
  let total = 0;
  for await (const chunk of res.body) {
    chunks.push(chunk);
    total += chunk.length;
    if (total >= MAX_BYTES) break;                                    // big page: stop early
    if (Buffer.from(chunk).toString('latin1').includes('</head>')) break; // tags live in <head>
  }
  return Buffer.concat(chunks).subarray(0, MAX_BYTES);
}

Getting the characters right

If you decode everything as UTF-8, a Shift_JIS or Windows-1252 page turns its title into mojibake. The charset can come from the Content-Type header or from a <meta charset> near the top of the document. The header wins when both exist:

function decodeHtml(bytes, contentType) {
  const fromHeader = /charset=["']?([\w-]+)/i.exec(contentType)?.[1];
  const sniff = bytes.subarray(0, 2048).toString('latin1');
  const fromMeta = /<meta[^>]+charset=["']?([\w-]+)/i.exec(sniff)?.[1];
  try { return new TextDecoder(fromHeader || fromMeta || 'utf-8').decode(bytes); }
  catch { return new TextDecoder('utf-8').decode(bytes); }   // unknown label
}

TextDecoder in Node supports the common legacy encodings, and the try catches labels it doesn't know.

Parsing the head without a parser

For a production service I'd reach for a real HTML parser. For share tags, a careful pattern match over <meta> and <link> tags covers what pages actually publish: double quotes, single quotes, unquoted values, attributes in either order, and entities like & inside content.

const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
function decodeEntities(s) {
  return s.replace(/&(#x[\da-f]+|#\d+|\w+);/gi, (m, e) => {
    if (e[0] === '#') {
      const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
      return Number.isFinite(n) && n <= 0x10ffff ? String.fromCodePoint(n) : m;
    }
    return ENTITIES[e.toLowerCase()] ?? m;
  });
}

function parseAttributes(tag) {
  const attrs = {};
  for (const [, name, , v1, v2, v3] of tag.matchAll(/([\w:-]+)\s*(=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g)) {
    attrs[name.toLowerCase()] = decodeEntities(v1 ?? v2 ?? v3 ?? '');
  }
  return attrs;
}

export function readTags(html) {
  const head = html.split(/<\/head>/i)[0];
  const meta = {};
  for (const [tag] of head.matchAll(/<meta\b[^>]*>/gi)) {
    const a = parseAttributes(tag.slice(5));
    const key = (a.property || a.name || '').toLowerCase();
    if (key && a.content !== undefined && !(key in meta)) meta[key] = a.content.trim(); // first one wins
  }
  const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(head)?.[1];
  const icon = [...head.matchAll(/<link\b[^>]*>/gi)].map(([t]) => parseAttributes(t.slice(5)))
    .find((a) => /(^|\s)icon(\s|$)/i.test(a.rel || ''))?.href;
  return { meta, title: title ? decodeEntities(title).replace(/\s+/g, ' ').trim() : '', icon };
}

Note the split(/<\/head>/i)[0]: tags after </head> are ignored. Some pages print share tags in the body by mistake, and many consumers won't see them, so neither should we.

Building the card

This is where the fallback table becomes code. URLs are resolved against the final URL after redirects, not the one the user pasted, because a relative og:image like /img/card.png belongs to the page that served it. Anything that isn't http or https after resolving is dropped, which quietly removes javascript: and data: values.

const first = (...values) => values.find((v) => typeof v === 'string' && v.trim() !== '')?.trim();
const clip = (s, n) => (s && [...s].length > n ? [...s].slice(0, n - 1).join('').trimEnd() + '…' : s);

export function buildPreview({ meta, title, icon }, pageUrl) {
  const abs = (u) => { try { const r = new URL(u, pageUrl); return /^https?:$/.test(r.protocol) ? r.href : undefined; } catch { return undefined; } };
  return {
    url: pageUrl.href,
    siteName: first(meta['og:site_name'], pageUrl.hostname.replace(/^www\./, '')),
    title: clip(first(meta['og:title'], meta['twitter:title'], title, pageUrl.hostname), 120),
    description: clip(first(meta['og:description'], meta['twitter:description'], meta.description), 300),
    image: abs(first(meta['og:image:secure_url'], meta['og:image'], meta['og:image:url'], meta['twitter:image'], meta['twitter:image:src']) ?? ''),
    imageAlt: first(meta['og:image:alt'], meta['twitter:image:alt']),
    largeImage: meta['twitter:card'] === 'summary_large_image' || Boolean(meta['og:image:width'] && Number(meta['og:image:width']) >= 600),
    icon: abs(icon ?? '/favicon.ico'),
  };
}

export async function unfurl(link) {
  const { finalUrl, contentType, bytes } = await fetchHead(link);
  return buildPreview(readTags(decodeHtml(bytes, contentType)), finalUrl);
}

The title is clipped to 120 characters and the description to 300, counting code points ([...s]) so an emoji or an Urdu character isn't cut in half. largeImage is a hint for your UI: show a wide image when the page asks for summary_large_image or declares a reasonably wide image, and a small thumbnail otherwise.

Tests

Node's built-in runner is enough. These cover the fallback order, duplicates, empty values, tags in the body and a javascript: image:

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readTags, buildPreview } from './unfurl.mjs';

const page = new URL('https://example.com/blog/post?ref=chat');

test('og tags win over twitter tags and <title>', () => {
  const html = `<head><title>Post | Example</title>
    <meta property="og:title" content="Fish &amp; Chips">
    <meta name="twitter:title" content="Twitter title">
    <meta property="og:image" content="/img/card.png"></head>`;
  const p = buildPreview(readTags(html), page);
  assert.equal(p.title, 'Fish & Chips');
  assert.equal(p.image, 'https://example.com/img/card.png');
});

test('falls back to twitter tags, then <title> and meta description', () => {
  const p = buildPreview(readTags(`<head><title> Just a\n title </title><meta name="description" content="Plain description"><meta name="twitter:image" content="card.png"></head>`), page);
  assert.equal(p.title, 'Just a title');
  assert.equal(p.description, 'Plain description');
  assert.equal(p.image, 'https://example.com/blog/card.png');
});

test('first duplicate tag wins, empty values are skipped', () => {
  const p = buildPreview(readTags(`<head><meta property="og:title" content=""><meta property="og:description" content="One"><meta property="og:description" content="Two"><title>T</title></head>`), page);
  assert.equal(p.title, 'T');
  assert.equal(p.description, 'One');
});

test('ignores tags after </head> and javascript: images', () => {
  const p = buildPreview(readTags(`<head><meta property="og:image" content="javascript:alert(1)"></head><body><meta property="og:title" content="Body tag"></body>`), page);
  assert.equal(p.image, undefined);
  assert.equal(p.title, 'example.com');
});

test('single quotes, unquoted values and long titles', () => {
  const long = 'A'.repeat(200);
  const p = buildPreview(readTags(`<head><meta content='${long}' property='og:title'><meta name=twitter:card content=summary_large_image></head>`), page);
  assert.equal([...p.title].length, 120);
  assert.ok(p.title.endsWith('…'));
  assert.equal(p.largeImage, true);
});

$ node --test unfurl.test.mjs
ℹ tests 5
ℹ pass 5
ℹ fail 0

And a real page:

$ node unfurl.mjs https://www.ogscope.pk/og-image-checker
{
  "url": "https://www.ogscope.pk/og-image-checker",
  "title": "OG Image Checker: What It Tests · OG Scope",
  "image": "https://www.ogscope.pk/og-image-checker-what-it-tests.webp",
  "largeImage": true,
  ...
}
$ node unfurl.mjs http://127.0.0.1/
Refusing to fetch a private address

What I'd add before shipping it

Cache the result per URL for a while (an hour or a day). Pasting the same link twenty times in a channel shouldn't mean twenty fetches. This is also why publishers see old cards after fixing a page: the consumer cached it.
Proxy the image through your own server instead of hot-linking it into users' browsers, so the image host doesn't learn who viewed the chat, and so you can enforce a size limit on the image too.
Rate-limit per user and per domain, so nobody uses your unfurler to hammer a site.
Respect opt-outs your product decides to honour, and show the plain link when anything fails. A card is a nice-to-have; the link is the message.

Checking your output against a reference

When your unfurler and another app disagree about a page, it helps to see the raw tags the page publishes. I use the Open Graph preview in OG Scope for that: it reads the public HTML on the server, lists the Open Graph and Twitter tags, the title, description and canonical, and draws estimated cards for several apps. If both tools see the same tags but show different cards, the difference is in the fallback rules, which, after this post, you now get to choose on purpose.

Ampersands, Quotes and Double-Encoding: Escaping og:title and og:description Exactly Once

Abid Ali — Fri, 30 Oct 2026 07:27:33 +0000

A shop owner shares a link to a page called Fish & Chips: "Best" in Town. In the chat, the card reads Fish & Chips: "Best" in Town. On another page, the title just stops at The, because a straight quote ended the attribute early.

Neither of these is a platform bug. Both come from the same place: the text was escaped the wrong number of times on its way into a <meta> tag. Once too many and the reader sees entity codes. Zero times and a quote breaks the HTML. This post walks through why it happens, a small helper that escapes exactly once, and a checker you can run on any page's HTML. Everything here is plain JavaScript with Node's built-in test runner, no packages.

How a value travels into a share tag

Share text rarely starts life as a clean string. Look at where og:title and og:description usually come from:

a CMS title field, which may store Fish & Chips or Fish & Chips depending on the editor
an excerpt generated from rich text, which still has <p>, <strong> and   in it
a product feed or spreadsheet import, where someone already "made it HTML-safe"
a template engine or a framework like React or the Next.js metadata API, which escapes attribute values for you

Every one of those steps can escape. If two of them do, you get the &amp; card. HTML parsing is strict about this: &amp; decodes once, to the literal text &, and that's what a crawler that reads the tag will hand to the card. Nothing downstream is going to "fix" it for you.

The opposite failure is quieter. A raw " inside a double-quoted attribute ends the value:

<meta property="og:title" content="The "Best" Chips in Town">

A parser reads content as The and treats Best" and the rest as junk attributes. The card shows a one-word title, or falls back to something else, depending on the app.

The rule: plain text in the middle, escape once at the edge

The fix is a boundary rule, not a cleverer escape function:

Normalise to plain text once, as soon as the value enters your code. Strip tags, decode entities one time, collapse whitespace.
Keep it plain through every function, cache and API in between.
Escape exactly once, at the last moment, by whatever writes the HTML.

Step 3 has a catch. If you render with React, JSX, the Next.js metadata API or most template engines with auto-escaping, they are the edge, so you pass plain text and do not escape yourself. Only escape by hand when you're building HTML strings, for example in a static site script or an edge function that rewrites HTML.

The helper

Here's the whole thing. It decodes the entities that turn up in real CMS output (the basic five,  , curly quotes, dashes, ellipsis, plus numeric and hex references) and leaves unknown names alone rather than guessing.

// share-text.mjs: turn whatever the CMS gives you into one escaped attribute value.
const NAMED = {
  amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: '\u00a0',
  ndash: '\u2013', mdash: '\u2014', hellip: '\u2026', lsquo: '\u2018', rsquo: '\u2019',
  ldquo: '\u201c', rdquo: '\u201d', copy: '\u00a9', reg: '\u00ae', trade: '\u2122',
};

export function decodeEntities(s) {
  return s.replace(/&(#[xX][0-9a-fA-F]+|#\d+|[a-zA-Z]+);/g, (m, e) => {
    if (e[0] === '#') {
      const hex = e[1] === 'x' || e[1] === 'X';
      const cp = parseInt(e.slice(hex ? 2 : 1), hex ? 16 : 10);
      return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : m;
    }
    return NAMED[e] ?? m; // unknown names stay as they are
  });
}

// Plain text, once: drop tags, decode entities a single time, collapse whitespace.
export function toPlainText(raw) {
  const noTags = String(raw).replace(/<[^>]*>/g, ' ');
  return decodeEntities(noTags)
    .replace(/\s+/g, ' ')
    .replace(/ ([,.;:!?])/g, '$1') // "</strong>," left a space before the comma
    .trim();
}

// Escape for a double-quoted attribute. Run this exactly once, at the very end.
export function escapeAttr(text) {
  return text
    .replace(/&/g, '&amp;')
    .replace(/"/g, '&quot;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;');
}

export function metaTag(attr, key, raw) {
  return `<meta ${attr}="${key}" content="${escapeAttr(toPlainText(raw))}">`;
}

Three details are deliberate:

Decoding runs once. Fish &amp; Chips becomes Fish & Chips, not Fish & Chips. If text arrives double-escaped, the honest fix is upstream, and the checker below will point at it. Decoding in a loop until nothing changes would also mangle a page that's genuinely about HTML entities.
& is escaped first in escapeAttr. Do it later and you escape your own " into &quot;, which is the bug we're trying to remove.
Bad code points are kept as text.  or an out-of-range hex value would throw in String.fromCodePoint, so they're returned unchanged.

Usage when you build the head yourself:

import { metaTag, toPlainText } from './share-text.mjs';

const post = { title: 'Fish &amp; Chips: "Best" in Town', excerpt: '<p>Open <strong>late</strong>,&nbsp;every day.</p>' };

console.log(metaTag('property', 'og:title', post.title));
// <meta property="og:title" content="Fish &amp; Chips: &quot;Best&quot; in Town">

console.log(metaTag('property', 'og:description', post.excerpt));
// <meta property="og:description" content="Open late, every day.">

And in a framework that escapes for you, stop at plain text:

// Next.js App Router: the metadata API writes the tags and escapes them.
export async function generateMetadata() {
  const post = await getPost();
  return {
    title: toPlainText(post.title),
    openGraph: { title: toPlainText(post.title), description: toPlainText(post.excerpt) },
  };
}

If you passed escapeAttr(...) there instead, the framework would escape your & again and you'd be back to &amp;.

A checker for pages you didn't build

You often find this bug on somebody else's site, or on a page whose template you can't easily read. This checker scans the raw HTML for share tags and reports two things: an entity that was escaped twice, and text left over after the content value, which is what a stray quote produces.

// check-head.mjs: flag share tags that were escaped twice or broken by a stray quote.
const SHARE = /^(og:|twitter:|description$)/;
const DOUBLE = /&amp;(amp|quot|lt|gt|apos|nbsp|#\d+|#x[0-9a-f]+);/i;

export function checkHead(html) {
  const problems = [];
  for (const [tag] of html.matchAll(/<meta\b[^>]*>/gi)) {
    const key = /(?:property|name)\s*=\s*"([^"]*)"/i.exec(tag)?.[1];
    if (!key || !SHARE.test(key)) continue;
    const m = /content\s*=\s*"([^"]*)"/i.exec(tag);
    if (!m) { problems.push({ key, issue: 'no double-quoted content' }); continue; }
    const rest = tag.slice(m.index + m[0].length).replace(/\/?>$/, '').trim();
    if (rest && !/^[\w:-]+\s*=\s*"[^"]*"(\s+[\w:-]+\s*=\s*"[^"]*")*$/.test(rest)) {
      problems.push({ key, issue: 'text after content: a stray quote probably cut the value', rest });
    }
    if (DOUBLE.test(m[1])) problems.push({ key, issue: 'double-encoded entity', value: m[1] });
  }
  return problems;
}

It's regex-based on purpose: it only has to read <meta> tags, and it should run anywhere with no install. Feed it the HTML the server sends, not what you see in DevTools, because the browser has already parsed and "fixed" the DOM by then:

// check.mjs
import { checkHead } from './check-head.mjs';
const html = await (await fetch(process.argv[2])).text();
console.table(checkHead(html));

node check.mjs https://example.com/menu

Tests

These run with node --test on Node 18 or later. They pin the behaviour that matters: escape once, don't re-escape, keep Urdu and emoji untouched, and catch both failures in the checker.

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { decodeEntities, toPlainText, escapeAttr, metaTag } from './share-text.mjs';
import { checkHead } from './check-head.mjs';

test('plain text from the CMS is escaped once', () => {
  assert.equal(metaTag('property', 'og:title', 'Fish & Chips: "Best" in town'),
    '<meta property="og:title" content="Fish &amp; Chips: &quot;Best&quot; in town">');
});

test('already-escaped text is not escaped again', () => {
  assert.equal(metaTag('property', 'og:title', 'Fish &amp; Chips'),
    '<meta property="og:title" content="Fish &amp; Chips">');
});

test('rich text loses its tags, keeps its words', () => {
  assert.equal(toPlainText('<p>Open <strong>9&ndash;5</strong>, Mon&#8211;Sat</p>'),
    'Open 9\u20135, Mon\u2013Sat');
});

test('Urdu and emoji pass through untouched', () => {
  assert.equal(toPlainText('کراچی کی بہترین چائے ☕'), 'کراچی کی بہترین چائے ☕');
});

test('checker finds double encoding', () => {
  const p = checkHead('<meta property="og:title" content="Fish &amp;amp; Chips">');
  assert.equal(p[0].issue, 'double-encoded entity');
});

test('checker finds a value cut short by a raw quote', () => {
  const p = checkHead('<meta property="og:title" content="The "Best" Chips">');
  assert.equal(p[0].issue, 'text after content: a stray quote probably cut the value');
});

The full test file has a few more cases (numeric and hex references, unknown entity names, a clean head that should produce no warnings).

Where to look when you see it

If a card shows entity codes, work backwards from the HTML:

View the raw response (curl -s URL | grep -i 'og:title'). If it says &amp;, the page is wrong, not the app.
Check whether the stored value already contains &. Rich-text editors and imports are the usual suspects.
Find every place that escapes on the way out. If a framework writes the tag, remove your own escaping.
Re-check the card in a preview tool. I use OG Scope, a free link preview checker I built, which shows the title and description as read from the live HTML next to estimated cards; its guide to what an Open Graph preview uses covers the other tags worth a look while you're there.

Then re-share. Apps that already cached the broken card may keep showing it for a while, so a fresh share, or the platform's own refresh tool where one exists, is part of the fix.

The pattern is worth remembering beyond share tags: decode once on the way in, keep plain text in the middle, escape once on the way out. Most "weird characters" bugs are a step that broke that rule.

A Job-Post Scorer That Never Touches Upwork: Pass, Weak or Skip With Reasons You Can Read, in Plain JavaScript

Abid Ali — Thu, 29 Oct 2026 06:41:12 +0000

Every few weeks someone in a freelancing group asks which Upwork auto-bidding tool is "safe". The honest answer is that the useful half of those tools doesn't need to be connected to anything, and the risky half is exactly the part people are paying for: the bit that clicks Apply and spends Connects while you're asleep.

On Digital Dialogue I wrote a longer piece on what an Upwork auto bidding bot should and shouldn't automate. The short version: Upwork's help page treats scripts, extensions and services that send requests, collect data or act faster than a person as bots, and auto-submit is the step that puts an account at risk. Scoring a job post and drafting notes, done away from the site, is a different thing.

So this post builds the safe half, as a developer would: a small, tested JavaScript module that scores job posts you copied by hand into a JSON file. It never opens Upwork, never needs a password, and never sends anything. Its output isn't a mysterious number from 0 to 100. It's one of three words, pass, weak or skip, with every reason written out, so you can disagree with it.

It's plain ES modules and Node's built-in test runner. No dependencies.

What the scorer is (and isn't)

The rules come straight from the checklist a careful freelancer already runs in their head:

Client signals. Is the payment method verified? Has this client hired before? What's their hire rate?
Skills. Do the skills in the post match work you've actually delivered?
Money. After the platform fee and the Connects for this one bid, what does the job leave per hour, and is that above your floor?
Competition. How many proposals are already in?
Phrases. Does the post ask you to move to WhatsApp, or do an unpaid test?

What it isn't: a feed reader, a scraper, a browser extension or a "watcher". You read the post on Upwork like a person, type the handful of fields into a file, and run a script on your own laptop. That's the whole interface, and it's deliberate.

The input: a job you typed yourself

One job is a plain object. Money is in integer cents, because a fee calculator that works in floating point eventually tells you something is worth $8.359999.

{
  "title": "Landing page in Next.js",
  "type": "fixed",
  "budgetCents": 15000,
  "estimatedHours": 16,
  "paymentVerified": true,
  "hires": 2,
  "hireRatePct": 50,
  "proposals": "20 to 50",
  "connects": 8,
  "skills": ["Next.js", "Tailwind CSS"],
  "description": "Simple landing page. Quick and easy for an expert."
}

Two fields are yours rather than the client's: estimatedHours (your estimate of the work) and the settings you score against. proposals is kept as the band Upwork shows ("Less than 5", "5 to 10", "50+"), and the code reads the lower bound.

The settings: your floor, your fee, your Connect price

export const DEFAULTS = {
  mySkills: [],
  floorHourlyCents: 1500,     // your own floor, e.g. $15.00/h (illustrative)
  feeBps: 1000,               // freelancer fee in basis points; 1000 = 10% (example, check your contract)
  connectPriceCents: 15,      // price per Connect at checkout (example; use the price you actually pay)
  maxConnects: 20,
  maxProposals: 20,
  minHireRatePct: 40,
  skipPhrases: ['whatsapp', 'telegram', 'outside upwork', 'off platform', 'pay after delivery', 'skype me'],
  weakPhrases: ['unpaid test', 'free sample', 'test task', 'long term for low', 'quick and easy'],
};

Every number here is an example, and I've labelled them that way in the code on purpose. The freelancer fee isn't one fixed percentage for everyone, and the price of a Connect is whatever checkout shows you. Put your own figures in a settings.json; the defaults only exist so the tests have something to run against.

The percentage is stored as basis points (1% = 100 bps). That keeps the fee an integer too, and 10000 is the only divisor you'll ever need.

The money rule: take-home per hour, after the fee and this bid

This is the rule that does the most work, so it gets the most care. Two small helpers first:

export function takeHomeCents(grossCents, feeBps) {
  // fee rounded half-up to the cent; take-home never goes negative
  const fee = Math.floor((grossCents * feeBps + 5000) / 10000);
  return Math.max(0, grossCents - fee);
}

export function connectsCostCents(connects, priceCents) {
  return Math.max(0, Math.round(connects)) * priceCents;
}

(x + 5000) / 10000 floored is half-up rounding in integer space. takeHomeCents(1005, 1000) gives a fee of 100.5 cents, rounded to 101, and a take-home of 904. Whether your platform rounds the same way is a question for its payment history, not for this post. The point is that the rounding is written down in one place where you can change it.

The Connects cost is counted against the job because the bid is a real cost of this job. DD's guide uses an example of $0.15 per Connect, where a 16-Connect proposal costs $2.40, and that exact figure is one of the tests below.

For a fixed-price job, the rule turns the budget into a rough hourly figure:

const net = takeHomeCents(job.budgetCents, cfg.feeBps) - bidCost;
const perHour = Math.floor(net / job.estimatedHours);
if (perHour < cfg.floorHourlyCents)
  add('rate', 'skip', `${usd(job.budgetCents)} over ${job.estimatedHours} h leaves about ${usd(perHour)}/h after the fee and Connects, under your floor.`);
else if (perHour * 10 < cfg.floorHourlyCents * 11)
  add('rate', 'weak', `About ${usd(perHour)}/h after costs: within 10% of your floor, no room for a revision round.`);

The "within 10%" check is written as perHour * 10 < floor * 11 so it stays in integers. A job that clears your floor by a few cents isn't a good job. It's a job where one extra round of changes puts you underwater, and the reason text says exactly that.

For hourly posts the rule checks the top of the client's range after the fee. If even the best case is under your floor, it's a skip. And if there's no budget at all, or a fixed budget but no hour estimate from you yet, the result is weak with a reason telling you to estimate first. Scoring a job you haven't sized is just guessing with extra steps.

The other rules

Client signals:

if (!job.paymentVerified && !(job.hires > 0)) add('client', 'skip', 'Payment not verified and no past hires.');
else if (!job.paymentVerified) add('client', 'weak', 'Payment not verified (has past hires).');
if (typeof job.hireRatePct === 'number' && job.hireRatePct < cfg.minHireRatePct)
  add('hire-rate', 'weak', `Hire rate ${job.hireRatePct}% is under your ${cfg.minHireRatePct}% line.`);

No verification and no history is a skip; either one alone is a reason to look harder, not a reason to stop. The 40% hire-rate line in the defaults is a placeholder for your own judgement, not a known good threshold.

Skills need normalising, because people type "Next.js", "NextJS" and "next js" for the same thing:

export function normalizeSkill(s) {
  return String(s).toLowerCase().replace(/\.js\b/g, 'js').replace(/[^a-z0-9+#]/g, '');
}

+ and # survive so C++ and C# don't collapse into "c". No overlap at all with your mySkills list is a skip. Fewer than half matching is weak.

Proposal bands keep the lower bound, since that's the number you're sure of:

export function parseProposalBand(band) {
  if (typeof band === 'number') return band;
  const s = String(band ?? '').toLowerCase().trim();
  if (!s) return null;
  if (/less than/.test(s)) return 0;
  const m = s.match(/(\d+)/);
  return m ? Number(m[1]) : null;
}

Phrases are matched with word boundaries, so "telegrams of support" doesn't trip the telegram rule, and runs of whitespace in a phrase match any whitespace in the post:

function hasPhrase(text, phrase) {
  const esc = phrase.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
  return new RegExp(`(^|[^a-z0-9])${esc}([^a-z0-9]|$)`).test(text);
}

Asking to move the conversation off the platform is a skip in the defaults. An unpaid test or "quick and easy" is only weak: sometimes a small paid test is perfectly reasonable, and the phrase is a prompt to read that part of the post again.

Verdicts without a hidden score

Each rule pushes { id, level, text } into a list. The verdict is simply the worst level present:

const LEVELS = { ok: 0, weak: 1, skip: 2 };

const worst = reasons.reduce((m, r) => Math.max(m, LEVELS[r.level]), 0);
const verdict = worst === 2 ? 'skip' : worst === 1 ? 'weak' : 'pass';
return { verdict, reasons, bidCostCents: bidCost };

I tried a weighted score first and threw it away. A number like 63 invites you to argue with the weights instead of with the facts. "Skip: $150 over 16 h leaves about $8.36/h after the fee and Connects" is something you can check in ten seconds, and if your estimate of 16 hours was wrong, you know exactly which input to change.

A tiny CLI

// node triage-cli.mjs jobs.json [settings.json]
import { readFileSync } from 'node:fs';
import { scoreJob, formatResult } from './triage.mjs';
const [jobsPath, settingsPath] = process.argv.slice(2);
const jobs = JSON.parse(readFileSync(jobsPath, 'utf8'));
const settings = settingsPath ? JSON.parse(readFileSync(settingsPath, 'utf8')) : {};
const order = { pass: 0, weak: 1, skip: 2 };
const scored = jobs.map((job) => ({ job, result: scoreJob(job, settings) }))
  .sort((a, b) => order[a.result.verdict] - order[b.result.verdict]);
for (const { job, result } of scored) console.log(formatResult(job, result) + '\n');

With three made-up jobs (illustrative, not real posts) the output looks like this:

PASS  Five-page WordPress site for a dental clinic  (bid $1.80)
      - nothing flagged

SKIP  Landing page in Next.js  (bid $1.20)
      - [skip] $150.00 over 16 h leaves about $8.36/h after the fee and Connects, under your floor.
      - [weak] 20+ proposals already.
      - [weak] Post mentions "quick and easy".

SKIP  Fix React Native build  (bid $1.50)
      - [skip] Payment not verified and no past hires.
      - [skip] Post mentions "whatsapp".

Passes first, then weak, then skip. You read the passes properly and write those proposals by hand. That's the order DD's guide recommends too: score, draft only the passes, then open the job on Upwork, paste your edited text, answer the questions and click Submit yourself.

Tests

The test file uses node:test and node:assert/strict. A few of them:

import test from 'node:test';
import assert from 'node:assert/strict';
import { scoreJob, parseProposalBand, takeHomeCents, connectsCostCents } from './triage.mjs';

const me = { mySkills: ['WordPress', 'PHP', 'Next.js', 'React'], floorHourlyCents: 1500, feeBps: 1000, connectPriceCents: 15 };
const good = { title: 'Clinic site', type: 'fixed', budgetCents: 60000, estimatedHours: 24, paymentVerified: true, hires: 6,
  hireRatePct: 70, proposals: '10 to 15', connects: 12, skills: ['WordPress', 'PHP'], description: 'Five pages.' };

test('a clean post passes with no reasons', () => {
  const r = scoreJob(good, me);
  assert.equal(r.verdict, 'pass');
  assert.deepEqual(r.reasons, []);
  assert.equal(r.bidCostCents, 180);
});

test('take-home uses integer cents and half-up fee rounding', () => {
  assert.equal(takeHomeCents(10000, 1000), 9000);
  assert.equal(takeHomeCents(1005, 1000), 904);   // fee 100.5 -> 101
  assert.equal(connectsCostCents(16, 15), 240);   // the $2.40 example
});

test('close to the floor is weak, not skip', () => {
  // $285 - 10% fee - $1.80 Connects = $254.70 over 16 h = $15.91/h: above a $15 floor, but within 10% of it
  const r = scoreJob({ ...good, budgetCents: 28500, estimatedHours: 16 }, me);
  assert.equal(r.verdict, 'weak');
  assert.equal(r.reasons[0].id, 'rate');
});

test('unverified payment with no hires, or off-platform contact, is a skip', () => {
  assert.equal(scoreJob({ ...good, paymentVerified: false, hires: 0 }, me).verdict, 'skip');
  assert.equal(scoreJob({ ...good, paymentVerified: false, hires: 3 }, me).verdict, 'weak');
  assert.equal(scoreJob({ ...good, description: 'Add me on WhatsApp\nthanks' }, me).verdict, 'skip');
  // word boundaries: "telegrams" is not "telegram"
  assert.equal(scoreJob({ ...good, description: 'telegrams of support' }, me).verdict, 'pass');
});

test('proposal bands keep the lower bound', () => {
  assert.equal(parseProposalBand('Less than 5'), 0);
  assert.equal(parseProposalBand('5 to 10'), 5);
  assert.equal(parseProposalBand('50+'), 50);
});

The full file has 11 tests, covering hourly ranges, partial skill overlap, missing budgets and the formatter as well. Run them with:

node --test

Things I deliberately left out

Fetching jobs. It's tempting to "just" pull the feed. That's the part DD's article and Upwork's own help page are clear about: background polling, timed refreshes and scraping are patterns that get accounts flagged. If you want alerts, use the saved searches Upwork gives you, and type the five or six fields you need. It takes a minute per post, and that minute is also when you actually read it.

Writing the proposal. A scorer can tell you a post is worth your time. It can't tell the client what you did on a similar project, because only you know that. Keep a small bank of real project notes and write the first two lines for the client in front of you.

A single magic threshold. Your floor, your fee and your Connect price change. They live in a settings file, not in the code, and the reasons always print the numbers they used.

Spending decisions across a week. One bid's cost is in the per-hour maths, but whether you can afford twenty bids this week is a budgeting question. The free Upwork Connects calculator on DD works out the dollar cost of a batch of proposals and your cost per reply, interview and contract, which is the right next number to look at once the scorer has trimmed the list.

Wrapping up

The safest automation for a freelancer is the kind that never logs in. A JSON file, a few honest rules, integer cents and a verdict that shows its working: that's enough to stop you spending Connects on posts you'd have skipped if you'd done the maths. Then you open the passes, read them properly, and send them yourself.

I'm Abid Ali, a freelance full-stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I write practical freelancing guides and build small free calculators on Digital Dialogue.

A Random Button That Doesn't Feel Broken: Unbiased Picks, No Instant Repeats and Shuffle Bags in JavaScript

Abid Ali — Wed, 28 Oct 2026 07:23:58 +0000

Meme Tap, the soundboard I built, has a page called Random. There is one button on it, Roll, and every tap pulls one sound button from the whole library: a title, a category, a play button. The page copy makes one small promise: roll again skips the one you just heard when it can.

That promise exists because truly random picks feel broken. If you roll twice and hear the same buzzer twice, you don't think "fair coin, these things happen." You think the button didn't work. People are very good at noticing repeats and very bad at believing they're chance, and a random button has to be built for people, not for a statistics textbook.

This post is the toolkit I'd reach for when building any "surprise me" button, whether it's sounds, quotes, recipes or quiz questions: a correct integer pick, an unbiased version with crypto, "anything but the last one", a short history window, a shuffle bag, and a seeded generator so all of it can be tested. Plain JavaScript modules, no libraries, and every function here has a passing node --test file behind it.

Step 1: get the integer right

Almost every random-pick bug starts with the one-liner:

const pick = items[Math.round(Math.random() * (items.length - 1))];

It looks reasonable and it's quietly unfair. Math.round gives the first and last items half the chance of everything else, because only half a step of the range rounds to 0 and only half rounds to the top. The correct version floors a value in [0, n):

export function indexFrom(rand, n) {
  return Math.floor(rand() * n);
}

const pick = items[indexFrom(Math.random, items.length)];

I pass the random source in as a function. In production it's Math.random; in tests it's a seeded generator (more on that below). That one parameter is what makes the rest of this post testable.

Step 2: when you want crypto, avoid modulo bias

Math.random() is fine for a soundboard. It's not suitable for anything where someone gains by predicting the next value: giveaways, raffles, shuffling a deck for real money. For those you want crypto.getRandomValues, which is available in every modern browser and in Node as globalThis.crypto.

The trap with crypto is the obvious conversion: take a 32-bit integer and do % n. Unless n divides 2^32 exactly, the low values come up slightly more often, because the last partial block of the range wraps around onto them. The fix is rejection sampling: throw away values from that partial block and draw again.

export function randomIndex(n, cryptoObj = globalThis.crypto) {
  if (!Number.isInteger(n) || n <= 0) throw new RangeError("n must be a positive integer");
  const limit = Math.floor(0x100000000 / n) * n; // largest multiple of n below 2^32
  const buf = new Uint32Array(1);
  for (;;) {
    cryptoObj.getRandomValues(buf);
    if (buf[0] < limit) return buf[0] % n;
  }
}

The loop almost never runs twice for small n, but it makes the result exactly uniform. The cryptoObj parameter is there so a test can hand in a fake and prove the rejection happens: feed it 0xffffffff (which is past the last full multiple of 3) followed by 5, and it should return 5 % 3, having drawn twice.

Step 3: "anything but the last one"

This is the rule the Random page states, and it has a neat implementation that stays uniform. Instead of rolling and re-rolling until you get something different (which works, but has no upper bound on attempts and reads badly), pick from n - 1 slots and skip over the last index:

export function pickNotLast(n, last, rand = Math.random) {
  if (n <= 1) return 0;                       // a pool of one has to repeat
  if (last == null || last < 0 || last >= n) return indexFrom(rand, n);
  const i = indexFrom(rand, n - 1);
  return i >= last ? i + 1 : i;
}

If the last pick was index 2 out of 5, the draw is over {0, 1, 2, 3} and anything from 2 up shifts by one, giving {0, 1, 3, 4}, each with exactly a quarter of the chance. One draw, always.

Note the n <= 1 line. That's the "when it can" in the page copy. If a category or a filtered search only has one clip, the honest answer is to play it again rather than loop forever or show an error.

Step 4: a short memory instead of a one-item memory

On a small pool, "not the last one" isn't enough. With four sounds you can get A, B, A, B, A and it still feels stuck. A history window blocks the last few picks, as long as the pool is big enough to allow it:

export function createRoller(items, { windowSize = 1, rand = Math.random } = {}) {
  const recent = [];
  return function roll() {
    const n = items.length;
    if (n === 0) return undefined;
    const keep = Math.min(windowSize, n - 1);   // never block the whole pool
    while (recent.length > keep) recent.shift();
    const blocked = new Set(recent);
    const open = [];
    for (let i = 0; i < n; i++) if (!blocked.has(i)) open.push(i);
    const pick = open[indexFrom(rand, open.length)];
    recent.push(pick);
    while (recent.length > keep) recent.shift();
    return items[pick];
  };
}

Math.min(windowSize, n - 1) is the important line. Ask for a window of 5 on a pool of 2 and it quietly becomes a window of 1, so the roller alternates instead of running out of options.

Building the open array is O(n) per roll. For a few hundred items that's nothing. For a big library you wouldn't hold every item in the browser anyway, which brings us to where the pick should happen.

Step 5: shuffle bags, for "I want to hear everything"

Sometimes the requirement is stronger: in a quiz round, a playlist or a classroom game, people expect every item to come up once before anything repeats. That's a shuffle bag. Shuffle the indexes with Fisher–Yates, hand them out one by one, and reshuffle when the bag is empty.

export function shuffle(arr, rand = Math.random) {
  for (let i = arr.length - 1; i > 0; i--) {
    const j = indexFrom(rand, i + 1);
    [arr[i], arr[j]] = [arr[j], arr[i]];
  }
  return arr;
}

export function createBag(items, rand = Math.random) {
  let bag = [];
  let last;
  return function next() {
    if (items.length === 0) return undefined;
    if (bag.length === 0) {
      bag = shuffle(items.map((_, i) => i), rand);
      // we pop from the end: if the first pop would repeat the last item, swap it away
      if (items.length > 1 && bag[bag.length - 1] === last) {
        const j = indexFrom(rand, bag.length - 1);
        [bag[bag.length - 1], bag[j]] = [bag[j], bag[bag.length - 1]];
      }
    }
    last = bag.pop();
    return items[last];
  };
}

Two details matter. First, the shuffle must be indexFrom(rand, i + 1), not indexFrom(rand, n). Swapping with any position on every step is the classic "naive shuffle", and it produces some orders more often than others. Second, there's a seam between rounds: the last item of one bag can be the first of the next, which is exactly the repeat you were trying to avoid. The swap after reshuffling fixes it without disturbing anything else.

Step 6: seed it, then test it

Randomness is where untested code goes to hide, because a wrong result looks like bad luck. The fix is a tiny seeded generator. mulberry32 is a few lines, fast, and good enough for tests and demos (not for security):

export function mulberry32(seed) {
  let a = seed >>> 0;
  return function next() {
    a = (a + 0x6d2b79f5) >>> 0;
    let t = a;
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}

Now the tests are deterministic. Here is the one I care about most, the shuffle bag across hundreds of seeds:

import test from "node:test";
import assert from "node:assert/strict";
import { createBag, mulberry32 } from "./roll.mjs";

test("createBag plays everything once per round with no repeat at the seam", () => {
  const items = ["a", "b", "c", "d", "e"];
  for (let seed = 1; seed < 300; seed++) {
    const next = createBag(items, mulberry32(seed));
    const out = Array.from({ length: 25 }, next);
    for (let r = 0; r < 5; r++) {
      assert.deepEqual(out.slice(r * 5, r * 5 + 5).sort(), items);
    }
    for (let k = 1; k < out.length; k++) {
      assert.notEqual(out[k], out[k - 1], `seed ${seed} at ${k}`);
    }
  }
});

Without the seam fix, this fails within the first handful of seeds. That's the point of looping over seeds: it turns "rare" into "certain".

The rest of the file checks that randomIndex stays in range and covers every value, that it redraws on a value past the last full multiple, that pickNotLast never repeats over 40,000 rolls and lands each of five counts within a loose band around the expected 8,000, that the history window never returns either of the last two picks, and that shuffle keeps every element. Seven tests, all passing on Node 20 with node --test.

A note on that distribution test: with a fixed seed it's not a statistical proof, it's a guard against the off-by-one mistakes from Step 1. If you swap Math.floor for Math.round, the counts for the first and last index drop to roughly half and the test fails loudly.

Where the pick should happen

For a large library of clips, don't ship the whole list to the browser just to roll. Let the server pick and send one item back, and have the client send the id it just played so the server can exclude it:

const res = await fetch(`/api/random?exclude=${encodeURIComponent(lastId ?? "")}`);
const clip = await res.json();

On the database side, avoid ORDER BY random() LIMIT 1 on a big table: it sorts every row to throw all but one away. Cheaper options include counting the eligible rows and fetching one at a random offset, or picking a random id in the known range and taking the first row at or after it (fast, but slightly favours ids after gaps). The exclude parameter is the server-side twin of pickNotLast.

The button itself

A few small UI choices make a random button feel solid:

Disable while loading, not before. Set aria-busy and ignore taps until the new clip arrives, so a double tap doesn't fire two requests and leave the page showing one while playing the other.
Announce the result. Put the new title in an aria-live="polite" region. A screen reader user pressing Roll otherwise hears nothing until they go hunting.
Don't autoplay the pick. Show it and let the person press Play. A roll that blasts audio is a surprise in the wrong way, and browsers may block it anyway without a fresh user gesture.
Let people keep a good one. A random roll is a discovery tool. Once someone finds a clip they like, a favourite or a copy-link button turns that luck into something they can find again.

If you want to see the behaviour from the user's side, tap Roll a few times on the Meme Tap Random page. The whole thing is a few small, well-tested functions and one honest rule: no instant repeats when the pool allows it.

I'm Abid Ali, a freelance full-stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I built Meme Tap, a free meme soundboard and meme maker that runs in the browser.

Money Math for a Freelance Fee Calculator in JavaScript: Integer Cents, Rounding on Purpose and Currency Symbols That Don't Pretend to Convert

Abid Ali — Tue, 27 Oct 2026 09:19:39 +0000

A fee calculator looks like the easiest thing you can put on a website. Take an amount, subtract a percentage, subtract a withdrawal fee, print the result. I've built a few of these for Digital Dialogue, my freelancing blog, and every one of them was "three subtractions" for about an hour, until the numbers started coming out one cent wrong.

One cent sounds harmless. It isn't, for two reasons. People compare your number with the one in their payment history, and when it doesn't match they stop trusting everything else on the page. And a rate calculator that rounds the wrong way can tell someone to charge a rate that leaves them slightly short of the goal they typed in.

This post is the money layer I'd write today: integer cents, percentages as basis points, rounding you choose on purpose, a gross-up that never undershoots, and formatting that changes the symbol without pretending to convert anything. It's plain JavaScript with tests for Node's built-in runner. It's a generic version of the pattern, not a copy of the production source.

Why floats bite

JavaScript numbers are binary floating point. Most decimal fractions don't have an exact binary form, so they're stored as the nearest value that does:

0.1 + 0.2      // 0.30000000000000004
1.15 * 100     // 114.99999999999999
19.99 * 100    // 1998.9999999999998

The last two are the dangerous ones, because converting to cents is exactly what people do first. Math.floor(1.15 * 100) is 114. Somebody types $1.15 and your calculator quietly works with $1.14.

toFixed(2) at the end doesn't save you either. It rounds the final display, but by then the error may have been multiplied, subtracted and compared against a threshold along the way.

The fix is old and boring: keep money as an integer number of the smallest unit (cents, paisa) and never let a float near the arithmetic. Integers are exact in JavaScript up to Number.MAX_SAFE_INTEGER, which is far beyond any freelance invoice.

Parse strings, not numbers

The trick is to go from the input string to cents without ever building the float 1.15. Split on the decimal point and treat each side as an integer:

// money.mjs
export function parseAmount(input) {
  const s = String(input).trim().replace(/,/g, "");
  const m = /^(\d+)(?:\.(\d{0,2}))?$/.exec(s);
  if (!m) return null;                       // not a plain positive amount
  const whole = Number(m[1]);
  const frac = Number((m[2] ?? "").padEnd(2, "0"));
  const cents = whole * 100 + frac;
  return Number.isSafeInteger(cents) ? cents : null;
}

"1.15" becomes 1 * 100 + 15 = 115. "1,250.5" becomes 125050. Anything with three decimal places, a minus sign or letters returns null, and the form shows an error instead of guessing. Stripping commas is a deliberate choice for an English-language form. If your audience types 1.250,50, you need a locale-aware parser, and that's a different post.

Read the value from input.value, which is always a string, rather than input.valueAsNumber, which has already turned it into a float.

Percentages as basis points

A percentage has the same problem. 12.5% as 0.125 is fine, but 10.4% as 0.104 isn't exact. So store percentages as basis points: hundredths of a percent, as integers. 10% is 1000, 12.5% is 1250, 100% is 10000.

export function parsePercent(input) {
  const s = String(input).trim();
  const m = /^(\d{1,3})(?:\.(\d{0,2}))?$/.exec(s);
  if (!m) return null;
  const bp = Number(m[1]) * 100 + Number((m[2] ?? "").padEnd(2, "0"));
  return bp <= 10000 ? bp : null;            // 0% to 100%
}

Now "a percentage of an amount" is integer times integer divided by 10,000. The multiplication is exact. The division is where you decide how to round.

Round on purpose

There's no neutral rounding. You pick one, and you should pick it per calculation:

For a fee shown as an estimate, round half up to the nearest cent. It's what most people expect when they check by hand.
For a minimum rate or price floor, round up, always. A floor that is a cent too low isn't a floor.
For what someone keeps, never show a negative number. If the costs are bigger than the amount, say so in words.

Half-up rounding with integers, for non-negative amounts:

// cents * bp / 10000, rounded half up
export function percentOf(cents, bp) {
  return Math.floor((cents * bp + 5000) / 10000);
}

Adding half the divisor before flooring is the integer version of "add 0.5 and round down". percentOf(1005, 1000) is 10% of $10.05, which is $1.005, and it rounds to 101 cents.

Platforms do their own rounding, and they don't publish every detail of it. That's fine. Your job isn't to reproduce their ledger to the cent. It's to be consistent, to say "estimate" on the page, and to tell people where the exact number lives. On Digital Dialogue's calculators that's the contract details and transaction history on the platform itself.

The order of deductions matters

A take-home calculator usually has three kinds of cost:

The platform's service fee, a percentage of what you bill.
A flat withdrawal or transfer fee from your payment method.
A percentage cost from your bank or provider, such as a conversion margin.

The question is what the third percentage applies to. On the gross? On what's left after the service fee? After the flat fee? Each is defensible, and each gives a different answer. Pick one, write it on the page next to the field, and implement exactly that. The order I use, and the one the free Upwork fee calculator on Digital Dialogue explains under its "Additional costs" field, applies the percentage to what's left after the service fee:

export function takeHome({ grossCents, feeBp, flatCents = 0, extraBp = 0 }) {
  const fee = percentOf(grossCents, feeBp);
  const afterFee = grossCents - fee;
  const extraPct = percentOf(afterFee, extraBp);
  const net = afterFee - flatCents - extraPct;
  return {
    fee, afterFee, extraPct,
    net: Math.max(net, 0),
    shortfall: net < 0 ? -net : 0,
    effectiveBp: grossCents === 0
      ? null
      : Math.round(((grossCents - Math.max(net, 0)) * 10000) / grossCents),
  };
}

A worked example with illustrative numbers: a $500 milestone, a 10% service fee and a $2 flat withdrawal fee. The fee is 5000 cents, 45000 is left, minus 200 is 44800. The effective deduction is 1040 basis points, so 10.4%. That last number is the one I find most useful on the page, because it shows the real cut in a single figure, and it's always a bit higher than the headline fee.

shortfall exists so the UI can say "These costs are more than the amount by $1.50" instead of showing -$1.50. Negative take-home pay isn't a result. It's a sign that an input is wrong.

effectiveBp returns null for a zero amount instead of dividing by zero and getting NaN. The UI decides what to show for null. Don't let NaN% reach a screen.

Gross-up: the calculation people get wrong by hand

The reverse question is more useful for pricing: what do I need to bill so that I keep X? The common mistake is to add the fee on top. If you want to keep $900 and the fee is 10%, adding 10% gives $990. The platform takes 10% of $990, which is $99, and you keep $891.

The correct move is to divide by (1 − fee). $900 / 0.9 is $1,000, the fee is $100, and you keep $900. In integers, rounding up:

export function grossUp(targetCents, feeBp) {
  if (feeBp >= 10000) return null;
  let g = Math.ceil((targetCents * 10000) / (10000 - feeBp));
  while (g > 0 && g - 1 - percentOf(g - 1, feeBp) >= targetCents) g--;
  while (g - percentOf(g, feeBp) < targetCents) g++;
  return g;
}

The two while loops look paranoid, and they are. The formula is exact in real numbers, but the fee is then rounded half up to a cent, so the formula's answer can be one cent off either way. The loops check the actual result with the same percentOf the take-home function uses and nudge until the answer is the smallest amount that still leaves the target. In practice they run zero or one time. The test below checks thousands of combinations.

grossUp(70000, 1500) returns 82353: to keep $700 with a 15% fee you bill $823.53. Divide by hand and you get $823.529..., and rounding that to the nearest cent would give $823.53 here. With other numbers it rounds down, and you fall a cent short. Rounding up removes the question.

Formatting: symbol, not conversion

Most freelance calculators let you pick a currency. Be clear about what that does. If you don't have live exchange rates, and for an estimate you usually shouldn't pretend to, the selector should change the symbol and format only. Then say so under the field, the way the calculators on Digital Dialogue do: "Changes the symbol and format only. No exchange rates are applied."

Intl.NumberFormat does the formatting:

export function formatMoney(cents, currency, locale = "en-US") {
  return new Intl.NumberFormat(locale, {
    style: "currency", currency, currencyDisplay: "narrowSymbol",
  }).format(cents / 100);
}

Dividing by 100 at the very end is fine, because it's only for display. A few things I learned while testing this on Node 20:

With the default currencyDisplay, en-US shows Canadian dollars as CA$1,234.50 and Pakistani rupees as PKR 1,234.50. narrowSymbol gives $1,234.50 and Rs 1,234.50. Narrow is friendlier, but two currencies can look identical, so put the currency code somewhere near the result.
The space in Rs 1,234.50 is a non-breaking space (U+00A0), not a normal one. My first test failed on exactly that. Don't string-compare formatted output in tests or code unless you account for it, and never parse a formatted string back into a number.
Locale changes grouping, not just symbols. en-IN formats 123456.5 rupees as ₹1,23,456.50. If you hard-code "en-US", everyone gets Western grouping. That may be what you want. Just make it a decision.
Minor units differ by currency. All the currencies above use two decimal places, so cents work. If you add one that uses zero or three, store "minor units" per currency and read the count from resolvedOptions().maximumFractionDigits.

Tests

The tests are where this approach pays off, because every expected value is an exact integer:

// money.test.mjs (run with: node --test)
import { test } from "node:test";
import assert from "node:assert/strict";
import { parseAmount, percentOf, takeHome, grossUp, formatMoney } from "./money.mjs";

test("parses amounts without float drift", () => {
  assert.equal(parseAmount("19.99"), 1999);
  assert.equal(parseAmount("1.15"), 115);
  assert.equal(parseAmount("1,250.5"), 125050);
  assert.equal(parseAmount("1.999"), null);
});

test("fee, flat cost, then percentage on the remainder", () => {
  const r = takeHome({ grossCents: 50000, feeBp: 1000, flatCents: 200 });
  assert.equal(r.net, 44800);
  assert.equal(r.effectiveBp, 1040);
});

test("never shows a negative take-home", () => {
  const r = takeHome({ grossCents: 500, feeBp: 1000, flatCents: 600 });
  assert.equal(r.net, 0);
  assert.equal(r.shortfall, 150);
});

test("gross-up never lands below the target", () => {
  for (let t = 1; t < 20000; t += 7) {
    for (const bp of [0, 500, 1000, 1250, 1500]) {
      const g = grossUp(t, bp);
      assert.ok(g - percentOf(g, bp) >= t);         // enough
      assert.ok(g - 1 - percentOf(g - 1, bp) < t);  // and the smallest such amount
    }
  }
});

test("currency changes the symbol only", () => {
  assert.equal(formatMoney(123450, "PKR"), "Rs\u00a01,234.50");
});

All of these pass on Node 20. The gross-up loop is the one I'd keep if I could keep only one, because it tests a property ("enough, and the smallest amount that is enough") instead of a handful of examples I picked myself.

What to put on the page

The arithmetic is half the job. The other half is honesty around it:

Label the result as an estimate and say which inputs it depends on.
Put the default fee in the field, but tell people to replace it with the one on their own offer. Upwork, for example, shows the fee per contract and says it can range from 0% to 15%.
Say what isn't included. Tax is the big one.
Show the breakdown, not just the final number. People trust a result they can follow line by line.

If you want to see these choices as a finished tool, the Digital Dialogue Upwork fee calculator handles hourly and fixed-price contracts, an editable service fee, flat and percentage withdrawal costs, and a currency picker that only changes the symbol. It shows a worked example as well.

The short version: parse strings to integer cents, keep percentages as basis points, choose your rounding per calculation, round floors up, never show negative money, and format only at the edge.

Keyboard Hotkeys for a Browser Soundboard: KeyboardEvent.code, Layout-Proof Labels and Not Hijacking the Search Box

Abid Ali — Sun, 25 Oct 2026 18:34:42 +0000

A soundboard on a phone is a grid of buttons you tap. A soundboard on a laptop, during a stream or a call, is something you want to fire without looking: press Q, hear the buzzer. Streamers usually solve this in OBS with a hotkey per media source, but plenty of people just keep a browser tab open and wish the page itself listened to the keyboard.

Adding that to a web soundboard looks like a five-minute job. A keydown listener, a map from letters to buttons, done. Then someone on a French keyboard reports that the layout is scrambled, someone typing in the search box triggers six sounds, holding a key machine-guns a clip, and a screen reader user loses their own shortcuts.

This post is the hotkey layer I'd write today, in plain JavaScript so it drops into React, Svelte or a static page. The code is a generic pattern I tested with Node's test runner, not a copy of the production source of Meme Tap, the meme soundboard I built.

`key` or `code`?

KeyboardEvent gives you two names for the key that was pressed:

e.key is the character the key produces on the user's layout: "q", "a", "Q" with Shift, "й" on a Russian layout.
e.code is the physical position: "KeyQ" is the key to the right of Tab on every keyboard, whatever is printed on it.

For text shortcuts like "press ? for help", key is right, because you mean the character. For a soundboard grid, you mean a position. The top-left button should be the top-left key whether the user types on QWERTY, AZERTY or QWERTZ, so the grid shape on screen matches the shape under their fingers. That's code.

// hotkeys.js
export const SLOT_CODES = [
  "Digit1","Digit2","Digit3","Digit4","Digit5","Digit6","Digit7","Digit8","Digit9","Digit0",
  "KeyQ","KeyW","KeyE","KeyR","KeyT","KeyY","KeyU","KeyI","KeyO","KeyP",
  "KeyA","KeyS","KeyD","KeyF","KeyG","KeyH","KeyJ","KeyK","KeyL",
];

const CODE_TO_SLOT = new Map(SLOT_CODES.map((code, i) => [code, i]));

Twenty-nine slots: the number row and two letter rows. I leave out the bottom row because Z, X and C sit right next to Ctrl and Cmd, and people hit them by accident while copying and pasting.

When not to play anything

Most of the bugs live here. A key press should not fire a sound when:

A modifier is held. Ctrl+R reloads, Cmd+W closes the tab, Alt combinations are menu shortcuts on Windows and type characters on a Mac. Never swallow those.
The user is typing. Search inputs, comment boxes, contenteditable regions. A range slider or a checkbox is fine, though, so check the input type rather than bailing on every <input>.
An IME is composing. People typing Japanese, Chinese or Korean go through an input method editor. During composition, e.isComposing is true, and some browsers report keyCode 229 on the first event. Those key presses belong to the IME.
Someone else already handled it. If a modal or a component called preventDefault(), respect that.

export function isTypingTarget(el) {
  if (!el || typeof el !== "object") return false;
  if (el.isContentEditable) return true;
  const tag = (el.tagName || "").toLowerCase();
  if (tag === "textarea" || tag === "select") return true;
  if (tag === "input") {
    const nonText = ["button","checkbox","radio","range","color","file","submit","reset","image"];
    return !nonText.includes((el.type || "text").toLowerCase());
  }
  return false;
}

export function slotForEvent(e) {
  if (e.defaultPrevented || e.isComposing || e.keyCode === 229) return null;
  if (e.ctrlKey || e.metaKey || e.altKey) return null;
  if (isTypingTarget(e.target)) return null;
  const slot = CODE_TO_SLOT.get(e.code);
  return slot === undefined ? null : slot;
}

Shift is deliberately allowed. You can use it later as a "stop instead of play" modifier, and blocking it means a user with Caps Lock habits gets nothing.

keyCode is deprecated, but the 229 check is still the documented way to catch the first composition event in some browsers, so it stays.

Key repeat: one press, one sound

Hold a key down and the operating system starts sending repeated keydown events after a short delay. For a soundboard, that turns a hold into a stutter. You have two choices:

function onKeyDown(e) {
  const slot = slotForEvent(e);
  if (slot === null) return;
  e.preventDefault();          // stop "/" opening find, Space scrolling, etc.
  if (e.repeat) return;        // ignore auto-repeat
  playSlot(slot, { restart: true });
}

window.addEventListener("keydown", onKeyDown);

e.repeat is true for every repeated event, so a hold plays once. If you want "hold to loop", start playback on the first keydown and stop it on keyup for the same code instead.

Call preventDefault() only once you know the key maps to a slot. Calling it for every key breaks Tab navigation and browser shortcuts for everyone.

Show the right letter on each button

If a French user's KeyQ prints A, the label on the top-left button should say A. The Keyboard Map API can tell you, in Chromium-based browsers:

export function labelFor(code, layoutMap) {
  const fromLayout = layoutMap?.get?.(code);
  if (fromLayout) return fromLayout.toUpperCase();
  if (code.startsWith("Digit")) return code.slice(5);
  if (code.startsWith("Key")) return code.slice(3);
  return code;
}

async function getLayoutMap() {
  try {
    return (await navigator.keyboard?.getLayoutMap?.()) ?? null;
  } catch {
    return null; // e.g. inside a cross-origin iframe
  }
}

Firefox and Safari don't ship navigator.keyboard, so the fallback prints the US label. That's honest enough: the position is still correct, only the printed letter might differ. If that bothers you, update the label after the first real key press, since e.key tells you what that position produces for this user.

Make the shortcut discoverable and accessible

Hotkeys are invisible by default. A few small things fix that:

<button class="sound" data-slot="10" aria-keyshortcuts="Q">
  <span class="name">Buzzer</span>
  <kbd class="hint" aria-hidden="true">Q</kbd>
</button>

aria-keyshortcuts tells assistive tech the button has a shortcut. Keep its value in sync with the label you computed.
A visible <kbd> hint, shown on devices with a fine pointer only, so phones don't get a grid of meaningless letters:

.hint { display: none; }
@media (hover: hover) and (pointer: fine) {
  .hint { display: inline-block; }
}

A toggle. Single-key shortcuts are a known problem for speech-input users and for screen reader users whose own commands use single letters. WCAG 2.1 (success criterion 2.1.4) asks that character-key shortcuts can be turned off or remapped, or only work when a component has focus. A "Keyboard shortcuts" switch, stored in localStorage, covers it:

const enabled = () => localStorage.getItem("hotkeys") !== "off";

function onKeyDown(e) {
  if (!enabled()) return;
  // ...as before
}

Another option is to listen on the grid container instead of window, so shortcuts only work once the grid has focus. That's the safest default for a page that is mostly a board.

Paging: more sounds than keys

A category page might have hundreds of buttons, and you have 29 keys. I map the keys to what is visible, not to the whole list. When the user scrolls or loads more, the slots shift to the first 29 buttons on screen. An IntersectionObserver that keeps an ordered list of visible buttons does this without measuring on every scroll:

const visible = new Set();
const io = new IntersectionObserver((entries) => {
  for (const en of entries) {
    en.isIntersecting ? visible.add(en.target) : visible.delete(en.target);
  }
  relabel();
}, { threshold: 0.6 });

document.querySelectorAll("button.sound").forEach((b) => io.observe(b));

function relabel() {
  const ordered = [...document.querySelectorAll("button.sound")].filter((b) => visible.has(b));
  ordered.forEach((b, i) => {
    const code = SLOT_CODES[i];
    b.dataset.slot = code ? i : "";
    b.querySelector(".hint").textContent = code ? labelFor(code, layoutMap) : "";
    code ? b.setAttribute("aria-keyshortcuts", labelFor(code, layoutMap)) : b.removeAttribute("aria-keyshortcuts");
  });
}

Changing the labels as the page scrolls is fine for sighted keyboard users, who see the letters move. For favourites or a pinned "my board" view, fixed slots are kinder, because muscle memory starts to matter.

Testing it

None of this needs a browser to test. slotForEvent takes plain objects, so Node's built-in runner covers the cases that bit me:

import { test } from "node:test";
import assert from "node:assert";
import { slotForEvent } from "./hotkeys.js";

const ev = (o) => ({ code: "KeyQ", target: { tagName: "BODY" }, ...o });

test("AZERTY 'a' on KeyQ is still slot 10", () =>
  assert.equal(slotForEvent(ev({ key: "a" })), 10));
test("ignores IME composition", () =>
  assert.equal(slotForEvent(ev({ isComposing: true })), null));
test("ignores search box, allows range slider", () => {
  assert.equal(slotForEvent(ev({ target: { tagName: "INPUT", type: "search" } })), null);
  assert.equal(slotForEvent(ev({ target: { tagName: "INPUT", type: "range" } })), 10);
});
test("leaves Ctrl shortcuts alone", () =>
  assert.equal(slotForEvent(ev({ ctrlKey: true })), null));

Where a page hotkey stops being enough

Page hotkeys only work while the tab has focus. The moment you click into a game or OBS, the browser stops receiving key presses, and no web API changes that for good reasons. If you need sounds while another app is focused, download the clips and load them into the tool that owns global hotkeys. The Meme Tap guide to a podcast and live stream soundboard in OBS walks through that setup, with a media source per clip and a hotkey on each.

For everything else, a focused tab with good hotkeys is surprisingly pleasant. Physical positions with code, no firing while typing or composing, one sound per press, labels from the real layout, and a switch to turn it all off.

I'm Abid Ali, a freelance full-stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I built Meme Tap, a free meme soundboard and meme maker that runs in the browser.

Link Previews for User-Generated Pages: Profiles, Moderation and the Cards You Didn't Plan For

Abid Ali — Sat, 24 Oct 2026 07:18:04 +0000

If your app has public profiles, listings, portfolios or posts, every one of those pages is a link someone will paste into WhatsApp, LinkedIn or Slack. The card that appears is built from text and images your users typed in. That's the point of the feature, and it's also where things get uncomfortable: a display name that says "Official Support", a profile image swapped after it was approved, a private account whose old card keeps circulating, a username that changes hands.

Most link preview advice assumes the person writing the tags is the site owner. On a user-generated page, you're writing the rules and your users are writing the content. This post is the setup I use in Next.js (App Router) to keep those cards useful without letting them become a liability.

What actually goes wrong

When I review a platform with user pages, the same handful of problems come up:

Raw user URLs in og:image. The profile stores an image URL from anywhere, and the page puts it straight into the share tag. You don't control the file size, the content type, or whether the file at that address changes next week.
User text with no framing. The og:title is just the display name. Someone named "Bank Customer Care" gets a card that looks like it came from a bank, sitting under your domain.
One card for every state. Private, suspended, pending review and removed accounts all render the same metadata as a public one, because generateMetadata was written for the happy path.
Renamed handles. A user changes @studio-amna to @amna-designs. Old links break, or worse, someone else claims the old handle and inherits every link that was ever shared.
Takedowns that don't take. A moderator removes a profile, but the page, its metadata and its share image stay cached on your side for hours.

None of this shows up in a design review, because the designs use a nice sample profile. It shows up when a real link is shared.

Step 1: decide the card for every state

I start with a pure function that takes the stored profile and returns the card. No framework imports, so it's easy to test.

// lib/share-card.ts
export const SITE = "https://www.example.com";
export const SITE_NAME = "Example";

export type ProfileForShare = {
  id: string;
  handle: string;
  displayName: string;
  bio: string | null;
  avatarUrl: string | null;
  visibility: "public" | "unlisted" | "private";
  moderation: "approved" | "pending" | "removed";
  suspended: boolean;
  updatedAt: Date;
};

export type ShareCard = {
  kind: "user" | "generic";
  title: string;
  description: string;
  url: string;
  image: string;
  imageAlt: string;
  index: boolean;
};

export function shareCardFor(p: ProfileForShare): ShareCard {
  const url = `${SITE}/u/${p.handle}`;
  const generic = {
    kind: "generic" as const,
    url,
    image: `${SITE}/og/default.png`,
    imageAlt: `${SITE_NAME} logo`,
    index: false,
  };

  if (p.suspended || p.moderation === "removed") {
    return { ...generic, title: `Profile unavailable · ${SITE_NAME}`, description: "This profile isn't available." };
  }
  if (p.visibility === "private") {
    return { ...generic, title: `Private profile · ${SITE_NAME}`, description: "This profile is private." };
  }
  if (p.moderation === "pending") {
    return { ...generic, title: `New profile · ${SITE_NAME}`, description: "This profile is waiting for review." };
  }

  const name = cleanUserText(p.displayName, 60) || p.handle;
  const bio = p.bio ? cleanUserText(p.bio, 160) : "";
  return {
    kind: "user",
    url,
    title: `${name} (@${p.handle}) on ${SITE_NAME}`,
    description: bio || `See ${name}'s work on ${SITE_NAME}.`,
    image: `${SITE}/og/profile/${p.id}?v=${p.updatedAt.getTime()}`,
    imageAlt: `Profile card for ${name} on ${SITE_NAME}`,
    index: p.visibility === "public",
  };
}

A few decisions are baked in here, and they're worth making on purpose:

Private and removed profiles get no user text at all. Not the name, not the avatar. If someone forwards an old link to a private account, the card shouldn't reveal who it belongs to.
Pending profiles get a generic card too. Otherwise the window between sign-up and review is exactly when a spam account's card looks its best.
Unlisted profiles get a full card but index: false. Unlisted usually means "anyone with the link", so the link is meant to be shared, just not found through search.
The title always includes the handle and the site name. The handle is unique and the display name isn't. Bank Customer Care (@xyz123) on Example reads very differently from Bank Customer Care.

Step 2: clean user text before it reaches a meta tag

React escapes attribute values for you, so this isn't about HTML injection. It's about what the text looks like on a card.

// lib/share-card.ts (continued)
export function cleanUserText(input: string, max: number): string {
  const flat = input
    .normalize("NFC")
    .replace(/[\u0000-\u001F\u007F-\u009F]/g, " ")        // control characters
    .replace(/[\u200B\u2060\uFEFF]/g, "")                 // invisible spacers
    .replace(/[\u202A-\u202E\u2066-\u2069]/g, "")         // bidi overrides and isolates
    .replace(/\s+/g, " ")
    .trim();

  const chars = Array.from(flat); // code points, so emoji surrogates aren't split
  return chars.length <= max ? flat : chars.slice(0, max - 1).join("").trimEnd() + "…";
}

The bidi overrides are the ones people forget. They can make a name render in a different order than it's stored, which is a classic way to make text look like something it isn't. I keep zero-width joiners and non-joiners, because emoji sequences and scripts like Urdu and Persian rely on them. The code-point slice is a simple version; if your users write long names in languages with combining marks, a grapheme-aware clip with Intl.Segmenter is the better choice.

Step 3: wire it into generateMetadata

// app/u/[handle]/page.tsx
import type { Metadata } from "next";
import { notFound, permanentRedirect } from "next/navigation";
import { getProfileByHandle, findHandleRedirect } from "@/lib/profiles";
import { shareCardFor, SITE_NAME } from "@/lib/share-card";

type Props = { params: Promise<{ handle: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const { handle } = await params;
  const profile = await getProfileByHandle(handle);
  if (!profile) return { title: `Profile not found · ${SITE_NAME}`, robots: { index: false } };

  const card = shareCardFor(profile);
  return {
    title: card.title,
    description: card.description,
    alternates: { canonical: card.url },
    robots: card.index ? undefined : { index: false, follow: false },
    openGraph: {
      type: "profile",
      siteName: SITE_NAME,
      title: card.title,
      description: card.description,
      url: card.url,
      images: [{ url: card.image, width: 1200, height: 630, alt: card.imageAlt }],
    },
    twitter: { card: "summary_large_image", title: card.title, description: card.description, images: [card.image] },
  };
}

export default async function ProfilePage({ params }: Props) {
  const { handle } = await params;
  const profile = await getProfileByHandle(handle);
  if (!profile) {
    const current = await findHandleRedirect(handle);
    if (current) permanentRedirect(`/u/${current}`);
    notFound();
  }
  // ...render the profile
}

Wrap getProfileByHandle in React's cache() so the metadata and the page share one database read per request.

Step 4: the share image comes from your server, built from stored data

The card points at /og/profile/{id}, never at the user's own image URL. That route reads the profile again, applies the same rules, and draws the image.

// app/og/profile/[id]/route.tsx
import { ImageResponse } from "next/og";
import { getProfileById } from "@/lib/profiles";
import { shareCardFor, cleanUserText, SITE, SITE_NAME } from "@/lib/share-card";

const AVATAR_HOSTS = new Set(["uploads.example.com"]);

export async function GET(_req: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const p = await getProfileById(id);
  const card = p ? shareCardFor(p) : null;
  if (!p || !card || card.kind === "generic") {
    return Response.redirect(`${SITE}/og/default.png`, 302);
  }

  const name = cleanUserText(p.displayName, 40) || p.handle;
  const avatar =
    p.avatarUrl && AVATAR_HOSTS.has(new URL(p.avatarUrl).hostname) ? p.avatarUrl : null;

  return new ImageResponse(
    (
      <div style={{ width: "100%", height: "100%", display: "flex", alignItems: "center",
                    gap: 48, padding: 80, background: "#0f172a", color: "white" }}>
        {avatar && <img src={avatar} width={240} height={240} style={{ borderRadius: 120 }} />}
        <div style={{ display: "flex", flexDirection: "column" }}>
          <div style={{ fontSize: 64, fontWeight: 700 }}>{name}</div>
          <div style={{ fontSize: 34, opacity: 0.8 }}>@{p.handle} · {SITE_NAME}</div>
        </div>
      </div>
    ),
    { width: 1200, height: 630, headers: { "Cache-Control": "public, max-age=3600" } },
  );
}

Why go to this trouble instead of using the uploaded avatar directly:

You control the file. Same size, same format, same weight every time. A user's 9 MB phone photo doesn't become the reason a crawler gives up on your card.
Avatars only come from your own storage. The allowlist means a profile can't point the image at a third-party server that logs every crawler request, or swap the file after review.
The route takes an ID, not text. If your image endpoint accepts ?title=..., anyone can generate an image with any words on it under your domain. An ID-only route can only draw what's in your database.
The ?v= changes when the profile changes. Platforms tend to cache by image URL, so a new version gets a fresh fetch. The route itself ignores v.

I keep max-age modest on purpose. The versioned URL would allow long caching, but if a profile is removed, I don't want its old image sitting in my own CDN for a week.

Step 5: make takedowns and renames take effect

When a moderator acts, invalidate the page so the next crawler request gets the generic card:

// lib/moderation.ts
import { revalidatePath } from "next/cache";

export async function removeProfile(id: string) {
  const p = await db.profile.update({
    where: { id },
    data: { moderation: "removed", updatedAt: new Date() },
  });
  revalidatePath(`/u/${p.handle}`);
}

Be honest with your moderators about the limits: cards already posted in chats are copies held by those apps. You can't recall them. What you can control is what every future fetch gets.

For renames, store old handles in a table with the profile ID, redirect them with a 308 for a grace period, and don't let anyone else register an old handle during that time. Otherwise the new owner inherits every link that was shared under the old name, and with it, other people's audiences.

Step 6: test the rules, then check real cards

Because shareCardFor is pure, the important cases are cheap to test with node:test:

import { test } from "node:test";
import assert from "node:assert/strict";
import { shareCardFor, cleanUserText } from "./share-card.mjs";

const base = { id: "p1", handle: "amna", displayName: "Amna", bio: "Logo design", avatarUrl: null,
  visibility: "public", moderation: "approved", suspended: false, updatedAt: new Date(0) };

test("private profiles leak no user text", () => {
  const c = shareCardFor({ ...base, visibility: "private" });
  assert.equal(c.kind, "generic");
  assert.ok(!c.title.includes("Amna") && !c.description.includes("Logo"));
});

test("titles carry the handle", () => {
  const c = shareCardFor({ ...base, displayName: "Bank Customer Care" });
  assert.equal(c.title, "Bank Customer Care (@amna) on Example");
});

test("bidi overrides are stripped", () => {
  assert.equal(cleanUserText("abc\u202Edef", 60), "abcdef");
});

Then check a few real pages from outside. I paste one public, one unlisted and one private profile into the Open Graph preview on OG Scope, a free checker I built that fetches the page server-side without running JavaScript. It shows estimated cards for several apps plus the raw tag values, so it's quick to confirm the private profile really returns the generic title and image, and that the robots tag differs between public and unlisted. The cards are estimates, not screenshots from the platforms, but they read the same HTML the crawlers get.

The checklist

One function decides the card for every account state, and it's tested.
Private, pending, suspended and removed accounts get a generic card with no user text.
Titles include the handle and site name, not just the display name.
User text is normalised and stripped of control and bidi characters.
Share images come from your own route, built from stored data, with avatars from your own storage only.
Moderation actions revalidate the page; old handles redirect and stay reserved for a while.

User pages are some of the most shared links a platform has. Spending a day on their cards is cheap compared with explaining why a removed account still looks fine in everyone's chats.

I'm Abid Ali, a freelance full stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I built OG Scope, a free link preview checker.

One Object, Three Outputs: Keeping og:, twitter: and JSON-LD in Sync in Next.js

Abid Ali — Fri, 23 Oct 2026 10:15:52 +0000

Open a few production pages and compare three things in the <head>: the meta description, og:description, and the description inside the JSON-LD block. On a lot of sites they say three slightly different things. The meta description was written at launch, the Open Graph text was fixed after someone complained about a LinkedIn card, and the JSON-LD was pasted from a schema generator and never touched again.

Nobody sees all three at once, so the drift goes unnoticed. Search engines read one set, chat and social apps read another, and the same page ends up introducing itself in different words depending on where someone meets it.

This post shows the setup I use on Next.js projects to stop that: one typed object per page, two small functions that turn it into Metadata and JSON-LD, and a script that catches drift on the live HTML.

Who reads what

It helps to be clear about the consumers first, because they are not interchangeable:

Open Graph tags (og:title, og:description, og:image, og:url) are what most chat and social apps read when they build a link preview card.
twitter:* tags are read by X. When they are missing, X can fall back to Open Graph for most fields, but the card layout comes from twitter:card.
JSON-LD (<script type="application/ld+json">) is structured data. Search engines use it to understand the page and, in some cases, for rich results. As far as I've seen, link preview cards in chat apps do not read it.
<title> and <meta name="description"> are the classic search snippet inputs and the browser tab.

So there is no single tag that "wins". Each consumer reads its own set, which is exactly why they need to come from one place.

Step 1: one object per page

I describe each page once, in a shape that has nothing to do with any particular output format:

// lib/seo/types.ts
export type PageSeo = {
  path: string;              // "/blog/head-drift"
  title: string;             // headline people see
  description: string;       // one or two sentences
  image: { url: string; width: number; height: number; alt: string };
  type: "website" | "article";
  publishedAt?: string;      // ISO date, articles only
  updatedAt?: string;
  author?: { name: string; url: string };
};

export const SITE = {
  name: "Field Notes",
  url: "https://example.com",
  twitter: "@fieldnotes",
} as const;

Where the object comes from doesn't matter: a CMS, MDX front matter, a database row. What matters is that every head tag is derived from it and nothing is typed by hand twice.

Step 2: `PageSeo` to Next.js `Metadata`

// lib/seo/to-metadata.ts
import type { Metadata } from "next";
import { PageSeo, SITE } from "./types";

export function toMetadata(seo: PageSeo): Metadata {
  const url = new URL(seo.path, SITE.url).toString();
  return {
    metadataBase: new URL(SITE.url),
    title: seo.title,
    description: seo.description,
    alternates: { canonical: url },
    openGraph: {
      type: seo.type,
      url,
      siteName: SITE.name,
      title: seo.title,
      description: seo.description,
      images: [{ ...seo.image }],
      ...(seo.type === "article" && {
        publishedTime: seo.publishedAt,
        modifiedTime: seo.updatedAt ?? seo.publishedAt,
        authors: seo.author ? [seo.author.url] : undefined,
      }),
    },
    twitter: {
      card: "summary_large_image",
      site: SITE.twitter,
      title: seo.title,
      description: seo.description,
      images: [{ url: seo.image.url, alt: seo.image.alt }],
    },
  };
}

Two details worth calling out. alternates.canonical and openGraph.url are built from the same url variable, so the canonical link and og:url can't disagree. And the Twitter fields are filled explicitly instead of relying on fallbacks, so the card on X uses the same headline even if X's fallback behaviour changes.

Step 3: `PageSeo` to JSON-LD

// lib/seo/to-jsonld.ts
import { PageSeo, SITE } from "./types";

export function toJsonLd(seo: PageSeo) {
  const url = new URL(seo.path, SITE.url).toString();
  if (seo.type !== "article") {
    return {
      "@context": "https://schema.org",
      "@type": "WebPage",
      name: seo.title,
      description: seo.description,
      url,
    };
  }
  return {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    headline: seo.title,
    description: seo.description,
    image: [seo.image.url],
    datePublished: seo.publishedAt,
    dateModified: seo.updatedAt ?? seo.publishedAt,
    author: seo.author && { "@type": "Person", name: seo.author.name, url: seo.author.url },
    publisher: { "@type": "Organization", name: SITE.name, url: SITE.url },
    mainEntityOfPage: url,
  };
}

And a tiny component to render it. The replace matters: JSON.stringify does not escape <, so a title containing </script> could close the tag early. Escaping it as \u003c keeps the JSON valid and the HTML safe.

// components/json-ld.tsx
export function JsonLd({ data }: { data: object }) {
  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{
        __html: JSON.stringify(data).replace(/</g, "\\u003c"),
      }}
    />
  );
}

Step 4: wire it into a route

// app/blog/[slug]/page.tsx
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getPost, type Post } from "@/lib/posts";
import { toMetadata } from "@/lib/seo/to-metadata";
import { toJsonLd } from "@/lib/seo/to-jsonld";
import { JsonLd } from "@/components/json-ld";
import type { PageSeo } from "@/lib/seo/types";

type Props = { params: Promise<{ slug: string }> };

function seoFor(post: Post): PageSeo {
  return {
    path: `/blog/${post.slug}`,
    title: post.title,
    description: post.summary,
    image: { url: post.cover.url, width: 1200, height: 630, alt: post.cover.alt },
    type: "article",
    publishedAt: post.publishedAt,
    updatedAt: post.updatedAt,
    author: { name: "Abid Ali", url: "https://example.com/about" },
  };
}

export async function generateMetadata({ params }: Props): Promise<Metadata> {
  const post = await getPost((await params).slug);
  if (!post) return {};
  return toMetadata(seoFor(post));
}

export default async function Page({ params }: Props) {
  const post = await getPost((await params).slug);
  if (!post) notFound();
  return (
    <article>
      <JsonLd data={toJsonLd(seoFor(post))} />
      <h1>{post.title}</h1>
      {/* ... */}
    </article>
  );
}

getPost runs twice here, once for metadata and once for the page. If it's a fetch, Next.js deduplicates identical requests during a render. If it's a database call, wrap it in React's cache() so you don't hit the database twice.

Step 5: catch drift on the live page

The types keep new code honest. They don't help with the page that someone patched by hand, the plugin that injects a second description, or the CDN serving an old build. For that I check the HTML that actually goes out.

This script has no dependencies and runs on Node 18 or newer. It reads the meta tags and any JSON-LD blocks, then reports pairs that disagree:

// scripts/check-head-drift.mjs
// Usage: node scripts/check-head-drift.mjs <url> [<url> ...]
const decode = (s) =>
  s.replace(/&amp;/g, "&").replace(/&quot;/g, '"').replace(/&#x27;|&#39;/g, "'")
   .replace(/&lt;/g, "<").replace(/&gt;/g, ">");

function readMeta(html) {
  const out = {};
  for (const tag of html.match(/<meta\b[^>]*>/gi) ?? []) {
    const key = tag.match(/\b(?:property|name)=["']([^"']+)["']/i)?.[1];
    const content = tag.match(/\bcontent=["']([^"']*)["']/i)?.[1];
    if (key && content !== undefined && !(key in out)) out[key.toLowerCase()] = decode(content);
  }
  return out;
}

function readJsonLd(html) {
  const blocks = [...html.matchAll(/<script[^>]+application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi)];
  const nodes = [];
  for (const [, raw] of blocks) {
    try {
      const data = JSON.parse(raw);
      nodes.push(...(Array.isArray(data) ? data : data["@graph"] ?? [data]));
    } catch {
      nodes.push({ __invalid: true });
    }
  }
  return nodes;
}

const firstImage = (img) =>
  typeof img === "string" ? img : Array.isArray(img) ? firstImage(img[0]) : img?.url;

async function check(url) {
  const res = await fetch(url, { redirect: "follow" });
  const html = await res.text();
  const meta = readMeta(html);
  const ld = readJsonLd(html);
  const problems = [];

  if (ld.some((n) => n.__invalid)) problems.push("a JSON-LD block is not valid JSON");
  const article = ld.find((n) => /Article|BlogPosting|NewsArticle/.test(String(n["@type"])));

  const pairs = [
    ["og:title", meta["og:title"], "twitter:title", meta["twitter:title"]],
    ["og:description", meta["og:description"], "description", meta["description"]],
    ["og:image", meta["og:image"], "twitter:image", meta["twitter:image"]],
  ];
  if (article) {
    pairs.push(
      ["og:title", meta["og:title"], "JSON-LD headline", article.headline],
      ["og:image", meta["og:image"], "JSON-LD image", firstImage(article.image)],
    );
  }
  for (const [aName, a, bName, b] of pairs) {
    if (a && b && a.trim() !== String(b).trim()) {
      problems.push(`${aName} != ${bName}\n    "${a}"\n    "${b}"`);
    }
  }
  console.log(`${res.status} ${url}${article ? "" : "  (no Article JSON-LD found)"}`);
  for (const p of problems) console.log("  - " + p);
  return problems.length;
}

let total = 0;
for (const url of process.argv.slice(2)) total += await check(url);
process.exitCode = total ? 1 : 0;

Run against a page with an old JSON-LD block, the output looks like this:

200 https://example.com/blog/head-drift
  - og:description != description
    "Fresh description"
    "Old description"
  - og:title != JSON-LD headline
    "New & better title"
    "Old title"

The regex parsing is deliberately simple. It's fine for checking your own pages, where you know the markup, and it's not meant for arbitrary HTML from the internet.

Not every difference is a bug. Some sites intentionally use a square crop of the cover in JSON-LD and a wide one in og:image, or a shorter meta description. The script reports, you decide. What I want to avoid is differences nobody chose.

It exits with code 1 when it finds anything, so you can run it after a deploy against a short list of important URLs and fail the job, or just run it by hand when something looks off.

Step 6: look at the card itself

Matching strings don't tell you how the result reads in a card. After a deploy I paste one or two of the URLs into the Twitter card checker on OG Scope, which shows which twitter:card it read and notes when a field fell back to Open Graph. If a fallback shows up that I didn't expect, it usually means toMetadata isn't being used on that route. The cards there are estimates drawn from the fetched HTML, not screenshots from X, but they're good enough to spot a wrong headline or a missing image before anyone else does.

Wrapping up

The pattern is small:

One PageSeo object per page.
toMetadata() and toJsonLd() derive every output from it, with canonical and og:url built from the same value.
JSON-LD rendered with < escaped.
A drift check against the live HTML for the cases types can't catch.

It takes an afternoon to set up on an existing project, and after that, changing a page's headline means changing it in one place.

I'm Abid Ali, a freelance full stack developer in Karachi working with TypeScript, Next.js, React and Node.js. I built OG Scope, a free link preview checker.

Building a "Trending This Week" Page: Time-Decayed Play Counts, Log-Space Scores and Cached Reads in Next.js

Abid Ali — Wed, 21 Oct 2026 10:08:31 +0000

A soundboard needs a "what's hot" page. The obvious version is a list sorted by total plays, and it goes stale almost immediately. The clips that were funny two years ago have a huge head start, so they sit at the top forever and nothing new can climb past them.

What people actually want is "what is everyone tapping right now". On Meme Tap the trending page is described as the sound buttons people are tapping the most this week. That one sentence hides a few real engineering decisions: how to score recency, how to count plays without accounts, how to stop one bored person with an autoclicker from owning the page, and how to serve the list cheaply.

This post walks through a pattern I like for this: an exponentially decayed score stored in log space, a small play-counting endpoint, and a cached read path in the Next.js App Router. The code is a general version of the idea, not a copy of any production codebase.

Why a 7-day window isn't quite enough

The first thing most people try is "count plays in the last 7 days":

SELECT sound_id, count(*) AS plays
FROM play_events
WHERE created_at > now() - interval '7 days'
GROUP BY sound_id
ORDER BY plays DESC
LIMIT 48;

It works, but it has two problems.

The cliff. A play from 6 days 23 hours ago counts fully; a minute later it counts for nothing. Rankings jump around at odd moments for no visible reason.
Cost. You have to keep every raw event and scan a week of them on every refresh. For a busy board that's a lot of rows to aggregate just to render one page.

What we want is a score where recent plays count a lot, older plays count a little, and nothing falls off a cliff.

Exponential decay with a half-life

Give every play a weight that halves every H hours:

weight(play) = 2 ^ ( -(now - playedAt) / H )
score(sound) = sum of weight over all its plays

With H = 48, a play right now is worth 1, a play two days ago is worth 0.5, four days ago 0.25, and a play from last month is effectively zero. A sound that is being tapped a lot today will overtake one that had a big week a fortnight ago, which is exactly the "trending" feeling.

The naive implementation still needs every event, because now keeps moving. The trick is to flip the reference point.

Store the score relative to a fixed epoch

Instead of decaying old plays towards now, inflate new plays relative to a fixed point in the past:

increment = 2 ^ ( (playedAt - EPOCH) / H )

Every sound's score is multiplied by the same factor as time passes, so the ordering never changes when you just wait. That means you can store a single number per sound, add to it on every play, and sort by it directly. No background job has to touch every row.

The catch is that 2^(t/H) grows without limit and will overflow a float within months. So store the logarithm instead and add in log space:

// lib/trending.ts
const HALF_LIFE_HOURS = 48;
const EPOCH_MS = Date.UTC(2026, 0, 1);

/** log2 of one play's weight, relative to the epoch */
export function playExponent(playedAtMs: number): number {
  return (playedAtMs - EPOCH_MS) / (HALF_LIFE_HOURS * 3_600_000);
}

/** log2(2^a + 2^b) without overflow */
export function logAdd(a: number, b: number): number {
  if (!Number.isFinite(a)) return b; // a = -Infinity means "no plays yet"
  const hi = Math.max(a, b);
  const lo = Math.min(a, b);
  return hi + Math.log2(1 + 2 ** (lo - hi));
}

/** Convert a stored log score into "plays-equivalent right now", for display or debugging */
export function currentWeight(logScore: number, nowMs = Date.now()): number {
  return 2 ** (logScore - playExponent(nowMs));
}

logAdd keeps everything in a range a double handles comfortably. currentWeight is handy when you want to sanity-check the numbers: "this sound is worth about 37 fresh plays right now".

The table and the upsert

In Postgres the whole thing is one row per sound:

CREATE TABLE sound_trending (
  sound_id   text PRIMARY KEY,
  log_score  double precision NOT NULL,
  updated_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX sound_trending_rank ON sound_trending (log_score DESC);

And the log-space addition can happen inside the database, so concurrent plays don't race each other in application code:

INSERT INTO sound_trending (sound_id, log_score)
VALUES ($1, $2)
ON CONFLICT (sound_id) DO UPDATE SET
  log_score = GREATEST(sound_trending.log_score, EXCLUDED.log_score)
            + ln(1 + power(2, LEAST(sound_trending.log_score, EXCLUDED.log_score)
                              - GREATEST(sound_trending.log_score, EXCLUDED.log_score))) / ln(2),
  updated_at = now();

$2 is playExponent(Date.now()). The expression is the same logAdd as above, written in SQL.

Counting a play without accounts

A soundboard with no sign-up has no user id to deduplicate on, and it shouldn't try to build one. What you can do is make counting cheap to send and hard to inflate.

On the client, send the play in the background so it never delays the sound:

function reportPlay(soundId) {
  const body = JSON.stringify({ soundId });
  if (!navigator.sendBeacon?.('/api/play', new Blob([body], { type: 'application/json' }))) {
    fetch('/api/play', { method: 'POST', body, keepalive: true }).catch(() => {});
  }
}

On the server, a route handler applies two cheap rules before touching the table: the same visitor tapping the same sound counts once per window, and each visitor has a small budget of counted plays per minute. Everything above that still plays; it just doesn't move the ranking.

// app/api/play/route.ts
import { createHash } from 'node:crypto';
import { playExponent } from '@/lib/trending';
import { db, kv, UPSERT_SQL } from '@/lib/server'; // UPSERT_SQL = the statement above

export async function POST(req: Request) {
  const { soundId } = await req.json().catch(() => ({}));
  if (typeof soundId !== 'string' || soundId.length > 120) return new Response(null, { status: 400 });

  const day = new Date().toISOString().slice(0, 10);
  const ip = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim() ?? '';
  const ua = req.headers.get('user-agent') ?? '';
  // Short-lived, salted fingerprint: good enough for rate limiting, useless for tracking
  const visitor = createHash('sha256').update(`${process.env.PLAY_SALT}:${day}:${ip}:${ua}`).digest('hex').slice(0, 16);

  const firstTapInWindow = await kv.set(`p:${visitor}:${soundId}`, 1, { nx: true, ex: 30 * 60 });
  const minuteKey = `r:${visitor}:${Math.floor(Date.now() / 60_000)}`;
  const perMinute = await kv.incr(minuteKey);
  if (perMinute === 1) await kv.expire(minuteKey, 120);

  if (firstTapInWindow && perMinute <= 20) {
    await db.query(UPSERT_SQL, [soundId, playExponent(Date.now())]);
  }
  return new Response(null, { status: 204 });
}

kv here is any store with SET NX EX and INCR (Redis or a hosted equivalent). The fingerprint rotates daily with the salt, so it's only useful for the thing it's for. Treat it as a speed bump, not a security boundary: anyone determined can rotate IPs, and that's fine for a meme page. Also check what your hosting platform puts in x-forwarded-for, because that varies.

Reading the list cheaply

Rendering the page is now a plain indexed query, and it doesn't need to be live to the second. In the App Router you can let the page be statically rendered and revalidated on a timer:

// app/trending/page.tsx
import { db } from '@/lib/server';

export const revalidate = 600; // rebuild at most every 10 minutes

export default async function TrendingPage() {
  const { rows } = await db.query(
    `SELECT s.id, s.title, s.slug, s.audio_url
       FROM sound_trending t JOIN sounds s ON s.id = t.sound_id
      ORDER BY t.log_score DESC
      LIMIT 48`
  );
  return <SoundGrid sounds={rows} />;
}

Ten minutes of staleness is invisible on a "this week" page, and it means the database sees a handful of reads an hour instead of one per visitor.

Tuning it

A few things I'd adjust after watching real data:

Half-life. 24 hours feels jumpy; a week feels like "all time" again. Something around two to three days matches the "this week" wording.
Brand-new uploads. A clip added this morning has had no time to collect plays. Rather than boosting it artificially, give new clips their own newest-first page and let trending stay honest.
Sanity checks. Log currentWeight for the top few sounds now and then. If one sound is worth thousands of fresh plays while the next is worth twenty, look at the rate limits before you celebrate.

You can see what the end result feels like on Meme Tap's trending sound buttons page, a mix of meme buttons, funny sounds and short effects that people are playing most at the moment. The pattern itself works for anything with a "hot right now" list: posts, products, search terms or snippets.

Abid Ali is a full-stack web developer in Pakistan. He builds Meme Tap, a free browser soundboard with one-tap meme sound buttons.

DEV Community: Abid Ali

Trimming Audio in the Browser Without the Click: Zero-Crossing Snaps and Short Fades in JavaScript

Where the click comes from

Step 1: snap the cut to a zero crossing

Step 2: a short fade at both ends

The code

Testing it in Node

Using it in the browser

Choosing the numbers

What this doesn't solve

If you just need the clip

Summary

Estimating Fixed-Price Freelance Work in TypeScript: Three-Point Estimates, Honest Ranges and the Questions Your Proposal Should Ask

Three numbers per task

The task file

The script

Running it

Turning the output into a proposal

Testing it

Where this fits on Fiverr

Limits

FAQ

A Pre-Delivery Check for Freelance Web Projects: One Node Script for Broken Links, Missing Alt Text and Leftover Staging URLs

What it checks, and what it doesn't

Reading attributes without a parser

The per-page checks

The crawl

The report

The whole script

Running it

Where it fits in a freelance workflow

Building a Small Link Unfurler in Node.js: Tag Fallbacks, Relative Image URLs, Charsets and Not Fetching Your Own Network

The fallback order

Fetching safely

Reading only what you need

Getting the characters right

Parsing the head without a parser

Building the card

Tests

What I'd add before shipping it

Checking your output against a reference

Ampersands, Quotes and Double-Encoding: Escaping og:title and og:description Exactly Once

How a value travels into a share tag

The rule: plain text in the middle, escape once at the edge

The helper

A checker for pages you didn't build

Tests

Where to look when you see it

A Job-Post Scorer That Never Touches Upwork: Pass, Weak or Skip With Reasons You Can Read, in Plain JavaScript

What the scorer is (and isn't)

The input: a job you typed yourself

The settings: your floor, your fee, your Connect price

The money rule: take-home per hour, after the fee and this bid

The other rules

Verdicts without a hidden score

A tiny CLI

Tests

Things I deliberately left out

Wrapping up

A Random Button That Doesn't Feel Broken: Unbiased Picks, No Instant Repeats and Shuffle Bags in JavaScript

Step 1: get the integer right

Step 2: when you want crypto, avoid modulo bias

Step 3: "anything but the last one"

Step 4: a short memory instead of a one-item memory

Step 5: shuffle bags, for "I want to hear everything"

Step 6: seed it, then test it

Where the pick should happen

The button itself

Money Math for a Freelance Fee Calculator in JavaScript: Integer Cents, Rounding on Purpose and Currency Symbols That Don't Pretend to Convert

Why floats bite

Parse strings, not numbers

Percentages as basis points

Round on purpose

The order of deductions matters

Gross-up: the calculation people get wrong by hand

Formatting: symbol, not conversion

Tests

What to put on the page

Keyboard Hotkeys for a Browser Soundboard: KeyboardEvent.code, Layout-Proof Labels and Not Hijacking the Search Box

key or code?

`key` or `code`?

One Object, Three Outputs: Keeping og:, twitter: and JSON-LD in Sync in Next.js

Step 2: `PageSeo` to Next.js `Metadata`

Step 3: `PageSeo` to JSON-LD