DEV Community: Bo Qian

Why your design looks fine on screen and broken on a shoe: three constraints, three consequences

Bo Qian — Sun, 01 Nov 2026 04:28:39 +0000

I build a browser-side customizer for printed sneakers. You upload artwork, it gets sliced across the shoe panels, and you preview it on the actual shoe before ordering: bukefootwear.com. The slicing geometry is in the first post, the magnification math in the second, the render pipeline in the third, the deploy budget in the fourth, and the routerless storefront in the fifth.

This one is different. It is not about a bug I fixed. It is about three physical properties of a shoe that decide what the software can and cannot promise, and the three places where ignoring them produced a page that looked correct and was not.

The failure mode is not ugly, it is plausible

Every bad custom-print result I have seen looked acceptable on a laptop. That is the problem. When a canvas render is wrong in an obvious way — black output, a stretched image, a 404 texture — you fix it in a minute. When it is wrong in a plausible way, it ships.

A design that loses four millimetres of its border at the seam still looks like a design. A motif that breaks across the toe cap still reads as a motif. A palette that shifts half a shade on a fabric substrate still reads as the same palette. You only find out after the pair is made.

So the useful framing is not "how do I rasterise artwork onto a shoe". It is "which constraints can the browser check, and which ones can only the person looking at it check". Three constraints turned out to matter more than everything else I did.

Constraint one: the surface is not developable

A t-shirt is a flat rectangle. You can print it in one pass and the artwork behaves like a poster glued to cardboard. A shoe upper is a curved shell. There is no isometric mapping from a plane onto a doubly-curved surface that preserves both distances and angles — this is Gauss's theorema egregium, and it is the reason a basketball cannot be wrapped in gift paper without creases.

The engineering consequence is that you do not flatten the shoe. You decompose it. A pair of low-tops in our pipeline resolves into dozens of separate cut pieces, each with its own outline, its own safe area and its own transform back into shoe space. The user's single upload becomes dozens of independent renders.

The consequence inside the code is that there is no single "the design" object after slicing. There is an array. Anything that assumed one image, one bounding box, one transform is now wrong, and it fails quietly: each panel renders fine in isolation, and the composition is broken.

If you are building anything similar, the data model has to be decided before the renderer. Ours looks roughly like this:

{ code: 'toe-cap', path: Path2D, safeArea: Path2D, warp: Float32Array }

The warp is the part people skip. A panel outline tells you where a piece is on the shoe. It does not tell you how the artwork bends to sit on it. Those are two different pieces of data and conflating them is the single most expensive mistake in this class of project.

Constraint two: the seam eats the edge

Panels are joined by stitching, and stitching needs material to hold. Every panel therefore carries a seam allowance — a strip along its outline that will be folded under or consumed by the join. Artwork placed there is not printed, or is printed and then hidden.

This converts a design problem into a clipping problem, and the clipping is where the silent failure lives: an out-of-bounds design gets cropped, and cropping is not an error. A drawImage call whose destination rectangle extends past the canvas does not throw, does not warn, and does not return a status. It draws what fits.

I have written about the mask layer specifically elsewhere, but the general lesson is worth stating plainly: in a canvas pipeline, geometry violations are not exceptions. The only way to catch them is to compare the intended area against the safe area yourself, before drawing, and to surface the result to the user as a number or a highlighted region — not as a console message nobody reads.

The practical rule I ended up with: never let the renderer be the first thing that discovers a bounds problem. Validate the placement against the safe area on input, and treat the renderer as an optimiser for a decision already made. This is the same reasoning as validating a form on submit rather than trusting a database constraint to reject it later.

Constraint three: the substrate is not paper

Paper holds ink on the surface. A shoe upper is a textile or a synthetic leather: it absorbs, it stretches over a last, and it moves with the foot. Three things follow, and none of them are visible in a canvas preview:

Colour shifts. Ink on a woven or microfibre surface sits differently than ink on a coated paper. A mid-tone that reads neutral in sRGB can go warm or muddy on a warm-grey substrate. There is no browser API for "how will this CMYK-adjacent stack land on this material" — the material sample is the oracle.

Edges soften. Small type and one-pixel hairlines do not survive the transfer intact. This is not a resolution problem in the usual sense; it is a material problem. Our answer was to stop specifying DPI and start specifying pixels against a measured magnification factor, which is what the second post covers.

The preview can only be honest about the first two constraints. A canvas render can show you cropping and composition truthfully. It cannot show you colour on material or edge softening. Any claim otherwise is a lie dressed up as a feature, so the preview needs to say what it does not model — and that statement belongs on the page, not in a FAQ.

What the constraints cost in pixels

Once the surface is non-developable and the pieces are small, magnification does the budgeting for you. Measured across panels, a single uploaded image is stretched by a factor between roughly 2.9× and 4.8× depending on where the panel sits. Working backwards from a target print resolution gives a hard floor on upload size rather than a preference: around 2,000 px lands near 78% of target, 2,400 px near 98%, and about 2,916 px clears it.

That number is not interesting on its own. It is interesting because it is derivable, and because it can be shown to a user before they upload anything. "Minimum 2,900 pixels on the long edge" is a rule a person can act on. "High resolution required" is not.

The acceptance problem

Put the three constraints together and you get a class of defect that no unit test catches: each panel is individually correct, the composition is wrong. The only reliable check is a human looking at the assembled result.

So the thing I actually shipped for this is not a spec sheet, it is an acceptance surface. There is a page that renders one artwork across the panel set at real proportions, side by side with an assembled preview, so a person can see whether the pattern breaks at a seam or loses its border: panel-preview. It is the same data the customizer uses, presented so that the failure is visible instead of plausible.

