DEV Community: West

The 51 KB Image Wasn't the Problem: How I Cut Mobile LCP from 4.0s to 1.47s

West — Mon, 07 Sep 2026 09:09:45 +0000

The homepage looked like an obvious image-performance problem.

It was a storefront full of digital planner covers and sticker previews. On mobile, Lighthouse reported a median Largest Contentful Paint (LCP) of 4.04 seconds. The hero image was the LCP element, so the first instinct was predictable: compress the image again.

But the hero was already a 51 KB WebP.

The real problem was everything surrounding it:

nearly 1 MB of initial HTML and React Server Component data;
134 KB of render-blocking CSS;
authentication and saved-product providers loaded on a public page;
full product objects serialized for cards that needed only a few fields; and
an LCP image that was responsive, but not yet expressed to the browser as the page's critical image.

After fixing those issues, the production mobile Lighthouse median dropped from 4.04 seconds to 1.47 seconds. CLS stayed at 0, and median Total Blocking Time was 9 ms.

This article explains the changes that mattered, the changes that were insufficient on their own, and the tests I added to keep the page fast.

Start with the LCP timeline, not the image file

LCP is not just image download time. It can be split into four parts:

Time to First Byte
Resource load delay
Resource load duration
Element render delay

That distinction matters because shrinking an image only improves the third part. It does nothing when the browser discovers the image late, rendering is blocked by CSS, or the main thread is busy processing unrelated JavaScript.

In my baseline run, Time to First Byte was about 98 ms. The server was not the bottleneck. The 51 KB hero was also not large enough to explain a four-second LCP by itself.

The waterfall pointed elsewhere: the browser was receiving and processing a large document, stylesheet, RSC payload, and client-side code before the hero could become visible.

That changed the optimization question from:

How can I compress this image further?

to:

What is preventing this already-small image from painting sooner?

1. Stop sending detail-page data to catalog cards

The homepage fetched complete product records. A sticker product could contain every sheet in the pack, aliases, high-resolution image URLs, and download URLs.

The card needed only a title, category, thumbnail, price, and a small amount of metadata.

Passing the full objects from a Server Component to a Client Component meant all of that unused data was serialized into the RSC payload.

I added an explicit projection at the server boundary:

export function toHomepageCatalogItem(item) {
  const card = {
    id: item.id,
    type: item.type,
    slug: item.slug,
    title: item.title,
    blurb: item.blurb,
    category: item.category,
    tone: item.tone,
    thumbnailUrl: item.thumbnailUrl,
    coverUrl: item.coverUrl,
    price: item.price,
  };

  if (item.type === "planner") {
    return {
      ...card,
      year: item.year,
      layout: item.layout,
      pages: item.pages,
    };
  }

  return {
    ...card,
    sheetCount: item.sheetCount,
  };
}

Then the server mapped the API response before rendering the interactive homepage:

const stickerCatalog =
  stickerResult.status === "fulfilled"
    ? stickerResult.value.map(toHomepageCatalogItem)
    : [];

return (
  <HomePage
    planners={planners.map(toHomepageCatalogItem)}
    stickers={stickerCatalog}
  />
);

This is easy to miss in image-heavy applications. The images get blamed because they are visible, while oversized JSON and RSC payloads remain invisible.

After projecting the catalog data, the production homepage document fell from roughly 999 KB to 169 KB.

The general rule is simple: serialize for the component you are rendering, not for every component that might render the object later.

2. Push client providers down the route tree

The root layout originally wrapped the entire application with authentication and saved-product state. That was convenient, but it made the public homepage pay for account features before a visitor used them.

The fix was architectural rather than image-specific: keep the root layout server-first and move client providers to the routes that need them.

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

// app/(site)/layout.tsx
export default function SiteLayout({ children }) {
  return (
    <AuthProvider>
      <SavedProductsProvider>
        {children}
      </SavedProductsProvider>
    </AuthProvider>
  );
}

The public homepage sits outside that route group, while account-aware pages remain fully functional.

This reduced the client work competing with image decode and paint on slower mobile hardware. It also follows a useful Next.js rule: render providers as deep in the tree as their consumers allow.

3. Make the LCP image discoverable and responsive

Below-the-fold images should usually be lazy-loaded. The LCP image should not.

For the hero, I used next/image with intrinsic dimensions, a realistic sizes value, and the Next.js 16 preload prop:

import Image from "next/image";

<Image
  src="/home/hero-digital-planner-ipad.webp"
  alt="Digital weekly planner open on an iPad beside a stylus"
  width={1402}
  height={1122}
  sizes="(max-width: 900px) 100vw, (max-width: 1440px) 55vw, 792px"
  preload
  decoding="async"
/>

Each prop has a different job:

