DEV Community: yyj-dev

filter: invert(1) is not dark mode, and a PDF page is not a picture

yyj-dev — Wed, 02 Sep 2026 08:36:18 +0000

Ask anyone how to dark-mode a PDF in the browser and you get the same two lines back: render the page to a canvas with pdf.js, put filter: invert(1) on it, done. It is the answer in every thread on the subject, and it is wrong in three separate ways.

Two of them show up in the first screenshot. Photos come out as film negatives. And the whole thing is a costume worn by the viewer: mail the file to a colleague, or open it on a tablet, and it is blinding white again, because you never touched the document.

The third is the one that took me longest to accept. 255 - x is not "the dark version of this color." It is the complement. A dark navy heading at rgb(20, 40, 120) inverts to rgb(235, 215, 135), which is khaki. Every colored element in the document comes out wearing the wrong hue, and no amount of tuning fixes it, because the operation itself is answering a different question than the one you asked.

I started where most people do, one step past the filter: rasterize the page, run a smarter per-pixel mapping over the bitmap, ship that. It works, and it is still the fallback path in my code. But a bitmap of a document is not a document, and every property you want back afterward has to be rebuilt by hand. Eventually I stopped treating the page as an image at all. Here is what is underneath.

A page is a little postfix program

A PDF page's /Contents is a content stream: a byte string of operands followed by operators, evaluated like a stack language.

0 0 0 rg              % set fill color to black (DeviceRGB)
BT /F1 12 Tf 72 700 Td (Hello) Tj ET   % draw some text
1 0 0 RG              % set stroke color to red
72 690 m 300 690 l S  % draw a line

Once you see this, dark mode stops being an image-processing problem and becomes a source rewriting problem. You don't repaint the picture; you find the instructions that set colors, rewrite those, and pass every other byte through untouched. The text operators still run. The glyphs are still glyphs.

That single change is what buys you the properties a canvas filter can never have: the output text is selectable and searchable, vector art stays razor sharp at 800% zoom, and the file size barely moves because you never rasterized anything.

The color operator zoo, and the one that ruins your day

The absolute operators are easy, and you can tabulate them by operand count:

const COLOR_OPS: Record<string, number> = {
  g: 1, G: 1,     // DeviceGray
  rg: 3, RG: 3,   // DeviceRGB
  k: 4, K: 4,     // DeviceCMYK
};

Lowercase is fill, uppercase is stroke. Read the operands, map them through your color function, emit the replacement.

Then there is sc / scn, which sets a color in whatever color space is currently selected. The space was selected earlier by cs / CS, naming an entry in the page's /ColorSpace resource dictionary. So 0.2 0.4 0.9 scn might be three RGB components, or it might be something else entirely, and you cannot know without resolving the resource. Worse, the selected space is part of the graphics state, so q and Q push and pop it. To know how many operands to even consume, you have to track what the original stream thought the current space was. You are not writing a regex over a byte string. You are writing an interpreter with a stack.

There is no way around that on the way in. But there is a trick on the way out. Every rewritten color is emitted as plain rg or RG, regardless of what came in. Those operators are absolute; they are always legal, and they reset the current color space to DeviceRGB as a side effect. Because you never re-emit a space-relative operator, you only ever have to read the color space state machine, never write a consistent one back. A CMYK 0 0 0 1 k becomes 1 1 1 rg. An ICCBased scn becomes rg. The nastiest class of bug in this project (emitting operands that don't match the space the viewer thinks it's in) is designed out of existence rather than debugged.

Refuse loudly, and refuse the whole page

The list of things a real-world PDF can contain is longer than the list of things you can confidently recolor. My rewriter throws a health-check failure and gives up on the entire page when it meets:

a color space it can't reduce to gray / RGB / CMYK: Indexed, Separation, DeviceN, Lab, Pattern
scn / SCN with a pattern name operand (/P1 scn)
an sh shading operator, because a gradient would stay bright on a dark page
an inline image (BI ... ID <binary> EI), where re-slicing raw bytes out of the token stream is a good way to corrupt a file
any stream that fails to decode or tokenize