The written version of the same reasoning — why an eighteen-panel curved shell is a genuinely different problem from a printed t-shirt, and what that means for what you can promise a customer — is at why shoes are harder than shirts.

What this changes about the build

None of this is exotic graphics programming. It is constraint accounting. The three things I would tell anyone starting a project that maps flat artwork onto a curved, seamed, non-paper object:

Decide the panel data model before the renderer. Outline, safe area and warp are three separate facts. Conflating them produces a renderer that cannot be fixed, only rewritten.
Treat geometry violations as validation, not exceptions. Canvas will happily crop your design out of existence and return success.
Be explicit about what the preview does not model. Colour on substrate and edge softening are outside the browser's knowledge. Say so.

The results, if you want to see whether the constraints are actually being respected rather than just described, are four prints on four different base shoes — a woven geometric, a botanical, a chain motif and a tonal Art Deco fan — each with the full seven-view set on its own page. They are collected at the featured designs gallery; Onyx Deco is the clearest test of the third constraint, because a tonal print with almost no contrast is exactly the case where a colour shift stops being subtle.

And if you want to test the whole pipeline against your own artwork, the customizer is the same one I have been describing: design your own.

The numbers in this post come from measurements on our own panel set, not from a general model. If your panel count, seam allowance or substrate differ, the constants move — the constraints do not.

Eight products, one URL: what breaks when a storefront has no router

Bo Qian — Sat, 31 Oct 2026 17:09:23 +0000

I build a browser-side customizer for printed sneakers. You upload artwork, it gets sliced across the shoe panels, and you preview it on the actual shoe before ordering: bukefootwear.com. The geometry is in the first post, the magnification math in the second, the render pipeline in the third, the deploy budget in the fourth.

This one is about the storefront shell around it. Our release is a folder of static files on Cloudflare Pages. There is no router, no server, no /product/[slug] route. Eight shoe styles are served by one HTML file:

https://bukefootwear.com/product?product=KJ1
https://bukefootwear.com/product?product=MT1
...

That works fine for humans and it is a trap for everything else. Four things broke, and none of them threw an error.

1. Canonical collapse: eight pages that all claim to be the same page

The first version had no canonical at all. Then I added one — statically, into the <head> of product.html:

<link rel="canonical" href="https://bukefootwear.com/product">

Eight product URLs, one canonical target. To a crawler that says "these eight pages are duplicates of one page, index that one instead." Every individual style gets dropped. The page that ranks is a page with no product on it until JavaScript runs.

The fix is to make the canonical a function of the query string, and to accept that it is now JavaScript's job:

const code = new URLSearchParams(location.search).get('product');
const canonical = document.createElement('link');
canonical.rel = 'canonical';
canonical.href = 'https://bukefootwear.com/product?product=' + encodeURIComponent(code);
document.head.append(canonical);

Two rules I now follow because of this:

Never ship a static canonical on a query-param page. A wrong canonical is worse than a missing one, and it is invisible in the browser.
The static HTML must never contradict what the JS writes. If a <link rel="canonical"> is already in the document, append gives you two canonicals and Google picks the first. The static one wins, and it is the wrong one.

The same shape of bug hit our designer page: it had <html lang="zh-CN"> and a Chinese <title>, and designer.js overwrote the title at runtime. Editing the HTML changed nothing for real visitors because the JS ran a millisecond later. Whatever the crawler reads statically and whatever the visitor sees have to be the same claim.

2. Zero structured data, on the pages that sell

Eight commercial pages, and the count of JSON-LD blocks across all of them was:

$ grep -c "application/ld+json" product.html
0

Not "malformed", not "warned in Search Console" — simply absent. Meanwhile the blog pages had it. The money pages were the only ones without a machine-readable name, price, or availability.

The reason was structural, not laziness: JSON-LD is per-product data, and a single static file cannot hold eight products' prices honestly. So it has to be generated where the product is known:

const ld = {
  '@context': 'https://schema.org',
  '@type': 'Product',
  name: `BUKE ${product.name} ${code}`,
  sku: code,
  brand: { '@type': 'Brand', name: 'BUKE STUDIO' },
  material: String(product.material || '').replace(/\s*[\r\n]+\s*/g, ', ').trim(),
};
if (images.length) ld.image = images.slice(0, 6);
if (fixedPrice && Number.isFinite(Number(fixedPrice.price))) {
  ld.offers = {
    '@type': 'Offer',
    price: Number(fixedPrice.price),
    priceCurrency: 'USD',
    url: 'https://bukefootwear.com/product?product=' + encodeURIComponent(code),
    availability: fixedPrice.purchasable
      ? 'https://schema.org/InStock'
      : 'https://schema.org/PreOrder',
    itemCondition: 'https://schema.org/NewCondition',
  };
}
const s = document.createElement('script');
s.type = 'application/ld+json';
s.textContent = JSON.stringify(ld);
document.head.append(s);

Two details that matter more than the schema itself:

The offers block is conditional. If the price is missing, emitting "price": undefined gives you {"@type":"Offer"} with no price — an invalid Offer that is worse than no Offer. Wrap the whole object, not the field.

material came from a text field with newlines in it. It arrived as "Upper: microfiber\nSole: rubber". Valid JSON, valid string, and a value no consumer wants to display. Normalise at the boundary, not at the renderer.

Verification has to be done in a real browser, because the block does not exist in curl output:

Product  sku=KJ1    price=98  USD  InStock  imgs=6
Product  sku=MT1    price=68  USD  InStock  imgs=6
Product  sku=DF1    price=88  USD  InStock  imgs=6

That is the same lesson as the canonical: if JavaScript writes it, only a JS-executing check counts. I have wasted more time on curl | grep returning empty while the browser was correct than on any other class of bug in this project.

