DEV Community: Silkline

Printing Data Matrix codes at an exact size: modules, DPI and PNG pHYs

Silkline — Sun, 25 Oct 2026 14:00:00 +0000

"Make the code 12 mm wide" sounds simple. Then the label goes through a 203 dpi thermal printer, the edges come out ragged, and the scanner struggles. The problem is rarely the barcode library. It's the step from millimetres to printer dots.

I recently built a browser Data Matrix generator for labels, and getting the physical size right was most of the work. This post covers the maths and the file formats, then GS1 input and a read-back check.

Modules and dots

A Data Matrix is a grid of square modules, for example 24×24, plus a quiet zone around it. If you want the code (without the quiet zone) to be 12 mm wide, each module is 12 / 24 = 0.5 mm.

A printer can't print 0.5 mm, though. It prints dots. At 203 dpi a dot is 25.4 / 203 ≈ 0.125 mm, so 0.5 mm is 3.996 dots. Print that as-is and each module edge gets rounded to a dot somewhere along the way, so modules come out at uneven widths. The fix is to round to a whole number of dots per module first, and derive every size from that:

export function resolvePrintSize(request: PrintRequest, { columns, rows, quietZone }: Geometry, referenceColumns = columns): PrintSize {
  const wantedModuleMm = request.basis === 'module' ? request.valueMm : request.valueMm / referenceColumns;
  const wantedDots = (wantedModuleMm * request.dpi) / MM_PER_INCH;
  const dotsPerModule = Math.max(1, Math.round(wantedDots));
  const moduleMm = (dotsPerModule * MM_PER_INCH) / request.dpi;
  return {
    dotsPerModule,
    moduleMm,
    totalWidthMm: (columns + 2 * quietZone) * moduleMm,
    pixelWidth: (columns + 2 * quietZone) * dotsPerModule,
    // ...heights, code size without quiet zone, and a flag if the module was raised to one dot
  };
}

For the 12 mm example at 203 dpi that's 4 dots, a 0.5005 mm module and a 12.01 mm code. At 300 dpi the same request becomes 6 dots per module and a 12.19 mm code: slightly bigger than asked, but every module is identical. The tool prints the actual module and code size, so the difference isn't hidden.

referenceColumns is for batches: codes with different data can get different symbol sizes, and passing the widest keeps one module size across the batch.

Getting the module grid out of bwip-js

bwip-js (a JavaScript port of BWIPP) does the encoding. I wanted the raw module grid rather than a canvas, so one matrix could feed SVG, PNG and PDF. bwip-js accepts a custom drawing object, so I pass one whose methods do nothing except record the outlines it traces:

polygon: (points: Point[]) => outlines.push(points.map(([x, y]) => [x, y] as Point)),
end: () => ({ outlines, width, height }),

At scale 1, one module is one unit, so testing the centre of each cell, (column + 0.5, row + 0.5), against those outlines with an even-odd rule gives the dark and light modules.

For plain text there's one encoding decision. Latin-1 text goes in as single bytes. Anything else is encoded as UTF-8 behind ECI 000026, so readers know which code page the bytes are in.

SVG: a viewBox in modules, a size in millimetres

SVG makes physical size easy. The viewBox is in modules, and width and height are written in mm:

`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}" ${size} shape-rendering="crispEdges" role="img">`

In print mode size is something like width="14.014mm" height="14.014mm": the 12 mm example at 203 dpi plus a two-module quiet zone on each side. Dark modules are merged into horizontal runs per row in one <path>. The background rectangle is optional, because laser and cutting software read it as one more shape to burn.

PNG: one pixel per dot, plus pHYs

A PNG has no physical size unless you write one. The pHYs chunk stores pixels per unit on each axis, with unit 1 meaning metres. I write the PNG myself (fflate for the zlib stream, plus a small CRC and chunk writer), so the bytes are the same in every browser and no canvas is involved:

/** pHYs chunk: pixels per metre in both directions, so print software and image editors know the physical size. */
function pixelDensity(dpi: number): Uint8Array {
  const data = new Uint8Array(9);
  const perMetre = Math.round(dpi / 0.0254);
  const view = new DataView(data.buffer);
  view.setUint32(0, perMetre);
  view.setUint32(4, perMetre);
  data[8] = 1;
  return chunk('pHYs', data);
}

300 dpi becomes 11811 pixels per metre. The chunk goes after IHDR and before IDAT, as the PNG spec requires. In print mode each module is exactly dotsPerModule pixels, so one image pixel is one printer dot and nothing gets resampled on the way to the printer.

The PNG is one RGBA buffer in memory, so sizes over 10,000 px a side or 40 megapixels are refused in favour of SVG or PDF.

PDF: the page is the code

For PDF I use jsPDF with unit: 'mm' and format: [totalWidthMm, totalHeightMm], so the page is exactly the code plus its quiet zone. Modules are vector rectangles from the same row runs as the SVG. Print at 100%, not "fit to page", and it's the size you asked for.

GS1: brackets in, FNC1 out

GS1 Data Matrix carries element strings such as (01)09506000134352(17)281231(10)LOT42. Each Application Identifier (AI) has a format, and some, like the GTIN in (01), end in a mod-10 check digit (weights 3 and 1 alternating from the right). The tool recomputes it and says what the digit should be.

For the common AIs, values are checked against the regex GS1 publishes, so a bad date gets a specific message such as "13 isn't a month" instead of a terse linter error. Less common AIs are still checked by BWIPP's own GS1 linter inside bwip-js.

The brackets are not encoded. The encoder (gs1datamatrix in bwip-js) adds FNC1 at the start and the group separators itself. So the most important cleanup is removing what users paste from other tools: <GS>, {GS}, [FNC1], \x1d, a leading ]d2. Left in, they'd be encoded as data, and you'd get a wrong code that still scans.