The design decision worth stealing is not the list, it is the granularity. The tempting move is per-operator: skip the thing you don't understand, keep going. That gives you a page that is 90% dark with one glowing white gradient panel in the middle, which reads as broken software. Failing the whole page instead lets the caller fall back to the raster pipeline for that page only, so the failure mode degrades to "this page is a picture of a dark page" rather than "this page is wrong." A mixed document gets real vector text on the pages that qualify and a correct-looking fallback on the ones that don't.

One trap on the way out: the PDF spec's default fill color is black. A stream that draws text without ever setting a color is relying on that default, and on a dark page black is now the wrong answer. So the rewritten stream gets a prologue that paints the background rectangle and then explicitly sets both fill and stroke to the mapped foreground, before a single original byte runs.

The accident that made scanned pages work

Here is my favorite thing I learned, and I found it by accident.

An image mask (/ImageMask true) is a one-bit stencil. It carries no color of its own; the viewer paints it using the current fill color, exactly like a glyph. And it turns out that is precisely how scanners encode text: the JBIG2 layer of a scanned page is a stencil mask of the letterforms.

Which means two things fell out of one decision.

In the object-rewriting path, I never wrote a single line of code for scanned text. Changing the fill color operators is enough. The stencil follows the fill color, so scanned black-on-white text flips to light-on-dark on its own.

In the raster path there is a scanner that walks pdf.js's operator list with a simulated graphics state (transform matrix plus clip box, pushed and popped on save/restore) to find the bounding boxes of images worth protecting from inversion. That scanner deliberately ignores paintImageMaskXObject. Protecting those rectangles would have felt correct, and it would have carefully preserved the one thing the user came to change: the black-on-white scanned text.

Two unrelated-looking features, one property of the format.

What I'd tell someone starting this

Resist the image-processing framing for as long as you can. The moment you rasterize, every property you care about afterward (selectable text, sharp vectors, sane file size, scanned pages) becomes a reconstruction job instead of a preservation job.

And whatever your color mapping is, make it hue-preserving. Mine splits on saturation: near-grayscale colors get pulled toward the theme background by luminance (white to background, black to white), while chromatic colors keep their hue and get only their lightness flipped, so that navy heading lands on light blue rather than khaki. The two results are cross-faded across a saturation band, because the anti-aliased edges of colored glyphs sit right in between and a hard switch leaves a visible seam around every letter. That scalar math lives in three places in my codebase, once readable and twice inlined per-pixel, purely because returning a fresh tuple for every pixel of a full-page bitmap is a GC problem you do not want.

If you want to poke at the output rather than the theory, the running implementation is a browser-only PDF color inverter built on exactly the above (File API in, Web Worker for the raster path, nothing leaves the tab), and the full two-pipeline flow is written up here.

Happy to go deeper on the tokenizer or the clip-box simulation in the comments if that's useful to anyone.

The Pokédex Is 2.4MB. My Users Never Download It.

yyj-dev — Sun, 16 Aug 2026 16:00:49 +0000

A random Pokémon generator is a strange thing to optimize. The entire product is: press a button, get a Pokémon. But behind that one button sits the whole dataset of the franchise — 1,025 species across nine generations, an 18×18 type chart, hundreds of moves and abilities, and a learnset table for every single species. The naive versions of this app either hammer a public API on every click or quietly ship a multi-megabyte database to every visitor. I spent most of my architecture budget on a random Pokémon generator I built making sure it does neither, and the pattern that came out of it — treat your build step as a data compiler — is the part worth writing down.

Why runtime API calls were never on the table

PokéAPI is a lovely public resource, but it answers questions one at a time, and a generator doesn't ask questions one at a time. When someone toggles "Gen 3 only, no Legendaries, starters excluded" and hits the button, the app needs the entire filtered pool in memory right now. Fetching per click means spinners, rate-limit anxiety, and being a bad citizen toward a free API.

