DEV Community: Tea-sip

Engineer-to-Engineer: Building a Typing Test That Doesn't Lie to You

Tea-sip — Fri, 14 Aug 2026 22:05:37 +0000

If you've ever shipped a "typing speed" feature into a developer tool, an educational dashboard, or a hiring pipeline, you've probably noticed that the simplest-looking metric in computing — words per minute — is also one of the easiest to game and the hardest to defend in a code review. The original article in this series pushes past the 80 WPM plateau. This one is for the people building the measurement itself: how do you write a typing test that survives scrutiny from an accessibility lead, a data engineer, and a skeptical senior dev all at the same time?

We'll walk through the constraints, the formulas, the edge cases that bite in production, and a checklist you can paste into a PR description. Where the underlying mechanics of WPM calculation matter, I'll point to a thorough walkthrough at Lizely's WPM formula guide so you don't have to reinvent the theory from scratch.

The Two Meanings of "Word" You Need to Settle Before Anything Else

A typing test fundamentally answers "how many characters did a user commit, and over what interval?" Everything else is convention. Before you write a single line of measurement code, decide which of these two definitions your product will use, because they produce noticeably different numbers for the same user:

The classic 5-character word. Divide total characters typed (including a trailing space) by 5. This is the convention most office-suite benchmarks report, and it's the one most "casual" testers expose to end users.
The linguistically grounded word. Count whitespace-delimited tokens that are actually present in the source text. This is closer to how a linguist or a reading researcher would count.