width and height reserve the correct aspect ratio and prevent layout shift.
sizes tells the browser how wide the image will actually render, allowing it to choose an appropriate candidate from srcset.
preload tells Next.js that this is the page's critical image.

In Next.js 16, priority is deprecated in favor of preload. Do not combine every urgency signal by habit. Use preload for the one image that is predictably the LCP element, and let non-critical images keep the default lazy-loading behavior.

4. Use image tiers instead of one asset everywhere

An image catalog has at least three different viewing contexts:

Context	Asset	Goal
Catalog grid	Thumbnail	Fast scanning
Product page	Display image	Clear normal viewing
Zoom viewer	High-resolution image	Inspecting details

Using the original asset in all three contexts wastes bandwidth. Using only a thumbnail makes the product viewer look broken.

I made the media contract explicit:

type CatalogImage = {
  thumbnailUrl: string | null;
  displayUrl: string | null;
  zoomUrl: string | null;
};

Catalog cards request thumbnailUrl. Product pages start with displayUrl. The viewer loads zoomUrl only when the user opens or changes the high-resolution preview.

function previewUrlFor(item, variant = "thumbnail") {
  if (variant === "zoom") {
    return item.zoomUrl
      || item.displayUrl
      || item.thumbnailUrl
      || null;
  }

  if (variant === "display") {
    return item.displayUrl
      || item.thumbnailUrl
      || null;
  }

  return item.thumbnailUrl || null;
}

The fallback chain keeps old content usable while new records adopt all three tiers.

For immutable, versioned media objects, the delivery endpoint returns a long-lived cache policy:

Cache-Control: public, max-age=31536000, immutable

Versioned object keys are important here. A year-long cache is safe only when replacing an image creates a new URL instead of mutating the bytes behind an existing URL.

5. Remove render blockers only after proving they block rendering

The baseline included a 134 KB stylesheet that blocked first render. For this application, enabling CSS inlining removed an extra render-blocking request:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    inlineCss: true,
  },
};

export default nextConfig;

This is not a universal recommendation.

Inlining can increase HTML size, reduce the caching benefit of a shared stylesheet, and behave differently as an experimental feature evolves. It was useful here because the waterfall showed CSS delaying the LCP render, and the document had already been reduced substantially.

Measure this change against your production route. Do not enable it because an audit contains a generic “eliminate render-blocking resources” suggestion.

6. Keep visual effects away from the critical paint

Image sites often add fade-ins, clip-path reveals, and scale animations to make grids feel polished. These effects can delay when a fully downloaded image is considered painted.

My rule became:

the hero is visible immediately;
below-the-fold cards may animate when appropriate;
image containers reserve space with aspect-ratio or intrinsic dimensions;
prefers-reduced-motion removes non-essential transitions; and
the high-resolution viewer progressively replaces the display image without resizing its container.

A 600 ms entrance animation on the LCP element is still roughly 600 ms added to LCP. The browser does not award style points for making the most important content wait.

7. Add regression tests for performance decisions

Performance regressions often look harmless in code review. Someone passes the complete API object again. A provider returns to the root layout. A hero loses its responsive sizes value.

I added tests for those architectural contracts:

test("homepage catalog projection excludes detail-only payloads", () => {
  const projected = toHomepageCatalogItem(largeStickerProduct);

  assert.equal(projected.images, undefined);
  assert.equal(projected.downloadUrls, undefined);
  assert.ok(
    JSON.stringify(projected).length
      < JSON.stringify(largeStickerProduct).length / 4
  );
});

test("account providers stay off the homepage root bundle", async () => {
  const rootLayout = await source("../src/app/layout.tsx");

  assert.doesNotMatch(
    rootLayout,
    /AuthProvider|SavedProductsProvider/
  );
});

I also test that the hero still uses next/image, sizes, and preload.

These are not substitutes for Lighthouse or real-user monitoring. They protect the decisions that made the measured improvement possible.

Results

I ran multiple Lighthouse tests against the canonical production URL and used the median rather than selecting the best run.

Metric	Before	After
Mobile LCP	4.04 s	1.47 s
CLS	0	0
TBT	—	9 ms
Initial document	~999 KB	~169 KB

Desktop LCP was already around 0.89 seconds before this work. Reporting only the desktop result would have hidden the real user experience on constrained mobile networks and devices.

These numbers are Lighthouse lab results, not field data. The site did not have enough Chrome UX Report data to validate INP or real-user Core Web Vitals, so I did not treat a perfect Lighthouse score as proof that every production user had a perfect experience.

The optimization order I would use again

If I were diagnosing another image-heavy site tomorrow, I would work in this order:

Measure the production page several times on mobile.
Identify the actual LCP element.
Split LCP into TTFB, load delay, load duration, and render delay.
Inspect HTML, RSC, CSS, and JavaScript before recompressing the image.
Remove unused data crossing the server-client boundary.
Scope client providers and third-party scripts to the routes that need them.
Give the real LCP image intrinsic dimensions, responsive sizing, and early discovery.
Serve thumbnails, display images, and zoom assets for different contexts.
Remove measured render blockers.
Deploy, retest the canonical production URL, and compare medians.

