DEV Community: mno tao

Prerendering a multilingual Nuxt game catalog without shipping the database

mno tao — Sun, 06 Sep 2026 01:00:00 +0000

A game catalog looks like a client-side application: filters, search, cards, detail pages, and playable iframes. It is still a poor reason to ship the complete content database and ask every crawler—or every phone—to reconstruct the page after JavaScript loads.

I recently localized a Nuxt catalog with 153 games into four languages. The public result is 676 indexable routes, but the architecture has three strict properties:

every indexable route is prerendered as complete HTML;
missing localized content fails the build instead of falling back to English;
the browser does not receive Nuxt Content’s SQLite/WASM engine or the full game records.

Here is how those pieces fit together.

Make the route set explicit

Relying only on a crawler means an accidentally missing link can remove a page from the static build. The catalog already has a source of truth, so use it to produce the complete route list.

The base set contains:

home, popular, new, search, and four site/legal pages;
one page per category;
one page per game.

With 153 games and eight categories, that is 169 base routes. A locale mapping applies no prefix to English and /id/, /it/, or /pt-br/ to the other languages. The same English slugs remain stable after the prefix.

169 base routes × 4 locales = 676 indexable routes

Localized 404 pages are also prerendered, but they are noindex and do not enter the sitemap.

This list feeds Nitro prerendering and the sitemap generator. The sitemap is not treated as evidence that pages probably exist; a post-build check resolves every <loc> to a generated HTML file.

Keep one source of truth for product facts

Game titles, iframe URLs, developers, dates, embed types, and stable slugs are product facts. Translators should not rewrite them.

Descriptions, objectives, controls, tips, category copy, and legal text are localized. A generation step combines those translations with the factual fields and writes the Markdown documents Nuxt Content will consume during the build.

For each non-English locale, the generator expects:

153 game documents;
eight category documents;
four site/legal documents.

That is 165 documents per locale and 495 localized Markdown files in total. Missing keys, extra slugs, duplicate entries, or fact drift are build errors.

The key rule is simple: an indexable localized route cannot silently borrow English body content. A visible fallback is useful in application chrome; it is dangerous when it creates a page advertised to search engines as a different language.

Localize the page, not the embedded game

The catalog can translate its navigation, metadata, controls guide, objectives, and warnings. It does not own every embedded game’s UI.

That boundary should be explicit. The page language changes, while the game iframe may remain in English. Trying to imply otherwise creates misleading metadata and support expectations.

The language switcher should preserve the current route:

/game/ember-vault/
/it/game/ember-vault/
/pt-br/game/ember-vault/

Do not redirect based on Accept-Language or browser settings. Automatic redirects make URLs unstable for crawlers and surprising for people who intentionally chose another language.

Generate SEO signals from the same locale model

Every page needs a self-referencing canonical and a complete alternate set:

en;
id-ID;
it-IT;
pt-BR;
x-default pointing to English.

The document lang, Open Graph locale, visible copy, and Schema inLanguage must agree. The sitemap repeats the same alternates.

This is a good place for a deterministic verifier. For all 676 HTML files, check:

expected html lang;
exact canonical URL;
all four hreflang entries plus x-default;
localized Open Graph locale;
Schema language;
no unresolved message keys;
no known English section headings on non-English pages.

Counting is surprisingly valuable. If the expected route count is 676 and the verifier saw 675, the build fails before deployment.

Split card data from detail data

The full game record contains fields that a grid never needs: iframe URL, long controls, features, developer information, and related-game details. Importing that object into a shared composable can put the entire catalog into a client chunk.

A build step projects a slim card record containing only fields used by search and grids, such as:

slug, title, description, category, tags,
thumbnail, embed type, difficulty, updated date, popular

Detail fields stay server/build-side. The detail route receives one game during prerendering and serializes only what that page needs. Legal and editorial pages do not preload the card catalog merely because they share a layout.

Add a leak test with a known detail-only iframe URL. If that marker appears in a shared JavaScript chunk, the split has regressed.

Remove the client database when all queries are prerendered

Nuxt Content can ship a SQLite/WASM client for browser-side queries. A fully static catalog does not need it if every content query runs during prerender and the result is hydrated from the page payload.

The production build aliases the client database module to a stub that must never execute. Post-build checks then fail if they find:

