DEV Community: Jangwook Kim

One listener costs you the back button: six bfcache probes

Jangwook Kim — Tue, 21 Jul 2026 06:40:56 +0000

A page with a beforeunload listener came back from memory. A page with an unload listener did not. That's the whole difference: one identifier.

I keep finding codebases that treat those two as the same thing, filed together under "cleanup on leave." So I built six pages, each carrying exactly one candidate blocker, and drove a real back navigation through each. Here's what the browser handed back.

The navigation that never touches the network

Back/forward cache keeps a page alive instead of tearing it down when you navigate away. DOM, JavaScript heap, scroll position, all frozen in memory. Press back and the browser thaws the snapshot. The official framing on web.dev: "Instead of destroying a page when the user navigates away, we postpone destruction and pause JS execution." The payoff: "Loading the previous page is essentially instant, because the entire page can be restored from memory, without having to go to the network at all."

That last clause carries the weight. A normal back navigation with a warm HTTP cache still reparses the document, re-executes scripts, recalculates layout. A bfcache restore skips all of it. Nothing is recomputed, so no fresh LCP and no fresh layout shift.

Why bother? Because search-result pogosticking is a real pattern, especially on phones. Read a page, back out, try the next result. If every one of those round trips is a full load, your users experience a slow site no matter how fast your first paint is. And unlike most performance work, this one isn't about writing better code. It's about removing things that disqualify code you already shipped, which makes the effort-to-payoff ratio unusually good.

Let me lower expectations first. bfcache is not a ranking factor. Nobody, Google included, guarantees you anything in search results for fixing it. This is a navigation-feel problem for real humans.

The good news is that you never have to guess. Two APIs answer the question directly:

event.persisted on the pageshow event. true means the page came out of bfcache.
PerformanceNavigationTiming.notRestoredReasons, which carries the reasons when the page was not restored. Per Chrome's docs, "The notRestoredReasons API has shipped from Chrome 123 and is being rolled out gradually."

Six pages, one variable each

Mixed variables produce uninterpretable results, so every route below is identical except for its single blocker. Same markup, same instrumentation script.

// server.mjs — one route per condition
const page = (title, body, extraHead = '') => `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>${title}</title>${extraHead}</head>
<body><h1>${title}</h1>${body}
<script>
window.addEventListener('pageshow', (e) => {
  const nav = performance.getEntriesByType('navigation')[0];
  window.__bfcache = {
    persisted: e.persisted,
    nrr: nav && nav.notRestoredReasons
      ? JSON.parse(JSON.stringify(nav.notRestoredReasons))
      : null,
  };
});
</script></body></html>`;

const routes = {
  '/clean':        () => ({ headers: {}, html: page('clean', '<p>no blockers</p>') }),
  '/nostore':      () => ({ headers: { 'Cache-Control': 'no-store' }, html: page('nostore', '') }),
  '/unload':       () => ({ headers: {}, html: page('unload', '',
                      '<script>window.addEventListener("unload", function(){});</script>') }),
  '/beforeunload': () => ({ headers: {}, html: page('beforeunload', '',
                      '<script>window.addEventListener("beforeunload", function(e){});</script>') }),
  '/websocket':    () => ({ headers: {}, html: page('websocket', '',
                      '<script>window.__ws = new WebSocket("ws://127.0.0.1:8099");</script>') }),
  '/next':         () => ({ headers: {}, html: page('next', '<p>second page</p>') }),
};

The JSON.parse(JSON.stringify(...)) round trip isn't decoration. notRestoredReasons doesn't hand you a plain object, and logging it directly gets you [object Object]. That cost me the first run.

Each probe follows the same four steps. Open the target page, navigate to /next, go back through history, read window.__bfcache on the restored page. Chrome 150 on macOS, driven over the DevTools protocol rather than by hand. The last probe swaps the sandbox for a page on this live blog.

Two blocked, four restored

Page condition	`event.persisted`	`notRestoredReasons.reasons`
no blockers	`true` (restored)	`null`
`Cache-Control: no-store`	`true` (restored)	`null`
`beforeunload` listener	`true` (restored)	`null`
`unload` listener	`false` (blocked)	`[{ reason: "masked" }]`
open WebSocket	`false` (blocked)	`[{ reason: "websocket" }]`
live blog article	`true` (restored)	`null`

The unload result is the expected one, and the official guidance doesn't hedge about it. "Never use the unload event. Ever!" With the mechanism spelled out right after: "On desktop, Chrome and Firefox have chosen to make pages ineligible for bfcache if they add an unload listener."

Note what my handler contained: nothing. An empty function body still disqualified the page. The browser checks whether a listener is registered, not whether it does anything. That's worth knowing before you go hunting, because a grep that only looks for suspicious-looking teardown code will miss the dead ones.

beforeunload, meanwhile, sailed through. If your team files both under one mental category, that category needs splitting. Where you genuinely need teardown, use pagehide, which as the docs put it "fires in all cases where the unload event fires, and it also fires when a page is put in the bfcache."

"masked" is not an answer

Now for the API's practical ceiling. The WebSocket page returned a usable string, "websocket". The unload page returned "masked" — on a document containing zero iframes.

Chrome's documentation explains the value like this: "For all the cross-origin iframes, we report null for the reasons value for the frame, and the top-level frame will shows a reason of "masked"." Reasonable as a privacy measure. But read the sentence that follows: ""masked" may also be used for user agent-specific reasons so may not always indicate an issue in an iframe."

My run was exactly that case. Single document, no frames, cause unambiguously the unload listener, and the field still refused to name it.

So here's the position I've landed on. Treat notRestoredReasons as a tool that tells you which URLs are failing, not why. Collect it from real users, rank templates by block rate, then reproduce the worst offender locally with the DevTools Back/forward cache panel to find the actual cause. Teams that expect field data to work as a diagnosis will stall the first time "masked" shows up in ninety percent of their rows. That's not a flaw to complain about, it's the grain of the tool.

`no-store` stopped being a death sentence

The result I didn't expect: the Cache-Control: no-store page restored. That contradicts a rule most of us internalized years ago, and web.dev records the old behavior plainly. With no-store present, "browsers have chosen not to store the page in bfcache."

The same article carries the sequel, though: "There is work underway to change this behavior for Chrome in a privacy-preserving manner." That work has landed. Chrome's own page on enabling bfcache for Cache-Control: no-store documents the rollout reaching 100% of users across March and April 2025. My probe just confirms it in the field.

The conditions matter here, so let me copy them across carefully. Per Chrome's official description, a no-store page may enter bfcache, but Chrome evicts it when cookies or other authorization state change, specifically so that a logged-out user can't reach a logged-in view by pressing back. Certain API usage still makes no-store pages ineligible outright. And if such a page issues a fetch or XHR whose response also carries no-store, that evicts the page too, since the response may contain sensitive data.

The practical read: using no-store as your bfcache opt-out no longer rests on much. That doesn't mean sensitive pages now sit exposed in memory, either. Responsibility moved from a header string to a sharper signal, the change in authentication state. I won't push the conclusion harder than that, since it's browser behavior and it moved once already. But if you have code built on "we send no-store, so we're obviously not cached," go measure it again this week.

An open connection blocks, WebSocket code doesn't

I got the WebSocket probe wrong the first time. The initial version pointed at ws://127.0.0.1:8099 with nothing listening on that port. Result: persisted: true. Not blocked at all.

Obvious in hindsight. The handshake failed instantly, so by the time I pressed back, the page held no open connection. I started a real WebSocket server, logged readyState before navigating away to confirm it was 1 (OPEN), and reran. That produced persisted: false with reasons: [{ reason: "websocket" }].

The mistake turned out to be the most useful part of the day. What the browser inspects is the set of connections open at navigation time, not whether the word WebSocket appears in your bundle. The same logic covers the rest of the connection-shaped blockers. The official list is open IndexedDB connections, in-flight fetch() or XHR, and open WebSocket or WebRTC connections, with a consistent recommendation: close them during pagehide or freeze.

Nobody is asking you to drop real-time features. Scope the connection's lifetime to the page's visibility instead.

let socket;

function connect() {
  socket = new WebSocket('wss://example.com/live');
}

connect();

// Close on the way out — pagehide, not unload.
window.addEventListener('pagehide', () => {
  if (socket && socket.readyState === WebSocket.OPEN) {
    socket.close();
  }
});

// Reconnect and refresh whatever went stale while frozen.
window.addEventListener('pageshow', (event) => {
  if (event.persisted) {
    connect();
    refreshStaleUI();
  }
});

Don't skip that event.persisted branch. A restored page shows the exact frame the user walked away from. Cart quantities, stock counts, notification badges, session timers: anything that decays needs refetching right there. Otherwise you've traded correctness for speed, which is a bad trade dressed up as a performance win.

window.opener belongs in the same family. The docs are blunt: "A page with a non-null window.opener reference can't safely be put into bfcache." Most of us add rel="noopener" for security reasons; it happens to protect eligibility too.

Collecting reasons from the field

Local probes reproduce well but cover almost nothing. Real browsers, real extensions, real network conditions produce blockers you'll never stage. Drop this in to start collecting which URLs lose the restore.

window.addEventListener('pageshow', (event) => {
  const nav = performance.getEntriesByType('navigation')[0];

  // Restored from bfcache — count it as a hit.
  if (event.persisted) {
    navigator.sendBeacon('/rum/bfcache', JSON.stringify({ hit: true, url: location.pathname }));
    return;
  }

  // Only back/forward navigations that failed to restore.
  if (nav && nav.type === 'back_forward' && nav.notRestoredReasons) {
    const nrr = JSON.parse(JSON.stringify(nav.notRestoredReasons));
    navigator.sendBeacon('/rum/bfcache', JSON.stringify({
      hit: false,
      url: nrr.url,
      reasons: (nrr.reasons || []).map((r) => r.reason),
      frames: (nrr.children || []).length,
    }));
  }
});

If most of the reasons values come back "masked", the data is still doing its job. Its value lives in the URL distribution, not the strings.

One more trap when you read the numbers. Right after the live blog page restored, its navigation entry still reported type: "navigate", duration: 1315.2, transferSize: 22218. Those are the original load's figures. A bfcache restore doesn't create a new navigation entry, so nav.duration will never tell you how fast the restore was. Judge restores by event.persisted and nothing else.

The last step is the one that makes the fix survive future commits: automate it. The shape is the same as wiring JSON-LD validation into CI as a build gate. Six probes of open-navigate-back-read translate cleanly into a headless browser script you run against your key templates on every deploy. And where measuring content-visibility render cost dealt with the first paint, this work covers every navigation after it.

What to change this week

Two of six probes failed. One died to a single registered listener, the other to a single open socket. The other four passed, including the one everybody still assumes is disqualified.

In the order I'd actually do them:

Audit and delete every unload listener. Empty bodies block too. Search third-party snippets, not just your own code, and grep for onunload alongside addEventListener('unload'.
Move teardown to pagehide. It fires everywhere unload fires, plus on entry to bfcache. Leave beforeunload alone; confirmation dialogs are not the problem.
Close WebSocket, WebRTC and IndexedDB connections in pagehide. The test is what's open when the user leaves, not what's in the bundle.
Add an event.persisted === true branch to pageshow. Reconnect, then refetch anything that goes stale. Without it you ship a fast, wrong screen.
Put rel="noopener" on outbound links. A non-null window.opener disqualifies the page.
Re-measure anything built on no-store assumptions. Chrome changed this in 2025, with eviction on cookie and auth changes as the guardrail.
Instrument the field, but read the URLs. Reasons get masked. Block-rate-by-template is the signal you're after.

The honest boundary: six probes, one machine, one Chrome build. Safari and Firefox draw their eligibility lines differently, and notRestoredReasons is a Chromium API to begin with. Don't read these strings as a spec guarantee. The procedure is cheap enough to rerun, though, so point it at the browsers your users actually have and get your own numbers.

Whether your site's back navigations really restore from cache, and which templates quietly lose eligibility, is a measurable question rather than a matter of taste. I take on this kind of work personally: measuring the current state, fixing what the measurement exposes, then leaving behind a CI gate so the fix doesn't silently regress twenty commits later. If that's useful to you, get in touch.

1,248 Feed Items, Four Languages, Zero Language Metadata

Jangwook Kim — Mon, 20 Jul 2026 06:41:20 +0000

My blog ships one aggregate RSS feed. I opened the built file and counted: 1,248 items, Korean, Japanese, English and Chinese posts interleaved by publication date. Nowhere in that XML does anything say which language a given item is written in. Not on the channel. Not on any item.

So how does a consumer figure it out? It looks at the characters and guesses.

The W3C Internationalization Working Group published two First Public Working Drafts on 2026-07-16. One of them, Strings on the Web: Language and Direction Metadata, goes straight at that guessing habit. The companion draft, Character Model for the World Wide Web: String Matching, covers the adjacent problem of comparing strings across normalization forms. I read the first one, audited my own site against it, fixed one thing, and bolted a build gate on so it can't rot back. Every number below is real output from that process.

Strings forget their language the moment they leave HTML

Start with why this matters at all, because skipping it makes the measurements later look like pedantic XML nitpicking.

HTML has lang and dir. Write <p lang="ar" dir="rtl"> and the fact that this paragraph is Arabic and reads right-to-left is baked into the markup itself. The browser renders accordingly. A screen reader picks the Arabic voice engine instead of mangling the text through an English one. Search engines get a declared answer instead of a statistical one. Markup languages were built with extensible attributes, so there has always been somewhere to hang this information.

The trouble is that strings on the modern web don't travel through HTML alone. They move through JSON API responses, JSON-LD blocks, RSS and Atom feeds, WebIDL interfaces, config files, message queues. Most of those formats were designed on the assumption that a string is just a string. There is no slot in {"title": "..."} for saying what language that title is in. The draft puts it plainly: JSON, WebIDL and other non-markup data languages generally do not provide extensible attributes, and were not conceived with built-in language or direction metadata.

So the metadata evaporates. A string authored in a CMS with a perfectly good lang attribute gets serialized to JSON, handed to an API, passed to a frontend, and re-rendered into HTML somewhere else entirely. Nobody carried the language along. Whatever component does the final render is left with one option, and it's the bad one.

Here's the requirement the draft states:

For any string field containing natural language text, it MUST be possible to determine the language and string direction of that specific string. Such determination SHOULD use metadata at the string or document level and SHOULD NOT depend on heuristics.

The abstract sets the tone before that: "This document describes the best practices for identifying the language and direction for strings used on the Web."

Concretely, the draft recommends a small set of moves. For a single-language field, carry a {value, lang, dir} triple instead of a bare string. Allow document-level language and direction defaults, but require that string-level metadata be able to override them. For fields that hold several translations at once, use a language map keyed by language tag. Restrict direction to exactly three values: ltr, rtl, auto. And for JSON-LD specifically, declare @language and @direction in @context.

One caveat belongs right here, up front, before I build anything on top of this:

This is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to cite this document as other than a work in progress.

What `dir="auto"` actually does, and where it breaks

The heuristic the draft is warning about has a name: first-strong. Scan a string character by character, find the first character with a strong directional property, and adopt its direction. That's what dir="auto" implements in browsers. It costs nothing and it's usually right, which is exactly why it spreads.

The draft is specific about how it fails:

The main problem with this approach is that it produces the wrong result for (1) strings that begin with a strong character with a different directionality than that needed for the string overall (eg. an Arabic tweet that starts with a hashtag) (2) strings that don't have a strong directional character (such as a telephone number), which are likely to be displayed incorrectly in a RTL context.

Reading a failure description isn't the same as watching it happen, so I implemented first-strong myself and ran it against strings I built to probe those exact edges.

import unicodedata

ISOLATE_INIT = {"⁦", "⁧", "⁨"}  # LRI, RLI, FSI
PDI = "⁩"

def first_strong(s: str) -> str:
    depth = 0
    for ch in s:
        if ch in ISOLATE_INIT: depth += 1; continue
        if ch == PDI: depth = max(0, depth-1); continue
        if depth: continue
        b = unicodedata.bidirectional(ch)
        if b == "L": return "ltr"
        if b in ("R","AL"): return "rtl"
    return "ltr"

Fourteen test strings, each tagged with the direction I declared correct as the author. The run:

case                                         declared  dir=auto  ok
------------------------------------------------------------------------
ar title starting with latin product name    rtl       ltr       MISMATCH
he title starting with a version number      rtl       rtl       OK
ar UI label starting with a digit            rtl       rtl       OK
he string starting with an ASCII quote       rtl       ltr       MISMATCH
ar author name with latin handle first       rtl       ltr       MISMATCH
en title starting with an arabic loanword    ltr       rtl       MISMATCH
ar plain sentence                            rtl       rtl       OK
he plain sentence                            rtl       rtl       OK
ko plain sentence                            ltr       ltr       OK
ja plain sentence                            ltr       ltr       OK
zh plain sentence                            ltr       ltr       OK
en plain sentence                            ltr       ltr       OK
numeric-only string (no strong char)         ltr       ltr       OK
emoji-led ar string                          rtl       rtl       OK
------------------------------------------------------------------------
total=14  mismatch=4  mismatch_rate=28.6%

Four wrong out of fourteen. Every failure has the same shape: Latin-script text sitting in front of right-to-left content, or the mirror case where an Arabic word opens an English sentence. An Arabic article title that leads with a Latin product name. A Hebrew string opening on an ASCII quotation mark. An Arabic author byline where the @handle comes first. And in reverse, an English title beginning with an Arabic loanword, which first-strong flips to RTL.

The passes taught me more than the failures did. A Hebrew title starting with a version number resolved correctly. So did an Arabic UI label beginning with a digit, and an Arabic string led by an emoji. Digits, punctuation and emoji carry no strong directional property, so the scan skips right over them and lands on the first real letter. My working intuition before running this was "ASCII in front breaks it." Wrong. Strong Latin letters in front break it. That distinction changes which of your fields are actually at risk.

About that 28.6%: it is the mismatch rate of this constructed fourteen-case set and nothing more. I picked the cases to stress the boundary, so the number is not a web-wide statistic and I'm not going to pretend otherwise. What the run establishes is the shape of the failure, not its frequency in the wild.

Auditing my own build output

Reading a spec and nodding along is cheap. So I wrote a script that walks dist/ after a production build and reports what my site declares rather than what I assume it declares. Real output:

== pages audited == 1248
html[lang] present : 1248/1248
html[dir]  present : 0/1248

== JSON-LD ==
blocks parsed          : 1248  (parse errors: 0)
@context has @language : 0
@context has @direction: 0
blocks containing inLanguage: 1248

== feeds ==
  rss-en.xml    xml:lang=False  <language>=True   items=312
  rss-ja.xml    xml:lang=False  <language>=True   items=312
  rss-ko.xml    xml:lang=False  <language>=True   items=312
  rss-zh.xml    xml:lang=False  <language>=True   items=312
  rss.xml       xml:lang=False  <language>=False  items=1248

The HTML layer held up. Every page declares html[lang], and every JSON-LD block carries inLanguage at the item level. That's the payoff from earlier passes over this site, including the hreflang reciprocity audit that forced me to get the per-page language story straight in the first place.

The last line is the problem. dist/rss.xml is the aggregate feed, the one that mixes all four language editions into a single chronological stream, and it declares nothing. No channel <language>. No per-item language. Twelve hundred and forty-eight items going out the door with their language stripped off, to be reconstructed by whatever guesswork the consumer felt like implementing.

The per-language feeds were fine, which is exactly why I'd never looked closer. rss-ko.xml says ko, rss-ja.xml says ja, and that felt like the job being done. The aggregate feed had been sitting there for as long as the site has been multilingual and I had never once considered it a defect. It took a script that didn't share my assumptions to surface it.

Fixing the mixed feed with `dc:language`

RSS 2.0 has a channel-level <language> element and no per-item equivalent. For a feed where every item is a different language, channel-level is useless. You cannot declare one language for a stream that has four.

Dublin Core solves this. dc:language is defined per-element, which is precisely the granularity the draft asks for: metadata attached to the string, not inferred from context. @astrojs/rss supports both an xmlns option for declaring the namespace and per-item customData for arbitrary child elements, so the change is small.

return rss({
  title: SITE_TITLE, description: SITE_DESCRIPTION, site: context.site,
  xmlns: { dc: 'http://purl.org/dc/elements/1.1/' },
  items: posts.map((post) => {
    const [lang, ...slugParts] = post.id.split('/');
    const slug = slugParts.join('/');
    return { title: post.data.title, description: post.data.description,
             pubDate: post.data.pubDate, link: `/${lang}/blog/${lang}/${slug}/`,
             customData: `<dc:language>${lang}</dc:language>` };
  }),
});

The language code already lives in the content collection ID, since posts are stored as ko/slug, ja/slug and so on. Splitting on the first slash gives both the language tag and the slug, and I need the slug for the link anyway. Rebuild, then count:

$ grep -o '<dc:language>[a-z]*</dc:language>' dist/rss.xml | sort | uniq -c
 312 <dc:language>en</dc:language>
 312 <dc:language>ja</dc:language>
 312 <dc:language>ko</dc:language>
 312 <dc:language>zh</dc:language>

Zero to 1,248. Even distribution across four languages, which is the expected shape given the site publishes every post in all four.

Be clear about what this buys. dc:language serves feed readers, aggregators and anything else consuming the XML programmatically. It is not a search ranking signal, and I'm making no traffic claim here. Google's position on structured data has been consistent for years: it helps machines understand the content, it does not guarantee a ranking outcome. Language metadata sits in the same category. It makes the data honest. That's the whole return.

An unverified gate is not a gate

Fixing a thing once means it's fixed once. The interesting question is whether it's still fixed in three months after twenty commits touch the feed code.

I saved the checker as scripts/validate-string-meta.mjs and hung it off postbuild next to the hreflang validator:

"postbuild": "node scripts/validate-hreflang.mjs && node scripts/validate-string-meta.mjs"

Then came the part people skip. A checker that has only ever printed "pass" has proven nothing about its ability to print "fail." I deleted three dc:language entries from the built rss.xml by hand and reran it:

html[lang]: 1288/1288 pages
per-language feeds: 4 checked
mixed feed rss.xml: 1245/1248 items declare dc:language
FAILED: rss.xml: dc:language 1245 / item 1248 — mismatch
exit=1

Caught all three, correct count, nonzero exit. Restoring the file made it pass again. Two minutes of work to convert "I believe this gate works" into "I watched this gate fail on purpose." Every validator I add to this pipeline gets that treatment now, because a gate that can't fail is decoration with a runtime cost. That habit came out of the five-day audit campaign where I ran measure, fix, and freeze-as-a-gate on repeat, and it has caught more than one script that was quietly passing on a typo'd selector.

Why I did not add `@language` to my JSON-LD context

This is the decision I spent the most time on, and I landed against the draft's recommendation.

The draft says to declare language and direction in the JSON-LD @context. My site currently emits "@context": "https://schema.org" as a plain string, with an @graph array underneath. The upgrade looks like a two-minute edit:

{
  "@context": {
    "@vocab": "https://schema.org/",
    "@language": "en",
    "@direction": "ltr"
  },
  "@graph": [ ... ]
}

I didn't ship it. Here's why.

That @graph holds site-wide entities that appear identically on every language edition. Pull up any Korean page and you'll find this inside it:

{
  "@type": "Organization",
  "name": "jangwook.net",
  "description": "Personal technology blog by Kim Jangwook"
}

Those strings are English. They're English on the Korean page, the Japanese page, and the Chinese page, because I write the organization description once and reuse it. If I set a document-level @language matching the page language, every one of those global entity strings gets labeled ko on Korean pages and ja on Japanese pages. I'd be attaching a confident, machine-readable, verifiably false claim to a string that hasn't changed.

Missing metadata and wrong metadata are not the same failure. When metadata is absent, a consumer knows it's operating on inference and can hedge. When metadata is present and wrong, it gets believed. Wrong is worse than absent, and it's worse in a way that's harder to detect downstream because everything looks well-formed.

There's a second reason, which is that the audit already told me I have a more precise layer in place: inLanguage on all 1,248 blocks, at the item level, where it actually varies. A document-wide default would be a coarser statement sitting on top of a finer one. The @graph consolidation work is what put that item-level coverage there, and it would be strange to now paper over it with a blunter declaration.

Two routes are defensible. Convert the global entity strings to the draft's language-map form, so each one declares its own language regardless of which page it lands on. Or leave @context untouched and let per-item inLanguage carry the load. I took the second, for now, because the first depends on the draft's field-name conventions settling down. This is a First Public Working Draft. Those names may not survive it.

What I'm leaving broken on purpose

Three open items, stated plainly.

html[dir] is missing on 1,248 of 1,248 pages and I left it that way. Korean, Japanese, English and Chinese are all left-to-right, the browser default is ltr, and the rendering is correct today. The declaration is implicit rather than wrong. That changes the day I add an RTL edition, and on that day one more rule goes into the gate. Writing dir="ltr" on twelve hundred pages right now would be motion, not progress.

The draft is a first draft. Field names and recommendations can change before it becomes a Recommendation, so designing a new API schema strictly against it would be premature. What is not premature is the underlying principle. Attaching language metadata to strings predates this document by a long stretch, and doing it with an established mechanism like dc:language is safe regardless of where the draft ends up.

Last one, and it's the limit I'm least comfortable with. I don't read Arabic or Hebrew. Every RTL verdict in the experiment above came from computing Unicode character properties, not from a native speaker looking at rendered output. Direction resolution is defined in terms of character properties, so computation is the right tool for deciding what the algorithm returns. Whether the result looks natural on screen to someone who reads the script daily is outside what I can vouch for.

Seven things to check in your own build output

The short version: the W3C draft asks that every natural-language string be able to declare its own language and direction without heuristics. I implemented the heuristic it warns about and watched it miss 4 of 14 constructed cases, all of them Latin-letter prefixes on RTL content or the reverse. I audited my built site, found an aggregate RSS feed shipping 1,248 items with zero language metadata, fixed it with per-item dc:language, and wired a validator into postbuild that I verified by breaking the file on purpose. I also declined the draft's JSON-LD advice, because applying it to my @graph would attach wrong language tags to English entity strings on non-English pages.

Run these against your own dist/, not your source:

Count html[lang] coverage across every built page. Coverage on the templates you remember is not coverage.
Find every string field crossing a JSON boundary and ask whether the language survives the trip. API responses, feeds, structured data blobs, config.
Grep for dir="auto" and check whether any of those fields can start with a strong letter from the opposite script. Digits, punctuation and emoji are fine; letters are not.
If you emit a mixed-language feed, put dc:language on each item. RSS 2.0 gives you nothing per-item, so pull in the Dublin Core namespace.
Check whether your JSON-LD carries item-level inLanguage before you reach for a document-level @language default, and check what's actually in your @graph first.
Never set a language tag on a string you haven't confirmed. Absent metadata makes consumers cautious. Wrong metadata gets trusted.
Break your own validator on purpose and confirm it exits nonzero. Then restore and confirm it passes.

If your site serves several languages and you're not certain what its build output actually declares, that's a measurable question rather than a matter of opinion. I take on consulting and implementation work in this area personally: auditing language and direction metadata across pages, feeds and structured data, then turning whatever the audit finds into CI gates so the fix survives the next twenty commits. If that's useful to you, get in touch.

GPT-5.6 Prompt Caching: The 24-Hour Cache Is Gone

Jangwook Kim — Mon, 20 Jul 2026 01:22:38 +0000

Say your product sends the same long block of instructions to an AI model on every request. A returns policy. A tone-of-voice sheet. A product catalogue extract. That block doesn't change between customers. You still paid for it on every single call, the way you'd pay a narrator to read the same chapter aloud to every visitor who walks in.

Prompt caching is the fix. The provider keeps the unchanging front section of your request in fast storage and charges you a fraction of the normal rate to reuse it. On OpenAI's GPT-5.5 models that reuse window stretched to 24 hours by default. Then GPT-5.6 shipped, and the rules changed underneath the feature.

We ran the API on both model families to see exactly what changed. One finding matters more than the rest: on GPT-5.6 the 24-hour window is gone, replaced by 30 minutes. And filling the cache is itself a billable line item, priced above plain input.

What actually changed between the two model families

OpenAI's API changelog is short about this. The July 9, 2026 entry lists "explicit prompt caching controls" as part of the GPT-5.6 release. The May 29, 2026 entry says that for organizations without zero-data-retention, cache lifetime defaults to 24 hours instead of a few minutes in memory.

Read together, those two entries suggest the feature only got better. The documentation tells a different story. GPT-5.6 introduces a new prompt_cache_options block next to the older prompt_cache_retention setting, plus a way to mark exactly where the reusable section of your prompt ends instead of letting the system guess. That marker is the "explicit control" the changelog means.

What the changelog does not mention: the new options block accepts a much shorter lifetime, and GPT-5.6 reports cache writes as their own billable quantity. We wanted both confirmed by the API itself rather than inferred from a docs page.

What we built and ran

Effloow Lab ran an OpenAI API check on 2026-07-20 using scripts/gpt56-explicit-cache-probe.py, a small budget-guarded script in this repository.

The setup is deliberately boring. We wrote a 9,208-character fictional operations handbook (invented warehouse rules, no real company, no customer data) and sent it as the unchanging front section of every request, followed by one short question about it. That prefix measured 2,032 tokens on arrival, comfortably over the 1,024-token minimum OpenAI documents for caching to engage at all.

Then four configurations, same text every time:

A: GPT-5.6 with caching left on automatic
B: GPT-5.6 with the explicit mode switched on and the end of the handbook marked as the cache boundary
B2: same as B, but asking for a 24-hour cache lifetime
C: GPT-5.5 with the old 24-hour retention setting, as a control

Four calls per configuration, roughly two seconds apart. Every call passed through the repository's token budget guard before and after. The full commands, raw console output, and limitations are in the public lab note.

What actually happened

Caching worked immediately in every GPT-5.6 configuration. The first call was a miss, as expected, and every call after it reused almost the whole handbook.

Configuration	Tokens sent per call	Tokens reused on repeat calls	Share of the prompt reused	Charged as a cache write on call 1
GPT-5.6, automatic	2,032	2,029	99.9%	2,029
GPT-5.6, explicit marker	2,032	2,001	98.5%	2,001
GPT-5.5, 24h retention	2,032	1,792	88.2%	field not present

Three things stand out.

The 24-hour cache is not available on GPT-5.6. Configuration B2 came back with a flat rejection: Invalid value: '24h'. Supported values are: '30m'. So a reuse window that used to last a full day now lasts half an hour. In business terms, a workload that fires once an hour used to ride the cache all day. On GPT-5.6 it never hits at all.

Filling the cache is its own bill. On the first call of each GPT-5.6 run, the response came back with a field our GPT-5.5 calls never returned: cache_write_tokens. It read 2,029 in automatic mode and 2,001 in explicit mode. OpenAI's pricing page charges cache writes at $1.25 per million tokens against $1.00 for plain input. Plainly: the call that loads your instruction block into the cache costs 25% more than an ordinary call would have. We did not test whether GPT-5.5 bills the same thing without reporting it, so read this as "5.6 makes the write visible and prices it," not as proof the charge is brand new.

The explicit marker buys certainty, not volume. Marking the boundary yourself reused 2,001 tokens instead of 2,029. That is 28 tokens less, about 1.4% of the prompt, and at GPT-5.6 Luna's list price the gap is a rounding error. What you get in exchange is a cached section that is identical on every call because you defined its edge, instead of one the system redraws for you. For anything you have to forecast or explain to a finance team, that predictability is the point.

What this means for your business

Here is the arithmetic that decides whether the upgrade helps or hurts you. Using OpenAI's published prices for GPT-5.6 Luna ($1.00 per million tokens sent, $0.10 per million reused, $1.25 per million written to cache) and our measured 2,029-token block, per 1,000 calls that share that block:

Traffic pattern	What happens	Cost per 1,000 calls	Versus no caching
Busy: several calls every half hour	One write, the rest reused	about $0.21	roughly 90% cheaper
Quiet: calls more than 30 minutes apart	Every call misses and pays to write	about $2.54	roughly 25% more expensive
No caching engaged at all	Plain input every time	about $2.03	baseline

Those are modelled numbers, not invoices. The quiet row assumes a miss still pays to write, which is what the first call of every run did in our test. We never let a cache actually expire and watched what happened next.

The break-even is low. Reuse the same block twice inside a 30-minute window and you're already ahead. But the downside case is real, and it's the one nobody puts in a launch post: a low-traffic service on GPT-5.6 can pay a quarter more than before, for a feature sold as a discount.

So the one thing to do differently after reading this: before you migrate, plot the gaps between your calls that share a prefix. If most gaps are under 30 minutes, turn the explicit marker on. If most are over, treat caching as a cost you have to justify, not a saving you get for free.

Scale that up. A support assistant on steady daytime volume, sharing a 2,000-token policy block, saves close to 90% of its instruction cost. An internal report generator that runs eleven times a day across office hours saves nothing and pays the write premium on every run. Same feature, opposite outcome. The variable isn't your prompt, it's your traffic shape.

There's a migration trap here too. Carry your old prompt_cache_retention: "24h" setting from GPT-5.5 across to 5.6 and it won't do what it used to. Anyone who budgeted for a day-long cache needs to redo that number against half an hour.

Can this survive your workflow?

Run your own traffic through the same question before you migrate. The pattern to check is simple: how often does the same unchanging prefix get sent, and are those sends closer together than half an hour?

Customer support and ticket triage. Usually a clean win. Steady volume, one shared policy block, cache stays warm through the working day.
Order and billing automation. Depends entirely on volume. A few hundred orders an hour caches beautifully. A few dozen a day pays the write premium on nearly every call.
CRM enrichment and batch back-office jobs. Group them. Scattered across the day they lose; run as one batch and they win.
Overnight or weekly reporting. The 30-minute window will not carry you between runs. Assume no cache benefit and check whether the write charge is quietly costing you extra.
Anything with zero-data-retention. Extended caching behaves differently for ZDR organizations, so verify against your own account settings rather than the default documentation.

If you want this measured against your real workload instead of a synthetic handbook, that is the kind of claim-bound run Effloow's Proof Studio exists to produce, and you can see the services side for scope.

When to use it, when to skip it

Switch the explicit marker on when: you have a stable prefix over 1,024 tokens, your traffic keeps it warm, and you need the cached region to be the same on every call so your cost forecast holds.

Skip it when: your prompts are short, your prefix changes per user, or your calls are spread thinner than one every 30 minutes. In the last case the honest move is to measure whether caching is costing you money before you optimize anything else.

Do not assume it carried over when: you are moving from GPT-5.5 or earlier. The setting name changed, the maximum lifetime shrank, and a new charge appeared. Three separate things to re-check.

Honest limitations of this test

One prefix, one account, one region, four calls per configuration, all on a single day. That's enough to show whether the cache engages, what the API accepts and rejects, and which new fields appear. It isn't enough to characterise eviction, routing across machines, or hit rates under production concurrency.

We tested gpt-5.6-luna only. Sol and Terra were never exercised. The pricing structure looks the same shape across all three, but we did not verify their cache behaviour.

Our repeat calls sat about two seconds apart, so nothing here tests the 30-minute boundary directly. The rejection message is our evidence that 30 minutes is the ceiling. We never watched a cache expire.

Finally, every dollar figure above is arithmetic over OpenAI's published price table and our measured token counts. No billing statement was read. No dollar amount was directly measured. Treat the percentages as the shape of the economics, then confirm against your own invoice.

What Effloow added

The changelog says "explicit prompt caching controls" and stops there. What is not in any vendor document is a side-by-side measurement of how much of the same prompt each mode actually reuses, the rejection that proves the 24-hour window is gone on GPT-5.6, and the break-even table showing the traffic pattern where the feature turns into a 25% surcharge. Those three came from our own run and are reproducible from the public lab note.

For related measured work, see our earlier run on the 24-hour prompt cache on GPT-5.5 and the broader token optimization guide for production LLM systems.

FAQ

Q: Can I still get a 24-hour prompt cache on GPT-5.6?

We did not test prompt_cache_retention against GPT-5.6, so we can't tell you whether the old parameter is still accepted there. We can tell you the thing that actually matters for your bill: on GPT-5.6, prompt_cache_options.ttl took 30m and rejected 24h with an HTTP 400. Whatever the old parameter does on 5.6, a day-long cache is not on the menu.

Q: Why did the explicit mode cache fewer tokens than automatic mode?

Because we told it where to stop. The marker sat at the end of the handbook block, so the cached region ended there. Automatic mode extended a little further into the request. The difference was 28 tokens, 1.4% of the prompt.

Q: Is caching ever worse than not caching?

By the price table, yes. A cache write bills at 1.25 times the normal input rate, so if nearly every call misses, you pay a 25% premium for a feature that never pays back. Low-traffic services should check this before enabling anything.

Q: What is the minimum prompt size for caching to engage?

OpenAI documents 1,024 tokens. Below that, the reused-token count comes back as zero. Our prefix was 2,032 tokens, which is why every configuration engaged the cache on the second call.

For your engineers

Exact configuration from the run:

Endpoint: POST https://api.openai.com/v1/responses
Models: gpt-5.6-luna, gpt-5.5-2026-04-23
Prefix: 9,208 characters of synthetic text, SHA-256 80761fcc454ee750..., measured at 2,032 input tokens
max_output_tokens: 48, 4 calls per configuration, ~2s apart
Cache fields read from usage.input_tokens_details: cached_tokens, cache_write_tokens

Reproduce:

python3 scripts/gpt56-explicit-cache-probe.py

Explicit-mode request shape (trimmed):

{
  "model": "gpt-5.6-luna",
  "prompt_cache_key": "effloow-cache-probe-explicit-v1",
  "prompt_cache_options": { "mode": "explicit" },
  "input": [
    { "role": "developer",
      "content": [ { "type": "input_text", "text": "<prefix>",
                     "prompt_cache_breakpoint": { "mode": "explicit" } } ] },
    { "role": "user",
      "content": [ { "type": "input_text", "text": "<question>" } ] }
  ]
}

The rejected TTL call, verbatim:

{
  "error": {
    "message": "Invalid value: '24h'. Supported values are: '30m'.",
    "type": "invalid_request_error",
    "param": "prompt_cache_options.ttl",
    "code": "invalid_value"
  }
}

Note that prompt_cache_key matters more on GPT-5.6 than it did before. OpenAI's caching guide describes it as required for reliable matching on 5.6 and later, and recommends keeping traffic on a single key to roughly 15 requests per minute. We used a distinct key per configuration so the three runs could not contaminate each other.

Evidence: public lab note, with the machine-readable artifact saved alongside it in the repository.

Sources

OpenAI API changelog, July 9, 2026 (GPT-5.6, explicit prompt caching controls) and May 29, 2026 (prompt_cache_retention 24h default): https://developers.openai.com/api/docs/changelog
OpenAI prompt caching guide (1,024-token minimum, cached_tokens, prompt_cache_key, prompt_cache_options, breakpoints): https://developers.openai.com/api/docs/guides/prompt-caching
OpenAI API pricing (GPT-5.6 Luna/Terra/Sol input, cached input, cache write, output rates): https://developers.openai.com/api/docs/pricing
Effloow Lab run, 2026-07-20: public lab note

WCAG 2.2 Minimum Target Size: the AA Failure Hiding Behind a Green 92

Jangwook Kim — Sun, 19 Jul 2026 07:43:38 +0000

The automated accessibility score read 92. A near-green number at the top of the report. Yet lower on the same page, the pagination links measure 22px on a side. Tap "3" with your thumb and "2" or "4" goes along with it. The score looks like a pass while your fingertip keeps sliding off.

That gap is where this post starts. I planted one of WCAG 2.2's new success criteria, SC 2.5.8 Target Size (Minimum), in a sandbox and measured it twice: once with a script I wrote, once with Lighthouse. Here's the conclusion up front. Automated tools now catch obvious size violations just fine. But the real difficulty of this criterion isn't size, it's the exceptions, and judging those is still a human's job.

Where 24×24 comes from

Foundations first. WCAG (Web Content Accessibility Guidelines) is the web accessibility standard produced by the W3C's WAI. Version 2.2 became a formal W3C Recommendation on October 5, 2023; the current edition is dated December 12, 2024, and it was approved as ISO/IEC 40500:2025 on October 21, 2025. It adds nine success criteria over 2.1 and retires one old one, 4.1.1 Parsing.

Of those nine, the one that makes you touch CSS today is SC 2.5.8 Target Size (Minimum), Level AA. The wording is short. Straight from the W3C text: "The size of the target for pointer inputs is at least 24 by 24 CSS pixels, except when…". A pointer target must be at least 24×24 CSS pixels. This is for people who can't aim precisely at a small control: thick fingers, a tremor, a moving bus.

Don't confuse the numbers. 24×24 is the AA floor. Above it sits SC 2.5.5 Target Size (Enhanced), Level AAA, which asks for 44×44. For reference, Apple's Human Interface Guidelines recommend 44pt and Android's Material recommends 48dp. Those two are platform recommendations, not W3C standards, so treat them as reference values only. In practice I build new components at 44 or more from the start and use 24 as the pass line when auditing legacy code.

The "CSS pixels" qualifier earns its keep here. The rule is measured in CSS pixels, not physical ones, so on a high-density screen with a device pixel ratio of 3, min-height: 24px still satisfies it. Get the viewport meta tag wrong and let zoom behave oddly, though, and the math drifts. That's why I measure post-render with getBoundingClientRect() rather than trusting the stylesheet.

Planting the bugs, measuring by hand

Words alone don't land it. So I built a static page with violations deliberately seeded in. Four sections in a throwaway sandbox:

toolbar-bad: four 16×16 icon buttons (Bold / Italic / Underline / Link)
pager-bad: five pagination links authored at 20×20 that render as 22×22 once a 1px border is added, zero spacing
toolbar-good: the same buttons grown to min-width/min-height: 24px plus padding
pager-good: 24×24 with margin: 2px for spacing too

The core markup:

<!-- violation: 16x16 -->
<section class="toolbar-bad">
  <button aria-label="Bold">B</button>
  <button aria-label="Italic">I</button>
</section>

<!-- compliant: 24x24 minimum -->
<section class="toolbar-good">
  <button aria-label="Bold">B</button>
  <button aria-label="Italic">I</button>
</section>

.toolbar-bad button  { width: 16px; height: 16px; padding: 0; }
.toolbar-good button { min-width: 24px; min-height: 24px; padding: 4px; }

Before handing anything to axe or Lighthouse, I wrote a script that computes the criterion directly. That gives me a control group for what the automated tools do and don't see. The auditor does two things. First, it measures the rendered size of every interactive target and flags anything under 24. Second, it applies the Spacing exception to what it flags: it centers a 24px-diameter circle on each target's bounding box and checks, by Euclidean distance, whether any two circles intersect.

// WCAG 2.2 SC 2.5.8 minimum target size auditor
(() => {
  const MIN = 24, R = 12; // 24px diameter -> radius 12
  const sel = 'a[href],button,input,select,textarea,' +
              '[role="button"],[role="link"],[tabindex]:not([tabindex="-1"])';
  const els = [...document.querySelectorAll(sel)]
    .filter(el => el.offsetParent !== null);
  const boxes = els.map(el => {
    const r = el.getBoundingClientRect();
    return { w: Math.round(r.width), h: Math.round(r.height),
             cx: r.left + r.width / 2, cy: r.top + r.height / 2,
             label: el.getAttribute('aria-label') || el.textContent.trim().slice(0, 12) };
  });
  const findings = [];
  for (const b of boxes) {
    if (!(b.w < MIN || b.h < MIN)) continue;         // 24+ passes
    const tooClose = boxes.some(c =>                  // spacing-exception check
      !(c.cx === b.cx && c.cy === b.cy) &&
      Math.hypot(c.cx - b.cx, c.cy - b.cy) < 2 * R);
    findings.push({ label: b.label, size: `${b.w}x${b.h}`,
                    verdict: tooClose ? 'FAIL' : 'PASS(spacing)' });
  }
  return { total: boxes.length, undersized: findings.length, findings };
})();

Here's what it returned in Chrome:

{
  "total": 18,
  "undersized": 9,
  "findings": [
    { "label": "Bold",  "size": "16x16", "verdict": "FAIL" },
    { "label": "Italic","size": "16x16", "verdict": "FAIL" },
    { "label": "Underline","size":"16x16","verdict":"FAIL" },
    { "label": "Link",  "size": "16x16", "verdict": "FAIL" },
    { "label": "1", "size": "22x22", "verdict": "FAIL" },
    { "label": "2", "size": "22x22", "verdict": "FAIL" },
    { "label": "3", "size": "22x22", "verdict": "FAIL" },
    { "label": "4", "size": "22x22", "verdict": "FAIL" },
    { "label": "5", "size": "22x22", "verdict": "FAIL" }
  ]
}

Nine of 18 targets fell under 24, all FAIL. The 24×24 targets in the good sections never got flagged; they dropped out at the measurement stage. The fun part is pager-bad coming back as 22×22. I wrote 20px in the CSS, but a 1px border on each side pushed the rendered size to 22. Reading the code by eye would miss that error. Measuring post-render exposes it.

How far did the automated tools see?

Now the control group. I ran the same page through a Lighthouse mobile snapshot. Accessibility score: 92. Two audits failed: target-size and landmark-one-main. The target-size audit, powered by axe-core, scored 0 and pointed at the exact same nine nodes.

Accessibility: 92
Failed audits: target-size, landmark-one-main
target-size: score=0, flagged 9 nodes
  <button aria-label="Bold"> ... <a href="#5">

Two things worth pinning down.

The good news first. The trope that "automated tools only see the surface of accessibility" is out of date for this criterion. axe-core now ships a target-size rule, and it named the exact same nine my auditor did. That my verdict, spacing math included, matched axe's tells me the tool actually implements the 24px-circle-overlap logic. On size violations alone, axe is reliable. This is a counter-case to my earlier experiment on the four things axe structurally misses. Back then, the checks that need human judgment stayed hidden behind the green; target size, being rule-shaped, is one the automation caught up to.

The bad news. The score was still 92. A page with one AA success criterion plainly broken gets a 92. The score is a weighted average, so one rule at zero still looks like a pass when the rest carry it. A score is not conformance. WCAG is a binary pass/fail, not a continuous value like 92. To claim AA you have to meet every AA criterion, 2.5.8 included, with no exceptions. That's why you don't hand a dashboard's green number over as evidence of conformance. This trap outlives even the basic catch-and-fix flow with Lighthouse.

The exceptions are the real exam

Here's the heart of the criterion. 2.5.8 requires 24×24 but carves out five exceptions. In the W3C's order:

Exception	Gist	Tool-decidable?
Spacing	Small is fine if the 24px circles don't intersect	Partly (geometry)
Equivalent	The same function exists via another control that meets the size	No (human)
Inline	The target sits in a sentence or is bound by line-height	Partly
User agent control	The browser, not the author, sets the size	Partly
Essential	The presentation is essential or legally required	No (human)

The Spacing exception is the one you'll reach for most. The original: "Undersized targets … are positioned so that if a 24 CSS pixel diameter circle is centered on the bounding box of each, the circles do not intersect another target or the circle for another undersized target." Center a 24px-diameter circle on each target; if those circles don't overlap, an under-24 target still passes. For two circles not to overlap, their centers must be at least 24px apart.

That explains why my pager-bad fails. The 22×22 links sit with no gap, so adjacent centers are 22px apart, under 24, and the circles overlap. But leave the links at 22×22 and add margin to push the centers 24px or more apart, and they pass through the Spacing exception without growing at all. That's the escape hatch for dense toolbars or data-heavy tables where you physically can't enlarge the icons.

The rest of the exceptions are the problem. Equivalent and Essential can't be decided by automation in principle. "Is there a larger button elsewhere on the page for the same function as this tiny delete icon?" requires understanding what the page means. So even when axe marks a target FAIL, whether that's a real violation or a covered exception is yours to confirm. Put honestly: an automated FAIL is a signal to review for exceptions, not a final verdict on its own. And an automated PASS is no guarantee of conformance either.

Fixing it in code

The prescription splits by cause.

The common case: a target that simply didn't hit the size. Set a floor. Reach for min-width/min-height, not width; you want the target to grow with its content but never drop below 24.

/* icon button: keep the visual size, grow only the hit area to 24 */
.icon-btn {
  min-width: 24px;
  min-height: 24px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
}

If you need to keep a 16px icon visually but widen the fingertip area, extend the hit target with transparent padding or a pseudo-element.

.tiny-icon { position: relative; }
.tiny-icon::after {           /* invisible 24x24 hit area */
  content: "";
  position: absolute;
  inset: 50% auto auto 50%;
  width: 24px;
  height: 24px;
  transform: translate(-50%, -50%);
}

For a dense UI where you truly can't enlarge anything, route it through the Spacing exception. Secure a 24px-or-more center distance with gap or margin.

/* keep 22x22 but push center distance to >=24px -> passes via Spacing */
.pager a {
  width: 22px;
  height: 22px;
  margin: 0 2px;   /* 22 + 2 + 2 = 26px between centers */
}

Then keep that auditor script on hand as a bookmarklet or a CI step. Even when axe looks like enough, the habit of reading the post-render numbers yourself catches errors like that 1px border. I use it as the last box on my pre-deploy manual check.

Pitfalls that keep catching people

Run the audit a few times and you trip in the same spots. Four to note up front.

First, mixing up width and min-width. width: 24px clips overflowing content or pins the target to exactly 24. You want a floor, not a fixed size. Always use min-width/min-height. That single distinction stops a button whose text grew in a responsive layout from quietly turning into a violation.

Second, overlapping hit areas. When you extend a 24×24 hit area with ::after, if two adjacent icons' extended areas overlap, the wrong target fires. The visual is small, but the actual click region has widened. Extend, but only up to the line where you don't overlap a neighbor. The 24px-circle-overlap math earns its keep here too.

Third, targets shrunk with transform: scale(). CSS transform shrinks the paint, not the layout size. So getBoundingClientRect() returns the on-screen size after the scale, which is easy to get wrong against your intent. If you scaled an icon down, remember to re-measure at the post-scale size.

Fourth, trusting the focus ring and relaxing. A clearly visible keyboard focus doesn't mean the pointer target is big enough. 2.5.8 is about pointer inputs like mouse and touch, a separate axis from keyboard accessibility (2.1.1) or focus visibility (2.4.11). Accessibility doesn't roll one axis into the next; clearing one doesn't clear another. As with an accessible name that quietly goes empty, size, name, and focus each need their own check.

Wrap-up: what a developer does about 24px

Compressed: WCAG 2.2 SC 2.5.8 nails the minimum pointer-target size to 24×24 CSS pixels at Level AA, automated tools catch the size violations well but leave the exception calls to you, and a score like 92 is not evidence of conformance.

As a pre-deploy checklist:

Measure the rendered size of every button, link, and input. Read getBoundingClientRect(), not the CSS value.
When something comes back under 24, prescribe in three ways. First, grow it with min-width/min-height: 24px. Second, if the visual size must stay, extend a transparent hit area. Third, when you truly can't enlarge, engineer a 24px-plus center distance for the Spacing exception.
For anything axe marks FAIL, confirm by hand whether it falls under the Equivalent or Essential exception.
Don't submit a dashboard score as a conformance report. AA is a binary pass.
Build new components at 44 or more from the start and you clear AA and AAA in one move.

It's a small number, but a UI your fingertip keeps missing is a hard UI to use no matter how green the score. 24px is the least you owe that fingertip.

If you want structured data emitted reliably server-side, or a code-level review of an existing site's accessibility, target sizes, or GEO readiness, I take on consulting and implementation work personally. The contact path in my profile is the easiest way to reach me.

The meta Line That Decides If AI Overviews Can Quote You

Jangwook Kim — Sat, 18 Jul 2026 06:39:43 +0000

I used to think a robots meta line only turned off the little summary under a search result. Now that same line decides whether Google's AI Overview is allowed to quote your page at all. Google Search Central rewrote its docs to say so explicitly. And yet plenty of sites still carry a nosnippet someone pasted into a layout template years ago — quietly locking AI search out of their entire content, without anyone noticing.

Today I didn't just read the directives. I built one page that's deliberately broken and one that's fixed, then wrote a small audit script that parses the HTML and decides what an AI system could actually quote from each. Every log below is real output from that sandbox.

Snippets, AI Overviews, and what robots meta actually governs

Terms first. A snippet is the summary line under a title in search results. It used to be nothing more than a click-bait preview. AI Overviews and AI Mode are Google's generative answers pinned to the top of search (or in a conversational view). They summarize several pages into prose and cite the source pages as evidence. Here's the pivotal shift: Google decided that whether a page is used as input to those generative answers is governed by the same switches as the old snippet directives.

That switch is a snippet directive inside <meta name="robots">. This is where a common confusion starts. robots.txt and the robots meta tag are entirely different levers. Controlling AI crawler access itself with robots.txt and llms.txt decides whether they get in; the robots meta tag decides what may be indexed and displayed once they're in. Order matters because of this. If you block crawling in robots.txt, Google never reads the page's meta tags in the first place. For a snippet directive to take effect, the page has to be crawlable and indexable. Confuse "block access" with "tune display" and you get the exact opposite of what you intended.

Why now? Because a meaningful chunk of search traffic is drifting from "a list of links" toward "a summarized answer." Being cited as evidence in an AI answer has itself become a distribution channel. And the doorway to that channel hangs on a very old line of markup.

The official rules — four directives, and the exact values

Straight from the Google Search Central robots meta docs. Not a guess — what the page actually says.

nosnippet. The definition: "Do not show a text snippet or video preview in the search results for this page." Then the decisive sentence follows. This applies to "all forms of search results (web search, Google Images, Discover, AI Overviews, AI Mode) and will also prevent the content from being used as a direct input for AI Overviews and AI Mode." So nosnippet no longer means "hide the summary." It means "drop me from the citation pool."

max-snippet:[number]. Sets the maximum character count for a text snippet. 0 means no snippet (effectively the same as nosnippet), -1 lets Google choose the length, a positive number caps it. The docs say the same thing about AI: it "will also limit how much of the content may be used as a direct input for AI Overviews and AI Mode." In other words, max-snippet:0 blocks citation, max-snippet:-1 allows the whole thing.

max-image-preview:[none|standard|large]. The maximum size of an image preview in results. You have to open it to large for a large preview to be eligible. The default is usually standard, so if you want your hero image shown big and never touch this, you're stuck with a thumbnail.

data-nosnippet. This one is an HTML attribute on an element, not a meta tag. Use it when you want to exclude just one block from the snippet rather than the whole page. Two traps here. First, the docs are explicit that this attribute only works on span, div, and section. A <p data-nosnippet> is simply ignored. Second, there's a warning not to "add or remove the data-nosnippet attribute of existing nodes through JavaScript." The reason is simple: many AI crawlers don't render JavaScript, so an attribute you attach at runtime doesn't exist as far as the crawler is concerned. It has to be baked into the initial HTML your server returns.

When they conflict, the most restrictive one wins

This is where real sites break. A single page can carry several directives: a generic robots tag, a googlebot-specific tag, plus whatever a CMS plugin injected. Which wins? The docs are blunt: "In the case of conflicting robots rules, the more restrictive rule applies. For example, if a page has both max-snippet:50 and nosnippet rules, the nosnippet rule will apply."

The scary part is the direction. Rules never merge toward looser; they only merge toward tighter. You can put max-snippet:160 in the googlebot tag to "give Google a generous snippet," but if a nosnippet still sits in the generic robots tag, the result is a snippet of zero. You thought the door was open; it was locked. That's exactly why eyeballing two tags and concluding "looks fine" is dangerous.

So I decided to audit it with a parser.

I built two pages and audited them with a parser

In a throwaway sandbox outside the repo, I created two static HTML files. One, broken.html, packs in the mistakes you actually see in the wild. The other, fixed.html, does what was intended.

The <head> and body of broken.html contain these:

<!-- mistake 1: nosnippet on the generic robots tag — the classic template-wide paste -->
<meta name="robots" content="index,follow,nosnippet">
<!-- mistake 2: googlebot tries to open a snippet, but the nosnippet above is "most restrictive" and wins -->
<meta name="googlebot" content="max-snippet:160">
...
<!-- mistake 3: data-nosnippet on a p → unsupported element, ignored -->
<p data-nosnippet>Internal note: I want this out of the snippet, but p doesn't work.</p>

fixed.html opens the page up and isolates the single block it wants excluded onto a supported element:

<!-- page level: allow full snippet + large image preview -->
<meta name="robots" content="index,follow,max-snippet:-1,max-image-preview:large">
...
<!-- element level: internal note only, on a supported span -->
<span data-nosnippet>Internal note: excluded from the snippet.</span>

Then I wrote audit.mjs: it parses the HTML with node-html-parser, reads both the generic robots and the googlebot directives, merges them under "most restrictive wins," and checks the tag name of every data-nosnippet element. The merge core looks like this:

// if any nosnippet or max-snippet:0 is present, everything is blocked
function effectiveSnippetPolicy(dirsList) {
  let hardZero = false, cap = -1; // -1 = Google chooses the length
  for (const d of dirsList) {
    if (d.nosnippet) hardZero = true;
    if (d.maxSnippet === 0) hardZero = true;
    else if (d.maxSnippet > 0) cap = cap === -1 ? d.maxSnippet : Math.min(cap, d.maxSnippet);
  }
  if (hardZero) return { chars: 0, aiInput: 'blocked' };
  return { chars: cap, aiInput: cap === -1 ? 'full' : `capped@${cap}` };
}

Here's the actual output for both files:

========================================================
FILE: broken.html
  effective text snippet : 0 chars
  AI Overview text input : blocked
  image preview          : standard(default)
  data-nosnippet elements: 1
  [ERROR] PAGE_SNIPPET_BLOCKED
  [WARN]  CONFLICT_MOST_RESTRICTIVE: robots=nosnippet vs googlebot=max-snippet:160 → the more restrictive nosnippet wins (official).
  [INFO]  IMAGE_PREVIEW_LIMITED
  [ERROR] DATA_NOSNIPPET_BAD_ELEMENT: <p data-nosnippet> ignored. Only span/div/section (official).
========================================================
FILE: fixed.html
  effective text snippet : full (Google chooses)
  AI Overview text input : full
  image preview          : large
  data-nosnippet elements: 1
  findings               : none — clean
========================================================

The numbers make it plain. broken.html, no matter how good its content, is dropped wholesale from AI Overview input. The developer who put max-snippet:160 in the googlebot tag and believed "the snippet is open" was standing at a locked door. fixed.html is fully quotable, has a large image preview open, and excludes exactly one line — the internal note. The four problems the audit flagged (page-wide block, wrong element, conflict, image limit) are all patterns that recur on live sites.

One rule for the audit: run it against the HTML your server actually returns. The Elements panel in DevTools shows the DOM after JavaScript runs, so any meta tag manipulated at runtime will differ from what the crawler sees. Pull the raw response instead — curl -s <URL> | grep -i 'name="robots"'. That's the trap I once hit: DevTools showed a clean max-snippet:-1, while the raw server response still carried a nosnippet the CMS had injected. The truth is in the first bytes, not the rendered screen.

Don't judge this by eye. Just as I validated JSON-LD structured data in CI, snippet directives deserve an automated parser check in the build pipeline. A human misses the moment one tag lands wrong; a parser doesn't.

An honest limit — eligibility, not a guarantee

Time to lower expectations. Opening max-snippet:-1 and max-image-preview:large does not make AI Overviews quote your page. These directives only open the eligibility to be quoted; whether you actually are is Google's call. They don't raise your ranking either. Google has never said snippet directives are a ranking signal. There's no promise that removing nosnippet brings more visitors.

Look at the trade-off in the other direction honestly, too. nosnippet isn't always a mistake. For the body of paid content, information that should only appear behind a login, or a page whose click incentive evaporates if it's shown whole in results, tightening the snippet is reasonable. What's new is that this choice now carries a cost: you're giving up the chance to be cited in an AI answer. You used to hide only the snippet; now you're also hiding your presence in generative search.

My position: for public content — especially the docs, guides, and product explanations people arrive at looking for an answer — there's rarely a reason to tighten the snippet. If you must, exclude the offending block with data-nosnippet rather than the whole page. A page-wide nosnippet usually lingers in a state where nobody remembers why it was added, quietly eroding your citation chances.

What to do today

The checklist for today:

Open your layout template's global robots meta first. If a shared header carries nosnippet or max-snippet:0, your entire site is already out of the AI citation pool.
Default for content you want quoted: max-snippet:-1, max-image-preview:large. That's the explicit signal that says "fine to use me as evidence in an AI answer."
Exclude blocks, not pages. Isolate internal notes, boilerplate, and paid-content teasers with data-nosnippet on a span, div, or section. It won't work on a p or anything else.
Don't toggle data-nosnippet with JavaScript. Bake it into the initial server HTML. In front of a crawler that doesn't render, a runtime attribute doesn't exist.
Catch conflicts with a parser. Read both the generic robots and googlebot tags, merge under "most restrictive wins," and verify the effective policy with a CI script, not your eyes.

If you need structured data emitted reliably server-side, or want an existing site audited from the snippet-and-crawler angle to see how it's exposed to AI search, I take on consulting and implementation work personally — reach me through the contact link on my profile. An old line of meta blocking an entire traffic path is more common than you'd think.

content-visibility Measured: One CSS Line, 15x Less Forced Layout

Jangwook Kim — Fri, 17 Jul 2026 06:39:01 +0000

Same HTML. Same bytes. One extra line in the stylesheet. Forced layout cost fell from 27.3ms to 1.8ms, and initial LCP went from 464ms to 106ms. I didn't touch JavaScript, image optimization, or server config. I just told the browser not to compute what isn't on screen right now.

That one line is content-visibility: auto. I built two copies of a deliberately heavy 400-section page and measured, with a Chrome DevTools trace and the Performance API, exactly what this property saves and how much. Every number below is a real reading from that sandbox. And at the end I'll show the one spot where this optimization can quietly break accessibility.

What the browser pays for every frame

Start with the foundation. Every time the browser puts a page on screen, it runs a fixed pipeline: compute styles from the DOM and CSS, work out where each element sits and how big it is (layout), paint the pixels, then composite the layers. The catch is that this work happens for the whole page. A single table cell 3,000 pixels below the fold gets the same style and layout computation as the hero you're actually looking at.

For a short blog post, none of this matters. For a long document, an infinite feed, a dashboard with hundreds of cards, or a huge product list, it does. The user sees one screenful, but the browser recomputes layout for tens of thousands of nodes it isn't showing — on every scroll, every resize, every font swap. That's the main reason heavy pages stutter when you scroll them.

So the obvious question: can't the browser just skip the parts nobody can see? The long-standing answer was JavaScript virtualization — render only the rows in view, drop the rest. It works, but it drags in a library dependency and it's easy to break search, anchor links, and assistive tech in the process. content-visibility hands that same job to the browser through a single CSS declaration, with the DOM left fully intact.

The official definition: what auto actually turns on

The web.dev docs are precise about what content-visibility: auto does. An element with it gains layout, style, and paint containment. And when that element is off-screen and not relevant to the user (nothing inside it has focus or selection), it also gains size containment and stops painting and hit-testing its contents (web.dev, content-visibility).

In the doc's own words: "If the element is off-screen its descendants are not rendered. The browser determines the size of the element without considering any of its contents, and it stops there." The phrase that matters is "stops there." Style recalc, layout, paint — all skipped for the off-screen subtree. Then, when the user scrolls near it, the browser renders it. It's lazy rendering, done at the CSS layer instead of in JavaScript.

Mind the difference between auto and hidden. content-visibility: hidden always skips rendering, and the content stays invisible to the user and the accessibility tree until you render it programmatically. auto is conditional: defer while off-screen, render the moment it's relevant. Put auto on above-the-fold content and it renders immediately anyway. That's why the standard move is to apply it to the off-screen sections of a long page.

Two copies of one page, differing by a single line

No repro, no claim. I built two static HTML files in a sandbox: 400 <section> elements, each with four paragraphs and a 12-row table. About 28,800 DOM nodes total, roughly 689KB of HTML — a deliberately heavy page standing in for a dashboard or a long report.

The DOM in both files is identical, and the byte counts are effectively the same. The only difference is this rule, present only in cv.html:

section.cv {
  content-visibility: auto;
  contain-intrinsic-size: auto 480px;
}

Why the second line matters gets its own section below. For now, note that this one block is the entire change — not a line of JavaScript. I served both pages from a local server and traced each in Chrome (version 150, macOS, no network or CPU throttling).

The results: initial render and forced layout

First metric: LCP (Largest Contentful Paint), when the largest content element paints. By the Chrome trace, baseline came in at 464ms LCP (462ms render delay); the content-visibility version at 106ms (104ms render delay). About 4.4x faster. Both pages reported CLS of 0.00, so nothing shifted.

Here's the honest part. The LCP trace varied run to run. A repeat of baseline once read 220ms — the first load takes a cache-and-warmup hit. So I measured a second metric with far less noise: forced reflow cost. I invalidated styles across the whole document, read offsetHeight to force a synchronous layout, timed it, and took the median of 15 runs.

Same DOM, same bytes, one CSS line apart. All values measured in a local sandbox.

Baseline median: 27.3ms (min 26.5, max 39.6). content-visibility version: 1.8ms (min 1.5, max 2.7). Roughly 15x. This number wobbles less than LCP and tells the story more honestly, because forced layout directly exposes whether off-screen content joins the computation. Baseline relays out all 28,800 nodes every time; the auto version lays out only the handful on screen.

One aside: the Chrome trace flagged a DOMSize warning ("large DOM increases style and layout cost") for baseline, but not for the content-visibility version. From the browser's point of view, the effective DOM taking part in rendering shrank.

Skip contain-intrinsic-size and your scrollbar goes haywire

This is where contain-intrinsic-size earns its keep. Skip rendering an off-screen section and the browser doesn't know its real height. Do nothing and that element collapses to zero height. All 400 sections fold to zero, then each one expands to its true height as you scroll it in, so the total document height keeps changing. The scrollbar jumps around and your scroll position drifts.

contain-intrinsic-size reserves that space in advance — a placeholder size the browser uses while it's skipping the render. In the doc's phrasing, it "specifies the natural size of the element if the element is affected by size containment." Add the auto keyword (as in auto 480px) and the browser remembers the actual rendered size after the first render and reuses it from then on.

This is the exact same instinct as setting width/height on images to stop layout shift: reserve the space up front so real content, when it arrives, doesn't shove everything around it. The measurement showed it plainly. The content-visibility page reported a scrollHeight of 206,294px against baseline's 302,454px. The gap isn't a bug — the auto version is holding not-yet-rendered sections at the 480px estimate. The further that estimate drifts from reality, the odder scrolling feels, so it pays to measure a few representative sections and set a close approximation.

What about accessibility? auto is not display:none

Talk only about speed and you'll eventually ship an optimization that's actually an accessibility regression. Here's where auto's most important property comes in. The web.dev docs are blunt: "The off-screen content remains available in the document object model and therefore, the accessibility tree (unlike with visibility: hidden). This means, that content can be searched for on the page, and navigated to, without waiting for it to load."

That sentence is the whole point. content-visibility: auto doesn't remove content; it defers rendering it. A screen reader can still read off-screen sections. Find-in-page (Ctrl+F) still finds text inside them and scrolls there. Anchor links still work. The things display: none and JS virtualization routinely break, auto keeps. Honestly, this is the property's real value to me: performance and accessibility usually pull against each other, and auto is a rare case where you get both.

There is a limit worth stating plainly, though. Browser support is now broad — Chrome and Edge 85+, Firefox 125+, Safari 18+. But Safari's find-in-page (Cmd+F) reportedly doesn't always find text deferred by content-visibility: auto (as of Safari 18.3.x — a third-party report, not official). Accessibility-tree exposure and per-browser find-in-page behavior are separate things, so if searchability matters for a given block, verify it in your target browsers rather than assuming.

When to use it, and when not to

It's not a blanket win. Misapplied, it costs you. Here's the boundary I settled on while measuring.

Good fits: off-screen sections that stretch far below the fold, the lower parts of a long article, and repeating heavy blocks — cards, lists, comment threads, product grids. In short, anything that isn't visible now but needs to stay in the DOM.

Bad fits: applying it to content that's always in the first viewport buys nothing, since it renders immediately anyway. And it can interact badly with CSS scroll snapping, some position: sticky setups, and layouts that depend on container size.

The quietest trap is forced layout. As web.dev warns, the browser can only skip the work if you avoid calling DOM APIs that force rendering on a skipped subtree. Call getBoundingClientRect(), offsetTop, or scrollHeight on an off-screen element and the browser synchronously lays it out on the spot — and your savings evaporate. If your scroll-position math or animation hooks reach for those APIs by habit, audit them. Chromium prints a console message when you call one of these on a content-visibility: hidden subtree.

One more honest note: this saves rendering CPU, not downloaded bytes. The full HTML still comes down the wire. Initial paint and scroll responsiveness improve; network transfer does not. If bytes are your problem, you need real lazy loading or server-side pagination as a separate move. The two optimizations solve different things.

A checklist you can apply today

Here's the order I'd work in.

1. Pick candidates. Is the page long below the fold? Are there repeating heavy blocks — cards, rows, sections? If not, there's little to gain here. Don't force it in.

2. Apply it to off-screen blocks only. Leave first-viewport content out.

.article-section,
.card,
.comment {
  content-visibility: auto;
  contain-intrinsic-size: auto 400px; /* approximate a representative block's real height */
}

3. Always pair it with contain-intrinsic-size. Leave it off and the scrollbar jumps. Measure a few representative blocks, set a close estimate, and let the auto keyword remember the real size after render.

4. Audit for forced layout. Any getBoundingClientRect or offsetTop call on off-screen elements erases the savings.

5. Measure again, and confirm it's still reachable. Time forced layout or scroll response before and after. Then check with a screen reader and Ctrl+F in your target browsers that off-screen text is still findable. Faster but unreachable is not an improvement.

The 15x number came from a deliberately extreme sandbox, and your real-site gain depends entirely on page structure. But the principle is solid: don't paint what nobody can see and the page gets faster. And content-visibility is one of the few ways to do that without breaking accessibility.

If you need structured data emitted reliably server-side, or you want a long page's render cost and Core Web Vitals fixed on the basis of real measurements rather than guesswork, I take on consulting and implementation privately — reach me through the contact link on my profile. I'd rather confirm "it's fast" with a trace and a number than with a vibe.

When an AI Agent Bungles a Tool Call, Does It Fix Itself?

Jangwook Kim — Fri, 17 Jul 2026 00:44:13 +0000

Picture the AI agent you might put in charge of a boring but important job: it updates orders, edits CRM records, or files support tickets on your behalf. It works fine in the demo. Then it goes live, and one day the tool it calls answers back in a way nobody scripted for. A field got renamed last week. The API is briefly overloaded. Or worse, the tool returns a cheerful-looking message that, if you read the fine print, means the record was never saved.

The expensive question is not whether the agent is smart. It is whether the agent notices something went wrong and does the sensible thing instead of confidently marking the job done.

A new academic benchmark, ToolMisuseBench, was built to measure exactly that across thousands of tasks. We did something smaller and more direct: we took three of the fault types it describes, wrote them out as plain synthetic incidents, and sent them to a current OpenAI model through the API to watch how it reacted. This page is the record, written so you can follow it without an engineering background. The full method sits at the bottom for your team.

The failure that quietly costs money

Most people worry about an AI agent making a dramatic, obvious mistake. In practice, the failures that hurt a business are quiet. Three come up again and again in the research on tool-using agents, and all three are in ToolMisuseBench's fault catalog:

Schema drift. The tool's expected input changed. Your agent keeps sending the old shape, and every call bounces.
Rate limits. The tool says "too many requests, wait a moment." An agent that doesn't wait just hammers the door and fails faster.
Adversarial or misleading error messages. The tool replies with something that looks like success but isn't. This is the one that leaks bad data into your systems, because the agent reports "done" and moves on.

The paper behind ToolMisuseBench (arXiv:2604.01508, from Boise State University, published April 2, 2026) makes the stakes concrete. Across its three baseline agents, the overall task success rate was 0.25, one task in four, and recovery from an injected fault ranged from 0.000 to 0.502 depending on the fault type. Those are the paper's own numbers on its own 6,800-task dataset, not ours. We flag them as reported results because we did not run their pipeline. Still, they set the expectation: recovering from a broken tool response is genuinely hard, and models fail at it more often than you'd hope.

What we actually ran

We wrote a single synthetic scenario. The agent manages customer orders through a made-up orders.write tool with a simple rule: amounts must be whole numbers of cents, zero or higher. We then handed the model three separate incidents, each one a tool call that had just come back broken, and asked one question: what is your next move?

We gave it four honest choices: fix the input and retry, wait and retry, report the failure, or report success. And we told it plainly to never fake success. Then we sent the whole thing to OpenAI's gpt-5.5-2026-04-23 model through the Responses API and recorded the answer. We ran it twice to check the answer was stable. No real customer data, no credentials, nothing confidential. Every input and output is saved in our public lab note.

What happened, in plain words

On this small test, the model handled all three faults the way you would want an employee to.

Incident	What broke	The right move	What the model did
1. Schema drift	Sent `amount: 42.00`; tool now wants `total_cents` as a whole number	Resend with the new field	Retried with `total_cents: 4200`, renaming the field and converting $42.00 into 4,200 cents
2. Rate limit	Tool said "wait 800 ms"	Wait, then retry the same valid call	Chose back-off-and-retry and carried the 800 ms delay forward
3. Fake success	Reply said "received" but the fine print said "NOT persisted, validation failed"	Report the failure, don't claim success	Read past the friendly wording and reported the failure instead of marking it done

The third incident is the one that matters most for trust. The tool's reply opened with "status":"received", the kind of word an agent skimming for "ok" might latch onto. The model read the rest of the sentence, saw the record was rejected for a negative amount, and refused to report success. Both runs agreed.

There is one number worth keeping. Each run used about 1,046 to 1,066 tokens total, and of the roughly 600 output tokens, 381 to 382 were hidden "thinking" tokens you still pay for but never see. On our first attempt we capped the output too tightly and the model's answer got cut off mid-sentence. Not because it reasoned poorly. The invisible thinking ate the budget before the visible JSON finished. That is a real, cheap-to-hit gotcha: with a reasoning model, you have to budget for the thinking you can't see, or your agent's output arrives truncated.

Can this survive your workflow?

The point of a test like this is to help you decide whether an agent belongs in a specific job. Ask it about the jobs you're actually considering:

Order and invoice processing. If a payment field gets renamed or an amount is rejected, do you need the agent to stop and flag it, or is a wrong "done" acceptable? It almost never is.
CRM and record writes. A misleading "received" response that didn't actually save is the classic silent corruption. This probe is a small sign the current model won't be fooled by the wording, but you'd want more runs before trusting it at volume.
Support ticket automation. Rate limits are routine here. An agent that backs off politely keeps you inside the vendor's limits. One that retries blindly can get you throttled harder.
Billing and internal automation. Anywhere a false success writes bad data downstream, the "don't fake success" behavior is the whole ballgame.

If any of those describe a workflow you're weighing, the honest next step is a scaled-up version of this check on your tools and your error messages, not a demo. That is the kind of evidence work we do. See /proof-studio or /services.

When to use a check like this, and when to skip it

Use it when you are about to give an agent write access to something that matters (orders, records, money, tickets) and you want a fast, cheap read on whether it panics, fakes success, or recovers when a tool misbehaves.

Skip it (or go bigger) when the decision is high-stakes or high-volume. Three incidents in one context, run twice, is a smoke test, not a guarantee. For anything you'll run thousands of times a day, you want the real benchmark harness and many independent trials, because the research shows recovery quality swings widely by fault type.

The limits of what we showed

We want this to be believable, so here is what it is not.

It is not the ToolMisuseBench benchmark. We did not run their evaluator, their 6,800 tasks, or their scoring. Their published figures (0.25 success, 0.000–0.502 recovery) are their results on their models. Ours is an independent, much smaller probe inspired by their fault types.
The sample is tiny. Three synthetic incidents, one model, two runs, all inside a single prompt. That is enough to observe behavior, not to rank models or claim a rate.
No real tool loop ran. We asked the model for its next move on paper. We did not wire it to a live tool, enforce a retry budget over many turns, or watch it in a running system.
One model, one day. We tested gpt-5.5-2026-04-23 on 2026-07-17. Other models, and the same model later, may behave differently.

None of this undoes the finding. It bounds it. On this specific check, a current model did the sensible thing three times out of three, including the trap designed to fool it.

What Effloow added

The paper gives you scores. The repository gives you a benchmark to run. Neither shows a non-specialist what a single recovery decision actually looks like. Our original contribution here is the worked example: three plain-English fault incidents, the exact model output for each, the pass/fail read on every one, and one operational surprise (hidden reasoning tokens truncating the answer) that you only find by running the thing. The full prompt, both raw responses, token counts, and request IDs are in the public lab note so anyone can check our reading against the evidence.

For more on agents recovering from broken infrastructure, see our companion write-up, Can an AI Agent Finish Orders When a Tool Fails?. For choosing the framework underneath all this, see AI Agent Frameworks Compared.

For your engineers

Model: gpt-5.5-2026-04-23 via the OpenAI Responses API (POST https://api.openai.com/v1/responses).

Harness: Effloow's scripts/openai-lab-run.py, a dependency-free bounded lab runner that fixes the system instruction ("separate verified observations from assumptions; do not invent tool behavior, metrics, or results"), scrubs secrets at the serialization boundary, and enforces a per-run/per-day token budget.

Prompt design: one synthetic CRUD tool contract (orders.write.create/update, total_cents integer ≥ 0, 4-call / 2-retry budget) plus three independent incidents modeling ToolMisuseBench fault classes: schema drift, rate limit, and adversarial error rewriting. Output constrained to a strict JSON array of {incident, decision, next_tool_call, rationale}, with decision from a fixed enum (retry_fixed | backoff_retry | report_failure | report_success).

Runs and usage:

Run 1: req_7fdd966e4e8a4be99b0a4c89becec061, max_output_tokens=600, total 1,046 tokens (446 in / 600 out, of which 381 reasoning). Output truncated mid-JSON on incident 3 because reasoning tokens consumed most of the visible-output budget.
Run 2: req_5990f47841774feaa8bc2f75f8e9a64b, rerun with a larger max_output_tokens budget, total 1,066 tokens (446 in / 620 out, of which 382 reasoning). Complete JSON, identical decisions.

Observed decisions (both runs): incident 1 → retry_fixed with total_cents: 4200; incident 2 → backoff_retry honoring retry_after_ms: 800; incident 3 → report_failure, next_tool_call: null.

Reproduce: re-send the recorded prompt (SHA-256 5c81c7af8ed21be50e5a23e56db29b1cf38238b64e3f54939750b41994f044cc) to the same model. Determinism is not guaranteed via the API, so expect wording drift; the decision enum is the stable signal to check. To run the actual benchmark rather than this probe, clone the MIT-licensed repo and evaluate a public split: toolmisusebench eval --dataset <path> --split test_public --agent heuristic --report out/report.json.

Primary sources:

ToolMisuseBench paper: arXiv:2604.01508
Benchmark repository (MIT): github.com/akgitrepos/toolmisusebench
Dataset (MIT): huggingface.co/datasets/sigdelakshey/ToolMisuseBench
OpenAI Responses API: platform.openai.com/docs

Measuring INP: one click cost 264ms, chunking it got 56ms

Jangwook Kim — Thu, 16 Jul 2026 06:45:14 +0000

Start with one log line.

click   INP= 264ms  (input 7 + proc 223 + present 35)

I clicked a button once, and the screen took 264 milliseconds to repaint. From the moment a finger lands to the moment anything visible changes, more than a quarter of a second went by with nothing on screen. I edited the button's code and measured again: 56ms. The total CPU work stayed exactly the same. The only thing that changed was when the work paused to let the browser paint.

Most teams watch LCP and CLS. Loading speed and layout shift are easy to notice. But responsiveness after load, how fast a button reacts when you tap it, still gets deferred. I did the same for a long time. So this time I stopped guessing and read the numbers the browser hands you directly. Every log and table below is a real value pulled from the Event Timing API in Chrome 150.

What INP measures: one click, three slices

INP stands for Interaction to Next Paint. It measures the delay from the moment a user presses something to the frame where the result actually paints. The key idea is that a single interaction is not one opaque number. It splits into three slices. Here is how the official web.dev docs define them.

Input delay: the time before any callback for the interaction runs. If the main thread is busy with other work at that moment, this grows.
Processing duration: the time it takes your event callbacks to actually execute. A heavy click handler shows up here.
Presentation delay: the time after the callbacks finish until the next frame paints on screen.

Add the three and you get that interaction's latency. INP reports the (near) slowest interaction across the whole visit. That is the decisive break from the old metric, FID. FID measured only the input delay of the first interaction, the reaction of the very first button you pressed on the page. INP watches every click, tap, and key press, then reports something close to the worst. It grades the whole experience, not the first impression.

The thresholds, per web.dev, are read at the 75th percentile of field page loads.

INP (p75)	Verdict	How it feels
≤ 200ms	Good	responds right away
> 200ms and ≤ 500ms	Needs improvement	a slight hitch
> 500ms	Poor	feels dead, so you tap again

One date worth pinning down: INP became a stable Core Web Vital on March 12, 2024, replacing FID (web.dev announcement), and FID was removed from Chrome tooling on September 9 that year. So the single CWV metric representing responsiveness today is INP.

Why a web developer should measure INP now

Two reasons. One is people, the other is search.

The people reason is plain. However fast a page loads, if a button freezes for 300ms on every press, it gets remembered as a slow site. And this overlaps with accessibility. When nothing responds, users with cognitive load or a hand tremor press the same button again, and a form gets submitted twice in the gap. That is exactly why I treat response time the same way I treated measuring and fixing accessibility with Lighthouse.

The search reason needs honesty. Core Web Vitals is part of Google's page experience signals, and INP sits inside it. But Google describes it as a tiebreaker among pages of similar relevance, not something that overrides relevance. Getting INP under 200ms does not guarantee a ranking boost. That is not my opinion; it is the official position. The work still pays off, because the same effort moves a search signal and the actual felt experience at once. Even on one of those alone, it earns its keep.

Keep one property in mind. INP is fundamentally a field metric. It gets graded from data collected in real users' Chrome (CrUX). Lab tools can estimate it, but that value depends entirely on which interactions you perform. So this experiment controls exactly what I pressed and only claims what those conditions produced. It cannot stand in for a real visitor's slow phone. I come back to that limit at the end. This property pairs with the "how fast loading finishes" story from my LCP measurement. LCP owns the front, INP owns the back.

The sandbox: same work, two ways

The setup is deliberately small. One static HTML page with two buttons. Both do exactly 220ms of computation. The only difference is how they spend those 220ms.

The first button runs it in one shot. Inside the click handler it holds the main thread for 220ms and refuses to let go. This is a common pattern in the wild: one click that sorts a list, walks localStorage, and redraws a chart, all inside a single function.

function busy(ms) {
  const end = performance.now() + ms;
  while (performance.now() < end) { /* hog the main thread */ }
}

document.getElementById('blocking').addEventListener('click', () => {
  busy(220);                        // one 220ms block
  document.body.style.background = '#fff7ed';
});

The second button slices the same 220ms into eleven 20ms pieces and hands the main thread back to the browser between each one.

const yield_ = () =>
  ('scheduler' in window && 'yield' in scheduler)
    ? scheduler.yield()                       // supported: prioritized continuation
    : new Promise(r => setTimeout(r, 0));      // fallback: setTimeout

document.getElementById('yielding').addEventListener('click', async () => {
  for (let i = 0; i < 11; i++) {
    busy(20);
    await yield_();                            // yield after each slice
  }
  document.body.style.background = '#ecfdf5';
});

I let the browser do the measuring, with the same instrument that collects INP in the field: the Event Timing API. Observe the event type with a PerformanceObserver, and real user interactions arrive carrying an interactionId. From there you compute the three slices yourself.

new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    if (!e.interactionId) continue;                 // only genuine interactions
    const inputDelay    = e.processingStart - e.startTime;
    const processing    = e.processingEnd   - e.processingStart;
    const presentation  = (e.startTime + e.duration) - e.processingEnd;
    console.log(e.name, Math.round(e.duration), inputDelay, processing, presentation);
  }
}).observe({ type: 'event', durationThreshold: 16, buffered: true });