The biggest lesson was not “use WebP” or “lazy-load images.” It was this:

An image can be the LCP element without being the LCP bottleneck.

Optimize the path that gets the image onto the screen, not just the image file.

References

Turning Photos into Buildable Pixel-Bead Patterns

West — Mon, 07 Sep 2026 09:09:00 +0000

A 58×58 bead board contains 3,364 positions. In one of our production checks, treating every position as part of the picture produced exactly 3,364 beads. With automatic background analysis enabled, the same source produced 900.

That difference is not a cosmetic optimization. It changes the material list, the cost of the project, and whether the exported guide is usable at all.

While building Pixel Bead Studio, I learned that converting an image into a physical bead pattern is not simply a matter of resizing a photo and choosing the nearest colors. A useful converter must preserve small features, understand empty space, map digital colors to a finite physical palette, and produce the same result everywhere—from the preview to the printable PDF.

This post explains the deterministic TypeScript pipeline we built to do that.

Why naive image resizing fails

The simplest implementation looks reasonable:

Resize the source image to the target grid.
Read one RGB value for each cell.
Find the nearest bead color.
Export the grid.

It also fails in predictable ways.

Thin outlines disappear because their average coverage is smaller than the surrounding fill. Eyes and facial details become muddy. White backgrounds turn into thousands of white beads. Near-neutral colors jump between visually inconsistent palette entries. Dithering can improve gradients, but it may also break a clean outline into isolated specks.

The central problem is that a bead cell is both a color sample and a structural decision. We therefore split the conversion into explicit stages:

source pixels
  -> source-resolution background analysis
  -> source-type detection
  -> 8×8 shape-aware sampling per bead
  -> perceptual palette matching
  -> optional protected dithering
  -> one canonical pattern matrix
  -> preview, material list, PNG, and PDF

Each stage solves one problem and leaves evidence that can be tested.

1. Remove backgrounds before resizing

Background removal must happen at source resolution. If the image is resized first, antialiasing mixes the foreground and background together. The converter then has to decide whether a pale edge pixel belongs to the subject or the canvas—with less information than it had at the start.

Our automatic mode samples the source perimeter, estimates a candidate background color, and checks how consistently that color appears across multiple sides. It then flood-fills only matching regions connected to the exterior.

The connectivity rule matters. An enclosed white area may be a real part of the design, such as the center of a ring. Removing every pixel close to white would erase it. Removing only exterior-connected pixels preserves enclosed regions.

The API makes uncertainty visible instead of hiding it:

type BackgroundMode = "auto" | "manual" | "off";

type BackgroundDiagnostics = {
  mode: BackgroundMode;
  decision: "removed" | "preserved" | "disabled";
  reason: string;
  confidence: number;
  removedPixels: number;
};

Automatic removal is deliberately conservative. If the border is inconsistent, the foreground is too similar to the candidate background, or compression artifacts make the decision ambiguous, the pipeline preserves the pixels. Users can then choose a background color manually or disable removal.

For creative tools, “I am not confident” is often a better result than a confident destructive edit.

2. Detect discrete pixel art before sampling it like a photo

A screenshot of pixel art and a photograph should not follow the same resampling path.

Photographs contain continuous tones and benefit from area-based resampling. Pixel art contains a deliberate lattice. Smoothing it creates colors that never existed in the source and blurs the boundaries we want to preserve.

We inspect horizontal and vertical edge peaks, search for a repeating period, and measure how strongly edges align with that lattice. A source can then be classified as continuous, a detected pixel lattice, or native low-resolution pixel art.

When the lattice evidence is strong, we recover colors from stable cell cores and use nearest-neighbor resampling. Otherwise, the image stays on the continuous-tone path.

This prevents an important category error: improving a photo and preserving pixel art are different jobs.

3. Treat every bead as an 8×8 analysis problem

One center pixel is too fragile, while a plain average erases small details. Our shape-aware sampler analyzes 64 subpixels for every output bead.

Inside each 8×8 region, the samples are grouped into two color clusters in Lab space. We then measure:

how much of the cell each cluster covers;
the perceptual distance between the clusters;
whether the smaller cluster forms a connected feature;
which sides of the cell the feature touches;
how that feature continues into neighboring cells.

A simplified decision looks like this:

const protectFeature =
  featureCoverage >= 0.18 &&
  featureCoverage <= 0.50 &&
  ciede2000(feature, surface) >= 9 &&
  connectedCoverage >= 0.60;

const representative = protectFeature ? feature : dominantColor;