SQLite WASM or worker artifacts;
public content database dumps;
a runtime fetch for the full catalog;
old code that overwrites the prerendered description after hydration.

The last item protects more than performance. Runtime replacement can show one description without JavaScript and a shorter, different one with JavaScript, which makes accessibility and indexing unpredictable.

Put budgets around the remaining JavaScript

Internationalization has a real bundle cost. Lazy locale dictionaries help, but only if the application does not preload all languages on every route.

Track both the largest chunk and total emitted JavaScript. Also scan locale chunks for markers from more than one language. A budget is not a universal performance score; it is a tripwire against accidental catalog or dictionary duplication.

The browser check should visit a localized game page directly, before navigating from English. That catches implementations that work only after a locale bundle has already been loaded.

Test the game boundary too

A perfectly localized wrapper is still broken if the play button cannot launch its iframe. For a small set of representative self-hosted games, browser checks should:

open the localized detail route;
verify localized initial HTML;
launch the iframe;
send a real keyboard or touch input;
observe game progress rather than elapsed time;
verify pause, restart, focus, and mobile sizing.

For third-party embeds, record that availability is an external dependency. Do not translate or bundle their binaries as if they were catalog content.

The reference implementation discussed here is SonoTap. The transferable pattern is to use static generation as an integrity boundary: routes, translations, metadata, content, and client payloads are all artifacts that a build can count and reject.

What “local OCR” should mean in a web application

mno tao — Sat, 05 Sep 2026 01:00:00 +0000

“Runs in your browser” is easy to put on a landing page. It is harder to make it a property of the whole OCR pipeline.

An OCR page can have a static interface and still send the selected file to an API. It can keep the image local but put the extracted text into error reporting. It can avoid both and still leak a protected PDF password through a URL or form submission. If privacy is part of the product, the useful question is not where the JavaScript was downloaded from. It is: which user-derived bytes can cross a process or network boundary, and why?

Here is the approach I use for a browser-only OCR tool.

Start with a small threat model

For an image or PDF OCR session, treat all of these as sensitive:

source bytes;
filenames and MIME metadata;
PDF passwords;
rendered pages and crops;
recognized text and table output;
parser and model errors that could contain user-derived values.

The default rule is that none of them may be placed in fetch, forms, beacons, analytics payloads, URLs, browser storage, or logs. Downloading application code, OCR models, and a public character dictionary is different: those resources are the same for every user and contain no document data.

That distinction makes the network policy testable. A test can select a uniquely marked fixture, perform OCR, and fail if the marker or source bytes appear in any outgoing request.

Move inference off the main thread

OCR is both CPU- and memory-heavy. Running it on the UI thread creates frozen progress indicators and tempts developers to move the whole job to a server.

A dedicated Web Worker gives a better local architecture:

The page decodes a selected file into an ImageBitmap.
Ownership of the bitmap is transferred to the worker.
The worker loads ONNX Runtime Web and the selected detection and recognition models.
It reports coarse progress states such as model loading, detection, and recognition.
It returns structured lines and then closes the bitmap.

Transferable objects matter here. Copying a large RGBA buffer between the main thread and a worker can briefly double its memory cost. Transferring an ImageBitmap avoids that copy, while explicitly closing it keeps repeated batches from accumulating GPU-backed resources.

Put bounds before decoding

File size is not enough to predict decode cost. A compressed image can expand into tens or hundreds of megabytes of pixels. A practical pipeline checks:

accepted MIME types and extensions;
compressed byte size;
decoded width, height, and pixel count;
a maximum working dimension for inference;
a separate hard ceiling for safe decoding.

For formats with no universal browser decoder, isolate the decoder. HEIC can run in a short-lived worker; TIFF and BMP can have explicit dimension and buffer checks. After decoding, constrain the bitmap before inference. The OCR detector rarely needs a full 12-megapixel phone photo to find lines of text.

The important failure behavior is deterministic: reject an unsafe image before allocating another full-size buffer, return a localized error, and release anything already created.

Separate text detection from recognition

A useful local OCR pipeline is not one giant black box. Mine has two model stages:

a detector produces a text probability map;
connected regions become candidate boxes and nearby boxes are merged;
each crop is deskewed into a normalized canvas;
a recognition model produces character probabilities;
CTC decoding turns those probabilities into text and confidence values.