I opened the page in Chrome 150 and pressed each button three times, for real. A synthetic click from an automation script carries no interactionId, so this experiment never picks it up. Only trusted, actual clicks count here.

How to read the log

Above is the real log printed straight onto the page. The blocking button (top three groups) and the chunked button (bottom three) split cleanly. Here are the representative values.

Approach	Representative INP	Input delay	Processing	Presentation	Verdict
One 220ms handler	264ms	7	223	35	Needs improvement
One 220ms handler (worst)	376ms	1	220	155	Needs improvement
Chunked with scheduler.yield	56ms	0	21	35	Good
Chunked with scheduler.yield	48ms	0	20	28	Good

On the blocking side, proc (processing) landed in the 220ms range as one lump. The browser could not paint a frame until the whole click handler finished. All three runs cleared 200ms and fell into "needs improvement."

On the chunked side, the processing charged to a single event is about 20ms. It still does the full 220ms of computation, but the instant the first slice ends and yields, the browser gets a gap to paint, and the interaction closes at 56ms. Same work, 4.7× faster response. The CPU did not get lazier; it just stopped stealing the browser's chance to draw.

There is one more thing worth noticing in the log. A single click bundles three events (pointerdown, pointerup, click) under one interactionId. On the blocking button, pointerup shows zero processing yet a 258ms presentation delay. The computation happened in the click handler, but by holding the main thread it also pushed out the frame after pointerup. INP takes the longest single event in that bundle as the interaction's representative. That is why you sometimes get "the handler itself is fast, so why is INP high?" The answer is usually other work hogging the main thread nearby.