Coverage alone is not enough. Random noise may occupy 20% of a cell, but it will not form a coherent local shape. Connectivity helps distinguish an eye, border, or narrow stroke from compression noise.

The sampler also records an outlineProtected flag. Later stages are allowed to simplify ordinary surface cells, but they cannot casually overwrite a cell selected to preserve structure.

4. Match physical colors perceptually

Bead palettes are finite. A photograph may contain thousands of RGB colors, while a selected bead brand provides a fixed catalog of purchasable color IDs.

Euclidean RGB distance is a poor proxy for human perception. Equal numeric changes in different RGB channels do not look equally large, especially around skin tones and low-chroma colors.

We convert both the sampled color and every palette entry from sRGB to CIE Lab, then choose the lowest CIEDE2000 distance:

function nearestPaletteColor(sample: RGB, palette: PaletteColor[]) {
  const sampleLab = rgbToLab(sample);

  return palette.reduce((best, color) => {
    const distance = ciede2000(sampleLab, hexToLab(color.hex));
    return distance < best.distance ? { color, distance } : best;
  }, { color: palette[0], distance: Infinity });
}

This still cannot make a limited palette reproduce every source color. What it can do is make the error correspond more closely to what a person sees.

The output stores real palette IDs rather than anonymous display colors. That lets the same matrix power editing, quantity calculation, and export.

5. Keep dithering away from structure

Floyd–Steinberg dithering distributes quantization error into neighboring cells. It can simulate intermediate shades with a limited palette, but physical beadwork exposes its cost: every extra speck is another bead the maker must place.

Our implementation uses serpentine traversal—left to right on one row, right to left on the next—to avoid a directional bias. More importantly, protected outline cells neither receive nor diffuse error.

for (let y = 0; y < height; y++) {
  const direction = y % 2 === 0 ? 1 : -1;

  for (const x of scanRow(width, direction)) {
    const cell = y * width + x;
    const match = nearestPaletteColor(rgb[cell], palette);
    output[cell] = match.id;

    if (!dither || outlineProtected[cell]) continue;
    diffuseError(cell, rgb[cell], match, direction, outlineProtected);
  }
}

The product exposes three choices: Off for clean flat regions, Auto for color-rich images, and On for stronger gradient simulation. The default should reflect the physical task, not just what looks smooth on a screen.

6. Make one pattern matrix the source of truth

An image converter is not finished when the preview looks correct.

The material count, editable workspace, PNG guide, and PDF guide must all represent the same cells. If each output performs its own interpretation of transparency or background removal, they will drift.

Our pipeline returns one integer matrix. A non-negative value is a palette index; an empty cell uses a sentinel value. Every downstream output consumes that matrix.

We verify the contract in browser tests:

automatic, manual, and disabled background modes recompute the pattern;
material quantities add up to the visible bead count;
enclosed foreground-colored regions remain present;
exterior empty cells stay empty in exported PNG files;
the PDF contains the same palette IDs and quantities shown in the UI.

For the release described here, the validation gate included 625 unit tests and six targeted desktop/mobile browser tests. Two supplemental visual-dataset tests were skipped in the clean release environment because their local image assets were intentionally not stored in the repository.

That last detail is worth reporting. A skipped visual test is not a passed visual test.

What I would do differently next time

Three lessons changed how I think about image conversion.

First, background removal is a topology problem before it is a color problem. Exterior connectivity is more useful than a global “remove white” rule.

Second, downsampling needs to preserve decisions, not pixels. The important question is not “What is the average color?” but “Is there a connected feature here that the final object needs?”

Third, printable exports are part of the algorithm. A correct preview with an incorrect material list is still an incorrect converter.

AI-assisted coding helped us explore implementations, generate adversarial cases, and tighten regression tests. It does not generate the final pattern in this pipeline. The shipped result is produced by deterministic image-processing rules and remains editable by the user.

That boundary has been useful: use AI to accelerate engineering, but keep the artifact reproducible, inspectable, and under the maker’s control.

You can try the current converter at Pixel Bead Studio.

How I Cut a 3D Homepage from 9.1 MB to 370 KB Without Removing the 3D

West — Mon, 07 Sep 2026 09:08:31 +0000

A single 3D model accounted for 83.7% of my homepage's initial payload.

It was a 7,833,440-byte GLB displayed in the hero of World Models Watch. The model looked good, but every mobile visitor downloaded it before deciding whether to interact with it.

Three mobile Lighthouse runs produced this baseline:

Metric	Baseline median	Final production median
Performance	53	96
LCP	4.525 s	2.653 s
CLS	0.146	0
TBT	357 ms	1 ms
Initial transfer	about 9.1 MB	about 370 KB

The final page still has the interactive 3D model. It simply does not load it until the visitor asks for it.