3. Social cards never render, because crawlers do not run your JS

This one is specific and it bit us during a campaign. We were pushing a design challenge on Threads, X and Instagram. When someone shares a link, the platform fetches the URL, reads og:title, og:description, og:image from the raw HTML — and does not execute JavaScript.

Result: the links we were paying attention to, shared all day, rendered as bare text. No image. The tags we had were set by JS, therefore invisible to every scraper:

$ curl -s https://bukefootwear.com/challenge | grep -c 'og:image'
0

Three of our most-promoted pages (/product, /designer, /challenge) had zero or partial Open Graph tags. The homepage had them. The campaign pages did not.

The fix is unglamorous: static tags in the HTML, per page, with a real 1200px image, plus the Twitter variants because X does not read Open Graph:

<meta property="og:image" content="https://bukefootwear.com/assets/studio-v4/XB1-pair-1200.webp">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="1200">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://bukefootwear.com/assets/studio-v4/XB1-pair-1200.webp">

And here is the honest trade-off: on a query-param storefront the static og:image is one image for all eight products. Scrapers cannot see the per-product image the JS picks. You either accept a generic card, or you generate eight real HTML files at build time.

I accepted the generic card for now. It is a small loss and an enormous improvement over nothing. The general rule: anything that must be readable by a machine that does not run JS (crawlers, social scrapers, link previews, RSS, some ad platforms) cannot be produced by client-side logic. Audit those separately; they are not part of your "the page works" test.

4. The price lived in four places

This is the one that would eventually have cost real money.

Prices for the eight styles were written into the product page markup, into a cart script, into a checkout calculation, and into one more place I found by grepping. They agreed, because I had been careful, which is exactly why the bug had not surfaced yet.

The data does not look risky:

// one module, the only place a price is allowed to be typed
window.BukePricing.products = {
  KJ1: { price: 98, purchasable: true },
  MT1: { price: 68, purchasable: true },
  ...
};

But a made-to-order shop has a twist: price and freight are different rules that both change. A pair costs $98. Shipping is charged once for the first pair and 40% for each additional one in the same order — so the number a customer sees depends on order composition, not on the product. Two formulas, two owners, and if either one is duplicated you get a cart that disagrees with the product page and nobody notices until a customer does.

What made this safe was not discipline. It was making the number impossible to type twice:

The product page renders price from the module.
The cart reads the same module.
The JSON-LD reads the same module.
Freight lives in exactly one function, and its constants are named, so "we changed the EU rate" is a one-line diff.

I now test pricing the same way I test pixels: change one value in the source of truth, reload three pages, and confirm all three moved. If one of them does not, I found a duplicate.

What a router would and would not have fixed

The reflexive answer is "use a framework with real routes." Eight static HTML files generated from one template would genuinely fix three of the four problems: real canonicals, real per-product Open Graph, no JS-dependent metadata. That is a build step, not a rewrite, and it is the correct destination.

It would not fix the fourth. A router does not create a single source of truth for price; it just moves the duplication. The rendering layer is the easy part — it is the data ownership that decides whether a storefront can be trusted with money.

Until then, the checklist I actually use before shipping a page that sells something:

curl the URL and confirm canonical, description, title and Open Graph are all present in the raw HTML.
Render it in a browser and confirm the JS-written versions match what curl returned, or that you accept the difference knowingly.
Grep for the number. If the price appears in more than one file, that is the bug, whether or not it is wrong today.
Count JSON-LD blocks. Zero on a commercial page is a decision you did not make on purpose.

The product pages these lessons came from are here, if you want to see the result: KJ1 low-top, MT1 slipper, and the designer that does the slicing.

Nine files of headroom: what a 1,000-file deploy limit taught me about srcset and dead assets

Bo Qian — Sat, 24 Oct 2026 14:39:35 +0000

I build a browser-side customizer for printed sneakers. You upload artwork, it gets sliced across 66 leather panels, and you see it on the actual shoe: bukefootwear.com. The geometry is covered in the first post, the magnification math in the second, the 44-second render in the third.

This one is about the part nobody writes about: the deploy.

Our release is a folder of static files pushed to Cloudflare Pages through a direct upload. That path caps a deployment at 1,000 files, and it fails at upload time, not build time. We found out where we stood by counting:

$ find cloudflare-release -type f | wc -l
1068
$ find cloudflare-release/assets -type f | wc -l
991

991 assets, 9 files of headroom, and a product roadmap that wanted to add more. That is not a performance problem. It is a packaging problem, and it forced a question I had been avoiding: how much of what we ship is never requested?

The answer was "more than half," and the two traps I hit while removing it are what this post is about.

Where the files come from

The customizer needs factory photos and alpha masks. Per model: 5 camera angles, one base photo each, and 29 panel masks per angle. Multiply by 8 models and you get a few thousand candidate images before anyone writes a line of CSS.

Most of that mass is not the 66 panel textures. It is higher-resolution originals, validation renders, calibration frames, and three generations of mask sets that were superseded but never deleted. Deleting them by hand is how you break a page you forgot about — nobody remembers which calibration image is still referenced from a comparison view.

So instead of guessing, measure.

The scanner: keep only what is reachable

Our pages are static HTML plus a handful of JS and CSS files, and all local assets live under assets/. That is enough to define reachability: walk every .html, .js, .css file, find anything that looks like an assets/... path, and stat it.

const sourceFiles = (await walkFiles(output)).filter((file) => {
  const rel = relativePosix(file);
  return !rel.startsWith('assets/') && ['.html', '.js', '.css'].includes(extname(file).toLowerCase());
});

const keep = new Set();
const assetRoot = resolve(output, 'assets');