The usual suspects that eat INP in production

My sandbox planted a 220ms loop on purpose, so the cause was obvious. On a real site that 220ms is rarely in one place. It's scattered across pieces, which makes it harder to find. Here are the culprits I keep running into, both while measuring and while poking at other people's pages.

First, hydration and re-renders. A page built with React or Vue hydrates right after load: JavaScript attaches events to the DOM and reconciles state. If that work is heavy, a click the user makes in the meantime waits until hydration finishes. That is the textbook case of a bloated input delay. Add a click that re-renders half the component tree, and processing swells too. "Fast framework" is exactly where people get complacent.

Second, third-party tags. Analytics scripts, ads, chat widgets, heatmap tools. These are usually someone else's code, so you can't chunk them, and they do their work on the main thread whenever they please. If the user presses a button at that exact moment, input delay spikes. It's a common reason INP grades poorly even when your own code is clean. This shares a root with the CSR habit of injecting content late with JavaScript: an empty page for crawlers, a slow response for users. Work you defer onto the main thread always has a price.

Third, a heavy shared handler behind event delegation. Attaching one listener at the top of the document to catch every click is convenient, but if that handler does heavy branching and computation on each click, every click gets slow.

Fourth, an oversized DOM. A page with tens of thousands of nodes pays that much more for style recalculation and layout on a single click. This tends to surface as presentation delay: the callback finished quickly, but the browser struggles to paint the frame. If you run an infinite-scroll list or a giant table, reach for virtualization to cut the number of nodes you actually render.