This is a lab-tested case study, not field data. Chrome UX Report did not have enough real-user data for the site, so INP was unavailable. The final LCP also missed my stricter target of less than 2 seconds. That distinction matters: this was a large improvement, not a claim that performance work was finished.

Here is what changed and, more importantly, how I found the work that actually mattered.

Find the request that dominates the page

The first audit could have led to a long list of generic fixes: compress images, reduce JavaScript, minify CSS, add caching, and so on.

The network evidence pointed somewhere much more specific:

Initial page resources:                    ~9.1 MB
/generation-models/anisotropy-barn-lamp.glb: 7.83 MB
Share of measured resources:                83.7%

Optimizing several 30 KB assets while continuing to load a 7.8 MB model would not materially change the experience.

The useful question was not “How do I make a GLB slightly smaller?” It was “Why is a mobile visitor downloading this GLB before interacting with the 3D viewer?”

That changed the solution from asset tuning to load-path design.

Replace eager 3D with a mobile interaction boundary

On mobile, the homepage now starts with a 19 KB AVIF cover. The cover has the same 4:3 geometry as the interactive stage, so switching from one to the other does not move surrounding content.

The actual stage component is imported after a tap:

"use client";

import Image from "next/image";
import { useCallback, useState } from "react";

type StageComponent =
  typeof import("./HomeInteractiveStage").HomeInteractiveStage;

let stagePromise: Promise<StageComponent> | null = null;

function requestInteractiveStage() {
  stagePromise ??= import("./HomeInteractiveStage").then(
    (module) => module.HomeInteractiveStage,
  );
  return stagePromise;
}

export function HomeInteractiveStageClient() {
  const [Stage, setStage] = useState<StageComponent | null>(null);
  const [requested, setRequested] = useState(false);

  const loadStage = useCallback(() => {
    setRequested(true);
    void requestInteractiveStage().then((component) => {
      setStage(() => component);
    });
  }, []);

  if (requested) {
    return Stage ? <Stage /> : <div role="status">Loading 3D…</div>;
  }

  return (
    <button
      aria-label="Load interactive 3D preview"
      onClick={loadStage}
      type="button"
    >
      <Image
        alt=""
        fetchPriority="high"
        height={576}
        loading="eager"
        src="/home-lab/model-cover-mobile.avif"
        width={768}
      />
      <span>Tap to load · Drag to rotate</span>
    </button>
  );
}

The promise is cached at module level. Repeated clicks or renders reuse the same import instead of starting duplicate work.

Desktop can still request the interactive stage automatically. The important product decision is that mobile users get a useful, stable first screen before paying for the 3D runtime and asset.

Lazy-load the runtime as well as the component

Code-splitting the React component is not enough if another import pulls the viewer runtime into the initial route.

I removed direct @google/model-viewer imports from homepage and generation-output components. A shared loader now injects the self-hosted runtime only when a 3D component mounts:

"use client";

const selector = 'script[data-model-viewer-runtime="true"]';
let viewerPromise: Promise<void> | null = null;

export function loadModelViewer() {
  if (customElements.get("model-viewer")) return Promise.resolve();
  if (viewerPromise) return viewerPromise;

  viewerPromise = new Promise<void>((resolve, reject) => {
    const existing = document.querySelector<HTMLScriptElement>(selector);
    const script = existing ?? document.createElement("script");

    script.addEventListener(
      "load",
      () => void customElements.whenDefined("model-viewer").then(resolve),
      { once: true },
    );
    script.addEventListener("error", () => reject(new Error("3D runtime failed")), {
      once: true,
    });

    if (!existing) {
      script.dataset.modelViewerRuntime = "true";
      script.src = "/vendor/model-viewer.min.js";
      script.type = "module";
      document.head.appendChild(script);
    }
  });

  return viewerPromise;
}

This loader solves three problems:

it keeps the runtime out of the initial mobile path;
it prevents duplicate script elements;
it gives every 3D surface one loading contract.

The walkable Three.js world was heavier still. Instead of embedding that entire runtime on the homepage, I moved it to a dedicated /world-experience route. The homepage shows a preview and a clear entry point.

The feature was not removed. Its cost was moved to the moment of intent.

Check route prefetch after adding lazy loading

After deferring the component, I still saw generator code arrive earlier than expected.

The first assumption was stale build output. The actual cause was Next.js route prefetching. Homepage calls to action and the mobile navigation linked to generator routes, so the browser downloaded route dependencies before the user navigated.

For heavy destinations, I disabled automatic prefetch:

<Link href="/image-to-3d-model" prefetch={false}>
  Create your model
</Link>

This is an easy failure mode to miss. A component can be correctly lazy-loaded on its own route while a nearby <Link> quietly warms that route and reintroduces the same cost.

Prefetch is valuable when the prefetched destination is small and likely to be visited. It is not automatically a win when the route owns a large editor, authentication UI, task history, or 3D dependencies.

