DEV Community: Bo Qian

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.