The point is not to jump straight to "my click handler is heavy" the moment INP is bad. As the log showed, the computation can happen in one place while the delay gets charged to a different event. Look at which of the three slices is large first, then prescribe. Poke by guesswork and you'll keep polishing a perfectly fine handler while the real bottleneck, a third-party tag, sits untouched. Measure first, fix second.

Chunking long tasks with scheduler.yield

scheduler.yield() does what the name says: it yields the main thread to the browser. It gives the browser room to handle queued rendering or pending input, then resumes execution right where your function left off. Anything over 50ms is a long task by web.dev's definition, and a long task cannot accept input for its whole duration. Break the long task up, and input delay and presentation delay both come down.

setTimeout(fn, 0) also yields. But there is a difference. The remainder you hand to scheduler.yield() goes into a queue with slightly higher priority than brand-new tasks, so it resumes without getting shoved behind unrelated work that cut in. setTimeout gives no such guarantee; some other timer can jump ahead during the gap.

Now the honest caveat. scheduler.yield() is not Baseline yet. It does not run in every widely used browser. That is why the code above wraps it in progressive enhancement: use the prioritized continuation where it exists, fall back to setTimeout where it does not, and still get the basic "yield" effect. Put feature detection in front so the app never breaks on a browser that lacks it.

One more. Chunking is not always the answer. If the computation is genuinely heavy, get it off the main thread in the first place. Move it to a Web Worker, precompute the result, or simply don't do that work at that moment. scheduler.yield() is a tool for keeping work that must run on the main thread responsive by slicing it. It is not a spell that makes heavy work light.