Keep global layouts boring

The root layout originally had responsibilities that were not needed by anonymous homepage visitors:

the global authentication provider;
a deferred generation task center;
advertising;
analytics.

“Deferred” components can still expand a route's dependency graph. A provider at the root makes every page pay part of its initialization cost.

I moved account and task-center behavior closer to the routes that require it. Public marketing pages now render without initializing Clerk. Advertising and analytics wait until the browser is idle, with a timeout fallback, instead of joining the critical rendering path.

The architectural rule is simple:

Root layout: document shell and truly global UI
Public page: immediately useful content
Account routes: authentication runtime
Generator routes: editor and task dependencies
3D interaction: viewer and asset after intent

Route ownership is a performance feature. It stops one convenient global import from taxing every visitor.

Fix layout stability at the boundary

The baseline CLS median was 0.146. The 3D area and mobile sections did not reserve enough stable space before late content arrived.

The cover and loaded stage now share fixed intrinsic dimensions and a 4:3 container. Loading text also renders inside that same box. The page no longer discovers the height of the hero after JavaScript runs.

.interactiveStage {
  aspect-ratio: 4 / 3;
  inline-size: 100%;
  overflow: hidden;
}

.stageCover,
.stageLoading,
.stageLoaded {
  block-size: 100%;
  inline-size: 100%;
}

This is why the final CLS reached 0. The image format helped transfer size; intrinsic geometry fixed stability.

Protect the loading boundary with tests

Performance regressions often look harmless in code review. Someone restores a static viewer import, puts authentication back in the root layout, or removes prefetch={false}.

I added source-level tests for the invariants that must stay true:

test("mobile 3D stays behind an explicit request", () => {
  const gate = source("../src/components/home/HomeInteractiveStageClient.tsx");
  const stage = source("../src/components/home/HomeInteractiveStage.tsx");
  const loader = source("../src/lib/model-viewer-loader.ts");

  assert.match(gate, /onClick=\{loadInteractiveStage\}/);
  assert.doesNotMatch(stage, /import\("@google\/model-viewer"\)/);
  assert.match(loader, /\/vendor\/model-viewer\.min\.js/);
  assert.ok(statSync(cover).size <= 50_000);
});

test("the public shell does not initialize account UI", () => {
  const layout = source("../src/app/layout.tsx");

  assert.doesNotMatch(layout, /ClerkProvider/);
});

These tests do not replace Lighthouse, browser traces, or real-user monitoring. They stop known architectural regressions before another measurement is needed.

The production release was also checked for behavior, not only scores:

no GLB request before interaction;
no initial Clerk or Google-script request;
the viewer runtime and GLB loaded successfully after a click;
homepage, generator, sign-in, and world-experience routes still worked;
the production build and complete test suite passed.

What the numbers actually prove

The final three production Lighthouse runs reported:

Performance: 97 / 91 / 96
LCP:         2.43 s / 2.94 s / 2.65 s
CLS:         0 / 0 / 0
TBT:         0 ms / 19 ms / 1 ms
Transfer:    ~370 KB
Requests:    43

The improvement came from removing work, not making the browser execute the same work more efficiently.

There are also clear limits to the result:

median LCP was 2.653 seconds, above the aggressive sub-2-second target;
lab variance remained visible across runs;
INP could not be evaluated without enough field data;
the measurements describe this release and test setup, not a permanent guarantee.

That is the useful lesson. A dramatic payload reduction can coexist with unfinished LCP work. Report transfer, LCP, CLS, TBT, test conditions, and field-data availability separately.

The checklist I would reuse

For any homepage with interactive 3D, maps, editors, or other heavy media:

Run the audit more than once and report the median.
Sort initial network requests by transferred bytes.
Ask whether the largest resource is required before interaction.
Defer the component, runtime, and asset—not only one of the three.
Inspect route prefetching for heavy destinations.
Remove route-specific providers from the root layout.
Reserve final geometry before client code runs.
Verify the deferred feature still works after a real click.
Add tests for the dependency boundaries you do not want to regress.
Keep lab results separate from field data and from your target.

The fastest 7.8 MB GLB is the one a visitor never has to download.

The better product is not a homepage without 3D. It is a homepage that waits until the visitor says, “Show me the 3D.”

You can explore the live project at World Models Watch. Its public repository and technical documentation are available on GitHub.

Keeping Photo Editor Previews and Exports in Sync with TypeScript and Sharp

West — Mon, 07 Sep 2026 09:07:12 +0000

A user positions a portrait inside a frame, checks the preview, and clicks Export. If the downloaded image crops their hair differently, the editor has broken a basic promise: the layout they approved should survive the export.

I build Photocard.ai, a tool for creating custom photocards. Its Maker pipeline combines uploaded photos with template artwork. That means handling photo placement, background removal, decorative layers, and multiple output sizes.