Read it back before offering it

The last step is a self-check. After encoding, a separate decoder reads the drawn modules the way a scanner would: strip the finder and timing patterns, walk the data modules in the placement order from ISO/IEC 16022, decode the codewords. Then it compares the result with what was asked for:

export function readBack(matrix: ModuleMatrix, request: EncodeRequest): ScannedSymbol | null {
  try {
    const scanned = scanMatrix(matrix);
    const data = request.mode === 'gs1' ? scanned.text.replaceAll('\u001d', '') : scanned.text;
    return data === expectedData(request) ? scanned : null;
  } catch {
    return null;
  }
}

If it doesn't match, the code isn't offered at all. The decoder is written independently of the encoder. In the test suite, the same symbols in every size also go through zxing-wasm, and optionally libdmtx, as independent decoders.

Summary

Round to a whole number of printer dots per module, then derive every size from that.
Write SVG with a viewBox in modules and width and height in mm.
Give PNGs a pHYs chunk (pixels per metre, unit 1) and make one pixel one printer dot.
Make the PDF page exactly the code plus quiet zone, and print at 100%.
For GS1, validate AIs and check digits, and strip any separators the user typed.
Decode what you drew and compare it with the input before you hand the file over.

If you need a Data Matrix at a real size in mm, the generator is free for single codes at data-matrix-generator.com, and it runs entirely in your browser.

Seating wedding guests with constraints: a small optimiser in a Web Worker

Silkline — Thu, 22 Oct 2026 13:00:00 +0000

Seating wedding guests sounds like a spreadsheet job until you write down the rules. The Smiths sit together. Uncle Bob and Aunt Carol must not share a table. The grandparents stay at table 1. Every table should be about as full as the others. Each rule is easy alone; together they pull against each other.

I recently built a browser seating chart planner, and the part that took longest was the optimiser behind its "Seat everyone" button. Here is how it works.

One cost for everything

The input is guests with a household (a free-text group column), tables with a capacity, pair rules ("together" or "apart"), and pinned guests who stay where the user put them. The optimiser turns this into indices and typed arrays, and rules into weighted edges between two guests.

Instead of a separate feasibility check, everything becomes one number to minimise. Hard rules get a weight that outweighs all the soft terms together:

export const DEFAULT_WEIGHTS: Weights = {
  hard: 10_000,      // per broken "together" / "apart" rule
  together: 100,     // per "together" rule, when it is set as a soft wish
  groupSplit: 100,   // per table a household uses beyond the fewest that could hold it
  groupSpread: 10,   // per table-number gap between the pieces of a split household
  balance: 4,        // per squared guest away from a table's fair share
  // ...plus tag, relation and table-preference terms
};

The balance term deserves a note. Each table's fair share is capacity × seatable guests / total seats, and the cost is the squared distance from it. That spreads guests over every table instead of leaving one nearly empty.

Scoring a move by its delta

A local search tries tens of thousands of moves, so rescoring the whole plan each time would be slow. The fix is to make every cost term belong to exactly one table, group, tag or rule. A move then only touches a few terms: sum them, apply the move, sum them again.

/** Moves guests[i] to targets[i] and returns the change in total cost. Undo by moving them back. */
export function moveGuests(p: Problem, s: State, guests: readonly number[], targets: readonly number[]): number {
  const from = guests.map((guest) => s.tableOf[guest]);
  const before = localCost(p, s, guests, targets);
  guests.forEach((guest, index) => seat(p, s, guest, targets[index]));
  return localCost(p, s, guests, from) - before;
}

localCost uses an epoch counter so each table, group and rule is visited once per call, even when two moved guests share it.

The search, in four steps

Pins first. Pinned guests are seated and never moved.
Greedy start. A household plus everyone tied to it by "together" rules is a block. Blocks go largest first, each to the table where it adds the least cost. A block that can't go in whole without breaking a hard rule is placed guest by guest.
Repair if needed. If everyone has a seat but a hard rule is still broken, the hard part is treated as graph colouring: tables are colours with a capacity, "apart" pairs are edges. DSATUR builds a colouring, then a tabu search works on the remaining conflicts. Its result is used only if it breaks fewer hard rules.
Simulated annealing on the full cost.

Each annealing step proposes one of four moves: one guest to another table, a whole block piece, a guest to the table of a household member seated elsewhere, or a swap of everyone movable at two tables.

function propose(ctx: Context, fixed: Uint8Array): Move | null {
  const { p, s, random, movable } = ctx;
  const guest = movable[randomIndex(random, movable.length)];
  const roll = random();
  const table = randomIndex(random, p.tableCount);
  if (roll < 0.35) return shiftOrSwap(ctx, [guest], table, fixed, false);
  if (roll < 0.67) return shiftOrSwap(ctx, blockPiece(ctx, guest, fixed), table, fixed, true);
  if (roll < 0.95) return proposeJoin(ctx, guest, fixed);
  return proposeExchange(ctx, s.tableOf[guest], table, fixed);
}

If the target table is full, a shift becomes a swap. Acceptance is the textbook rule: keep a better move, keep a worse one with probability exp(-delta / temperature). The temperature cools geometrically from 30 to 0.3, so early steps can break a household apart to make room and late steps only polish. The best seating seen is restored at the end.

Random numbers come from a seeded generator (mulberry32), so the same input and seed give the same seating unless the time budget cuts the run short. The run stops at a 250 ms budget by default, or early once the cost reaches the balance floor, the lowest balance cost any whole-number seating can have.

Exact solving for small plans