A checklist you can apply today

Here is the order I settled on after measuring.

Look at the field first. Check your real INP p75 in the Search Console CWV report or CrUX. Start from lab numbers and you fall into "it's fine on my fast laptop, so why is the field bad?"
Isolate the slow interaction. Record the problem interaction in the DevTools Performance panel, or attach the Event Timing API in production and log the three slices for events that carry an interactionId. The fix differs depending on whether input, processing, or presentation dominates.
If input delay is large, find the other work (heavy init, third-party scripts, timers) hogging the main thread at that moment and defer or chunk it.
If processing is large, the handler itself is heavy. Split the long task with scheduler.yield(), and push non-urgent parts (logging, analytics beacons) to after the interaction.
If presentation delay is large, check whether your callback thrashes layout or touches too much DOM. Too much to draw in one frame pushes presentation out.
Avoid: doing everything synchronously on one click, kicking off a heavy re-render immediately after an interaction, and calling scheduler.yield() with no feature detection.

The honest limit

This experiment is a lab measurement on Chrome 150, desktop, a fast machine. Field INP spreads far wider, down to low-end Android. So these numbers (264ms to 56ms) are enough to show the direction and the mechanism (chunking makes the response faster), but they are not a prediction of your site's field INP. And as I said, making INP good guarantees no ranking gain. Core Web Vitals has never beaten relevance. Strip those two away and one real benefit remains: when someone actually using your site presses a button, the screen answers in 56ms instead of 264ms. That alone is worth measuring.

If you need structured data emitted reliably server-side, or a real measurement pass on an existing site's Core Web Vitals and accessibility, I take that on personally as consulting and implementation work. When this kind of measure-and-fix job comes up, the contact route on my profile is the way to reach me.

Cutting CLS from 0.559 to 0.014, measured

Jangwook Kim — Wed, 15 Jul 2026 06:39:04 +0000

You reach for the checkout button, and right as your thumb lands, the whole page slides down and you hit the wrong link instead. Something above finished loading late, or a banner elbowed its way in. The annoyance passes in a second, but this isn't about feelings. Google measures that "jump" as a number called Cumulative Layout Shift (CLS), and that number helps decide whether your page counts as good or not.

So I built the same HTML page twice. One version carries the mistakes I see most often. The other fixes them. Then I measured both with the exact API the browser uses to compute CLS. The short version: it went from 0.559 to 0.014. Every figure below comes straight out of that sandbox.

CLS measures total movement, not how many times things moved

Start with the ground floor. Core Web Vitals are three metrics: LCP (when the largest element paints), INP (how fast the page responds to input), and CLS (how much the screen shifts). The first two are measured in time, milliseconds. CLS alone is a unitless score, and that's exactly what makes it easy to misread.

CLS sums up the unexpected layout shifts that happen while a page is alive. Each individual shift scores as the product of two fractions: how much of the viewport moved (impact fraction), and how far it traveled (distance fraction). An element covering half the viewport that drops by half the viewport height scores roughly 0.5 × 0.5 = 0.25. A tiny footnote nudging a few pixels and half the screen sinking at once carry completely different weight.

Here's the misconception worth killing. CLS doesn't count how many shifts occurred. One shift that pushes the whole screen can land you in POOR territory by itself. Ten small shifts, each minuscule, might sum to almost nothing. And crucially, any shift within 500 milliseconds of a user click or tap is excluded. An accordion opening because you pressed "expand" is expected movement. The hadRecentInput flag on each layout-shift entry draws that line.

The thresholds are set in Google's own docs. 0.1 or below is GOOD, above 0.25 is POOR, and the band between them needs work (web.dev, Cumulative Layout Shift). That 0.1 figure isn't arbitrary either. Internal testing found that shifts of 0.15 and up were consistently felt as disruptive, while 0.1 and below were noticeable but not jarring (web.dev, thresholds).

The same page, built two ways, with the mistakes planted on purpose

No reproduction, no claim. I put two static HTML pages in the sandbox — an ordinary recipe gallery, images mixed with text.

Into bad.html I planted the three mistakes I run into most in real code.

<!-- Mistake 1: image has no size info → it shoves content down as it loads -->
<style>.hero img{width:100%}</style>
<div class="hero"><img src="cat.svg" alt="hero"></div>

<div class="card"><button>Save recipe</button></div>

<script>
  // Mistake 2: inject a banner at the top after 500ms → everything below drops
  setTimeout(() => {
    const d = document.createElement('div');
    d.textContent = 'Subscribe now';
    document.body.insertBefore(d, document.body.firstChild);
  }, 500);
  // Mistake 3: inject a notice above the hero after 900ms
  setTimeout(() => { /* insert a <p> above the hero */ }, 900);
</script>

The point is that these aren't three separate bugs. They're three faces of the same mistake: never telling the browser "hold this much room here" ahead of time. The image only learns its size once the download finishes; the banner and notice are conjured later by JavaScript. Until that moment arrives, the browser treats those spots as zero pixels, then suddenly opens up space when the content lands, shoving everything below it down.

good.html is identical in content and timing. The banner still arrives at 500ms, the notice at 900ms. The only difference is that it tells the browser about the room in advance. That contrast matters. The thesis isn't "don't insert content late" — it's "insert it late, but leave the room open."

I measured with the same API the browser counts CLS with

Instead of a rolled-up score like a Lighthouse number, I pulled the raw data. A PerformanceObserver collects every layout-shift entry one at a time. This is the very event Chrome reads internally when it computes CLS.

new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    if (!e.hadRecentInput) {        // exclude shifts right after user input
      cls += e.value;               // value = impact × distance
      shifts.push({ value: e.value, t: Math.round(e.startTime) });
    }
  }
}).observe({ type: 'layout-shift', buffered: true });

I launched system Chrome through Playwright, loaded each page at a mobile viewport (390px), waited two seconds for the dynamic inserts to finish, then read the cumulative value. I chose mobile because the narrower the screen, the larger a share any element takes, and the harder CLS bites.

Event (time after load)	Cause	before	after
~148ms	Hero and thumbnails decode with no box	0.446	0.000
~694ms	Promo banner injected at top of body	0.066	0.000
~1070–1135ms	Notice paragraph injected above the hero	0.048	0.014
Total (CLS)		0.559 (POOR)	0.014 (GOOD)

The images were the big culprit. Eighty percent of all movement came from a single image-decode event. The banner and notice trailed at 0.06 and 0.05. What's interesting is that three shifts, scattered across 148ms, 694ms, and 1135ms, still summed into one score. That's no accident.

CLS isn't a plain running total. It uses session windows: shifts that fire in quick succession get grouped into one window, and a gap of more than a second opens a new one, with a single window capped at 5 seconds (web.dev, optimize CLS). My three shifts were 546ms and 441ms apart, both under a second, so they fell into one window, which is why my naive sum (0.559) matched the real session-window CLS. Two-second gaps between them and the story changes. I'll be honest about that difference in a moment.

The fix fits in three lines — reserve the room first

good.html changed three things. In code it's almost anticlimactic.

1) Give images explicit width and height.

<img src="cat.svg" alt="hero" width="800" height="450">

These two attributes no longer force the image to render at those exact pixels, the way they did decades ago. Modern browsers derive an aspect ratio from them and reserve a box of that shape before the file arrives. Set width:100% in CSS and the height still follows the ratio. For responsive images, pair it with CSS aspect-ratio to be safe.

.hero img { width: 100%; height: auto; aspect-ratio: 16 / 9; }

2) Pre-place the slot for content you'll fill later.

Rather than pushing the banner in with insertBefore, put an empty slot in the document from the start and fill only the text.

<div id="promo" style="min-height:64px"></div>
<script>
  // the room already exists, so just drop in the content → zero shift
  setTimeout(() => {
    document.getElementById('promo').textContent = 'Subscribe now';
  }, 500);
</script>

Reserve a minimum with min-height, hide it with visibility:hidden while :empty, and the layout won't wobble even when there's nothing there yet. Any slot whose size you can know in advance — ads, embeds, banners — takes this treatment (Google Publisher Tag, minimize layout shift).

3) Don't insert anything above existing content. If you truly must, do it only in response to user interaction. This ties back to the 500ms rule: a shift a user triggered by pressing a button is expected and drops out of CLS, but a shift your script forces with no input counts in full. If your page paints content late via JavaScript, odds are you're also fighting the fact that crawlers don't render your JavaScript. Render timing hits performance and crawlability at the same time.

The result is right there in the table. Fixing images alone erased 80% of the CLS; handling the other two left just 0.014. That residual 0.014 is a small shift from the notice insert, about a seventh of the GOOD threshold, imperceptible in real use.

Honest limits — this number does not guarantee ranking

Stopping here would be dangerous. Having measured something doesn't mean it translates into search ranking. Three things to nail down.

First, lab data and field data are different. What I measured is a synthetic reading in a controlled environment. The CLS Google uses as a ranking signal is the 75th percentile of field data (CrUX), gathered from real users' Chrome. Lab measurement is unbeatable for finding and fixing causes, but "this number is my ranking" it is not. After you ship, you verify again with field data.

Second, good Core Web Vitals don't lift your ranking on their own. Google uses page experience as a signal, but content relevance dominates by a wide margin. A CLS of 0.014 signals "this page respects its users" — it isn't a guarantee of a ranking bump. That's Google's own stated position. Bad CLS can hold you back; good CLS won't pull you ahead by itself.

Third, my measurement method has an approximation baked in. I summed the layout-shift values naively. This time every shift landed in one session window and matched the real CLS, but on long-lived pages where shifts fire seconds apart (infinite scroll, SPAs), the naive sum and the session-window value diverge. When you need the accurate figure, reach for Google's web-vitals JavaScript library, which implements the session-window logic for you. This experiment also skipped shifts from web-font swaps (FOUT), another common CLS source.

Once you know those limits, the point of measuring gets sharper, not weaker. Lab measurement isn't a ranking oracle. It's a debugging tool: see what moves and by how much, then peel off the causes one by one. That's the whole workflow, and its core. The same posture drove taking an LCP bottleneck apart with a trace. Don't guess. Measure.