So at runtime, my site makes zero calls to PokéAPI. Instead, the excellent @pkmn/dex npm package sits in devDependencies — it never ships to anyone — and a build-time script, scripts/generate-pokedex.mjs, runs it once and emits plain static JSON that the app imports like any other module:

pokedex.json — 1,025 species, exactly 13 fields each
typechart.json — the full 18×18 effectiveness matrix
moves.json — 685 moves
abilities.json — 310 abilities
learnsets.json — the legal move list for each of the 1,025 species

The motivation is a pair of numbers I refuse to inflict on visitors: the dex package weighs 2.4MB, and the raw learnsets data alone is a 3.1MB chunk. Neither ever appears in the client bundle. What ships instead is the trimmed JSON — 13 fields per species, nothing the UI doesn't render or filter on. The dex knows a thousand things about each Pokémon; my users' phones only need to know thirteen of them.

Editorial decisions belong in the generator script

Here's the part I didn't expect: deciding what counts as a Pokémon is genuinely messy, and I'm glad that mess lives in one script instead of being sprinkled across components.

The raw dex data includes battle-only formes, cosmetic variants, fan-designed CAP species, and other entries that would feel like bugs if they popped out of a generator. My script hardcodes the policy in one place:

skip anything with a non-empty forme, and cosmetic formes generally
skip entries with num <= 0
skip anything whose isNonstandard is CAP, LGPE, Custom, Unobtainable, or Future

Some classifications simply don't exist in the data, so I made them exist. There is no isStarter flag anywhere — "starter" is a fan concept — so the script carries a hardcoded Set of the 27 starter names and stamps a boolean onto each matching species. Legendary and mythical status comes from tags. Generation isn't stored either; it's derived from National Dex number ranges (number ≤ 151 → Gen 1, and so on up through Gen 9).

The client never reasons about any of this. It reads pre-computed booleans and fields. If I ever change my mind about what belongs in the pool, that's a one-file diff and a rebuild, not a scavenger hunt through UI code.

The one file too big to import

After trimming, learnsets.json still weighs 870KB. That's small compared to the 3.1MB it came from, but it's still enormous next to everything else — and only one feature on the entire site needs it: the moveset generator.

So it's the one file that never gets a static import. It loads through await import(), dynamically, the first time someone actually generates a moveset. The visitor who came to spin up random Gen 1 teams never downloads a byte of it. The visitor who wants movesets pays the cost exactly once, on first use, and the chunk is cached after that.

The same isolation logic applies at a smaller scale: moves and abilities live in two separate lib files, not one shared "battle data" module. The moveset page doesn't bundle abilities.json; the ability page doesn't bundle moves.json. It's the kind of split that feels fussy until you look at a bundle analyzer and see each route carrying only its own weight.

Strings you can compute don't belong in JSON

One more trim that surprised me with how much it mattered: sprite URLs aren't stored in the data at all. A thousand-entry JSON file where every entry carries even one URL string is a thousand copies of the same CDN prefix. Since sprite filenames are just the National Dex number, the URL is assembled at runtime from the number the app already has. The JSON stores an integer; the string exists only in memory, briefly, on its way into an img tag.

The most boring line of code I've ever shipped

After all of that — the build pipeline, the filtering policy, the chunk isolation — here is the actual "generator":

pool[Math.floor(Math.random() * pool.length)]

That's it. That's the feature. No seeded PRNG, no weighting, no cleverness. The team generator adds exactly one wrinkle: when it draws a Pokémon for a six-slot team, it splices the pick out of a working copy of the pool, so the same species can't appear twice. Draw, remove, repeat six times.

I find this genuinely funny. The line users think of as "the app" took thirty seconds to write. Everything around it — making sure pool is small, correct, filtered to their settings, and arrived on their device without dragging megabytes of dex data along — took weeks.

The takeaway

If your side project is really a dataset wearing a UI, the highest-leverage code you'll write probably isn't in a component. It's a script that runs at build time, reads a heavyweight source of truth from devDependencies, applies every editorial decision you'd otherwise scatter through the app, and emits the smallest possible artifacts for each route to import — with anything both large and rarely-used pushed behind a dynamic import().

