DEV Community: Peter Hallander

Validate Poland's e-invoices offline against the official XSD, then make your validator fail on purpose

Peter Hallander — Tue, 22 Sep 2026 07:02:34 +0000

Since 2026, invoices between Polish businesses are XML documents. They go to the national e-invoicing system, KSeF, in a schema called FA(3). The last exemptions end on 1 January 2027. Once KSeF accepts an invoice, you cannot edit it or withdraw it. The only fix is a correcting invoice, filed after the fact.

So when I changed the XML builder to add three new blocks to every invoice (a third party, a payment section with bank accounts, and a footer), I wanted proof that the documents were still valid before any of them reached the real system.

There are two ways to get that proof.

The slow way: the government sandbox

KSeF has a demo environment. To use it you log in through the national ID service, generate a token, open a session and send your documents. In my setup the demo token has to be regenerated every day. When something is wrong, you get an error code and a sentence in Polish, and then you fix one thing and send again.

It is the final word on whether an invoice is accepted. It is also far too slow to run every time you touch the builder.

The fast way: the XSD

The Ministry of Finance publishes the FA(3) schema as an ordinary XSD file on crd.gov.pl. It is 180 KB, it declares 331 elements, and it imports a shared type library, which imports one more. Python's lxml compiles all three without any special setup:

import glob, os, sys, urllib.request
from lxml import etree

XSD_URL = "https://crd.gov.pl/wzor/2025/06/25/13775/schemat.xsd"
XSD = "tmp/fa3/schemat.xsd"
if not os.path.exists(XSD):
    urllib.request.urlretrieve(XSD_URL, XSD)

schema = etree.XMLSchema(etree.parse(XSD))
bad = 0
for f in sorted(glob.glob("tmp/fa3/*.xml")):
    ok = schema.validate(etree.parse(f))
    print("VALID  " if ok else "INVALID", os.path.basename(f))
    if not ok:
        bad += 1
        for e in list(schema.error_log)[:4]:
            print("     line", e.line, "-", e.message)
sys.exit(1 if bad else 0)

Four documents, including fetching the two imported files, take about 1.3 seconds. No token, no login, no network round trip per invoice.

Validate what your code produces, not what you typed

The obvious move is to write a sample XML by hand and validate it. That proves you can write a valid invoice. It says nothing about your builder.

So the samples come from the real serializer. A small script calls the same function the application uses and writes the output to disk:

const samples = {
  "a-baseline":    { ...base, invoiceNumber: "TEST/A/1" },
  "b-wdt-factor":  { ...base, currency: "EUR", vatRate: "0 WDT", payment: factor },
  "c-own-account": { ...base, payment: { bankAccounts: [ownAccount] } },
  "d-footer-only": { ...base, payment: { footer: "Kapitał zakładowy: 50 000 PLN" } },
};
for (const [name, data] of Object.entries(samples))
  fs.writeFileSync(`tmp/fa3/${name}.xml`, buildFa3Xml(data));

Each sample covers one new path: nothing configured, everything at once (a foreign buyer in euros with two factor accounts and a footer), own bank account only, footer only. The baseline matters as much as the others. A change that adds optional blocks must not change the document when they are empty.

Why the order is the whole problem

FA(3) is built from xsd:sequence, so the order of elements is part of the contract. The root looks like this:

Faktura
  Naglowek
  Podmiot1              seller
  Podmiot2              buyer
  Podmiot3        0-100 third parties (factor, recipient, ...)
  PodmiotUpowazniony 0-1
  Fa                    the invoice itself; Platnosc sits inside it, after the rows
  Stopka          0-1   footer
  Zalacznik       0-1

My three new blocks land in three different places: one between the buyer and the invoice body, one deep inside the body after the line items, one after the body. An XML builder that emits them in a slightly different place produces a document that looks perfectly reasonable and is invalid.

The schema also knows things that no summary in the documentation mentions. A factor may have at most 20 bank accounts. An account number is any string of 10 to 34 characters. The third party's role is a number from a closed list, where 1 means "factor". When I read these rules in the XSD instead of in a PDF guide, I found them faster and trusted them more.

All four passed. That was the moment to worry.

Every sample was valid on the first run.

A validator that has never said no has not been tested. Maybe the schema failed to load its imports and validated nothing. Maybe the glob matched an empty folder. Maybe I validated yesterday's files. A green result from any of those looks exactly like a real one.

So I broke a document on purpose. I took the most complex sample and moved the Podmiot3 block from before Fa to after it. Same content, wrong place:

INVALID z-control.xml
     line 80 - Element '{http://crd.gov.pl/wzor/2025/06/25/13775/}Podmiot3':
     This element is not expected. Expected is one of (
     {http://crd.gov.pl/wzor/2025/06/25/13775/}Stopka,
     {http://crd.gov.pl/wzor/2025/06/25/13775/}Zalacznik ).

Now the four green results mean something. The message is also more precise than a rejection code: it names the line, the element, and the elements that would be allowed there.

If you keep one habit from this post, keep that one. Every validator, linter or test gate you add needs one input that must fail, run at least once, on purpose.

What the schema cannot tell you

The XSD checks structure: order, types, lengths, allowed values. It does not check meaning.

The NIP, the Polish tax number, is a good example. Its type in the shared library is a regular expression:

[1-9]((\d[1-9])|([1-9]\d))\d{7}

1234567890 matches it. Its checksum is wrong, so it cannot be anyone's tax number, and the schema will not notice. The same goes for arithmetic: the schema cannot see whether the line totals add up to the invoice total.

KSeF checks meaning on submission, and rejects with its own errors, for example code 450, "Błąd weryfikacji semantyki dokumentu faktury" (semantic verification failed). So the offline check is the fast first gate, not the last one. One real submission through the sandbox is still the final check. The difference is that it becomes one submission to confirm, not twenty to debug.

The setup, in short

Download the XSD once and keep it next to your tests. It pulls two more files from crd.gov.pl on compile; cache them too if your CI has no network.
Generate samples with your real builder, one per code path, plus a baseline.
Keep one sample that must fail, and look at it fail.
Treat a pass as "structurally valid", never as "accepted".

I build FakturaFlow, which sends invoices to KSeF in bulk. If you need the field-by-field map of FA(3) in Polish, which is the language the people filing these invoices work in, I keep one here: FA(3) schema guide.

wp_kses deletes tags you forgot to allow, and tells you nothing

Peter Hallander — Fri, 11 Sep 2026 06:26:25 +0000

I shipped a WordPress plugin last week whose only job is to reproduce a specific, legally prescribed document on a product page. Exact colours, exact layout, nothing editable.

It went live rendering as unstyled text.

The CSS file was correct. The markup was correct. php -l passed on every file, the official Plugin Check tool reported no errors, and reading the diff told me nothing. The bug was wp_kses, and the reason it took me an hour is that wp_kses does not fail in a way you can see.

What actually happens

wp_kses( $html, $allowed ) filters HTML against an allow-list. Everyone knows that. What is easy to miss is what it does with a tag that is not on the list.

It does not remove the element. It removes the tag and keeps the children.

wp_kses(
    '<section class="card"><p>Still here</p></section>',
    [ 'p' => [ 'class' => true ] ]
);

// => '<p>Still here</p>'

The <section> is gone. The paragraph survived. No notice, no warning, no return value to check. Run that in wp shell and watch it happen.

That behaviour is correct and deliberate: kses is a sanitiser, and throwing away a user's text because their comment had an unexpected wrapper would be much worse. But when you point kses at your own markup, the failure mode inverts. You do not lose content. You lose structure, and structure is where all your CSS hooks live.

How it looked in practice

My notice is built like this:

<section class="sbgn" role="note">
    <header class="sbgn__head">
        <span class="sbgn__emblem"></span>
        <h2 class="sbgn__title">LEGAL GUARANTEE</h2>
    </header>
    <div class="sbgn__body">
        ...
    </div>
</section>

and echoed like this:

echo wp_kses( self::markup(), SBGN_Kses::notice() );

My allow-list had div, p, span, ul, li, h1–h3, strong, b, aside, figure, figcaption, br and a.

No section. No header. No ol.

So on every product page the browser received this:

<span class="sbgn__emblem"></span>
<h2 class="sbgn__title">LEGAL GUARANTEE</h2>
<div class="sbgn__body">
    ...
</div>

The root .sbgn element carried the border, the background and the CSS custom properties everything else referenced. .sbgn__head carried the coloured header bar. Both were deleted, so:

every var(--brand) resolved to nothing, because the custom properties were declared on .sbgn
the header bar vanished entirely
<ol> was stripped too, so numbered steps quietly became bullets

The page still looked populated. All the text was there, in roughly the right order. It just had none of the design, which for this particular plugin is the entire product.

Why nothing caught it

This is the part worth internalising.

php -l passes. The PHP is valid. It always was.
Plugin Check passes. It reads the source, and the source is correct.
The CSS is served and parses. I fetched the stylesheet URL directly: HTTP 200, right content, braces balanced. I wasted time on that.
The class names match. Grepping the rendered page for class="sbgn returned sbgn__body, sbgn__title, sbgn-qr and friends. They were all present, which made it look like the CSS simply was not applying.

The tell, when I finally saw it, was an absence: class="sbgn" and class="sbgn__head" were the only two selectors in my stylesheet with no counterpart in the DOM. A missing string is much harder to notice than a wrong one.

# the check that actually found it
curl -s "$URL" | grep -o 'class="sbgn[^"]*"' | sort -u

Everything my stylesheet defined, minus the two that mattered.

The fix, and the guard

The fix is obvious once you know. List every tag you emit:

$html = array(
    'div'     => $attr,
    'section' => $attr,   // added
    'header'  => $attr,   // added
    'footer'  => $attr,   // added
    'p'       => $attr,
    'ul'      => $attr,
    'ol'      => $attr,   // added
    'li'      => $attr,
    // ...
);

Attributes are silently dropped the same way, which is its own small trap. My notice carried role="note"; role was not in the attribute list, so the element survived while its announcement to a screen reader did not. Nothing in the visual output would ever have told me.

The guard I added is a comment pointing at a one-line command, because the allow-list and the markup live in different files and will drift:

grep -ohE "<[a-z][a-z0-9]*" includes/class-*-notice.php includes/class-*-label.php \
  | tr -d '<' | sort -u

Run that, compare against the allow-list, done. If you would rather have it fail loudly in development, wp_kses gives you no hook for that, but you can diff the two strings yourself:

$out = wp_kses( $markup, $allowed );
if ( defined( 'WP_DEBUG' ) && WP_DEBUG && $out !== $markup ) {
    trigger_error( 'kses altered plugin markup', E_USER_WARNING );
}

Crude, but it turns a silent structural edit into something you can see. For your own trusted markup, where the output should be byte-identical, any difference at all is a bug.

The general lesson

I had two correct artifacts, a correct template and a correct stylesheet, and a broken page. The defect lived in the transformation between them, and every tool I owned inspected the artifacts rather than the result.

Escaping late is the right rule and I am not arguing with it. But an allow-list is a second source of truth about your own markup, and a second source of truth drifts. Whatever you are building, the check that would have caught this in five seconds is looking at what the browser actually received.

I only found it because I screenshotted the rendered output on a real install before writing the listing. That is now a release step rather than a nice-to-have.

The plugin, for the curious, shows the EU's harmonised legal guarantee notice, which becomes mandatory for anyone selling goods to EU consumers on 27 September 2026. It renders in all 24 official EU languages, and as real text rather than the flat artwork everything else in this category ships, which is the only reason a screen reader can read it at all. Free, WooCommerce optional, and I maintain it: EU Legal Guarantee Notice and GARAN Durability Label for WooCommerce.

toISOString() put 328 invoices in the wrong tax month

Peter Hallander — Sat, 05 Sep 2026 06:28:12 +0000

A customer emailed me on 1 September. Her invoices were dated 31 August, and they should have said 1 September.

She was right. 328 of them.

One line

The invoices arrive from a billing platform by webhook. Each one carries a unix timestamp, and we turn it into a date:

const issueDate = new Date(inv.date * 1000).toISOString().slice(0, 10);

That looks like it produces a date. It produces a UTC date.

Poland runs UTC+2 in summer. The billing platform runs its subscription cycle at 00:00 Europe/Warsaw. So an invoice issued at midnight on 1 September is 2026-08-31T22:00:00Z, and toISOString() renders it as 2026-08-31.

Every invoice in that run was wrong.

Why it hid for a month

The bug only fires between midnight and 02:00 local time. Every invoice issued during the working day converts correctly, because the UTC date and the Warsaw date are the same date.

The integration had been live for a month. Invoices had been arriving one or two at a time, whenever someone signed up, and every one of them was right. Then the monthly billing run went out at exactly the wrong minute, and 328 invoices landed together in the wrong month.

The failure mode was invisible until it hit at scale, at the only time of day that triggers it.

Wrong day vs wrong month

An off-by-one day on a date field is usually a cosmetic bug. This one was not, for a boring reason: 31 August and 1 September are in different VAT periods.

These invoices go to Poland's national e-invoicing system. Once an invoice is filed there it cannot be edited or withdrawn. The only remedy is issuing a correcting invoice afterwards. So the difference between "wrong day" and "wrong month" is the difference between a typo and a tax filing in the wrong period.

The 328 had not been filed yet. That was luck, not design.

Finding the wrong rows without guessing

I could have selected everything dated 31 August and moved it forward one day. That would also have moved genuinely-August invoices, because 31 August is a real date on which real invoices exist.

The tempting shortcut is to use the arrival time: if a row arrived on 1 September and is dated 31 August, fix it. That is wrong too. An invoice legitimately issued at 23:58 on 31 August, whose webhook landed at 00:01, is correctly dated and would be corrupted by the fix.

What saved me was a second, independent signal. The billing platform's own invoice numbers carry the month:

PSA-09-2026-17
     ^^ September

So the rule became: correct a row only when the invoice number says September and the row arrived on 1 September Warsaw time and the stored date is exactly one day earlier. Three facts agreeing, two of them from the source system rather than from my own inference.

That found 328 rows, zero ambiguous ones, and left the 23:58 case alone. After the fix, all 490 invoices agreed with the platform's own numbering, where 328 had not.

If you are writing a data repair script, find the second signal before you write the UPDATE. The one-signal version would have quietly broken correct rows while looking like it worked.

The fix

Intl.DateTimeFormat with an explicit time zone. The sv-SE locale is the convenient one here because its date format is already YYYY-MM-DD:

const WARSAW_YMD = new Intl.DateTimeFormat("sv-SE", {
  timeZone: "Europe/Warsaw",
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
});

export function polishDate(d) {
  return WARSAW_YMD.format(d);
}

Build the formatter once outside the function. Intl.DateTimeFormat construction is not free, and this runs per invoice.

Do not be tempted by the arithmetic version:

// Wrong six months a year
const local = new Date(ts * 1000 + 2 * 3600 * 1000).toISOString().slice(0, 10);

Poland is UTC+2 in summer and UTC+1 in winter. A hardcoded offset is correct until the last Sunday in October, then silently wrong until March. Intl reads the timezone database, so DST is handled for you.

The test that catches it

Two cases, and the second is the one that matters:

// 2026-09-01 00:00 Europe/Warsaw (22:00 UTC on 31 August)
expect(polishDate(new Date(1788213600 * 1000))).toBe("2026-09-01");

// 2026-01-01 00:00 Europe/Warsaw (23:00 UTC on 31 December), UTC+1
expect(polishDate(new Date(1767222000 * 1000))).toBe("2026-01-01");

The January case fails against a hardcoded +2. Without it, the fix looks correct for six months.

I also reverted the fix and re-ran the tests, to confirm they actually caught the original bug. A test you have never seen fail is a test you have not written yet. Mine passed on the first run before I checked, which is exactly when I should have been suspicious.

The general shape

toISOString() is a timestamp serializer. It is not a date formatter. It answers "what is this instant in UTC", and if you slice the first ten characters off it, you have asserted that UTC is the calendar your users live in.

That is fine for a log line. It is not fine when the date has meaning to somebody: a tax period, an invoice date, a delivery date, a contract term, a birthday.

Three questions worth asking about any date field in your system:

Does this date belong to a place? An issue date on a Polish invoice is a Polish calendar date, no matter where the server or the billing platform is. If the answer is yes, the timezone is part of the data, not a display concern.
What happens near midnight? Every timezone bug lives between 00:00 and the UTC offset. If your tests use midday timestamps, they will all pass.
What happens in the other season? Half the year is DST. Test in January and in July.

The customer found this one before we did. She had been sending invoices through the system for six weeks, noticed the dates were a day out, and told us the same morning. That is a good customer, and it is not a substitute for a test at midnight.

I hit this building FakturaFlow, which files invoices to Poland's e-invoicing system in bulk. That link goes to a longer write-up of what else breaks at a thousand invoices a month, in Polish, since that is who has to deal with it.

If you convert a timestamp to a date anywhere in your codebase, it is worth ten minutes with grep today:

grep -rn "toISOString().slice(0, 10)" src/

That found eight more in mine. Seven turned out to be fine: a download filename, today's date in a prompt, a test fixture. Being a day out in a filename costs nothing.

The one I am still looking at is a central bank exchange-rate lookup, because the rate published "for 1 September" is a Polish calendar date too, and asking for the wrong day returns the wrong number rather than an error.

That is the test. Not "is this UTC", but who cares what day this is, and what does it cost them if it is wrong. Most of the time, nobody. Occasionally, a tax authority.

pdf-lib throws on Ł. The obvious fix silently deletes your users' data

Peter Hallander — Sun, 30 Aug 2026 08:26:50 +0000

I generate invoices in a Node serverless function with pdf-lib. It is a good library, and to its credit it did the right thing: it threw.

Error: WinAnsi cannot encode "Ł" (0x0141)

The client was called Łódź Sp. z o.o.

I did what almost everyone does when a document generator throws in production: I stripped the character that was upsetting it. The exception stopped. The tests went green. And the invoice then said ód Sp. z o.o., on a document my user was about to send to their own customer, with nothing in the logs to suggest anything had happened.

pdf-lib is not the thing being quiet here. My fix was. That distinction took me longer to see than it should have, and it is the whole point of this post.

The standard 14 fonts are Latin-1 only

PDF has fourteen fonts every reader is guaranteed to have, so you can use them without embedding anything. pdf-lib exposes them as StandardFonts:

import { PDFDocument, StandardFonts } from 'pdf-lib'

const doc = await PDFDocument.create()
const font = await doc.embedFont(StandardFonts.Helvetica)

That is the default path in every tutorial, and it is fine until it is not. Those fonts are encoded as WinAnsi (roughly Windows-1252). Their glyph set covers Western European Latin and nothing else.

Ł and ź are not in it. I checked the boundary rather than guessing, and it is narrower than people assume:

Character	Standard font
`€` `£` `’` `–` `—`	draws fine
`ř` (Czech)	throws
`ı` (Turkish)	throws
`Москва` (Cyrillic)	throws
`株式会社` (CJK)	throws

So the euro sign and curly quotes are safe, which is the part most people worry about. Names are not, which is the part that matters.

The part that makes it dangerous is the fix, not the error

The exception above is correct and helpful. It is also loud, and loud things get silenced. So people do the obvious thing to stop the crash:

// don't do this
const safe = (s) => s.replace(/[^\x20-\xFF]/g, '')
page.drawText(safe(customerName), { x, y, size, font })

I did exactly this. It stops the exception, the code goes green, and every test passes. What it actually does is delete parts of your users' data from a document they are about to send to their own customer.

There is no error to notice. The PDF is valid. Nothing in your logs suggests anything happened. The only way to find out is to render a page with non-Latin-1 text in it and look at it with your eyes.

The fix: embed a real font

Embed a TrueType or OpenType face and the problem disappears, because you are no longer restricted to a 1990s encoding table.

import fontkit from '@pdf-lib/fontkit'
import { readFile } from 'fs/promises'
import { PDFDocument } from 'pdf-lib'

const doc = await PDFDocument.create()
doc.registerFontkit(fontkit)   // required, and easy to forget

const bytes = await readFile('assets/fonts/Archivo-Regular.ttf')
const font = await doc.embedFont(bytes, { subset: true })

page.drawText('Łódź Sp. z o.o.', { x: 40, y: 700, size: 12, font })

Three things worth knowing:

registerFontkit is mandatory. Without it embedFont on a byte array throws a message about fontkit that does not obviously connect to your problem.

subset: true matters more than you think. A full Archivo weight is about 180 KB. Embedding three weights unsubsetted adds half a megabyte to every single document. With subsetting, my four-page invoice with three weights comes out at 35 KB, because only the glyphs actually used get embedded.

Cache the file reads. In a serverless function, readFile on every invocation is wasted latency. Read once into a module-level variable and reuse it across warm invocations:

let cache = null

async function loadFonts() {
  if (cache) return cache
  const dir = path.join(process.cwd(), 'assets', 'fonts')
  const [regular, semi, black] = await Promise.all([
    readFile(path.join(dir, 'Archivo-Regular.ttf')),
    readFile(path.join(dir, 'Archivo-SemiBold.ttf')),
    readFile(path.join(dir, 'Archivo-Black.ttf')),
  ])
  cache = { regular, semi, black }
  return cache
}

Also check the licence before you vendor a font. Archivo is SIL OFL, which permits embedding; plenty of commercial faces do not.

An embedded font still is not every glyph

Embedding solves the encoding problem, not the coverage problem. Archivo has no CJK. If a user types a Japanese company name, widthOfTextAtSize throws on that character and you are back where you started, just further along.

So keep a fallback, but make it visible rather than silent:

function drawable(font, s) {
  let out = ''
  for (const ch of s) {
    try {
      font.widthOfTextAtSize(ch, 10)
      out += ch
    } catch {
      out += ' '          // a gap you can see, not a deletion you cannot
    }
  }
  return out
}

A space is not a great outcome. It is a much better outcome than a name silently closing up, because a human proofreading the document has a chance of spotting it.

Two more things only rendering will tell you

While I had a rasteriser pointed at the output, two layout bugs turned up that no amount of reading the code would have found.

A six-figure total ran backwards over its own label. The totals block right-aligned the figure at 20pt Black in a column sized for four digits. At $2,160.00 it was fine. At 86,832.81 PLN it overlapped the words TOTAL DUE sitting to its left. Text does not wrap or complain when it is drawn at an absolute coordinate; it just draws.

A long company name ran off the right edge of the page. Same cause. drawText has no concept of a container, so anything longer than you imagined simply continues past the paper.

Both are obvious in a rendered image and invisible in a diff. If you generate PDFs, put a rasteriser in your test loop:

# PyMuPDF, no system dependencies
python3 -c "
import pymupdf
pymupdf.open('out.pdf')[0].get_pixmap(dpi=120).save('out.png')"

Then actually open the PNG. It takes ten seconds and it is the only test that catches this class of bug.

The short version

The standard 14 fonts are WinAnsi. They cannot draw most of the world's names.
Stripping the characters to stop the exception silently corrupts user data in a document they will send to a third party.
Embed a subsetted TrueType face with @pdf-lib/fontkit, cache the bytes, and check the licence.
Keep a fallback that leaves a visible gap rather than a clean deletion.
Render your output to an image in tests and look at it. Absolute-positioned text overlaps and overflows without any error.

I found all of this building HourToBill, where the invoice is the entire product, so a mangled client name is not a cosmetic bug. If you generate documents from anything a user typed, it is worth spending twenty minutes checking what yours does with Łódź.

We ran the same ChatGPT prompt three times in a row. Here is what changed.

Peter Hallander — Tue, 18 Aug 2026 20:38:23 +0000

We wanted to know how much a single ChatGPT answer can be trusted as a measurement. So we ran the same prompt through ChatGPT more than once, with nothing changed between runs, and recorded what came back each time.

The setup

We used DataForSEO's ChatGPT LLM Scraper on 2026-08-16. For each prompt we ran the exact same query three times, minutes apart, same settings every time. Nothing about the prompt or the account changed between runs. Any difference in the answers is the model, not us.

Email marketing apps for Shopify

The prompt was "best email marketing app for Shopify," run three times.

Across the three runs, 16 distinct domains showed up somewhere in the answers. Only 4 of those 16 appeared in all three runs.

Brand	Runs appeared in	Position
Klaviyo	3 of 3	1st, every time
Omnisend	3 of 3	2nd, every time
Mailchimp	2 of 3	4th twice, absent once

Klaviyo and Omnisend held their spots exactly. Mailchimp did not. It sat at position 4 in two runs and was missing from the answer entirely in the third. Nothing about the prompt changed between that run and the other two.

If you had only run this prompt once, and it happened to be the run without Mailchimp, you would have concluded Mailchimp does not appear for this query. Run it again and that conclusion is wrong.

A wider check: HTML-to-PDF APIs

To see if this held up outside one prompt, we ran 4 prompts about the HTML-to-PDF API category, 3 runs each, for 12 observations total.

66 distinct domains showed up across those 12 observations. Only 5 domains appeared in every run of the specific prompt they showed up on. 4 of 8 brands we were tracking appeared in some runs of a prompt and were missing from others.

The pattern from the email marketing prompt was not a one-off. The names at the top of an answer tend to hold their position. Everything below that is less settled than a single run makes it look.

What it cost to check

Running all 12 observations for the HTML-to-PDF category cost $0.004 per call, $0.048 in total. Checking whether an answer is stable is not expensive. Not checking is the part that costs something, because it produces a wrong number with the same confidence as a right one.

The conclusion

A tool that runs a prompt once and reports "brand visibility: 67%" is reporting a single sample as if it were a measurement. Based on what we saw here, that number would land differently depending on which of the three runs happened to be sampled.

The top of a ranking is stable. Klaviyo held position 1 in every run. Omnisend held position 2 in every run. That part, one run would have told you correctly.

The marginal brand is not stable. Mailchimp came and went. In the wider check, more than half the brands we tracked were inconsistent from run to run. That instability sits exactly where most brands actually are, not at the top, and it is exactly what a business paying for this kind of tracking wants to know: are we in or out, and how often.

A single run cannot answer that question. It can only tell you what happened once.

Measured on 2026-08-16 using DataForSEO's ChatGPT LLM Scraper. Same prompts, same settings, three runs each, minutes apart.

I measured 7,032 WordPress plugins to find out how anyone gets their first install

Peter Hallander — Sun, 16 Aug 2026 18:24:12 +0000

I shipped a plugin to the WordPress.org directory. It got zero installs.

That is not a complaint, it is the normal outcome. Roughly 19% of all plugins in the directory never pass zero installs, which is more than 10,500 of them. But I wanted to know why, and whether the answer was "your plugin is bad" or something structural.

So instead of reading marketing advice, I queried the directory API and counted.

Everything below is reproducible. The API is free, needs no key, and every query I used is in the article.

The short version

Search is a two phase system, and phase one is a hard filter, not a ranking. If a single word of the user's query is missing from your listing, you are excluded from that search entirely.
Phase two is where you lose, and it is ranked partly on active installs. That is the cold start trap.
Of the plugins that broke out recently, 88% had distribution before they started.
The two behaviours that actually correlate with breaking out from nothing are release cadence and resolving support threads, which are two of the five phase-two ranking inputs and the only two a plugin with no installs can move.
WordPress.org gives plugin authors no analytics whatsoever. No listing views, no impressions, no click-through. Anyone who tells you confidently what makes people click install is guessing.

How search actually works

The best-documented account traces to WP Tavern's 2017 coverage of the directory relaunch, quoting Greg Brown, the Automattic data engineer who built it. It runs on Elasticsearch, and it has two phases.

Phase one builds the candidate pool. It matches against title, excerpt, description, tags, slug, author name and contributor names. Critically: all search keywords must appear somewhere, or the plugin is excluded from the result set. Not ranked low. Excluded.

Phase two sorts that pool by last update date, compatibility with the current core version, active installs, percent of support tickets resolved, and average rating.

That split matters more than anything else in this article, because phase one is entirely yours and phase two mostly is not.

Testing the hard filter on my own plugin

I took my live plugin and measured its actual position for terms it should rank for, then checked which query words appear in its listing.

rank	term	missing words
14	disposable email blocker	none
46	block disposable email	none
50	disposable email	none
146	temporary email	none
>300	email validation	none
>300	spam registration	"spam"

Two failures, two completely different causes.

"spam registration" fails because the word spam appears nowhere in the listing. That is phase one. It is a hard exclusion, and it is free to fix.

"email validation" fails even though every word is present. That is phase two: the term is owned by WP Mail SMTP and CleanTalk on install count, and no amount of rewriting changes it.

Being able to tell those two apart is the single most useful thing I learned. One is a typo-level fix. The other is not a copy problem at all.

Here is the query, if you want to check your own. Note the -g flag, without it your shell will try to glob the square brackets:

curl -g "https://api.wordpress.org/plugins/info/1.2/?action=query_plugins&request[search]=disposable+email&request[per_page]=100&request[page]=1"

Who actually breaks out

This is the part I expected to be discouraging, and it was worse than I expected.

I swept the entire directory for plugins with 1,000 or more active installs. That is 7,032 plugins. Then I filtered to those added in the last 18 months. That leaves 167. Those are the breakouts.

Then I looked at who published them.

cause	share
Author already ran another plugin with real installs	67%
Known commercial brand with an audience off WordPress	17%
Cross-promoted from the author's own theme or membership site	3%
Legacy plugin name revived by a directory insider	1%
Company formed specifically to ride a trend	1%
Unclear, possible genuine cold start	10%

88% had some form of pre-existing distribution.

The scale of the first group is worth spelling out. One vendor launched eight breakouts off the back of a two million install plugin. Another launched three off ten million. That is not a growth tactic you can copy, it is an asset you either have or do not.

The second group is the one that fooled me at first. It looks like cold starts, because those authors have no other WordPress plugins. But it is Visa. It is Sendcloud. It is a hosting company. These are businesses with a customer base off WordPress, shipping an integration to people who already pay them. Same advantage, different platform.

When I dug into the remainder, two out of sixty-nine survived as genuine unknown-author cold starts.

What those two did

They took opposite routes, and the difference is instructive.

One is a floating WhatsApp button. Its author has exactly one plugin in the entire directory and no brand at all. It serves an extremely common, low-friction search intent that the directory's own search surfaces well.

The other is an llms.txt generator. It broke out because llms.txt did not exist before 2025. There were no incumbents with an install-count advantage, so phase two was level and phase one decided.

That second one is the only mechanism I found that beats the cold start loop rather than enduring it. When the need is new, nobody has installs yet.

The grind that does work

I filtered the breakouts down to solo developers shipping security and blocking utilities, which is my own category, and looked at their behaviour rather than their marketing.

plugin	installs	age	releases	support resolved
Advanced IP Blocker	2,000	14 mo	124	12 of 12
Vigilant	2,000	6 mo	64	15 of 15
BotBlocker	3,000	9 mo	25	4 of 4
Geo Blocker	1,000	15 mo	2	0 of 1

Advanced IP Blocker shipped 124 releases in 14 months. That is roughly nine a month. Vigilant shipped 64 in six. Both resolved every single support thread they received, both have the most ratings in the group, and both had shipped within days of when I measured.

Geo Blocker is the control case. Two releases, never touched again, one support thread left unanswered. Still at the bottom.

This is not just correlation. Last update date and percent of support tickets resolved are two of the five documented phase-two ranking inputs. The third input, active installs, is the one you cannot move. So shipping often and answering everything are not merely habits of successful plugins, they are literally the only two ranking levers available to a plugin with no users.

One more thing I noticed and cannot prove causal: those breakout readmes run 39,000 to 42,000 characters. Mine were 8,000.

Things that are simply not true

"0 active installs" does not mean zero. A WordPress core issue confirms the label really means "fewer than 10". If you are sitting at zero, you may well have users.

You cannot measure your funnel. WordPress.org exposes no listing views, no search impressions, no click-through rate, nothing comparable to App Store Connect or the Play Console. So when someone tells you that a better banner or a shorter description improves conversion, ask where the number came from. The platform does not hand anybody that data.

Do not pay for reviews or installs. It is Guideline 9. The penalty is removal of all your reviews, then removal of the plugin on a repeat. There is a real enforcement case.

An API trap that cost me an hour

request[browse]=popular silently ignores request[tag].

I confirmed it across four different tags, all returning identical results. There is no error and no warning. If you are trying to sweep a category by popularity, you cannot do it in one call. Sweep by tag without browse, or sweep browse=popular globally and filter client-side.

Also useful: query_plugins returns the added date in the bulk response, so you can find recently-published plugins without a detail call per plugin.

What I actually changed

I stopped treating this as a marketing problem.

I audited every listing for phase-one coverage, checking that every word of each target search literally appears. That found a real gap: one of my plugins says "blocklist" everywhere, while merchants type "blacklist". Free to fix, and it was excluding me from those searches entirely.

I built a rank tracker, because installs are the last thing to move and search position is the first. Without it I was editing copy blind. If rank improves after a wording change, that is phase one responding. If it refuses to move, that is phase two, and no rewrite will fix it.

And I stopped picking categories with entrenched incumbents. The llms.txt case is the whole lesson: when a requirement is brand new, everybody starts at zero installs together.

The honest conclusion

If you have an audience, use it, because that is what 88% of successful launches did.

If you do not, the directory is not going to discover you on its own. The two levers you own are shipping often and answering every support thread. Both are slow. The most rigorously documented zero-audience case I could find took about a year to reach a thousand installs, at roughly a hundred a month, and the developer says plainly it was never exponential.

The alternative is to be early to something new enough that nobody has an install-count advantage yet. That is the only shortcut in the data.

This came out of building four plugins for WordPress.org, one of which is live so far and sitting at the install count this article is about, which is rather the point. The one that prompted the research is Email Guard, a local disposable-email blocker for WooCommerce that bundles its domain list and makes no outbound requests. Every number above is reproducible from the public plugin API.

If you render user HTML, you have an SSRF problem. Here is the code that fixes it.

Peter Hallander — Sat, 15 Aug 2026 11:57:08 +0000

Every HTML-to-PDF service has the same shape. Someone hands you markup, you open it in headless Chromium, you print to PDF. If you want Mermaid diagrams or KaTeX math to work, that markup has to be allowed to run JavaScript.

Which means you have built a machine that fetches arbitrary URLs from inside your network, on request, for strangers.

Most write-ups stop at "block private IPs". That is the easy half. The hard half is that the URL your user submits is not the only URL your service requests, and an IP address has more spellings than you think.

The request you validated is not the request you make

Say you accept a URL and check it before rendering:

const url = new URL(input);
if (isPrivateIp(await resolve(url.hostname))) throw new Error("nope");
await page.goto(url);

That check covers exactly one request. The page you just loaded can issue as many more as it likes, and none of them went through your validator:

<img src="http://169.254.169.254/latest/meta-data/iam/security-credentials/">
<script>fetch('http://localhost:6379').then(r => r.text()).then(t => 
  document.title = t)</script>

The image fetch reaches your cloud metadata endpoint. The fetch hits Redis on the loopback address. A redirect from a public URL to an internal one bypasses the check too, because you validated the URL before the redirect existed.

So you need two layers, and the second one is the one that matters:

await page.setRequestInterception(true);
page.on("request", async (req) => {
  if (await isAllowedRequestUrl(req.url())) await req.continue();
  else await req.abort();
});

Every subresource, every redirect hop, every XHR. Chromium asks permission before each one.

DNS rebinding, and the asymmetry that beats it

Now the classic attack. Your validator resolves evil.example and gets a public address, so it passes. Chromium then resolves it again to make the actual request, and this time the record answers 127.0.0.1. Two lookups, two answers, and the gap between them is the vulnerability.

You cannot fully close that gap without pinning the resolved address at the socket layer. You can narrow it a lot, and there is one design decision that does most of the work:

Cache refusals. Never cache approvals.

const blockedCache = new Map();
const BLOCKED_TTL_MS = 60_000;

This looks like a performance detail. It is the security property. If you cache "this host is public" for even sixty seconds, an attacker answers public once, gets that verdict cached, and then points the record wherever they like for the rest of the window. Your cache is now defeating your own validator.

Caching the refusal is safe, because the cached answer is the "no". A host that becomes benign later is simply blocked slightly longer than necessary, and nobody is harmed by that.

The same instinct applies everywhere else in this code. When you cannot tell, refuse:

try {
  const addrs = await lookup(host, { all: true });
  isPrivate = addrs.length === 0 || addrs.some(a => isPrivateIp(a.address));
} catch {
  isPrivate = true;   // a name that will not resolve is refused, not passed through
}

A URL that will not even parse gets the same treatment. It returns false, not true. The schemes that legitimately arrive here (data:, about:, blob:) all parse fine, so a parse failure is genuinely suspicious.

And allowlist the schemes rather than blocklisting them. ftp:, ws: and chrome-extension: have no business in a document you were asked to render, and you will never think of all of them in advance.

Now the part that actually bites: parsing

Here is where I lost the most time, and where I suspect most implementations are quietly wrong. Every one of these was a real bug in my own code, found by writing the test suite rather than by reading it.

parseInt is not a validator. It takes a valid prefix and ignores the rest. parseInt("1g", 16) is 1, not an error. So ::1g parses as ::1, or worse, as something that passes a check it should have failed. Validate the shape first, parse second:

if (!/^[0-9a-f]{1,4}$/.test(hextet)) return null;

Anchor your dotted quad. IPv6 allows a trailing IPv4 form, ::ffff:127.0.0.1. If you match that suffix without anchoring both ends, then ::ffff:1.2.3.4.5, ::ffff:1.2.3 and ::ffff:1.2.3.4x all get accepted, because your regex happily consumes the part it likes and ignores the rest.

Reject zone indices, do not strip them. Node considers fe80::1%eth0 a valid IPv6 address. It is tempting to strip the %eth0 and carry on. Do not. A scoped address is not something a web page should ever be fetching, and stripping a suffix is how malformed input becomes valid input.

Judge mapped addresses by what they embed. ::ffff:127.0.0.1 and ::ffff:7f00:1 are the same address wearing different clothes. Compare the bytes, not the string, or you will block one spelling and wave the other through.

NAT64 is not where you think it is. The translation prefix is 64:ff9b::/96. The first hextet is 0x0064, so the significant bytes sit at offsets 1 to 3, not 0 to 2. Get this off by one and you block nothing.

Teredo needs all four bytes. The prefix is 2001:0000::/32. I originally checked three bytes, which was worse than useless: it blocked 2001:0001::/32 and everything else under 2001:00xx, which are ordinary public addresses. An over-broad rule is still a bug, it just fails in a direction nobody reports.

Strip the brackets. WHATWG URL keeps them: new URL("http://[::1]/").hostname is "[::1]", and Node's isIP() rejects the bracketed form. Miss this and every IPv6 literal falls through to a DNS lookup that fails, gets refused, and looks like it works. It is correct by accident for private addresses, wrong for public ones, and it will break the day you change your fallback.

What this does not do

It narrows the rebinding window. It does not eliminate it. Fully closing it means resolving the name once and pinning that address at the socket layer so the request cannot be redirected to a different one. That is not implemented here, and I would rather say so than let you assume otherwise.

It also assumes your renderer is not otherwise sandboxed. Network policy at the container level, a blocked metadata endpoint, and an egress allowlist are all better defences than anything above, because they do not depend on my parser being correct. Treat this as the layer that catches what those miss, not as the only thing standing between a stranger and your instance metadata.

The part worth stealing

If you take one thing: write the test suite before you trust the parser. Mine has thirty-one cases for the URL layer and forty-five assertions for IPv6 alone, and it found four real bugs in code I had already read twice and believed was correct. Address parsing is exactly the kind of problem where reading proves nothing, because every bug looks reasonable on the page.

The code above runs in MintPDF, a Markdown and HTML to PDF API. It is MIT licensed, so the full implementation is on GitHub if you want the rest of it.

Integrating with Poland's KSeF: five things that aren't in the docs

Peter Hallander — Sat, 15 Aug 2026 08:39:33 +0000

Poland switched to mandatory structured e-invoicing this year. Since 1 February 2026 for the largest companies, since 1 April 2026 for all active VAT payers, and from 1 January 2027 for everyone else, including the smallest and VAT-exempt.

The system is called KSeF (Krajowy System e-Faktur). You send an invoice as XML in a schema called FA(3), it validates it, assigns it a number, and returns a signed receipt. Conceptually simple. There is an OpenAPI spec and official SDKs in C# and Java.

I've spent this year building an integration against it in TypeScript on Deno, and it now files invoices in production. Below are five things that cost me real time and are not in the documentation, or are in it in a way you only recognise afterwards.

1. The receipt is issued per invoice, but fetched through the session

This is the one I'd most want to tell my past self, and it has two halves that are easy to get backwards.

You can send invoices in a batch session: one ZIP of XML files, hundreds at a time. The session returns a reference number, and it's tempting to store that and call the invoices delivered.

It isn't. The document that legally proves an invoice reached the system is the UPO (Urzędowe Poświadczenie Odbioru), and it exists per invoice. A session reference proves a session happened. If you are ever asked to produce evidence for one specific invoice, that isn't it.

But — and this is the half I got wrong first — the UPO is retrieved through the session that submitted it:

GET /api/v2/sessions/{originalSessionRef}/invoices/ksef/{ksefNumber}/upo

So the session reference isn't disposable, it's a required key. An earlier version of my code opened a fresh session to fetch UPOs and could never resolve them, because KSeF binds UPO metadata to the original session. If you lose that reference, retrieving the receipt afterwards gets considerably harder.

Practically: store the session reference and iterate per invoice. A batch of 200 means one upload and then 200 fetches, all keyed on that one session ref. Budget for it in your queue design — it dominates wall-clock time, not the upload.

2. One bad invoice doesn't fail the batch

The inverse mistake. A document that fails semantic validation is rejected individually. The other 199 in the same session go through normally.

If you treat a batch as atomic and roll the whole thing back on any error, you'll re-send invoices that were already accepted, and duplicate invoice numbers are their own category of pain. Per-invoice status tracking isn't optional.

3. Not every buyer has a tax ID, and it isn't only consumers

FA(3)'s buyer section (Podmiot2) offers a choice of identifiers. One of them is BrakID, literally "no ID":

<fa:Podmiot2>
  <fa:DaneIdentyfikacyjne>
    <fa:BrakID>1</fa:BrakID>
    <fa:Nazwa>Jan Kowalski</fa:Nazwa>
  </fa:DaneIdentyfikacyjne>
</fa:Podmiot2>

I read that as "consumer invoices" and wrote validation that required a tax ID for everything else. Both halves of that were wrong.

Wrong on scale: roughly three in four invoices in one real customer's book have no buyer tax ID. Any validation demanding one rejects most of a working invoice book, which is a spectacular way to discover your assumption.

Wrong on meaning: BrakID is not consumer-only. A taxpayer can lack a tax ID too — in Poland, unregistered business activity is the common case — and such an invoice is still fully in scope of the mandate. If you special-case "consumer", you'll misclassify them.

The subtler bug that came out of this: my validation demanded the ID while my serialiser, twelve lines further down the same file, correctly emitted BrakID. The two disagreed for months without anyone noticing, because the code path that would have surfaced it was never called in production. Worth grepping for that shape in your own code — a validator and a serialiser that encode the same rule separately will drift, and the drift is silent.

4. Session encryption keys are per-session, and generating them is async

Invoices are uploaded encrypted with a symmetric key, which is itself wrapped with the system's public key (RSA-OAEP, SHA-256).

Two traps here.

The keys are per session. They are not credentials to cache. Generate them each time you open a session.

And in the TypeScript client I use, the call that produces them became async at one point, when it migrated to Web Crypto. My code destructured it as if it were synchronous:

// silently produces undefined for every field
const { cipherKey, cipherIv, encryptionInfo } = client.crypto.getEncryptionData();

// correct
const { cipherKey, cipherIv, encryptionInfo } = await client.crypto.getEncryptionData();

Nothing throws. You get undefined for all three, send an empty encryption field, and the server rejects it several calls later with a code that means "encryption must not be empty". The stack trace points at the session-open call, which is not where the bug is.

If you're on Deno specifically, one more note: use Web Crypto (crypto.subtle) rather than the node:crypto compatibility layer for the RSA-OAEP step. The compat path silently downgraded the mask generation function to SHA-1 for us, which produces ciphertext the server won't accept, and again nothing local fails.

5. When a government API tells you the problem is your data, believe it early

The expensive one.

Authentication kept failing with HTTP 450 and a message saying the token could not be used in the context of our tax ID. 450 is not a standard status code, and the message reads exactly like the sort of thing you get when your request is malformed.

So I checked everything on my side. Token format, scopes, permissions, the certificate, the encryption, the challenge encoding. All correct. I filed a support ticket. I waited.

The actual cause: that tax ID was in a bad state in the test environment's database. Nothing I could send would ever have worked. Generating a token for a different, properly registered tax ID authenticated cleanly on the first attempt.

That cost about three weeks, and the fix would have taken an hour on day one. The ticket was never going to resolve it, because there was nothing to fix on my side and the message had been telling me so the whole time.

The generalisable lesson: when an integration fails against a government system and the error blames your data, spend an hour testing that hypothesis directly before you spend a week disproving yours. Try a different account. It's cheap and it's decisive.

Choosing an integration path at all

Stepping back, there are really three ways to reach KSeF, and the right one depends far more on where invoices are created than on engineering taste:

Direct API integration — most work up front, least friction afterwards. Right when the system issuing the invoices is yours or your vendor already supports it.
File-based — the invoicing system stays untouched and something else maps its export into FA(3) and handles the session and receipt lifecycle. Right when the invoices come out of a billing, subscription, or warehouse system that will never speak to KSeF.
The government's free web app — genuinely fine at low volume, and worth trying before paying anyone.

Most of the pain above only exists on the first path. That's the honest trade: direct integration means owning sessions, encryption, per-invoice receipts, and error semantics forever.

I ended up building the middle option as a product, and I wrote up how the three paths compare, including the exact column mapping a file needs — that page is in Polish, since that's who has to deal with this, but the structure translates.

If you're starting a KSeF integration now: read the FA(3) schema before the API docs, assume the receipt is per invoice, and test your assumptions about buyer identifiers against a real invoice book rather than a fixture.

What Google did with a brand new site in its first 24 hours

Peter Hallander — Sat, 15 Aug 2026 08:27:21 +0000

We put a new site online with no backlinks, no audience and no history. Sixteen pages, a sitemap, and a Google Search Console property connected the same afternoon. Then we recorded what Google said about every page, the first morning and the next.

That record is the only reason this article exists. Search Console answers the question for today and keeps nothing, so the day-one state of a site is normally gone by day two. Ours is not.

What happened in the first day

On the first afternoon, Google had not heard of any of it. Every page came back as unknown. By the next morning's check, thirteen of the sixteen were indexed.

What Google reported	First afternoon	Next morning
Indexed	0	13
Seen but not indexed yet	0	1
Not heard of at all	16	2

That is the part worth sitting with if you have ever been sold an indexing service. A site with no links pointing at it from anywhere on the internet, published the previous day, was most of the way into Google by the following morning. Nobody paid for that and nothing clever caused it.

The bit we thought would be the story

Partway through that first afternoon, we opened Search Console and used Request Indexing on nine of the pages. Not as an experiment. We were working through a list and stopped when we got distracted, which left the remaining pages untouched.

By accident that produced two groups, and the tempting article writes itself: three pages nobody asked about were indexed by morning on the same schedule as the nine we did ask about, so the button does nothing.

We are not going to tell you that, because the rest of the data does not agree.

Group	Pages	Indexed by morning
We asked Google to index it	9	9
We did not ask	6	3

Nine out of nine against three out of six looks like the button working. It also looks like exactly what you would expect from a list worked through in order by a person who started with the pages he cared about most. The nine were not chosen at random, the groups are tiny, it is one site on one day, and every page was in the same sitemap and linked from the same navigation.

So the honest answer is that we cannot tell you whether Request Indexing helped, and neither can anyone else running a sample this size. What we can tell you is that three pages got into Google without anybody asking, which is the part most indexing tools would prefer you did not find out.

What would settle it. Split new pages randomly, ask for half, publish them the same day with the same internal linking, and repeat until the groups are large enough to mean something. We are running that now. It will take months, and any article that claims to have answered this in a week has not.

The three pages that did not make it

Two were tool pages we had edited heavily that afternoon, and one was our terms page. By morning Google had discovered the terms page and decided not to index it yet, and still had not heard of the other two.

This is the ordinary shape of it. Indexing is not a switch that flips for a whole site. It arrives page by page, and the pages that lag are usually the ones with the least reason to exist in Google's eyes: legal boilerplate, and pages that changed after they were first found.

Why the paid version of this does not work

There is a whole product category built on submitting your pages to Google. It is worth knowing what those submissions actually are.

Google has an Indexing API. Its documentation supports two kinds of content: job postings and live-stream events. Send it a blog post and it returns a success response, because the response tells you the message was received, not that anything will be done with it. We wrote up what it does with everything else separately.

The other half of the bundle is usually IndexNow, which is a genuinely good protocol that notifies Bing, Yandex, Seznam, Naver and Yep. It does not include Google and has never claimed to. We submitted all thirteen of these pages to IndexNow, so if you want a clean reading of the numbers above: the only submission that definitely reached Google was the nine manual ones, and Google indexed pages from both groups regardless.

What we would actually do with a new site

Nothing exotic. Have a sitemap, link every page from somewhere a person could reach, connect Search Console on day one, and then leave it alone for a week before concluding anything. Most pages arrive on their own.

The pages that do not arrive are the ones worth your attention, and you will only know which those are if something wrote down what happened. That is the whole argument for keeping a record, and it is the one thing you cannot add later: you cannot go back and observe last week.

Checking your own

Search Console's URL Inspection tool gives you the same answer we recorded, one page at a time, for free. If you want the state of every page rather than one, the same data is available through its API, which is what we are reading. Either way the answer comes from Google rather than from a tool guessing on its behalf, and that is the only kind of answer worth having.

Measured on our own property, 14 and 15 August 2026. Sixteen pages, one site, two consecutive mornings. Small enough that you should treat every number above as a description of what happened to us rather than a rule about what will happen to you.

I build Seomely. It kept this indexing record automatically, and I have been using the same approach on a different question: how a brand actually shows up in ChatGPT and Gemini answers. The first numbers are in a follow-up post. The free index checker needs no login if you just want to see what is blocking a single page.

Headless Chrome splits your PDFs in the wrong places. Here is the CSS that fixes it.

Peter Hallander — Mon, 10 Aug 2026 09:36:46 +0000

If you generate PDFs with headless Chrome, your output probably has a defect you have not looked for.
Mine did. A sixteen-line code block rendered as line_0 through line_9 at the bottom of page one,
then line_10 onwards at the top of page two. Nothing was lost. It just looked like something a
program produced rather than a document a person would send.

That is Chromium's default fragmentation behaviour. It fills the page, and when it runs out of room
it cuts wherever it happens to be. For a web page that is correct. For a printed document it is the
difference between "generated" and "designed".

Here is what actually fixes it, what it costs, and one rule that quietly breaks Markdown tables while
looking completely reasonable.

The problem, concretely

Render a long document with a headless browser and you get four recurring defects:

Blocks cut in half. Code blocks, tables and blockquotes split across the page boundary.
Stranded headings. A heading lands as the last line of a page, its section starting overleaf.
Orphans and widows. A single line of a paragraph alone at the top or bottom of a page.
Table headers that appear once. A table spanning three pages labels its columns only on the first.

None of these are bugs. They are the absence of instructions.

The stylesheet

/* Keep blocks whole across page boundaries. */
pre, table, blockquote, figure, img { break-inside: avoid; page-break-inside: avoid; }
tr, li                              { break-inside: avoid; page-break-inside: avoid; }

/* Rendered diagrams and display maths are blocks too, and both look absurd cut in half. */
pre.mermaid, .katex-display         { break-inside: avoid; page-break-inside: avoid; }

/* Never strand a heading at the foot of a page. */
h1, h2, h3, h4, h5, h6 { break-after: avoid; page-break-after: avoid; }

/* At least three lines of a paragraph stay together. */
p { orphans: 3; widows: 3; }

/* Repeat the header row when a table continues onto the next page. */
thead { display: table-header-group; }

/* Long lines wrap instead of being clipped at the page edge. */
pre { white-space: pre-wrap; overflow-wrap: anywhere; }

Both the modern (break-inside) and legacy (page-break-inside) properties are there deliberately.
Chromium understands both, and the older one is still what several rendering paths respect.

thead { display: table-header-group } is the one people miss. It is not a hack: it is the CSS
mechanism for repeating headers, and it costs one line.

What it costs

Keeping blocks whole means pages end early when the next block will not fit. My 17-page test document
became 19 pages, about 12% longer.

That is the entire trade: slightly more paper, no sliced content. For invoices, reports and receipts
it is obviously worth it. If you are generating something where page count is contractually fixed,
you will want to be more selective about which elements get break-inside: avoid.

One limitation worth stating plainly: a block taller than a page will still split, because it has to.
break-inside: avoid is a preference, not a guarantee. It saves the sixteen-line code block; it
cannot save an eighty-line one.

The rule that broke my tables

This is the part I would not have found by reading advice. My Markdown pipeline had this:

th, td { border: 1px solid #ccc; padding: .45em .7em; text-align: left; }

Reasonable-looking. It also silently destroyed every right-aligned column.

Markdown lets you align columns:

| Item   | Qty | Price |
|:-------|:---:|------:|
| Widget |  2  |  9.00 |

Most Markdown parsers implement that with an HTML attribute. Here is what marked emits:

<th align="right">Price</th>
<td align="right">9.00</td>

The align attribute is a presentational hint, and any CSS rule beats it. So th, td { text-align: left } overrode every alignment the author had asked for. Every price column in every invoice was
rendering left-aligned, and nothing in the output looked broken enough to notice.

The fix is specificity, not removal:

th, td                             { text-align: left; }
th[align="center"], td[align="center"] { text-align: center; }
th[align="right"],  td[align="right"]  { text-align: right; }

An attribute selector (0,1,1) outranks a bare element selector (0,0,1), so the author's alignment
wins again. If your parser emits style="text-align:right" instead, inline styles already beat your
stylesheet and you never had this bug.

Verify by rendering, not by reading

I nearly shipped the page-break fix without checking it, because the CSS is well known and obviously
correct. The reason I know it works is that I rendered a 40-section document before and after and
looked at the pages.

That is also how I found the table bug, which no amount of reading about page breaks would have
surfaced.

A cheap way to eyeball output without leaving your terminal: render the PDF, then screenshot it in
the same headless browser you generated it with.

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({ headless: true, args: ["--no-sandbox"] });
const page = await browser.newPage();
await page.goto("file:///tmp/test.pdf", { waitUntil: "networkidle0" });
await new Promise((r) => setTimeout(r, 2500));   // let the built-in viewer paint
await page.screenshot({ path: "/tmp/preview.png", fullPage: true });
await browser.close();

Chrome's built-in PDF viewer renders the file, so the screenshot shows real pagination, including the
page boundaries you are trying to fix. Crude, fast, and it catches things a diff never will.

Worth testing specifically:

A document long enough to paginate, with a code block positioned to straddle a break.
A table with more rows than fit on one page.
A table with mixed column alignment.
Content whose background you did not choose.

That last one deserves a decision rather than a fix. If a caller sends you HTML with
background: #111, printing a dark page is correct: they asked for it. Forcing white would be you
overriding an author's design. Only style the paths you own, which for me means the Markdown
renderer, not arbitrary HTML input.

The short version

Four properties (break-inside, break-after, orphans/widows, table-header-group) turn
browser output into document output, at the cost of about 12% more pages. Then check whether your own
stylesheet is overriding your parser's alignment, because that failure is invisible until someone
looks at a price column and frowns.

The stylesheet above is the one I ship in my own
Markdown to PDF converter, which is where all of this came
from. It is free and needs no account, so it is an easy way to see the difference these rules make
without wiring up Puppeteer yourself.

Splitting Polish statutory interest across central bank rate changes

Peter Hallander — Tue, 28 Jul 2026 16:23:45 +0000

If you invoice a business in Poland and they pay late, you are entitled to statutory interest. Computing it looks like a one-liner:

interest = amount × rate × days / 365

That is wrong often enough to matter, for a reason that has nothing to do with rounding: the rate changes while the debt is outstanding, and you have to split the delay into segments.

Two regimes, two different clocks

Poland has two separate statutory interest rates, and mixing them up is the single most common error I see.

Odsetki ustawowe za opóźnienie (Civil Code) apply to ordinary obligations. The rate is defined relative to the National Bank of Poland reference rate, so it changes whenever the central bank moves rates, effective from the date of the decision.

Odsetki za opóźnienie w transakcjach handlowych apply to business-to-business commercial transactions. This rate is fixed per half-year: it is set from the NBP reference rate on 1 January for the first half, and on 1 July for the second, and it does not move in between even if the central bank cuts rates in March.

So for the same 200-day delay, one regime may need five segments and the other exactly two. Picking the wrong regime does not just change a number, it changes the shape of the calculation.

The segmentation

Once you accept that the rate is a function of time rather than a constant, the calculation becomes a fold over intervals:

type RatePeriod = { from: Date; to: Date; ratePercent: number };

function interestForPeriods(
  amountGrosze: number,
  periods: RatePeriod[],
): number {
  return periods.reduce((total, p) => {
    const days = daysBetween(p.from, p.to);
    // integer grosze throughout; never accumulate in floats
    return total + Math.round((amountGrosze * p.ratePercent * days) / (365 * 100));
  }, 0);
}

Three things in that small function are load-bearing.

Money stays in integer grosze. 0.1 + 0.2 !== 0.3, and interest is a sum of many small terms. Accumulating in floats produces drift that shows up as a one-grosz disagreement with the other side's accountant, which is exactly the kind of thing that turns a payment discussion into an argument.

Rounding happens per segment, not once at the end. This is a modelling decision rather than a mathematical one: each segment is a distinct legally-defined period, so it is the natural unit to round. Whichever convention you choose, choose it deliberately and document it, because the two approaches differ by a grosz or two and someone will eventually ask why.

The day count is exclusive of one endpoint. Off-by-one over a 400-day delay is not a rounding error, it is a whole day of interest.

Building the period list

The segmentation itself is a merge between the delay window and the rate timeline:

function splitByRateChanges(
  from: Date,
  to: Date,
  rateTable: { effectiveFrom: Date; ratePercent: number }[],
): RatePeriod[] {
  const sorted = [...rateTable].sort((a, b) => +a.effectiveFrom - +b.effectiveFrom);
  const out: RatePeriod[] = [];

  for (let i = 0; i < sorted.length; i++) {
    const start = sorted[i].effectiveFrom;
    const end = sorted[i + 1]?.effectiveFrom ?? to;
    // clip the rate window to the delay window
    const segFrom = start > from ? start : from;
    const segTo = end < to ? end : to;
    if (segFrom < segTo) {
      out.push({ from: segFrom, to: segTo, ratePercent: sorted[i].ratePercent });
    }
  }
  return out;
}

For the commercial-transactions regime you feed it a rate table with two entries per year. For the Civil Code regime you feed it every NBP decision. Same fold, different input, which is the point: the regime difference belongs in the data, not in the control flow.

Why not just use the current rate

Because the answer is wrong, and wrong in a direction that is easy to spot. During a rate-cutting cycle, applying today's rate to the whole delay understates what you are owed. During a hiking cycle it overstates it, which is worse, because now your demand letter contains a number the debtor can dispute.

Worth knowing if you build this

Rate tables need a source of truth with effective dates, and they change with no notice on your schedule.
Store the segment breakdown, not just the total. When someone challenges the figure, "here are the five periods and the rate in each" ends the conversation; a single number does not.
Test around the boundaries: a delay that starts on the day of a rate change, one that ends on it, and one entirely inside a single period.

I maintain WezwaniePro, a free generator for Polish payment demands and interest notes that does this segmentation automatically. The arithmetic above is the part that took longest to get right, which is why it seemed worth writing down.

If you have implemented statutory interest for another jurisdiction and handled the rate-change problem differently, I would be interested to hear it.

Poland's e-invoicing system has no JavaScript SDK, so I published the validation layer

Peter Hallander — Mon, 27 Jul 2026 18:39:15 +0000

Poland runs a national e-invoicing system called KSeF (Krajowy System e-Faktur). Business-to-business invoices are submitted to a government API in a schema called FA(3), and the system hands back an official confirmation of receipt. If you sell software to Polish companies, you will meet it.

The Ministry of Finance publishes official SDKs for Java and .NET. There is nothing for JavaScript.

A full client is a real project: authentication, session handling, certificates, XML signing. But a large share of rejected invoices have nothing to do with any of that. They are structural. A tax ID with a bad checksum. Net plus VAT that does not add up to gross. A date that does not exist. Those are worth catching on your side, before you build a session with anyone.

So I pulled that layer out of a product I work on, rewrote it standalone, and published it: ksef-invoice-validate. Zero dependencies, no network calls, runs in the browser.

npm i ksef-invoice-validate

import { validateInvoiceForKsef } from "ksef-invoice-validate";

const result = validateInvoiceForKsef({
  invoice_number: "FV/2026/07/1",
  issue_date: "2026-07-01",
  seller_nip: "1111111111",
  buyer_nip: "1111111111",
  amount_net: 1000,
  amount_vat: 230,
  amount_gross: 1230,
});

Three things in it were more interesting than I expected.

The NIP checksum

A Polish tax identification number (NIP) is ten digits. The tenth is a checksum over the first nine, each weighted and reduced modulo 11.

const weights = [6, 5, 7, 2, 3, 4, 5, 6, 7];
const digits = cleaned.split("").map(Number);
const checksum = weights.reduce((sum, w, i) => sum + w * digits[i], 0) % 11;

if (checksum !== digits[9]) {
  // invalid
}

There is a small elegance here. The remainder can be 10, and no single digit equals 10, so those numbers simply cannot exist as valid NIPs. You do not need a special case. The comparison rejects them on its own.

This alone catches a surprising amount. Most bad tax IDs in the wild are transposed digits from manual entry, and a mod-11 check catches every single-digit transposition.

Never compare money as floats

The original implementation checked that net plus VAT equals gross with a tolerance:

if (Math.abs(net + vat - gross) > 0.01) { /* mismatch */ }

That is the bug everyone writes once. 0.1 + 0.2 === 0.30000000000000004, and on invoice arithmetic the drift lands exactly where you cannot afford it: a comparison against a rounding tolerance. Values that should pass fail, and it is not reproducible in a way that looks like a pattern.

The fix is to leave floating point entirely and compare in integer grosze (Polish cents):

const grosze = (n: number) => Math.round(n * 100);
const diff = Math.abs(grosze(net) + grosze(vat) - grosze(gross));
if (diff > 1) { /* mismatch */ }

The tolerance is now literally "one grosz", which is a statement about money rather than about IEEE 754.

Dates that do not exist

This one is quiet and nasty:

new Date("2026-02-31"); // no error. Rolls over to March 3rd.

Date will happily accept the 31st of February and silently move you into March. On an invoice, an issue date that shifts by three days is not a cosmetic problem.

The cheapest reliable check is a round trip:

const date = new Date(value);
if (date.toISOString().slice(0, 10) !== value) {
  // not a real calendar date
}

If the string you get back is not the string you put in, Date corrected you, which means the input was wrong.

Codes, not sentences

The internal version returned i18n message keys, which are fine inside one app and useless in a library. Every error now carries a stable code you can switch on:

nip.format | nip.checksum | date.format | date.invalid
date.future | amount.negative | amount.mismatch | field.required

The English message is there for humans reading logs. The code is the contract.

What it deliberately does not do

It is not a substitute for validating against the official FA(3) XSD, and it cannot check anything that requires the Ministry's systems: duplicate detection, counterparty status, authorisation, session handling. Think of it as the cheap check you run first, so that the expensive one has less to complain about.

It also does not know your business rules. Buyer tax ID is required by default because the common case is B2B, but consumers and foreign buyers legitimately have no Polish NIP, so that is a flag rather than a law.

Package: ksef-invoice-validate on npm.
Source: github.com/TrendTweekers/ksef-invoice-validate, MIT licensed.

It was extracted from the validation layer of FakturaFlow, a KSeF tool for Polish accounting offices. The checks themselves are general enough to be useful well outside it, which is why they are now their own package.

If you have implemented FA(3) in TypeScript and solved parts of this differently, I would genuinely like to hear it. The JS side of KSeF is thin enough that most of us are solving the same problems alone.