The detector can operate on a bounded, resized image. Recognition still maps boxes back to the source bitmap, so each line gets a cleaner crop. This also makes table-oriented output possible: the UI retains text plus geometry instead of receiving one opaque string.

Two recognition models are a reasonable product tradeoff. A small model reduces first-use download and latency; a larger model can be loaded only when the user asks for higher accuracy. “High accuracy” should describe the relative model choice, not promise perfect OCR.

PDFs need their own boundary

A PDF workflow is not just an image workflow with a different file extension. It introduces page ranges, passwords, malformed structures, and potentially hundreds of render operations.

Render only selected pages, cap the document size and page count, and keep the password in memory. Each page should be converted to a bounded bitmap and passed through the same worker pipeline. Release page canvases as soon as their OCR result is complete.

If a user can pause or stop a batch, make that a real state transition. It should stop scheduling new pages, not merely hide a spinner while work continues in the background.

Be precise about offline support

“Works offline” does not mean the first visit works without a network. The application shell and a chosen OCR model have to be downloaded first.

A service worker can cache immutable application resources and models, but model versions need explicit names. When a model changes, old and new caches should not be confused. The UI should say that models load on demand and that offline reuse begins after caching.

Test offline behavior after a successful warm-up, then reload with the network disabled. Also test a model the user has not cached: that failure should be clear rather than silently switching to an unrelated model.

Translate operational text, not just the heading

OCR interfaces contain many strings that appear only during work: decode failures, password prompts, page progress, model downloads, pause states, empty results, and export errors. A translated landing page with English worker errors is not a translated product.

One approach is to keep worker errors as stable codes and translate them in the UI. If a worker must produce fallback text, verify every public error path in every locale. Missing messages should fail the build rather than fall back silently on an indexable page.

Tests that support the privacy claim

The highest-value tests are not snapshots of the hero section. I keep checks for:

recognized text from a repository-authored public fixture;
Fast and higher-accuracy model selection;
a PDF page range and a password-protected PDF;
stop, continue, clear, and batch export states;
oversized and malformed input;
zero user-derived network requests;
offline reload after model caching;
memory cleanup after replacing or clearing files;
the same workflow in every interface language.

No browser test proves that all future code will be private. It does make a privacy regression visible in the same place as a broken download button.

The reference implementation behind these notes is BrowserOCR. The useful idea is broader than one product: local processing is an end-to-end constraint, not a badge attached to a client-side upload form.

Safely parsing email files in the browser

mno tao — Fri, 04 Sep 2026 00:40:06 +0000

An email file is not just text plus a few attachments. It can contain HTML, nested MIME parts, misleading filenames, inline resources, remote tracking pixels, malformed encodings, and enough data to exhaust a browser tab.

Moving parsing into the browser removes an upload from the architecture, but it does not automatically make the viewer safe. It changes the security job: untrusted content is now being interpreted next to the user’s active web session.

This is the checklist I use for a local EML and winmail.dat/TNEF reader.

Treat every parsed field as untrusted

The sender, subject, recipient, filename, MIME type, and message body all came from a file. Render headers and filenames as text, never by concatenating HTML.

The same applies to errors. A parser exception can include a filename or fragment of malformed input. Showing that message verbatim may leak data into logs or turn it into markup. Map parser failures to stable error categories, then display a controlled explanation.

Normalize into one internal model

EML and TNEF have different container structures, but the UI should not contain two independent security implementations.

Both parsers can produce a common message model:

subject, sender, to, cc, date,
plain body, sanitized HTML candidate,
attachments[] {
  safe filename, MIME type, bytes,
  inline flag, content ID, content location
}

The normalization layer is the right place to enforce per-source limits and reject unsupported structures. The viewer and download code then work against the same constrained data regardless of input format.

Sanitize HTML as hostile input

Email HTML was designed for mail clients, not for direct insertion into an application DOM.

A conservative policy removes:

scripts and event handlers;
forms and interactive controls;
iframe, object, and embed elements;
styles and CSS URLs;
unsafe protocols;
executable or unexpected embedded content.

Use a maintained sanitizer with a pinned version, but do not stop at its default configuration. Email has resource-loading behavior that a generic “safe HTML” preset may still allow.

Plain text should remain the fallback. If HTML cannot be sanitized into the allowed subset, showing text is better than trying to preserve every visual detail.

Rewrite local inline images