The browser gets answers, not the encyclopedia the answers came from.

(Standard footnote: this is an independent fan project, not affiliated with Nintendo, Game Freak, or The Pokémon Company. The data pipeline is the part I can take credit for; the 1,025 reasons anyone visits are theirs.)

The Color Math Was Never the Slow Part

yyj-dev — Fri, 14 Aug 2026 18:17:42 +0000

The first version of my image-to-Minecraft-blocks converter locked up the browser tab for long enough that I assumed something had crashed. I dropped in a photo straight off my phone, hit convert, and the page stopped responding to clicks — no spinner animation, no scroll, nothing. I sat there for a while wondering whether I'd written an infinite loop.

I hadn't. It was just doing exactly what I told it to, on the main thread, one pixel at a time.

This post is about what I got wrong when I tried to fix it, because my first guess was confidently wrong and the actual bottleneck turned out to be somewhere I wasn't looking.

The naive shape of the problem

The job is simple to state. You have a photo. You have a fixed list of Minecraft blocks, each with a known average color. For every cell in the output grid you find the block whose color is closest, and you write it down.

The obvious implementation is two nested loops: outer over pixels, inner over the palette, keep the minimum. Textbook nearest-neighbor search, and for small inputs it's genuinely fine.

Then you run the numbers on real inputs. A photo out of a modern phone camera is around 4000×3000 — twelve million pixels before you touch anything. You downscale before matching, sure, since the output grid is maybe 128 or 256 blocks wide. But the decode and resample still happen at full resolution, and then the match loop runs every cell of the output grid against every entry in a palette of several hundred blocks.

And I was running all of it inside a click handler.

My wrong guess

My first theory was the color space. Matching happens in OKLab rather than raw RGB, because RGB distance produces the classic "cheap filter" look — most visibly on skin tones and mid-range greens, where a numerically small gap can read as a very different color to a human eye. OKLab conversion involves a matrix multiply and cube roots, and cube roots felt expensive, so I assumed that was where the time was going.

It wasn't. When I actually profiled it instead of guessing, the color conversion barely registered. Nearly everything was sitting in the palette scan — the inner loop — and in the plain fact that all of this was happening on the thread responsible for painting the page.

Two separate problems wearing one costume:

The work was on the main thread, so the UI froze regardless of how fast the work was.
The work was genuinely redundant, because photos repeat colors constantly and I was re-deriving the same answer thousands of times.

Moving it off the main thread, and the bug that came with it

The first fix is the boring correct one: put the pipeline in a Web Worker. The UI thread hands over the pixels, the worker grinds, the UI stays alive and can render progress.

What nobody warns you about is that the handoff itself has a cost. postMessage structured-clones its payload by default, and structured-cloning a multi-megabyte pixel buffer means copying a multi-megabyte pixel buffer, twice per conversion — once in, once out. You can move the buffer instead of copying it by passing it in the transfer list:

worker.postMessage({ buf, width, height }, [buf]);

That hands ownership across the boundary with no copy. It also neuters the original — after the transfer, buf.byteLength on the sending side is 0.

Which is how I spent an evening on a bug where the source thumbnail rendered as a black rectangle every time, but only after the first conversion. I was holding a reference to the same buffer for the preview, and the transfer had emptied it out from under me. The fix is unglamorous: keep a copy for anything the main thread still needs, or don't transfer that particular buffer. But it's the kind of bug that reads as "canvas is broken" for an hour before it reads as "you gave your array away."

The cache that made the inner loop mostly disappear

The second fix is where the actual speedup lived, and it comes from a property of photographs rather than a property of JavaScript.

Photos are enormously repetitive at the color level. A sky is thousands of pixels of nearly the same blue. A cheek is hundreds of pixels of nearly the same tone. If you're doing a full palette scan for every one of those pixels independently, you are computing the identical answer over and over.

So quantize the lookup key. Take the source color down to 5 bits per channel and use that as a cache key. Five bits per channel means 32×32×32 = 32,768 possible keys — small enough to keep in a flat typed array, and a real photo touches only a fraction of them. First time you see a bucket, do the full palette scan. Every time after, it's an array index.

