DEV Community: Chang-Hai

PDF Accessibility Pre-Checks in the Browser: What Automation Can (and Cannot) Tell You

Chang-Hai — Wed, 19 Aug 2026 13:03:48 +0000

A PDF can look perfectly readable on screen and still be difficult to navigate with a screen reader. The reverse is also true: a file can pass several automated checks while still containing confusing reading order, weak alternative text, or an inaccessible complex table.

That is why I treat automated PDF checking as a pre-check, not as certification.

What a browser-based pre-check can inspect

A local checker can examine machine-verifiable signals exposed by the PDF structure, including:

whether the document contains tags and a usable structure tree;
whether basic metadata such as a title and document language is present;
whether form fields and links expose detectable structure;
whether pages appear to be image-only and may need OCR;
whether the file can be parsed successfully before deeper review.

These checks are useful because they turn a vague question — “is this PDF accessible?” — into a concrete list of issues to investigate.

What automation cannot prove

Passing structural checks does not prove conformance with WCAG, PDF/UA, Section 508, or any legal requirement.

Several important questions still require human judgment:

Does the reading order match the intended meaning?
Is alternative text accurate and useful in context?
Are headings, lists, and tables tagged semantically rather than merely present?
Is color contrast sufficient?
Can a keyboard and real assistive technology complete the document's tasks?
Are complex tables understandable when read linearly?

For formal review, the automated result should be followed by manual inspection in Adobe Acrobat or another professional PDF accessibility tool, plus assistive-technology testing.

Why local processing matters

PDFs often contain private material: contracts, student records, internal reports, or unpublished research. A useful first-pass checker does not need to upload that content.

I maintain PDF Accessibility Checker, a free browser-based pre-check that uses PDF.js locally. The PDF file, filename, document content, hash, and local path are not uploaded by the scanning workflow.

You can try the browser-local pre-check here:

PDF Accessibility Checker

Disclosure: I am the product maintainer/operator. The tool checks a limited set of machine-verifiable signals. It is not a compliance certificate and it does not replace a manual audit.

A practical review sequence

A defensible workflow is:

Run a structural pre-check.
Fix obvious metadata, tagging, and OCR problems.
Inspect reading order, headings, lists, links, and tables manually.
Review alternative text for meaning, not just presence.
Test keyboard interaction and at least one screen reader.
Record which checks were automated and which were reviewed by a person.

This keeps automation in the role where it is strongest: finding repeatable structural signals quickly, while leaving semantic and experiential decisions to human reviewers.

For the standards background, refer to the W3C WCAG overview and the PDF Association's accessibility resources.

The most useful result from an automated checker is not a green badge. It is a clear, explainable list of what to verify next.

Replacing a Next.js Microsite with an Embedded Go + Vite Binary Without Losing SEO

Chang-Hai — Mon, 10 Aug 2026 15:00:14 +0000

I recently moved a small interactive content site from a Next.js runtime to a single Go service. The motivation was operational simplicity: the product needed a polished React interface and indexable content pages, but it did not need a Node server in production.

The result uses Go’s standard net/http stack, an embedded Vite build, SQLite infrastructure, and build-time prerendering. This post covers the boundaries that made the migration manageable and the tradeoffs that remain.

The product boundary came first

The site is a deterministic planner. Users choose a few options, compare two generated sequences, edit them, download a PNG, or share a URL. The calculation can happen entirely in the browser.

That meant I could separate the system into two clear parts:

React owns the interactive product state and rendering.
Go owns HTTP delivery, configuration, security headers, small API endpoints, and production integration points.

There was no reason to turn every user interaction into a server round trip. Recent planner choices stay in localStorage, while a validated query string carries the state needed for a share link.

Build React once, embed the output

The frontend is built with React 19 and Vite. Production does not run Vite. Instead, Go embeds the finished assets:

package webassets

import "embed"

//go:embed dist/*
var Dist embed.FS

