DEV Community: yu chen

One Variant, One Image: Why Shopify's Image Table Binds Exactly One Photo per Variant

yu chen — Mon, 09 Nov 2026 02:07:35 +0000

By EasyCatch Growth Desk — weekly technical deep-dive for the Shopify community. Written 2026-11-09.

TL;DR

A merchant on the Tinker theme posted last week that his garments carry two or more photos per variant, yet the gallery keeps downloading 20+ images from variants the shopper never selected — "it's killing my performance." The first reply from Mustafa_Ali is the sentence this whole article unpacks: "Shopify only ties one featured image to each variant, so the 'hide other variants' media' toggle hides down to that one image and leaves the rest of the gallery alone. Showing a full set of images per variant isn't in the data model, so it comes down to the theme." A second, much busier thread — how long processing new product photos actually takes you, where an apparel merchant puts a 30-SKU drop at four to five hours and names the bottleneck precisely: "renaming 90 files by SKU, then uploading each one to the right variant … that part alone takes 2 hours per drop."

Both threads describe the same constraint from opposite ends. The images table is not a photo album bolted onto a product; it is a join table whose binding column holds exactly one value per variant row. That cardinality is the reason the toggle cannot do what merchants expect, the reason alt-text matching became a cottage industry, and the reason a "successful" import can still ship the wrong photograph. This is a schema fact, not a theme bug and not an operator error. Our earlier piece on collapsed option slots covered what happens when attributes outnumber the three option columns; this one starts one step later, at the moment a converted file has to become a specific variant's image.

1. The images table is a join table with a single slot

A Shopify product CSV looks like one flat file. It is three tables interleaved, and each one answers a different question:

products — one row per product, keyed by Handle. Carries Title, Body (HTML), Tags, and the option declarations (Option1 Name, Option2 Name, Option3 Name).
variants — one row per purchasable unit, repeating the same Handle, supplying Option1 Value … Option3 Value, Variant SKU, Variant Price, Variant Grams.
images — separate rows carrying Image Src, Image Position, Alt Text, and one binding column: Variant Image.

The cardinality is asymmetric on purpose. A product can own an unlimited number of image rows. A variant row, however, exposes exactly one Variant Image field — and that field does not take a list, a comma-separated string, or an index into a gallery. It takes a URL string that must match an Image Src value elsewhere in the same file. When it matches, that media item becomes the variant's featured image: the one the product page swaps to when a shopper picks the colour.

Do the arithmetic on the merchant's catalogue. Six colours, five sizes, three photos per colour: 30 variant rows, 18 image rows, and 30 bindings — of which each variant can point at only one of its colour's three photos. The other 12 photos are product-level media with no variant anchor, so they are eligible to appear in the gallery for every selection. Shopify's "hide other variants' media" setting hides precisely the images bound to other variants; the unbound majority stays visible, and the browser downloads it. That is the thread's complaint in mechanical form, and it is also why the answer was "this comes down to the theme."

2. What the browser actually does to a WebP file

Supplier catalogues from domestic wholesale marketplaces hand you WebP far more often than JPEG. The standard route is a canvas transcode inside the browser: draw the decoded image onto a canvas, then canvas.toDataURL('image/jpeg', quality) and upload the resulting bytes. It works, and it is lossy in four ways that matter for apparel:

Alpha is not representable. JPEG has no alpha channel. If the canvas is transparent when you draw a cut-out garment, the transparent pixels composite against black by default, and you get a garment with a charcoal halo. Filling the canvas with white (fillStyle = '#fff', fillRect over the full area) before drawImage is not cosmetic — it is the difference between a usable product photo and a rejected one.
Chroma subsampling and 8-bit rounding. JPEG encoders typically subsample chroma at 4:2:0, which is invisible on fabric but very visible on thin print detail and on saturated reds and blues, where the hue shifts by a few degrees. At quality = 0.92 this is acceptable; at 0.7 a printed pattern dissolves into mush.
Colour space is assumed, not measured. Canvas composites in sRGB. A supplier file tagged Display P3 or Adobe RGB gets reinterpreted without conversion, and saturated colours come out flatter than the original. For solid colours this is tolerable; for brand-accurate textiles it is not.
Metadata is dropped, including orientation. EXIF disappears in the transcode. A WebP that relied on an orientation flag becomes a sideways JPEG — and it will look sideways on the product page because there is no longer a tag telling the browser to rotate it.

There is a fifth trap that is not about pixels at all. Wholesale CDNs frequently serve WebP behind a URL that ends in .jpg, rewritten by a query string such as ?imageMogr2/format/webp or ?x-oss-process=image/format,webp. Any pipeline that routes on the file extension — "it ends in .jpg, skip conversion" — will upload WebP bytes under a JPEG name. Shopify's media pipeline sniffs the actual content, and when the sniffed type does not match what its media processor accepts, the row imports cleanly and the media slot stays empty. No error, no warning, upload success. This is the same silent-drop class that made a name for itself in our CDN image guide, and it is why a Local Canvas Transpiler that decodes and re-encodes locally, rather than trusting the extension, produces a materially different failure rate. The first bytes of a real JPEG are FF D8 FF; if your "JPEG" does not start there, it is not one.

3. Cartesian expansion and the per-row repetition rule

Colour times size is where the images table stops being abstract. Six colours and five sizes expand to 30 variant rows, each representing one purchasable unit, each repeating Handle and the identical Option1 Name / Option2 Name declarations from the product row. Two rules govern the image columns during that expansion, and both are easy to get subtly wrong:

Rule one: repeat the binding, not the URL. If each colour has its own photo, the Image Src URL for that colour appears on one image row, and the same URL string appears as Variant Image on each of the five variant rows for that colour. One media item, five bindings. The common mistake is the reverse: copying the image row five times, once per size. That creates five duplicate media items of the same photograph, which bloats the gallery to 30 items, gives the theme five candidates for "featured", and makes position ordering meaningless.

Rule two: set the binding on every row, not on the first row of the group. If you write Variant Image only on the first variant row of each colour block, the remaining 24 rows in a 30-variant product carry an empty binding. The storefront does not error — it falls back to the product's primary image for those variants, so a shopper selecting "Navy, XL" sees the white version. This is the mechanism behind most "wrong colour shipped" complaints, and it survives every re-import, because the emptiness is preserved in the file.