For up to 60 guests there's a second stage. The same cost is written as a mixed-integer linear program and solved by HiGHS compiled to WebAssembly, in the browser. The annealing result is the starting solution, so the solver only has to improve it or prove it optimal within 1.5 seconds.

Unless the solver fails, it ends with a proof that nothing costs less, or a proven lower bound. Larger plans get a cheap combinatorial bound instead, where a big gap means "not proven", not "far from optimal".

Keeping it off the main thread

A solve of over a second would freeze the page, so the optimiser runs in a module Web Worker. Cancelling is the simplest thing possible: terminate the worker, and start a fresh one next time.

return {
  outcome,
  cancel: () => {
    discardWorker(); // worker.terminate(); worker = null
    finish({ status: 'cancelled' });
  },
};

Each request carries an id and replies with another id are ignored, so a late answer can't overwrite a newer run.

The planner runs it twice. A quick run with the exact solver off is shown immediately. Then, for small plans, a full run goes in the background, and its result replaces the quick one only if it is strictly cheaper and the user hasn't changed anything meanwhile.

When the rules can't all be met

"Something went wrong" is the worst answer here, so the optimiser looks for causes that hold for every possible seating:

an "apart" pair that a chain of "together" rules ties to one table. A breadth-first search finds the chain so the message can name it.
a "together" group larger than the largest table.
more guests who must all sit at different tables than there are tables.
an odd ring of "apart" rules with only two tables: three guests who each must avoid the other two can't fit on two tables.
two pinned guests who contradict a rule.

Anything still broken that none of these explain is reported as unresolved, with both names. If there simply aren't enough seats, the planner adds tables first and says how many.

Summary

Put hard rules and soft goals in one cost, with the hard weight above all soft terms combined.
Make every term belong to one table, group or rule, and score moves by their delta.
Greedy start, colouring repair for hard rules, then seeded simulated annealing.
For small plans, an exact MILP solver in WebAssembly can prove the result optimal.
Run it in a Web Worker, cancel by terminating, match replies by id.
When the rules can't be met, explain why, by name.

If you're planning a wedding or any event with tables, the planner is free at seating-chart-generator.com, and the guest list never leaves your browser.

Bates numbering PDFs in the browser with pdf-lib: shrink the page, then read the numbers back

Silkline — Thu, 22 Oct 2026 10:58:24 +0000

A Bates number is a label printed on every page of a set of documents: usually a short prefix and a running number, like ABC-000251, ABC-000252, and so on. No two pages in the set share one, so anyone can point at a single page and find it again.

I added Bates numbering to a browser tool that turns .eml and .msg emails into PDFs. Stamping a string at the bottom of a page sounds like ten lines of pdf-lib. It wasn't. Here is what the code does and why.

The format: prefix, padding, start number

The prefix is optional and limited to A–Z, a–z, 0–9, space and - _ . /, up to 20 characters, because the number is drawn in Helvetica, a standard PDF font. A character Helvetica can't draw is refused up front, with its code point in the message.

The number gets at least six digits. If the last number in the batch needs more, every page in that batch gets the wider width, so the numbers still sort as text:

export function batesStamp(options: BatesOptions, totalPages: number): BatesStamp {
  const digits = Math.max(BATES_DIGITS, String(options.start + totalPages - 1).length);
  return { ...options, digits };
}

export function batesNumber(stamp: BatesStamp, pageIndex: number): string {
  return `${stamp.prefix}${String(stamp.start + pageIndex).padStart(stamp.digits, '0')}`;
}

A batch starting at 999990 with 20 pages runs from ABC-0999990 to ABC-1000009: seven digits on all 20 pages.

The start number (1 to 9999999) accepts 1,353, full-width digits and leading zeros. Paste SMITH-001353 while the prefix is SMITH- and the prefix is taken off, but only after the input fails as a plain number, so a digit prefix can't eat part of the number.

Where the number goes on someone else's page

The number sits bottom right, 22 points up, black, 8pt, shrinking to as little as 4pt on receipts and labels. An optional grey "Page x of y" goes in the middle and moves up a line if the two would come within 6 points.

"Bottom right" means as displayed. Other people's PDFs carry /Rotate and CropBoxes that differ from the MediaBox, so the visible area is the CropBox clipped to the MediaBox, and every point is mapped from displayed coordinates into unrotated page space, with the angle the text needs:

export function displayedPoint(width: number, height: number, rotation: number, across: number, up: number): FooterPlacement {
  const turn = ((rotation % 360) + 360) % 360;
  if (turn === 90) return { x: width - up, y: across, rotate: 90 };
  if (turn === 180) return { x: width - across, y: height - up, rotate: 180 };
  if (turn === 270) return { x: up, y: height - across, rotate: 270 };
  return { x: across, y: up, rotate: 0 };
}

The tests run this over portrait, landscape, all three rotations, crop boxes inside and sticking out of the sheet, MediaBoxes off the origin, scans and a 226×152 label, checking that the number reads upright at the bottom right.

Don't cover anything: shrink the content

The obvious approach is a white box with the number on top. But an attached PDF is someone's evidence, and a box can hide a line of it. So the tool shrinks the page content evenly, just enough to leave an empty strip at the bottom, keeping its top edge and horizontal centre:

export function makeRoomAtBottom(page: PDFPage, band: number): void {
  const box = visibleBox(page);
  const turn = page.getRotation().angle;
  const [across, down] = sideways(turn) ? [box.height, box.width] : [box.width, box.height];
  if (band <= 0 || band >= down) return;
  const factor = (down - band) / down;
  const fixed = displayedPoint(box.width, box.height, turn, across / 2, down);
  const move: Move = { factor, shift: { x: (1 - factor) * (box.x + fixed.x), y: (1 - factor) * (box.y + fixed.y) } };
  moveContent(page, move, box);
  moveAnnotations(page, move);
}