Legitimate messages often reference an attachment using cid: or Content-Location. Those images can be displayed without a network request:

match the reference to a parsed attachment;
create a Blob from the attachment bytes;
create an object URL;
replace the resource reference with that local URL;
revoke the URL when the message is switched, removed, cleared, or the page exits.

Matching needs normalized identifiers and explicit MIME checks. Do not let an attachment’s declared filename or content location become an arbitrary URL.

Keep remote images out of the DOM by default

Removing a visible remote image after rendering is too late. The request may already have exposed the user’s IP address, time, user agent, and a unique tracking token.

The safer sequence is:

parse and sanitize the body;
replace remote image sources with inert placeholders before insertion;
tell the user that external images are blocked;
only after an explicit action for the current message, restore allowed HTTPS sources;
use a no-referrer policy.

“For the current message” is important. Permission should not silently carry to another email in the batch, and it does not belong in local storage.

A browser test should observe the network and assert zero remote-image requests before the click. After the click, it should allow only the expected image request and no navigation or script execution.

Make downloads path-safe

Attachment names can contain path separators, control characters, reserved device names, or repeated values. Normalize every name before using it in a download or ZIP archive:

strip directory components;
remove control and unsafe characters;
provide a fallback when the result is empty;
cap length;
deduplicate names deterministically.

ZIP creation can happen entirely in memory. Object URLs used for individual files, PDF previews, and archives should have a clear owner and lifecycle. Revoke too early and downloads fail; never revoke and repeated batches leak memory.

PDF attachments deserve another small boundary. Create a preview only after the user asks, and use a Blob URL. Do not embed an untrusted remote URL just because an attachment declared itself as a PDF.

Put limits on expansion, not only input bytes

A 25 MB source can contain many MIME parts or highly compressible attachments. Useful limits include:

source files per batch;
bytes per source and per batch;
MIME parts or attachments per source;
total successfully extracted attachments;
nesting depth and parser work, when the library exposes them.

Check limits during parsing instead of building an unbounded structure and rejecting it afterward.

The UI should distinguish “unsupported format,” “malformed message,” and “safe limit exceeded.” That helps users without exposing parser internals.

Local processing includes telemetry

A page can parse locally and still send sensitive metadata to analytics or error reporting. For a mail viewer, do not collect:

filenames or file sizes;
subject, sender, recipient, or body;
attachment names, types, or counts derived from one message;
parser errors containing input values;
full referrers or query strings that could carry user data.

If aggregate task events exist, make their vocabulary fixed and inspect the exact payload. A successful open can be counted without serializing anything about the email that was opened.

Also avoid storing parsed messages in localStorage, sessionStorage, IndexedDB, cookies, or URLs. “The files never leave your device” is weaker than “the message stays in memory for this session.” State which one you mean.

Test with synthetic fixtures

Real user mail is a tempting source of edge cases and a bad test asset. Build repository-owned fixtures containing:

plain text and sanitized HTML alternatives;
CID and Content-Location images;
one deliberately blocked HTTPS image;
duplicate and path-like filenames;
zero, one, and many attachments;
malformed input and exact size/count boundaries;
Unicode headers and filenames.

Use unique harmless markers so the test can detect accidental requests or persistence. Run the same fixture through every translated interface; security warnings and errors are part of the product, not incidental copy.

The reference implementation for this checklist is Mail File Viewer. Browser-only parsing reduces one major exposure, but the remaining work—sanitization, resource policy, bounds, and cleanup—is what makes the result defensible.

Hitting an image size ceiling with Rust and WebAssembly

mno tao — Thu, 03 Sep 2026 08:12:16 +0000

Many image tools expose a quality slider. Forms and government portals usually expose a different requirement: “the file must be under 100 KB.”

Those are not the same problem. A quality value is an encoder input. A byte ceiling is a constraint on the output, and the relationship between the two depends on the pixels, dimensions, color profile, output format, and encoder.

I wanted a HEIC converter with one simple invariant:

output_bytes <= target_kb * 1024

The implementation runs in the browser, with Rust compiled to WebAssembly. Here are the design choices that mattered.

Decode once and keep a bounded image object

HEIC decoding is expensive enough that repeating it for preview, rotation, compression, and conversion is wasteful. The WebAssembly boundary therefore exposes an image object that owns one decoded RGB buffer.