The HTTP server opens the embedded subdirectory and serves hashed assets with long cache lifetimes. HTML uses a shorter policy so metadata and content changes can ship predictably.

This keeps the deployment artifact small in concept: one binary, its environment file, CA certificates, timezone data, and a writable data directory. Node is still part of the build toolchain, but not the production runtime.

Preserve route-level HTML

A client-rendered shell would have weakened the content pages, so the build produces complete HTML for every indexable route. Each route gets its own title, description, canonical URL, Open Graph fields, and page body.

The prerender list includes the landing page, generator, style guides, eye-shape guides, methodology and safety pages, and printable template guide. A build should fail if a new indexable route is added without metadata or prerender output.

The Go server substitutes the configured production origin into canonical fields. That avoids baking a staging hostname into a release while keeping generated HTML deterministic.

Keep the interactive state in one module

The generator’s state needed to survive three paths:

defaults created by the current product version;
a saved local state from the same browser;
a shared URL received from another person.

I use one normalization layer for all three. Unknown values are rejected, lengths are constrained to the supported range, cluster counts are bounded, and a custom map must match the normalized count and available lengths.

The same module creates the outbound query string. A round-trip test verifies that a state encoded for sharing restores to the same normalized map.

const query = generatorSearchParams(state, activeMap, selectedPlan)
const restored = generatorStateFromSearch(query, defaults)
assert.deepEqual(restored.customMaps[selectedPlan], activeMap)

That test matters more than the framework choice. Without it, a share button can appear to work while silently changing a recipient’s map.

Generate downloadable images in the browser

The download feature draws the current map to a canvas and exports a 1200×675 PNG. Native sharing uses the Web Share API when the browser supports files, then falls back to sharing or copying the URL.

This is another task that did not require a backend rendering service. Keeping it local reduces infrastructure and avoids uploading a user’s work merely to create an image.

SQLite is infrastructure, not an excuse to collect data

The Go template includes SQLite in WAL mode for product features that may need persistence later. The current planner does not write map data to it. Having a database available does not mean every piece of browser state belongs there.

The same principle applies to authentication adapters. The template has an optional Google sign-in boundary, but the public planner does not require an account. Disabled infrastructure stays disabled until a feature has a real need, a tested flow, and matching privacy documentation.

Consent-aware analytics

Analytics loads only after the visitor chooses to allow it. Before consent, the site keeps only bounded attribution values for the current tab. Product events describe actions such as the first interaction, download, print, or share; they do not include exact map sequences, email addresses, or photos.

This required more work than dropping a script into the document head, but it made the public privacy explanation match the code path.

Deployment and rollback

The production process is intentionally boring:

build the Vite frontend;
prerender indexable routes;
run frontend tests;
run Go tests, race checks, and vet;
compile one Linux binary;
deploy it behind the existing TLS reverse proxy and systemd service.

Releases use an explicit environment value for the public base URL. The previous binary remains available for rollback. SQLite data lives outside the release directory even though the current product does not write planner state.

Tradeoffs

This architecture is not a universal replacement for Next.js. It works here because the interactive state is local, the content routes are known at build time, and the server-side needs are small.

It would be a worse fit if the product depended on per-request React server rendering, a large ecosystem of server components, or many dynamic pages that must be rendered with authenticated data.

The migration also creates responsibility. We own the prerender pipeline, route manifest, caching behavior, and security headers. Framework defaults no longer hide mistakes, so tests must enforce those contracts.

The useful lesson

The biggest memory saving was conceptual before it was technical: decide which data truly needs a server. Once the planner, image export, and share-state encoding were treated as browser responsibilities, the production server became a compact delivery and integration layer.

The live result is Lash Map Lab, a free lash-map planner. The subject is niche, but the architecture applies to many small interactive SEO sites: prerender the known content, keep deterministic tools local, and deploy only the runtime the product actually needs.

Disclosure: I’m Julian Tao, Owner of Lash Map Lab. This article describes my own product. It was prepared with AI-assisted editing and reviewed for technical accuracy before publication.