The palette scan doesn't get faster. It just stops running for the overwhelming majority of pixels. That's the whole trick, and it's the difference between a frozen tab and a progress bar that finishes while you're still looking at it.

One consequence worth flagging if you build something similar: the cache key has to include the palette identity, not just the color. My block palette is versioned — Java releases from 1.13 up through 26.2, with Bedrock carrying its own separate block and texture set — because a palette frozen at whatever version the tool was written against will eventually disagree with what the game actually renders, and you get a preview that doesn't match your build. That's a correctness win, but it means "nearest block to this color" is not a stable function. Switch edition or version and every cached answer is potentially wrong. Ask me how I know. Version identity goes in the cache key, or the cache gets cleared on switch; either works, silently doing neither does not.

What the worker sends back

The last thing I changed was the return type, and it turned out to matter more than the performance work.

Originally the worker returned an ImageData — the rendered preview, RGBA. That's all you need to show someone what their build will look like. But it's the wrong artifact to hand a person who then has to actually place the blocks, because "a picture of the finished thing" throws away the one piece of information they need most: which block is at each position.

So the worker now returns two things: the preview pixels and a flat array of palette indices, one per cell. Once those indices are the source of truth, the things a builder actually needs stop being separate features and start being views over one array. A material list is a single tally pass with a counts array, which is where "you'll need 340 of this, 118 of that" comes from — the number you want before you go mining, not after. Slicing the same array into sections gives you a chunk-by-chunk build guide, so you can work one region at a time instead of squinting at a flat reference image and losing track of which row you're on. And .schem and .litematic export are just serializers over those indices, for anyone running WorldEdit or Litematica who'd rather skip manual placement altogether.

None of that needed its own pipeline. Returning an RGBA preview and nothing else had been quietly throwing away the only representation any of it could be built from.

The side effect I didn't plan for

There's an accidental property of this architecture that turned out to be one of my favorite things about it. The worker has no network code in it. There's no upload step, because there's nothing on a server to upload to — the whole conversion runs locally in the browser.

That means the privacy claim isn't something you have to trust me on. Open DevTools, watch the Network panel, drop in a photo, convert. Nothing goes out. It's a verifiable property of the page rather than a promise in a policy document, and I only ended up there because moving the work into a worker was the fastest way to stop the tab from freezing.

The whole thing lives at minecraftpixelart.xyz if you want to poke at it — it's a solo side project I maintain in my spare time, and the palette upkeep as new Minecraft versions ship is the part I expect to be doing forever.

If you take one thing from this: profile before you optimize, because I would have happily spent a weekend hand-optimizing a cube root that accounted for almost none of the runtime.

One React Component, Three Display Technologies — Flip Cards, Pixel LEDs, and Seven-Segment Digits in Pure CSS

yyj-dev — Fri, 03 Jul 2026 07:28:26 +0000

I recently shipped a fullscreen clock app, digitalclock.xyz, that offers eight themes. Four of them look like a mechanical flip clock, three like a retro pixel LED display, and one like a seven-segment alarm clock. Three genuinely different display technologies — and I wanted all of them rendered by the same component tree, with zero canvas, zero SVG, and zero image assets.

That constraint turned out to be the most interesting engineering decision in the project. Here's how the architecture actually works.

A theme is just data

The first rule I set: a theme is not a component, not a CSS file, not a variant prop scattered across the tree. It's a plain object.

export type ThemeStyle = "flip" | "pixel" | "segment";

export interface Theme {
  id: ThemeId;
  label: string;
  style: ThemeStyle;
  pageBg: string;
  cardBg: string;
  cardBgGradient?: string;
  digitColor: string;
  divider: string;
  glow?: string;
  fontClassVar: "var(--font-flip)" | "var(--font-flip-mono)" | "var(--font-pixel)";
  separatorColor: string;
  subtleText: string;
}

Everything a theme knows is color tokens, an optional glow, a font variable — and one 3-value enum, style, which decides which of three rendering branches the digit component takes. All eight themes fit in a single array in themes.ts. "Flip Ocean" and "Pixel Amber" differ only in the values of these fields.