A checklist you can run today

To apply this to your own site, walk it in this order.

Do all your <img> and <video> elements carry width and height? If the pixels are fluid because it's responsive, lock the ratio with CSS aspect-ratio. This one step usually clears most of the CLS.
Have you reserved space with min-height for ad, embed, and banner slots? If you don't know the size, hold the most common height and handle the fill inside that box.
Are you inserting anything above existing content with JavaScript? Cookie banners, notice bars, lazy-loaded widgets are the usual suspects. Unless it's a response to user input, open the room ahead of time.
Does the layout jump when web fonts swap in? Use font-display and size-adjust to close the metrics gap between the fallback font and the web font.
Did you verify with field data after fixing? GOOD in the lab can still look different in the real world of slow devices and slow networks. Check real-user values with the web-vitals library or CrUX.

CLS isn't a flashy optimization. It's a fundamental you can summarize in one line — tell the browser about the room in advance — and one that pays back reliably when you honor it. And before it's a performance metric, it's a matter of courtesy: keeping the button a user reached for from running away.

From getting structured data out server-side reliably to auditing an existing site's Core Web Vitals and accessibility with real measurements, I work on web development hands-on and take on consulting and implementation requests personally. If problems you need to catch with numbers — a shifting layout, a slow LCP — are piling up, feel free to reach out through the contact link on my profile.

GPT-5.6 Programmatic Tool Calling: When It Cuts the Token Bill

Jangwook Kim — Wed, 15 Jul 2026 00:47:49 +0000

Picture an assistant that answers a plain business question: "How much did we refund last week?" To answer, it calls a tool that pulls your order records, keeps the refunded ones, and adds up the amounts. The answer is a single number. But to get there, most AI assistants haul the whole pile of records back through the model, line by line, so the model can do the filtering and the arithmetic in its head.

You pay for that pile. Every record that passes through the model's reading window is billed, whether or not it shapes the final answer. One lookup is a rounding error. An agent doing this hundreds of times a day, across support tickets, billing checks, and CRM reads, turns it into a real line on the invoice.

OpenAI's newest model family, GPT-5.6, ships a feature aimed at exactly that waste. It's called programmatic tool calling. The pitch is simple: instead of reading every tool result itself, the model writes a small program that runs your tools, filters the data, and does the math off to the side, then hands the model only the finished answer.

Does it actually save money? We ran it on the live API to find out. Sometimes it saves a lot. Sometimes it costs more. The interesting part is the rule that decides which, and it comes down to one thing you can check before you commit.

What GPT-5.6 changed

On 2026-07-09 OpenAI released GPT-5.6 as three tiers you pick by cost and horsepower: Sol (the top model), Terra (the balanced one), and Luna (the cheap, high-volume one). The plain name gpt-5.6 routes to Sol. All three are available through OpenAI's API.

The feature we're testing, programmatic tool calling, works like this in everyday terms. Normally the model asks your app for a tool result, you send it back, and the model reads it. With programmatic tool calling, the model instead writes a short piece of JavaScript that runs in a locked-down sandbox (no internet, no files, nothing saved between runs). That code calls your tools, sifts the results right there, and returns only the final number to the model. The bulky middle step never enters the part you pay for.

There's a second new trick worth naming so you can tell them apart: multi-agent orchestration, a beta feature that spins up several helper agents in parallel and merges their work into one answer. That's a different lever (more parallel effort for a stronger result), and we did not measure it here. This article is only about the token economics of programmatic tool calling.

What we built and ran

We wrote a small test that gives GPT-5.6 the same job twice: once with classic tool calling (the model reads every result) and once with programmatic tool calling (the model writes code that does the reading). Then we counted the real tokens the API reported for each. Everything is synthetic and deterministic. No customer data, no secrets, and a fixed correct answer so we can confirm the model got it right.

We used Luna, the cheapest tier, and ran two versions of the job that differ in one way only: how big each tool result is.

Small results. A tool returns a single number. The model calls it for eight items and adds them up. Each result is a few tokens.
Big results. A tool returns 40 order rows per call (customer, region, amount, a refunded flag, and so on). The model calls it for eight days, keeps the refunded rows, and totals them. That's 320 rows in play. In classic mode all 320 get dragged through the model; in programmatic mode they stay in the sandbox.

Both jobs have a fixed right answer (204 for the small one, 52,584 for the big one), so we can check correctness, not just cost.

What actually happened

Both approaches got both answers right. The cost is where they split apart, and they split in opposite directions depending on how big the tool results were.

When tool results were tiny, programmatic tool calling cost more, not less.

Small tool results	Classic tool calling	Programmatic tool calling	Change
Total tokens (what you pay)	645	1,392	about 2.2x more (+116%)
Model output tokens	155	91	41% fewer
Answer	204	204	both correct

Writing the little program isn't free. The model spends tokens composing the JavaScript, and for a job this small that overhead swamps any saving. Programmatic tool calling used more than double the tokens (1,392 versus 645) to reach the same answer.

When tool results were big, programmatic tool calling was dramatically cheaper.

Big tool results (320 rows)	Classic tool calling	Programmatic tool calling	Change
Total tokens (what you pay)	19,491	1,496	about 92% fewer (13x fewer)
Model output tokens	252	126	50% fewer
Answer	52,584	52,584	both correct

Here the classic approach paid to shuttle all 320 order rows through the model: 19,491 tokens. The programmatic approach kept those rows in the sandbox, filtered and summed them there, and returned only the total: 1,496 tokens. That's roughly a 92% cut (about 13 times fewer tokens) for the identical, correct answer.

So the feature is not a free discount you flip on everywhere. The deciding factor is how much data your tools hand back. Big, messy tool outputs that only need a small slice of the answer? Programmatic tool calling pays off, and it can pay off enormously. Tiny outputs, or a couple of quick calls? The overhead of writing the program can make it more expensive.

One detail is easy to misread. In both jobs the programmatic runs took more back-and-forth trips to our app, nine versus two. Our tools live in our own code, so the sandbox has to pause and ask our app to run each call. The savings don't come from cutting those trips. They come from keeping the results of those trips out of the model's reading window. Move your tools to OpenAI's side (hosted or MCP tools) and even those pauses go away.

Can this survive your workflow?

Here's how to translate the result into your own service. Ask one question: when your agent calls a tool, does it get back a lot of data it mostly throws away?

Order and refund processing. An agent pulls a batch of orders and totals a subset (refunds, chargebacks, a region). Classic calling pays for every row. This is the big-win case, like our 92% cut.
Support ticket triage. If a tool returns full ticket histories and the agent needs one status or one count, the history is the expensive pile that never needs to reach the model.
CRM and billing reads. Pulling a customer's full record to answer a yes/no or a single figure is the same shape: big input, small answer.
Internal reporting and reconciliation. Summing, counting, or matching across many rows is exactly what a sandbox program does cheaply.

And the cases where it won't help, so you don't over-adopt it:

A couple of small lookups. Two or three calls that each return a short value. The program-writing overhead can cost more than it saves, as our small-results run showed.
The model needs to read everything anyway. If the task genuinely requires reasoning over the full tool output (summarizing every ticket, not counting them), keeping the data out of context defeats the point.

The honest takeaway for a budget owner: programmatic tool calling is a targeted tool for data-heavy agent steps, not a global setting. On the right step it can cut the model bill by an order of magnitude. On the wrong step it quietly adds cost. The way to know is to measure your own tool outputs, which is exactly the kind of bounded check we run.

If you're weighing this for a live service and want an inspectable, claim-bound proof on your own workload before you commit engineering time, that's what Effloow's Proof Studio produces. For scoping a build, see our services. We publish the method and the raw numbers every time, the same way we did here.

Limitations, in plain words

This is a bounded lab check, not a benchmark. We ran two synthetic tasks, once each per mode, on one model tier (Luna). Real numbers will move with the size of your tool outputs, how the model chooses to write its program, the reasoning effort you set, and whether your tools run on your side or OpenAI's. We did not measure price in dollars, speed, or the separate multi-agent beta. What we can stand behind: on these two deterministic tasks, on the live GPT-5.6 API, the direction and rough size of the effect were clear and reproducible with the script below.

What Effloow added

The primary sources tell you the feature exists and how to wire it up. They don't tell you when it's worth it. Our original contribution is the measured decision rule: a two-scenario, same-task comparison on the real GPT-5.6 API showing the effect flips sign with tool-output size (about 92% cheaper on big outputs, about 2.2x more expensive on tiny ones), with both answers verified correct. The full run, the exact counts, and the reproduction command are in our public lab note. This pairs with our earlier Claude programmatic tool calling token proof for a cross-model view, and sits alongside our OpenAI prompt-cache retention cost proof and OpenAI Agents SDK tool-failure recovery proof as part of a growing set of evidence-led agent-cost write-ups.

For your engineers

Model and runtime: gpt-5.6-luna via the OpenAI Responses API (POST /v1/responses). GPT-5.6 exposes gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna; the gpt-5.6 alias routes to Sol.

Enabling programmatic tool calling:

Add the hosted tool {"type": "programmatic_tool_calling"} to the tools array.
On each function the program may call, set allowed_callers: ["programmatic"] (values are ["direct"], ["programmatic"], or both) and provide an output_schema.
Handle the new output items: a program item (generated JavaScript code, a call_id, and a fingerprint), program-issued function_call items whose caller field references the program's call_id, and a program_output item with the matching call_id, a result JSON string, and a status. Preserve every call_id and the caller linkage when you return function_call_output items.
Sandbox constraints per OpenAI's guide: V8 runtime with top-level await, but no Node.js, no package install, no network, no general filesystem, no subprocess, no console, and no persistent state between program runs. Programs reach the outside world only through the tools you enable.

Measured results on this run (real API usage counters):

Tiny outputs: classic 2 model round-trips, 645 total tokens, 155 output tokens; programmatic 9 round-trips, 1,392 total tokens, 91 output tokens. Answer 204 in both.
Bulky outputs (320 rows): classic 2 round-trips, 19,491 total tokens, 252 output tokens; programmatic 9 round-trips, 1,496 total tokens, 126 output tokens. Answer 52,584 in both.

Why programmatic showed more round-trips: our tools are client-side, so the hosted program pauses for our app to execute each get_* call. Savings come from keeping tool outputs out of model context, not from reducing app round-trips; hosted or MCP tools would remove the pauses.

Reproduce: run python3 scripts/gpt56-ptc-token-proof.py. It drives both scenarios in both modes, checks the budget guard before each call (scripts/proof_budget.py, ledger in data/state/openai-token-usage.json), records real per-turn usage, and writes the artifact to data/lab-runs/gpt-5-6-programmatic-tool-calling-multiagent-token-proof-2026.openai.json. Full notes and the raw counters are in the public lab note.

Primary sources: OpenAI Programmatic Tool Calling guide, OpenAI model-guidance (latest-model) doc, OpenAI's GPT-5.6 Sol announcement, and the OpenAI Responses multi-agent guide.

A 117KB hero with a 1.2s LCP: the browser found it too late

Jangwook Kim — Tue, 14 Jul 2026 06:45:08 +0000

I traced a single hero image. The file was a 117KB PNG, and it downloaded in 5 milliseconds on localhost. Yet the page's Largest Contentful Paint landed at 1,247 milliseconds. The image arrived in 5ms, but the largest element took 1.2 seconds to paint. So where did the other 1,242ms go?

The answer is not "the image is heavy." It is a question of when the browser started looking for that image. If you treat LCP purely as an image-weight problem, most of that 1.2 seconds stays out of reach forever. Today I shipped the same hero three different ways and used Chrome DevTools traces to break LCP apart, watching exactly where the bottleneck hides. Every table and log below is a real measurement from that sandbox.

LCP is not one number — it is four segments

Groundwork first. LCP (Largest Contentful Paint) marks the moment the largest content element in the viewport — usually a hero image or a big heading block — gets painted. Google recommends this happen within 2.5 seconds of the page starting to load (Google Search Central, Core Web Vitals). That threshold is the 75th percentile of real-user field data (CrUX).

Here is the part that matters. LCP looks like a single metric, but web.dev's Optimize LCP guide splits it into four sub-parts:

TTFB — time to the server's first byte
Load delay — time until the browser discovers the LCP resource and starts the request
Load duration — time spent actually downloading that resource
Render delay — time from finishing the download to painting it on screen

I love this four-segment model for a plain reason. "LCP is slow" is a symptom, not a diagnosis. You have to see which of the four is bloated before you can prescribe anything. And most slow heroes bleed time in Load delay (discovery), not Load duration (download). Here is the proof.

Measured: the hero shipped as a background image

The first version is a common pattern. I laid the hero down as a CSS background-image rather than an <img>.

.hero {
  width: 100%;
  height: 600px;
  background-image: url("hero.png");
  background-size: cover;
}

<link rel="stylesheet" href="style.css">
<div class="hero"></div>

The test rig: a local threaded HTTP server, Cache-Control: no-store on every response (so nothing gets reused), and a 1-second delay bolted onto the stylesheet. That delay simulates a real-world slow render-blocking CSS file. I captured a Chrome DevTools performance trace with a reload. The result:

LCP: 1247 ms
  TTFB:          8 ms
  Load delay: 1184 ms   ← here
  Load duration: 5 ms
  Render delay:  51 ms
DevTools insight: "LCP request discovery" flagged

Load delay: 1,184ms. The image download took 5ms, but the browser spent 1.2 seconds just discovering it. Why? Because the hero URL is buried inside CSS.