moveContent wraps the existing streams in q … cm … Q and clips to the visible box, so what the CropBox hid (the black edge of a scan) stays hidden. moveAnnotations applies the same transform to link Rect and QuadPoints.

The nasty detail: real content streams don't always balance their graphics state. An extra q leaves the wrapper open, so the number lands inside the shrink; an extra Q closes it early. So the content is counted first, extra qs are opened for stray Qs to close, and stray qs are closed before the wrapper's own Q.

Pages the tool rendered itself already have a wide enough bottom margin, so only copied PDF pages are shrunk.

Read the numbers back before the download

Computing the right numbers isn't the same as writing them. After stamping, the tool loads the bytes it's about to hand you and reads every page's number. The stamp is drawn last, so the check takes the last <hex> Tj in the last content stream, trusted only if the streams balance their q/Q:

function lastShownText(page: PDFPage): string | null {
  const streams = contentStreamBytes(page);
  const last = streams?.at(-1);
  if (!streams || !last || !isBalanced(streams.slice(0, -1)) || !isBalanced([last])) return null;
  const shown = [...new TextDecoder('latin1').decode(last).matchAll(SHOWN_TEXT)].at(-1);
  return shown ? fromHex(shown[1]) : null;
}

Each page is compared with its expected number, counting across all output files. One wrong page fails the export with the page and its source file named, and nothing is downloaded. Tests cover a repeat, a gap and missing pages.

A file that can't be numbered (encrypted, unreadable, empty, an undecodable page) is listed with the reason and skipped. Files are also rechecked just before numbering, so one that changed after you added it can't shift everyone else's numbers.

Emails and their attachments in one sequence

The merged email export sorts oldest first; undated emails go last, in the order they were opened:

export function sortByDate(emails: readonly ParsedEmail[]): ParsedEmail[] {
  const time = (email: ParsedEmail) => email.date?.getTime() ?? Number.POSITIVE_INFINITY;
  return emails
    .map((email, index) => ({ email, index }))
    .sort((a, b) => time(a.email) - time(b.email) || a.index - b.index)
    .map(({ email }) => email);
}

Each email's PDF and image attachments become pages right after it (GIF, WebP and BMP via a canvas); other types are only named. A contents page goes in front, and one stamp numbers the whole document, so an email and its attachment run on without a break. A CSV lists begin and end numbers per email and attachment, with formula-looking cells escaped.

Remembering where you stopped

Productions come in batches. After a numbered export, nextStart = start + pages is saved to localStorage and offered as a "Start the next batch at N" button:

private offerNextBatch(range: BatesRange | null): void {
  if (!range || range.nextStart > BATES_START_MAX) return;
  this.nextStart = range.nextStart;
  this.startBoxAtExport = this.ui.batesStart.value;
  saveNumbering({ start: String(range.nextStart) });
  this.syncNextBatch();
}

Only the prefix, start number and a few checkbox choices are saved, never file content, and each is type-checked on read. Blocked or broken storage just means the page forgets on reload. The start box only changes if you haven't edited it since the export.

It all stays in the tab

Files are read with File.arrayBuffer(), pdf-lib loads when the first PDF is dropped, and the result leaves through a Blob URL. No server step.

Stamping your own PDFs is free for everyone. Numbering emails together with their attachments in one step, sorted by date, is part of the paid Case Pass and Legal plans.

Summary

Fix the digit width once per batch, so numbers sort as text.
Place text in displayed coordinates. Rotation and CropBox are normal in other people's PDFs.
Shrink the content to make room instead of covering it, and move the link annotations with it.
Count q/Q before you wrap someone else's content stream.
Read the numbers back from the final bytes before you let anyone download them.

If you need to number a set of PDFs without installing anything, the tool is at emltopdf.net/bates-numbering.

This post was written with AI assistance.

What's inside a .pkpass file, and how to render one in the browser

Silkline — Mon, 19 Oct 2026 13:00:00 +0000

A .pkpass file is an Apple Wallet pass: a boarding pass, a concert ticket, a gym card. On an iPhone it opens straight into Wallet. On Windows or Android it is an attachment nothing wants to open.

I recently built a small viewer that opens these files in the browser without uploading them. Most of the work was understanding the format, so here is what's inside a pass and how each part can be read.

It's a ZIP file

Rename a .pkpass to .zip and you can open it. Inside you'll find:

pass.json: the content of the pass, including the barcode data
images such as icon.png and logo.png, often with @2x and @3x versions
optional en.lproj/, de.lproj/ folders with a pass.strings file each
manifest.json and signature

The file comes from a stranger, so unzipping is the first place to be careful. I use fflate, check the ZIP magic bytes, and count uncompressed sizes in the filter callback, which runs before an entry is inflated:

export function readZip(bytes: Uint8Array, budget = new UnpackBudget()): Unzipped {
  if (bytes.byteLength > MAX_INPUT_BYTES) throw new PkpassError('too-large');
  if (!hasZipSignature(bytes)) throw new PkpassError('not-zip');
  return unzipSync(bytes, {
    filter: (entry) => {
      if (isSkippedEntry(entry.name)) return false; // directories, __MACOSX/, .DS_Store
      if (entry.originalSize > MAX_ENTRY_BYTES) throw new PkpassError('unpacked-too-large');
      budget.spend(entry.originalSize);
      return true;
    },
  });
}

One detail that's easy to miss: fflate returns files as a plain object keyed by entry name. An entry named __proto__ would collide with the prototype, so those names are skipped and every lookup uses Object.hasOwn.

pass.json: style and fields

A pass has one style, and the style is a top-level key, not a type field:

export const PASS_STYLES = ['boardingPass', 'eventTicket', 'coupon', 'storeCard', 'generic'] as const;

function detectStyle(json: JsonObject): PassStyle {
  const style = PASS_STYLES.find((name) => isObject(json[name]));
  if (!style) throw new PkpassError('not-a-pass');
  return style;
}

Inside it are five field lists: headerFields, primaryFields, secondaryFields, auxiliaryFields and backFields. Values need formatting. A date with dateStyle: "PKDateStyleShort" maps onto Intl.DateTimeFormat's dateStyle. ignoresTimeZone: true means "show the wall-clock time as written", so I strip the offset and format in UTC. Numbers with a currencyCode go to Intl.NumberFormat. attributedValue can hold HTML links; I reduce it to plain text, and every string from the pass reaches the page through textContent.

Localization: .lproj and .strings

Translations live in <language>.lproj/pass.strings, an old Apple format of "key" = "value"; pairs. Apple's docs say non-ASCII .strings files use UTF-16, so check for a byte-order mark before decoding:

export function decodeStringsFile(bytes: Uint8Array): string {
  if (startsWith(bytes, UTF16_LE_BOM)) return new TextDecoder('utf-16le').decode(bytes.subarray(2));
  if (startsWith(bytes, UTF16_BE_BOM)) return new TextDecoder('utf-16be').decode(bytes.subarray(2));
  return decodeUtf8(bytes);
}

You also need a rule for picking one language. Mine is en, then any en-*, then the first folder alphabetically. A missing key falls back to the untranslated text, and the parser keeps every pair it read before a syntax error.

Images and @2x / @3x

There are six image roles: logo, icon, strip, thumbnail, background and footer, each at up to three scales. Apple says an image should live either at the top level or inside a .lproj folder, never both. Some passes break that rule anyway, so the viewer picks one predictable order and checks the top level first:

const IMAGE_SCALES = ['@2x', '@3x', ''];

function findImage(files: Unzipped, name: PassImageName, language?: string): Uint8Array | undefined {
  const folders = language ? ['', `${language}.lproj/`] : [''];
  for (const folder of folders) {
    for (const scale of IMAGE_SCALES) {
      const bytes = getFile(files, `${folder}${name}${scale}.png`);
      if (bytes) return bytes;
    }
  }
  return undefined;
}

Before an image reaches the browser, I read its width and height from the PNG's IHDR chunk without decoding it. Non-PNGs, files over 5 MB and anything over 2000×2000 pixels are skipped, so a crafted image can't make the tab allocate a huge bitmap.

manifest.json and signature

manifest.json maps every file in the pass to its SHA-1 hash, and signature is a PKCS #7 detached signature of the manifest, made with the issuer's certificate. That's why you can't edit a pass: change one byte and the hashes no longer match what was signed.

My viewer doesn't read either file. It draws what pass.json says. That keeps it simple, but any tool like this should say the consequence plainly: a pass that renders fine is not proof that it's genuine or that Wallet will accept it.

Barcodes

The barcode lives in barcodes, an array of { format, message, messageEncoding, altText }. Wallet uses the first one it can display; older passes use a single barcode object. So I take the first supported entry of barcodes, then fall back to barcode. All eight formats map onto bwip-js:

export const BARCODE_SYMBOLOGIES = {
  PKBarcodeFormatQR: 'qrcode',
  PKBarcodeFormatPDF417: 'pdf417',
  PKBarcodeFormatAztec: 'azteccode',
  PKBarcodeFormatCode128: 'code128',
  PKBarcodeFormatCode39: 'code39',
  PKBarcodeFormatCodabar: 'rationalizedCodabar',
  PKBarcodeFormatEAN13: 'ean13',
  PKBarcodeFormatI2of5: 'interleaved2of5',
} as const;

The eight encoders are imported by name from bwip-js/browser, so the bundler can drop the rest, and loaded with import() on first use.

messageEncoding matters for non-ASCII text. bwip-js turns text into UTF-8 unless binarytext: true is set, in which case each character is one byte, which is ISO-8859-1. So: ISO-8859-1 messages that fit in Latin-1 go in as single bytes, everything else as plain UTF-8 with no ECI header, since older gate scanners may not understand one.

For the gate there's a full-screen view. It re-encodes the barcode at the largest whole number of device pixels per module that fits, so module edges stay sharp, and asks for a screen wake lock so the phone doesn't dim in the queue.

.pkpasses bundles

A .pkpasses file is a ZIP of .pkpass files, so opening one is the same function with one more branch:

export function openPassFile(bytes: Uint8Array): OpenResult {
  const budget = new UnpackBudget();
  const files = readZip(bytes, budget);
  if (getFile(files, PASS_JSON)) return { kind: 'pass', pass: parsePassArchive(files) };
  const items = readBundle(files, budget);
  if (items.length > 0) return { kind: 'bundle', items };
  throw new PkpassError('missing-pass-json');
}

The same budget covers the outer ZIP and every pass inside, so nesting can't get around the size limit. A broken pass becomes an error entry instead of failing the bundle.

Summary

A .pkpass is a ZIP. Check sizes before inflating and look files up with Object.hasOwn.
The style is whichever of five top-level keys exists. Field values need Intl formatting.
.strings files may be UTF-16 with a BOM. Fall back to the untranslated text.
An image belongs at the top level or in a .lproj folder, not both; pick a fixed lookup order for passes that break the rule. Read PNG dimensions before decoding.
manifest.json and signature protect the pass from edits. If you don't verify them, say so.
bwip-js covers all eight PassKit formats, and messageEncoding maps onto binarytext.