Image Position is the third piece. It defines gallery order, and the lowest position of a product's images is what shoppers and themes treat as the primary. Positions must be unique within a product; duplicate or missing positions leave ordering to the importer's discretion, so the same file can produce a different gallery on two stores. And note the interaction with rule one: one bound image per variant plus a deterministic position order is the only combination that yields a gallery a theme can filter reliably — which is exactly the workaround the Tinker thread ended up recommending, via alt text, because the data model cannot express "three photos belong to the Navy variant."

A Matrixify-compliant ZIP produced by an expansion engine solves this by construction rather than by discipline: the variant rows are generated from the colour-by-size matrix, every generated row inherits the colour's Image Src as its Variant Image, and positions are assigned sequentially per product, so the binding count equals the variant count by definition. That is checkable after the fact, which matters more than elegance.

4. Why alt-text matching is a workaround, not a fix

The Tinker thread converged on tagging each image's alt text with the colour name, then filtering the gallery in Liquid. It works, and it is the cheapest path when a merchant has two hundred products live and no appetite for a re-import. Its costs are worth stating plainly:

Alt Text lives on the image row, so it is shared by every variant bound to that image. You cannot store three alt texts for one photo. If one photo serves two variants, the tagging scheme has to assume one photo belongs to one variant only — which is often false.
Alt text is free-form. Any later re-import that carries an empty Alt Text column overwrites the tags, and the gallery silently reverts to showing everything.
Filename and slug matching break when a handle changes; handles change when a title is edited, and nothing warns you.
CSS hiding does not stop downloads. The merchant's performance complaint is specifically about bytes over the wire, which is why the thread kept coming back to "the browser could still download them."

The durable fix is upstream: give each variant its own file per view, encode the view in the filename and the position, and let the theme map deterministically instead of guessing. That is a file-naming and CSV-generation problem, which is the layer a 100% Local-First exporter controls — not a Liquid problem.

5. A pre-flight you can count, not eyeball

Before any import, these four counts answer whether the file is structurally sound. They are cheap, deterministic, and they catch every failure mode above:

Variant rows should equal colours multiplied by sizes (plus any legitimate one-off rows). If the count is lower, part of the matrix collapsed during generation.
Distinct Image Src values should equal the number of gallery photos you intend, not the number of times a URL is mentioned. Duplicates inflate the gallery.
Non-empty Variant Image rows should equal variant rows that have their own photo. Anything less means those variants will fall back to the product's primary image.
Transcode sanity: output bytes at least 60 percent of the source, pixel dimensions identical to the source, alpha flattened against white, and the first three bytes equal to FF D8 FF.

Run those four and the "import succeeded but the photo is wrong" class disappears. Skip them and the storefront becomes the test harness — with customers as the assertion library.

Conclusion

The Tinker merchant was not fighting a theme setting. He was fighting a join table that holds one binding per variant, and the "hide other variants' media" toggle simply cannot express what he wanted. The same asymmetry explains the four-hour photo drop: the renaming and matching loop exists because humans are manually creating the one-to-one binding that the schema requires.

Five things to check, in order:

Count variant rows against the colour-by-size matrix before importing.
Count distinct Image Src values against the photos you actually want in the gallery.
Ensure every variant row that has its own photo carries a non-empty Variant Image.
Give every image a unique Image Position so the primary is deterministic.
Verify each converted file is genuinely JPEG (FF D8 FF), full-size, alpha-flattened, and white-matted.

Do those five and the gallery stops being a lottery — on Tinker, on Dawn, and on whatever theme you migrate to next.

About EasyCatch

EasyCatch is a 100% Local-First copilot for 1688-to-Shopify sourcing. Its Local Canvas Transpiler converts supplier WebP images to JPEG entirely inside your browser — decoding first, re-encoding second, so a mislabeled CDN URL cannot slip a WebP past the import — and its CSV engine expands colour-by-size variants into Matrixify-compliant ZIPs with the per-row Variant Image binding already repeated on every generated row. No supplier link, cost price, or SKU structure ever leaves your machine. Zero-Server Privacy by design.

An @e1 Is a Handle, Not a Position: How Operun's Snapshot Keeps a Ref Meaning the Same Thing

yu chen — Mon, 02 Nov 2026 02:02:47 +0000

By Chen Yu — building Operun, a local-first browser kernel. Written 2026-11-02.

TL;DR

The previous guides in this series were about what a snapshot reads: the three walls that hid
text from an a11y snapshot, the 40,000-token budget, and the size of a captured HAR body. This one
is about the other half of the contract — the @eN handle itself.

A snapshot line like @e7: [button 'Pay now'] is a promise: act on @e7 and you touch that button,
not "the seventh thing on the page". That promise is only credible if three things hold. The number
must be an identity rather than a position, so a cookie banner appearing above it does not renumber
the page under a workflow's feet. The handle must be able to fail honestly, so a stale ref returns
nothing instead of a detached node that reports SUCCESS for an event no page ever saw. And the handle
must know where it stops, because a ref names a node inside one frame and carries no frame identity
of its own.

None of that is free. It costs two maps, one pruning pass per snapshot, a structural type check
across realms, an exclusion list of things the kernel cannot actually click, and a refusal to accept
@e1 >>> #inner at all.

The failure a position would cause

Number the controls by their order in the walk and everything works until the page changes. Then it
does not merely get slower — it gets quietly wrong. A consent banner mounts above the form, one
table row is inserted, a "you have unsaved changes" toast pushes the layout down by forty pixels, and
every ref the agent is still holding now names a different control. Nothing throws. The next click
lands on the wrong button and the trace looks like the agent made a bad decision, when in fact the
address book was rewritten.

So the scanner assigns numbers by node identity, not by index. The in-page function keeps a
WeakMap<Element, string> called byNode — "which ref is this node" — and a Map<string, Element>
called byRef — "which node is @e1". When a control is handed a ref the code asks byNode first:

function refFor(node: Element, cache: Slot): string {
  const known = cache.byNode.get(node)
  if (known !== undefined) {
    // Re-register: the index may have pruned this node while it was detached,
    // and `byNode` is the authority on which ref the node owns.
    cache.byRef.set(known, node)
    return known
  }
  const ref = '@e' + cache.next
  cache.next += 1
  cache.byNode.set(node, ref)
  cache.byRef.set(ref, node)
  return ref
}