for (const sourceFile of sourceFiles) {
  const content = await readFile(sourceFile, 'utf8');
  for (const match of content.matchAll(/assets\/[A-Za-z0-9_./-]+/g)) {
    const candidate = resolve(output, match[0].split(/[?#]/, 1)[0]);
    if (candidate !== assetRoot && !candidate.startsWith(assetRoot + sep)) continue;
    try {
      const details = await stat(candidate);
      if (details.isFile()) keep.add(candidate);
      else if (details.isDirectory()) for (const child of await walkFiles(candidate)) keep.add(child);
    } catch {
      if (/\.(?:png|jpe?g|webp|svg|ico|woff2?)$/i.test(match[0])) {
        errors.push(`Referenced asset is missing: ${match[0]}`);
      }
    }
  }
}

for (const assetFile of await walkFiles(assetRoot)) {
  if (!keep.has(assetFile)) await rm(assetFile);
}

Two details that matter more than the code:

Directories are kept whole. If a reference resolves to a directory, everything inside it survives. That is deliberate: some assets are loaded by naming convention (angle-3.webp) inside a loop, and I would rather keep an unused folder than ship a broken angle.

A missing reference is a build failure. The catch branch does not log a warning; it pushes an error and fails the build. A silently 404ing webp is exactly the class of bug that reaches production, because nobody opens the network tab looking for the image that didn't load.

The first run removed 300+ files and dropped the release to a size we could keep shipping. It also produced a list of every orphan, which is a much better code review artifact than "I deleted some stuff."

Trap 1: dynamic paths are invisible to a text scanner

The scanner's whole premise is that paths appear as literal text. Ours didn't, in one place.

The product page has a thumbnail strip where each 76px tile should load a small image, not the full-size one. The original code built the path at runtime:

const thumb = src.replace('/gallery/', '/gallery/thumb/').replace('.webp', '.jpg');

That is correct at runtime and completely invisible to matchAll. The scanner sees no assets/factory/XB2/gallery/thumb/01.jpg anywhere, deletes every thumb file, and the strip starts requesting 404s. The page still renders. The build still passes. You only find out from a console full of errors, or from a customer.

The fix is to make the paths literal. The build step now generates a map as plain strings:

// generated, do not hand-edit
const GALLERY_STRIP_THUMBS = {
  "assets/factory/DF1/gallery/01.webp": "assets/factory/DF1/gallery/thumb/01.jpg",
  // ...one line per tile
};

and the runtime does a lookup with a fallback, so a missing entry degrades to the full image instead of a broken tile:

const thumbOf = (src) => GALLERY_STRIP_THUMBS[src] || GALLERY_STRIP_THUMBS_ALT[src] || src;

The general rule I took away: any asset path you construct at runtime is an asset the packager cannot see. Either resolve it through a generated literal manifest, or accept that your deploy step will delete it at some point. There is no third option, because "remember to add it to the exclusion list" is not a mechanism.

I also added a second guard, a stale-reference check: every key in the manifest must exist on disk, every value must be a real file, and the build fails otherwise. That catches the other direction — a manifest that grows out of sync after a directory gets regenerated.

Trap 2: the srcset that saved zero bytes

With the file count under control, I went after bytes. The gallery page was shipping 876 KB of images on a mid-range Android at DPR 3. The cards are 260 CSS px wide on mobile, so I generated a 720px variant and added it to the srcset:

<img srcset="assets/featured/champagne-weave/thumb.webp 560w,
             assets/featured/champagne-weave/campaign-720.webp 720w,
             assets/featured/champagne-weave/campaign.webp 1100w"
     sizes="(max-width:760px) 260px, 545px">

Saved bytes: zero. The page still pulled the 1100w file on mobile. Here's why.

A card is 260 CSS px. At DPR 3 that is 780 device pixels. The candidates are 560w, 720w, 1100w. 720 is not enough for 780, so the browser correctly picks 1100. I had added a variant that was strictly worse than an existing one: bigger than 560, still too small.

The rule is a single line of arithmetic, and it is not optional:

needed_px = css_px * devicePixelRatio

For the hero image at 337 CSS px, DPR 3 needs 1,011 — so a 720w candidate is dead weight there too, and the browser jumps to 1400w. For the card at 260 CSS px you need 780, so the useful rungs are ~560 (DPR 2) and ~800 (DPR 3).

Once I sized candidates against css_px × DPR instead of picking round numbers, the gallery went from 876 KB to 507 KB (−42%) on mobile, with the LCP image itself dropping from 283 KB to 176 KB. Same layout, same markup, no change to how it looks. The only difference is that every candidate became reachable by some real device.

Two things get confused here, so to be explicit: sizes describes the layout width, and the browser multiplies it by DPR internally. If your sizes lies — says 545px when the container is actually 337 — every downstream decision inherits that lie, because the chosen candidate is computed from it.

The product page had the same disease with worse symptoms: eight product photo sets at 377–1159 KB each. They are now 196–356 KB (−86% on the worst one), and the 76px thumbnail grid finally loads thumbnail-sized files.

Trap 3: layout shift is a packaging problem too

The same release process exposed a third issue that I don't think is separate from the other two.

The customizer page had a CLS of 0.80 on desktop. The cause was mundane: a grid of cut panels that started empty in HTML and got appended to by JavaScript, one panel at a time. The container grew by 376px after first paint and pushed everything below it down.

The fix was not a CSS trick, it was ordering: move the grid into a section that already exists in the static markup, at the end of its column, so growth happens below the fold instead of above it. Desktop CLS went 0.80 → 0.016, and at 390px wide it is now 0.

One caution if you go measuring this: CLS is flaky in ways that will make you chase ghosts. The same page, same URL, four consecutive runs gave me 0 / 0.1311 / 0 / 0 — with a warm cache, the JS wins the race against first paint and there is nothing to shift. A single run is not a measurement. And measure production, not localhost: identical code gave 0.0017 locally and 0.0342 on the CDN, because locally the first paint is the final state and online it isn't.

The checklist

If you ship a static site with a lot of images, these are the four rules I now apply before every deploy:

Count files, not just bytes. We fail the build over 1,000. A file budget is as real as a byte budget, and it is the one that stops the deploy outright.
Derive the release from references, and fail on missing ones. Deleting unreferenced assets is safe; deleting assets whose references you couldn't parse is how you ship 404s.
No runtime-constructed paths. Generate a literal manifest, or the packager will eventually eat your files.
Size every srcset candidate against css_px × DPR. Otherwise you are shipping variants no device can ever select.

None of this is clever. It is just the difference between a build that tells you when it is wrong and one that quietly ships.

We are at 991 files with 9 to spare, which means the next thing I build has to justify its files before it justifies its features. If you want to see what all this packaging is protecting, the thing itself is at bukefootwear.com — upload a drawing and watch it land on a shoe.

44 seconds to render a shoe: six fixes, and the biggest one was a single toDataURL call

Bo Qian — Sat, 24 Oct 2026 13:39:29 +0000

I build a customizer for printed sneakers. You upload an artwork, it gets split across the leather panels of a shoe, and you see the result on the actual shoe before buying. The geometry is the interesting part — that's the first post and the second.

This post is about the other half: it worked, and it was unusably slow. Cold load, first preview: 44 seconds.

Here is what actually fixed it — including one "optimization" I had to revert, and a measuring mistake that sent me chasing a bug that didn't exist.

The pipeline, briefly

For each of 5 shoe angles, the browser:

downloads a 1800×1800 factory photo of the shoe from that angle,
downloads one alpha mask per panel for that angle (29 of them on one model),
for each panel, inverse-bilinear-maps every masked pixel back into the uploaded artwork, samples it, and multiplies.

Rendering was already fast in isolation: ~77 ms of pure computation per angle after I dropped the resolution of the inverse-mapping pass. So 44 seconds was never arithmetic. It was the browser waiting, and then the browser doing work I never asked for.

Fix 1: the angle strip was decoding 16 MB of images nobody could see

Each angle thumbnail is displayed at 41 × 43 px. The code that produced it looked like this:

img.src = viewCanvas.toDataURL('image/png');  // viewCanvas is 1800 × 1800

A 1800² PNG of a shoe photo is about 5.6 MB as base64. Five angles: 16 MB of data URLs, each one an <img> the layout had already reserved 41 px for. The browser dutifully decoded all of them at full resolution, on the main thread.

This is the trap with toDataURL: it looks like "export a small preview". It doesn't know what small means. It exports at canvas resolution, and the cost lands later, at decode time, where it isn't attributed to any of your code.

Replacing it with a 256 px JPEG on a white background:

function thumbUrl(srcCanvas, side = 256) {
  const s = Math.min(side / srcCanvas.width, side / srcCanvas.height, 1);
  const c = makeCanvas(Math.round(srcCanvas.width * s), Math.round(srcCanvas.height * s));
  const g = c.getContext('2d');
  g.fillStyle = '#fff';           // JPEG has no alpha; flatten first or edges go grey
  g.fillRect(0, 0, c.width, c.height);
  g.drawImage(srcCanvas, 0, 0, c.width, c.height);
  return c.toDataURL('image/jpeg', 0.86);
}

5.6 MB → 15 KB per angle. The white fill matters: JPEG has no alpha channel, and a transparent-to-JPEG round trip gives you a grey halo exactly where the shoe silhouette meets the background.

Fix 2: the source images were PNG

Same photos, no alpha needed, 1800 px long edge: 51.4 MB → 3.0 MB as WebP, visually indistinguishable at q84. The old PNGs stayed on disk but nothing referenced them anymore, so the deploy step dropped them.

One detail: I convert with a white background rather than keeping transparency, because the print pipeline multiplies the artwork against the shoe photo. Semi-transparent edges multiply against black and the shoe comes out dirty grey.

Fix 3: stop downloading base images you can't draw on

Not every angle has a usable mesh. The sixth gallery image is usually a 4000² whole-shoe shot for reference — 5 MB on one model — that the renderer can't map panels onto at all. It was being downloaded every time and then skipped.

const hasMesh = i => !!(meshViews[i] && meshViews[i].parts && meshViews[i].parts.length);

Two lines of guard. On one model it removed a 5 MB download from the critical path.

Fix 4: 29 masks awaited one after another

The render loop did this, inside a for:

const mask = await reconLoad(part.mask);   // 29 iterations

Each iteration waited for a full round trip. 29 masks × latency is where tens of seconds go, with the CPU idle the whole time. The fix is not clever — kick them all off when you enter the branch, and let the render loop hit an already-resolved promise:

// reconLoad caches by src and returns a promise, so a second call is free
[...new Set(wantedViews.flatMap(v => (v.parts || []).map(x => x.mask)))]
  .forEach(m => { reconLoad(m).catch(() => null); });

On the same session, request span for that batch went from 612 ms to 0.1 ms — proof it was real concurrency, not just faster.

Fix 5: yielding between angles

Five angles rendered back-to-back in one task held the main thread for 525 ms straight. Nobody can scroll during that. One line between iterations:

views.push(await renderPartWarpView(bases[i], source, mesh));
await new Promise(r => setTimeout(r, 0));   // let the frame paint

Longest task: 525 ms → 181 ms. Total wall time barely moved; interactivity changed completely.

Fix 6: draw one angle, then the rest

Originally: download all 5 base images and all masks, render all 5, then show anything. So the user stared at nothing until the last angle finished — 44 s on a cold cache.

Split into two passes:

updateReconstruction(version, true)      // current angle only
  .then(() => updateReconstruction(version, false));  // fill in the rest

The first pass touches one base image. The second pass reuses the same reconLoad promise cache, so nothing downloads twice.

One trap here: the empty-canvas early return in pass one means .then() still fires. Without a second guard, pass two immediately starts pulling the full 9.6 MB batch on first paint — exactly the thing the early return was supposed to prevent.

if (!state.layers.length) return;

The optimization that made it worse

Encouraged by fix 4, I tried prefetching everything — all masks for all angles — in parallel on first paint.

All angles went from 13 s to 21 s. The full prefetch competed with the first-pass downloads for the same bandwidth, and pushed several requests past the load timeout, which then triggered my retry path and made the queue longer.

Reverting it was the right call, and the general lesson is worth stating plainly: parallelism helps latency-bound work and hurts bandwidth-bound work. Masks are 41 KB each — latency bound, so parallel wins 9 s. Base images are 10.9 MB total — bandwidth bound, so parallel just reorders the same wait. Those two bottlenecks need different fixes and I had been treating "slow" as one problem.

Where it landed

	Before	After
First preview, cold	44 s	2.2–2.9 s
All angles done	—	3.6–6.5 s
Longest main-thread task	525 ms	181 ms
First-screen image bytes	9,797 KB	337 KB
Whole page transferred	9,853 KB	583 KB

Measured across six models, each in a fresh browser. Not a lab number: that's the production build on the CDN.

The measuring mistake worth repeating

At one point my DevTools Protocol calls started timing out while inspecting the renderer, and I concluded the renderer was broken on one model. It wasn't. I had 16 MB of data URLs decoding on the main thread; Runtime.evaluate simply couldn't get a slot. A timing-out inspector is not evidence that the page is dead — it's evidence the main thread is busy. Read the DOM with one long wait and a single call instead of polling.

Part 2: after speed comes layout shift

With rendering fast, a second problem surfaced — one that is the same bug in three costumes.

CLS on the designer page was 0.80. Google's "poor" threshold starts at 0.25, so this was off the chart. The cause in every case: a container whose height is decided by content injected after first paint.

Element	What it did	Fix
Step indicator	built by JS and `prepend`ed	write the skeleton in HTML, JS only fills it
Toolbar	34 px → 101 px when two buttons and a language selector were appended	same: static markup, JS binds handlers to existing nodes
Panel grid	0 → 376 px, pushing everything below it	move the growing block to the end of the column, so growth pushes nothing
Scroll gutter	content overflowed, scrollbar appeared, inner width −16 px	`scrollbar-gutter: stable`

0.80 → 0.038, and after the scrollbar fix on narrower viewports, 0.0164 on desktop and 0 at 390 px.

Two things I got wrong on the way:

A CLS of 0 measured once is not a fix. The product page returned 0 / 0.1311 / 0 / 0 across four consecutive runs of the same URL. Warm cache meant the JS won the race to first paint and nothing moved. The layout shift only appears when the network is slow enough — which is exactly the condition real visitors are in, and exactly the condition your warm cache test doesn't reproduce.

Local and production differ by an order of magnitude. The same viewport measured 0.0017 locally and 0.0342 in production. Locally the first paint is already the final state; in production it isn't. Any CLS number from file:// or localhost is a lower bound you can't ship on.

What I'd tell someone starting this

toDataURL is a serialization, not a thumbnail. If the display size is 41 px, hand it 256 px on purpose.
Attribute bytes before you attribute CPU. I spent a day reading flame charts for a problem that was 9.8 MB of images.
Separate latency-bound from bandwidth-bound before parallelizing.
Yield every few hundred milliseconds. Total time unchanged, perceived responsiveness transformed.
Anything appended after first paint has a layout cost. If the container's height depends on it, either reserve the height or move it to the end of the flow.

The customizer is live at bukefootwear.com/designer if you want to watch it render, and the measurement that started all of this — all 66 panels, sampled and scaled — is written up at bukefootwear.com/guides/panel-magnification-measured. The panel-by-panel viewer is at bukefootwear.com/panel-preview.

I measured how much 66 shoe panels magnify one upload - and the number changed our file requirements

Bo Qian — Thu, 22 Oct 2026 14:45:21 +0000

People send us a 1200px PNG, it looks crisp in the browser preview, and then the printed shoe comes back with a slightly soft edge on one panel. Not all panels. One.

That asymmetry is the interesting part. A sneaker upper is cut into flat panels — 2 on our slipper, 4 on the blade pattern, 10 on the everyday sneaker, 14 and 18 on the two low-tops. 66 panels across 8 styles. Each panel takes a different region of the uploaded artwork, so each panel magnifies that upload by a different factor.

If you assume "the image is big enough", you are assuming it for the panel you happened to look at.

So I stopped guessing and measured all 66.

The geometry that makes the numbers different

Each panel in our data file is four numbers plus a mask:

{
  id: 4,
  mask: "assets/panel-masks/DF2/piece-04-mask.png",
  w: 702, h: 752,                                  // production resolution
  sb: { x: 197.83, y: 573.11, w: 146.7, h: 216.91 }, // region of the artwork it samples
  mirror: false
}

w/h is how many pixels the printer wants for that panel. sb is the rectangle the panel reads from the user's artwork, expressed in canvas units (the canvas for that style — 611×800 for the low-top, for example).

The pipeline is: scale the artwork to cover the canvas, then for each panel crop sb, stretch it to w × h, and mask it to the panel outline. Which means:

magnification = w / sb.w

For that DF2 panel, 702 / 146.7 = 4.79. That single panel needs roughly five times the pixel density of the artwork compared to a panel that happens to sample a wide region.

The distribution across 66 panels

I computed w / sb.w for every panel (65 valid entries; one panel in XB2 has a dirty sb of 1e22 and is skipped in the tool):

statistic	magnification
min	2.40×
median	2.91×
max	4.79× (DF2 panel 4: 146.7×216.91 → 702×752)

Nothing under 2.4×. So "the artwork is roughly panel-sized" is never true — every single panel is upscaling by at least 2.4×, and the worst one by almost 5×.

That number alone doesn't tell you what to ask users for, because magnification is relative to canvas units. Inverting it does: for a given upload width, how many panels can be rendered at 1:1 or better?

// required artwork width for a 1:1 render, per panel
// the binding axis is the larger of the two ratios, not just the width
const scale = Math.max(panel.w / panel.sb.w, panel.h / panel.sb.h);
const need  = model.w * scale;

That Math.max is not cosmetic. A tall narrow panel — a heel strip, an eyestay — can be comfortably satisfied on the horizontal axis and still be short of pixels vertically, so measuring only panel.w / panel.sb.w overstates coverage at small upload sizes. With both axes in play, across all 65 panels:

upload width (px)	panels rendered at 1:1
1400	25%
1600	29%
1800	54%
2000	78%
2400	98%
3000	100%

Median requirement: 1673px. 90th percentile: 2267px. Worst case: 2916px (KJ1BM, panel 6).

What we changed because of this

Before: "upload a high resolution image, at least 1000px".

After: short side ≥ 2000px, and we tell people 2400px if they want every panel sharp.

2000px is the point where four out of five panels render at native resolution and the remaining ones are upscaled by 1.45× at most — which survives printing because output is leather at ~300 DPI equivalent, not a 4K display. 3000px is where the requirement stops growing; above that you are paying upload time for nothing.

Two things I did not do:

I did not raise it to 3000px. The last 2% of panels cost every user a slower upload and a bigger file, for a difference nobody can see on a curved panel under stitching. 2000px is the practical knee.
I did not silently upscale in the pipeline. A blurry 900px image that we quietly resample to 2900px looks worse than an honest soft render, because interpolation adds ringing around edges before the print does its own.

The two silent failures that cost more than resolution

Resolution problems are visible. These are not.

1. Aspect ratio drift. The artwork is stretched to cover the canvas. If the uploaded image's aspect ratio differs from the canvas by 3%, nobody notices on screen — but the distortion is applied before the panel crop, so all 66 panels inherit it, and the seam between two adjacent panels stops lining up. Hard requirement: artwork ≥ canvas and the same aspect ratio, otherwise the pipeline stretches it and does not complain.

2. Multiplying by a dead alpha channel. This one is specific to canvas: if a mask PNG's visible content lives in RGB with alpha = 0 (which is what a designer's visual mockup export looks like), drawImage composites with premultiplied alpha and the RGB is multiplied by zero. You get a fully transparent draw. No exception, no console warning — the panel just renders empty. We hit it on 7 of 8 styles and now rebuild masks offline rather than trusting exports.

Both of these are "check your inputs" problems that no amount of extra resolution fixes.

A tool so users can check before ordering

Measurement is only useful if it reaches the person choosing the file. So the same geometry now runs client-side as a panel preview: upload an image, see the crop for every panel, in the browser, nothing uploaded to a server.

That is also how I found the dirty 1e22 sample box — a preview that draws 65 of 66 panels correctly is a better test suite than any assertion I would have written.

The takeaway

"High resolution" is not a spec. Every multi-panel print has a distribution of magnifications, and the useful question is not "is the image big enough" but "for which panel is it not".

If you are building anything that maps one image onto many physical pieces — shoes, garments, packaging, tile — spend an afternoon computing outputPixels / sampledRegion for every piece. In our case it turned a hand-wavy guideline into a number (2000px) that a support person can state and a user can check.

The full per-style table and the method behind it is published here: how much a shoe panel enlarges your artwork. The geometry write-up, including the four pipeline bugs that failed silently, is mapping one image across 66 shoe panels. And the panel-by-panel preview tool is at bukefootwear.com/panel-preview if you want to see the crops for our 8 styles.

One image, 66 shoe panels: the geometry (and four silent bugs) behind a canvas cutting pipeline

Bo Qian — Thu, 22 Oct 2026 14:06:07 +0000

I make custom printed sneakers. People upload a picture, we print it onto the leather panels of a shoe, and somewhere between those two steps the picture stops being a picture and becomes a set of manufacturing instructions.

That middle step is a browser-side canvas pipeline, and it is the least glamorous and most bug-prone code I have written. This post is about the geometry it has to solve and the four bugs that took me longest to find — all of which failed silently, which is the worst kind.

The problem in one sentence

A sneaker upper is not one surface. It is a set of flat panels cut from a hide, printed, then sewn together — 2 panels on our slipper, 4 on the blade pattern, 10 on the everyday sneaker, 14 and 18 on the two low-tops. Sixty-six panels across eight styles.

So "print this image on a shoe" decomposes into: for each panel, take a rectangular region of the user's artwork, scale it to that panel's production resolution, mask it to the panel's actual outline, and flip it if the pattern piece is mirrored.

The data model

Every panel is four numbers and two files:

{
  id: 1,
  sampleBox: { x: 112.24, y: 29.89, w: 440.06, h: 455.83 }, // where to read from the artwork canvas
  width: 1342, height: 1106,   // production raster for this panel
  mask: 'piece-01-mask.png',   // the panel outline, as an alpha mask
  mirrored: false
}

The artwork itself sits on a logical canvas — 611 × 800 for the low-top, roughly 3:4. Coordinates in sampleBox are in that space, so the same layout can be reprinted at any physical scale without touching the data.

The cutting step is then genuinely short:

const cut = new OffscreenCanvas(p.width, p.height);
const ctx = cut.getContext('2d');
if (p.mirrored) { ctx.translate(p.width, 0); ctx.scale(-1, 1); }
ctx.drawImage(artwork, sb.x * s, sb.y * s, sb.w * s, sb.h * s, 0, 0, p.width, p.height);
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.globalCompositeOperation = 'destination-in';
ctx.drawImage(mask, 0, 0);

Eight lines. It took a week to make those eight lines trust each other.

Bug one: the masks looked like masks but were not

The panel outlines came from the pattern department as PNGs. Some of them were real alpha masks — opaque inside the panel, transparent outside. Others were exported from a design file: white shape, grey backdrop, red construction lines.

The second kind looks correct in any image viewer. It is not correct for canvas.

Canvas compositing is premultiplied. An RGBA pixel of (255, 255, 255, 0) is stored as (0, 0, 0, 0) — the colour is discarded the moment alpha hits zero. So a "white shape on transparent" export, where the white actually carries alpha = 0, arrives as pure transparent black. drawImage with destination-in then erases everything. No exception, no warning, just an empty canvas.

I tried to patch it at runtime: read the pixels, find the bright ones, rebuild alpha from luminance. It never worked, because by then the RGB values were already gone. The information was destroyed at export time, not at draw time.

The fix was to stop patching at runtime and rebuild the masks offline, once:

// per panel, decide which encoding it actually uses
const hasBlackCover = blackPixels / total > 0.01;  // a grey overlay layer, alpha ~153, luminance < 70
let on;
if (hasBlackCover) on = !isBlackCover(r, g, b, a);  // the cover marks what is *not* the panel
else               on = a > 120;                    // honest alpha mask

66 masks rebuilt as binary alpha, 658 KB total — smaller than the originals, and now unambiguous. The runtime code went from ~40 lines of guessing to a validity check.

Lesson: if a shape has to survive a compositing step, the shape has to be in alpha before it reaches the canvas. Luminance is not a mask.

Bug two: garbage coordinates fail silently

One panel's sampleBox came out of the geometry export as:

{ x: -2.18e+22, y: -2.64e+22, w: 4.81e+22 }

drawImage with those numbers throws nothing. It draws nothing. There is no error to catch, no onerror, no rejected promise — the panel just renders blank and you assume your mask is wrong.

I spent most of an afternoon on the mask before printing the source numbers.

The guard is now a magnitude check rather than a sign check, because negative coordinates are legitimate — a panel can sample from outside the artwork canvas and let canvas clamp it:

const sane = (sb, mw, mh) =>
  Math.abs(sb.x) <= mw * 4 && Math.abs(sb.y) <= mh * 4 &&
  sb.w > 0 && sb.h > 0 && sb.w <= mw * 4 && sb.h <= mh * 4;

Lesson: validate geometry against the canvas bounds it is supposed to live in, not against "looks reasonable".

Bug three: `revokeObjectURL` kills the image you are still drawing

The first version loaded uploads the obvious way:

const url = URL.createObjectURL(file);
const img = new Image();
img.src = url;
URL.revokeObjectURL(url);   // "free the memory"

This works exactly once. Redraw the panel grid — switch style, change the layout — and every drawImage silently produces an empty canvas, because the blob URL backing the image is gone. The <img> element still reports naturalWidth > 0, which is what made it confusing.

createImageBitmap is the right tool here: it decodes once into an immutable bitmap that stays valid until you close it, and it is also faster to draw repeatedly.

const bmp = await createImageBitmap(file);
userImage?.close?.();
userImage = bmp;

Lesson: if a decoded image is going to be drawn more than once, own the bitmap, not a URL that points at it.

Bug four: fast clicks race the render loop

Switching styles fires an async render. Switch twice quickly and the first render's results land after the second one's, painting the old style's panels into the new style's grid.

The fix is a monotonic token checked at every await point:

let renderSeq = 0;
async function render() {
  const mySeq = ++renderSeq;
  for (const cell of cells) {
    const mask = await getMask(cell.panel.mask);
    if (mySeq !== renderSeq) return;   // a newer render owns the canvas now
    // ...
  }
}

Unglamorous, and the only version that survives a user with a fast mouse.

What the numbers look like

The pipeline is not just slicing; it is upscaling, and that decides whether a user's file is good enough.

To fill a 1342-pixel panel from a 440-unit window on a 611-unit canvas, the artwork needs to be about 1,860 px wide to arrive at full resolution with no interpolation. Across the library, the median enlargement is 2.9× and the worst case is 4.8× (the 360 × 566 window feeding a 1598 × 1958 panel).

That is a real product constraint disguised as a geometry detail. Telling someone "your image needs to be 2,000 px on the short edge" is only credible if you can derive it from your own pipeline — which is exactly what the sampling windows give you.

Why I shipped the tool instead of a diagram

The pipeline runs entirely in the browser, so I exposed it: upload an image, pick a style, and see every panel of that style cut from your artwork at production size. No upload, no account, no server round trip — the same destination-in compositing you just read about.

It turned out to be a better explanation than any diagram I could draw, and it cost nothing extra to run: bukefootwear.com/panel-preview.

The written version, with all 66 panels and the per-style numbers, is at bukefootwear.com/guides/artwork-across-shoe-panels.

If you are doing anything with panel-based printing, garment mapping or texture atlases, I would like to hear how you handle seam continuity — that is the part I still consider an open problem rather than a solved one.