The important consequence: adding a ninth theme is a data change, not a code change. Adding a fourth display technology is a code change — one new branch — but nothing else in the tree has to know about it.

The only interface between JS and styling is custom properties

React never writes real CSS declarations inline. The digit component's inline style contains nothing but CSS custom properties:

style={{
  "--seg-on": theme.digitColor,
  "--seg-off": `color-mix(in srgb, ${theme.digitColor} 10%, transparent)`,
  "--seg-glow": theme.glow ?? "none",
} as React.CSSProperties}

Static CSS rules in globals.css consume those variables. JS decides what the values are; CSS decides what they mean. That split is what keeps three unrelated display technologies from leaking into each other — the React side genuinely does not know how a segment gets its bevel or how a flip card folds.

One detail I like a lot: the seven-segment theme only declares a single color, digitColor. The dim "off" segments are derived in that snippet above with color-mix(in srgb, <digitColor> 10%, transparent), and the glow is another derivation of the same hue. One token in, an entire lit/unlit/halo palette out. When I added the theme picker, no theme ever shipped with mismatched on/off colors, because there's nothing to mismatch.

Branch 1: pixel — the trivial case

The pixel LED branch is almost embarrassingly simple, which is the point:

if (theme.style === "pixel") {
  return (
    <span className="flip-pixel-digit"
      style={{ color: theme.digitColor, textShadow: theme.glow }}>
      {value}
    </span>
  );
}

A pixel font does the heavy lifting for the dot-matrix look, and a two-layer text-shadow (an 18px halo plus a wider 36px falloff) makes it bloom like a backlit display. The glyph is text, so the glow technique that fits is text-shadow — it hugs the letterforms for free.

Branch 2: seven-segment — the font is in the stylesheet

This is the branch people don't believe until they open devtools. A seven-segment digit renders as seven empty spans:

<span className="seg-digit" data-value={value} aria-label={value}>
  <span className="seg seg-h seg-a" />
  <span className="seg seg-v seg-b" />
  <span className="seg seg-v seg-c" />
  <span className="seg seg-h seg-d" />
  <span className="seg seg-v seg-e" />
  <span className="seg seg-v seg-f" />
  <span className="seg seg-h seg-g" />
</span>

No text content at all. The "font" — which segments light up for which digit — lives entirely in CSS as ten attribute-selector rules. It's literally the 0–9 truth table you'd find in a 7-segment decoder datasheet, written in selectors:

.seg-digit[data-value="2"] :is(.seg-a, .seg-b, .seg-d, .seg-e, .seg-g),
.seg-digit[data-value="4"] :is(.seg-b, .seg-c, .seg-f, .seg-g),
.seg-digit[data-value="8"] :is(.seg-a, .seg-b, .seg-c, .seg-d, .seg-e, .seg-f, .seg-g) {
  background: var(--seg-on);
}

React's entire job here is setting data-value="4". The cascade does the decoding.

The geometry is absolutely positioned in em units — seg-a at top: 0, seg-g at top: 0.455em, seg-d at top: 0.91em, verticals hung at the corners — so the whole digit scales with font-size like real text does. The classic tapered segment ends are one clip-path: polygon(...) per orientation, hexagons instead of rectangles.

Two branch-specific details worth stealing:

Glow: text-shadow is useless here because there's no text. The segment branch uses filter: drop-shadow(var(--seg-glow)) on the container, which follows the clipped hexagon shapes exactly — including the tapered tips.
Accessibility: a pile of empty spans is meaningless to a screen reader, so the container carries aria-label={value}. Cheap insurance for a fully decorative DOM structure.

Branch 3: flip — the only branch that needs memory

Flip is the one technology that can't be stateless, because a flip has a before and an after. The component keeps the previous value in state and runs a two-phase animation — the top half folds down over 300ms, then the bottom half unfolds for another 300ms — before committing:

useEffect(() => {
  if (value === prev) return;
  if (theme.style !== "flip") {
    setPrev(value);   // pixel/segment themes: no animation, just sync
    return;
  }
  setFlipping(true);
  timerRef.current = window.setTimeout(() => {
    setPrev(value);
    setFlipping(false);
  }, 600);
}, [value, prev, theme.style]);

Note the second early return: when the active theme is pixel or segment, the same component silently degrades into "just track the value." The flip machinery — the extra state, the timeout, the transient fold elements rendered during flipping — costs nothing on the branches that don't use it. That's what lets one FlipDigit component serve all three technologies instead of three sibling components duplicating the value-diffing logic.

The one SSR wrinkle

A clock is the canonical hydration-mismatch generator: the server has no idea what time it is in the client's timezone. My useNow hook returns Date | null, starts as null, and only picks up a real Date inside useEffect — so the server render and first client render agree on "no time yet," and the 250ms interval is purely a refresh rate after that.

What this bought me

The final tally for eight themes across three display technologies: one digit component with three branches, one theme array, and a few hundred lines of static CSS. No canvas contexts to manage, no SVG sprites to generate, nothing to preload. The DOM stays inspectable — you can watch digit 4 light up b, c, f, g in the elements panel, which also made every rendering bug a devtools problem instead of a bitmap-debugging problem.

If you want to poke at the result (devtools open, ideally), it's live at digitalclock.xyz. And if you've pushed attribute selectors somewhere equally questionable, I'd honestly love to hear about it in the comments.

What Western Devs Need to Know Before Visiting China in 2026: Alipay, WeChat Pay & the Mobile Web

yyj-dev — Tue, 23 Jun 2026 15:42:03 +0000

If you write software for a living and you're considering a trip to China in 2026, the friction you'll hit is not what you expect. The Great Firewall is the headline, but it's rarely what trips up a first-time visitor. What actually breaks your week is the small stuff: a QR code at a noodle shop, a metro turnstile that won't take your foreign card, a hotel Wi-Fi that quietly drops every request to Google.

This is a brief survival guide written from a developer's mindset: what's actually changed in 2026, what you can fix before you leave, and what you should just accept.

1. Visa-free entry now covers most Western devs

As of late 2025, China extended its 30-day visa-free transit policy to passport holders from 38 countries, including the US, UK, Germany, France, Australia, the Netherlands, and most of the EU. If you're flying in for a vacation, a conference, or even a short remote-work stretch, you may not need to apply for a visa at all — you just need an onward ticket within 30 days.

The catch: the rules per nationality drift quarterly, and the official guidance is scattered across embassy pages. I keep a more current breakdown here: FirstTripChina visa-free guide — worth checking the week you book your ticket.

2. The payment problem is the real "API" you need to integrate

China runs on two payment rails: Alipay and WeChat Pay. Cash is technically legal but vendors below the level of a 4-star hotel will look at you like you handed them a stone tablet. Foreign credit cards work at airports and big chains; they do not work at the dumpling place you actually want to eat at.

The fix that exists in 2026 — and that did not exist three years ago — is "Tour Card" inside Alipay and "International" mode inside WeChat Pay. Both let you link a Visa/Mastercard issued outside China and pay via the same QR system locals use. Setup steps (roughly):

Install Alipay (App Store / Play Store, US/EU regions both work).
Verify with passport + selfie (KYC takes about 3 minutes).
Tap Tour Card → add your foreign card → top up an in-app balance, OR enable real-time charges.
Repeat the equivalent flow in WeChat → Me → Services → Wallet → International.

Two tips that took me embarrassingly long to figure out:

Top-ups under ¥200 (~$28) waive fees; above that, you pay ~3%. Re-charge often instead of once.
WeChat Pay's International mode has a daily transaction cap that resets at midnight Beijing time, not midnight local time. Plan accordingly.

I wrote up the full setup with screenshots: Alipay & WeChat Pay setup for foreigners.

3. Your phone is a router, not just a phone

If you're traveling from a country with a "free roaming in China" plan (T-Mobile US, Three UK, some EU carriers), the bandwidth is throttled but the route is unfiltered — your traffic exits in Hong Kong or Singapore. Google, GitHub, Slack, your work VPN: all just work.

