Make switching instant

A product sold in five colours on two sides can have dozens of photos behind the designer, and each side may print its own template. The designer loads a photo, and a side’s template and pictures, when the customer first switches to it, so that switch waits on the network. Preloading loads them ahead, so a switch to one shows on the next frame with no request:

const designer = await Pixonaut.mount('#designer', {
  // …
  preload: 'background',
});

The modes

preload	What it loads ahead
'off'	Nothing: each switch loads what it shows.
'background'	Everything, one item at a time in the browser’s idle time, once the first view is shown, nearest first: the variant shown’s other views, then its sides, then the other variants in the blank’s order. It holds off while the customer drags on the canvas or types in the form, and while the page is hidden.
'eager'	Everything at once, once the first view is shown: for a product you know is small, or a page whose only job is the designer.
'auto' (default)	One of the three, with a concurrency and a memory budget, chosen from an estimate of what preloading would hold and from what the browser says of the device.

Preloading never changes what is shown and never fails a switch: an item that fails to load is loaded by the switch to it, as without preloading. A switch to something not loaded yet loads it at once, ahead of everything queued, and the preload carries on after it.

What it costs

Preloading spends the customer’s memory, bandwidth and CPU to make switching instant, and may slow the page on a low-end device. auto chooses from an estimate, because a page cannot measure its own memory: the estimate is width × height × 4 bytes for each photo, from its view’s photoSizePx, plus each side’s preview canvas at the size it is drawn. Of the browser’s signals it reads navigator.deviceMemory, navigator.hardwareConcurrency and navigator.connection (effectiveType, saveData):

• saveData on, or a 2g or slow-2g connection, chooses off.
• A device with plenty of memory and cores on a 4g connection, preloading an estimate within its budget, may choose eager.
• Where a signal is missing (Safari and Firefox have neither deviceMemory nor connection), auto assumes a low-memory device on an unknown connection: background, one at a time, within a small budget. Never eager.

Past the budget the photo shown least recently is let go, and loads again when it is switched to; what is shown is never let go.

Preloading on demand

await designer.preload({ variants: ['v_black_m'], sides: ['back'] }, {
  mode: 'eager',
  concurrency: 2,
  budgetBytes: 64 * 1024 * 1024,
});
designer.cancelPreload();
const plan = designer.preloadPlan();

• preload(target, { mode, concurrency, budgetBytes }) loads target: 'all', or the variants (refs), views (ids) and sides (placement ids) named, an axis left out meaning every one the product allows. mode is 'background' when left out; concurrency and budgetBytes apply to every mode. It ends a preload in progress, and resolves once what it asked for is loaded or cancelled. A variant, view or side the product does not allow rejects with a TypeError, as setView() and setSide() do.
• cancelPreload() stops what is queued and in flight. What has loaded stays loaded.
• preloadPlan() returns what auto would do and why, loading nothing: { mode, concurrency, budgetBytes, estimatedBytes, items, signals, reasons }. signals holds deviceMemory, hardwareConcurrency, effectiveType and saveData, each null where the browser has none, and reasons names each signal or fallback that decided it, such as "deviceMemory unavailable: assumed low" or "saveData on: off".

on("preload") reports progress after each item settles, and once more when the preload ends or is cancelled, with done: true:

designer.on('preload', ({ loaded, total, estimatedBytes, failed, done }) => {
  if (done) console.log(`${loaded} of ${total} preloaded, ${failed} failed`);
});