If you need to look at a pass on a computer or an Android phone, the viewer is free at pkpassviewer.com, and the file never leaves your browser.

11 scrapers for Chinese platforms in 8 days, and my first $4

Silkline — Wed, 14 Oct 2026 00:09:59 +0000

Disclosure: I build and sell the Actors mentioned here (Silkline on Apify). Most of the code was written with an AI coding agent; the product calls, pricing and checks were mine. Numbers are from my Apify console on October 12, 2026.

On October 5 I published three scrapers on the Apify Store: Bilibili, Weibo and Xiaohongshu (RedNote). Five days later there were eleven. On day 8 someone I've never met paid for the RedNote one.

Revenue so far: $4.10. Platform cost: $0.01.

That's not a business yet. But it answers the only question I cared about in week one: will anyone pay for this? Here's what got me there and what I'd tell anyone thinking about selling Actors.

Why Chinese platforms

I scanned the whole Apify Store (about 12,000 Actors) and looked at monthly users per platform. Chinese platforms stood out: real demand, few maintained tools, and a language barrier that keeps most builders away. RedNote, Douyin, Bilibili, Weibo and WeChat are where Chinese consumers review products, follow creators and argue about brands. Marketers and researchers outside China want that data and can't easily read the sites.

I don't run my own crawlers. The data comes from a commercial data API whose terms let me resell it, and I got that permission in writing before going public. The Actors turn it into clean, documented JSON with pricing per result.

The lineup today:

Xiaohongshu / RedNote: notes, comments, creator profiles
Douyin: videos, comments, hot search
Bilibili: videos, comments, danmaku, subtitles
Weibo: posts, comments, hot search
WeChat Official Accounts: articles, read counts, Channels video search
TikTok Shop, TikTok, YouTube, Reddit, Threads, Telegram

Lesson 1: "published" is not "found"

For the first few days the store search didn't show my Actors at all for their own platform names, and I assumed that was normal for new listings. It wasn't. They were listed but ranked far below the first page.

What actually moves ranking on Apify is the Actor quality score. The base items are mostly boring work: a README with real examples, an input schema with defaults that work, a dataset schema, an icon, and example tasks. I published 46 example tasks across the 11 Actors. Six Actors now sit at a quality score of 81, which seems to be about the ceiling before real users, bookmarks and reviews count.

Result after a week: the WeChat Actor went from roughly #46 to #30 for "wechat". Most of the others are still outside the top 100. Ranking is the main bottleneck, not code.

Lesson 2: compete on fields, not price

My first instinct was to undercut. I didn't. Pricing sits in the same range as the established Actors, and the difference is in the output.

The clearest example: for every commenter, author and reviewer, the Actors return the public profile fields the platform already shows: user ID, avatar, IP location (Chinese platforms display "IP属地" next to every comment), gender and verification. I made that the headline of every listing instead of a footnote. For anyone doing audience or regional analysis, it's often the column that matters most.

Lesson 3: price per result, charge only on success

All 11 Actors are pay-per-event:

a small run start fee, charged only after the first page of data actually arrives,
a per-result fee (a RedNote search result is $0.005),
and a hard cost cap per run, so a bad input can't burn money on either side.

If the upstream fails at the very start, the user pays nothing and the run is marked failed. It's more code than a flat price, but it means a user's first run can't go badly for them.

Lesson 4: your first paying user will find your bugs

The day the first payment showed up, my own daily self-check flagged the RedNote search mode: some results had an empty title.

The cause: many RedNote posts simply have no separate title, only body text. The API returned an empty title and I passed it through. Technically correct, practically useless in a spreadsheet. The fix was to fall back to the first line of the body (up to 50 characters), keep the full text in description, and ship a new build the same afternoon. A live run on 20 coffee posts came back with zero empty titles.

Lesson: run your own Actor on boring real queries every day, not just your test fixtures.

Lesson 5: memory is your margin

Apify charges the developer for compute on paid users' runs, out of your share. I launched everything at 4096 MB. Measured peak usage was about 100 MB. Dropping all 11 to 512 MB cut compute per run to roughly an eighth. On pay-per-result pricing, that's the difference between a margin and a loss.

The stack

Python, one shared client package vendored into each Actor at build time
Tests built on real recorded responses, so schema drift shows up as a failing test
A daily report script: users, runs, failures, store rank per keyword, upstream balance and now revenue
One person deciding, one AI agent writing most of the code and running the checks

What's next

Taobao/Tmall product data (waiting on a data provider)
A Product Hunt launch this week
Weekly progress posts here and on X (@silklinedata)

If you need data from Chinese platforms, the RedNote Actor that made the first sale is here: Xiaohongshu (RedNote) Scraper. If you're building Actors yourself, ask me anything about the quality score or pay-per-event pricing in the comments.

Previewing untrusted .eml files in the browser: sandboxed iframe, CSP and blocked remote images

Silkline — Mon, 12 Oct 2026 13:15:39 +0000

An .eml file is a saved email. Open one and you get raw MIME: headers, a plain-text part, an HTML part, maybe some base64 attachments. The HTML part is the interesting one, because it was written by whoever sent the email. It can contain scripts, forms, tracking pixels, CSS that pulls images from a server, and links that try to take over the page.

I recently built a small tool that previews .eml and Outlook .msg files in the browser and turns them into PDFs, without uploading anything. The preview was the part that needed the most care. If you just parse the email and drop its HTML into your page with innerHTML, you are running a stranger's markup inside your own origin.

Here is the setup I ended up with. It is three locks, each covering what the previous one might miss.

Lock 1: sanitize the HTML before it goes anywhere

The first step is DOMPurify. On top of its defaults I forbid a list of tags that have no business in an email preview:

const FORBIDDEN_TAGS = [
  'svg', 'math', 'form', 'input', 'button', 'select', 'textarea', 'option', 'iframe', 'frame', 'frameset',
  'object', 'embed', 'applet', 'link', 'meta', 'base', 'video', 'audio', 'source', 'track', 'picture', 'canvas', 'dialog',
];
const FORBIDDEN_ATTRIBUTES = ['srcset', 'formaction', 'ping', 'autofocus', 'poster'];

meta and base matter more than they look: a <meta http-equiv="refresh"> can redirect, and a <base href> changes where every relative link points.

Two hooks do the email-specific work:

Images. cid: references (images embedded in the email itself) are resolved to data URLs from the attachments. Any http(s):// image is replaced with a small grey placeholder, and the count is shown to the user with a "Load remote images" button. Remote images are how senders know you opened the mail, so they stay off until you ask.
Links. Every <a href> gets target="_blank" and rel="noopener noreferrer nofollow", so a click opens a new tab and the email can't reach back into the page that opened it.

Inline style attributes and <style> blocks get their url(https://...) values and @import rules stripped while remote images are blocked. That is the part where sanitizing alone starts to feel shaky: CSS is a whole language, and a regex over it is a best effort, not a guarantee.

Lock 2: render it in a sandboxed iframe

The cleaned HTML never touches the main document. It goes into an iframe through srcdoc:

const frame = document.createElement('iframe');
frame.setAttribute('sandbox', 'allow-same-origin allow-popups allow-popups-to-escape-sandbox');
frame.setAttribute('referrerpolicy', 'no-referrer');
frame.srcdoc = frameDocument(cleanHtml, loadRemoteImages);

What matters is what is not in that sandbox list: no allow-scripts, no allow-forms, no allow-top-navigation, no allow-modals. Even if something slipped past DOMPurify, it could not run a script, submit a form or navigate the tab. The popup flags are there only so a link the reader clicks can open in a normal new tab.

Lock 3: a CSP inside the iframe

The document written into srcdoc carries its own Content Security Policy:

function policy(loadRemoteImages: boolean): string {
  const images = loadRemoteImages ? 'img-src data: blob: https:' : 'img-src data: blob:';
  return `default-src 'none'; ${images}; style-src 'unsafe-inline'`;
}

default-src 'none' means the frame can't fetch anything except what is listed. With remote images blocked, only data: and blob: images load, so a background image hidden in CSS that the sanitizer missed still goes nowhere. This is the lock that makes the CSS regex in Lock 1 a convenience rather than the last line of defence. The parent page has its own CSP as well (script-src 'self'), so there are two policies between the email and the network.

The trade-off: a preview that grows with the email

The first version of the preview was a fixed-height box. Short emails sat at the top of a big empty frame, which looked broken. Making the iframe fit its content means the parent page has to read the height of the document inside it, and you can't read a sandboxed frame's document unless the sandbox includes allow-same-origin.

allow-same-origin sounds alarming, and combined with allow-scripts it is: a script inside the frame could then remove its own sandbox. Without allow-scripts, though, nothing inside the frame can execute, so being same-origin gives the email no new powers. It only lets my page measure it:

const fit = (): void => {
  frame.style.height = '0px'; // shrink first: scrollHeight never reports less than the frame's own height
  frame.style.height = `${Math.min(doc.documentElement.scrollHeight + 2, FRAME_MAX_HEIGHT)}px`;
};

Long emails stop at a maximum height and scroll inside the frame. The height is recalculated when images inside the email finish loading and when the card changes width.

The risk with this kind of setup is not today's code. It's someone, possibly me in six months, adding allow-scripts to fix an unrelated bug. So there is a test that reads the source and fails if the sandbox ever includes a dangerous flag:

it('never allows scripts, forms or top navigation', () => {
  for (const value of values) {
    for (const flag of ['allow-scripts', 'allow-forms', 'allow-top-navigation', 'allow-modals']) {
      expect(value.split(/\s+/)).not.toContain(flag);
    }
  }
});

It is a blunt test, and that is the point. The comment next to the sandbox line explains why allow-same-origin is there, and the test makes sure the reason stays true.

Parsing happens in the browser too

None of this would matter much if the file went to a server first. Parsing is done client-side: postal-mime for .eml, @kenjiuno/msgreader for Outlook .msg files, and pdfmake to build the PDF. You can check it the usual way: open the Network tab in DevTools, pick a file, and watch that no request carries it anywhere.

Summary

Sanitize with DOMPurify, forbid the tags an email doesn't need, rewrite images and links in hooks.
Render in a srcdoc iframe with a sandbox that has no allow-scripts.
Put a default-src 'none' CSP inside the frame, so anything the sanitizer misses still can't load.
If you add allow-same-origin to size the frame, write a test that keeps allow-scripts out.

I wrapped all of this into a free tool at emltopdf.net, if you ever need to open an .eml file without installing a mail client.

How to get Xiaohongshu (RedNote) data in Python

Silkline — Tue, 06 Oct 2026 06:51:13 +0000

Disclosure: I built the Xiaohongshu Scraper used in this tutorial. It's a paid Actor on Apify (pay per result), and the pricing is listed at the end.

Xiaohongshu (小红书), known abroad as RedNote, is where Chinese consumers go to decide what to buy. People post reviews, "what I bought" hauls, travel guides and café lists, and other people save those notes to come back to later. For brand research, product research or a Chinese-language NLP dataset, that's very valuable data.

It's also hard to get. The site is in Chinese, logged-out web access is restricted, requests are signed, and there's no public API. This tutorial skips all of that and gets Xiaohongshu data into Python in about 20 lines.

What you'll build

A short script that:

searches Xiaohongshu for a keyword,
loads the results into a pandas DataFrame,
ranks notes by saves (collects),
pulls the public comments of the top note.

Setup

You need Python 3.10+ and an Apify account. Copy your API token from Console → Settings → API & Integrations.

pip install apify-client pandas
export APIFY_TOKEN="your-token-here"

Step 1: search notes by keyword

The Actor has four modes: search, note, comments and user. We start with search.

One tip before you write any code: search in Chinese. "coffee" and "咖啡" return very different results, and the Chinese keyword is what real users type.

import os
from decimal import Decimal
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
actor = client.actor("clover_folktale/xiaohongshu-scraper")

run = actor.call(
    run_input={
        "mode": "search",
        "keyword": "咖啡",      # "coffee"
        "maxResults": 40,
    },
    max_total_charge_usd=Decimal("0.50"),  # hard spending cap for this run
)

items = list(client.dataset(run.default_dataset_id).iterate_items())
print(len(items), "notes")

maxResults is the total number of items for the whole run, and pagination is handled for you. max_total_charge_usd is a safety net: the run stops once that amount is spent.

This uses apify-client 3.x, where call() returns a Run object. On 1.x/2.x, use run["defaultDatasetId"] instead of run.default_dataset_id.

Each item is a flat dict. A search result looks like this (values illustrative):

{
  "type": "note",
  "noteId": "6aa72fd3000000002802c3f4",
  "url": "https://www.xiaohongshu.com/explore/6aa72fd3000000002802c3f4",
  "noteType": "image",
  "title": "Example title",
  "description": "Example description",
  "authorName": "ExampleCreator",
  "authorId": "63ebbadf00000000260055d5",
  "authorUrl": "https://www.xiaohongshu.com/user/profile/63ebbadf00000000260055d5",
  "publishedAt": "2026-09-14T10:00:51Z",
  "likes": 1658,
  "collects": 527,
  "comments": 131,
  "shares": 306,
  "coverUrl": "https://example.com/cover.webp",
  "imageCount": 9,
  "durationSeconds": null,
  "hashtags": []
}

Missing fields are null. durationSeconds is filled for video notes in search results. hashtags is filled only in note details (mode note), so it's an empty list here.

Step 2: rank by saves

Likes on Xiaohongshu are cheap. Collects (saves) mean someone plans to come back to the note, which usually makes it a guide, list or review. The save-to-like ratio is a quick way to find "useful" content.

import pandas as pd

df = pd.DataFrame(items)
df["save_ratio"] = df["collects"] / df["likes"].where(df["likes"] > 0)

top = df.sort_values("collects", ascending=False)[
    ["title", "authorName", "likes", "collects", "comments", "save_ratio", "url"]
].head(10)
print(top.to_string(index=False))

From here you can write df.to_csv("xhs_coffee.csv", index=False) and hand it to a marketing team, or keep going.

Step 3: read the comments of the top note

Comments are where the product feedback is. Pass note URLs or 24-character note IDs to mode comments:

top_note = top.iloc[0]["url"]

run = actor.call(
    run_input={"mode": "comments", "notes": [top_note], "maxResults": 100},
    max_total_charge_usd=Decimal("0.50"),
)
comments = list(client.dataset(run.default_dataset_id).iterate_items())

for c in comments[:5]:
    print(c["likes"], c["text"])

A comment item:

{
  "type": "comment",
  "commentId": "6a1f0c2e000000001e03a9b7",
  "noteId": "6aa72fd3000000002802c3f4",
  "text": "Example comment text",
  "likes": 42,
  "replyCount": 3,
  "publishedAt": "2026-09-15T08:12:40Z",
  "authorName": "ExampleUser"
}

Comment items include only text, likes, reply count, time and the commenter's public nickname. Commenter IDs, avatars and other personal data are never returned, which keeps your dataset simpler to store and share.

Step 4 (optional): creator profiles

To vet an influencer, use mode user with profile links or user IDs. You get one profile record followed by that creator's recent notes:

run = actor.call(
    run_input={
        "mode": "user",
        "users": ["https://www.xiaohongshu.com/user/profile/63ebbadf00000000260055d5"],
        "maxResults": 30,
    },
    max_total_charge_usd=Decimal("0.50"),
)
records = list(client.dataset(run.default_dataset_id).iterate_items())
profile = next(r for r in records if r["type"] == "user")
notes = [r for r in records if r["type"] == "note"]
print(profile["nickname"], profile["followers"], profile["likesReceived"], len(notes))

The profile record has userId, url, nickname, bio, followers, following, noteCount, likesReceived and verified.

To get the full record of a single note (including hashtags), use mode note:

actor.call(run_input={"mode": "note", "notes": ["6aa72fd3000000002802c3f4"]})

xhslink.com share links work too, so you can paste links straight from the app.

What it costs

The Actor is pay-per-event:

Event	Price
Run start	$0.01 per run
Note from a list (search, creator notes) or a comment	$5 per 1,000
Note detail (mode `note`)	$20 per 1,000
Creator profile	$20 per 1,000

Check the store page for the current price on your plan. Search results are the cheapest way to collect notes. Use note mode only when you need the full record, such as hashtags.

Going further

Schedule it. Create a saved task with your keyword and run it daily from the Apify Console to track a trend over time.
No-code exports. Every run's dataset downloads as JSON, CSV or Excel, and it connects to Google Sheets, Zapier and Make.
AI agents. The Actor is available through the Apify MCP server, so an agent can call it directly.
Other platforms. The same approach works for Weibo (including the trending list) and Bilibili.

The data is public content only. You are responsible for using it in line with applicable laws and Xiaohongshu's terms.

If a field you need is missing, open an issue on the Actor page. I read them.