How to listen for USDT (TRC20) payments in Node.js without running a full node

Chang-Hai — Wed, 19 Nov 2025 15:39:27 +0000

Building a Telegram bot is fun until you hit the "payments" part.

I recently built a bot that sells digital products, and I wanted to accept USDT on Tron (TRC20) because the fees are low and everyone uses it.

I thought: "How hard can it be? I just need to check if an address received money."

Turns out, it's a headache.

If you are a solo dev like me, you usually have two bad options:

Use BitPay/Coinbase Commerce: Requires KYC, business docs, and they hold your funds. (No go for me).
Self-host: Query the blockchain manually.

I tried the self-host route first. Here is what I learned, and the solution I eventually built to fix it.

The "Hard" Way: Polling with TronWeb

To listen for payments, you typically use the tronweb library to interact with the Tron network.

You need to poll the most recent transactions or set up an event listener. Here is a simplified version of the script I initially wrote:

const TronWeb = require('tronweb');
// You need an API Key from TronGrid, or you'll get rate-limited instantly.
const tronWeb = new TronWeb({
    fullHost: '[https://api.trongrid.io](https://api.trongrid.io)',
    headers: { "TRON-PRO-API-KEY": 'your-api-key' }
});

const USDT_CONTRACT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"; // USDT Address

async function checkRecentTransactions(myWalletAddress) {
    // This is where it gets messy.
    // Public nodes often time out or return incomplete data.
    try {
        const contract = await tronWeb.contract().at(USDT_CONTRACT);
        // You have to parse the Transfer event logs
        // And handle hex conversion for amounts
        console.log("Listening for events...");

        // ... complex logic to filter events by 'to' address ...

    } catch (error) {
        console.error("RPC Error:", error);
    }
}

The Problem with this approach

It works locally, but in production:

Rate Limits: The free TronGrid API limits you heavily. If you have 10 users checking payments, you get banned.
Missed Events: Public WebSocket connections drop all the time. You need robust retry logic.
Maintenance: You are basically maintaining a mini-indexer just to receive $20.

The "Easy" Way: Webhooks (ChainHook)

I got tired of debugging RPC errors at 3 AM, so I decided to wrap this entire logic into a dedicated microservice.

I built ChainHook.

It's a "Set and Forget" middleware.

You give it a wallet address (Public key only).
It monitors the chain using premium nodes.
It sends a Webhook (POST) to your bot when a payment confirms.

Integration Example

Instead of maintaining the script above, your bot just needs one endpoint to receive the data:

// Your Bot's Backend (Express/Fastify/Python)
app.post('/webhook/payment', (req, res) => {
  const { event, data } = req.body;

  if (event === 'payment.confirmed') {
    const { amount, from, tx_hash } = data;

    console.log(`Received ${amount} USDT from ${from}`);
    console.log(`Hash: ${tx_hash}`);

    // TODO: Auto-deliver product to user
  }

  res.status(200).send('OK');
});

The payload looks like this:

{
  "event": "payment.confirmed",
  "data": {
    "network": "TRC20",
    "currency": "USDT",
    "amount": "29.99",
    "tx_hash": "89d3a...",
    "from": "TMwF...",
    "to": "YOUR_WALLET_ADDRESS",
    "timestamp": 171092834
  }
}

Looking for Beta Testers

I built this primarily for myself and a few friends running Telegram bots, but I'm opening it up for a public beta.

If you are:

Building a Telegram Bot / Discord Bot
Selling digital goods
Hate manual verification (or fake screenshot scams)

I'd love for you to try it out. It's non-custodial, meaning the money goes straight to your wallet—I just act as the notifier.

👉 Join the waiting list here: [https://chainhook-landing.vercel.app/]

(Early testers will get lifetime access to the starter plan for free).

Let me know in the comments if you have questions about handling Tron transactions manually, happy to help with the code too!