The useful architectural decision was to make those composition decisions explicit and save them in a versioned render plan. Preview and high-resolution rendering can then consume the same decisions.

This article focuses on that template renderer. The TypeScript examples are simplified illustrations of the design, with storage and application plumbing omitted.

The goal is consistent composition across resolutions. A lightweight browser preview can still differ from a final render in hair detail, filtering, and edge quality. Those are separate things to validate.

Save the decisions that produced the image

A template thumbnail shows the intended appearance. It cannot tell the renderer which source belongs in each slot, where to crop it, or which decoration belongs in front of the person.

In the Maker implementation, a template manifest describes those rules. A render plan resolves them for a particular set of uploads.

A reduced representation looks like this:

type Rect = {
  x: number;
  y: number;
  width: number;
  height: number;
};

type RenderSlot = {
  sourceIndex: number;
  sourceCrop: Rect;       // Relative to the oriented source image
  destination: Rect;      // Relative to the output canvas
  zIndex: number;
  subjectAlphaKey?: string;
  refinedForegroundKey?: string;
  effectSeed: number;
};

type RenderPlan = {
  version: 2;
  templateVersionId: string;
  assetPackageVersion: string;
  outputVariant: string;
  slots: RenderSlot[];
};

The application has additional fields for clipping, filters, subject treatments, and edge processing. The principle stays small: save the information needed to explain the composition.

When an export starts, it should load the saved crop. Running an automatic crop detector again creates another opportunity to choose a different face position.

The same applies to decorative effects. If a paper-edge treatment uses randomness, save its seed so another render does not choose a different pattern.

Version numbers also need something concrete behind them. Keep the corresponding artwork and processing behavior available for as long as old cards must remain editable. A version string cannot recover an overwritten asset.

Let each template slot choose its source

A portrait inside a film frame may need the complete original photo. A sticker composition may need a transparent person.

The manifest makes that choice explicit:

type SourceComposition = "original_photo" | "cutout_subject";

type TemplateSlot = {
  sourceIndex: number;
  sourceComposition: SourceComposition;
  frame: Rect;
  zIndex: number;
};

This prevents a subtle failure: applying background removal to a slot simply because a cached mask happens to exist.

For the normal full-photo path, the renderer retains the scene. For a cutout slot, a missing required mask is a validation error. Explicit editing features, such as an outline mode, can introduce their own rules, but the presence of an optional asset should never decide the visual policy by accident.

This matters for group photos, too. A single-person mask and the original group image contain different subjects. Choosing between them changes the content of the card.

Separate source coordinates from canvas coordinates

There are two rectangles in a crop operation:

The source crop selects a region of the uploaded image.
The destination frame places that region on the output canvas.

Both can use normalized coordinates. An x value of 0.1 means ten percent of the relevant image's width. The source rectangle is measured against the oriented upload; the destination is measured against the canvas.

Consider a destination frame of { x: 0.1, y: 0.1, width: 0.8, height: 0.8 }:

Canvas	Left	Top	Frame width	Frame height
600 × 900	60	90	480	720
2400 × 3600	240	360	1920	2880

These are illustrative sizes with the same aspect ratio. The placement scales without a new layout decision.

Convert to pixels at the rendering boundary. This helper covers rectangles fully inside an image:

function toPixels(rect: Rect, width: number, height: number) {
  const values = [rect.x, rect.y, rect.width, rect.height];
  if (
    !Number.isInteger(width) || width <= 0 ||
    !Number.isInteger(height) || height <= 0 ||
    !values.every(Number.isFinite) ||
    rect.x < 0 || rect.y < 0 ||
    rect.width <= 0 || rect.height <= 0 ||
    rect.x + rect.width > 1 || rect.y + rect.height > 1
  ) {
    throw new Error("Invalid image dimensions or rectangle");
  }

  const left = Math.round(rect.x * width);
  const top = Math.round(rect.y * height);
  const right = Math.round((rect.x + rect.width) * width);
  const bottom = Math.round((rect.y + rect.height) * height);

  if (right <= left || bottom <= top) {
    throw new Error("Rectangle is smaller than a renderable pixel region");
  }

  return { left, top, width: right - left, height: bottom - top };
}

Rounding the boundaries keeps the rectangle's edges explicit. Allow for rounding differences when comparing different output resolutions.

There are three other details to settle before this helper runs:

Orientation: normalize EXIF orientation before calculating crop coordinates. Otherwise, the browser and server can interpret the same photograph with different axes.

Aspect ratio: the crop planner must resolve the fit between the selected source region and the destination. Normalized coordinates alone do not prevent stretching. Sharp exposes distinct cover, contain, and fill behaviors; choose deliberately when materializing the crop. Sharp resize documentation.