You cannot ship both silently. Either pick one and document it, or expose the formula in a tooltip and let the user see the math. The 5-character convention has a long history in typing research (see Wikipedia's coverage of the words-per-minute metric), and it's still the right default for general-purpose typing products because it normalizes across languages and punctuation density.

The Time Window Is Where Most Bugs Hide

A naive implementation measures Date.now() from the first keypress to the last keypress and divides. That's wrong in three ways that show up in real bug reports:

Idle gaps inflate the denominator unfairly. If a user pauses for 12 seconds to think, their WPM collapses even though their burst speed was fine. The common fix is to stop the clock after, say, 3 seconds of no input, or to compute WPM over the active interval and surface "active time" alongside "elapsed time."
Cold-start padding distorts short runs. The first keypress almost always takes longer than the average character. For runs under 10 seconds, either run a warm-up prompt (most competitive testers do this) or display a disclaimer that sub-15-second runs are indicative, not definitive.
Backspace handling changes the meaning of the score. Does correcting a typo count against the user? Industry convention is "yes for accuracy, no for raw speed" — you compute raw CPM over all characters committed, and accuracy as correct / total_attempted. Don't conflate the two into a single score, or your accuracy and speed will appear to trade off against each other when they actually don't.

If you instrument the active-time vs. elapsed-time split, you'll also catch a class of "are they really typing?" bots: if elapsed time exceeds active time by a large factor, you're probably looking at a paste event, not keystrokes.

What You Measure vs. What the User Sees

A reasonable internal model has three numbers:

Quantity	Formula	Surface to user?
Raw CPM	`total_keys / active_minutes`	Sometimes, as "raw"
Net WPM	`(correct_chars / 5) / active_minutes`	Yes, primary metric
Accuracy	`correct_chars / total_chars`	Yes, secondary metric

The trap is letting "gross WPM" leak into the UI. Gross WPM rewards sloppy typing because it includes errors in the numerator; once a user notices that fixing typos lowers their score, they stop fixing typos, and the product has taught them the wrong thing. Always display the corrected (net) WPM.

For keystroke handling, the event you'll listen for is the keydown event on a focusable element. Capture event.key, normalize for layout differences (Shift should not count as a character, modifier-only keys should be ignored), and decide your policy on IME composition events up front. If your test supports non-Latin scripts, you'll need to read from the input event instead, because keydown fires per Latin key press and double-counts for CJK input methods.

Picking a Corpus Without Accidentally Building a Bias Engine

Corpus selection is the silent politics of a typing test. Two questions to answer in your design doc:

Dictionary vs. prose. A common-words dictionary produces higher and more consistent scores, but it trains only short, common tokens. Prose produces lower scores and more variance, but it surfaces real bigram weaknesses (more on bigrams below). Most serious tools offer both; pick a default and make the alternative one click away.
Domain. Programming-language tokens (function, return, const) have dramatically different character distributions than English prose. If your user base is developers, a code-flavored corpus is more honest. But also consider keyboard layout: the same text typed on QWERTY vs. Dvorak vs. Colemak will produce wildly different WPM numbers, so don't let a "global leaderboard" mix layouts unless you've normalized for that.

There's an accessibility angle here too. For users on screen readers or alternative input devices, the "competition" framing is actively hostile. At minimum, your test should allow pausing, should not auto-fail on long pauses, and should expose a "practice mode" that reports per-character latency rather than a single summary number.

The Bigram Heatmap: The Single Most Useful Diagnostic You'll Add

Once the headline metric works, the highest-leverage feature you can ship next is a per-bigram latency map. A bigram is just a two-character sequence; there are ~676 of them in English lowercase plus space. Plotting mean latency per bigram reveals exactly where a user hesitates, and it's much more actionable than "your WPM is 52."

The implementation is straightforward:

For each completed session, group keystrokes into pairs (th, he, e, s, ...).
For each pair, record the inter-key interval in milliseconds.
Render a grid where rows and columns are characters; cell color encodes mean latency.
Sort the slowest bigrams to the top of a sidebar.

Once a user sees that their ed, th, and tion transitions are slow, they can drill those specifically, and your product is now a training tool, not just a measurement tool.

Shipping Checklist for a v1 Typing Test

Use this list verbatim in your PR template:

Time source is performance.now(), not Date.now(), to avoid clock-skew artifacts.
WPM formula is documented in the UI tooltip and matches the code, character for character.
Accuracy is reported separately from speed, and the formula is in the tooltip.
Backspace behavior is explicit: errors counted in accuracy, ignored in raw WPM.
The clock stops after a configurable idle threshold (3 seconds is a sensible default).
Sessions under a minimum duration (15 seconds) display a confidence note.
The corpus file is versioned and the version is shown in results.
Layout is recorded (auto-detected when possible) and shown on the leaderboard.
Pause/resume is supported and does not reset progress.
The event handler correctly ignores modifier keys and handles IME composition.
Paste is detected (event.inputType === 'insertFromPaste') and either rejected or flagged.
Results are exportable as JSON for users who want to track their own history.

If all twelve boxes are checked, your test will survive a code review from someone who actually knows the domain.

Frequently Asked Questions

What's a reasonable default for the idle-timeout threshold?

Three seconds is the consensus in most consumer-facing typing tools. Shorter than that and thinking pauses get punished; longer and the user gets ambiguous results after walking away. Make it configurable in your advanced settings.

Should I count capitalized words differently from lowercase ones?

No, if you're using the 5-character-word convention. Capitalization adds one keystroke (Shift + letter) but only when starting a sentence or proper noun, so it doesn't materially shift the average. If you're using token-based counting, capitalization is irrelevant because the token is the same.

How do I prevent paste-based cheating in a public leaderboard?

Detect inputType === 'insertFromPaste' on the input event and disqualify the run. Be transparent about this in your rules. Also display the active-vs-elapsed time ratio; humans rarely sustain above a 1.2x ratio, while pasted runs typically show near-perfect 1.0x because they were applied in a single event.

My users complain that their scores dropped after I "fixed" the formula. What do I do?

This is almost always because the old formula was gross WPM and the new one is net WPM, or because you tightened the idle timeout. Don't roll back. Instead, ship a "score history" feature so users can see their own trend line, and announce the change clearly. Honest measurement always costs a few leaderboard positions in the short term, and that's the right trade-off.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Reviewing Pull Requests Without Losing Your Mind: A Text-Diff Workflow for Code Reviewers

Tea-sip — Thu, 13 Aug 2026 19:02:28 +0000

Code review fails in predictable ways. The reviewer skims, the author feels blindsided, and a missing comma in a SQL migration ships to staging. Most of those failures are not about skill — they are about what the reviewer actually sees. Diff tools shape what is visible, what is hidden, and what the human eye can reasonably scan in fifteen minutes between meetings.

This article is for the reviewer on the receiving end. It treats the text comparison not as a "diff" feature but as a review surface with its own rules, edge cases, and pitfalls. The goal: a repeatable, defensible way to read a change so you catch semantically meaningful edits and ignore cosmetic noise.

Why Diffs Are Harder to Read Than They Look

The Myers diff algorithm, the algorithm behind nearly every textual comparison tool in modern version control, is one of those pieces of engineering that quietly shapes daily life. It traces back to Eugene Myers's 1986 paper and is now baked into Git, Mercurial, and most standalone comparison utilities. The algorithm is correct, but correctness is not the same as clarity.

A diff is a projection. You are looking at the difference between two strings, but the strings represent intent, and intent lives in a layer the algorithm cannot see. A renamed function may produce a noisy hunk that hides a real bug. A reindent can grow a hunk by twenty lines without changing a single instruction. A trailing-whitespace cleanup right before a security-sensitive block can bury the security-sensitive block six lines below the visible change.

Reviewers compensate by changing the surface. Side-by-side viewing, collapsed unchanged regions, syntax highlighting, and consistent hunk anchoring all reframe the same algorithm output. The practices below are about choosing that frame deliberately.

The Configuration That Pays Off Immediately

Before walking through a pull request, set the comparison up so it matches the way you actually read. Three settings matter more than any plugin collection.

Whitespace normalization on display, strict on commit. git diff exposes --ignore-cr-at-eol, --ignore-trailing-cr, --ignore-space-change, and --ignore-all-space flags. In a browser-based viewer, you usually toggle the equivalent settings inline. The right pattern is: ignore trailing-space differences and end-of-line differences in the visual layer, but reject them in code review discussions if the file format forbids them. For example, a Markdown file rendered on the web can tolerate a stray \r, but a shell script being executed on Linux cannot (POSIX defines text files as sequences of lines terminated by newline, not carriage return + newline).

Word-level granularity for prose, line-level for code. Algorithms can compare two files character by character, word by word, or line by line. Word-level is overwhelming for source files; line-level is the right default there. For copy edits, config files with long values, or translation strings, word-level reveals more. Some viewers default to one or the other — pick deliberately, do not inherit the default.

Anchor hunks to function or section headers. A unified diff shows @@ -120,8 +120,8 @@ optional context line. The optional context line is whatever happens to live nearby. In a large file, that optional context tells you almost nothing. Good viewers anchor the hunk on a label — the nearest function signature, the heading above a paragraph. If your tool does not do this automatically, scan up from the hunk header to find one before you start reading.

A Walkthrough: Reviewing a 400-Line Backend Change

Suppose a teammate opens a pull request touching a single file, around 400 lines, that blends three concerns: a SQL migration, a Go service layer, and a few JSON serialization helpers. You have fifteen minutes. Here is how to consume it without missing the load-bearing edits.

Read the file path and the file's role first. A migrations/0007_add_user_role.sql file is destructive in a different way than internal/service/user.go. Treat them as different review surfaces. The SQL migration has a small surface area; read it line by line, and pay close attention to the order of statements. Some databases, including PostgreSQL, do not allow all forms of ALTER TABLE inside a transaction wrapping backfill, depending on the version — confirm any backfill strategy against the version deployed in staging (PostgreSQL transactional DDL notes are documented at length on the official wiki).

Now look at the Go service layer. Scan the diff hunks in the order they appear, but read only the new lines and the removed lines until you have the structure. The unchanged context is for orientation, not for re-reading. As you go, mentally tag each hunk with one of three labels: contract change (renames, signature changes), behavior change (new branch, new state transition), or cosmetic (renames of locals, comment edits). The contract and behavior tags are what you write comments about. Cosmetic edits get a thumbs-up, not an action.

For the JSON helpers, the question is whether the wire format moved. Renaming a struct field is fine in isolation; renaming it without bumping the version and updating the producer breaks every downstream consumer in production. This is the moment where a side-by-side comparison earns its keep. Two panes, one anchored on the "before," one on the "after," with whitespace ignored — you can see in five seconds whether the field rename is paired with the right serialization call. For a deeper walkthrough on tuning this kind of browser-based comparison workflow, the Lizely guide on comparing text differences covers the configuration knobs in detail.

Edge Cases That Trip Up Even Senior Reviewers

A few cases deserve explicit attention because they consistently hide defects.

Reformatting commits before logical commits. If the diff includes a whole-file rename (a change touching almost every line because of a formatter), the hunks become unreadable. Ask the author to split the change before review. The conventional commits specification does not require this, but a clean separation of "style:" and "feat:" commits in a single pull request is what makes a diff reviewable.

Cherry-picks that drop hunks. A reviewer sees a patch that looks safe but was produced by cherry-picking across branches. Context lines can disagree between the two parents, which means the hunk applies cleanly but the semantics drift. The Myers algorithm reports a clean apply; the human reviewer has to know whether to ask.

Binary files reported as "text." A .sql file shipped with \uFEFF (a BOM, byte order mark) at the top will compare as text but render oddly in some terminals (Unicode's BOM is defined in UAX #15 and surrounding areas). If the diff shows weird leading characters, that is the cause.

Three-way merges masquerading as two-way diffs. A pull request updated to resolve conflicts may show only the final patch. The conflict markers themselves are gone, but the logic they resolved is what you need to see. Ask for git log --merge output if anything in the diff looks suspiciously consistent across two unrelated areas.

A Checklist You Can Keep Open During Review

Set whitespace rules for the file type before opening the diff.
Tag each hunk as contract, behavior, or cosmetic while reading.
For SQL or schema files, re-read in source order ignoring the diff layout.
Cross-check every rename against every callsite the tool shows.
Confirm that any binary or BOM-prefixed files are intentional.
If the patch touched merge-resolved code, request the merge's history slice.
Before approving, run the test command locally and read the failing-test diff if any.

Trade-offs Worth Naming

Browser-based comparison has limits. Large files (multi-megabyte logs, generated code) usually lag in a tab-based viewer and feel snappier in a native tool. Cross-file comparison — for example, "did this constant move?" — is harder in any single-file viewer. And you lose the integration with comment threads and CI status that a code-host-native diff page provides. The right answer in production is usually both: use the host's diff for the conversation, and a side-by-side external viewer for the careful read of the largest, riskiest file in the change.

No single setting, plugin, or algorithm will catch everything. The leverage comes from applying the same six-step checklist to every change, so the review surface is consistent enough that your pattern recognition actually fires.

Frequently asked questions

Should I review a diff in a browser or in an IDE?

Use the host's diff for the conversation and quick orientation, and an external side-by-side viewer for the largest, riskiest file. Browser tools are nearly always more responsive for cross-file comparison and stay out of the way of your editor.

What whitespace setting should I default to?

Ignore trailing whitespace and end-of-line differences for display, but never for shell scripts, build files, or any file executed by a POSIX tool. Confirm against the project's editorconfig or equivalent before tightening the rules.

How do I review a reformatting commit that turned every line red?

Do not review it as a single diff. Ask the author to split it: one commit for the formatter, one commit for the actual change. A reformat that hides a logic edit is a defect waiting to land.

What is the Myers algorithm and why does it matter to me?

It is the standard approach used to compute the shortest edit script between two strings, which is what nearly every diff tool displays. Knowing it exists is useful, but knowing its limits matters more: it finds minimum edits, not minimum intent, and that gap is exactly where review judgment has to step in.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Stress-Testing Visual States in Frontend Apps With Random Color Sweeps

Tea-sip — Wed, 12 Aug 2026 22:03:39 +0000

When you build a frontend, you spend most of your time on the "happy path" — the layout where the data loads, the user is logged in, the empty state is friendly, and the error is a soft amber pill. But every UI surface also has to survive bad data, weird data, hostile data, and no data. One trick I lean on more than I'd like to admit: blast random colors through the component tree and look at what breaks.

This is not about design polish. It is a debugging and QA pattern. Random color generators turn into a cheap, repeatable visual fuzz tester for state-handling code. Below is the workflow I use, the rules I hold the team to, and the trade-offs you'll hit once you try to ship this.

What a Color Sweep Actually Exercises

If you swap every text color, background, border, and divider for a value pulled from a random generator, you are not just "making it ugly." You are forcing the component to render under inputs it was never hand-tuned for. That surfaces four classes of bugs fast:

Contrast regressions. Hardcoded hex codes like #cccccc on #ffffff look fine in code review and look broken on screen under real luminance. A sweep catches the ones that slipped through.
Stale state leaking between renders. If a component caches the "last color used" in a closure and you re-render with a different key, you'll see ghost colors or stuck backgrounds. Random sweeps make this obvious in two seconds.
Theme provider blind spots. Components that bypass the theme and reach for raw values show up immediately because their colors stay constant while everything around them changes.
CSS specificity wars. A random inline color fights with a class-based rule, and the winner tells you which side of the cascade is actually in charge.

If you've ever shipped a UI where "it looked fine on my machine" — this is the cure.

A Reproducible Sweep Workflow

Don't ad-hoc this. Random inputs are only useful if you can reproduce a failure. Here is the workflow I keep in a scripts/color-sweep.ts and run in CI for visual diffs.

Seed the PRNG so the run is deterministic. Math.random() is fine for a one-off, useless for a regression test.
Pick a target node. Usually the root, or each top-level route shell.
Walk the rendered tree. For every element with text, a background, a border, or an SVG fill, replace the value with a fresh random color.
Capture a screenshot per route. Keep the seed in the filename.
Store the seed in the test report. If a screenshot fails review, that seed reproduces it.

The MDN guide on the Web Performance APIs is the right landing page for any tooling that needs frame timing while you capture; you do not want the sweep itself to mask rendering stalls.

Holding the Team to Rules

A color sweep is a hammer; without rules it produces a mess of screenshots nobody trusts. The rules I enforce:

Scope first. The sweep is opt-in per route. You do not run it against billing or auth screens; the data is real and the colors may persist in logs.
Names, not hex. Every randomized color must come from a typed enum (text, bg, border, accent). No "let me just inject a string."
Two runs minimum. One with a fixed seed for diff, one with a different seed to confirm the bug is not a single lucky value.
One bug per PR. A sweep is exploratory. If you find three regressions in one run, split them.

The contrast rule is the one that matters most. WCAG lays out the math for relative luminance and contrast ratio in a stable, citable form, and every "looks fine" debate ends at that document.

The Trade-offs Nobody Mentions

This is where engineers lose patience. Honest list:

Snapshot diffs grow. A random sweep produces N images that are not stable across PRNG library upgrades. Pin the seed library, and treat the screenshot suite like a binary artifact — re-baseline deliberately, not by accident.
Performance overhead. Walking a large DOM and patching styles per node is real work. Profile once, then gate the sweep behind a flag.
False confidence. A green sweep does not mean the UI is correct. It means the UI tolerates arbitrary colors. The next bug class — semantic correctness — needs fixtures, not fuzz.
Reviewer fatigue. Five hundred random screenshots is not "exhaustively tested." It is a pile. Curate. Keep ten representative seeds, not one thousand.

I have watched two teams adopt this pattern well and one team adopt it badly. The difference was almost always whether someone owned the seed corpus.

Integrating With Existing Visual Tests

You probably already have a visual regression runner — Percy, Chromatic, Playwright's toHaveScreenshot, or a homegrown pixel-diff job. The color sweep is a complement, not a replacement. Wire it like this:

Run the normal visual suite against the real theme. This catches "the new button is 2px off."
Run the sweep suite against the same routes. This catches "the loading skeleton uses a hardcoded white that nobody noticed."
Compare the two pass/fail sets. Bugs that appear only in the sweep pass/fail are the unique catch.

Keep the sweep suite on a separate CI lane with a longer timeout. Don't make every PR wait for it. Nightly is fine.

When a Random Sweep Is the Wrong Tool

A few honest cases where you should skip this entirely:

The component is a chart with a semantic palette (red = down, green = up). Random colors destroy meaning. Use a palette fixture instead.
The screen is text-heavy and the bug class is information density. Color won't help.
You are debugging a single user's environment. A sweep tells you nothing about one machine.
The renderer is canvas/WebGL. DOM walking is irrelevant; you need a pixel-level approach instead.

If you're staring at a bug report that says "the toast disappears when I do X," a color sweep is not the first move. A color sweep is for the bugs that only show up because the state is varied.

For a deeper walkthrough of generator formats and how to wire deterministic output into a script, the Lizely guide on generating random colors in any format with one click is the closest fit.

Frequently asked questions

How many seeds do I need before the sweep is "enough"?

Ten is a practical floor for a small app; thirty is a reasonable ceiling for a medium one. Beyond thirty, you're mostly paying reviewer cost. The exact number depends on how many visually distinct states your app has — login vs. logged-out vs. error vs. empty are four, and each deserves its own seeds.

Can I run this against a production build?

I would not. The sweep mutates live DOM and may persist in error reports, analytics payloads, and screen recordings. Run it against a staging build with telemetry stripped, or against Storybook with a flag.

Won't this just find contrast bugs my linter already catches?

Linters catch hardcoded values and obvious violations of a token. They do not catch a theme provider being bypassed in a single component, or a stale value bleeding between renders. The sweep is for the bugs the linter cannot see — runtime state-handling, not static rules.

Should the random colors be perceptually uniform?

Yes for sweep runs meant to find contrast regressions, because a uniform sampler across RGB leaves huge gaps in the luminance space. For most debugging sweeps, plain HSL rotation is fine and faster to reason about. The choice matters less than the discipline of keeping the seed reproducible.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Stop Reinventing the Wheel: A QA Pattern for Date Math in User-Facing Code

Tea-sip — Tue, 11 Aug 2026 22:04:31 +0000

Every backend that touches a date of birth ends up reinventing the same arithmetic. I've watched it happen in three codebases this year alone: a fintech KYC service, a healthcare intake portal, and a small HR tool for a startup. The bug shape is almost always identical — somebody computes age by subtracting birth year from current year, the QA suite passes because it only tests inputs born in 1970 and 2000, and then someone born on February 29 walks in and gets flagged as underage. Or worse, a leap-year-spanning eligibility window quietly lets the wrong person through.

This article is a checklist for engineers who inherit one of these systems and need to harden it before the next incident. It assumes you've already decided you need to compute a duration between two dates correctly, and your job is to figure out how to test that computation so you stop shipping regressions.

The Two Questions You Actually Need to Answer

Before writing a single assertion, ask the business which of these they care about. The implementation is different for each, and conflating them is the source of most date-math bugs.

How many full years has the person been alive? This is the classic "age in years" question — what a doctor's office, a voting registration form, or an age-gated content filter wants. The answer changes only on the birthday.
Has a duration threshold been crossed? This is the eligibility question — "has this user been enrolled for at least 90 days," "was this contract signed more than 30 days ago," "did the trial expire." The answer is a boolean with a specific reference date.

The age-in-years case is subtler because of the birthday boundary, and it's where most teams stumble. The duration-threshold case is just subtraction with a comparison, but the comparison must use the right granularity — comparing a millisecond timestamp to a day count is a famous source of off-by-one-day bugs when daylight saving time shifts occur. The Date and Time Arithmetic section of MDN's Date reference is worth a read if you're implementing in JavaScript, and the datetime topic in the Python docs covers the equivalent pitfall with timedelta.

The Reference Test Matrix You Should Commit to Your Repo

Most date-math codebases have maybe two test cases: "born today" and "born 30 years ago on the same day." That's not a test suite, that's a smoke test. For age-in-years logic, commit a fixture-driven test that covers these rows at minimum:

Born exactly today — must return 0.
Born one calendar day before today — must return 0, not 1.
Born exactly one year ago to the day — must return 1.
Born one year and one day ago — must return 1.
Born on Feb 29 in a leap year, queried on Feb 28 of a non-leap year — must return the elapsed years, not treat the missing day as "not yet had a birthday this year."
Born on Feb 29 in a leap year, queried on March 1 of a non-leap year — must return the elapsed years (birthday observed March 1).
Born on Dec 31, queried on Jan 1 the next year — must return 0, not 1.
Born on Jan 1, queried on Dec 31 of the previous year — must return 0.

For each row, store the birthday and the "as of" date as explicit ISO-8601 strings in your fixture file, never as new Date() literals in the test body, because the latter will rot the moment someone runs the suite in a different timezone. The ISO 8601 entry on Wikipedia is a reasonable anchor for the team on why the format is preferable to anything locale-driven.

Injecting the Clock: The Single Most Useful Refactor

Most age-computation bugs are not in the math. They are in the fact that the math depends on now, and now is hidden inside the function being tested. You can't unit-test what you can't control.

Refactor every age computation so the reference date is a parameter. Default it to now() only at the public boundary (controller, handler, scheduled job). Internally, everything takes (birth_date, reference_date) explicitly. This sounds pedantic until you see how much it simplifies the test:

def age_in_years(birth: date, ref: date) -> int:
    years = ref.year - birth.year
    if (ref.month, ref.day) < (birth.month, birth.day):
        years -= 1
    return years

Now the test isn't testing "the current moment," it's testing "given these two inputs, does this function produce this output." That single refactor usually eliminates a third of the team's date-bug backlog.

When the Rule Has a Time-of-Day Component

This is the case that catches mature codebases. The product says "users under 18 cannot purchase," but the actual stored rule is "users whose 18th birthday has not yet passed at the moment of purchase." If your backend stores the birthday with a time component (and many do, because the database column is a TIMESTAMP rather than a DATE), you have to decide whether 2007-03-15 23:59:00 plus 18 years crosses the threshold on 2025-03-15 14:00:00 or 2025-03-16. The answer depends on whether your business rule operates in calendar days or in elapsed time.

I've seen teams burn a week on this. The pragmatic answer is: strip the time component at the boundary, then use calendar-day comparison. Almost no product actually cares about the hour; they care about the date. If your column is TIMESTAMP, cast to DATE on read and the question evaporates.

For teams operating across jurisdictions, remember that the rules of whose calendar day matters can vary. A patient admitted at 23:50 in Tokyo is in a different calendar day than a physician reviewing the chart at 00:10 in Berlin. If your system crosses timezones, decide explicitly which anchor you use. The IANA Time Zone Database overview is worth skimming so the team at least agrees on terminology before they disagree on policy.

A Pragmatic Workflow for the Next Time This Comes Up

When a ticket lands asking for an age check or an eligibility-window check, walk through this sequence:

Classify the question as age-in-years or duration-threshold.
Locate the existing helper. Most codebases already have one, hidden in a utils/ folder, written by someone who left. Read it before writing a new one.
Write the fixture file with at least the eight rows above, plus any domain-specific rows (e.g. "free trial expires exactly on day 30 at midnight UTC").
Inject the clock. If the helper takes now implicitly, refactor before adding tests.
Add the rule check as a separate function that consumes the helper's output. Age computation and age policy are different concerns and should live in different files.
Run the suite in CI with a fixed system clock for at least one test case, using something like freezegun or timecop, to prove the clock is actually injectable.
Document the boundary behavior in the helper's docstring, especially what happens on Feb 29 and on month-end edges.

If your team has standardized on Excel for any of these calculations — which happens more often than engineers like to admit, especially in HR and operations — pair the engineering helper with a spreadsheet that uses the same logic. The in-depth walkthrough on calculating age between two dates is a useful reference when the business needs a non-engineer to verify the rule.

Frequently asked questions

What's the difference between using a `TIMESTAMP` and a `DATE` column for birthdays?

A DATE column stores only the calendar day. A TIMESTAMP stores a moment in time, down to microseconds, and is interpreted in the session timezone. For age logic, you almost always want DATE, because the rule operates on calendar days and the time component is either ignored or, worse, used inconsistently across queries. If you must store TIMESTAMP for legacy reasons, cast to DATE at the application boundary.

Should leap-year babies be treated specially?

No special-casing is needed if you use the standard "subtract years, decrement if birthday hasn't occurred yet" pattern. The function handles Feb 29 correctly because it compares month-and-day tuples; when the reference date is in a non-leap year and is Feb 28 or March 1, the comparison still works. What you must avoid is birthday.addYears(n) style libraries that throw when the target year is not a leap year — those libraries need a policy on whether to roll forward to Feb 28 or March 1, and not all of them document it.

My tests pass locally but fail on the CI server once a month. What's happening?

The CI server's clock and yours are fine. The problem is almost certainly that one of your tests uses new Date() directly and runs near midnight UTC. The local machine and the CI runner cross the day boundary at different wall-clock times. This is the single most common reason date tests are flaky, and it's exactly why fixture-driven tests with explicit ISO-8601 strings are non-negotiable.

Is there an existing standard I should be citing in my code review comments?

Yes. If you're working in Python, PEP 8 covers naming but not date logic; the relevant authority is the datetime module documentation and, for cross-system interchange, ISO 8601. Citing those in a code review makes the date-of-birth column review land faster than re-explaining the Feb 29 case each time.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Choosing How to Merge PDF Files: A Practical Engineer's Decision Guide

Tea-sip — Mon, 10 Aug 2026 19:08:48 +0000

Combining separate PDF documents into a single file sounds like a trivial operation until you hit your second real-world use case. A one-off personal scan is one thing; a recurring team process with naming conventions, retention rules, and audit trails is another. This guide walks through the three most common ways engineers and technical leads actually get this done — doing it manually, scripting it in code, or routing the job through a purpose-built web utility — and lays out the trade-offs honestly so you can pick the right path per situation.

The advice here applies whether you are stitching together scanned invoices, assembling an evidence packet for a compliance review, or shipping a multi-appendix deliverable to a client. The decision criteria are the same: how repeatable the task is, how sensitive the contents are, and how much control you need over the resulting file.

The Three Approaches in Plain Terms

Before going deeper, here is the short version of what each path looks like in practice.

Manual, on your desktop. Open each file, copy pages, paste into a new document, save. Most operating systems now ship a stock previewer that supports page reordering and export.
Programmatic, in code. Use a library in Python, Node, Go, or your language of choice. A short script reads the input list, walks each page, and writes a new file. Pair it with a spreadsheet or CSV for the input manifest.
Web-based utility. Upload the source files, drag to reorder, click combine, download the result. No install, no code, no environment setup.

None of these is universally best. The rest of the article explains when each one earns its place.

When the Manual Route Actually Makes Sense

For a single merge involving two or three files you have already inspected, manual work is hard to beat. There is no setup overhead, no script to debug, and you can eyeball the result before saving. This is also the safest choice when the documents contain information you would rather not transmit to any external service — the operation never leaves your laptop.

The cost shows up the third or fourth time you do the same thing. If you find yourself repeating the same sequence of clicks every week, you are paying a hidden tax. That tax is the right signal to graduate to a script or a shared utility.

A quick mental test before going manual:

Is the file count below five?
Are you confident in the page order without writing it down?
Is this a one-time task, or at most a quarterly one?

If all three are yes, stay manual. If any is no, keep reading.

When a Script Earns Its Keep

Once the task repeats, or once you have more than a handful of files to combine, a short script pays for itself. Engineers usually reach for pypdf in Python, pdf-lib in Node, or unipdf in Go. A minimal example using pypdf reads like this:

from pypdf import PdfWriter

writer = PdfWriter()
for path in ["cover.pdf", "body.pdf", "appendix.pdf"]:
    writer.append(path)

with open("out.pdf", "wb") as f:
    writer.write(f)

The real value is not the ten lines of code — it is the input manifest sitting next to it. A spreadsheet or CSV that lists, in order, every file path and its role (cover, toc, chapter-1, appendix-a) turns the operation from a manual chore into a reproducible pipeline. Now any teammate can run the same script, and the order is reviewable in version control.

This path shines when:

You need a deterministic, auditable order.
The merge is part of a larger build or release flow.
You want to attach metadata (title, author, subject) programmatically.
Multiple people contribute files and the manifest is the contract.

The honest downsides:

You own the dependency, the Python or Node version, and the runner.
Output validation is on you — you need to spot-check page count, embedded fonts, and any password-protected inputs.
Scanned documents that started as images need OCR handled elsewhere before this step.

If you want to dig deeper into how a small build script can sit inside a larger document pipeline, the combine PDF vs PDF Portfolio decision guide walks through the underlying formats and when a multi-file container is actually the better answer.

When a Web Utility Is the Right Tool

There is a class of job that does not justify a script and does not fit cleanly into the manual column: an ad-hoc merge performed by someone who is not a developer, using files that are not sensitive enough to require an air-gapped workflow. Think of a freelancer packaging deliverables for a client, a sales rep assembling a proposal, or a student joining lecture notes.

A purpose-built online tool is the lowest-friction option for these cases. Drag the files in, reorder by drag-and-drop, click combine, download. Done in under a minute, with no install and no learning curve. For repeated personal use, bookmark the page and the next time around it takes seconds.

The trade-offs to weigh honestly:

Privacy posture. Files travel to a third-party server. For non-sensitive material this is fine; for medical, legal, or financial documents, it is not.
File size and count limits. Free tiers often cap total size or the number of source files. Check before you start.
No audit trail. You cannot easily show a colleague which version of which input produced today's output. If that matters, a script with a manifest wins.

A reasonable rule of thumb: if the inputs are public or already shared widely, and the output does not need to be reproducible from a record, a web utility is the pragmatic choice. If either of those conditions is false, fall back to manual or scripted.

A Decision Checklist You Can Reuse

Run through this list the next time you are about to combine documents. Pick the path that satisfies the most items.

Are the documents sensitive (PII, financial, legal, internal-only)? If yes, prefer local execution — manual or scripted.
Will this exact sequence of files need to be re-merged later? If yes, script it with a manifest.
Does the order matter and is it non-obvious from filenames? If yes, anything that lets you visually reorder before saving is worth it.
Are there more than five input files? Manual starts to break down here; lean toward scripted or web utility.
Does the output need to carry metadata such as title, author, or page numbers? Scripted gives the most control.
Is the person doing the merge a developer? If no, the choice is between manual and web utility.
Is the result subject to an audit or compliance review? If yes, scripted with a logged manifest is the safest answer.

If at least four of those land on "scripted," write the script. If at least four land on "manual" or "web utility," do not over-engineer it.

Validation You Should Never Skip

Whichever path you choose, the last step is the same: open the result and confirm three things before you send or archive it.

Page count matches expectations. A missing page from a bad read or a truncated download is the most common silent failure.
Embedded text is selectable, not rasterized. If you need to search or copy text later, this matters. Tools like pdftotext from the Poppler suite let you verify quickly.
Fonts render correctly. A missing font on a different machine can show up as boxes or substituted glyphs.

For deeper reading on the format itself, the PDF specification on Wikipedia is a reliable entry point, and the Adobe PDF 1.7 reference covers the structural details if you are working at the byte level.

Frequently Asked Questions

How do I know whether the merge actually preserved the original quality?

Page count and visual inspection are the first checks. For a stronger guarantee, extract text from a few representative pages using pdftotext and compare it to what you expect from the source. If the text comes out garbled or empty, the source was likely image-only and the merge is fine but the document was never searchable to begin with.

Can I merge password-protected files without removing the protection?

Yes. Both pypdf and pdf-lib accept an empty-password option for owner-locked files that simply restrict editing. For files with a real user password, you have to provide it during the read step. In every case, the merged output should have its own protection applied if the source had any.

What is the difference between merging and creating a PDF portfolio?

A merge produces a single document with continuous page numbering. A portfolio is a container that holds separate files and presents them under one cover, but each component stays independent. The right choice depends on whether the reader needs to extract one piece later or treat the whole thing as one document.

Is there a size limit I should worry about?

Practically, yes. Most viewers handle files up to a few hundred megabytes without complaint, but anything past a gigabyte starts to feel slow on lower-end hardware. If your inputs regularly push the merged result above that range, consider whether a portfolio or a download bundle would serve the reader better.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Resizing Images for Email Campaigns: A Frontend Engineer’s Playbook

Tea-sip — Sun, 09 Aug 2026 19:02:20 +0000

Email clients are the most hostile rendering environment most web engineers will touch this year. Outlook on Windows ignores CSS background images, Gmail strips <style> blocks from forwarded messages, Apple Mail ignores height on img if the source has a fixed width attribute, and every mobile client downsamples differently. Resize an image the wrong way and your carefully designed newsletter lands in the inbox looking like a captcha. Resize it the right way and it survives all of it.

This article is the playbook I wish I’d had when I inherited a transactional email pipeline that was shipping 1.4 MB JPEGs into a user base where 60% read on mobile networks. I’ll cover the sizing decisions, the HTML constraints, and the QA loop that catches regressions before they reach production.

Why Email Forces Different Rules Than the Web

The web has progressive enhancement. Email has progressive degradation: every client is the worst client. The HTML Living Standard treats <img> as a replaced element with intrinsic dimensions, but most email clients pre-process the markup, rewrite the DOM, and sometimes re-encode images before display. The result is that your pixel-perfect mockup in Litmus or Email on Acid is not the same pipeline your recipient sees.

A few constraints shape every decision below:

Outlook (Word rendering engine) still re-proxies images through a CDN and can recompress them. Sending a noisy JPEG gives it permission to make things worse.
Gmail’s web client strips images that are not https://, or that have a src attribute longer than ~2,000 characters. Every query string on a resizing CDN costs you headroom.
Apple Mail (macOS and iOS) respects srcset and sizes more reliably than Gmail does, but it caches aggressively and ignores cache-busting unless you rotate the entire cid:.
Dark mode clients (iOS Mail, Gmail iOS) may invert background colors. Transparent PNGs of UI chrome look fine; opaque JPEGs with baked-in backgrounds look like day-glo.

A safe default is a single image per visual concept, sized for the most common reading viewport, with CSS that holds it together if the image fails to load. That is the opposite of how you’d ship a hero image on a marketing site.

The Sizing Math That Actually Matters

I size once, in code, and reuse the numbers. Open the analytics for the last six issues of your newsletter on whatever platform you use, and pull the distribution of email client and viewport sizes. If you don’t have that, the approximate breakdown from Litmus’s annual email client market share reports is a reasonable starting point until you have your own data.

Three buckets cover nearly every case:

Slot	Logical width	Pixel width @2x	Pixel width @3x	Notes
Full-bleed	600 px	1200 px	1800 px	Banded hero, broken rarely
Two-column	280 px	560 px	840 px	Card images, product thumbnails
Inline/icon	48 px	96 px	144 px	Icons, avatars, badges

Three questions decide which bucket an asset belongs in:

What is the role of the image — hero, product, supporting, or functional?
At what width fraction does it sit in the 600 px content column?
What is the worst-case device pixel ratio you’ll target? iOS Safari goes to 3x on iPhone Pro Max; Android Chrome on mid-range hardware hits 2x and stops.

For 2x output I keep one master, resize to 1200 px wide, and re-encode. For 3x I generate a parallel 1800 px variant. I do not send both — I pick based on the dominant client. If your list is 70%+ iOS Mail, send the 3x master and let Android downsample. If your list is mixed Gmail and Outlook, ship the 2x master, because Outlook’s re-compression already costs you roughly 15%.

Choosing a Format That Survives the Pipeline

I default to a short decision tree rather than a rule, because the answer changes with the image type:

Photographic hero or lifestyle shot: JPEG, quality 78–82, mozjpeg if available. Strip the EXIF; email clients don’t display it and the metadata leaks PII.
Logo, line art, badges with text: PNG-8 with adaptive palette, or better, an SVG. SVG support in email is uneven — Gmail and Outlook strip it — so embed SVG only when you control both clients, and fall back to a high-DPI PNG otherwise.
Screenshots of UI: WebP is now supported in Apple Mail and Gmail iOS/Android, but Outlook does not render it. If your recipient set includes any meaningful Outlook share, stick with PNG. The extra 30% on file size is not worth a broken screenshot.
Animations or motion: Short looped GIF, but cap at 200 KB. Email clients do not autoplay GIFs silently above 1 MB on mobile data.

Format selection is downstream of resizing, not independent of it — a 1200 px image encoded badly in any format will fail Outlook’s re-compression tests. The MDN article on image file type and format guidance is a useful cross-check, especially the section on browser support, which overlaps about 80% with email client support.

A Practical Workflow You Can Run From a Makefile

Below is the loop I use, stripped of the proprietary tooling. Each step is its own command, so it slots into CI.

Audit the brief. Read the design spec and write down the role, target slot, and alternate text for every image in the issue. If the brief does not include alt text, ask for it. No image ships without it. Accessibility is non-negotiable; the W3C alt text decision tree is short and concrete.
Generate masters at 3x. A single convert (ImageMagick) or magick command resizes from the design source to 1800 px wide for full-bleed and 840 px for two-column. Lanczos resampling is fine for photos; bicubic for screenshots.
Encode for the target slot. Run separate passes at 1200 px and 1800 px. Strip metadata with mogrify -strip. Set JPEG quality 80 for full-bleed, 78 for two-column, 85 for inline icons.
Measure. Reject any output above the slot’s budget. A 1200 px JPEG of a clean lifestyle shot should not exceed 180 KB; a screenshot PNG should not exceed 220 KB. If it does, drop the width one step and re-encode.
Tag the file. Rename to {slot}_{role}_{2x|3x}.{ext} and drop into the email build directory. The naming makes it impossible for an editor to grab the wrong variant.
Render in a real client. Pin the campaign to Litmus or Email on Acid, or open in Mail.app and Outlook desktop, and screenshot. Compare to the design spec at 100% zoom on a 1x display and on a 3x display.

QA: The Three Screenshots That Catch 80% of Bugs

Most email regressions are visible in three screenshots, taken every run:

Outlook desktop on Windows, reading pane at default zoom. Look for stretched logos (a giveaway that the source aspect ratio didn’t match the width and height attributes), and missing alt text fallbacks.
Gmail iOS app on the latest iPhone, portrait, with the message open at the top. Scroll once and confirm that the second image renders crisp, not blurred. A blurred image means the 3x variant was uploaded to a 2x slot, or vice versa.
Apple Mail macOS with dark mode enabled. Confirm that any UI chrome sitting on the image has enough contrast in both modes. A common failure: a light-gray button PNG on a hero image that vanishes when the background inverts.

Anything that survives those three screenshots will survive the long tail. Anything that breaks one of them is fixed and re-run before the issue ships.

Trade-offs Worth Naming Out Loud

A few decisions that come up often and that I’ve changed my mind on over time:

File size versus image count. Twenty sharp small images beat eight compressed posters. Gmail’s pre-processor stalls on large combined payloads more than on small individual ones.
srcset versus a single 3x master. srcset is honored by Apple Mail and recent Yahoo/AOL webmail. It is ignored by older Outlooks. If your list has more than 15% Outlook desktop, ship one 2x master and accept the soft rendering on a Pro Max display. Most readers will not notice.
CDN resizing versus build-time resizing. CDN resizing (?w=1200) is convenient, but the resulting URLs are long, brittle, and stripped or shortened unpredictably by Gmail. Build-time resizing means losing flexibility but gaining predictability. For newsletters I prefer the latter.
Aspect ratio fixity. The image always declares its width and height attributes in the HTML, so the layout reserves space even when the image fails to load. For a deeper walkthrough on avoiding stretch and quality loss during the actual resize operation, the Lizely resize guide covers the resampling and aspect-ratio math in detail.

Frequently asked questions

Should I send retina/HiDPI images to every recipient?

Only if your list is dominated by Apple Mail iOS/macOS. For a mixed Outlook+Gmail+Apple Mail audience, a single 2x master is more reliable than a 3x variant delivered to a recipient who will downsample it anyway. Test with your own client distribution.

What’s the right JPEG quality for email?

Around 78–82 for hero and lifestyle photos, 85 for inline icons and avatars. Going higher adds bytes without visible gain in the inbox, because Outlook and Gmail both recompress during transit. Going below 70 introduces banding that is visible in flat-colored product shots.

Can I use WebP in transactional email?

Only if every client on your recipient list supports it. That excludes Outlook desktop and older Outlook for Mac. For mixed lists stick with JPEG/PNG; for pure Apple Mail + Gmail iOS audiences, WebP is fine and saves 25–30% on file size.

What’s the single biggest mistake engineers make resizing for email?

Fixing the rendered width but forgetting width and height attributes on the <img> tag. Most clients don’t compute aspect ratio from the image itself, so a missing attribute pair causes the layout to reflow, the next image to load shifted, and the entire grid to land wrong. Always declare both attributes, with the natural pixel dimensions of the variant you’re sending.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Designing a Solvability Gate for 15 Puzzle Implementations

Tea-sip — Sat, 08 Aug 2026 20:02:54 +0000

Every 15-puzzle implementation eventually hits the same quiet question: given a starting arrangement, can the player ever reach the goal? The answer is not obvious. Random shuffles fail roughly half the time, and a permissive build that lets the player play an unsolvable board wastes the user's evening. A strict gate that blocks too many starts kills engagement. Engineers building or integrating a sliding-tile game need a clear, testable rule, plus a way to debug it when their version disagrees with a reference solver.

This piece walks through the parity math behind the classic sliding puzzle, the edge cases that bite production code, and a short checklist you can drop into a code review. It is written for engineers, not for casual players — if you want the gameplay walkthrough, rules, and winning tips, the 15 puzzle rules and winning tips guide covers that side of the topic.

The Two-State Rule Most Codebases Get Wrong

The puzzle's state space splits cleanly into two connected components. From any reachable configuration, the parity of the permutation combined with the row of the blank tile determines which component the configuration lives in. The standard formulation:

Count the number of inversions — pairs (i, j) with i < j and value[i] > value[j], treating the blank as value 16 and ignoring it when it occupies a tile position.
Find the row of the blank tile, counted from the bottom (row 1 is the bottom row of the 4×4 grid).
The board is solvable iff either of the following holds:
- The blank is on an even row from the bottom and the inversion count is odd.
- The blank is on an odd row from the bottom and the inversion count is even.

That is the rule. Implementations get it wrong by counting inversions with the blank included, by counting the blank's row from the top, or by flipping both branches at once. Any one of those slips makes the gate accept unsolvable boards or reject solvable ones. Treat the two checks as a single boolean with a unit test on each side.

A useful reference for the underlying combinatorics is the Wikipedia entry on the 15 puzzle, which traces the parity argument back to the 1870s and explains why the two-component structure exists.

Why the Rule Is Not Enough in Production

A pure parity check protects you against random shuffles, but production systems accumulate state through player actions, save/restore, and import/export. Three concrete failure modes show up repeatedly:

Resume from a corrupt save. A user closes the tab mid-shuffle, the local storage writes a half-serialized state, and on reload the board is technically legal but unreachable from the current "shuffle seed." Reject these on load.
Drag-and-drop moves that bypass the grid model. A naive drag handler lets the user pick up a tile and release it two cells away. From the player's view it looks like two swaps; from the solver it is an illegal transition. Gate every input through the same move primitive.
Hint features that propose an illegal move. If your hint engine runs an A* search on a state graph but you forgot to apply the parity filter when seeding the search, you can return a move that pushes the board out of the goal's component. Pre-filter the start state before any search.

The fix in every case is the same: have one function isSolvable(state) -> boolean, call it on every transition that changes state, and never expose the underlying state object to other modules without that wrapper.

A Minimal Implementation in TypeScript

Here is a compact, testable version. It treats the blank as 0 internally and never lets the blank leak into inversion counting.

type Board = readonly (readonly number[])[]; // 4x4, values 1..15 plus one 0

export function isSolvable(board: Board): boolean {
  const flat = board.flat();
  let inversions = 0;
  for (let i = 0; i < flat.length; i++) {
    if (flat[i] === 0) continue;
    for (let j = i + 1; j < flat.length; j++) {
      if (flat[j] === 0) continue;
      if (flat[i] > flat[j]) inversions++;
    }
  }

  // Row of the blank, 1-indexed from the bottom.
  const blankIndex = flat.indexOf(0);
  const blankRowFromTop = Math.floor(blankIndex / 4);
  const blankRowFromBottom = 4 - blankRowFromTop; // 1..4

  if (blankRowFromBottom % 2 === 0) return inversions % 2 === 1;
  return inversions % 2 === 0;
}

Two tests worth pinning down before shipping:

The solved board ([1..15, 0]) is solvable — inversions is 0, blank is on row 1 from the bottom (odd), even inversions satisfy the branch. Returns true.
A swap of just 14 and 15 in the solved state is unsolvable — inversions jumps to 1, blank is still row 1, even branch rejects. Returns false.

If those two cases pass, you have eliminated about 90% of parity bugs.

Generating Shuffles That Are Always Legal

Once the gate exists, the natural next step is a shuffle primitive that never returns false. The simplest approach is rejection sampling:

export function shuffleBoard(rng: () => number): Board {
  while (true) {
    const flat = [0, ...range(1, 15)].map((v) => ({ v, k: rng() }));
    flat.sort((a, b) => a.k - b.k);
    const board = flat.map((c) => c.v).chunk(4);
    if (isSolvable(board)) return board;
  }
}

Rejection sampling is fine for small state spaces and human-scale runs, but the expected number of retries is close to 2, so the cost is negligible. If you are seeding thousands of puzzles per minute — leaderboards, daily challenges, classroom modes — consider a constructive algorithm: start from the solved state and perform a long random walk of legal moves. Any walk from the solved state is, by construction, in the same connected component. This guarantees one valid output per walk and avoids the loop entirely. The walk length matters: fewer than ~50 moves produces recognizably ordered boards; 200+ looks random to players.

For a deeper look at random walk length and perceived randomness in puzzle generation, the JavaScript reference on typed arrays is a useful reminder that any RNG path you pick should produce reproducible output when seeded, so daily challenges are reproducible across users.

Debugging When Your Solver Disagrees With a Reference

A common debugging story: a tester solves the puzzle, your completion counter does not increment, and the state you serialized looks solved. Three checks, in order:

Re-serialize and re-run isSolvable on the result. If it returns false, your move handler produced an illegal transition. Walk back through the last move and confirm the move primitive is the only path to mutate state.
Compare the serialized state to the canonical solved state byte-by-byte. Tile-by-tile equality is the only valid completion signal. Do not compare hashes, do not compare "all tiles in correct position except blank" — the only correct solved state has the blank in the bottom-right corner.
Replay the user's move log against a known-good solver. If your solver refuses the final move, your solver is wrong; if it accepts but your counter does not fire, your completion signal is reading stale state.

A reviewer-friendly way to enforce this: keep isSolvable, applyMove, and isSolved in the same module, expose them through a single barrel, and forbid direct state mutation outside that module. A grep for board[...]= outside the file should be a code review failure.

Checklist for the Code Review

Before approving a 15-puzzle change, verify:

[ ] Every public mutation goes through a move primitive that updates the blank position and the tile permutation atomically.
[ ] isSolvable is called on every external state entry point: shuffle, save restore, URL-import, and seeded challenge load.
[ ] The solved-state check is strict tile equality with the blank at index 15, not a heuristic.
[ ] At least one unit test pins the parity rule with the blank on an even row from the bottom and one with an odd row.
[ ] The shuffle path is either rejection sampling with a bounded retry count, or a constructive random walk of length 100+.
[ ] No PDF, download, or vendor-specific link appears in error messages; failures resolve to stable docs.

That checklist, plus the parity function above, will catch every solvability regression I have seen in shipped builds.

Frequently Asked Questions

Does the parity rule change for 3×3 or 5×5 sliding puzzles?

Yes — the rule generalizes to any NxN board with a single blank. For odd-width grids (3×3, 5×5) the rule collapses to a single inversion parity: solvable iff the inversion count is even. For even-width grids the blank-row term appears, exactly as in the 4×4 case. The derivation is on the Wikipedia page linked above and is worth a careful read if you ship multiple sizes.

How do I handle boards imported from a URL or QR code?

Treat the import as untrusted. Run isSolvable on the deserialized state and refuse to load if it fails, with a clear message. Optionally offer a "shuffle to a solvable state" button so the user is not stranded. Never silently rewrite the user's input — they may be testing your gate.

Can the parity rule be bypassed to add "cheat" features like swapping any two tiles?

Technically yes — any state is reachable if you let the user perform arbitrary permutations — but doing so breaks every downstream feature that assumes the two-component invariant, including hint engines, save compatibility, and leaderboard validation. If you must ship a "free play" mode, isolate it behind a flag and never let its state cross into the main mode's persistence layer.

What is the smallest number of moves guaranteed to solve any legal state?

The worst-case optimal move count for the 15 puzzle is 80, established by exhaustive search. If your hint engine proposes more than 80 moves to a solved state, your search is misconfigured; if it proposes fewer for a legal state, your state is misconfigured. Use 80 as a sanity bound during development.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Picking the Right Video Compression Path for Web Delivery: A Practical Decision Guide

Tea-sip — Fri, 07 Aug 2026 19:03:07 +0000

When a web team owns video assets, the hardest part is rarely the encoding itself — it's choosing a workflow that fits the team's constraints. Files arrive from product shoots, screen recordings, partner agencies, and customer support screen captures. Each one has a different source size, codec, and deadline. The goal here is to walk through three realistic routes engineers take to shrink those files for web distribution, lay out the honest trade-offs of each, and point to a deeper reference when the team needs more background.

Why "Just Use HandBrake" Is Often the Wrong Starting Point

HandBrake is excellent software, but it solves the wrong problem for most web teams. It's tuned for personal archival and one-off encodes. A team shipping updates every week runs into three recurring pain points:

Per-machine inconsistency. Two engineers on macOS and Windows will produce slightly different output even with identical settings, because of the underlying toolchain versions. Reviewers end up chasing visual regressions that aren't real.
Preset drift. Someone tweaks a preset, the change isn't documented, and six months later the original spec is gone.
No audit trail. There's no built-in log of which file went through which profile on which date. When QA flags a regression, the answer is usually "we think this is the May preset."

For a single freelancer uploading one reel, none of this matters. For a four-person product team responsible for 200 clips, it's a recurring tax.

Path 1: The Command-Line Pipeline (FFmpeg + a Config Repo)

This is the route most engineering-led teams eventually settle on. The shape is consistent:

A Git repository holds presets/ (JSON or shell snippets), inputs/ (filenames and SHA256), and outputs/ (file paths and target sizes).
A single shell script or Makefile wraps the ffmpeg invocation.
CI runs the encode on every push, so the same binary produces the same artifact across machines.

A minimal example for a 720p web clip:

ffmpeg -i input.mov \
  -c:v libx264 -preset slow -crf 21 \
  -vf "scale=-2:720" \
  -c:a aac -b:a 128k \
  -movflags +faststart \
  output.mp4

The +faststart flag matters more than people realize. It relocates the moov atom to the front of the file, which lets the browser begin playback before the full download completes. Without it, the entire file must load before the first frame renders, which kills the perceived performance of any video under five seconds.

The trade-offs:

Pros: Reproducible, scriptable, CI-friendly, supports any input format FFmpeg can read.
Cons: Engineers own it. Non-technical teammates can't run an encode without help. Encoding speed on commodity laptops is slow without libx264 tuned flags or hardware acceleration.

This path fits when the team already has a deployment pipeline and treats video assets the same way they treat JavaScript bundles — built, versioned, and deployed from a single source of truth.

Path 2: The Spreadsheet-of-Bitrates Workflow

Marketing-led teams frequently land here because it lets non-engineers participate. The pattern looks like this:

A spreadsheet lists every clip, its source duration, source resolution, and target distribution context (landing page hero, blog post inline, email thumbnail).
Each row has a column with a target bitrate in kilobits per second, picked from a small lookup table (e.g., 1080p = 2500 kbps, 720p = 1200 kbps, 480p = 600 kbps).
A formula computes the expected output size: bitrate_kbps × duration_seconds / 8 / 1024 = megabytes.
Someone runs the encode manually using those numbers.

The bitrate math is straightforward enough that it survives in a shared doc for years. The spreadsheet is the contract between the person who records the footage and the person who encodes it.

The trade-offs:

Pros: No code to maintain. Anyone on the team can update it. The size estimates are good enough to promise delivery budgets to stakeholders.
Cons: Manual execution is slow and error-prone. There's no enforcement that the actual encode matched the plan — someone can write 1200 kbps in the sheet and ship a 4000 kbps encode by mistake.

This path fits when the team produces fewer than 20 clips a month and one person is willing to own the encode queue as a recurring chore.

Path 3: A Browser-Based Tool for One-Off Conversions

Not every clip needs to enter a pipeline. A customer success manager recording a 30-second screen walkthrough for a support ticket doesn't want to clone a repo, push to CI, and wait for a build. They want to drop a file in, pick a target, and move on.

This is where a lightweight in-browser compressor earns its place. The key engineering concern is that the conversion must actually happen client-side. If the file uploads to a server, two things go wrong: the upload itself takes longer than the encode would have, and the file leaves the user's machine, which is a non-starter for assets under NDA.

The browser tool approach has gotten more practical in recent years thanks to two browser-side capabilities that have stabilized. The first is broad codec support in the <video> element, which means most inputs can be decoded without server help. The second is WebAssembly builds of common codec libraries, which let tools encode entirely in the browser without a round trip. For background on the codec landscape and which formats browsers can actually decode today, the MDN guide to media container formats is the right starting point. For the bitrate math that determines output size, Wikipedia's article on bitrate gives the underlying formula without vendor framing.

The trade-offs:

Pros: Zero install, works on a colleague's laptop, fast for files under 200 MB, no pipeline to babysit.
Cons: Output is harder to reproduce across runs because the browser environment varies. Not appropriate as the team's only path for high-volume work.

This path fits when someone needs a single file shrunk in the next five minutes and there is no engineer available.

A Decision Checklist for the Next Clip

When a new file lands in the queue, walk through this ordered list before picking a path:

Will this clip be published more than once? If yes, the CLI pipeline (Path 1) is the right home — reproducibility pays off the second time.
Is the file under 200 MB and needed in the next hour? A browser-based compressor is faster than waiting on CI.
Does the team have a single owner who will encode manually every time? If yes, the spreadsheet workflow (Path 2) is sustainable. If no, it isn't.
Is the asset under NDA or contains customer data? Verify the chosen tool processes locally. Server-side uploads are a hard no.
Will the result play on mobile Safari? Test on a real device before shipping. Encodes that look fine on a desktop Chrome can fail on iOS due to codec profile mismatches.

What I'd Actually Recommend

For most teams starting from zero, the right move is to build Path 1 once and accept that Path 3 will still happen informally. The CLI pipeline handles the 80% of clips that go to production. The browser-based tool covers the long tail of one-off requests where the pipeline is overkill.

Path 2 — the spreadsheet — is a transitional state. It works, but it tends to collapse into Path 1 within a year as the volume grows. If the team is already at scale, skip it.

When the team needs a deeper walkthrough on the codec choices, target sizes, and quality trade-offs that sit underneath all three paths, the Lizely guide on compressing video files without losing quality online covers the background in more depth than fits in a decision article.

Frequently Asked Questions

Does client-side compression match server-side quality?

For most web targets, yes. Browser-side encoders running through WebAssembly produce files within a few percent of server-side output at the same target bitrate. The gap shows up at very high resolutions (above 4K) or when the encoder lacks hardware acceleration.

How small should a web clip actually be?

A reasonable budget for a hero video is roughly 1 MB per second of playback at 1080p, and 0.5 MB per second at 720p. Anything larger and the bandwidth cost starts to dominate the design budget.

Can a single team use more than one path?

Absolutely. Most teams do. The mistake is treating the browser-based tool as a replacement for the pipeline. It complements it by handling the small, ad-hoc requests that would otherwise clog the queue.

What about format choice — MP4 vs WebM?

MP4 with H.264 is still the safest default because every browser, TV, and phone can play it. WebM with VP9 or AV1 delivers smaller files at equivalent quality but isn't universal yet. If the audience is known to be on modern browsers, AV1 is worth testing; otherwise, MP4 is the right baseline.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

QA-Testing Audio Trimming Workflows Before You Ship a Web Editor

Tea-sip — Fri, 07 Aug 2026 03:38:15 +0000

If you're building — or integrating — a browser-based audio trimmer, the question that eventually reaches your inbox isn't "does it cut audio?" The real question is: does it cut audio correctly across the inputs we actually receive from users? That shift, from feature presence to behavior under fuzzy conditions, is what turns a demo into a product. This article walks through the QA matrix I use when reviewing client-side trimmers before release, with an emphasis on the silent failures that don't show up in a happy-path recording.

The tool under review for most of this article is the Lizely audio cutter (in-depth walkthrough), but the principles apply to any browser trimmer that decodes via AudioContext or OfflineAudioContext.

What "Trim" Actually Means Once You Leave the Lab

In the lab, you upload a 44.1 kHz stereo WAV, drag two handles, click export, and verify the output. In production, users upload M4A recordings from iPhone Voice Memos, AMR files from old Android handsets, mono 8 kHz captures from cheap conference mics, and — occasionally — files renamed from .wav to .mp3 without re-encoding. Each of those paths stresses a different layer of the pipeline.

The first thing to test, before any UI work, is the decode step. Browsers expose this through the decodeAudioData method on BaseAudioContext, documented on MDN's BaseAudioContext page. MDN is explicit about something engineers often miss: decodeAudioData detaches the input ArrayBuffer. If your trimmer holds a reference to the original buffer for "undo" and reuses it, you'll decode an empty buffer the second time around and get a silent result. That's a real defect class, not a theoretical one.

The second thing to test is what happens when decoding fails. The spec says decodeAudioData invokes the error callback with a DOMException, but the browser-specific error messages vary. Chrome tends to surface "Decoding error" with no detail; Firefox appends the underlying codec name. Your QA suite should assert on the callback being invoked, not on a particular string — otherwise you'll chase platform-specific noise forever.

The Input Matrix I Run Before Sign-Off

For every trimmer I review, I keep a fixed matrix of inputs. The columns change per project, but the rows are stable. Here's the version I use for a generic web trimmer targeting consumer audio:

Container/codec combinations. MP3 (CBR and VBR), WAV (PCM 16-bit and 24-bit), FLAC, M4A (AAC-LC and HE-AAC), OGG Vorbis. At minimum, three of these.
Sample rates. 8 kHz, 16 kHz, 22.05 kHz, 44.1 kHz, 48 kHz. The 22.05 kHz case catches tools that assume CD-quality input.
Channel layouts. Mono, stereo, and — if you support it — 5.1. Most consumer editors don't, but you should at least fail cleanly on multi-channel input rather than silently downmixing to mono with a phase-inverted side.
File sizes. Under 1 MB, around 50 MB, and the "I exported my entire podcast feed by accident" case at 500+ MB. The last one is where memory budgets explode.
Duration edge cases. Files shorter than the minimum selection window (some trimmers enforce a 1-second floor), files longer than OfflineAudioContext will render without chunking, and files whose total length is not an integer number of seconds.

Each cell in that matrix gets two assertions: the trim completes without throwing, and the output's first/last sample timestamps match the UI's reported selection within a tolerance that depends on sample rate. For 48 kHz audio, a tolerance of one sample is roughly 20 microseconds — tight enough to catch rounding bugs but loose enough not to fail on legitimate resampling.

Sample-Accurate Timing vs. Frame-Accurate Timing

A subtle source of QA failures is the difference between sample-accurate trim points and frame-accurate ones. MP3 is encoded in frames of 1152 samples (for MPEG-1 Layer 3) — see the MPEG-1 Layer III Wikipedia article for the framing details. That means you cannot start an MP3 decode at an arbitrary sample index; you have to start at a frame boundary and discard the leading samples.

In practice, a browser trimmer sidesteps this by decoding the whole file into an AudioBuffer and then slicing the in-memory representation. The frame boundary becomes irrelevant once you're working with raw PCM. But if your architecture ever goes near the encoded bitstream — for example, to avoid decoding a 3-hour file into memory — you need to know that any "sample 4,823,104" you report to the user is meaningless until you account for the encoder's framing.

The test I run for this: pick an MP3, ask the trimmer for a selection that starts at, say, sample 1000 (not a frame boundary), and verify that the output starts at exactly that offset in the resulting PCM. If the tool silently snaps to frame boundaries, the user gets a clip that's a few milliseconds earlier or later than the UI shows. That's a defect worth filing, even if most users never notice.

Memory Budgets: The Constraint That Kills Browser Editors

The most common production failure I see isn't a logic bug — it's the tab crashing because the editor tried to hold a 600 MB decoded buffer in memory. AudioBuffer stores Float32 PCM, so a stereo 48 kHz file of duration d seconds consumes roughly d × 384 KB. A 60-minute podcast is about 1.4 GB. Most desktop browsers will allocate that, eventually, but mobile Safari will not.

The QA angle here is: at what file size does your trimmer stop working, and what does it tell the user? Acceptable answers include "we reject files over X MB with a clear message" or "we chunk-decode and never hold more than Y MB at once." Unacceptable answers include the silent hang followed by the tab being killed by the OS.

A practical test: upload the largest MP3 your matrix allows and watch the browser's memory profiler. If you see peak heap usage approaching the file's decoded size * 2 (input plus output), you have a problem. If it stays flat regardless of input size, you're chunking correctly.

The OfflineAudioContext Render Trap

If your trimmer uses OfflineAudioContext to render the trimmed region — and most do, because it's the cleanest way to apply fades, gain, or format conversion — there's a render-length limit that varies by browser. Chrome has historically capped OfflineAudioContext at a total render length related to the source's duration; Safari is stricter. Long files combined with fade-out tails can exceed these limits silently.

The test: take a file that's near your maximum supported duration, apply a 5-second fade-out, and render. If the result is truncated, you've hit the limit. The fix is usually to chunk the render into segments and concatenate, but that's its own QA exercise — concatenation bugs are easy to introduce and hard to spot by ear.

A Pre-Ship Checklist for Browser Audio Trimmers

Before signing off on a release, I walk through this list with the engineering owner:

Confirm decodeAudioData does not retain references to the source ArrayBuffer.
Verify the error callback is wired and surfaces a user-readable message.
Run the input matrix above with at least one file per row.
Assert output sample timestamps match UI-reported selection within tolerance.
Profile peak heap usage on the largest supported input.
Test OfflineAudioContext renders at maximum supported duration with fades applied.
Verify behavior on mono, stereo, and multi-channel inputs (even if multi-channel is unsupported — fail loudly, don't silently downmix).
Confirm the export format's metadata (artist, title, album) is either preserved or explicitly stripped, not partially copied.

Frequently asked questions

How do I decide whether to decode in memory or chunk-stream?

Decode in memory when files are under ~50 MB and you need random-access trimming. Chunk-stream when you support hour-long inputs or mobile users with memory-constrained devices. The cutoff depends on your target audience; for podcast editors, in-memory is fine. For music production tools, chunk-streaming is mandatory.

What's the right way to test sample-accurate trim points?

Decode a known test tone (sine wave at a specific frequency), trim a region whose boundaries fall between zero crossings, and verify the output's first and last samples match the requested indices exactly. Use a small tolerance for floating-point comparison, but the trim point itself should be exact.

My trimmer works on Chrome but fails on Safari. Where do I start?

Check OfflineAudioContext length limits first — Safari is stricter than Chrome. Then check decodeAudioData support for your codec matrix; Safari ships fewer free codecs. Finally, inspect any uses of AudioWorklet or AudioBuffer.copyFromChannel, which have had varying levels of support across Safari versions.

Should I preserve or strip metadata from the trimmed output?

Default to preserving, but be explicit. Users who trim a podcast for a clip often want the original title and artist preserved; users who trim a voice memo for privacy often want everything stripped. The right answer is to expose the choice in the export dialog, not to guess.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Engineering a Shared Reference Clock for Distributed Teams: Rules, Drift, and Recovery Playbooks

Tea-sip — Sun, 02 Aug 2026 20:03:59 +0000

When a backend incident fires at 02:47 UTC, a payroll export runs late in São Paulo, or a deploy window opens for a Singapore office, the question "what time is it where they are?" stops being trivia and becomes a debugging primitive. Distributed teams keep three or four reference clocks side by side, often in the same browser tab. The hard part is not the display — it is agreeing on the rules underneath.

This article walks through the data structures, protocol references, and operational playbooks I lean on whenever a shared wall clock has to be trustworthy across continents. It complements the practical setup guide, which you can find here: Change Your World Clock in Seconds with This Free Tool.

The Data Layer Behind Every Display

A clock widget renders one number, but the inputs to that number are layered. From the ground up:

A monotonic counter. Most platforms expose a millisecond- or nanosecond-resolution timestamp tied to a chosen epoch. JavaScript hands you performance.now() relative to navigation start, and Date.now() in epoch milliseconds; both are sourced from the same system clock but answer different questions. For wall-clock semantics you almost always want the latter, cross-checked against a network time source.
A UTC offset at the current instant. Time zones are not static vectors. They are functions of (UTC instant, civil location, historical database version). The IANA tz database — version 2024b at the time of writing — encodes those functions, including the transitions in 2011 when Samoa skipped an entire calendar day and the multiple DST rules that have changed in regions like Morocco and Egypt. Anyone representing local time as a fixed offset is hiding this layer.
A formatting rule. ISO 8601 gives a deterministic string for any instant, but humans still want "Mon, 14:30". The CLDR repository, mirrored by Unicode, owns the locale-data tables behind that rendering, including whether noon is rendered as 12:00 PM or 24-hour 12:00.

If your "clock" is doing all three steps inline without an explicit boundary between them, the next time someone changes a DST rule upstream you will spend a day grepping the codebase.

The Four Reference Points I Trust in Production

When I audit a system that mishandles civil time, the fix usually comes from one of four canonical sources. Pick the one that matches your trust boundary:

IANA tz database (/usr/share/zoneinfo, mirrored at iana.org/time-zones) — the source of truth for offsets and transitions. Every operating system ships it; every language runtime forwards to it indirectly. Treat any hard-coded offset list as suspect.
NTP and its successors. NTP version 4, documented in RFC 5905, is the protocol that keeps the monotonic counter honest. For sub-second accuracy without dedicated hardware, NTP can usually hold a workstation within tens of milliseconds of a stratum-1 server. Chrony, ntpd, and systemd-timesyncd all speak it.
Roughtime. Google, Tailscale, and others published Roughtime as a deliberately simpler, auditable alternative — signed timestamp responses without the full NTP state machine. Useful when you want a verifiable audit trail rather than tight jitter.
Leap-second tables. The IERS publishes Bulletin C and the leap-second table referenced by POSIX tzdata. Treat 2016-12-31 23:59:60 as a reminder that civil time is not always a clean bijection with atomic time; UT1 vs TAI differences occasionally matter for systems that aggregate logs across a leap boundary.

A robust shared clock consumes from at least two of these so that a single source's bug — for instance, a tz database update that flipped Argentina's rules mid-cycle — cannot propagate silently.

Mapping Civil Location to an Offset: The Five-Step Procedure

Given an arbitrary user-entered city or IANA zone identifier, the canonical procedure for a backend service is:

Normalize. Lowercase, strip punctuation, fold common aliases ("NYC" → "America/New_York"). Keep the original string in logs for audit; never trust the normalized form alone.
Resolve against the tz database. If the input matches an IANA identifier, you are done. If it is a free-form city, look it up against your own curated city-to-zone table — populated from zone.tab — and flag any miss for review. The Wikipedia entry on tz database documents the file layout.
Compute the offset for the target instant. This is not getOffset(); it is the offset function offset(t) = local(t) − UTC(t) evaluated at the instant of interest. Most libraries expose this as DateTimeFor(t).offset.
Format using CLDR locale data. Pass the resolved zone plus the user's language tag into an ICU formatter. Do not hand-roll AM/PM logic.
Persist the resolved IANA identifier, not the offset. DST changes; identifiers are stable. Storing offsets is a classic postmortem root cause.

If step 2 fails, do not silently fall back to UTC. Return an explicit unresolved state and surface it in the UI. The cost of a wrong fallback during a scheduling meeting is much higher than the cost of an empty clock row.

Drift, Skew, and the Things That Go Bump at 02:00 Local

Three failure patterns recur in cross-region incidents:

Container clock drift. A container running for months without an NTP sync can drift minutes per day if its host kernel is virtualized without kvm-clock. Always run chrony or systemd-timesyncd inside long-lived containers; never assume the host is honest.
DST transition windows. Brazil abolished DST in 2019, Chile abolished it for most regions in 2015, and Mexico's border municipalities follow US rules while the rest of the country does not. A scheduled job that ran at "02:30 local" pre-transition can land at "03:30 local" post-transition without a code change. Encode jobs in UTC and project to local at display time only.
ISO week vs fiscal week. ISO 8601 defines weeks starting Monday and the first week containing a Thursday as week 1. Your finance team may use a different definition. Coordinate the conversion in one place — usually a week_of_year(civil_date, locale) helper — not in thirty scattered report queries.

When triaging an incident that touches civil time, the first three questions to ask are: what is the UTC instant, what is the IANA zone the operator believes they are in, and what is the IANA zone the system actually applied. Almost every confusing report becomes clear once those three values are written down explicitly.

A Playbook for Cross-Region Coordination

Here is the checklist I run through before announcing a maintenance window that touches more than one region:

State the window in UTC first, then list local projections for every participating region.
For each region, confirm whether the window crosses a DST or offset transition.
Verify that the region's tz database version is current on every host that will execute work in the window.
Identify the human on call in each region and the local civil time at which they pick up.
Capture the IANA identifier and offset for each on-call location in the runbook, so a responder searching the document at 03:00 does not have to recompute it.
After the window, archive the wall-clock times of every event in the postmortem with their UTC equivalent.

If your team needs a quick reference display while executing that playbook, a lightweight world clock widget on the incident channel removes the cognitive load of converting in your head. The tool linked at the top of this article is built for that exact workflow — keep the runbook authoritative and use the widget as a verification surface, not as the source of record.

When to Compute, When to Trust the Wire

Not every system should compute civil time itself. If you are displaying time that originates from an API, the safest pattern is to propagate the producer's formatted string plus the IANA zone plus the source instant, then reformat on the consumer side. This is the same pattern W3C Date and Time Formats recommends for datetime interchange. Avoid shipping pre-formatted local strings to downstream consumers; they will silently disagree with whoever computed them.

For client-only displays, prefer the platform's built-in Intl.DateTimeFormat with an explicit timeZone option. MDN documents the Intl.DateTimeFormat constructor and the IANA time zone names the constructor accepts. This guarantees that the offset you see came from the same tz database your server uses, modulo the user's update cadence.

Closing Thought

A trustworthy shared clock is mostly a discipline problem: name your sources, version your tz data, store identifiers instead of offsets, and project to local only at the edge. Once those rules are in place, the wall-clock widget becomes what it should be — a quiet confirmation that the numbers in your runbook match the numbers in your head.

Frequently asked questions

What is the minimum data I need to display correct local time?

You need an IANA tz identifier for the location and the UTC instant you want to project. From those two inputs, any compliant library can derive the formatted string using the current tz database. An offset alone is not enough, because the offset can change for the same zone across the year.

How often should I update my tz database?

Most operating systems ship tz database updates via standard patch channels and apply them automatically. For servers that handle scheduled jobs, I treat a tz database bump as a low-priority maintenance event and confirm it within a week of release. Critical infrastructure should pin the version it was tested against and audit changes before promotion.

My container's clock keeps drifting — what should I check?

Confirm that NTP or chrony is running inside the container and can reach a time server. If your orchestration platform freezes process clocks for snapshots, that can look like drift after a resume. On most clouds the hypervisor's paravirtualized clock (kvm-clock, tsc) is good enough that host-side NTP is sufficient, but verify with chronyc tracking rather than trusting the clock face.

Is it safe to store local times in my database?

No, unless the field is purely for display after the fact. Persist UTC instants for events and IANA identifiers for user preferences, and project to local at query time. Storing a formatted local string means every future DST or policy change misrepresents your historical data.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Picking a Random Name From a List: A Practical Decision Guide for Engineers

Tea-sip — Sun, 02 Aug 2026 02:05:11 +0000

Rolling a name out of a hat sounds trivial until you actually have to do it in front of people. When fairness matters, when the list changes every session, and when someone will inevitably ask "but is it really random?", the method you choose quietly shapes how much credibility you have. This guide walks through three realistic approaches — pen and paper, a spreadsheet, and a purpose-built wheel — and tells you when each one earns its keep.

Why the Method Matters More Than the Wheel

A draw is only as trustworthy as the process behind it. If the audience cannot reproduce it, the result is just a coin flip someone else flipped. If the host can quietly retry until a "good" outcome comes up, the result is theatre. Psychology research on fairness perception, summarized in part by Wikipedia's Random assignment entry, suggests that visible process often matters as much as the outcome itself. That is why the choice of mechanism — not just the spinning animation — is the actual engineering decision.

Concretely, the questions you should answer before picking an approach are:

How many entries are in the pool, and how often does it change?
Does every entry need equal odds, or do some deserve more weight?
Will the draw be live in front of people, or run offline?
Do you need an audit trail — timestamps, the exact list used, the seed value?
Will non-technical teammates be able to run it without help?

A draw for a Slack channel of twelve people bears no resemblance to one for a three-hundred-person conference, and the tooling should follow the situation, not the other way around.

Approach 1: Doing It by Hand

Slips of paper, a deck of cards, or a hat still work. Write each item on an identical slip, fold them the same way, drop them into a container, and have someone else draw. This is the original pseudorandom device, and it has real advantages.

Transparency: everyone watches the physical shuffling.
Zero dependencies: no electricity, no browser, no spreadsheet license.
Pedagogically rich: good for explaining probability to kids or trainees.

Trade-offs are real, though. You cannot easily weight entries without writing numbers on the back of slips and doubling some, which the audience will notice and may dispute. You cannot add or remove an entry mid-session without a recount. And with fewer than roughly thirty slips, physical imperfections (size, thickness, how tightly folded) introduce subtle bias. As the pool grows, manual draws become slow and error-prone.

Hand-drawn methods earn their place when the audience is small, the stakes are low, and the ritual itself is the point — a team lunch, a classroom exercise, a wedding. They do not scale, and they resist automation or audit.

Approach 2: A Spreadsheet With a Random Number

For repetitive draws, a spreadsheet is the path many engineers reach for first. One column holds the pool, a second column uses RAND() or RANDOM() to produce a value, sort by that column, and the top row is your winner. If you need weighting, multiply the random value by a weight column or use INDEX with MATCH against a cumulative distribution.

This shines when:

You want reproducibility. Most spreadsheets expose the seed via the recalculation state, and you can save a snapshot.
You need to attach metadata. A timestamp column, a session ID, and a hash of the pool turn the draw into evidence.
You are integrating with other workflows. A CSV export feeds downstream reporting.

The costs are subtler. Spreadsheet RNG is documented in vendor docs but rarely audited by the user — a quick read of the Mozilla Developer Network entry on Math.random shows that it is not suitable for cryptographic or fairness-critical use, and the same caveat applies to most spreadsheet implementations. Sorting also changes the visible structure, which can be confusing in a live demonstration. If a non-technical teammate will run this, count on spending twenty minutes documenting the steps.

A spreadsheet is the sweet spot when you are running dozens of draws a week, need an audit trail, and are comfortable owning the procedure yourself.

Approach 3: A Purpose-Built Online Wheel

When the draw is public and the audience expects something to spin, a dedicated tool reduces friction. The core requirements are simple: paste a list, spin, and show a result. The interesting engineering questions are the ones the tool abstracts away — how the underlying selection is implemented, what happens when the list contains duplicates, and whether a screenshot is enough to back the claim.

For a one-off session or a recurring public draw, a web-based picker handles the parts that slow down hand-built solutions. A walkthrough of the fair-spin method, including how to scrub the list, what to record, and how to spot a rigged animation, is laid out in the fair-spin guide on Lizely, which is the most thorough reference I have found on the procedural side.

What a wheel does not solve:

It does not generate your list. You still need to decide who is eligible.
It does not store history unless you do. Save the screenshot and the input list yourself.
It does not replace the social contract. If your audience does not trust the host, a fancier animation will not save you.

Where it wins is in the mundane middle: a team standup, a giveaway in a streamed session, a classroom lottery that runs every Friday. The overhead is roughly a minute of setup, and the result is something people can watch without explanation.

A Checklist for Choosing Your Method

Before reaching for any tool, walk through this:

List the pool size and the expected variance week to week.
Decide whether equal odds are required, or if some entries should be more likely.
Identify who runs the draw and whether they can be trained.
Define what proof of fairness you need to keep — a screenshot, a log row, a witness signature.
Pick the lightest method that satisfies all four constraints.

If you can answer "manual, equal odds, I run it, a witness is enough", then slips of paper are correct. If you need "automated, weighted, anyone on the team, plus a log", the spreadsheet is right. If you need "live, public, light-touch, reversible within one session", use a wheel.

A Worked Example

Consider a fifty-person engineering org running a monthly "demo lottery" where one slot is drawn to present at the all-hands. The pool is built from a query against the HR database, so it is fresh every month. The host rotates among managers, most of whom do not write code. Auditors will ask, twice a year, whether a given draw was fair.

A spreadsheet is appealing but creates a support burden: every new manager needs the template explained, and the file lives in someone's drive. Hand-drawing is too tempting to cheat with when the prize is visibility. A wheel, run from a shared link with a standardized list, keeps the procedure identical regardless of who is hosting. The screenshot plus the exported list is the audit trail.

That is the pattern worth internalizing: when the host changes and the audience persists, standardize the tool first and the conversation second.

Frequently Asked Questions

How do I know the draw is actually random if I use a tool I cannot inspect?

You cannot fully. What you can do is run the same tool many times in private, compare against a known-good source like a spreadsheet, and confirm that the distribution matches. Treat the tool as a black box you have validated, not as an oracle.

Should I include duplicates or aliases in the list?

No. Build a canonical list first with one row per real entity. If "Alex" appears twice, you have already biased the draw before the tool even runs. Normalize the input, then put the list through whichever picker you are using.

What is the smallest defensible audit trail?

A timestamp, the exact list used, a screenshot of the result, and the name of the host. If your process is challenged, those four artifacts answer ninety percent of the questions a reasonable observer will ask.

Can I reuse one list for every draw in a series?

You can, but it is rarely wise. Pools shift — people leave projects, new joiners appear, eligibility rules change. A draw that used a stale list is not unfair, but it is unauditable, and that is almost the same problem.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

Designing QR Codes That Survive Real-World Scanning: A Debugging Playbook

Tea-sip — Fri, 31 Jul 2026 19:02:30 +0000

A QR code can look perfect in your browser and still fail on a printed flyer behind glass, on a wrinkled shipping label, or under a flickering streetlight at dusk. When you treat generation as a one-step drop into a designer, you skip the constraints that decide whether the code is actually scannable in the field. This article walks through the engineering decisions that show up after you hit "download" — the ones that decide whether your audience scans cleanly or gets a "Could not read code" error.

We'll treat the QR code as an input/output system: inputs are the data payload, version, error correction level, and module size; outputs are reliability across distance, lighting, surface, and reader hardware. Most production failures trace back to a mismatch between those inputs and the physical medium.

Understand the Encoding Budget Before You Pick a Version

Every QR code carries a fixed payload capacity per version and error-correction level. Version 1 holds up to 25 alphanumeric characters at level L (low correction), but the same symbol only holds 14 characters at level H (high correction). Version 10 jumps to 271 alphanumeric characters at L but drops to 213 at H. The QR specification defines 40 versions, and the structural choices ripple outward into module density and quiet-zone requirements.

This matters because the code's module count drives the physical size you need. A Version 10 symbol at the same module pitch as a Version 2 symbol needs more space per side to stay scannable. The International Organization for Standardization's ISO/IEC 18004 standard is the canonical reference for these tables, and the QR Code Wikipedia overview summarizes version/capacity trade-offs in plain language. If your payload sits near a version boundary, a single extra URL parameter can bump you up a version, which then changes the minimum print size.

Practical rule: before generating, compute the version your payload needs at your chosen ECC level. If you can drop to L for a URL under 60 characters, you'll get a less dense code that scans from farther away at the same physical size. If you must use H because you're overlaying a logo on the center, accept the density penalty and size up accordingly.

Pick an Error Correction Level That Matches the Surface

Error correction is not a "more is better" knob. The four levels — L (~7%), M (~15%), Q (~25%), H (~30%) — describe how much of the code can be destroyed before the payload is unrecoverable. A clean digital display can use L. A printed sticker on a courier's package that gets scuffed in transit wants Q or H. A code printed on a curved bottle cap that gets partially occluded by a logo needs H and a generous quiet zone.

Trade-off: each step up in error correction costs you capacity and increases module density. A code that fits at version 5 / L might require version 7 / H for the same payload. Higher density means each module is smaller at a fixed print size, which reduces the working distance and demands better focus from the camera.

If you need to drop a branded icon into the center, H gives you headroom — up to 30% of the modules can be obscured before the payload fails. For reference, the MDN documentation on image error correction is not the right source here, but the Wikipedia page on Reed–Solomon error correction explains the underlying math if you want to understand why H is more expensive than Q.

Size and Quiet Zone: The Two Numbers Most People Get Wrong

The most common field failure is a code that technically decodes in a lab and refuses to decode in a café window. Two physical parameters dominate: the module pitch (the size of one black square, measured in mm or inches) and the quiet zone (the white border required around the symbol).

Module pitch drives working distance. A general guideline from print-production references is that the module pitch should be at least 0.4 mm for reliable scanning at hand-held distance, and larger if the code will be read from across a room. Tiny codes look elegant on a business card and frustrate users whose phone cameras can't resolve the modules.

Quiet zone is non-negotiable. The QR specification requires a margin of at least four modules' width on all four sides. Printers, designers, and CMS templates routinely crop this. If your generator produces an image with no margin, you must add it yourself, or expect failures on first-encounter scans. When in doubt, treat the quiet zone as part of the artifact, not as decorative padding.

Match the Output Format to the Distribution Channel

A PNG with a transparent background is not the same artifact as an SVG. The format you choose changes how the code behaves through the rest of your pipeline.

Raster (PNG, JPEG): Fixed resolution. If you upscale beyond the native pixel grid, you get blur, which destroys module edges. Use these when the final display size is known and won't change.
Vector (SVG, EPS, PDF): Scales without quality loss. Use these for print pipelines, where the artwork may be resized, embedded in larger layouts, or sent to a commercial printer at arbitrary DPI.
High-contrast B/W only: Cameras use the contrast boundary to lock onto the finder patterns. If you tint the code with brand colors, keep contrast high — dark modules against a light background, with sufficient luminance difference. Avoid gradients on the modules themselves.

For printed materials, SVG or PDF keeps the modules crisp at any scale. For a web page or app where the code is rendered at one fixed pixel size, a high-resolution PNG is fine.

Build a Pre-Print QA Checklist

Before sending any QR code to print, run it through this ordered list. Catching issues at this stage costs minutes; catching them after 10,000 flyers have shipped costs the campaign.

Decode the generated image with at least two independent scanners (your phone, a colleague's phone, a desktop tool). Confirm the payload matches what you intended, character for character.
Print a proof at the final intended physical size, on the actual substrate (matte vs. glossy paper, fabric, plastic). Substrate reflectance changes effective contrast.
Scan the proof under three lighting conditions: bright direct light, dim indoor light, and shadow. A code that fails under any of these will fail for someone in the field.
Verify the quiet zone visually — measure four modules' width of clear space on every side. Crop tools and template overlays routinely remove it.
If a logo or icon overlays the center, confirm the obscured area stays below 30% of the modules, and that the error correction level is H.
Re-decode the printed proof. Do not assume the digital version is the artifact being shipped.
Archive the final file alongside the source URL, version number, ECC level, and proof photo. Future you will need to audit this.

Common Debugging Scenarios

Symptom: Code scans on some phones, fails on others. Usually a quiet-zone violation or a contrast issue. Older or budget cameras have less margin for error. Enlarge the code or restore the quiet zone.

Symptom: Code scans at arm's length but fails across a room. Module pitch is too small. Increase the physical size of the printed symbol or reduce the version by shortening the payload.

Symptom: Code scans once, then stops working after a few weeks. Surface degradation. UV, abrasion, or moisture is destroying modules. Switch to a more durable substrate, increase ECC to H, or add a laminate that doesn't reflect IR.

Symptom: Code redirects to the wrong URL. Payload mismatch. The URL in your campaign tracker doesn't match the URL encoded in the file. Re-encode from the canonical URL and replace every instance.

When you need a walkthrough of the generation step itself — version selection, ECC choice, and download formats — the Lizely guide on generating QR codes covers the mechanics in depth.

Constraints Engineers Hit in Production

Three constraints bite hardest when QR codes move from prototype to production.

Tracking attribution across physical surfaces. A code on a poster and a code on a business card may encode different UTM-tagged URLs even though they lead to the same landing page. Decide your tagging scheme before you generate, and store the mapping between artifact and URL in a versioned log.

Print pipeline vs. web pipeline. Print and web want different file formats, and going from one to the other often introduces subtle quality loss. Generate once at the highest fidelity you need, and derive smaller versions rather than re-encoding.

Reader diversity. Not every scanner uses the same detection algorithm. Apple's Camera app, Google's Lens, and dedicated industrial readers handle damaged codes differently. Test with the readers your audience actually uses, not just the one on your desk.

Frequently asked questions

How small can a QR code be before it stops scanning?

There is no universal minimum, because it depends on the camera, the version, and the ECC level. A practical floor for hand-held scanning at arm's length is a module pitch around 0.4 mm and a total size of roughly 2 cm per side for a low-version code. Larger versions need larger physical sizes to keep the module pitch above that threshold.

Should I use a dynamic QR code or a static one?

Dynamic codes point to a redirect URL that you control, so you can change the destination after printing. Static codes encode the final URL directly and cannot be changed. Use dynamic when the destination might change, when you need scan analytics, or when you want to A/B test landing pages without reprinting. Use static when the URL is permanent, you want zero redirect latency, and you don't need analytics.

What error correction level should I choose?

L (low) for clean digital displays with no logo overlay. M (medium) as a safe default for most printed materials. Q (quartile) when the surface may be lightly scuffed or the code will live outdoors. H (high) when you must overlay a center logo, the surface is curved, or the code may be partially occluded.

How do I verify a QR code before printing?

Print a physical proof at the intended final size, on the actual substrate, and scan it with multiple devices under varied lighting. Decode the result and confirm it matches the intended URL. Check that the quiet zone — four modules of clear space on every side — is intact. Do not skip this step.

This article was drafted with AI assistance and reviewed for technical accuracy before publishing.

DEV Community: Tea-sip

Engineer-to-Engineer: Building a Typing Test That Doesn't Lie to You

The Two Meanings of "Word" You Need to Settle Before Anything Else

The Time Window Is Where Most Bugs Hide

What You Measure vs. What the User Sees

Picking a Corpus Without Accidentally Building a Bias Engine

The Bigram Heatmap: The Single Most Useful Diagnostic You'll Add

Shipping Checklist for a v1 Typing Test

Frequently Asked Questions

What's a reasonable default for the idle-timeout threshold?

Should I count capitalized words differently from lowercase ones?

How do I prevent paste-based cheating in a public leaderboard?

My users complain that their scores dropped after I "fixed" the formula. What do I do?

Reviewing Pull Requests Without Losing Your Mind: A Text-Diff Workflow for Code Reviewers

Why Diffs Are Harder to Read Than They Look

The Configuration That Pays Off Immediately

A Walkthrough: Reviewing a 400-Line Backend Change

Edge Cases That Trip Up Even Senior Reviewers

A Checklist You Can Keep Open During Review

Trade-offs Worth Naming

Frequently asked questions

Should I review a diff in a browser or in an IDE?

What whitespace setting should I default to?

How do I review a reformatting commit that turned every line red?

What is the Myers algorithm and why does it matter to me?

Stress-Testing Visual States in Frontend Apps With Random Color Sweeps

What a Color Sweep Actually Exercises

A Reproducible Sweep Workflow

Holding the Team to Rules

The Trade-offs Nobody Mentions

Integrating With Existing Visual Tests

When a Random Sweep Is the Wrong Tool

Frequently asked questions

How many seeds do I need before the sweep is "enough"?

Can I run this against a production build?

Won't this just find contrast bugs my linter already catches?

Should the random colors be perceptually uniform?

Stop Reinventing the Wheel: A QA Pattern for Date Math in User-Facing Code

The Two Questions You Actually Need to Answer

The Reference Test Matrix You Should Commit to Your Repo

Injecting the Clock: The Single Most Useful Refactor

When the Rule Has a Time-of-Day Component

A Pragmatic Workflow for the Next Time This Comes Up

Frequently asked questions

What's the difference between using a TIMESTAMP and a DATE column for birthdays?

Should leap-year babies be treated specially?

My tests pass locally but fail on the CI server once a month. What's happening?

Is there an existing standard I should be citing in my code review comments?

Choosing How to Merge PDF Files: A Practical Engineer's Decision Guide

The Three Approaches in Plain Terms

When the Manual Route Actually Makes Sense

When a Script Earns Its Keep

When a Web Utility Is the Right Tool

A Decision Checklist You Can Reuse

Validation You Should Never Skip

Frequently Asked Questions

How do I know whether the merge actually preserved the original quality?

Can I merge password-protected files without removing the protection?

What is the difference between merging and creating a PDF portfolio?

Is there a size limit I should worry about?

Resizing Images for Email Campaigns: A Frontend Engineer’s Playbook

Why Email Forces Different Rules Than the Web

The Sizing Math That Actually Matters

Choosing a Format That Survives the Pipeline

A Practical Workflow You Can Run From a Makefile

QA: The Three Screenshots That Catch 80% of Bugs

Trade-offs Worth Naming Out Loud

Frequently asked questions

Should I send retina/HiDPI images to every recipient?

What’s the right JPEG quality for email?

Can I use WebP in transactional email?

What’s the single biggest mistake engineers make resizing for email?

Designing a Solvability Gate for 15 Puzzle Implementations

The Two-State Rule Most Codebases Get Wrong

Why the Rule Is Not Enough in Production

A Minimal Implementation in TypeScript

Generating Shuffles That Are Always Legal

Debugging When Your Solver Disagrees With a Reference

Checklist for the Code Review

Frequently Asked Questions

What's the difference between using a `TIMESTAMP` and a `DATE` column for birthdays?