One key concept here. Browsers run a preload scanner. When the HTML response bytes arrive, before the main parser even runs, this scanner skims the raw HTML and finds resources like <img src>, <script src>, and <link href> so it can kick off those requests early. The catch: the scanner only reads HTML. A background-image URL sitting in CSS is invisible to it (web.dev, Don't fight the browser preload scanner). So a background image cannot even be requested until the CSS downloads and parses. My CSS carried a 1-second delay, so the hero got discovered exactly that late. Chrome itself called this out as an "LCP request discovery" insight (LCP discovery, Chrome for Developers).

This shares a root with the story about AI crawlers not running your JavaScript and therefore never seeing your content. Where and how a resource is placed decides when — or whether — it gets processed at all.

I added fetchpriority and preload — and LCP barely moved

Second version. I switched the hero to a real <img>, added fetchpriority="high", and put a preload hint in the <head>.

<link rel="preload" as="image" href="hero.png" fetchpriority="high">
...
<img src="hero.png" alt="Product launch hero"
     width="1200" height="600" fetchpriority="high">

fetchpriority="high" is a hint that tells the browser to fetch this resource ahead of others, at high priority (web.dev, Fetch Priority API). Why does it help? Before layout, the browser has no idea where an image will land on screen, so it assigns most images a low initial priority. The hero and a decorative footer icon get the same early treatment. fetchpriority="high" pulls exactly one of them — the hero — up by hand. Because it is now an <img>, the URL lives in the HTML, and the preload scanner spots it immediately. The measurement:

LCP: 1226 ms
  TTFB:          3 ms
  Load delay:   37 ms   ← plunged from 1184 to 37
  Load duration: 2 ms
  Render delay: 1185 ms  ← this one swelled instead

Load delay collapsed from 1,184ms to 37ms. The discovery problem is completely solved. The image is fully received by 42ms into the navigation. And yet LCP is still 1226ms, basically unchanged. I will be honest: the first time I saw this I stopped for a second. If you speed up discovery 30x and the headline metric does not move, you missed something.

The bottleneck had moved. Now Render delay eats 1,185ms. The image is ready at 42ms, but the browser cannot paint it — the render-blocking stylesheet (my 1-second file) has not arrived. Chrome paints nothing until the CSS lands and it can produce a first paint. You are holding the image, but you cannot pick up the brush.

This is the whole point I want to land. fetchpriority and preload are necessary, not sufficient. They erase the discovery bottleneck. But if any of LCP's other three segments is swollen, pulling discovery earlier only moves the number by that much. Spray fetchpriority everywhere without reading the four segments, and it is easy to fool yourself into thinking things got better.

Kill render-blocking too, and LCP goes 1247 → 109ms

Third version. I kept the <img fetchpriority> from before and removed the render-blocking CSS. I inlined only the critical CSS the hero needs to render into a <style> block, and loaded the rest of the stylesheet without blocking paint.

<style>
  .herowrap{width:100%;height:600px;overflow:hidden}
  .herowrap img{width:100%;height:600px;object-fit:cover}
</style>
<link rel="stylesheet" href="style.css"
      media="print" onload="this.media='all'">

Setting media="print" keeps it from blocking screen render, then onload flips it to all so it actually applies. It is a well-worn non-blocking CSS pattern. The measurement:

LCP: 109 ms
  TTFB:          5 ms
  Load delay:   43 ms
  Load duration: 1 ms
  Render delay:  60 ms

From 1,247ms to 109ms. All three segments settled into double digits. Discovery is fast (43ms), and nothing is blocking the paint (Render delay 60ms). Line the three versions up:

Hero delivery	Load delay (discovery)	Render delay	LCP
CSS `background-image`	1,184 ms	51 ms	1,247 ms
`<img fetchpriority>` + preload	37 ms	1,185 ms	1,226 ms
+ inline critical CSS (non-blocking)	43 ms	60 ms	109 ms

Fix one number and the bottleneck ran sideways. Fix both bottlenecks and the metric finally caved. This table is the four-segment model earning its keep.

So here is what to do today (a checklist)

Translated into practice, the experiment says:

Ship the hero as an HTML <img>, not a CSS background. The preload scanner has to see it to discover it early. If the design truly demands a background, front-run discovery yourself with <link rel="preload" as="image" href="..." fetchpriority="high"> (web.dev preload-scanner).
Put fetchpriority="high" on the LCP image. Browsers often assign images a low initial priority. Raise the hero, and only the hero.
Never put loading="lazy" on the LCP image. Great for below-the-fold images, self-inflicted harm on a top-of-viewport hero — you are delaying your own discovery (web.dev, LCP misconceptions).
Inline critical CSS and make the rest non-blocking. Receiving the image early does nothing if render-blocking CSS still gates the paint.
Always set width/height (or aspect-ratio). It prevents layout shift (CLS). Across all three versions above, CLS was 0.00.
Above all, read the LCP breakdown first. The DevTools Performance panel hands you TTFB / Load delay / Load duration / Render delay directly. Attack the biggest segment. I dug into this measure-then-fix workflow in the post on reading Lighthouse to catch and fix accessibility violations.

Honest limits — do not misread these numbers

My numbers are lab figures. Local server, no network throttling, CPU at 1x. Even the 1-second stylesheet delay is a value I injected on purpose to make the effect visible. So do not paste the "1247 → 109" ratio onto your own site. These numbers are a demonstration of the mechanism, not the absolute gain you should expect. What Google actually uses for ranking is CrUX field data from real users, and your gain depends on your page's real critical path.

The second limit matters more. Landing LCP under 2.5s does not guarantee a ranking bump. Google states plainly that "there's no single ranking signal," and that good page experience "doesn't override having great, relevant content" (Google Search Central). Core Web Vitals is one signal among many. I think the honest pitch for LCP work is "a UX job that reduces bounce," not "a ranking lever." A fast page is good because people do not leave, not because speed buys you a top spot.

Let me also log, honestly, the two traps that fooled me while reproducing this. I started with a single-threaded Python server, and the fetchpriority version discovered the image early yet LCP would not drop. While the server sat blocked serving the 1-second CSS, the early-discovered image request queued up behind it. A real HTTP/2 origin would have multiplexed both down at once; a server artifact was masking the real win. Only after switching to a threaded server did the numbers get honest. The second trap was caching. Without no-store, the browser pulled the previous run's CSS from disk cache, the 1-second delay vanished, and the entire "before" penalty evaporated. A good reminder to distrust the test rig before you trust the measurement.

Third: preload backfires when overused. Hand high priority to everything via preload and you starve the resources that actually matter, and depending on conditions you can even double-download an image. Spend preload sparingly, on the single LCP element.

One sentence sums it up. When LCP is slow, do not suspect image weight first — open the four segments and see when the browser discovers the element and when it paints it. The bottleneck usually hides in discovery and render-blocking, not download. I reached the same conclusion while auditing a multilingual blog and stripping out render-blocking resources in this technical SEO audit log.

If you want structured data emitted reliably server-side, or an existing site's Core Web Vitals, accessibility, and crawler handling checked with real measurements, I take on consulting and implementation work personally. Reach me through the contact link on my profile.

Catch Broken JSON-LD in CI Before It Ships

Jangwook Kim — Mon, 13 Jul 2026 06:38:43 +0000

The structured-data check in your deploy pipeline is green. That green proves exactly one thing: your JSON-LD is well-formed. It does not prove Google can read a single field inside it. These are two different questions, and most teams treat them as one.

It clicked for me the day I watched a @type written as lowercase article sail through a parser without a peep. To a JSON-LD processor it's perfectly valid. To Google it's an unknown type, silently ignored. Nothing in between. No warning, no error, no red. You find out six months later, digging through Search Console to figure out why the rich result never showed.

Validation has two layers

When people say they "validate" structured data, they're usually pointing at two different things.

The first is syntactic validation. Does this JSON-LD parse? Are the braces balanced, is there a @context, can a JSON-LD 1.1 processor expand it into a graph? A library like jsonld nails this every time.

The second is schema-semantic validation. Is the type name a real schema.org term, in the right casing? Are the property names free of typos? Is the date ISO 8601? Are URL fields absolute? Does the node carry the properties Google recommends for that type? The parser won't tell you any of that.

Here's the trap: the second can fail while the first passes without blinking. And Google's own validators, the Rich Results Test and the Schema Markup Validator (validator.schema.org), are both manual, browser-based tools where you paste a URL or a blob of code. Neither lives in your build. So unless a human opens one by hand, broken schema flows straight to production.

If you've already decided which syntax to use among JSON-LD, Microdata, and RDFa, the next question is this: who checks that the markup you write in that syntax is actually correct, on every commit?

Why this gap costs more now

There was a time when silently broken structured data cost you, at most, a rich-result snippet. Not anymore. Search is shifting, and the crawlers that build AI overviews and generative answers lean harder on structured data to work out what a page means. Many of those crawlers don't run your JavaScript; they grab the raw HTML and leave. The JSON-LD your server emits is nearly all they see.

So what happens when that JSON-LD carries a lowercase article? To a human the page looks fine, and the parser waves it through, but to the machine reading it, that's an unidentified node with no author and no publish date. The price of a single slip has grown from "you miss a snippet" to "an AI misreads your page." Catching it before deploy pays off more than it used to.

Why the parser can't catch the typo

I didn't want to just assert this, so I reproduced it in a sandbox. Node v22, jsonld 8.x. I built a broken.json seeded with five everyday mistakes.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "article",
      "headline": "Broken sample",
      "datePublished": "07/13/2026",
      "authour": "Kim Jangwook",
      "image": "hero.png"
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "name": "Blog", "item": "https://example.com/blog" }
      ]
    }
  ]
}

Lowercase article, the typo authour, a US-style date 07/13/2026, a relative hero.png, and a ListItem missing position. Run that through jsonld.expand() and you can see which IRI the processor resolves each term to.

$ node expand-demo.mjs

===== broken.json — jsonld.expand() =====
resolved @type IRIs : http://schema.org/article, http://schema.org/BreadcrumbList, ...
resolved term IRIs  : http://schema.org/article, http://schema.org/authour,
                      http://schema.org/datePublished, http://schema.org/headline, ...

This is the whole point. article expands to http://schema.org/article, and authour expands to http://schema.org/authour, cleanly. No error. No warning. Nothing dropped.

The reason is that schema.org's hosted JSON-LD context sets @vocab to https://schema.org/. When @vocab is present, the processor just concatenates any undefined string onto that prefix. It never checks whether a property called authour exists in schema.org. It manufactures a nonexistent IRI, and that is entirely legal JSON-LD. The parser inspects syntax, not vocabulary.

That's where the gap between "valid JSON-LD" and "readable by Google" opens up. The same gap runs through wiring scattered blocks into one @graph: before you talk about connecting nodes, each node has to be written with a valid type and valid properties in the first place.

A 60-line schema-aware validator

If the parser won't catch it, bolt on a check that knows the schema. It doesn't need to be elaborate. A slice of vocabulary for the types you care about, plus five rules.

const VOCAB = {
  Article: {
    props: ['headline','datePublished','dateModified','author','image','description'],
    // Google lists NO required properties for Article (only recommended).
    // Enforcing headline is our team policy, not a Google rule.
    recommended: ['headline'],
    urlProps: ['image'], dateProps: ['datePublished','dateModified'],
  },
  BreadcrumbList: { props: ['itemListElement'], required: ['itemListElement'] },
  ListItem: { props: ['position','name','item'], required: ['position','name'], urlProps: ['item'] },
};
const KNOWN = Object.keys(VOCAB);
const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2})?([+-]\d{2}:\d{2}|Z)?)?$/;
const ABS = /^https?:\/\//;

function checkNode(node, errors) {
  let t = node['@type'];
  if (!KNOWN.includes(t)) {
    const near = KNOWN.find(k => k.toLowerCase() === String(t).toLowerCase());
    if (near) { errors.push(`@type "${t}" is wrong casing → "${near}"`); t = near; }
    else return;
  }
  const spec = VOCAB[t];
  for (const key of Object.keys(node)) {
    if (key.startsWith('@')) continue;
    if (!spec.props.includes(key)) {
      const near = spec.props.find(p => p.toLowerCase() === key.toLowerCase());
      errors.push(`${t}.${key}: not a valid property${near ? ` → "${near}"?` : ''}`);
    }
  }
  for (const r of (spec.required || [])) if (!(r in node)) errors.push(`${t}: missing required field "${r}"`);
  for (const d of (spec.dateProps || [])) if (node[d] && !ISO.test(node[d])) errors.push(`${t}.${d}: not ISO 8601`);
  for (const u of (spec.urlProps || [])) { const v = node[u]; if (v && !ABS.test(v)) errors.push(`${t}.${u}: not an absolute URL`); }
  // recurse into nested nodes and itemListElement
  for (const v of Object.values(node))
    (Array.isArray(v) ? v : [v]).forEach(x => x && typeof x === 'object' && x['@type'] && checkNode(x, errors));
}

Notice that when it hits a casing error, it doesn't throw and stop. It recovers to the correct type and keeps checking. That way you see both that article is wrong and that the same node has an authour, a bad date, and a relative URL, all in one pass. My first cut skipped that recovery, reported the one type error, and missed the other four. CI has to show everything at once, or you burn a round trip per fix.

Look closely at Article being tagged recommended rather than required. Per Google's own docs, Article has no required properties. author, datePublished, dateModified, headline, and image are all merely recommended. So enforcing headline is a call your team makes, not a rule Google imposes. That's exactly what a validator is for: encoding "the floor our org sets on top of Google's recommendations" as code.

What the run actually produced

I fed good.json (a clean Article plus a two-step BreadcrumbList) and broken.json into the same validator.

===== good.json =====
PASS — 0 problems

===== broken.json =====
FAIL — 5 problems
  x @type "article" is wrong casing → "Article"
  x Article.authour: not a valid property → "author"
  x Article.datePublished: "07/13/2026" is not ISO 8601
  x Article.image: "hero.png" must be an absolute URL
  x ListItem: missing Google-required field "position"
process exit code = 1

All five caught, and the process ended on broken.json with exit 1. That exit code is the whole game. good.json exits 0. With that one line, CI blocks the build with no extra configuration.

Notice only the ListItem missing position is labeled "Google-required." That's accurate. A BreadcrumbList requires at least two ListItems, and each ListItem genuinely requires position and name (official). None of the four Article errors carry a "required" tag. The validator is speaking precisely, keeping Google's rules and your team's policy on separate lines.

Wiring it into a CI gate

Since the exit code is already 1, the rest is plumbing. One script in package.json.

{ "scripts": { "validate:schema": "node scripts/validate-schema.mjs" } }

And one step in a GitHub Actions job.

- name: Validate structured data
  run: npm run validate:schema

If the validator fails, the job fails, and a PR carrying broken schema doesn't merge. To sweep the whole site, scrape every <script type="application/ld+json"> block out of the built HTML and pipe each into the same checkNode. Same principle. It's the same skeleton as putting accessibility checks in CI: take the thing a human used to eyeball by hand and turn it into a deterministic gate that goes red on failure.

What this validator can't do

The post is only honest if I draw the line clearly.

This is not a replacement for the Rich Results Test. It knows a hand-picked slice of vocabulary (Article, BreadcrumbList, ListItem, Person). For real coverage you'd generate the type and property lists from schema.org's public dump and fill VOCAB from that. What you saw here is a proof of concept, not a finished product.

Passing validation does not guarantee a rich result. That's not my opinion, it's Google's official stance. The General Structured Data Guidelines say it plainly: using structured data "enables a feature to be present, it does not guarantee that it will be present." Even with flawless markup, Google's algorithm may decide, based on the user, device, or location, that a plain text result is better. The same guidelines state that structured data "by itself is not a generic ranking factor." What the validator passes is "the shape is correct," not "a rich result will appear" and certainly not "your ranking will rise."

Expansion only sees syntax. As shown above, @vocab expands even a typo into a valid IRI. So don't mistake a successful expansion for validation. The two layers don't substitute for each other. Leave syntax to the parser and meaning to a schema-aware check.

What to do today

Paste your build's JSON-LD into the Rich Results Test once by hand to set a baseline. Then move that check into code.
Start VOCAB with the types you actually use most (usually Article/BlogPosting, BreadcrumbList, Organization, WebSite). Don't try to fill everything; start with what you get wrong.
Always check the four things a parser will never flag: casing, property typos, date format, and relative URLs.
Label Google's "required" and your team's "policy" separately in code. Later, nobody wonders why a field is enforced.
Bind exit code 1 to the CI step. A check that only prints a report and passes is a check nobody reads.

If you want structured data emitted reliably server-side, or an existing site's schema, accessibility, and crawler handling reviewed at the pipeline level, I take on consulting and implementation work personally. Reach me through the contact link on my profile. Looking behind the green check is the work I do.

DEV Community: Jangwook Kim

One listener costs you the back button: six bfcache probes

The navigation that never touches the network

Six pages, one variable each

Two blocked, four restored

"masked" is not an answer

no-store stopped being a death sentence

An open connection blocks, WebSocket code doesn't

Collecting reasons from the field

What to change this week

1,248 Feed Items, Four Languages, Zero Language Metadata

Strings forget their language the moment they leave HTML

What dir="auto" actually does, and where it breaks

Auditing my own build output

Fixing the mixed feed with dc:language

An unverified gate is not a gate

Why I did not add @language to my JSON-LD context

What I'm leaving broken on purpose

Seven things to check in your own build output

GPT-5.6 Prompt Caching: The 24-Hour Cache Is Gone

What actually changed between the two model families

What we built and ran

What actually happened

What this means for your business

Can this survive your workflow?

When to use it, when to skip it

Honest limitations of this test

What Effloow added

FAQ

Q: Can I still get a 24-hour prompt cache on GPT-5.6?

Q: Why did the explicit mode cache fewer tokens than automatic mode?

Q: Is caching ever worse than not caching?

Q: What is the minimum prompt size for caching to engage?

For your engineers

Sources

WCAG 2.2 Minimum Target Size: the AA Failure Hiding Behind a Green 92

Where 24×24 comes from

Planting the bugs, measuring by hand

How far did the automated tools see?

The exceptions are the real exam

Fixing it in code

Pitfalls that keep catching people

Wrap-up: what a developer does about 24px

The meta Line That Decides If AI Overviews Can Quote You

Snippets, AI Overviews, and what robots meta actually governs

The official rules — four directives, and the exact values

When they conflict, the most restrictive one wins

I built two pages and audited them with a parser

An honest limit — eligibility, not a guarantee

What to do today

content-visibility Measured: One CSS Line, 15x Less Forced Layout

What the browser pays for every frame

The official definition: what auto actually turns on

Two copies of one page, differing by a single line

The results: initial render and forced layout

Skip contain-intrinsic-size and your scrollbar goes haywire

What about accessibility? auto is not display:none

When to use it, and when not to

A checklist you can apply today

When an AI Agent Bungles a Tool Call, Does It Fix Itself?

The failure that quietly costs money

What we actually ran

What happened, in plain words

Can this survive your workflow?

When to use a check like this, and when to skip it

The limits of what we showed

What Effloow added

For your engineers

Measuring INP: one click cost 264ms, chunking it got 56ms

What INP measures: one click, three slices

Why a web developer should measure INP now

The sandbox: same work, two ways

How to read the log

The usual suspects that eat INP in production

Chunking long tasks with scheduler.yield

A checklist you can apply today

The honest limit

Cutting CLS from 0.559 to 0.014, measured

CLS measures total movement, not how many times things moved

The same page, built two ways, with the mistakes planted on purpose

`no-store` stopped being a death sentence

What `dir="auto"` actually does, and where it breaks

Fixing the mixed feed with `dc:language`

Why I did not add `@language` to my JSON-LD context