Two details in those ten lines matter more than the rest of the file. First, a node that already has a
number keeps it forever — across re-renders, across being pulled out of the DOM and put back. Second,
next only ever increases and is never reused. A number that has been spent cannot come back as a
different control later, which is what makes "a stale ref never resolves" a property rather than a
hope.

Two maps, because there are two questions

byRef and byNode look redundant until you ask what each one is for. byRef answers which node is
@e1 — that is what an action needs. byNode answers which ref is this node — that is what
stability needs, and it is a WeakMap on purpose: a node the page throws away stops being remembered
without anything having to sweep it.

byRef is the opposite: a plain Map holds its keys strongly and would pin every removed subtree
for the life of the document. On a dashboard that re-renders a table every few seconds, that is a
leak measured in megabytes per minute. So every snapshot starts with one pass:

cache.byRef.forEach((node, ref) => {
  if (!node.isConnected) cache.byRef.delete(ref)
})

Pruning costs nothing in correctness because a node that comes back — a reparented row, a virtualised
list item re-mounted — is re-registered from byNode on the next walk, getting its original number
back. The index is a cache of the truth; byNode is the truth.

Where the cache lives, and who may rewrite it

The cache cannot live in the kernel. In an MV3 world the kernel's home is a service worker that
shares no memory with any page and that Chrome is free to tear down between two steps of the same
task — state kept there would be lost exactly when it is needed.

The cache also cannot live in the page's own JavaScript. The primitives run in the extension's
isolated world, which page script cannot see or write to. That is not paranoia for its own sake: a
cache a page could edit is a cache a hostile page could repoint, and an @e1 that silently becomes a
different control is worse than a ref that fails.

So the cache is an object on the isolated world's globalThis, under __operunRefCache__, written by
the snapshot function and read by the primitives that act on a ref. That lifetime is exactly right: it
outlives a single injected call, because Chrome re-evaluates each function but not the world it runs
in, and it dies with the document — and a navigation is a different document, so refs from the
previous page do not survive into the next one.

Two consequences are worth spelling out. chrome.scripting.executeScript serialises a function with
toString() and re-evaluates the source in the frame, so an injected function cannot import the cache
module — the key and the lookup exist twice, once for kernel-side use and once as a literal inside the
function, pinned together by a unit test. And the "is this our cache" check is structural rather than
instanceof Map, because a Map constructed in another realm is a perfectly healthy Map that this
realm's instanceof would reject as foreign. A cross-realm identity check would have turned a working
cache into a mysterious "ref not found".

A ref that resolves to nothing beats a ref that lies

Resolution is one line of judgement: a node either isConnected or the ref resolves to null. The
comment in the source is blunt about why null is the only acceptable failure mode — a detached node
still has click() and dispatchEvent(), its events fire into nothing, and the step would report
SUCCESS for a page that never saw it. A workflow that fails loudly can be debugged. A workflow that
succeeds silently writes the wrong price into the wrong product.

null deliberately does not distinguish "this ref was never handed out" from "the node left the
document". Both mean the caller can do nothing different, so inventing two error codes would only give
the caller more ways to be wrong.

Handles the kernel cannot pull

A ref is a promise that something can be done with it, so the walk skips nodes where nothing can be
done:

<option> inside a native <select>. No primitive in the kernel can pick one by ref — the platform opens its own popup, which no synthetic click reaches. The parent <select> reports the currently chosen value instead. A custom listbox built from [role="option"] elements is reported, because a click does reach those.
input[type="hidden"]. Excluded by what it is, not by how it is styled. It usually computes to display: none and would fail the visibility test anyway, but a page is free to lay one out, and it would still not be a control.
Anything under [hidden], [aria-hidden="true"], or [inert] — a single closest() test. inert exists precisely to make a subtree unreachable; handing out a ref into it would be handing out a handle to a node the platform refuses to route events to.
Invisible elements, tested by walking ancestors for display: none, visibility: hidden or visibility: collapse. Same rule as the Tab order, so what the agent reads and what the keyboard can reach cannot disagree.
Empty prose blocks, in content mode only. <p></p> is scaffolding; an @eN naming it is a handle to nothing.

The prose path is worth a note because it is where role === null is handled rather than skipped.
A declared role that is not a control (role="heading", role="presentation") is a statement about
interaction, and content mode is not asking about interaction — so <h1 role="heading"> still gets
its text reported. That single branch is the difference between a content snapshot of a documentation
page and a content snapshot with a hole in it.

Where a ref stops: the frame boundary

Cross-origin iframes are the classic blind spot. A mailbox's login form lives in a frame the
same-origin policy keeps a top-level querySelector from entering, and no amount of >>> changes
that: the piercing chain is a CSS selector per frame walking inwards, and the browser still enforces
the origin boundary at every hop.

Operun's answer is not to pierce harder but to ask every frame at once.
executeScript with allFrames: true returns one result per frame, each carrying the frameId the
next step must name to act inside it, and those results are merged into one text:

=== Frame: 0 (Top: https://mail.example.com) ===
@e1: [button 'Compose']
=== Frame: 849201 (https://login.example.net/signin) ===
@e1: [textbox 'Email'] [frame_id=849201]
@e2: [textbox 'Password'] [frame_id=849201]

Note that frame 849201 has its own @e1. That is not a collision, because a ref's scope is the frame
its snapshot ran in — the top frame is the default context, so only a frame an action must name
carries the [frame_id=N] marker. This is also why @e1 >>> #inner is rejected at the payload
boundary rather than attempted: a reference already belongs to a frame and carries no frame identity of
its own, so the chain has no meaning that resolves to one element. Refusing it keeps the ref cache's
scope a single statable rule instead of one with a special case per position in the chain. Blank
segments like #frame >>> fail the same check — not a typo, an unanswerable question.

Two smaller decisions in the merge are the kind that only show up in production. A frame that answered
nothing — a blank ad iframe that navigated mid-injection, an origin the build is not granted — is
skipped rather than thrown, because one mute frame must not cost you the other eleven. And the frames
are sorted by id before merging, because executeScript promises no ordering and the same page must
read as the same text every time; an unstable snapshot is a cache-buster for every layer above it,
including the token budget, where each line is charged ceil(length / 3) against a 40,000-token
allowance and the trailer … N more elements omitted is the reader's only warning that what it holds
is not the whole page.

Conclusion

The interesting part of a browser kernel is not the click. It is everything that has to be true before
the click is allowed to happen: a number that means a node and not a slot, an index that can be pruned
without losing identity, a cache the page cannot rewrite, a failure mode that is a refusal instead of
a lie, an exclusion list that admits what the platform will not let you touch, and a frame boundary
that is respected rather than papered over.

Each of those is a small piece of code. Together they are the difference between a workflow you can
leave running and a workflow you have to watch.

About Operun

Operun is a local-first browser kernel: a Chrome extension plus a runner that
drives your own logged-in browser, with an a11y snapshot built for agents rather than for humans to
read. Snapshots, refs and selectors are resolved in the page and in the isolated world, which is why
the handle semantics above can be stated as rules instead of best-effort behaviour. The kernel keeps
your session, your cookies and your pages on your machine; the cloud, when you use one, routes steps
and never receives your page content by default. If you are building agents that touch real accounts,
start with the a11y snapshot and the token budget, then read the selector contract — the handles are
where reliability actually lives.

Four Supplier Attributes, Three Option Slots: How Collapsed Options Break Variant Images and Re-Imports

yu chen — Mon, 26 Oct 2026 02:13:08 +0000

By EasyCatch Growth Desk — weekly technical deep-dive for the Shopify community. Written 2026-10-26.

TL;DR

Supplier catalogs are not built around Shopify's option model. A clothing SKU on a domestic wholesale marketplace routinely carries four attributes — colour, size, fabric weight, and print — while a product CSV exposes exactly three option slots. Two threads on this forum keep circling the same gap: a clothing-store thread asking how merchants actually check supplier files before importing, where a responder zeroes in on the real pain ("especially when supplier files have a lot of variants … whether the comparison can also show exactly which row or field changed"), and a much older import failure reported as Option value provided for unknown options, where the accepted answer spells out that there are only "three option spaces: Option 1 Name/Value, Option 2 Name/Value, Option 3 Name/Value."

That second answer is the whole article in one sentence. When a supplier has more attributes than you have slots, you do not get an error — you get a decision. You collapse two attributes into a single option value ("Black / Heavyweight"), and from that moment the option value string becomes the identity of the variant. Everything downstream keys off that string: the per-row Variant Image binding, the swatch mapping, and every future re-import that tries to match existing rows. This is a data-model problem with a naming surface, not a technique problem — which is why the same store can import "successfully" for months and still ship the wrong photo to customers.

1. Three tables, one column that decides whether an image actually lands

A Shopify product import is not one table. It is three overlapping ones, serialised into a single flat file:

products — one row per product, keyed by Handle. This row carries the product-level fields: Title, Body (HTML), Tags, and — critically — the Option1 Name, Option2 Name, Option3 Name declarations.
variants — one row per purchasable SKU, repeating the same Handle and supplying the values (Option1 Value, Option2 Value, Option3 Value), plus Variant SKU, Variant Price, Variant Grams.
images — separate rows that carry Image Src and Image Position, usually with the variant-specific fields left empty, plus a per-variant binding column: Variant Image.

The binding rule is the part people get wrong, and it is unforgiving in a specific way: Variant Image is matched against the image URL as a string. If the value on a variant row does not byte-for-byte match an Image Src declared for that same product, the variant simply has no image. No error, no warning, no row rejection — the product imports, the variant exists, the front end falls back to the featured image, and the customer sees a colour they did not order. Note also that the option names live on the product row while the option values live on variant rows; mixing a name into a value column is exactly how you produce Option value provided for unknown options rather than a useful message.

This is why the clothing-thread responder's request — "show exactly which row or field changed" — is the correct instinct. Row-level diffing is the only diagnostic that catches a broken Variant Image string, because the import report will never mention it.

2. The three-slot ceiling and the error that is not the one you expect

Shopify's variant model exposes three option dimensions. The CSV mirrors that with Option1/2/3 Name and Option1/2/3 Value, and the forum answer above states it plainly. There is no Option4 Name column to add, and adding one does not extend the model — the column is ignored, and any value you expected it to carry has nowhere to go.

Two failure signatures follow, and they look nothing alike:

Loud failure. A variant row supplies a value whose option name was never declared on the product row — or the option name is missing entirely while values are present. Shopify rejects the row with Option value provided for unknown options. This is the good outcome: the import stops and tells you something.
Silent failure. You keep three option columns but pack a fourth attribute inside one of the values, e.g. Option1 Value = Black / Heavyweight. Import succeeds. The product page now shows a single dropdown whose entries are compound strings. Every downstream consumer that assumed Option1 Value is a clean colour token — swatch mapping, filter apps, feed syndication, your own re-import matcher — silently loses that assumption.

The asymmetry matters: the loud error gets fixed in ten minutes, the silent one survives for quarters. If your supplier file has a fourth attribute, assume you are in case 2 until proven otherwise.

3. Three ways to collapse a fourth attribute, and what each one costs

Once you accept the ceiling, there are only three strategies. Each has a concrete, predictable breakage:

Strategy A — concatenate into one option value. Black / Heavyweight, Black / Lightweight, White / Heavyweight. Clean to generate, brutal downstream: swatch logic matches exact strings, so colour swatches stop resolving; sorting is alphabetical on the compound string, so all Black variants are not even adjacent unless your padding happens to agree; and any future supplier rename (Heavy Weight vs Heavyweight) creates a new variant instead of updating the old one. This is the most common choice and the most common source of duplicate variants on re-import.

Strategy B — promote one attribute to a second product. Each fabric weight becomes its own product with its own Handle, carrying only colour and size as options. The data model stays clean and swatches keep working. The cost moves to the catalog: N products instead of one, split reviews, split inventory reporting, and a collections/filter strategy you have to maintain. It is legitimate — but it is a merchandising decision, and it should be made deliberately rather than discovered after import.

Strategy C — drop the attribute from the variant model and move it to metafields or the description. The attribute still exists for the customer, just not as a purchasable dimension. Correct when the fourth attribute does not change the price or the SKU — if it does change either, you have silently made two SKUs into one and your inventory count is now fiction.

The decision is not aesthetic. Ask one question: does the fourth attribute change price, SKU, or stock? If yes, you cannot take Strategy C. If no, Strategy A is usually fine — provided you own the string-normalisation step and never let a supplier's spelling variant create a second variant.

4. Cartesian expansion is where the images quietly die

Whichever strategy you pick, the row count is a product, not a sum. Five colours × eight sizes is 40 rows; add a third dimension of three collapsed fabric values and you are at 120 rows for a single product. Every one of those rows is an independent variant, and every one of them needs its own Variant Image value — the same image URL repeated, once per row, for each row that shares that colour.

The classic failure is writing the image only on the first row of each colour group. Rows are not grouped; the file is flat. Row 1 gets the image, rows 2-8 of the same colour get an empty Variant Image, and the storefront shows eight sizes of the correct colour with no photo. Then someone "fixes" it by setting the product's featured image, which masks the problem on the default variant and hides it on all the others.

A second, subtler failure comes from the URL itself. Supplier CDN URLs frequently carry query strings — resize parameters, region tags, signed expiries. Image Src and Variant Image must be the same string, so the moment you normalise one and not the other (strip the query string in one column, keep it in the other), the binding breaks even though both URLs point at the same picture. Consistency between the two columns is worth more than prettiness in either.

5. What the transcode actually does to a per-row image

Supplier images are usually WebP, often wide-gamut, sometimes EXIF-rotated. If you convert them before upload — which you should, because a file whose bytes do not match its extension is the single most reliable way to get an image dropped at the CDN edge — the conversion itself introduces three specific losses that show up as colour complaints, not as errors:

Alpha becomes black. JPEG has no alpha channel. Drawing a transparent WebP onto an uninitialised canvas composites it against black; the correct order is fill the canvas white first, then draw. Skipped, every transparent-background product shot gets a black rectangle behind it.
Colour profile is clipped. Canvas defaults to sRGB. A Display P3 or Adobe RGB source is clipped into sRGB on drawImage, and toDataURL('image/jpeg') writes no ICC profile — so the browser that rendered it "looks fine" while the phone that receives it shows a duller, shifted red. This is the mechanism behind "the photo looked right on my laptop."
EXIF orientation is discarded. Canvas ignores the orientation tag. A portrait supplier photo with a rotation flag comes out sideways, and it comes out sideways consistently, which makes it look like a supplier error rather than a pipeline step.

None of these produce a failed row. They produce a batch that imports cleanly and generates returns — which is why the fix belongs upstream of the CSV, in the conversion step, not in a post-import cleanup pass.

The white-fill ordering is the one part of this that is purely a code decision, and it is worth getting right once: a Local Canvas Transpiler that fills the canvas before calling drawImage eliminates the black-backdrop class of defect entirely, because the composite has an opaque destination from the first pixel. The colour-profile and EXIF losses are physics — no converter recovers what the format discards — but they can at least be known rather than discovered in a refund request. Running that conversion 100% Local-First also means the supplier photos never leave the machine they were downloaded to, which matters when the file set is the whole of next season's catalog.

Conclusion

The through-line across all five sections is the same: the CSV is a serialisation of a model with three option dimensions, one string-keyed image binding, and no per-row grouping. Every failure above is that model asserting itself against a supplier file that never agreed to it. Before importing a batch, check the following — in this order, because each step invalidates the next if it fails:

Count attributes, not columns. If the supplier spec has more than three purchasable dimensions, choose Strategy A, B, or C before generating the file — and write down the choice.
Normalise option values once, centrally. One canonical token per colour, per size. Supplier spelling variants must never reach the CSV as distinct values.
Assert row count = cartesian product. 5 colours × 8 sizes must equal 40 rows; if it does not, something collapsed silently.
Assert Variant Image is non-empty on every row, and that each value exactly matches an Image Src string for the same Handle — query strings included. A round-trip through a Matrixify CSV export will surface a broken binding immediately, because the export reads back what the store actually stored rather than what you sent.
Pre-encode images to JPEG or PNG before upload, filling white behind transparency and accepting that the ICC profile will not survive.
Re-import diff on Handle + option values, never on Title. Title changes are cosmetic; option value changes create new variants.

About EasyCatch

EasyCatch is a 100% Local-First copilot for 1688-to-Shopify sourcing. Its Local Canvas Transpiler converts supplier WebP images to JPG entirely inside your browser — filling behind transparency before the draw, so per-row images survive the transcode instead of arriving with black backdrops — and its CSV engine expands colour-by-size combinations into Matrixify-compliant ZIPs with the image URL repeated on every variant row, not just the first. Option values are normalised once, at extraction, so a supplier's spelling variant cannot become a second variant. No supplier link, price, or product data ever leaves your machine: Zero-Server Privacy by design.

A Snapshot That Stops at 4,000 Tokens Is Not Smaller, It Is Blind: Three Walls That Hide a Page From an Agent

yu chen — Mon, 19 Oct 2026 02:04:50 +0000

By Chen Yu — building Operun, a local-first browser kernel. Written 2026-10-19.

TL;DR

Most browser-automation stacks treat "read the page" as a solved problem: dump the accessibility tree, hand it to the model, let the model pick a control. The failure mode that costs real days is not a wrong click. It is a snapshot that is quietly incomplete and looks complete. In Operun's a11y snapshot we found three independent walls, each producing the same complaint from the operator ("the data is missing") from a completely different root cause: a per-name hard clip at 50 characters, a token budget that truncated by break and said so only in a trailer, and a dispatch rule that never emitted nodes with no role at all. The fixes were not one constant: the name ceiling went 50 → 300 → 1,200 characters, the token budget went 4,000 → 40,000 tokens (roughly 120,000 characters of read surface), and the third wall could not be fixed by any constant — it needed a separate content-reading path. This post is the mechanism, the field evidence, and the design reasoning, including the reasons the numbers are ceilings rather than removals. Everything below comes from src/core/snapshot/scanner.ts and from instrumented runs against a live listing page; nothing here is a feature summary.

1. The read surface is a budget, not a dump

An a11y snapshot in Operun is produced by takeSnapshotInPage() and returned as { text, count } — one newline-terminated line per control, plus the number of controls reported, which is the unambiguous signal for "this page is genuinely empty" as opposed to "I found nothing I could name". The function is injected into the page through chrome.scripting.executeScript, which imposes a discipline that shapes the whole file: no imports, no module scope, every helper nested inside the function. Anything closed over from module scope would simply not survive injection.

That constraint is also why the budget exists at all. Actionbook, the earlier kernel, could afford a 100,000-token ceiling because it wrote the full tree to a file and only the path traveled back. In Operun the text travels inline, in a STEP_RESULT frame over the cloud socket. So the token budget here bounds a message, not a file. That distinction is the entire design pressure: a message has to be one frame's worth of payload, and the reader on the other end is a model deciding what to do next, not a human scrolling.

The walk itself is root.querySelectorAll('*') — every element, every time. The budget does not bound the walk; it bounds what leaves the page. That is worth stating plainly because it sets expectations: raising the ceiling tenfold did not make the scan cheaper, it made the answer complete. Cost moves to the message size, which is the cheaper of the two failures.

Three exclusions happen before a node can ever become a line, and they are worth knowing because they explain absences that look like bugs: <option> elements inside a native <select> (no action this kernel has can pick one, so a ref on an option would be a handle to nothing — the parent reports the currently chosen value instead); input[type=hidden] (excluded by what it is, not by how it is styled, since it computes to display: none anyway); and anything inside closest('[hidden], [aria-hidden="true"], [inert]'), which covers all three routes the platform offers for taking a subtree off the page.

2. Wall one: a name clipped at 50 characters

MAX_NAME_CHARS shipped at 50. Its only consumer was clip(), applied to the accessible name of each control. On a dense admin console that is invisible — button labels are short. On a recruiting or e-commerce listing it is catastrophic, because a listing card typically composes the whole card's text into one accessible name: company, school, and self-description concatenated. The field evidence was blunt: 60 out of 60 cards on one BOSS listing had an accessible-name length of exactly 50, and the cut landed mid-word. Not "around 50" — precisely 50, minimum equal to maximum, because every card exceeded the cap and every card was clipped to it.

Why this is worse than a shorter answer: the name is how the agent decides which control a line is. A name that stops mid-sentence is a line the agent cannot match against what it is looking for, so it confidently reports "not present" about a card that is sitting on screen. A wrong answer that looks like a whole one is the most expensive failure class in this whole system.

The fix went in two steps, and the intermediate step is the interesting part. 50 → 300 was not enough: with the cap at 300 the observed distribution became {300: 32, 298: 1, 296: 1, …} — the mass of cards sitting exactly at the new ceiling, which is the signature of a clip that is still binding. Only at 1,200 did the distribution spread out naturally and the company name start surviving.

1,200 is a ceiling, not a removal, and that is deliberate. A page is free to put a 100 KB aria-label on a single element, and one element spending the budget that every other control draws from is exactly how a snapshot stops describing the page. The same trade is made explicitly nearby: MAX_VALUE_CHARS = 30, because a value is something you read once, not something you match on.

3. Wall two: the budget that truncated silently

MAX_TOKENS shipped at 4,000. The accounting loop walks the collected lines, estimates cost as Math.ceil(line.length / 3) — a character is roughly a third of a token, the same estimate the earlier kernel truncates by — and accumulates. When spent + cost > MAX_TOKENS it breaks, and appends exactly one trailer: … N more elements omitted.

The trailer is honest about how many and silent about which. That is the wall: the reader of a truncated a11y snapshot is an agent deciding what to do next, and it must know that what it holds is not the whole page — otherwise it concludes the page is short.

The original 4,000 was argued from "a dense admin page is a few hundred controls". True of a console. False of a listing page that is thousands of cards and whose controls a workflow reaches by scrolling to the bottom. A ceiling that cuts that page is not a smaller answer, it is a blind one.

Diagnosing this wall has a trap worth documenting, because it produced a false accusation in our own notes. Two frames from the same drawer: frame A measured 12,175 characters ≈ 4,058 tokens > 4,000 → trailer present; frame B measured 7,713 characters ≈ 2,571 tokens < 4,000 → no trailer, and no reason to suspect the budget. If you see an absent field in frame B and blame token truncation, you are wrong by arithmetic. Always run the sum before blaming the wall.

The ceiling is now 40,000 tokens, which at ceil(len/3) is roughly 120,000 characters of read surface — about 120 KB of text, one WebSocket frame, comfortably inside what the transport carries without configuration, and still a bound. The arithmetic that matters when sizing a page for this budget is one line: cards × name ceiling ÷ 3 ≈ tokens, which must stay under the budget. Sixty cards at 1,200 characters is 72,000 characters ≈ 24,000 tokens — under 40,000, with room for the rest of the page.

4. Wall three: the nodes with no role at all

roleOf() returns one of three things, and the third is the wall. A declared role attribute is mapped through INTERACTIVE_ROLES; anything declared but not interactive (role="heading", role="presentation") returns null — a statement about interaction, not about content. Tags map directly: a[href] → link, button → button, select → combobox, and the input type fan-out covers checkbox, radio, the button-ish types, slider, spinbutton, searchbox, textbox. A <a> with no href returns the empty string. Everything else — a <div>, a <span>, a <section> — also returns the empty string, meaning no declared role.

That empty string is where plain-div UIs live. A page whose controls are <div>s with a delegated click listener has no roles anywhere, so the only way it becomes visible to an agent is pointerHint(): cursor: pointer, onclick, or tabindex. That is the inherited cursor-detection pass, and it is why some pages work beautifully and others return zero nodes despite a successful frame match.

The three-layer measurement from a BOSS detail drawer is the clearest illustration I have:

__TOP__                28 → 36 nodes   (the 8 new ones are the action bar)
iframe (frame A)      255 → 267        (growth is wall one's fix: longer names)
iframe[search]        160 → 160        (unchanged — checking only this layer
                                        reports "the click did nothing")
iframe[src*=resume]         → 0 nodes  (the resume body lives here, plain text)

Three layers, three different diagnoses, and a fourth that simply has no roles to report. No constant fixes this. Raising MAX_NAME_CHARS to a million changes nothing about a paragraph of <div> text with no role, no cursor hint, and no tabindex. The dispatch is explicit about it: if (role === null) { pushContent(node, cache, lines); continue } — and since pushContent() opens with if (mode !== 'content') return, in interactive mode that branch is exactly if (role === null) continue: the node is visited, then dropped without a line. This is why the content-reading path is a separate mode rather than a bigger cap: mode === 'content' makes the walk call pushContent(), which emits @eN: [tag 'text'] for content tags with non-empty flattened text — guarded by if (text === '') return, because a block with no text is not a shorter answer, it is a line with nothing on it.

5. What changing a constant actually costs

Three engineering details separate "changed a number" from "shipped a fix".

Build-time injection. The constants live in src/, and the snapshot is injected into the page at runtime from the built bundle. Editing src alone changes nothing until npm run build:operator runs and the unpacked extension is reloaded in chrome://extensions. There is no hot path: a stale service worker keeps serving the old background.js from memory, and a websocket reconnect does not reload code.

Never grep the built artifact for the number. Minification rewrites 40000 as 4e4 and 16000 as 16e3. Verifying a build by grepping for 40000 in background.js reports a false negative on a perfectly good build. Compare byte size and behavior, not literals.

The constant's own name is redacted. MAX_TOKENS contains TOKEN, so reading that line through most tooling returns const MAX_TOKENS=***. I hit this on this very article: the line reads =*** and MAX_NAME_CHARS = 1200 right below it reads fine. The workaround is mechanical — index by line number and extract digits with a regex, never paste the whole line into a command and trust the echo.

One more design detail that shows the budget is not the only bound: the ref cache prunes itself. byRef is a Map, so it would pin every removed subtree for the life of the document; the walk deletes entries whose node is no longer isConnected. byNode is a WeakMap and releases on its own. A reparented row is re-registered from byNode on the next walk, so pruning costs nothing.

Conclusion

All three walls produce the same operator complaint — "the data is missing" — and each needs a different instrument. The checklist we now run before blaming the page:

Count the controls first. count === 0 with a successful frame match is wall three, not a missing element. Check pointerHint coverage on that layer before touching any constant.
Measure name lengths, not names. If the distribution is {cap: N, cap-2: 1, …} with the mass sitting exactly on the ceiling, the clip is still binding. A spread distribution means the cap is finally above the data.
Run the token arithmetic before blaming truncation. sum(ceil(len/3)) against the budget, per frame. An untruncated frame has no trailer — do not invent a cause for an absence it cannot explain.
Treat … N more elements omitted as a page-level warning, not a footnote. It means the answer is incomplete and you do not know what is missing.
Check the layer you did not check. iframe[search] stayed at 160 while the action bar grew and the resume frame went to zero nodes — one layer's stability says nothing about the other three.
Reach for CSS only when perception genuinely cannot. Some things — a download control that is a bare <div><svg><use> with no accessible name — are addressable only by structural selector. That is a fallback, not a strategy.

The general lesson is less about snapshots than about perception as an interface: a perception layer that fails by returning less is safe, and one that fails by returning a plausible subset is dangerous, because the agent downstream has no way to tell the difference. Every constant in that file is a decision about which of those two failures you are willing to ship.

About Operun

Operun is a local-first browser kernel: a cloud core on loopback plus an operator extension that drives your real, already-logged-in Chrome through CDP. Its a11y snapshot, token budget, and content mode are the perception layer an agent uses to decide what to click — which is why they are specified as constants with reasons attached rather than tuned per deployment. Local-first here is structural, not promotional: the browser session, the cookies, and the page text stay on your machine, and only the bounded snapshot crosses the socket.

Supplier Spreadsheets Are Not Shopify CSVs: Handle Keys, SKU Mapping, and the Image-Prep Pipeline That Keeps Bulk Updates Safe

yu chen — Wed, 14 Oct 2026 15:29:34 +0000

By EasyCatch Growth Desk — weekly technical deep-dive for the Shopify community. Written 2026-09-07.

TL;DR

Most merchants treat "importing" as the hard part and "updating" as a smaller repeat of it. The two most active workflow threads on community.shopify.com this week show the opposite is true. In How do you handle supplier spreadsheets when updating your store? (Sep 5), a developer exploring this exact workflow is told by merchants that the import itself is rarely the failure point — it is everything before it: supplier files are keyed on SKU while Shopify's products CSV is keyed on Handle, so a blank or drifted handle silently creates duplicate products instead of updating the one you meant. In What do you do with product images before they're ready for Shopify? (Sep 4), the consensus is that renaming, organizing, and matching images to variants is the "most repetitive and time-consuming" stage — and the filename is where variant-to-image binding is won or lost before the CSV is ever written. This guide explains why the update loop is a data-model problem, not a spreadsheet chore: handle-keyed upsert semantics, SKU-to-handle mapping, Excel's silent corruption of identifiers, and an image-prep naming discipline that makes the Variant Image column trivially correct.

1. Why Your Supplier File Is Not a Shopify CSV

Open Shopify's product CSV template next to a supplier's price/stock sheet and the difference is not the columns — it is the key. Supplier files identify a row by SKU (ABC123-BLUE-M). Shopify's importer identifies a row by Handle (abc123-blue-m), and merges every CSV row sharing a handle into one product record before applying variant-level changes.

This mismatch is invisible until it bites. As one merchant put it in 676989: "the supplier file is keyed on SKU and Shopify's product CSV is keyed on Handle. Nothing warns you about the mismatch. If the handle column is blank or slightly wrong, the row does not update the product you meant, it creates a new one, and you find out when the store has two of everything." That is the single most expensive sentence in the thread. A price-update file built by joining on SKU but written with a stale or hand-typed handle column is a duplicate-product generator, and the import summary will show zero errors — handle-keyed upserts silently create when they cannot match.

The fix starts with a mapping, not a merge. Before touching the supplier file, export a fresh product list and build a SKU → Handle map from it. Not last month's copy, not the CSV you imported last time — a fresh export, because handles change when titles change and SKUs get reassigned. Join the supplier file to the map on SKU; let any SKU with no handle fall into an exceptions list for human review instead of being auto-created.

2. Excel Is a Data-Damage Tool, Not a Data Tool

The second recurring theme in 676989 is that opening the file is enough to break it. Excel silently rewrites identifiers on save:

Leading zeros stripped. SKU 001234 becomes 1234 — which no longer matches anything in the SKU → Handle map, so the row either creates a duplicate or silently updates nothing.
Scientific notation. Long numeric IDs (order IDs, barcode-adjacent fields, 11+ digit supplier codes) become 7.05E+11. The value looks wrong only if someone scrolls to it.
Date coercion. 01-2345 or 3-4 cells get converted to dates, destroying the identifier entirely.
Sorting a column independently. One merchant's hard rule from the thread: "I'd avoid sorting that CSV in Excel." A partial sort detaches rows from their products — the file now says SKU X costs $12 when the adjacent row still holds SKU Y's description.

The practical rule for anyone handling supplier files: never let the supplier file touch Excel before it is normalized. Read it with a proper CSV parser, validate SKU format (length, charset, leading zeros), and fail loudly on rows that don't validate — do not "fix them quietly," because quiet fixes are how wrong prices ship to the storefront.

3. The Update Loop: Change Detection Before Re-Import

A supplier price or stock update should never be applied by re-importing the entire catalog. Full re-imports re-run every upsert rule in Section 1 across every row — one stale handle in a 2,000-row file creates one duplicate you won't notice until the Google Shopping feed flags two products with identical titles.

The safe loop, assembled from the merchants' answers in 676989:

Export fresh state from Shopify (products + variants + inventory).
Normalize the supplier file: validate SKUs, strip formatting, parse prices/stocks as numbers, reject malformed rows.
Join to the SKU → Handle map built in step 1.
Detect changes — compare the supplier's new price/stock against current values, and keep only rows where something actually changed. Change detection is also your safety net: a supplier file that suddenly shows 40% of SKUs at $0 is a broken export, not a sale, and detection will surface it as an anomaly instead of importing it.
Review exceptions (unmatched SKUs, zero prices, new products) in a separate list.
Import, and use Shopify's own stock safety check for inventory rows — the On hand (current)/(new) confirmation that one merchant called "the safety check" — before confirming.
Keep an update log of what was changed and when, so a bad import can be rolled back by re-running the previous good state.

This loop turns "import the file and pray" into a reviewable, reversible operation.

4. The Image-Prep Pipeline: Filenames Are the Join Key

Thread 676739 asks merchants what they actually do with images between creation and upload. The answers converge on one discipline that most stores skip: the filename is the data model. The most-cited pattern in the thread is a SKU-position naming rule:

ABC123-01.jpg, ABC123-02.jpg — gallery order encoded in the filename
ABC123-blue-01.jpg — variant shots carry their option value
One folder per batch, with approved / needs-editing / rejected subfolders, and only approved files get renamed
Crop to a consistent aspect ratio and compress before upload (merchants cited ~2000 px on the long side as a working default)
A spreadsheet mapping final filenames to product handles before the CSV is written

Why does this matter technically? Because Shopify's CSV binds variant images by URL-string identity: the Variant Image column must repeat, per variant row, a URL that exactly matches an Image Src row in the same file — or an existing image in the Media library. When your files are named ABC123-blue-01.jpg from the start, generating the cartesian expansion (5 colors × 4 sizes = 20 variant rows, each repeating its own color's image URL) is a mechanical join on the filename. When your files are named IMG_4821.jpg, someone has to eyeball every row — and eyeballing 20-row variant blocks is exactly where "colors swapped / sizes show the wrong image" complaints are born. One merchant in the thread confirmed the slowest step is "making sure each image belongs to the right color/option" — which is only slow when the naming scheme doesn't encode the answer.

5. WebP and the File-Prep Stage

The image-prep stage is also where format conversion belongs — before naming and upload, never after. 1688/Alibaba supplier galleries are predominantly WebP files behind signed CDN URLs (...webp?x-oss-process=image/...). If a WebP URL survives into the CSV, Shopify's async download queue can silently skip the fetch — the row imports "successfully," the image slot stays blank, and no error is surfaced anywhere.

The conversion is a local binary operation: a browser <canvas> decodes the source via drawImage, then toDataURL('image/jpeg') re-encodes it. Two honest constraints: JPEG is 8-bit per channel, so higher bit-depth sources and alpha channels are downsampled (visually negligible for product photography, relevant for line art), and the re-encoded file must be re-hosted at a stable, standard-format URL — a signed, expiring supplier URL re-entered into the CSV just moves the failure a few hours later when the signature expires before Shopify's queue fetches it.

Local-first is not a privacy slogan here; it is a correctness argument. Transpiling on your own machine means the CSV never contains a format Shopify will drop, and the file you produce — standard JPEGs plus a Matrixify-compliant ZIP with every expanded variant row repeating its own image URL — is deterministic. You can run the same prep twice and get the same catalog. You cannot say that about a manual Excel session at 11 p.m. before a product launch.

6. A Normalization Pipeline That Makes All Three Safer

Every failure in this guide happens upstream of Shopify, which is the good news: fix the pipeline once, and every future supplier update inherits the fix.

Read supplier files programmatically — never Excel-first. Validate SKUs, preserve leading zeros, parse numbers strictly.
Transpile WebP to JPEG locally (canvas decode → re-encode → stable output), so no unsupported binary or expiring signed URL ever enters a CSV. This is the same binary conversion as Section 5, running as a repeatable step instead of a manual one-off.
Build the SKU → Handle map from a fresh export and join, never blind-merge.
Generate the cartesian expansion programmatically, repeating each color's Variant Image URL on every size row, and package the result as a Matrixify-compliant ZIP that Shopify's importer (or Matrixify) accepts without row-level hand-editing.
Run change detection and keep an update log, so a price update touches only the rows that actually changed.

This is exactly the workflow class that a tool like EasyCatch (easycatch.org) — a 100% Local-First 1688-to-Shopify copilot built around a Local Canvas Transpiler for WebP-to-JPG conversion and Matrixify-compliant ZIP generation — automates end to end. But the architecture matters more than the tool: normalize the source catalog locally, and the entire class of silent-import bugs disappears for every future batch, not just this one.

Conclusion

The two threads that anchor this guide say the same thing from opposite ends of the workflow. The supplier-update thread (676989) shows that updating a store breaks on keying — SKU files against a handle-keyed importer, with Excel quietly corrupting the identifiers in between. The image-prep thread (676739) shows that the tedious, error-prone half of merchandising is naming and matching — and that a filename convention converts variant-image binding from eyeball work into a join. Both are upstream problems. Handle them there — with a fresh SKU → Handle map, strict file validation, change detection, an update log, and a local transpile-and-package step — and "import" becomes the boring, reliable 5% of the job it was always supposed to be.

About EasyCatch

EasyCatch is a 100% Local-First copilot for 1688-to-Shopify sourcing. Its Local Canvas Transpiler converts supplier WebP images to JPG entirely in your browser, and its CSV engine expands color-by-size variants into Matrixify-compliant ZIPs with correct per-row image mapping — no supplier link or product data ever leaves your machine. Zero-Server Privacy by design.