The browser creates the object from the HEIC bytes, requests a JPEG preview, changes rotation if needed, and then calls either compress or convert. Replacing the input explicitly frees the old object.

The decoder has pixel and memory limits before it returns that buffer. This is not optional in a browser tab: a small compressed file can decode into a very large allocation.

Define “precise size” as a ceiling

An encoder cannot promise an output of exactly 100,000 bytes without padding or a more complicated rate-control system. Padding has no user value, and a 99 KB file satisfies a 100 KB form.

So the product contract is “at or below the selected target.” The UI reports the actual result. Tests assert the byte inequality, not a rounded label.

That also avoids the KB ambiguity hiding in the interface. Internally, the target is converted once to bytes and every comparison uses that value.

JPEG: search quality before dimensions

For JPEG, encoded size is sufficiently ordered by quality to make binary search practical. The algorithm searches a protected quality interval rather than the entire 1–100 range:

Q_MIN = 55
search [55, 100] for the highest quality whose bytes fit

The minimum is a product decision. Very low JPEG quality can technically hit a target while producing obvious blocks around faces and text. Below the floor, reducing dimensions usually gives a more usable result.

There is a useful optimization for tight targets: encode at Q_MIN first. If even that output is too large, the other quality probes at the same dimensions are doomed. Skip them and resize.

If current_bytes is the failed encoding, estimate the next scale from image area:

scale = sqrt(target_bytes / current_bytes) * 0.95

The square root appears because both width and height change. The 0.95 factor leaves a small margin so the next attempt is less likely to miss by a few bytes. Resize from the original decoded pixels with a high-quality Lanczos filter, then repeat the quality search.

The result is the highest JPEG quality at the largest dimensions found under the ceiling, subject to the quality floor and iteration limit.

PNG is a different algorithm

Lossless PNG has no quality knob comparable to JPEG. Compression level and filter choices do not produce a clean monotonic control that can be binary-searched against output size.

For PNG, dimensions are the practical lever:

estimate an initial downscale for very large photos, avoiding a slow full-resolution PNG encode;
encode the resized pixels and compare real bytes;
continue scaling down until the output fits;
try a few “grow-back” steps from the original pixels to use more of the remaining byte budget.

The grow-back step matters. A conservative scale can produce a 92 KB image for a 100 KB target. Increasing both dimensions slightly may retain more detail and still fit. Each candidate is resized from the original RGB buffer, not from the already reduced image, to avoid accumulating blur.

JPEG does not need this phase because quality search already spends the available budget at a fixed dimension.

Keep conversion separate from compression

“Convert HEIC to JPEG” and “compress HEIC below 100 KB” are different user intents.

The conversion path uses the original pixel dimensions and a fixed high JPEG quality, or lossless PNG. It does not run the target-size loop. The output can be larger than the HEIC input, especially for PNG, and the interface should say so.

Mixing these paths creates surprising tools that label an operation “convert” while quietly shrinking a photo to meet an arbitrary size.

Preserve color information when possible

A technically correct byte result can still look wrong if its color profile disappears. The decoder extracts an ICC profile when available, and both the preview and final encoder receive it.

Using the same profile for the “before” preview and output also prevents a misleading comparison where only one side is color-managed.

Make the WebAssembly contract boring

The JavaScript-facing result contains bytes plus explicit metadata:

output, MIME type, extension,
input width/height, output width/height,
JPEG quality or null for PNG,
encoding passes, resize passes

That shape keeps UI code out of the compression algorithm. The page creates object URLs for preview and download, revokes them when the file changes, and never sends source or result bytes to a server.

Test the invariant with real HEIC files

Synthetic RGB patterns are useful for forcing difficult compression, but they skip the HEIC decoder—the most format-specific part of the pipeline.

The test suite includes a repository-owned phone photo and checks several targets for both JPEG and PNG. Useful assertions include:

output bytes never exceed the target;
JPEG quality never falls below the floor;
output dimensions are positive and preserve orientation;
conversion retains the original dimensions;
ICC data survives when the fixture contains it;
encoding and resize pass counts remain bounded;
the browser can download and decode the result;
no image-derived request leaves the page.

The reference implementation is open source as HEIC To Size under AGPL-3.0-only. The larger lesson is that a byte target should be modeled as an invariant with format-specific control variables, not as a renamed quality slider.