Padding: a cutout editor may let someone shrink a person enough to reveal transparent space beyond the original image. Our crop system supports bounded virtual source rectangles for this. The small helper above deliberately handles only in-bounds rectangles; virtual crops need a padding step before extraction.

Make the layer order visible in code

The composition has a readable order:

Background artwork
    ↓
Artwork behind the subjects
    ↓
Prepared photo slots, ordered by zIndex
    ↓
Foreground artwork

A title behind someone's head and a sticker overlapping their shoulder belong at different points in that sequence.

With every slot already cropped, masked, treated, and placed onto a transparent canvas, the final compositing step can stay small:

import sharp from "sharp";

async function compositeCard(input: {
  background: Buffer;
  behindSubject: Buffer;
  subjects: Array<{ png: Buffer; zIndex: number }>;
  foreground: Buffer;
}): Promise<Buffer> {
  // All inputs are already prepared at the same canvas dimensions.
  const subjects = [...input.subjects]
    .sort((a, b) => a.zIndex - b.zIndex);

  return sharp(input.background)
    .composite([
      { input: input.behindSubject, left: 0, top: 0 },
      ...subjects.map(({ png }) => ({ input: png, left: 0, top: 0 })),
      { input: input.foreground, left: 0, top: 0 },
    ])
    .png()
    .toBuffer();
}

The array order is part of the rendering contract. Sharp also requires overlay images to be no larger than the processed base image. Preparing each layer at the target canvas dimensions makes that constraint straightforward to check. Sharp composite documentation.

Filters deserve an equally explicit boundary. If a preset should affect the portrait, apply it to the portrait before composition. Applying it to the flattened result also changes the frame, typography, and decorations.

Keep alpha and foreground color separate

A clean-looking mask can still produce a pale fringe around someone's hair.

The mask describes coverage. The source RGB may still contain color from the old background, especially around partially transparent edges.

The preparation pipeline therefore keeps separate artifacts:

Artifact	Purpose
Oriented source	Stable coordinates and original image detail
Subject alpha	Continuous coverage around hair and soft edges
Refined foreground	Foreground color with background contamination reduced
Effect silhouette	Shape used for borders, shadows, and cutout treatments

These assets need consistent coordinate alignment, even when a renderer resamples them to different resolutions.

A hard sticker border and a soft strand of hair have different requirements. Deriving an effect silhouette lets the renderer make a stronger outline without hard-thresholding the alpha used for the actual portrait.

The render plan references the prepared artifacts and mask revision. A retry can reuse that preparation instead of silently asking another segmentation pass to interpret the person again.

Define what each preview promises

The current local editor work separates a fast browser preview from higher-quality preparation during generation.

That distinction needs to remain visible in both the architecture and the interface:

Render	Main purpose	Expected limitation
Interactive browser preview	Adjust position and scale	Approximate masks and effects
Server-rendered preview	Inspect the prepared composition	Lower output resolution
High-resolution export	Produce the final file	Detail remains limited by source quality

The browser draft can use local photo URLs and a lightweight mask. The authoritative render uses prepared assets and the saved composition rules.

In the server renderer, preview and HD output share the composition function. The target canvas and resolution-specific assets change. An HD export recomposes the sources and template layers at the requested size.

That is different from enlarging a flattened preview, but it still cannot manufacture missing detail in a small upload. A large output canvas describes file dimensions; it does not prove that every input contains that much detail.

Shared geometry also does not guarantee pixel-identical results after downscaling. Resampling, edge refinement, and resolution-dependent effects still need visual checks.

Test the rendering promises

Synthetic images make useful tests because their expected pixels are easy to reason about.

A solid blue background, a red subject, and a green foreground patch can verify layer order without depending on a real portrait. A soft alpha edge can check whether filtering preserves transparency.

The repository includes tests for shared crop geometry at preview and HD sizes, original-photo behavior when a matte exists, EXIF orientation, alpha preservation, and behind-subject versus foreground ordering.

For a similar editor, I would start with these checks:

Render one saved crop at two resolutions and compare normalized placement within a rounding tolerance.
Give a full-photo slot an available mask and confirm that its normal rendering path still preserves the complete image.
Place a subject across behind-subject and foreground artwork, then inspect known overlap pixels.
Apply a portrait filter and check that the template artwork stays unchanged.
Remove a required cutout artifact and confirm that rendering fails instead of producing a different composition.

Then inspect real photos: loose hair, dark clothing, busy backgrounds, unusual framing, and groups. Geometry tests can establish where the subject lands. They cannot establish whether the hair edge looks convincing.

If you are building a template editor, start by saving one source crop, one destination frame, and one template version. Render that plan at two sizes before adding more effects. It gives you a concrete contract to preserve as the editor grows.

These are the rendering ideas behind the Maker in Photocard.ai. The templates provide the artwork; the render plan records how each photo belongs inside it.