If you're not on one of those plans, you have three options:

Buy a physical or eSIM tourist plan from China Unicom HK or 3HK — these route through Hong Kong, so still unfiltered. ~$25 for 20 GB / 30 days.
Pre-install a paid VPN with a stealth protocol (WireGuard over obfuscation works in mid-2026; pure OpenVPN is detected). Test it before you land — VPN provider websites are blocked inside the wall, so you can't sign up after arrival.
Do nothing and accept that for one week, your Slack will live on Telegram, your Gmail on Outlook, and your Google Maps on Apple Maps. (Yes, Apple Maps works in China. It's surprisingly good. Baidu Maps is better.)

4. High-speed rail beats everything else for inter-city

The high-speed rail (HSR) network in 2026 is the single best argument for traveling in mainland China. Beijing → Shanghai (1,300 km / 800 mi) is 4h 18m at 350 km/h, costs ¥553 (~$77) in second class, and runs every 12 minutes. There is no airport security line, no boarding pass, no luggage check — you tap your passport at the gate and walk on.

Book through Trip.com or 12306 English in your Apple/Play store. The native 12306 app is more reliable but the English UI is rough. Buy your ticket the day before; popular Beijing-Shanghai trains do sell out on weekends.

5. The three cities most worth your first week

If this is your first trip and you have 7–10 days, the strongest itinerary I've seen:

Beijing (3 days) — Forbidden City, Mutianyu Great Wall, 798 art district. The history is the point.
Xi'an (2 days) — Terracotta Army, the Muslim Quarter night market. Worth the detour.
Shanghai (3 days) — Modern China. The Bund, Pudong skyline, plus the food scene most worth flying for.

HSR connects all three in <6 hours each leg. Full city-by-city breakdown: FirstTripChina city guides.

Short version

Check visa-free eligibility before you book — for most Western passports in 2026, you don't need a visa for ≤30 days.
Install Alipay + WeChat Pay before you fly. Their KYC requires a phone number you can receive SMS on; do it from home.
Get an HK-routed eSIM if your home carrier doesn't include China roaming.
Beijing → Xi'an → Shanghai by HSR is the optimal first-trip loop.

The country is friendlier to foreign travelers than its reputation suggests, but the friction is concentrated in the first 24 hours after you land. Front-load the prep, and the rest of the trip is a breeze.

I built PDF Dark — convert any PDF to true dark mode, 100% in your browser

yyj-dev — Mon, 22 Jun 2026 13:12:29 +0000

Why another PDF tool?

I read a lot of PDFs at night — research papers, ebooks, technical manuals. Every PDF reader I tried had the same problem: their "dark mode" was just a viewer toggle. The moment I forwarded the PDF to my Kindle or iPad, the white background blasted me again.

So I built PDF Dark — a tool that converts any PDF into a real dark-mode PDF file you can download, share, and reread anywhere.

What it does

100% browser-side conversion. Your file never touches a server. Verifiable in DevTools.
Real dark output PDF, not a viewer trick. Works on Kindle, iPad, Acrobat, anywhere.
Saturation-aware algorithm — photos and charts keep their original colors.
Free, MIT-licensed, no signup, no ads.

How it works under the hood

The conversion runs entirely in the browser using PDF.js to parse the original PDF page by page, then re-renders each page through a Canvas pipeline. The algorithm walks pixel data and inverts only low-saturation regions (text, line art, white background), while preserving high-saturation regions (photos, color charts, logos).

The output is then re-encoded as a standard PDF using pdf-lib. No server, no upload — your file never leaves your device.

Try it

Website: https://pdfdark.org
GitHub (MIT): https://github.com/1436941541/pdf-dark

Feedback welcome

This is an early version. PRs, bug reports, and feature requests are very welcome — especially edge cases (complex form PDFs, scanned PDFs with dense images, RTL languages). Drop a comment below or open an issue on GitHub.

If you read PDFs at night, give it a try and let me know what breaks.