SXN Labs

What AI didn't make faster

2026-10-22T09:00:00+02:00

AI now writes a good share of my code, and my days are no shorter. What fills them changed: writing the code takes far less time, and everything around it moved in.

What got faster

The first draft of a screen, a migration, tests for a business rule that is already clear, a translation, API documentation, reading a repo nobody has opened in six months. On that work the gain is clear, sometimes threefold by rough estimate. But that is the visible part of the job, and the invoice fills up elsewhere.

AI shortened one step out of five, the visible one.

Deciding

On my prospecting tool, a model scores companies on how likely they are to buy software from me. It gave almost everyone the same high score. Rewriting the prompt took one evening.

The rest took days: choosing which mistake costs me more, a good prospect I never see or a bad one that wastes an hour, then sorting dozens of companies by hand to have something to measure against. No assistant makes that call, because it does not know what costs you.

Specifying

On a management application, a demo company was shown “your subscription has been cancelled,” because the code did not tell “demo” from “stopped.” The change was one condition and one message, five minutes.

The half hour before went into what the code never asks. What should a demo company read? Who can change that status? What does an administrator see when impersonating a colleague’s account? AI writes the behavior you describe very well, not the one you need.

Checking

An assistant produces code that looks right, and that is what makes it misleading.

A pull request fixes one bug and cites two neighboring issues as debts it does not address, with a link to each. Any automation that closes “linked issues” closes both, and two live bugs vanish from the tracker.

A release of my e-invoicing gem passed its 317 tests and would not load for anyone who did not already have two of its dependencies. No tool pointed me to the missing check. It took knowing that the tests run in the repo while the user installs the package.

Securing

This summer in France, the leaks kept coming. The tax administration confirmed illegitimate access to its information system between June and August, using stolen credentials, and 678,000 people are reportedly affected according to the ministry. The national education ministry suffered an intrusion into its staff training platform that may have exposed data on staff who have worked in schools since 2001. SFR, a major telecom operator, warned fiber customers in August that their contact details had been read through an internal tool. Over 2025, the data protection authority received 6,167 data breach notifications, 9.5% more than in 2024.

Many of these leaks take no skill at all. In the spring, 11.7 million accounts at ANTS, the agency issuing ID documents, were exposed through a flaw attributed to an IDOR: changing a file number in the URL was enough to read someone else’s, because the server never checked who it belonged to.

That is exactly the kind of code that looks right. The screen works, the tests pass, and the hole only shows once someone exploits it. Reviewing every change while asking who could abuse it takes as long as it did before, and producing more code means more to review.

Answering for production

During a recent audit of an application, the code fixes took a fraction of the time they would have two years ago. What is left on my list is operations work you do not get to replay, done by hand by someone who answers for it. And when production goes down on a Saturday night, the model is not on call.

What it changes when you commission software

Ran Craycraft at thoughtbot frames the question well: having an AI build a prototype now costs almost nothing, so use it to check whether an idea deserves real investment. He adds that the dangerous moment comes when the prototype works and production seems within reach. A prototype exists to learn quickly. A production application has to protect data, control access and hold up when something fails.

Code was rarely the biggest line on a project’s bill, only the most visible one. When you pay a contractor, you are mostly paying for the decisions they make with you, what they check before shipping, security included, and the fact that they answer for what runs on your side. A quote promising a project “three times faster thanks to AI” assumes the project was nothing but writing code: ask what happens to the decisions, the checks, security and production.

Senko Rašić points out that saying “code was never the hard part” dismisses a whole profession. Writing code still takes skill. Its cost went down, the cost of the rest did not.

If you are weighing a prototype against a real project, we can look at your context together.

The popover that flickers on hover, the tiny bug that gives everything else away

2026-10-15T09:00:00+02:00

On a line-of-business app I maintain, a set of settings cards each show a small “?” badge that opens a help bubble on hover. Nothing exotic, a pattern you’ll find on half the web. Except the bubble flickered. You’d move the cursor toward the badge, the help would appear, vanish, reappear, in a nervous strobe that made the screen look broken. And it kind of was.

This sort of detail breaks no feature. You can leave it sitting there for months; nobody files a ticket for it. But that flicker is exactly the kind of thing that plants a quiet doubt in a user’s mind: “this software isn’t finished.” The perceived quality of a business tool rides on these micro-details as much as on the big features. It is the broken windows theory applied to software. A visible defect left alone signals that nobody is looking after the rest, and it ends up licensing others.

Why the bubble flickers

The naive instinct for this kind of bubble: open on the badge’s mouseenter, close on mouseleave. That works as long as the cursor stays on the badge. The trouble starts the moment there’s a gap, even a single pixel, between the badge and the bubble, which there almost always is, since the bubble shows up next to the badge, not on top of it.

When the mouse leaves the badge heading for the bubble, it crosses that void. The browser fires mouseleave on the badge → we close. The bubble disappears from under the cursor → the badge is under the mouse again → mouseenter → we reopen. mouseleave → close again. At the screen’s refresh rate, that’s a strobe light. The pointer sits on an unstable boundary, and each crossing fires a contradictory event.

Two pixels of gap are enough to make the pointer oscillate between two contradictory states.

The second problem shows up when you line several cards up side by side: sweeping the mouse across the grid opened three bubbles at once, overlapping. Two distinct bugs, one root cause: we treat hover as an instantaneous binary signal, when the user’s intent has both a duration and a context.

Reading an intent rather than raw events

The right abstraction is called hover intent. Instead of reacting to each isolated mouseenter/mouseleave, you read an intent: “the user wants to read this help” (they linger), “they’re done” (they leave for good).

A grace delay on close. On mouseleave, don’t close immediately, arm a ~120 ms timer. If the cursor reaches the bubble within that window, cancel the timer. The little gap between badge and bubble becomes crossable.

The bubble is part of the hot zone. mouseenter on the bubble itself cancels any pending close; its mouseleave re-arms the timer. Badge and bubble form one logical zone, even though they’re visually separate.

One bubble open at a time. Before opening, close whichever one is lingering. A simple module-level registry is enough, no state manager required for this.

Here’s the whole thing as a dependency-free Stimulus controller:

import { Controller } from "@hotwired/stimulus"

// Shared registry: only one bubble open at a time.
let openController = null

export default class extends Controller {
  static targets = ["content"]

  connect() {
    // Touch screens have no hover: fall back to tap.
    this.hoverable = window.matchMedia("(hover: hover)").matches
    this.closeTimer = null
  }

  open() {
    if (!this.hoverable) return
    clearTimeout(this.closeTimer)
    if (openController && openController !== this) openController.hide()
    this.contentTarget.hidden = false
    openController = this
  }

  scheduleClose() {
    if (!this.hoverable) return
    this.closeTimer = setTimeout(() => this.hide(), 120)
  }

  cancelClose() {
    clearTimeout(this.closeTimer)
  }

  hide() {
    this.contentTarget.hidden = true
    if (openController === this) openController = null
  }
}

And the HTML, where both the badge and the bubble are wired to the same actions:

<div data-controller="popover">
  <button type="button"
          data-action="mouseenter->popover#open mouseleave->popover#scheduleClose
                       focus->popover#open blur->popover#hide"
          aria-describedby="help-<%= card.id %>">?</button>

  <div id="help-<%= card.id %>" role="tooltip" hidden
       data-popover-target="content"
       data-action="mouseenter->popover#cancelClose mouseleave->popover#scheduleClose">
    <%= card.help_text %>
  </div>
</div>

The cancelClose on the bubble is the keystone: it’s what makes the gap between badge and bubble crossable. Take it out and the grace delay only postpones the flicker.

Two details that make the difference

Touch has no hover. On a phone or tablet, mouseenter fires on the first tap and never leaves until you touch elsewhere, and the bubble stays stuck. The matchMedia("(hover: hover)") guard neutralizes the hover logic on those devices; there, a plain tap that toggles the display is more honest. Testing a hover interaction only with a mouse is a classic trap: it works perfectly on the developer’s machine and breaks in the field, where many business users are on a tablet or a phone.

Keyboard and screen readers. I wired focus/blur alongside hover, and tied the badge to its bubble with aria-describedby. Contextual help that only exists on hover doesn’t exist for anyone navigating by keyboard. That took very little code, and it avoids quietly excluding a chunk of your users.

What I take away

The fix comes down to three ideas (grace delay, hot zone extended to the bubble, one open at a time) and about thirty lines. No library, no heavy component. What took effort was seeing the problem and refusing to let it slide.

A business tool is judged in use, across the thousand micro-frictions of daily work, rather than during the demo. Absorbing those frictions on the vendor’s side is invisible work: it shows up in no spec sheet, and users only notice it in the negative, the day the tool stops getting in their way.

If you have an internal tool that “works” but that your teams find vaguely annoying without being able to say why, it’s often an accumulation of details like this one. We can look together at which ones are actually worth fixing.

An offline handwriting notebook in the browser, no native app

2026-10-08T09:00:00+02:00

A business app I build offers a handwritten notes pad on tablets. Its users work in the field, often where the network is bad or simply gone, and they write with a stylus the way they would on a paper pad. Two requirements that normally call for a native app.

I didn’t go native. A PWA (an installable web page, served by a plain Rails app) does the job, provided you respect three realities of the device: there isn’t always a network, the stylus is a real stylus, and it spits out data far faster than you’d expect. Each one hides a trap the tutorials never mention.

The deploy that wipes the offline notes

Offline-first relies on a service worker that caches pages and serves them back when the network drops. The pattern is well known. You name a cache, store the visited pages in it, and on the next deploy you rename the cache to invalidate the old content.

That very rename creates a silent failure. When you bump carnet-v2 to v3, the new service worker’s activate event deletes the old cache. Everything in it goes too, including the notes the user had already viewed offline. The result is that someone installs the update in the morning at the depot, heads out to the field, loses the network, opens their notes… and lands on the “no connection” page. Their data existed; we had just thrown it away.

Renaming the cache is what invalidates the old content, and it is also what throws away the notes already read.

The fix is to migrate the entries from the old cache into the new one before activate does its housekeeping:

self.addEventListener("install", (event) => {
  event.waitUntil((async () => {
    const cache = await caches.open(CACHE_NAME)
    // Carry entries over from any previous cache version before `activate`
    // prunes it. Renaming CACHE_NAME would otherwise wipe already-cached
    // /admin/notes pages, and the offline page relies on them to redirect
    // offline, so a user going offline right after the SW update would land
    // on the dead-end offline page until they revisited notes online.
    for (const name of await caches.keys()) {
      if (name === CACHE_NAME) continue
      const previous = await caches.open(name)
      for (const request of await previous.keys()) {
        if (await cache.match(request)) continue
        const response = await previous.match(request)
        if (response) await cache.put(request, response)
      }
    }
    await cache.add(OFFLINE_URL) // the offline page itself is always refreshed
  })())
  self.skipWaiting()
})

The offline page stops being a dead end along the way: if the notes are cached, a script bounces straight to them instead of announcing a failure.

The stylus that writes “too thick”

For the stroke rendering I use perfect-freehand, which turns a sequence of points into a smoothed, variable-width outline. By default the library simulates pressure from the speed of the gesture: go fast and the line thins, go slow and it thickens.

Great for drawing. Disastrous for handwriting. When you write, you go slow and deliberate, exactly the regime where simulation swells the stroke. The result is pasty letters that don’t match what the hand is doing on screen.

The tablet has a real stylus, which reports real pressure through PointerEvent.pressure. So the right answer is to turn the simulation off and use hardware pressure only, when it is available:

export const FREEHAND_PEN_OPTS = Object.freeze({
  smoothing: 0.45,
  streamline: 0.2,
  // Width comes from real stylus pressure, never from velocity: simulation
  // swelled the stroke at the slow speeds typical of handwriting.
  simulatePressure: false,
  // Little modulation: hard presses made the stroke pasty again.
  thinning: 0.2,
  // Without this, smoothing catches the final point too. See below.
  last: true,
})

With one subtlety: PointerEvent.pressure reads 0.5 when the device reports nothing, mouse and finger included. So once per stroke we check whether any value breaks out of that constant 0.5, and width varies only then.

The line that does not stick to the tip

The symptom was hard to put into words. No visible slowness, no clear stutter, only the sense that the line followed the pen instead of coming out of its tip. So I measured before touching anything, with two scripts replaying real strokes, one for the geometric gap between tip and line, one for the cost of the pipeline in Chromium. Two causes came out.

The tip was being filtered. The streamline option smooths each point toward the previous one, and without last: true it smooths the final one too, the point meant to sit under the pen. Over 67 real strokes, 3497 samples, the rendered tip trailed by 6.1 px on average and up to 75.8 px on fast gestures. One boolean brings the gap to zero and leaves the smoothing to the trail behind it.

The thread froze at the worst moment. Every pointerup queued a bitmap snapshot of the note in requestIdleCallback. Since the next letter starts about a hundred milliseconds later, the callback fired mid-stroke: every outline recomputed, a 2D canvas filled, a WebP encoded synchronously. The line froze for 150 to 950 ms, then jumped to the pen.

The fix owes nothing to an algorithm. The snapshot waits for a second and a half of stillness, never fires during a gesture, and encodes off the main thread; the live stroke left the SVG holding the persisted ones, where rewriting it every frame forced the whole scene to be recomputed, for a dedicated canvas in desynchronized: true. The worst frame while writing went from 199 to 34 ms on a light note, and from 935 to 21 ms on a note of 370 strokes.

That leaves the raw sample rate. At 500 Hz most samples land less than a pixel from the previous one, adding no visible detail. Screen-space distance filtering drops them.

const dx = ev.clientX - this.lastSampleClient.x
const dy = ev.clientY - this.lastSampleClient.y
if (dx * dx + dy * dy < MIN_SAMPLE_DIST_SQ) continue // < 1.2 px: drop it
this.lastSampleClient = { x: ev.clientX, y: ev.clientY }

Distance is measured in screen pixels, not document coordinates, so density holds at any zoom, and we compare the squared value to avoid a root per point. The filter dedupes the pointerrawupdate and pointermove events describing the same point along the way.

The discarded samples carried no visible detail, only per-frame computation.

getCoalescedEvents() and getPredictedEvents() were in place long before this diagnosis and had nothing to do with it. The best-practice list was fully ticked, and the line still came off the tip.

What I take away from it

None of these fixes is sophisticated: a loop, two booleans, a distance comparison. What costs is identifying the right problem. The cache that wipes itself needs a genuinely bad connection, the pasty stroke a real pen in hand, the tip coming off an instrument to measure it. None of that shows up on a MacBook over Wi-Fi during development.

The browser is more than capable of a near-native experience, without the cost of an app to maintain, sign and push through a store. What it asks in return is a test bench that looks like the field: a real tablet, a real pen, and airplane mode.

If this sounds familiar

Offline notebooks, sync that survives a flaky connection, a field app that has to hold up on an iPad that keeps falling asleep: that’s exactly the kind of friction I unblock at SXN Labs. If you have a business use case stuck between “we’d need a native app” and “the web can’t do it”, we can look at what it actually takes.

Connecting a Rails application to French e-prescription through Ordoclic

2026-10-01T09:00:00+02:00

ORIGAMI, the line-of-business software I build and keep in production for medical dispatch, now offers electronic prescribing to its practitioners. The connection was not built directly against the national health insurance services, but through Ordoclic, which exposes its e-health services to integrator vendors through an API. The CNDA certification for e-prescription, though, belongs to ORIGAMI: we ran the pre-series in our own name, with Ordoclic as the technical foundation.

I am writing this path down because it is poorly known, and because smaller vendors give up on it believing they have to absorb everything themselves.

Software that has to prescribe

ORIGAMI is a Rails application used by practising clinicians. At some point electronic prescribing stops being optional: paper becomes an irritant for the doctor, who wants to transmit straight to the pharmacist, and for the patient, who does not want to carry a sheet around. The software has to produce structured, signed prescriptions, file them in the secure database hosted by the national health insurance fund, and let pharmacists retrieve them from an identifier.

Two paths, two regulatory surfaces

The direct path. The vendor registers with the national digital health agency, builds its PKI chain, manages its server and software certificates, integrates the national identity federation or CPS smart cards to authenticate professionals, talks to the e-prescription state service, builds and certifies its own prescribing engine with the health authority, drug database, interaction checks, contraindications and posology included, then files its own CNDA application. This is the route the large incumbent vendors take, and it holds together: the chain is controlled end to end, with no dependency. Its entry and maintenance cost distorts the product of a one or two developer shop.

The integrator API path. The vendor leans on a partner already connected to the state services and already certified as a prescribing engine, which factors out the regulatory plumbing behind an API. The line-of-business software consumes those services and obtains its own CNDA certification on top of that foundation. For the doctor, the experience is the one a directly connected vendor gives: they prescribe, it goes out, the pharmacist queries the database.

The choice turns on how much regulatory surface you carry in-house. Either way the CNDA certification stays in the vendor's name.

What Ordoclic carries

The connection to the national health insurance services and the wider agency ecosystem, with the server certificates and health PKI chain that go with it.
Practitioner authentication through the national identity federation, soft certificates and CPS card readers, without the vendor touching those low-level flows.
Signing the prescription and filing it in the secure database, in the format pharmacists expect, with a unique QR code.
Retrieval on the dispensing side from the prescription identifier.
The prescribing engine itself: certified by the health authority for ambulatory care, CE-marked as a medical device, CNDA-approved for e-prescription, backed by a maintained drug database with interaction, contraindication and posology alerts. This is the heaviest piece to carry alone: a demanding certification framework, an approved drug database to integrate, and revalidation on every change.
Support through the CNDA pre-series, the mandatory step for an integrator vendor to obtain its own certification.

What stays with the vendor

Prescribing does not happen inside ORIGAMI. The doctor clicks a button that opens Ordoclic’s prescribing engine with the context already set, and that is where they prescribe, in front of the interaction and contraindication alerts of the drug database. Once they are done, ORIGAMI receives the secured prescription as a PDF by webhook, files it on the patient record, and sends it to the patient over a secure channel.

That split pushes the vendor’s work to both ends. Upstream, sending the right context: which practitioner is acting, under which national registry number, in which practice context, for which patient. That flow is set up when the doctor’s account is configured and has to stay current on every prescription. Downstream, receiving the webhooks: an endpoint that answers fast, tolerates a replay without creating a duplicate, and records what it filed.

The prescriber’s clinical responsibility is delegated nowhere. The engine displays the alerts, the doctor decides, and the prescription that lands back on the record carries that decision.

When the partner is down

This is what the route costs: if Ordoclic does not answer, nobody prescribes electronically. No degraded mode will produce the prescription later, since signing and filing in the national database both go through the partner. The fallback is a paper prescription.

Better to tell the prescribers before go-live. INSi took an outage better: care carried on, only identity verification stayed pending. Here the feature stops dead, and the availability you announce to doctors is the partner’s, not yours.

The Rails side

The code holds no surprises: authenticated HTTP calls against the integrator API from a dedicated service layer, and an endpoint that receives the webhooks. The patterns from the rest of the application apply unchanged.

The webhook is the piece that takes the most care. It arrives after the fact, on a server that did not follow the prescribing session: it has to find the right record, check the prescription was not already filed, and answer fast enough not to trigger a pointless replay.

An e-prescription in the sense of the state service is a set of structured data, signed and filed in the national database, that the pharmacist retrieves by identifier. The PDF the patient receives is a copy of it, and no pharmacist ever reads it.

Delivering that copy stays the vendor’s job. ORIGAMI sends an email carrying a tokenised link, and the patient confirms their identity with their initials before the document opens. Medical labs and Doctolib have already made that gesture familiar, which saves writing instructions for it.

The vendor holds both ends, the button that opens the engine and the webhook that brings the prescription back. The act itself happens elsewhere.

The CNDA certification belongs to the vendor

The CNDA e-prescription certification obtained this way belongs to the integrator vendor, ORIGAMI here, for a given version of the software. It is earned by running the CNDA pre-series on top of Ordoclic’s engine as a compliant foundation, and it authorises releasing that version to health professionals.

So it is neither an approval earned alone through a direct connection, nor one passively inherited from the partner. It is recorded, attached to a precise version, and replayed on every significant change.

The pattern, for other domain vendors

Lean on an integrator partner rather than aim for a direct connection and an in-house prescribing engine, unless you intend to become a full-time PKI and prescribing-engine vendor.
Keep the vendor responsible for what surrounds the act (context sent to the engine, webhook handling, filing on the record, secure delivery of the PDF to the patient, traceability) and delegate the regulatory plumbing, the drug database and prescribing itself.
Plan the paper fallback and announce it to prescribers, because the feature’s availability becomes the partner’s.
Treat CNDA certification as a state attached to a version, replayed on every significant change.

If this is sitting in your backlog

If you build health software and e-prescription is on your roadmap, the integrator API route exists and works. This is the kind of work I take on at SXN Labs: framing the need, integrating the partner into a Rails application, seeing the CNDA pre-series through, and leaving behind a system that is workable and pleasant to maintain.

The code was right, the shipped package was not

2026-09-24T09:00:00+02:00

In late August I released version 0.9.3 of einvoicing, my e-invoicing gem. It adds and fixes no feature. Version 0.9.2 would not load in a project that did not already have bigdecimal, while its 317 tests passed on my machine.

Works on my machine

The gem uses bigdecimal for amounts and rexml to read XML. Ruby used to install them itself, they now have to be declared as dependencies, and I had not declared them. On my workstation, other gems already pulled them in. Anywhere else, require "einvoicing" failed right away, and Peppol validation failed as soon as it read XML.

The tests run in the repository. The published package only holds the files listed in the gemspec and the declared dependencies, and it installs on a Ruby I do not control. No test looked at that package.

The tests check the repository, the user installs the package.

Three gaps between the repository and the package

A dependency present on the workstation and missing on the user’s side. That is the gap that shipped.
A file read at runtime but missing from the gemspec. The gem embeds an sRGB profile in every PDF/A-3: drop it from the list and every test stays green while the published gem can no longer produce a compliant invoice. I caused it on purpose, and no check saw it.
A lockfile resolved on Ruby 4.0, pinning versions that require Ruby 3.3 while the gem promises to run on 3.2.

The checks added

The first builds the gem as for a release, installs it in an empty environment and loads it. It then compares, file by file, what the repository uses at runtime with what the package contains. An undeclared dependency fails the load, and a missing file is identified.

The second walks the lockfile and verifies that every version accepts Ruby 3.2. A gem it could not verify, for instance when RubyGems rate-limits the requests, counts as a failure.

Those checks had holes of their own, flagged in review. The first loaded the package without looking at its contents, so removing a translation file left everything green. Once fixed, it verified that a gemspec glob matched something instead of checking every expected file. I reproduced each hole by breaking the package on purpose before fixing it.

Beyond Ruby

The same gap exists wherever you test one thing and ship another: an installer tried on the machine that compiled it, a Docker image built with a local cache, a mobile app validated on the developer’s phone.

If you have software built for you, ask what the last check before delivery runs on. If it runs on the contractor’s machine rather than on what you receive, it does not cover what you receive.

Version 0.9.3 and version 0.4.0 of einvoicing-connect have been out since August 31. Their continuous integration now runs the tests on Ruby 3.2 and 4.0, installing the package in an empty environment on both, and the lockfile check.

VAT is not a rate, it is a regime

2026-09-03T09:00:00+02:00

On a PDF, VAT fits in two columns: a rate and an amount. When the rate is zero, you write the reason at the bottom of the page, in plain language, and whoever receives the invoice understands. In a structured electronic invoice, that line of text does not exist. You have to declare a regime code, and if that regime charges no VAT, a coded reason as well. Without it, the flow is rejected at the door.

I maintain einvoicing, an open source Ruby gem that generates Factur-X, UBL and CII invoices compliant with the EN 16931 standard. Recently I ran a batch of fifteen deliberately hostile invoices through it: multi-rate, reverse charge, five hundred lines, overseas rates, foreign currency. The batch went through the XSD schema, the PDF/A-3 container checks and a hand-recomputed EN 16931 rule set.

The batch turned up four defects, all of them in my gem.

The same exemption, written for a reader on the left and for a validator on the right.

Seven regimes, not one rate

The standard does not know about “a 0 % invoice”. It knows seven VAT categories, and zero can come from five of them for entirely different legal reasons:

Code	Regime	Typical case
S	Standard or reduced rate	The ordinary invoice
Z	Zero rated	Certain supplies taxed at 0 %
E	Exempt	Small-business franchise, medical acts, training
AE	Reverse charge	Construction subcontracting
K	Intra-Community supply	EU customer with a valid VAT number
G	Export outside the EU	Sale to a Swiss or American customer
O	Outside the scope of VAT	Certain indemnities and subsidies

My gem stopped at three: standard, zero rated, reverse charge. Everything else came out as “standard”, quietly and without any visible error.

The field paper never asked for

When a category charges no VAT, the standard requires a reason: readable text and, in most cases, a European code. Five compliance rules check for it, one per category.

My gem wrote none of them. As a result, every reverse-charge invoice it emitted was non-compliant. They produced a correct PDF and schema-valid XML while being rejectable by the business rules.

For reverse charge, intra-Community supply, export and out-of-scope, the reason is mechanical: there is a dedicated European code. For plain exemption, there is not. The reason depends on the article invoked, and a small business under the French franchise regime is not exempt for the same reason as a medical practice.

Einvoicing::LineItem.new(
  description: "Consulting work",
  quantity:    1,
  unit_price:  BigDecimal("2500.00"),
  vat_rate:    0,
  category:    :exempt,
  exemption_reason:      "TVA non applicable, art. 293 B du CGI",
  exemption_reason_code: Einvoicing::Tax::VATEX_FR_FRANCHISE
)

That is three lines of configuration. It still requires the software issuing the invoice to have somewhere to store them, which assumes it models the regime and not just the rate.

Three cents apart, and the invoice is refused

The second defect is sneakier. A category’s VAT total can be computed two ways: by summing the rounded VAT of each line, or by applying the rate to the category’s taxable base.

On a five-line invoice, both methods give the same figure. On five hundred lines, they diverge: three cents apart on one category, fifteen on another. The check is verified to the cent, and a “nearly right” invoice is refused like any other.

Both methods are defensible. The check, however, is verified to the cent.

The standard settles on the second method: a category’s VAT amount is derived from its aggregated taxable base, not from the sum of the lines. One multiplication, one rounding, at the end.

# EN 16931, BR-CO-17: category VAT = category taxable base x rate, rounded
# to the cent. The bases therefore add up in BigDecimal, with no intermediate
# rounding, and the rounding only happens after the multiplication.
base = lines.sum(&:net_amount)      # BigDecimal, no rounding here
vat  = (base * rate).round(2)       # rate is 0.20 for 20%, as in the gem

Any rounding placed higher in the chain reopens the gap, which is why the defect survives line-by-line debugging, where every line taken on its own is correct.

And it never shows up in acceptance testing either, because nobody tests a five-hundred-line invoice.

The rates that exist anyway

20, 10, 5.5 and 0. My list of French VAT rates stopped there, like nearly every tutorial out there. So it rejected 2.1 %, the rate for the press and reimbursable medicine. It rejected 8.5 %, the standard rate in Guadeloupe, Martinique and Réunion. It rejected the Corsican rates. All of them perfectly legal.

Same family of error on VAT numbers. My validator held everyone to the French format, buyers included. An intra-Community invoice to Germany therefore failed on the customer’s VAT number, which was perfectly valid.

What both bugs have in common is a reference list written from the common case. It holds until the day a user sells in Corsica or buys from Munich.

Why this becomes a business problem

None of these cases is exotic. The French small-business franchise covers hundreds of thousands of companies. Reverse charge is the rule in construction subcontracting. The overseas rates cover several regions. Foreign currency shows up with the first customer outside the euro area.

Every one of these cases is somebody’s daily routine.

Today these invoices go out and nobody complains, because a human reads them on arrival and mentally fills in what is missing. The moment a machine receives them, there is no mental correction left. There is a rejection, a late payment, and a customer asking you to send it again.

In France, receiving electronic invoices becomes mandatory in September 2026, and issuing them in September 2027 for small and mid-sized companies. The first rejection, though, will land before the date on the calendar.

The question to ask your software vendor

Not “will you be ready for 2027?”. Everyone answers yes.

Rather: “what does your software write in the exemption reason field when I issue a reverse-charge invoice?”. If there is no answer, there is no field.

And to settle the doubt on a specific invoice, there is something faster than theory: run it through a validator, local analysis, no upload. If you want to review your whole chain, the 2026 e-invoicing page describes the assessment I offer.

What I take away from it

My conclusion is a little uncomfortable. I have been writing this gem for months, I know the standard, and I still emitted non-compliant invoices the whole time without a single test flinching.

The trap is not in the standard itself: schema-valid XML can be business-invalid, and nothing will tell you until somebody writes the invoices that hurt. The batch of fifteen hostile invoices cost half a day. It would have cost a great deal more in September 2027.

All of it is fixed in version 0.9.0 of the gem, released right after.

When code describes a feature that doesn't exist

2026-08-24T09:00:00+02:00

While auditing a Rails application, I reviewed its report-sharing flow. The application generated a URL that a user could send to a recipient to grant access to a document. If the URL reached the wrong person or access needed to end, the product needed a way to invalidate it.

The repository appeared to cover that case. A comment described the link as revocable, and a method regenerated its token, which should have made the previous URL unusable. The product, however, offered no revoke button, and nothing invoked the method.

Reading only the code suggested an obvious conclusion: revocation was broken. Following the product raised a different possibility: the feature might never have existed.

A feature that existed only in the repository

I restarted from the entry point. A route created the share, the controller prepared the link, and the interface let the user send it. The flow ended there, with no action to invalidate the URL and no screen for generating a replacement.

The regeneration method completed no user flow. Its name and comment described a coherent capability, but the method remained disconnected from the product. That distinction matters during an audit: a broken revocation feature means users could rely on behavior that failed, while an orphaned implementation points to work that was abandoned or never finished.

The likeliest explanation was a client request taken too literally. “We need to revoke a link” sounds like a need, but it already describes a solution. The underlying problem may have been a link sent to the wrong recipient, access that lasted too long, or poorly defined permissions. None of those cases had been framed, and the method remained after the subject was dropped.

The same mismatch distorts estimates. A team reading the repository may price an enhancement as if revocation already existed, then discover that permissions, interface design, and the behavior of previously issued links still need to be defined.

Proving the code is unreachable

Finding no callers is not always enough in a Rails application. A callback, an interpolated name, public_send, or a background job far from the model may still invoke a method. I checked the code from the entry points the product actually used.

reproduce link creation and use through the interface;
trace the route, controller, views, and background jobs;
search for direct references to the method and token name;
inspect dynamic calls that a text search could miss;
instrument the method temporarily if production traffic leaves any doubt.

That evidence supports a narrow deletion: the method, its comment, and tests that cover only the orphaned implementation can disappear together. Tests around the sharing flow then confirm that creating and opening a link still work. Git retains the previous implementation if the investigation turns out to be incomplete, without forcing the repository to present it as current code.

Delete the code, preserve the need

The dead method did not make revocation available, but the need remained valid. Deleting both together would conflate two separate decisions: cleaning the repository now and deciding whether the product should support revocation.

A real feature ticket still needs to define who can revoke a link, what its recipient sees after invalidation, whether the product creates a replacement automatically, and how the interface confirms the operation. Keeping an unused method answers none of those questions and merely makes the work look almost complete.

The orphaned code can be deleted immediately while the need enters the roadmap with its actual scope. If revocation is prioritized later, its implementation can start from the expected user flow instead of a method discovered by accident.

What the audit should conclude

The report should claim neither a fixed vulnerability nor a repaired feature. It should establish that links had never been revocable, the regeneration method had no callers, and deleting it did not change the product’s behavior.

That conclusion leaves two useful artifacts: evidence supporting the cleanup and a product need that can be prioritized separately. The next reader will no longer mistake an abandoned intention for an available capability.

Turbo has three scopes, not three tools

2026-08-06T09:00:00+02:00

Turbo’s documentation has a reputation for being incomplete. It isn’t, not really: every page says roughly what it should say. The problem is elsewhere. Drive, Frames and Streams are documented side by side, as three separate products, with nothing saying what connects them or how to choose. You learn the syntax of each one, and you stay stuck on the question that matters when you sit down to write: which one, here, now.

When choosing, I look at two things: which part of the document changes and when its target is decided. Drive implicitly targets the whole page. A frame names its fragment before the request is sent. A stream lets the server name its targets in the response. That gives the three mutation scopes used throughout this article: the whole page, a named fragment, or a set of elements designated by a response.

remove, refresh, custom actions and broadcasts are not literally replacements, but the model still holds. Morphing changes how the mutation is applied, not its scope.

This is the guide I wanted three years ago. Use the model and decision table to choose a primitive, and the checklist and symptom index to debug one. The rest documents Turbo 8.0.23.

Versions and confidence levels

This article targets Turbo 8.0.23 and turbo-rails 2.0.23, released on 29 January 2026, with Rails 8. Most details below come from the source and tests for those pinned versions. Callouts that depend on a particular guarantee use the following labels:

API documented on turbo.hotwired.dev. You can rely on it, and breaking it would be an acknowledged breaking change.
Verified the behaviour is present in the pinned source or tests but absent from the public API. Usable, as long as you test it yourself and re-test after an upgrade.
Internal implementation detail. Precious for understanding a bug, dangerous as a foundation. Build nothing on it.

Links to Turbo and turbo-rails source code point at the v8.0.23 and v2.0.23 tags, so at frozen lines: they will still say what I claim they say long after main has moved on.

What's inside

The model in one pagethe three scopes, and who designates the target
Which primitive should you reach for?the decision table, and the two tests that settle it
Turbo Drivewhat is intercepted, the lifecycle, the cache, the config
Turbo Framesthe identifier rule, the layout, the attributes that matter
Turbo Streamsthe two worlds, the controller-to-view path, the eight actions
The HTTP status, and why 422
Morphingwhat it removes, idiomorph, the pantry, field values
Broadcaststhe macros, the request-id, the debounce, stream security
Stimulus and third-party libraries
Network and offlinefetch failures, service workers, Action Cable
Debugging checklistin this order, before you open a ticket
The symptom indexyou have a bug, you start here
What changed recently

If you are here because something is broken, go straight to items 11 and 12, then work your way back up to the relevant section.

The model in one page

The same mechanism, three scopes. What changes from one column to the next: the extent of the replacement, who designates its target, and when.

With Drive, the target is implicit: it is the <body>. It is never negotiated, so there is no identifier contract to honour. The client decides to navigate, the server responds with a page, Turbo swaps the body and merges the head.

With Frames, the target is decided by the client before the request even leaves. The emitting frame puts its identifier in a Turbo-Frame header. On the normal extraction path, Turbo accepts only the element carrying that same identifier, either directly or through a recurse frame. The server cannot redirect the content into another frame. It can only bypass extraction with turbo-visit-control: reload, which turns the response into a full-page visit.

With Streams, the target is written into the response, so it is decided at the last moment, by the server. It says replace the element with this id, append this to the end of that one, remove that other one. It can aim at several non-contiguous places, and it can do so without anyone having asked for anything, over a WebSocket.

Remember

Frames and Streams both rely on a DOM contract. The normal frame extraction path must find the expected identifier, either directly or through recurse; otherwise Turbo dispatches turbo:frame-missing, displays Content missing unless the event is cancelled, and throws. turbo-visit-control: reload bypasses that path entirely with a full-page visit. A stream target must exist when the command arrives; if it does not, Turbo silently does nothing.

Which primitive should you reach for?

The table below is the short version. It does not rank the tools from simplest to most advanced. Start with where the state originates, then pick the first row that describes the actual need.

What you need	The primitive	Why this choice
The state is purely client-side and the server has no business knowing about it	Stimulus, without Turbo	A round trip to open a menu is one round trip too many
The whole page changes and the URL must remain shareable	Drive, meaning nothing to write	It is already on. Reach for a frame only when the navigation belongs to one named region; frames can participate in history with `data-turbo-action`
One named zone changes, and a URL returns a document containing that frame	Frame	Lazy loading, loading state and internal navigation come for free. The response may be a full page; Turbo extracts the matching frame. A stream would make you write the same thing by hand
Several non-contiguous zones change in response to a user action	A `.turbo_stream` response	A frame can only aim at one fragment. Slicing the page into five frames to fake a stream multiplies the requests
The change comes from the server, with nobody clicking in this tab	A broadcast	It is the only path that can arrive without an originating request in the tab. When Turbo renders the broadcast HTML itself, its synthetic renderer has no browser session or usable `current_user`

That leaves the case where both look possible.

The URL test, for frames. If there is no navigable URL whose response contains the matching frame, a frame is probably not what you want. That response does not have to be a fragment-only endpoint: a full document containing the expected <turbo-frame> is the normal case. A frame is a small browser with an address and a loading state, and it can also promote its navigations into Drive history with data-turbo-action.

The recipient test, for streams. If only the tab that just acted needs to change, use a .turbo_stream response. If other tabs must receive the mutation without having made that request, use a broadcast. These are two very different uses sharing one format, and confusing them is a common source of HTML broadcast to the wrong user.

Turbo Drive

Drive is active as soon as you load @hotwired/turbo. There is nothing to write: despite the documentation’s chapter order, Drive covers most navigation needs.

What is intercepted, and what is not

Drive intercepts unmodified primary clicks on navigatable <a href> elements and navigatable form submissions, provided their destination is visitable. A visitable URL stays under the page’s <meta name="turbo-root"> (/ by default) and its extension does not appear in Turbo.config.drive.unvisitableExtensions (about fifty extensions, including .pdf, .zip, .csv, .jpg). Cross-origin URLs are therefore excluded with the default turbo-root. The extension list is configurable and is documented nowhere on the official site.

Turbo also leaves download links, every link whose target differs from _self, and forms with method="dialog" to the browser.

You switch it off case by case with data-turbo="false" on the element or any of its ancestors. A data-turbo="true" nested further down turns it back on.

The lifecycle

There is no universal sequence. This table follows an advance link navigation that opens a Drive visit with a fetch. It assumes a cacheable departure document and no preview snapshot. A full-page form submission makes its own request first, while a restoration from cache skips the fetch events. On the initial page load, turbo:load fires without turbo:render. Render hooks can also run twice for a preview. The last column remains the useful one because several names are misleading.

Event	Fired on	Cancelable	What it actually lets you do
`turbo:click`	the clicked `<a>`	✓	Cancel to let the browser do a plain navigation
`turbo:before-visit`	`<html>`	✓	The last place you can refuse the visit
`turbo:before-fetch-request`	`<html>` on a visit, the frame or form involved, the `<a>` on a prefetch or preload	✓	`preventDefault()` does not block the request, it pauses it until you call `detail.resume()`
`turbo:visit`	`<html>`	✕	Informational. `detail.action` is `advance`, `replace` or `restore`
`turbo:before-fetch-response`	`<html>` on a visit, the frame or form involved, the `<a>` on a prefetch or preload	✓	Cancelling stops the Visit/Frame/FormSubmission delegate from handling the response. It does not block a turbo-stream by itself: `StreamObserver` ignores `defaultPrevented` and may apply it from the same event
`turbo:before-cache`	`<html>`	✕	Clean the DOM before caching. Cloning is deferred until the next event-loop tick
`turbo:before-render`	`<html>`	✓	Same pause semantics. `detail.newBody` can be modified before rendering, `detail.renderMethod` is `replace` or `morph`
`turbo:render`	`<html>`	✕	The new body is in place
`turbo:load`	`<html>`	✕	End of the visit. On the initial load, Turbo fires it when `readystatechange` reaches `interactive` or `complete`; an async bundle loaded after `DOMContentLoaded` can start too late and miss it

First surprise, turbo:before-fetch-request comes before turbo:visit. Visit#start() calls this.adapter.visitStarted(this), which prepares the request, before this.delegate.visitStarted(this), which dispatches turbo:visit (visit.js#L114-L118). The actual fetch() still waits for interception to finish, but a listener installed from turbo:visit has already missed turbo:before-fetch-request. Listen to that event directly if you need to observe or modify every request.

The other surprise comes down to a dispatch() default: with no explicit target, it fires on document.documentElement, not on document (util.js#L29-L44). The events bubble, so listening on document works, but event.target is <html>, which matters if you filter on it. This is true for both fetch events of a Drive visit. A frame fetch targets the frame, a form submission targets the <form>, and a prefetch or preload targets the <a>.

And the events specific to frames and forms, which slot into the same sequence:

Event	Fired on	Cancelable	What it actually lets you do
`turbo:before-frame-render`	the frame	✓	Pause, and `detail.render` is replaceable: this is the official entry point for plugging in another rendering engine
`turbo:frame-render`	the frame	✕	Declared `cancelable: true`, but the dispatch return value is discarded: cancelling does nothing
`turbo:frame-load`	the frame	✕	The frame is done
`turbo:submit-start`	the `<form>`	✕	`detail.formSubmission`
`turbo:submit-end`	the `<form>`	✕	Always `detail.formSubmission`. A response handled by `FormSubmission` adds `success` and `fetchResponse`; a network error adds `success: false` and `error`. Those keys are absent after an abort and after the `Form responses must redirect` guard rejects a non-redirected unsafe 200 response.

Under the hood Verified

turbo:before-fetch-request does one more thing than its name suggests. Pausing it is documented in the handbook, but not the fact that Turbo re-reads the URL afterwards: this.url = event.detail.url (fetch_request.js#L183-L199), and that this.url is exactly what goes into the fetch a moment later. Rewriting event.detail.url from a listener therefore really does change the URL that gets called, which is the shortest way to add a tenant prefix to every Turbo request at once.

You still have to do it synchronously in the listener: the assignment happens before the pause’s await, so changing detail.url after a preventDefault() and before resume() has no effect. And assign a URL object, not a string: Turbo reads this.url.href, and a string gives undefined. It is not in the handbook, but it is covered by the repository’s own test suite (form_submission_tests.js#L191-L204), which makes it a sturdier guarantee than it looks.

The rest of the lifecycle bugs almost always come from the snapshot or the preview.

The snapshot comes from the page you are leaving, not the one you are loading. turbo:before-cache fires on the live document, then PageView#cacheSnapshot() waits until the next event-loop tick before calling cloneNode(true). Synchronous cleanup in this hook remains the deterministic path. The visit does not await cacheSnapshot(), however, so replacing the <body> and a Stimulus disconnect() can change the old DOM before it is cloned. A disconnect() is not necessarily too late to clean the cache.

The clone loses the listeners but keeps whatever injected DOM still exists at that point. That is how a library can end up initialized twice on back navigation; we will return to it later.

Useful detail: the clone also restores the selection of <select> elements (which cloneNode loses), clears the value of every input[type=password], and removes <noscript> elements.

A preview from the cache can fire turbo:render twice, but not on back navigation. On an advance or replace visit, Turbo uses a cached snapshot only when it is previewable and, when the URL has an anchor, contains that anchor. It renders the snapshot while the fetch continues; if the fresh response is itself rendered, a second turbo:render follows. During the first render, <html> carries the data-turbo-preview attribute.

The nuance matters, and I had it wrong for a long time. A restoration visit with a usable snapshot issues no request and renders once. Without a usable snapshot, it goes back to the network. advance and replace describe history actions, not just link clicks or form submissions: Turbo.visit() and a page refresh can produce them too.

Under the hood internal

It all comes down to a six-line method: shouldIssueRequest() returns !this.hasCachedSnapshot() when this.action == "restore", and this.willRender otherwise (visit.js#L377-L383). And loadCachedSnapshot computes its preview as const isPreview = this.shouldIssueRequest() (visit.js#L245-L265). No request, so no preview, so a single render.

In practice, the guard to write in a Stimulus controller is unchanged:

connect() {
  if (document.documentElement.hasAttribute("data-turbo-preview")) return
  this.initExpensiveWidget()
}

The cache, in numbers

The Drive cache is an LRU of ten snapshots, in memory, in the tab. No localStorage, no IndexedDB, no Cache API. It dies when the tab closes and on reload. Each entry keeps a clone of the <body> and an index of the <head>, including <img>, <link>, and <script> elements. It does not store the bytes of images, stylesheets, or scripts; reusing those is the browser’s HTTP cache job.

Remember

Turbo’s cache is a perceived-latency optimization, not an offline strategy. A restoration visit can display an existing snapshot without a request after the network drops, but the cache survives neither a reload nor a closed tab and cannot guarantee that the page you need is still present. Do not use it as a persistence layer.

You often read that the cache is emptied “on every unsafe form submission”. That is true for half the cases only, and the other half is surprising.

Under the hood internal

The clearing is asymmetric. On the full-page success path, clearSnapshotCache() is only called when !formSubmission.isSafe, and only inside the if (responseHTML) branch: an unsafe submission whose response is not HTML clears nothing (navigator.js#L71-L90). On the full-page failure path, the cache is cleared when responseHTML exists, including for a safe GET form returning an HTML 4xx or 5xx (navigator.js#L92-L107). Inside a frame, the form-submission callbacks differ: an unsafe success and every failed HTTP response clear the cache even without HTML (frame_controller.js#L246-L260). A network error goes through formSubmissionErrored() and does not clear it; neither does a failed link or src navigation.

Concretely, a GET search form clears the entire cache if it returns an HTML 4xx or 5xx as a full-page submission, or any 4xx or 5xx inside a frame. Nothing tells you.

What is left for you to tune:

What you want	How
Never cache this page	`<meta name="turbo-cache-control" content="no-cache">`
Cache it but never show it as a preview	`<meta name="turbo-cache-control" content="no-preview">`
Remove an element before caching	`data-turbo-temporary` on the element

data-turbo-cache="false" was removed in 8.0.21, in January 2026, after three years of deprecation. So was Turbo.clearCache(), replaced by Turbo.cache.clear(). Both still linger in a pile of blog posts, and in Stack Overflow answers, that site where humans used to write documentation for one another.

Turbo.config

Since 8.0.6, configuration goes through a single object. The old setter functions (setProgressBarDelay, setConfirmMethod, setFormMode) still exist but emit a console warning.

Turbo.config.drive.progressBarDelay = 500          // ms before the progress bar
Turbo.config.drive.enabled          = true
Turbo.config.forms.mode             = "on"         // on | off | optin
Turbo.config.forms.submitter        = "disabled"   // disabled | aria-disabled
Turbo.config.forms.confirm          = async (message) => window.confirm(message)

Under the hood Verified

Of those five lines, two are documented on the Drive reference page: Turbo.config.drive.progressBarDelay and Turbo.config.forms.confirm. drive.enabled, forms.mode and forms.submitter appear nowhere on turbo.hotwired.dev. The three modes are inferred from the two equality tests in Session#submissionIsNavigatable plus the "on" default; there is no enum in the source.

One detail that goes with it, and it bites: set submitter(value) { this.#submitter = submitter[value] || value } (config/forms.js#L33-L35). An unrecognized string is stored as-is, without error, and blows up later on config.forms.submitter.beforeSubmit(...). A typo only shows up on the first submission that has a submitter; a submission triggered without one never makes that call.

forms.submitter deserves a word. By default, Turbo sets disabled on the submitter during submission. The control then leaves the tab order and, if it had focus, loses it; depending on the browser and assistive technology, focus may fall back to <body> and disorient someone navigating by keyboard or screen reader. With "aria-disabled", Turbo sets aria-disabled="true" and intercepts clicks on the submitter, which remains focusable. That blocks a second click handled by Turbo, not a submission triggered directly from code.

Turbo.config.forms.submitter = "aria-disabled"

If the interface should preserve focus during submission, this line in application.js is the better default. Just remember to style the aria-disabled state.

Prefetching

Since Turbo 8, prefetch on hover is on by default. For an eligible link, Turbo waits 100 ms after mouseenter, sends a GET with the X-Sec-Purpose: prefetch header, and keeps the response in a single-entry cache for 10 seconds by default. The turbo-prefetch-cache-time meta tag changes that TTL in milliseconds. Leaving the link before the delay expires cancels the start.

Not every link qualifies. It needs a same-origin, visitable HTTP(S) URL with no target, download, data-turbo="false", unsafe method, stream, confirmation, or UJS attribute; links to the current page are excluded too. turbo:before-prefetch can still cancel. Hovering any other eligible link does send a request to your server. If your GET actions are not idempotent, or if your server does not like free traffic, switch it off:

<meta name="turbo-prefetch" content="false">     <%# global %>
<a href="/x" data-turbo-prefetch="false">…</a>   <%# per element %>

Not to be confused with data-turbo-preload, which only applies to <a> elements and which Turbo scans after the initial load and after every view render rather than on hover. It warms the same Drive snapshot cache; only hover prefetching has the separate one-entry, ten-second cache.

Turbo Frames

It all comes down to one identifier

After turbo-visit-control, Turbo looks for the frame directly or through recurse. If no frame matches, it dispatches turbo:frame-missing.

The matching rule, literally, is container.querySelector("turbo-frame#" + CSS.escape(id)). No fuzzy matching, no configurable selector. In practice, have the server echo the identifier sent by the client with turbo-rails’ turbo_frame_request_id helper:

<%= turbo_frame_tag turbo_frame_request_id || "invoice_detail" do %>
  …
<% end %>

The fallback is not decorative: on a full-page visit the header is absent and turbo_frame_tag nil produces id="", which breaks every later navigation to that frame, without a word.

There is a second chance, rarely used: the recurse attribute. If no frame with the same id is found but a <turbo-frame src="…" recurse="my-id"> is present, Turbo waits for it to load and then looks inside it. The ~= syntax belongs to Turbo’s internal CSS selector, not to the HTML attribute.

And if nothing matches, the sequence is this:

complete is set on the frame, before the event.
turbo:frame-missing is dispatched on the frame, cancelable, with detail.response (a raw Response) and detail.visit(urlOrResponse, options).
If nobody cancels, the frame displays <strong class="turbo-frame-error">Content missing</strong> and Turbo throws a TurboFrameMissingError.

Session expiry gives a common example: the request leaves from the frame, the server redirects to /login, and the login page obviously does not contain your frame. Rather than intercepting the event, mark the login page:

<%= turbo_page_requires_reload %>

which emits <meta name="turbo-visit-control" content="reload">. Turbo then skips frame extraction entirely and performs a full-page visit. That is the intended escape hatch, and it is far better than a global turbo:frame-missing listener.

A trap while we are here, and it applies to turbo_refreshes_with further down too: this helper calls provide :head. It writes nothing at the call site, despite the <%= %>. Without <%= yield :head %> in your layout, the meta tag never comes out and nothing happens. The turbo_page_requires_reload_tag variant renders the tag in place if you prefer to position it yourself.

The layout, and the static layout trap

turbo-rails installs this into ActionController::Base:

layout -> { "turbo_rails/frame" if turbo_frame_request? }
etag   { :frame if turbo_frame_request? }

The turbo_rails/frame layout is minimal (just csrf_meta_tags and yield :head), not absent, so that content_for :head and CSRF keep working.

The trap: if you write layout "admin" in a controller, you overwrite that lambda. Frame requests will then render the full layout. It still works, because Turbo parses the response outside the live DOM and extracts the frame, but you pay the server-rendering, network and parsing cost of the entire layout on every frame request. The discarded <head> scripts are not evaluated. Scripts inside the extracted frame are activated during rendering, except those marked data-turbo-eval="false". You have to convert the declaration into a method:

layout :layout_for_request

private

def layout_for_request
  turbo_frame_request? ? "turbo_rails/frame" : "admin"
end

Trap

No error, no warning, and the frame renders perfectly. Just a silent server, network and parsing bill on every request. The response’s <head> is parsed and discarded, not executed. This is the kind of regression that only shows up when you profile.

The attributes that matter

Attribute	Effect
`src`	Loads this URL into the frame. In the `turbo_frame_tag` helper, the value goes through `url_for`, so a model works.
`loading="lazy"`	Defers the first load of `src` until the frame enters the viewport. Within one `FrameController`, later `src` changes load immediately. After a Drive restoration the controller is recreated and that internal flag starts over, so a new `src` outside the viewport can wait again.
`target`	Default target for descendant links and forms.
`data-turbo-frame`	On a link, a form or a submit button. Overrides `target`. The button wins over the form.
`_top`	Breaks out of the frame: Drive treats the navigation as a full-page visit.
`_parent`	Targets the nearest ancestor frame. Added in 8.0.21.
`busy`	Set by Turbo during loading, along with `aria-busy="true"`. Useful in CSS.
`complete`	Set after rendering a matching frame, but also before `turbo:frame-missing`. On a connected frame, a `src` change or `reload()` removes it. The JS property `frame.complete` reports the current loading state and does not read this attribute.
`disabled`	Cancels the current `src` fetch and stops the frame from intercepting new navigations. A descendant link or form can then fall through to Drive and navigate the full page; a form submission already in flight is not cancelled.
`autoscroll`	Calls `scrollIntoView()` on the first element child after rendering; an empty frame does not move. `data-autoscroll-block` defaults to `end` and `data-autoscroll-behavior` to `auto`.
`refresh="morph"`	Morphs the contents fetched by `reload()`. During a page refresh rendered with morphing, Turbo keeps a compatible `src` frame outside a `data-turbo-permanent` region and calls that reload automatically.

The table does not say everything about how a frame handles a response.

For a link or src navigation, once an ordinary HTML response reaches FrameController, HTTP status does not choose the frame renderer. The direct requestSucceededWithResponse and requestFailedWithResponse callbacks both call loadResponse(). A 4xx or 5xx with non-empty HTML and a matching frame can therefore render like a 2xx. A turbo-stream Content-Type is intercepted earlier by StreamObserver. Other non-HTML Content-Types and empty bodies produce no frame render and no turbo:frame-render, turbo:frame-load, or turbo:frame-missing, although turbo:before-fetch-response has already fired. Cancelling that event blocks the FrameController path, with the stream exception described in the table. With turbo-visit-control: reload, Turbo abandons extraction and starts a full-page visit with a console warning; without a matching frame, it follows the turbo:frame-missing path above.

An ordinary HTML form submission takes a different path. Unless turbo:before-fetch-response is cancelled, a 4xx or 5xx puts detail.success === false in turbo:submit-end, clears the snapshot cache, and calls loadResponse() on the originating frame. If the form targeted another frame, that target is therefore ignored for the failure and Turbo looks for the originating frame’s id in the response. A success uses the resolved target instead, and only clears the cache for an unsafe method.

Under the hood internal

One clarification, because “the status is never consulted” is slightly wrong. loadResponse does read two status-derived properties, but for one thing only: updating src.
if (fetchResponse.redirected || (fetchResponse.succeeded && fetchResponse.isHTML)) {
  this.sourceURL = fetchResponse.response.url
}
(frame_controller.js#L132-L135) After a link navigation or direct src assignment, the frame already points at the requested URL: if it returns an HTML 404, reload() repeats that failing URL. A form submission does not copy its action into src. On a non-redirected failure, the originating frame therefore keeps its previous src, if it had one, and reload() may return there; with no src, it loads nothing. After a redirect, src always takes the final URL even when its status is a failure.

A form submission inside a frame does not need to redirect. The Form responses must redirect to another location error is triggered only for an unsafe full-page submission whose final response is exactly 200 OK without a redirect. GET submissions do not have that constraint, and the guard does not cover other 2xx statuses. Inside a frame, mustRedirect is false: a 200 OK with a matching frame is valid.

Turbo Streams

A <turbo-stream> is an envelope. It carries an action, a target, and a <template>:

<turbo-stream action="replace" target="invoice_42">
  <template><div id="invoice_42">…</div></template>
</turbo-stream>

There are two worlds behind this format, and conflating them causes a fair share of Turbo Stream bugs.

The format is identical and the tab cannot tell them apart. The whole difference was settled earlier, when the server rendered.

The first world is an HTTP response: the user does something, the server responds with text/vnd.turbo-stream.html, and the tab that made the request applies it. It is synchronous, it lives in the request context, current_user exists, and the HTML is rendered for that one person.

The second is a broadcast: the server publishes on an Action Cable channel, and every subscribed tab receives it. The model macros use jobs for operations that render HTML, but turbo-rails also exposes synchronous broadcast methods. When turbo-rails has to render the HTML, its synthetic renderer has no browser session or usable current_user. A synchronous call, perform_now, or the :inline adapter may still see thread-local state such as Current.*; a job actually dequeued by a worker does not inherit it. A call that already receives html: or content: skips that renderer, and a refresh renders no HTML. When turbo-rails renders the partial, it produces one HTML payload and sends it unchanged to every subscriber. We come back to it below, because that is where the real problems hide.

Remember

The format says nothing about the context. A <turbo-stream> received by a tab carries no trace of where it came from, and the application code is the same in both cases. Everything that separates the two worlds happened server-side, at render time, which is to say at the moment you decide what goes inside the <template>.

Frames or Streams? What really separates them

Both can replace a piece of a page, and that is where the confusion starts.

Criterion	Turbo Frame	Turbo Stream
Who designates the target	The client, before the request leaves	For a targeted action, the server, in the response
How many zones	One, the frame’s own	Per `<turbo-stream>`: zero or one with `target`, every match with `targets`. A response can contain several elements
Is the mutation a navigation	Yes: a URL returns the expected frame	No: the stream describes a mutation, even when its request has a URL
History and back button	Optional, with `data-turbo-action`	No
Lazy loading	Yes, `loading="lazy"`	No
Can it fire without a request	No	Yes, that is the broadcast
What happens when the target is missing	On the direct path, `turbo:frame-missing`, then “Content missing” by default; `recurse` may still load the expected frame, and `turbo-visit-control: reload` bypasses extraction	For a targeted action, nothing at all, silently
What the server must know	The expected identifier, usually echoed from the `Turbo-Frame` header	For a targeted action, the `id` through `target` or the CSS selector through `targets`. `refresh` has no target

The last row is the one that should decide. On the normal direct path, a frame limits the contract to one matching fragment: the server may render a full page, but it must contain the requested identifier. recurse can find it in a second response, while turbo-visit-control: reload abandons that contract for a full-page visit. A targeted stream action is more coupled: the server must know how to address its targets in the live DOM, with no way to verify that contract. refresh is the exception because it names no target.

If you knew Rails before 2021, the first world will ring a bell. Answering a submission with a document that describes DOM mutations is exactly what create.js.erb did back in the UJS days. The difference is format and vocabulary: the server returns HTML instead of arbitrary application JavaScript, and Turbo ships eight built-in actions. Custom actions extend that vocabulary explicitly, rather than opening the door to “everything jQuery knows how to do”. The main gains are readable responses and bounded intent. That is not a security boundary: Turbo deliberately activates <script> elements inside stream templates, so untrusted HTML is still untrusted HTML.

The full path, from controller to view

A conventional controller looks like this:

# app/controllers/invoices_controller.rb
def create
  @invoice = Invoice.new(invoice_params)

  if @invoice.save
    respond_to do |format|
      format.turbo_stream                                    # -> create.turbo_stream.erb
      format.html { redirect_to @invoice, status: :see_other }
    end
  else
    respond_to do |format|
      format.turbo_stream do
        render turbo_stream: turbo_stream.replace(
          "invoice_form", partial: "invoices/form", locals: { invoice: @invoice }
        ), status: :unprocessable_entity
      end
      format.html { render :new, status: :unprocessable_entity }
    end
  end
end

A bare format.turbo_stream renders a template; use it when several regions change. Inline render turbo_stream: also accepts several concatenated tags, but its main convenience is avoiding a file for simple responses.

The template is a plain ERB file that uses the stream builder:

<%# app/views/invoices/create.turbo_stream.erb %>
<%= turbo_stream.prepend "invoices", @invoice %>
<%= turbo_stream.update "invoices_count", Invoice.count %>
<%= turbo_stream.replace "invoice_form" do %>
  <%= render "invoices/form", invoice: Invoice.new %>
<% end %>

Those three lines condense almost the whole API, and each one hides something.

turbo_stream.prepend "invoices", @invoice takes no partial: passing a record is enough, the builder calls to_partial_path and renders invoices/_invoice.html.erb. That is also why this partial must render an element with id="<%= dom_id(invoice) %>"; without it, record-based helpers cannot target the element directly later.

turbo_stream.update accepts a raw string as content, which saves a one-line partial for a counter.

The block form captures whatever you write inside the current view context. In an HTTP response it therefore sees the controller ivars, including those set by before_action hooks. The synthetic context described above applies only when rendering a broadcast.

And on the calling view side, the rule is the same as everywhere: what the stream aims at must exist with the right id.

<%# app/views/invoices/index.html.erb %>
<div id="invoices_count"><%= @invoices.count %></div>

<div id="invoices">
  <%= render @invoices %>
</div>

<div id="invoice_form">
  <%= render "invoices/form", invoice: Invoice.new %>
</div>

<%# app/views/invoices/_invoice.html.erb %>
<div id="<%= dom_id(invoice) %>" class="invoice">
  <%= invoice.reference %>
  <%= button_to "Supprimer", invoice, method: :delete, form: { data: { turbo_confirm: "Sûr ?" } } %>
</div>

Note data-turbo-confirm on the button_to form, the direct successor to rails-ujs’ data-confirm. The difference is that it is pluggable: Turbo.config.forms.confirm accepts your own function, which finally lets you replace the native dialog with your own modal without rewriting the mechanism.

Eight actions, and `morph` is not one of them

Action	What it does	Target required
`append`	Adds to the end of the target’s content	✓
`prepend`	Adds at the beginning	✓
`before`	Inserts before the target	✓
`after`	Inserts after the target	✓
`replace`	Replaces the target itself	✓
`update`	Replaces the target’s content	✓
`remove`	Removes the target. No `<template>`	✓
`refresh`	Refreshes the current URL through a `replace` visit. No `<template>`	✕

That is all. There is no morph action. Morphing is an attribute, method="morph", and among the targeted actions only replace and update read it. Writing turbo_stream.append("x", method: :morph) does produce the attribute in the HTML, and the JavaScript handler for append simply ignores it. refresh reads method too, but for another reason: to choose the render mode of the page refresh there, broadcast by broadcast.

The reference documents how append and prepend deduplicate: if a direct child of the target carries the same id as a top-level incoming element, the old one is removed. append therefore behaves like an upsert. Since 8.0.21, before and after apply the same rule to the target’s siblings; that extension is not yet in the reference.

refresh also carries a request-id attribute. It lets the originating tab ignore a recent request it has already applied; the client-side debounce that merges closely spaced refreshes is independent of that identifier. The broadcasts section covers both mechanisms.

`target` and `targets` are not the same thing

turbo_stream.replace     "invoice_42"        # target  => getElementById
turbo_stream.replace_all ".invoice-row"      # targets => querySelectorAll

target takes a bare DOM id, not a selector, and resolves to at most one element. targets takes a CSS selector and applies the action to every match. If both are present, target wins.

On the Ruby side, this difference in kind is absorbed for you. If you pass a record rather than a string, the helper puts the hash in the right place:

turbo_stream.replace     @invoice   # target="invoice_42"    <- bare dom_id
turbo_stream.replace_all @invoice   # targets="#invoice_42"  <- dom_id with the #

The trap appears when you write the selector by hand, because at that point nobody is correcting it any more: turbo_stream.replace_all "invoice-row" without the dot or the hash matches nothing, and says nothing.

The silence when the target does not exist

If document.getElementById(target) returns null, the getter returns an empty array, and every action iterates over that empty array. No warning, at any log level. The stream arrives, it is visible in the Network tab, it is visible in the Rails logs, and nothing happens.

The classic causes: a misspelled or accidentally pluralized dom_id, a target living inside a <template> or an <iframe> (explicitly unsupported), or a target inside a loading="lazy" frame that has not loaded yet.

Debug internal

Total silence only applies to a target that is present but not found. If the attribute itself is missing, get targetElements() throws "target or targets attribute is missing", and get performAction() throws "unknown action" or "action attribute is missing" (stream_element.js#L95-L120). Those throws are caught by connectedCallback’s try/catch and surface as console.error (stream_element.js#L33-L41), visible, but with no event and nothing on screen.

Check the console first: silence despite a received stream points to a missing target; a console.error points to a missing attribute or an unknown action.

There is a second one, sneakier. On a GET request, Turbo sends the Accept: text/vnd.turbo-stream.html header only if the link or the form carries data-turbo-stream. Without that attribute, normal content negotiation falls back to HTML, unless the URL or params explicitly force the turbo_stream format.

Adding your own actions

The mechanism is simpler than it looks and it is a good investment as soon as you catch yourself stacking streams to express a single intention.

On the Ruby side, a load hook:

# config/initializers/turbo.rb
ActiveSupport.on_load :turbo_streams_tag_builder do
  def highlight(target)       = action     :highlight, target
  def highlight_all(targets)  = action_all :highlight, targets
end

On the JavaScript side, an entry in Turbo.StreamActions, where this is the <turbo-stream> element:

Turbo.StreamActions.highlight = function () {
  this.targetElements.forEach((el) => {
    el.animate([{ backgroundColor: "#FFD83F" }, { backgroundColor: "transparent" }],
               { duration: 1200 })
  })
}

And from a model, without going through the builder:

after_update_commit -> {
  broadcast_action_to "plannings", action: :highlight, target: "gantt", html: ""
}

If the action is not registered on the JavaScript side, the element throws unknown action. It is one of the rare places where Turbo is loud.

The HTTP status, and why 422

Turbo does not choose a renderer by reading the request headers on the way back. The fetch delegate is known before the request leaves: FrameController for frame navigation, Visit or FormSubmission for full-page navigation. The response then follows this path:

If the Content-Type starts with text/vnd.turbo-stream.html, StreamObserver intercepts the response and applies the <turbo-stream> elements, regardless of status.
Otherwise the response goes back to that delegate. The Turbo-Frame header tells the server which fragment to render; Turbo does not use it as a client-side response switch.
On the full-page path, status then helps choose the normal renderer, the error renderer, or a refusal to render.

A Hotwire form that appears frozen often comes down to one line of Turbo’s code:

responseSucceededWithoutRedirect(response) {
  return response.statusCode == 200 && !response.redirected
}

For a full-page non-GET submission, if you answer with 200, HTML and no redirect, Turbo prints console.error("Form responses must redirect to another location") and renders nothing. The page looks frozen. The form went out, the progress bar ran all the way, and the error messages never appeared. A submission inside a frame does not pass through this guard.

The reason is given in the manual, and it is a good one: browsers have native behaviour for reloading a page that came from a POST, that “do you want to resubmit the form?” dialog, which Turbo cannot reproduce. Rather than lie about the URL, it refuses.

Hence the Rails convention, which the scaffold generator already applies:

render :new, status: :unprocessable_entity  # 422: the response is rendered, the URL does not move
redirect_to @invoice, status: :see_other    # 303: after update and destroy

The 303 is not a Rails whim: it is the unambiguous way to say that the redirect target must be fetched with GET. Turbo passes redirect: "follow" and lets the browser follow. Under the Fetch specification:

303 replaces every method other than GET or HEAD with GET.
301 and 302 force the switch to GET only for POST. An actual DELETE would keep its method.
307 and 308 always preserve the method.

There is an important turbo-rails detail here. In version 2.0.23, encodeMethodIntoRequestBody turns methods other than GET into a POST with an _method parameter before Fetch sees them (fetch_requests.js#L1-L18); Rails’ button_to method: :delete also submits a POST with a hidden _method. Fetch therefore sees POST, and a 302 is followed as GET in this stack. The often-repeated story in which a Turbo DELETE is replayed against the redirect target does not describe turbo-rails 2.0.23. status: :see_other remains the clearest and most portable convention, especially for clients that do send a real DELETE, but it is not repairing that particular failure mode here.

A turbo-stream response short-circuits renderer selection. render turbo_stream: …, status: :unprocessable_entity is therefore applied without trouble. The status remains observable: on a submission, turbo:submit-end.detail.success is false for a 422 and true for a 2xx. It also retains its meaning for tests and non-Turbo clients.

A small amusing detail: the test is on statusCode == 200 exactly. A 201 Created bypasses the guard and, when the response contains a non-empty HTML body, carries on to a visit. Without that body, Navigator proposes no visit.

4xx and 5xx: two rendering paths, not one

This is the point I had wrong, and it is repeated in plenty of articles: everyone writes that a 4xx is rendered by the normal page renderer and a 5xx goes through the error renderer. That is only true for form submissions.

What you did	2xx HTML	4xx HTML	5xx HTML
Submit a full-page form	`PageRenderer`, except for an unredirected 200 from a non-GET method, which is refused	`PageRenderer`	`ErrorRenderer`
Click a link, or `Turbo.visit()`	`PageRenderer`	`ErrorRenderer`	`ErrorRenderer`

The table assumes a usable HTML response. For a successful submission, Navigator only proposes the visit when responseHTML contains something, so an empty or non-HTML response never reaches PageRenderer. On a visit, a non-HTML response takes the error path.

Under the hood internal

On a visit, the test is binary: if (isSuccessful(statusCode) && responseHTML != null) renders normally, else goes to this.view.renderError(...) (visit.js#L203-L223), with isSuccessful defined as statusCode >= 200 && statusCode < 300 (visit.js#L417-L419). The 4xx/5xx distinction exists only in Navigator#formSubmissionFailedWithResponse (navigator.js#L92-L107).

That deserves more than a footnote, because ErrorRenderer is markedly more brutal than PageRenderer:

It does a replaceChild on the entire <head>, instead of merging it.
It walks every <script> in the document, including head scripts (error_renderer.js#L36-L38), then re-activates those without data-turbo-eval="false" (util.js#L1-L15).
It does not run Bardo, the machinery that transplants permanent elements. data-turbo-permanent is not honoured on an error page.

And symmetrically, since a form 4xx goes through PageRenderer, it is subject to shouldRender: a data-turbo-track="reload" mismatch on your error page will turn displaying validation errors into a full browser reload.

Trap

If your 500 page is a minimal template that does not load the same assets as the rest of the site, then every server error on a link click replays the <head> scripts without data-turbo-eval="false" and throws away your permanent elements. User reports then read like “the app goes weird after an error”, which is a horrible symptom to reproduce.

Morphing

Turbo 8 introduced page refreshes with morphing. The idea: rather than replacing the <body>, compare the old tree with the new one, and change only what differs. Scroll can be preserved; focus, text selection and transition state survive when the corresponding live node stays in place.

Enable it in the layout:

<%= turbo_refreshes_with method: :morph, scroll: :preserve %>

And here is the first trap, responsible for a good share of the “morphing does not work for me” reports: turbo_refreshes_with calls provide :head. It writes nothing where you call it. Without <%= yield :head %> in your layout, the meta tags never come out, and Turbo keeps doing classic replacements, without reporting anything. The accepted values are :replace or :morph for method:, :reset or :preserve for scroll:, anything else raises an ArgumentError.

What actually triggers a morph

A page morph only happens for a page refresh. When PageView receives a Visit, the exact test comes down to two clauses: same pathname (the query string and the fragment do not count) and action === "replace". With no Visit, isPageRefresh() returns true directly; a 4xx response to a full-page form submission takes that path and may morph when the effective method is morph.

Without an explicit action, an unsafe submission only takes replace when the response redirects to the exact URL of the page that contained the form. Turbo compares the final URL with history.location, not with the form action (navigator.js#L158-L166). From /invoices/42, a PATCH /invoices/42 that redirects to /invoices/42 morphs. From /invoices, a POST /invoices that redirects to /invoices/42 takes advance. A GET form also takes advance, unless its response redirects to the exact URL of the page it left.

data-turbo-action="replace" on the form or its submitter can force that action. A GET form moving from /search?q=old to /search?q=new can therefore morph; only the pathname has to stay the same. The same rule applies to a data-turbo-action="replace" link from /invoices?page=2 to /invoices?page=3.

Two common triggers are a form that redirects back to the page it left and a <turbo-stream action="refresh"> broadcast.

What morphing changes, line by line

The beginning and the end of the cycle are identical. It is the middle that changes, and the middle is exactly where your code lives.

What happens	Classic render	Morph
`turbo:before-cache`	when Turbo is about to cache the snapshot	same
Snapshot cached	according to the visit policy	same
The `<body>`	replaced wholesale	compared node by node by idiomorph
Stimulus `disconnect()` / `connect()`	on everything	on nodes added, removed or moved; even `moveBefore` produces the mutations that Stimulus interprets as a disconnect followed by a reconnect
Inline `<script>` already present	re-executed unless it has `data-turbo-eval="false"`	✕ never
Genuinely new `<script>` eligible for evaluation	executed	executed; `data-turbo-eval="false"` leaves it inert
`data-turbo-permanent`	transplanted by Bardo, `id` required	current node skipped when it already carries the attribute, no `id` required, Bardo never runs
Scroll after a page refresh	preserved with `scroll: :preserve`, otherwise reset	same
Focus and text selection	lost by default; restored inside a matching permanent element	kept when the live node survives; after replacement, restoration is limited to `<input>` and `<textarea>` elements with an `id`
`autofocus` during a page refresh	honoured	✕ `MorphingPageRenderer.shouldAutofocus` is `false`
`turbo:render` then `turbo:load`	fire	fire

The first two rows depend on the visit path, not the renderer. After a successful unsafe form submission, Turbo clears the cache and starts a visit with shouldCacheSnapshot: false: no snapshot, therefore no turbo:before-cache. Session#refresh also passes that flag, with an LRU exception detailed below.

turbo:load does fire after a morph. A refresh is a real visit. What does not replay is the inline <script> tags. The repository’s own test suite asserts it (page_refresh_tests.js#L33-L42).

turbo:before-cache is controlled by snapshot paths, not by the renderer. You read, and I wrote, that morphing simply removes the event. It is narrower than that. The distinction determines which cleanup code stops running.

Under the hood internal

Session#refresh hard-codes shouldCacheSnapshot: false (session.js#L108-L117). With no snapshot already cached for the current URL, a <turbo-stream action="refresh"> therefore does not emit turbo:before-cache. But BrowserAdapter#visitStarted() calls loadCachedSnapshot() first (browser_adapter.js#L21-L26). If the LRU already contains a previewable snapshot for that URL and the current document is cacheable, this path calls cacheSnapshot() without checking the flag and emits the event (visit.js#L245-L263, page_view.js#L43-L50). After a successful form submission, Navigator sets shouldCacheSnapshot from formSubmission.isSafe and clears the cache first for an unsafe method (navigator.js#L71-L87): a POST that redirects to the same URL can therefore morph without emitting the event. A cacheable regular replace visit or GET form caches the snapshot and emits it.

So: do not wire teardown required by the live DOM to turbo:before-cache on the assumption that it precedes every morph. Keep that event for cleaning the snapshot when one will be taken, and use morph events or the component lifecycle to protect the current document.

A new script that is eligible for evaluation can run under morph. idiomorph matches the old <script> with the new one by tag name, then syncs their text nodes with oldNode.nodeValue = newNode.nodeValue. Changing the text node of an already executed script does not execute it again.

A <script> produced by DOMParser or a <template> is inert and does not run merely because it is inserted. Turbo replaces it with an element created through document.createElement("script") before rendering (util.js#L1-L15). That activation also runs on the morph path, before idiomorph compares the trees (page_renderer.js#L174-L190). If the morph finds a script already present, the live node stays in place and does not replay. If the script is genuinely new and does not carry data-turbo-eval="false", the activated element enters the DOM and runs.

idiomorph decides by identifiers

This is the central mechanism of morphing, and everything else depends on it: what survives a morph, what replays, what breaks in Safari and nowhere else.

The content and visual order are identical in both columns; the new HTML is not. What changes is what survives the operation.

An id is considered stable only if all three of the following conditions hold: it exists in both trees, the tag name is identical, and it is duplicated in neither of them.

That third condition deserves a box around it. A single duplicated id in either morph root removes that id from the persistent set, in both copies. For a page morph, the roots are the two <body> elements; for a stream morph, the search is limited to the target and the incoming content. A duplicate in <head> or outside the target does not affect that morph. A duplicate inside the same root can still degrade, at a distance, the matching of another element carrying that id.

Without stable identifiers, everything is paired by position. Adding a row at the top of a list rewrites the text of every row rather than inserting a node. The DOM nodes remain in place, and a running CSS transition continues when the attributes or styles that triggered it do not change. The actual bug: client state can stay attached to the wrong record, or be overwritten when idiomorph synchronizes the property carrying it.

Remember

Give every list item a stable, unique id, never reuse it, and never change the associated tag. dom_id(record) follows those three rules; without them, morphing a list becomes unpredictable.

Node moves, and why Safari differs

Here is the mechanism that explains the “it works on my machine but not on his” bug reports, and that is documented nowhere.

When idiomorph reuses a node with a persistent id elsewhere, it moves the node without cloning it. Depending on morph order, the move happens directly from the current tree or temporarily through the pantry, a hidden <div> after <body>. In both cases, idiomorph uses moveBefore() when available and falls back to insertBefore().

The choice between the two changes observable behaviour:

With moveBefore (Chromium 133 and up, Firefox 144 and up), the node stays connected at the DOM level. <iframe> elements do not reload, transition state is preserved, and native connectedCallback hooks do not replay. Stimulus still observes the move mutations and runs disconnect() then connect().
With insertBefore, the node is actually disconnected then reconnected. <iframe> elements reload, CSS transitions and animations may be interrupted or restarted, native connectedCallback hooks replay, and Stimulus also runs disconnect() then connect(). <video> and <audio> playback normally survives removal and reinsertion too; it is not a difference between the two paths.

And here is the part I have seen misread more than once. moveBefore gets described as “widely available in 2026”. That is only true if you exclude Apple.

Under the hood Verified

Per @mdn/browser-compat-data (snapshot of August 6, 2026): Chromium 133+, Firefox 144+, Opera 118, Samsung Internet 29. Safari, Safari iOS and the iOS WebView are all three at version_added: false, with WebKit bug 281223 still open.

Chrome and Firefox currently distributed on iPhone also use WebKit, so they take this fallback too. Apple does allow alternative browser engines in the European Union, which makes it too broad to equate all iOS traffic with WebKit forever. Safari, WebViews and the WebKit browsers in your traffic remain affected, as do Macs running Safari.

So yes, a morphing bug can be perfectly reproducible on an iPhone and nowhere to be found on your machine. It is not necessarily your code. And if your product is mostly consumed on mobile, this is not an edge case either: it may affect a material share of your users, which your own traffic data should settle.

Field values are not protected

idiomorph does not only sync attributes, it also writes the live DOM properties of form controls. The code is explicit:

if (!newElement.hasAttribute("value")) {
  if (!ignoreAttribute("value", oldElement, "remove", ctx)) {
    oldElement.value = ""           // what the user had typed
    oldElement.removeAttribute("value")
  }
}

Server-rendered HTML may contain a value attribute, as Rails form builders often emit one, or omit it. idiomorph clears the live value in the second case and replaces it with the server value in the first. Either way, a refresh arriving mid-keystroke can discard unsaved input. The same treatment applies to checked, disabled, <option selected> and the content of <textarea> elements.

Trap

This bug is easy to miss in single-tab development, but it is not production-specific. A page refresh during typing is enough; a second tab, a broadcast or Turbo.visit(location.href, { action: "replace" }) reproduces it locally. If you turn morphing on in an application where people enter data, treat field protection as a prerequisite, not as an improvement.

idiomorph has an ignoreActiveValue option that excludes document.activeElement from this synchronization. Turbo’s built-in renderers do not enable it and provide no setting for doing so. Turbo does export morphElements and morphChildren, which pass the option through to idiomorph, so a custom renderer can use it.

Without a custom renderer, it is on you to protect the field. The most direct lever is data-turbo-permanent, which skips the morph on the element; turbo:before-morph-element and turbo:before-morph-attribute allow narrower protections. Since you do not want to freeze the field permanently, you set the attribute on focus and remove it on the way out. Turbo’s test fixtures demonstrate the pattern for an <input>; this version extends it to <textarea>, <select> and contenteditable fields as well:

addEventListener("focusin", ({ target }) => {
  const field = target instanceof HTMLInputElement ||
    target instanceof HTMLTextAreaElement ||
    target instanceof HTMLSelectElement
      ? target
      : target instanceof HTMLElement && target.isContentEditable
        ? target.closest("[contenteditable]")
        : null

  if (field && !field.hasAttribute("data-turbo-permanent")) {
    field.toggleAttribute("data-turbo-permanent", true)

    const unprotect = ({ relatedTarget }) => {
      if (relatedTarget instanceof Node && field.contains(relatedTarget)) return

      field.removeEventListener("focusout", unprotect)
      field.toggleAttribute("data-turbo-permanent", false)
    }

    field.addEventListener("focusout", unprotect)
  }
})

As long as the live node survives the morph, it naturally keeps focus. If that node is replaced, idiomorph explicitly restores focus and selection only for an <input> or a <textarea> with an id. It offers no equivalent guarantee for a <select>, a contenteditable element or a field without an id.

During a page morph, autofocus is not honoured: MorphingPageRenderer declares shouldAutofocus as false. A frame morph takes another path; MorphingFrameRenderer inherits from FrameRenderer, which does apply autofocus after rendering.

The protection toolbox

From the finest to the most brutal:

// 1. Protect one specific attribute
document.addEventListener("turbo:before-morph-attribute", (event) => {
  const { attributeName } = event.detail            // + mutationType: "update" | "remove"
  if (attributeName === "open") event.preventDefault()
})

// 2. Protect an entire subtree
document.addEventListener("turbo:before-morph-element", (event) => {
  if (event.target.matches(".widget-tiers")) event.preventDefault()
})

// 3. Reinitialize afterwards (turbo:morph-element)
document.addEventListener("turbo:morph-element", ({ target }) => { /* … */ })

<%# 4. The complete freeze %>
<div id="map" data-turbo-permanent>…</div>

The documentation says nothing about what follows.

data-turbo-permanent does not have the same semantics depending on the render mode. In classic rendering, the selector is [id][data-turbo-permanent]: the id is mandatory, and the live node is transplanted into the new body by Bardo. Under morph, it is different code with different rules.

Under the hood internal

Under morph, beforeNodeMorphed and beforeNodeAdded handle data-turbo-permanent with different criteria.

The “don’t touch me” guard (beforeNodeMorphed) tests the attribute on the current node: no id is needed, and the node is left alone when it already carries data-turbo-permanent. If only the incoming HTML adds the attribute, that first morph proceeds; later ones are frozen. The insertion guard does read the id, but with the opposite polarity: beforeNodeAdded = (node) => !(node.id && node.hasAttribute("data-turbo-permanent") && document.getElementById(node.id)) (morphing.js#L61-L63). An incoming permanent element carrying an id that already exists in the document is therefore refused: the existing one wins. Without an id, it is inserted normally.

One more thing, and it explains a lot of surprises: MorphingPageRenderer and MorphingFrameRenderer both reduce Bardo to async preservingPermanentElements(callback) { return await callback() }. Under morph, Drive’s transplantation machinery does not run at all.

Under morph, a current node carrying data-turbo-permanent freezes its subtree completely. Legitimate server updates inside it will never arrive. It is the tool of last resort, not the reflex.

Finally, turbo:before-morph-element is also dispatched for nodes about to be removed, and in that case detail.newElement is undefined. A listener that writes event.detail.newElement.matches(…) will throw a TypeError sooner or later.

Broadcasts

Broadcast macros take one line. Their mistakes often appear only in production.

Four macros, and one asymmetry

class Card < ApplicationRecord
  broadcasts_refreshes_to :board   # a single after_commit, everything goes to board
end

Macro	Create	Update	Destroy
`broadcasts_to :board`	`append` to `board`	`replace` to `board`	`remove` to `board`
`broadcasts`	`append` to `"cards"`	`replace` to the record’s GID stream	`remove` to the GID stream
`broadcasts_refreshes`	`refresh` to `"cards"`	`refresh` to the GID stream	`refresh` to the GID stream
`broadcasts_refreshes_to :board`	`refresh` to `board`	`refresh` to `board`	`refresh` to `board`

Read the second and third rows twice. broadcasts and broadcasts_refreshes send creates to the collection stream, but updates and destroys to the record’s own stream. A page that only does turbo_stream_from "cards" will see the new cards appear and will never see the updates or the deletions.

The code is intentional, but turbo_stream_from Card does not fix the asymmetry: the class produces the "Card" stream, not "cards". For an index to receive all three operations, use a _to macro and subscribe the page to that same stream. With the unsuffixed macros, it would have to subscribe to the collection stream for creates and to every record stream for updates and destroys.

Remember

If you want creation, update and deletion to all go to the same stream, use broadcasts_to for targeted DOM actions or broadcasts_refreshes_to for page refreshes. The unsuffixed broadcasts and broadcasts_refreshes send creates to the collection but updates and destroys to each record’s own stream. An index subscribed only to the collection therefore sees new rows appear, then nothing else move.

Another asymmetry worth knowing: for the first three macros, deletions are synchronous while creates and updates go through a job. That is logical (a deletion has nothing to render), but it means the deletion is not debounced. broadcasts_refreshes_to escapes this because it installs only one after_commit: everything there is asynchronous and debounced, including the destroy.

The full path of a refresh

The tab that writes receives its own broadcast, like every other tab. The whole request-identifier mechanism exists only to let it ignore the redundant refresh action.

Every Turbo fetch generates a UUID, adds it to a set capped at 20 entries, and sends it as X-Turbo-Request-Id. On the Rails side, an around_action copies it into Turbo.current_request_id. A refresh created from that context re-emits it in the request-id attribute by default. On reception, Session#refresh ignores the refresh if the identifier is in its local set.

The reason is a good one: the tab that wrote has already displayed the result of its request. Replaying the refresh would cost another network round trip and could lose scroll or focus, depending on the refresh configuration and which nodes the morph keeps.

This protection disappears, or acts at the wrong time, in the following cases:

Outside a request, Turbo.current_request_id is nil: it is a thread_mattr_accessor populated by an around_action. Every tab refreshes. That is generally what you want from a background job.
Without an X-Turbo-Request-Id header, for example from another HTTP client, the around_action has nothing to copy.
The set is capped at 20. Twenty new Turbo requests after the one that triggered the broadcast are enough to evict its identifier. With prefetch on hover on by default, that is no longer so theoretical.
Conversely, turbo_stream.refresh rendered as a direct response carries the request’s identifier by default, so the requesting tab ignores the action it has just received. Write turbo_stream.refresh(request_id: nil) if that response really should refresh the tab.

The synchronous broadcast_refresh_to variant is not an exception: it also goes through turbo_stream_refresh_tag, whose default is Turbo.current_request_id (action_helper.rb#L40-L46).

The debounce, and what it costs

broadcast_refresh_later_to goes through a Turbo::ThreadDebouncer memoized in Thread.current, keyed on (stream name, request_id), which schedules a Concurrent::ScheduledTask 0.5 seconds into the future. Each new call with the same key cancels the previous one. A thousand records modified in one request and broadcasting to the same stream therefore give one broadcast; a thousand distinct GID streams still give a thousand broadcasts.

On the client side, Session#refresh is debounced at 150 ms on top of that.

The downside:

Trap

A process that exits before the delay expires loses the broadcast. A rails runner, a rake task or a container can send it just fine if it stays alive for more than 0.5 s. If it exits before the ScheduledTask runs, there is no error and no log. For a one-shot process, the synchronous broadcast_refresh_to avoids this timing. Adding sleep Turbo::Debouncer::DEFAULT_DELAY + 0.1 is only a workaround, not a documented contract.

This bug slips through code review easily: the migration script runs, the data is correct, and nobody notices that the open tabs did not move.

In Rails tests that load ActiveSupport::TestCase, there is no debounce. The turbo-rails initializer then replaces the debouncer with Turbo::ImmediateDebouncer. For N calls with the same key, your assertions count N broadcasts where production will see one. A test harness that never loads ActiveSupport::TestCase does not get this replacement automatically.

`current_user` is not available in a broadcast render

Every broadcast that has to render its own HTML, whether synchronous or asynchronous, goes through:

ApplicationController.render(formats: [format], **rendering)

broadcast_refresh_later_to, along with calls that already receive html: or content:, has nothing to render and skips this renderer. The other paths use an ActionController::Renderer with a synthetic Rack environment. There is no session, no cookies, no Warden key. Mechanical consequences:

With standard Devise, current_user raises Devise::MissingWarden. The synthetic environment has no warden key, so the broadcast render fails; it does not quietly choose an anonymous branch. A home-grown helper may return nil, but current_user.admin? would then raise a NoMethodError anyway. Broadcast partials must not depend on request authentication helpers.
Current.* is not carried into an asynchronous worker. A job actually taken from the queue runs in another execution context, without the request state. perform_now and the :inline adapter can stay on the same thread and make the opposite appear true; synchronous broadcast variants also render on the current thread. Do not use either path as proof that a worker will see Current.*.
ApplicationController is hard-coded, but it does not lose all of its configuration. The renderer keeps configured view paths and, with Rails’ default include_all_helpers setting, the application helpers. What it does not run is a before_action, and it prepares no request ivars. A helper_method that depends on controller-instance state is therefore still unusable.
The result of _url helpers depends on default_url_options and the renderer’s default_env. With no host configured, this Rails 8.0.2 renderer produces a synthetic URL on example.org. Do not depend on that fallback: configure Rails.application.routes.default_url_options[:host] for broadcasts. _path helpers do not need a host (renderer.rb, v8.0.2).

The pattern that scales is the only one that accepts that the broadcast HTML is the same for every recipient: broadcast a neutral partial, and have the personalized parts loaded by a frame, which each browser will go and fetch with its own cookies.

<%# the broadcast partial, identical for everyone %>
<div id="<%= dom_id(card) %>">
  <%= card.title %>
  <%= turbo_frame_tag "#{dom_id(card)}_actions", src: card_actions_path(card), loading: :lazy %>
</div>

The alternatives: broadcast one stream per user, which is correct but O(users), or explicitly pass everything you need through locals: and treat “this partial is broadcastable” as a strict property of the partial.

It is also a practical reason to favour broadcasts_refreshes: a refresh renders nothing on the server. Each browser makes its own request, with its own session. The problem disappears by construction.

A signed stream is not an authorized stream

<%= turbo_stream_from "quotes" %>

This line produces a signed-stream-name that is identical for every user. The signature prevents forgery, not reading: the name is a MessageVerifier, so signed base64, not encrypted. Decoding the payload before -- reveals the JSON string "quotes" here. With a record, that string contains its to_gid_param, which can itself be decoded to gid://app/Account/5. Neither decode needs your key.

And Turbo::StreamsChannel#subscribed accepts the subscription with no additional check whatsoever. It verifies that the signature is valid, full stop.

Remember

Signing is not authorizing. A signed-stream-name proves the stream name came from your application; it proves nothing about the person subscribing to it, and it does not expire by default. Carrying the tenant inside the stream name prevents accidental cross-tenant broadcasts. It still does not authorize the subscriber: if access must be revocable, the channel has to check the current user when they subscribe.

So you have to carry the scope in the stream name:

broadcasts_refreshes_to ->(quote) { [quote.company, :quotes] }

<%= turbo_stream_from current_company, :quotes %>

That partitioning does not replace authorization. For revocable membership, write your own channel and perform the check before stream_from. Reusing an old signed name is only exploitable while that person’s Action Cable connection is still accepted; the channel check closes that door.

Plumbing traps

In development, the default Action Cable adapter is async, single-process. A broadcast triggered from bin/rails console will never reach a browser connected to a separately started server. Switch to redis in config/cable.yml, or use <%= console %> to trigger it inside the same process.

turbo-rails’ jobs inherit from ActiveJob::Base, not from your ApplicationJob. Retry policies, callbacks and queue_as declarations defined only on ApplicationJob therefore do not apply. All three classes declare discard_on ActiveJob::DeserializationError, but they do not carry the same arguments. With ActionBroadcastJob and BroadcastJob, a record present in the rendering options and deleted before execution makes the job discard without a retry; the instance helpers do add self to locals:. The stream and target have already been converted to strings before enqueue. BroadcastStreamJob, which handles refreshes, receives only the stream name and an already rendered <turbo-stream>, both as strings. Rails does not re-raise a deserialization error handled by discard_on, but it logs at error level and emits discard.active_job.

Stimulus and third-party libraries

The lifecycle, precisely

Stimulus knows nothing about Turbo. It reacts to a MutationObserver, in the microtask that follows each modification.

On a cacheable classic visit, turbo:before-cache starts the capture, but the clone is not immediate: PageView#cacheSnapshot waits until the next event-loop tick, and the visit does not await that Promise before continuing the render. The <body> swap and the MutationObserver microtask can therefore run disconnect() before the clone. Synchronous cleanup in disconnect() may clean the deferred copy too, but that ordering is not a contract. turbo:before-cache remains the public, deterministic hook for preparing the snapshot.

Under morph, elements merely modified in place get neither disconnect() nor connect(). Stimulus runs those callbacks for an addition, removal or move. A move can be direct or go through the pantry, including with moveBefore. Changing the value of data-controller triggers them too. turbo:before-cache is a separate question: it is absent after a successful unsafe form submission, and absent on Session#refresh unless the LRU already contains a previewable snapshot for the current URL and the current document is cacheable.

A Turbo 8.0.23 test fixture forces reconnection like this:

addEventListener("turbo:morph-element", ({ target }) => {
  for (const { element, context } of application.controllers) {
    if (element === target) {
      context.disconnect()
      context.connect()
    }
  }
})

This is not a reconnection API promised by Turbo: the fixture reaches directly into Stimulus’ context and is pinned to that version. On each turbo:morph-element, it scans the whole application.controllers collection, but reconnects only controllers whose element is exactly target. On a large page, the cost comes from the repeated scan, not from reconnecting everything.

What breaks, and why

Remember

Any library that injects DOM absent from the server HTML, or writes class or style at runtime, can conflict with morphing. Whether it breaks depends on what the server returns and whether the library can reconcile or rebuild its state. It is not automatically incompatible, but that surface needs explicit protection or lifecycle handling.

Library	What breaks	The cause	The fix
Chartkick	The chart disappears, a “Loading…” stays behind	Chartkick listens for `turbo:before-render` and destroys every chart, including when `renderMethod` is `morph`. Raw Chart.js does not do this on its own. The `<script>` that would recreate the chart does not re-execute	`Chartkick.config.autoDestroy = false`, then redraw on `turbo:morph`
Alpine.js	Elements become invisible again, the `:class` bindings drop	Alpine removes `x-cloak` on init and writes `class` and `style.display` at runtime. The server HTML knows nothing about them, the morph puts them back	Cancel `turbo:before-morph-attribute` for `x-cloak`, `class` and `style` on `[x-data]` subtrees
Tom Select, Select2, Choices	The widget disappears, the selection reverts	The injected `<div>` is not in the server HTML, so it is removed. The original `<select>` survives, so there is no reconnection	Server-render a stable wrapper containing both the control and the injected DOM, then put an `id` and `data-turbo-permanent` on that parent. Otherwise tear down before its morph and reinitialize afterwards
Leaflet, Mapbox GL	Dead map, grey tiles, or `Map container is already initialized`	The library’s injected internal DOM is removed while the container survives, so `disconnect()` does not run	Destroy before the container morphs, reinitialize on `turbo:morph-element`, then call `invalidateSize()` with Leaflet or `resize()` with Mapbox GL
`<dialog>` opened with `showModal()`	The page becomes unusable	The morph rewrites the content but does not reset the browser’s top layer	Open, unresolved ticket. Close the dialog on `turbo:before-render`, or exclude it from the morph
`<details>`	Panels open or close on their own for every viewer	`open` is synced like an ordinary attribute	Cancel `turbo:before-morph-attribute` for `attributeName === "open"`
`<turbo-cable-stream-source>`	Broadcasts are lost, or the UI thinks the cable is offline	Reparenting through the `insertBefore` fallback unsubscribes it; an in-place morph can remove the runtime `connected` attribute without reconnecting it	Stable `id`, outside reordered areas, plus protection for `connected` or `data-turbo-permanent`

Trix and Action Text have been fixed since March 2025, contrary to what many blog posts still claim. The technique used provides a useful pattern for a custom element under morph: <trix-editor> sets a connected attribute on initialization and declares it in observedAttributes. The server HTML does not contain it, so the morph removes it, attributeChangedCallback fires, and the element reinitializes itself.

It is a self-healing custom element. If you write your own, do that.

What leaks if you do not clean up

With Turbo, the same document and JavaScript context can remain active for a long time. Every resource owned by a controller instance needs its teardown in disconnect(): setInterval timers, addEventListener calls on window or document, IntersectionObserver and ResizeObserver instances (which keep the observed node alive and block collection of the entire detached subtree), Action Cable subscriptions, and Chart.js instances. A genuinely shared or singleton resource follows a different lifecycle, often with reference counting; every disconnect() must not destroy it.

WebGL contexts deserve a mention. Their quota depends on the browser, GPU and implementation. Keep leaking Mapbox maps and the browser may lose one or more contexts or refuse to create a new one; affected canvases can turn blank or remain unusable until they are reinitialized.

Injecting a stream without an HTTP response

Turbo.renderStreamMessage() accepts an HTML string containing <turbo-stream> elements and applies them as if they had arrived over the network. The <script> tags inside the <template> are activated, permanent elements are preserved, focus is restored by id.

This is what you need for: a transport other than Action Cable (raw WebSocket, SSE, postMessage from a service worker), an optimistic update synthesized on the client before the server confirms, or a native shell pushing HTML into the webview.

Turbo.renderStreamMessage(
  `<turbo-stream action="append" target="messages"><template>…</template></turbo-stream>`
)

Network and offline

When the request fails, nothing happens

Turbo dispatches turbo:fetch-request-error, which bubbles and crosses shadow roots, with detail.request and detail.error. A listener placed on document catches it reliably.

What happens next depends on the context, and the difference is brutal.

For a frame or a form submission, the user sees nothing. No banner, no toast. A console.error, and the frame stays on its old content.

For a Drive visit, Turbo leaves the page. The network failure is recorded as SystemStatusCode.networkFailure, the adapter dispatches turbo:reload with reason: "request_failed", then performs a plain navigation. Offline, that means the browser’s network error page, with the application’s entire JavaScript context gone. You lose client state just as the network has already failed.

Under the hood internal

The name reload is misleading, and it took me a while to understand what was actually happening:
reload(reason) {
  dispatch("turbo:reload", { detail: reason })
  window.location.href = (this.redirectedToLocation || this.location)?.toString() || window.location.href
}
(browser_adapter.js#L130-L134) This is not a location.reload(). It is a full-page navigation to the visit’s destination, the one that just failed. So on an offline link click you do not land on the page you were on: you land on the network error page at the link’s address, and the previous page’s state is gone.

Two details that come with it. turbo:reload is dispatched without cancelable: listening for it lets you prevent nothing. And its detail is the whole reason object, so event.detail.reason is "request_failed" and event.detail.context.statusCode carries the internal code.

Hence the only interception point that works: turbo:fetch-request-error, earlier in the chain. The preventDefault() there is not cosmetic, since it makes #willDelegateErrorHandling return false, which short-circuits requestErrored, therefore recordResponse, so the adapter is never asked to do anything and the navigation does not happen. In exchange, FetchRequest#perform still rethrows the error: expect an unhandled promise rejection in the console.

document.addEventListener("turbo:fetch-request-error", (event) => {
  event.preventDefault()   // also prevents the full reload on a Drive visit
  showOfflineBanner(event.detail.error)
})
window.addEventListener("offline", () => showOfflineBanner())
window.addEventListener("online",  () => hideOfflineBanner())

Watch out for an ordering trap: turbo:before-fetch-response fires only if there is a response. Network-loss detection built on it will never fire when the network is actually down.

Turbo and service workers

Turbo navigations are window.fetch() calls. Turbo passes no mode option, so on the service worker side the request has mode === "cors" and, more surprisingly, destination === "", the default value for anything coming out of fetch().

A service worker that routes on request.mode === 'navigate' therefore misses every Drive navigation. And the fix you read everywhere, adding || request.destination === 'document', catches nothing at all: that destination only exists for navigations initiated by the browser itself. You have to discriminate on what Turbo actually sends:

const isDocumentNavigation = ({ request }) => {
  const accept = request.headers.get('Accept') || ''

  return request.method === 'GET' && (
    request.mode === 'navigate' ||                                  // browser navigation
    (request.destination === '' &&                                  // Turbo Drive's fetch()
     !request.headers.has('Turbo-Frame') &&                          // not a frame request
     !accept.includes('text/vnd.turbo-stream.html') &&               // not a stream request
     accept.includes('text/html'))
  )
}

registerRoute(isDocumentNavigation, new NetworkFirst())
registerRoute(
  ({ request }) => ['style', 'script', 'image', 'font'].includes(request.destination),
  new CacheFirst()
)

Both exclusions are essential: Frames and Streams also use fetch(), carry destination === "" and accept HTML. Without them, a partial response can pollute the cache for the same URL that Drive later visits. The second route works as is: those requests really are initiated by the browser and carry a populated destination.

This matcher also assumes that your other application fetch() calls do not request HTML over GET without a distinguishing header. If they do, the HTTP metadata above cannot identify Drive on its own: mark Drive requests with an application header from turbo:before-fetch-request and make the predicate require it.

Two service worker failures come up often with Turbo: a wrong Content-Type and inconsistent asset fingerprints. They are not the only possible failures.

Serving a response with the wrong Content-Type. On a Drive visit, Turbo records contentTypeMismatch, dispatches turbo:reload, then performs a full navigation to the destination. In a frame, a non-HTML response leaves the frame unchanged after the fetch events. Only that second case is silent in the interface.

Serving HTML whose asset fingerprints no longer match. Turbo compares the data-turbo-track="reload" elements between snapshots. On divergence, it triggers a full browser reload. A loop only appears if subsequent responses keep alternating between incompatible HTML and assets; one stale cache entry does not guarantee a loop on its own.

Rails 8 adds constraints of its own:

Put the service worker at a stable root URL. By default, its scope cannot reach above the directory of its URL. The Service-Worker-Allowed HTTP header can widen that scope, but it does not fix the unstable URL of a Propshaft-digested asset. Two simple options are public/service-worker.js, or the route Rails 8 generates, which is commented out by default in config/routes.rb and therefore has to be uncommented: get "service-worker" => "rails/pwa#service_worker", as: :pwa_service_worker. Note the rails/pwa controller and the path without .js.
Importmaps do not apply inside a service worker. There is no <script type="importmap"> in there. Use importScripts() in a classic worker, or register a module worker with { type: "module" } and static imports resolved as real module URLs, without an importmap.
Digested asset URLs change with their content. A precache list written by hand goes stale on the first deploy that touches a file. Prefer runtime caching, by request.destination.

An official patch is in progress (turbo#1427, a Turbo.offline API shipped in a separate bundle) but it is open, not merged. Do not write an architecture that depends on it.

Action Cable replays nothing

This production risk receives little attention in Hotwire documentation.

Action Cable is publish/subscribe with no persistence, no acknowledgement, no sequence number and no history. A message published while a consumer is disconnected is delivered to those who are subscribed at that instant, then thrown away. There is nothing in the protocol capable of replaying it.

Action Cable reconnects on its own, and the tab receives the subsequent messages again. Everything that went through during the outage is permanently lost. The page stays stale until a navigation, an explicit catch-up refresh, or a later payload resynchronizes it. There is no automatic replay or error indication.

Wifi switching over, a computer waking up, a tunnel, a deploy: this is not an edge case, it is the daily life of a mobile user.

The public DOM observation surface fits in one attribute: <turbo-cable-stream-source> sets and removes connected. You can instrument subscription callbacks or the Action Cable consumer, but that couples the application to their internals.

Under the hood Verified

The element does dispatch an event, just not the one you would want: a MessageEvent("message") per received payload, which is how StreamObserver consumes it (cable_stream_source_element.js#L30-L33). What it does not dispatch is any lifecycle event at all: subscriptionConnected and subscriptionDisconnected only set and remove the attribute.

To stay on the custom element’s public interface, observe that attribute with a MutationObserver or, for a simple banner, CSS: turbo-cable-stream-source:not([connected]) ~ .offline-banner { display: block }.

There is one morphing trap to remove before observing it. connected is runtime state and is absent from the server HTML, so idiomorph will otherwise remove the attribute while the subscription is still alive. The custom element does not observe connected, so it will not put it back until a real reconnect. Preserve that one attribute during morphs:

document.addEventListener("turbo:before-morph-attribute", (event) => {
  if (event.detail.attributeName === "connected" &&
      event.target.matches("turbo-cable-stream-source")) {
    event.preventDefault()
  }
})

Hence the workaround, which is entirely application code:

// Stimulus controller placed on <turbo-cable-stream-source>
connect() {
  this.observer = new MutationObserver(() => {
    const isConnected = this.element.hasAttribute("connected")
    if (isConnected && this.wasDisconnected) {
      Turbo.visit(location.href, { action: "replace" })
    }
    this.wasDisconnected = !isConnected
  })
  this.observer.observe(this.element, { attributeFilter: ["connected"] })
}

disconnect() { this.observer.disconnect() }

Handle visibilitychange (the machine waking up) and window.online too.

With turbo_refreshes_with method: :morph, scroll: :preserve, this catch-up costs one round trip and preserves the scroll. Focus survives when its node stays in place; idiomorph can also restore it on an identified <input> or <textarea>. This is what makes pairing morphing with broadcasts practical: the catch-up becomes cheap enough that you actually write it.

One last thing to know in the same vein: Session#refresh also drops a refresh that arrives while a navigation is already in flight (!this.navigator.currentVisit), with no retry. It is a second, narrower path to the same staleness.

Debugging checklist

This checklist has resolved nearly every Turbo bug I have encountered. It is deliberately mechanical: each step eliminates a class of causes, and the first three take ten seconds.

1. The console, before the network tab. A console.error changes the diagnosis entirely. Form responses must redirect → HTTP status. unknown action or target or targets attribute is missing → the <turbo-stream> is malformed. Content missing → frame identifier. An empty console and nothing on screen: look first for a silent no-op, a missing target, or a cancelled event. It narrows the diagnosis, but does not prove that the response was empty.

2. Did the request leave, and with which headers. In the network tab, inspect Accept, Turbo-Frame and X-Turbo-Request-Id. Without text/vnd.turbo-stream.html in Accept, the usual content negotiation will not select that format, but a .turbo_stream extension or an explicit params[:format] still can. Inspect the URL and params too. If the request never left at all, look for a data-turbo="false" on an ancestor.

3. The status, and only at this point. A 200 with no redirect on a POST is the classic. A turbo-stream Content-Type selects the stream renderer before page/frame rendering, but the status still feeds turbo:submit-end.detail.success. For frame navigation started by a link or src, both 2xx and 4xx/5xx HTML go through loadResponse(). For an ordinary HTML frame-form response, status instead selects the success/failure path, the frame that receives the response, and whether the Drive cache is cleared.

4. Does the target actually exist, right now. In the console, document.getElementById("your_id"). Also check it is not inside a <template>, inside an <iframe>, or inside a loading="lazy" frame that has not loaded: three places Turbo will not look.

5. How many of them are there? document.querySelectorAll("#your_id").length. The answer must be 1. A 2 explains both streams hitting the wrong element and morphs behaving strangely at a distance.

6. Which renderer ran. document.addEventListener("turbo:before-render", e => console.log(e.detail.renderMethod)). MorphingPageRenderer needs an effective morph method and a page refresh in PageView’s sense. When there is a Visit, that means action: "replace" and the same pathname as the last rendered page; with no Visit, isPageRefresh() returns true directly. A successful full-page submission creates a Visit, while a failed response takes the direct rendering path. A missing <%= yield :head %> drops the morph meta tag, but it is only one possible cause.

7. Is it coming from a broadcast. Check whether the HTML received is meant to be identical for everyone. With standard Devise, a broadcast partial that calls current_user fails with Devise::MissingWarden; with a home-grown helper it may return nil, but the partial still cannot safely personalize one shared payload.

8. Run the same test in Safari, or on an iPhone. A difference limited to those browsers is a reason to check Element.prototype.moveBefore and idiomorph’s insertBefore fallback. It is not proof: application code, CSS and other API differences remain suspects. Reduce the case before clearing the application.

9. Cut the network, and watch what happens. It is the only way to discover that an offline link click leaves your application, and that nobody is listening to turbo:fetch-request-error.

The symptom index

Symptom	Most likely cause
The form goes out, nothing moves, console: “Form responses must redirect”	`200` with HTML on a POST. Answer `422` on failure, `303` on success
The form updates an unexpected region	It inherits the frame that contains it, that frame’s `target`, or a `data-turbo-frame` on the form or submit button
The frame empties out, “Content missing”	The response has no `<turbo-frame>` with the same id. Often a redirect to `/login`. Mark the target page with `turbo_page_requires_reload`
The stream arrives, visible in the network tab, no effect	The target does not exist in the DOM. It is a completely silent no-op
The stream does not arrive on a GET link	Add `data-turbo-stream`: without it the `Accept` header is not sent
`first child element must be a <template> element`	A `<turbo-stream>` built by hand without its `<template>`
The `Content-Type` is wrong	A frame stays unchanged after the fetch events; a Drive visit dispatches `turbo:reload` and then navigates fully to the destination
The JS stops working after a navigation	Initialization on `DOMContentLoaded`, which only fires on the first load. Move to `turbo:load` or to Stimulus
The JS stops only since morphing was turned on	Inline `<script>` tags do not re-execute. `turbo:before-cache` is also path-dependent: absent after a successful unsafe form, and absent on `Session#refresh` unless a previewable snapshot of the current URL is already cached and the current document is cacheable
Morphing “does not work”, the page gets replaced	On a page refresh, the effective method is not `morph`. Check the meta tag emitted by `turbo_refreshes_with`, hence `<%= yield :head %>`, or the `method` attribute on the `refresh` stream
Morphing does not trigger after a form	For a successful full-page response turned into a Visit, the effective method must be `morph`, the action `replace`, and the `pathname` unchanged. Without an explicit action, Turbo chooses `replace` only for a redirect to the full departure URL; otherwise it chooses `advance`. A full-page 4xx goes straight through `renderPage`, a 5xx through `ErrorRenderer`, and a frame submission through its frame renderer: those branches do not apply this Visit test
Full browser reload on every navigation	`data-turbo-track="reload"` signature mismatch. Normal after a deploy. A loop requires successive responses to remain inconsistent; look for a dynamically injected asset or a service worker cache mixing versions
Lists animate all over the place under morph	No stable `id` on the items, or an `id` duplicated in either root of this morph, or the tag changed
Works on your machine, breaks on an iPhone, under morph	Check for `Element.prototype.moveBefore`. The `insertBefore` fallback can disconnect and reconnect moved nodes; WebKit browsers often share that path, but this symptom alone proves neither the cause nor the innocence of application code
The text the user is typing gets erased	`syncInputValue` writes the live properties, and Turbo does not enable `ignoreActiveValue`
The back button shows stale content	With a usable restoration snapshot, that snapshot is the only render and Turbo performs no fetch. Without one, it goes back to the network. Use `turbo-cache-control: no-cache` if the content is sensitive
The back button shows a duplicated widget	The snapshot kept the DOM injected by the widget. Remove it in `turbo:before-cache`, the deterministic hook intended for that job. A synchronous `disconnect()` may also precede the deferred clone, but should not be your only cache contract
Flash messages do not appear under morph	A refresh broadcast carries no flash. And if the flash has the same `id` and the same text, the morph changes nothing at all
A broadcast updates the wrong user’s page	Stream name not partitioned, or a channel with no authorization check. Signing is not authorizing
A broadcast refreshes its author’s tab too	Missing or nil `request_id`, a broadcast outside the request, or an identifier evicted after twenty new Turbo requests
Real-time updates stop, with no error	The WebSocket dropped. Action Cable replays nothing. Catch up on the `connected` attribute after protecting it from morphs
Nothing happens when the network is down, in a frame or a form	`turbo:fetch-request-error` is dispatched but nobody is listening
The browser error page appears when the network is down, on a link click	A Drive visit failing on the network navigates to the destination, outside Turbo. `preventDefault()` on `turbo:fetch-request-error` is the only way to stop it: `turbo:reload` is not cancelable
After a form returns 404, the frame shows the error but `reload()` returns to the old content	A failed form response does not replace an existing `src`. Navigation started by a link or by `src` sets that URL before the request, so `reload()` then repeats the failing URL instead
After a 500 on a link click, the application goes unstable	`ErrorRenderer` replaces the whole `<head>`, re-activates scripts unless they have `data-turbo-eval="false"`, and does not run Bardo: `data-turbo-permanent` is not honoured
Back navigation got slow since a search form was added	A failed GET with an HTML response clears the full-page cache; inside a frame, every failed form submission clears it
Some changes are not broadcast from a `rails runner`	The process exited before the debounce task scheduled 0.5 s out. If it stays alive beyond the delay, the broadcast is sent

What changed recently

If you are rereading documentation or blog posts written before 2026, be wary of these points, all changed in version 8.0.21 of January 2026:

data-turbo-cache="false" was removed. It is data-turbo-temporary.
Turbo.clearCache() was removed. It is Turbo.cache.clear().
data-turbo-frame="_parent" was added.
The method and scroll attributes on the refresh stream action were added: they override the meta tags, broadcast by broadcast.
before and after now deduplicate siblings, as append and prepend already did for children.

And a few things present in the code but absent from the official reference, all of which belong under the Verified label: the turbo:before-frame-morph event, the Turbo.config.forms.mode, Turbo.config.forms.submitter, Turbo.config.drive.enabled and Turbo.config.drive.unvisitableExtensions options, reassigning event.detail.url on turbo:before-fetch-request, and the fact that turbo:frame-render is declared cancelable even though cancelling it produces no effect.

The internal details here are linked to source or tests from the pinned versions; revisit those links whenever you upgrade Turbo.

The useful rule is still the one at the top: choose the replacement scope first, then decide who names its target. Use Drive while the whole page is the right boundary, a Frame when the client names one region backed by a URL, and Streams when the server must name one or more targets. Morphing only changes how that choice is applied.

If your Hotwire application has accumulated these symptoms, this is the work I do at SXN Labs. I start from a reproducible case, fix the broken contract and verify the result in production.

Six parallel workstreams, one integration bill

2026-08-05T09:00:00+02:00

Six feature workstreams passed their tests and reviews, then produced ten serious defects when they came together. They had been designed as independent even though they changed the same quotes, job sites, and contacts, enforced the same business rules, and rewrote some of the same files.

The application schedules field visits, sends quotes for signature, and notifies clients by text message. Parallel work shortened each workstream’s development time while the effort required to produce a coherent product remained.

The tickets separated the work, but not the systems being changed.

Two correct workstreams, one inconsistent flow

One workstream added online quote acceptance: the system checked the quote, confirmed the order, and generated the invoice. Another let the back office change the job site or delete the associated request. Each behavior made sense in isolation and had test coverage.

Together, they opened a gap between validation and confirmation because the back office could change the job site while the client was signing. The client then approved the current quote while the signature provider still held a contract describing the previous version.

No isolated test covered that sequence. The defect lived in the seam, around shared state that could change before the irreversible action.

The tickets hid a shared system

A duplicated business rule. Three paths needed to preserve a quote’s recipient, using three definitions: a full contact fingerprint, only its ID, or no check.
State read too early. Two requests could load the same draft and generate separate PDFs, with no reliable way to determine which one represented the accepted offer.
A shared artifact. Two branches rewrote the database schema. The merge removed a table required for appointments even though each branch was correct in isolation.

Faster implementation moves the bottleneck

When every workstream can interact with every other one, the maximum number of pairs to examine follows n × (n - 1) / 2:

Parallel workstreams	Calculation	Possible pairs
6	`6 × 5 / 2`	15
10	`10 × 9 / 2`	45

These 15 or 45 pairs do not imply as many conflicts. They are an upper bound; actual integration cost depends on the density of the dependency graph and the cost of each seam.

AI lets one developer start several workstreams cheaply. Generation, local tests, and review parallelize well. Reconciling two interpretations of a business rule remains sequential work that requires an understanding of the whole product.

Before starting parallel work

The read/write overlap requires coordination, not necessarily a stack. The second PR branches from the first only when it depends on its code or schema.

Map reads and writes. List the objects each workstream reads or changes, along with shared invariants and artifacts.
Classify dependencies. If one workstream writes data that another reads or writes, or if they share an invariant or artifact, plan their integration together.
Stack code dependencies. If a PR uses code or schema from the previous PR, base it on the previous PR’s branch so its diff remains focused. Merge the stack from the bottom upward and restack its descendants after each change. A business dependency alone needs coordinated integration and an end-to-end test, not necessarily a stack.
Close race conditions. Bind the signature to an immutable version of the quote and job site, then compare that version in the same transaction that confirms the order. If it differs, invalidate the signature and regenerate the contract.
Test after every merge. Regenerate shared artifacts, then rerun the affected business flows. A green suite on each PR does not cover their seams.
Schedule integration. Name the integrator, set the cadence, and reserve the required time. The delivery date must include this work.

Contrast cannot be checked in the mockup alone

2026-07-30T09:00:00+02:00

A brand’s design can look perfect on paper and still produce screens that some of your users simply cannot read. It happened to me recently, on an interface I develop: hundreds of texts too pale against their background, including the main button label and the tab bar, across some thirty screens. No design review had caught it.

This article covers only one part of accessibility: the contrast of text and indicators. It is visible, measurable, and still surprisingly easy to miss.

On the left, the screen the review signs off. On the right, the same screen outside, the one the user actually gets.

What the mockup does not show

A review looks at intent, on a nice screen, in good conditions. Real life also means the same screen in bright sunlight, on a cheap phone, or read by someone who is sixty. Light grey text on a coloured background can look “sleek” in the design file and become invisible outside.

In this interface, much of the text sits on a gradient, a translucent layer or a blend of tints. The colour to judge is the one obtained once those layers are composed, in every theme and every state, not only the value written in the file. The mockup can and should eliminate some mistakes. On its own, it cannot prove that the final implementation remains readable everywhere.

The colour written in the file is a flat fill. What gets painted is a gradient, and the white text drops to 1.5:1 on it, where AA asks for 4.5.

What a green score does not prove

The next reflex is to run Lighthouse, get a nice green score and tick the box. But a green score does not prove that every piece of text is readable. It means the automated checks found no problem. Gradients, background images and some overlapping layers remain difficult to analyse: they need a dedicated check.

The most instructive trap came from our own check. To judge a gradient, it computed the average colour. A plate going from dark to light therefore produced a reassuring average, a colour painted nowhere on screen. The test went green on a fiction.

The same gradient judged two ways. On the average, the check goes green. On the worst spot, it fails.

A check that shows green on a colour that does not exist sells peace of mind while guaranteeing nothing. We fixed it to judge the worst spot of the gradient, not its average.

Why it was a product problem

The worst cases landed on the button everyone taps, the navigation bar, and the little frame that shows where you are when navigating by keyboard. The elements everyone touches, barely visible to a chunk of people.

Text that is too pale is not “a bit less pretty”. It is a user who cannot find the button, who gives up, who calls support. On a consumer product, readability is a conversion number before it is a compliance checkbox.

What we fixed, and what remains

We combined the three levels that were missing: design review, automated checks and inspection of the interface actually rendered in a browser. None is enough on its own. Together, they uncover obvious mistakes, implementation mistakes and the cases automation cannot decide.

The point that matters to a decision-maker is that no brand colour moved. What changed is the ink on top. Each type of background now has its own text colour, chosen once in the design system instead of eyeballed screen by screen. We went from hundreds of insufficient cases to a handful.

That handful consists of white text on the brand gradient, where no single text colour meets the threshold across the whole surface. Knowing about them does not make them compliant. These residual issues still need fixing by changing the composition, for example with a local background or different placement, without necessarily touching the palette.

A guardrail, not an audit

The guardrail is a small test that runs in seconds on every change. It does not replace an accessibility audit, and does not even cover all of accessibility. It does one narrower, useful job. It stops a new colour, a rebuilt component or an added screen from slipping back below the bar without anyone noticing.

The useful question is not “what is our score?”

Accessibility is not a favour done for a minority. It makes the product usable by people who age, who read in the sun or who simply have average eyesight: everyone, sooner or later.

Since June 2025, the European Accessibility Act has also applied accessibility requirements to defined categories of products and services, including e-commerce, banking, transport and electronic communications. But compliance is not the best reason to care, and this contrast test is obviously not enough to establish it.

For a decision-maker, the useful questions are simpler: how many of our users can actually read our screens? What stops us from becoming unreadable again next month? If the answer is “the team’s vigilance”, there is no answer.

In this case, the first diagnostic and the guardrail took half a day. If you have a consumer product and nobody has ever checked the contrast of the interface actually shipped, we can look at it together.

When AI becomes your single point of failure

2026-07-27T09:00:00+02:00

A few days ago, my monitoring dashboard sat frozen for three days. It aggregates the application errors from my projects every hour. For three days, the tile displayed perfectly plausible numbers. They were three days old.

The monitoring service itself had never stopped answering. The data was there, available, one API call away. What had failed was the piece I had slipped into the middle of the pipe: an AI session.

A silent failure, the worst kind

The unpleasant part of the story is that the outage did not look like one.

An agent that crashes shows an error, raises an alert, gets noticed. Here, the hourly agent failed cleanly, wrote nothing, and the page kept serving the last known state with its usual formatting. Nothing blinked. I found out while looking for something else.

The cause was mundane. The authentication on the command line tool carrying the session had expired. No quota exceeded, no model unavailable, no bad answer. Just a stale token on a component I had never counted as part of my data collection chain.

Why the AI was there in the first place

Convenience, and that is the interesting part.

Access to the monitoring service already existed as a tool wired into my assistant. Writing a prompt along the lines of “fetch the unresolved errors, classify them, write the summary” takes ten minutes and works on the first try. Writing the equivalent API client, handling pagination, fields and edge cases, takes half a day and produces no impressive demo.

So the decision was rational the moment I made it. It was much less so a month later, when that shortcut had become a production link carrying the only view I had of my applications’ health.

It is a pattern I see a lot right now in companies “adding AI” to their processes. The prototype is spectacular, shipping it is painless, and nobody circles back to ask what happens the day the newest and least deterministic component in the chain stops answering.

The fix, two hundred boring lines

The replacement is about two hundred lines of Python. It reads the monitoring service’s REST API with a dedicated token, filters out the projects that are none of my business, applies a keyword based classification and writes the result. No AI anywhere on the path.

The model did not disappear, it moved. Fine grained triage, phrasing a diagnosis, deciding whether to create a task: that stays as a layer on top, one that can fail without consequences. If it does not run, I lose commentary. Before, I lost the data.

The difference fits in one sentence: the truth shown on my dashboard no longer depends on an assistant’s authentication state.

This was not the first warning

A few weeks earlier, the agent that watches the other agents started sending me outage alerts for services that were perfectly healthy. The reason is that it computed the current timestamp itself, and the model got the day wrong in certain time windows. Eight false alerts before I figured it out.

The fix was to forbid it from producing a date at all. A date is something you ask the operating system for, not something you infer.

Here again, “AI is unreliable” misses the point. A language model is non deterministic by construction, and that is exactly what you want from it when you need rephrasing, summarising or judgement calls. The problem only shows up when you also hand it tasks where non determinism is a defect: counting, dating, adding up, fetching a value that already exists somewhere.

The rule I apply now

My personal system currently runs forty eight active agents. Twenty nine of them contain no AI at all. They are scripts. They read an API, compute, write a file, send a notification. They run on time, they cost nothing, and their failure mode is legible.

The other nineteen use a model because they do something a script cannot: read a client conversation and extract an intent, draft a text, rank heterogeneous signals, propose three options and recommend one.

That is where I draw the line. AI above the system, for judgement. Never inside it, on the path where data is acquired or computed.

The question to ask before putting it everywhere

For an executive evaluating an automation with AI inside, the useful question goes further than “does the demo work”. It comes in two parts.

If the model is unavailable for three days, what exactly stops? And does anyone notice, or does the screen keep showing numbers that look normal?

If the second part is fuzzy, the problem sits with the dependency rather than the AI. It was added without being held to the standards every other dependency is held to: failure detection, an explicit degraded mode, and a clear assumption about what happens when it is not there.

An automation that cannot tell you it is down is not an automation, it is a display.

If you have a process where AI settled in without that line ever being drawn, we can look together at what deserves to stay and what would be better off as a script again.

E-invoicing 2026: the real work isn't the format

2026-07-23T09:00:00+02:00

The French e-invoicing reform is coming, and the question everyone asks is the wrong one. Not “which format?”, not “which platform?”, but whether your software already produces a clean electronic invoice, edge cases included.

A 30-second recap. Every VAT-registered business in France is concerned, down to the smallest ones. Receiving becomes mandatory in September 2026, and issuing follows in September 2027 for small and mid-sized companies, as early as 2026 for large and intermediate-sized ones. A non-compliant invoice is a flow rejected at the door, which means late payment, a penalty, and direct pressure on cash.

Generating a Factur-X file is a few lines of code. The real work sits elsewhere: credit notes that have to reference the right invoice, SIREN, SIRET, VAT and IBAN validators, reconciliation with the business side, plugging into a certified platform or Chorus Pro. That is where most existing chains stall, because paper used to let through everything that structured XML refuses.

This is why I wrote einvoicing and einvoicing-connect, two open source gems published on RubyGems and already running in production. EN 16931 compliant Factur-X PDF/A-3 generation, validators included, a Chorus Pro and PPF client ready to wire up, with no third-party SaaS and no external dependency. Fitting them into an existing Rails system takes a few days.

To find out where you stand, I put together a dedicated page with a 30-minute assessment. I look at your stack, your volumes and your target platform, and you leave with a concrete integration plan and a firm quote.

See the 2026 e-invoicing page

And to check whether a PDF is already compliant, a Factur-X validator is freely available, fully local analysis, nothing uploaded.

My Postgres high availability wasn't, autopsy of an outage

2026-07-22T18:00:00+02:00

Yesterday evening, every one of my internal services and the software I host for my clients became unreachable for several hours. A saturated Postgres database, a high-availability setup that did not play its part, and a Scaleway incident on top. Here is the autopsy, no filter, because an outage you tell honestly is worth more than one you paper over.

The trigger, or rather the triggers

At 10:15 PM (Paris time), Scaleway lost a node in its block storage cluster in fr-par-1 (incident bsp2y5fysy9w). On the infrastructure side the effect was immediate: virtual machines stuck, and above all managed databases frozen on storage that had become unreachable.

At the very same moment, on my end, I had kicked off a batch of contact-enrichment jobs on Argos, my CRM. That kind of batch opens a lot of Postgres connections, and fast. Was it the batch that saturated the pool, or was the database already suffering from the Scaleway storage? I do not have a clean answer, and that is exactly the trap of correlated incidents: two plausible causes landing in the same window, and a doubt that only lifts after the fact. What I do know is that the two fed off each other. A database that responds poorly, connections piling up instead of being released, a batch that keeps asking for more. The pool hits its connection limit, and from there no application can open a single one. Everything falls in cascade.

The real problem: an HA setup that wasn’t one

My database ran in high availability, two nodes. Reassuring on paper. Except that both nodes lived in the same datacenter, fr-par-1. When the block storage layer of fr-par-1 went down, my two replicas left together, in the same second. That is the lesson I hold onto the most: redundancy only protects against what it isolates. Mine covered the failure of a process or a machine, not that of an entire zone. I had taken out insurance against one risk, not against all of them.

Worse, restarting the database was impossible. The managed Postgres engine stayed hooked to the failing storage. I could kill the zombie connections and restart my applications all I wanted, the final recovery no longer depended on me: it was suspended on Scaleway’s repair. Finding yourself a spectator of your own outage, with no lever at all, is the most unpleasant moment of the evening.

Getting out of it

Things unblocked during the night, by combining three things. I cut the connections left open on the Postgres side, I restarted the applications to start again from clean pools, and Scaleway eventually repaired the storage node. That last point was the decisive factor. Without it, the rest was useless. My first two actions only set the stage so everything could come back cleanly once the infrastructure returned.

What I take away, and what I have already done

A good incident is the one that finally makes you do what you were putting off. I tackled three things right away.

PgBouncer in front of Postgres, first. A connection pooler I had wanted to set up for a long time without ever getting to it. It caps the number of connections and stops a batch from starving every other application. It is in place.

A read-only failover in another zone, next. My two HA nodes in the same datacenter were the heart of the problem. I added a read-only replica elsewhere, so that a Scaleway zone going down no longer takes everything with it in one block.

Observability on connections, finally. Watching pg_stat_activity and how full the pool is, to see saturation climb and fire an alert before it kills everything, instead of discovering it once the service is already down.

The lesson, in one sentence

An infrastructure dependency, however solid on paper, stays a single point of failure until you have explicitly isolated it. And redundancy you have never tested against the right failure mode is redundancy in name only.

If you have infrastructure you keep calling “highly available” without having checked against which kind of failure exactly, we can take a look together, rather than finding out on some Tuesday evening.

How much am I owed, in total, right now?

2026-07-13T18:00:00+02:00

All financial figures and client names in this article are fictional. The screenshots show real screens, filled with made-up data.

When you run a company on your own, one question comes up more often than any other. Not “how much did I invoice last month”, not “what’s my yearly revenue”. The real question, the one that decides everything, is: how much am I owed, in total, that I’m going to collect?

Not within a 30 or 90 day window. In total. Everything invoiced and not yet paid, with no time limit, and whatever is overdue clearly flagged.

And the problem was that nothing answered it. My accounting software told me what was invoiced. My CRM what was in the pipe. My bank account what had already landed. Three partial truths, in three different tools, that I had to cross-reference by hand in a spreadsheet on a Sunday evening. Which is to say: never.

So I stitched the pieces back together at the source, inside Argos.

Argos, from CRM to treasury cockpit

Argos is the CRM I built for SXN Labs. It started out managing contacts, deals and quotes. The latest project was to graft a treasury-tracking layer onto it, with one rule I set for myself: show facts, not predictions. I didn’t want a model guessing my future. I wanted the truth at time T, the kind I can verify line by line.

The result is a dashboard whose default state is a sentence I love to read: “Nothing needs your attention.” When something is off, it surfaces it. When everything is fine, it says so, and then it shuts up. At the top of the screen, a handful of numbers, all factual, all up to date, without me entering anything.

The Argos Cash dashboard at a glance (fictional data).

Under that calm surface, there are three small technical challenges I find interesting.

All the pending cash, at once

The central number is “to collect”: the sum of every invoice issued and not yet paid. No sliding window, no arbitrary horizon, just the total.

But a raw amount isn’t enough. What I want to see at a glance is the ex-VAT figure (what’s actually mine), the VAT share (which I’m only holding for the tax office), and above all what’s overdue. A client who has owed 8,400 € for ten days is not the same piece of information as a client who has until the end of the month to pay me. The first calls for a reminder, the second doesn’t.

Argos computes that ex-VAT / incl-VAT / overdue split from Pennylane invoices. And this is where using Pennylane as both bank and accounting software pays off. No bank reconciliation to do, since payments are natively matched to invoices, transactions arrive already categorized. I consume the data as-is, I don’t reclassify anything by hand.

Two accounts, one treasury

My treasury lives in two places. Pennylane for day-to-day banking. Spiko for idle cash, parked in tokenized money-market funds that earn a little every day.

Total treasury is therefore the sum of the two pools. Because they are physically distinct, a bank account on one side and fund shares on the other, there’s no risk of counting the same euro twice. And if one of the two sources goes down, the system falls back cleanly on the other rather than showing a phantom balance.

A small anecdote for anyone who has integrated an API before: Spiko returns a lovely 403 from Cloudflare if you don’t send a browser User-Agent. The classic “your urllib is blacklisted by default”. Five minutes of confusion, one header, and you move on.

And everything else, in one place

Once cash-to-collect and treasury were in place, I added the other facts that weigh on a small company: monthly recurring revenue, what was actually collected this month, and an estimate of the dividend I could pay myself, net of tax. Always the same logic: observed numbers, not promises.

And because Argos isn’t only a financial tool, the same screen also aggregates the operational side: are my deployed applications healthy, how many servers are tracked, which deploys happened today, is my inbox up to date, are my mileage entries logged. Finance, ops and admin, in a single glance. All crowned by that famous “nothing needs your attention” when the checklist is green.

The twist: less interface, not more

Here’s the counter-intuitive part.

The natural tendency, when you add data to a tool, is to pile on screens, charts and filters. I did the opposite. I shrank Argos’s interface surface to the minimum, and I now drive it almost entirely through MCP.

For the uninitiated, MCP (Model Context Protocol) lets you expose an application’s functions as tools an assistant can use. Concretely, Argos exposes tools like list_deals, create_quote, get_metrics_summary, daily_briefing. As a result, I barely click anymore. I talk to my CRM. “Summarize the treasury”, “which quotes are signed but not yet invoiced”, “create a deal for this prospect”. The answer comes back, or the action happens, without me opening a single page.

What I understood while building this is that for a tool I use alone, the most efficient interface isn’t a pretty web page. It’s a good, well-described API that an AI can operate on my behalf. The graphical UI becomes the exception, reserved for the moments when I actually want to see something.

A word on trust, because the question always comes up: this whole financial pipeline is read-only. No invoice creation, no transfer, no automated movement of money. The system reads, aggregates, displays. It never touches the money. It’s a sensor, not a hand.

Cash in sight, without going to look

One last detail remained, and it might be the most pleasant one day to day.

A dashboard, however accurate, is useless if it’s buried in a tab I open once a week. So I took it off the screen. I put a small e-ink display, a TRMNL, on the shelf in my office. It cycles the Argos Cash screen (to sign, to invoice, to collect, treasury, overdue invoices, collected this month) alongside other CRM views and more general ones: the weather, a photo, and the rest.

The TRMNL on my desk: treasury, ambient (fictional data).

The effect is surprisingly strong. Financial information is no longer something I go and fetch: it drifts through my field of view several times a day, between the weather and a photo, next to the hat and the sunglasses. I look up, and often enough, I know where I stand. No notification, no app to open. Just a calm number, updated on its own, in black and white on electronic paper.

What I take away

Building this thing for myself confirmed a conviction: the best tools you can make are often the ones you use first yourself, with real needs and real irritations. Argos’s treasury tracking was born from my own question, the one about the cash I’m owed. And that demand, the kind that lets nothing slide, ends up seeping into the product I offer my clients.

Three ideas worth keeping: stitch the data back together at the source instead of in a spreadsheet, show verifiable facts rather than predictions, and accept that the best interface is sometimes the one that doesn’t exist.

Next time you wonder how much you’re really owed, ask yourself another question: does your tool answer you at a glance, or do you still have to open a spreadsheet on a Sunday evening?

Ripping Algolia out of a healthcare app, the dependency that no longer earned its place

2026-07-06T18:00:00+02:00

On ORIGAMI, the healthcare business application I build for SOS Médecins (see the case study), patient search ran on Algolia. A hosted search service, fast, forgiving of typos. Last week I unplugged it entirely. The whole change comes down to two numbers: 33 lines added, 331 removed. And on the user’s side, nobody noticed a thing. That was exactly the outcome I was after.

Why Algolia was there

The reflex is a familiar one. You need a “real” search, instant, typo-tolerant, surfacing the right patient even when you fat-finger three letters. You glance at Postgres, decide it’ll be a hassle, and wire in a specialised service. Algolia does that job very well. Within a few hours the search feels smooth and the matter seems settled.

Except “wiring in Algolia” is never a single line. In the code it meant a Ruby gem, an npm package on the front end, an initializer to configure, API keys exposed to the browser, a job that reindexed patients into Algolia in parallel with the database on every change, and three Stimulus controllers talking directly to the Algolia client. A dependency isn’t a button you flip: it’s a surface you adopt, upgrade, monitor, and pay for every month.

The real requirement, once you lay it flat

The question I hadn’t asked myself in a long time: what search do I actually need here?

The answer is modest. We look up patients within the scope of a care structure. The dataset runs to hundreds of thousands of records, not tens of millions. The fields are simple: a last name, a first name, a few identifiers. The real need is to find “Smith” when you type “smth”, and to find it fast.

For that, Postgres is more than enough, even at that scale. The pg_trgm extension computes trigram similarity: it absorbs typos and partial prefixes without you writing a single distance algorithm by hand. A dedicated table materialises each patient’s search document, a job keeps it fresh on change, and the query runs in the same database, in the same transaction, with no network round-trip to a third party. That internal backend already existed and had been the default for a few weeks. Algolia was just a second engine we kept around out of caution.

The real argument: health data on the move

KISS is a good reason. It isn’t the best one here.

Sending patient names to a search index hosted abroad means letting health data leave its own infrastructure. It pulls in health-data hosting rules, GDPR, the principle of data minimisation. Even when everything is contractually airtight, it’s one more governance surface: another place sensitive data flows through, another processor to audit, another clause to defend the day someone asks the question.

So removing Algolia isn’t just dropping a dependency and a €250-a-month bill. It’s removing a reason to worry. Patient data no longer leaves the database. There’s no external index to secure, no API keys to leak from the front end, no processing agreement to keep an eye on, for a feature we already knew how to do in-house.

What the switch was really about: nobody feeling a thing

Swapping one search engine for another on software used in production isn’t a matter of flipping a global switch. The bar was clear. On the user’s side, search response times had to stay rigorously identical. Not “roughly as fast”, identical. A patient search that lags by a tenth of a second, on a dispatch desk, gets noticed immediately.

To validate that without risk, I’d added a per-user boolean, internal_patient_search, that turned the new engine on for a handful of accounts only. A selective activation mechanism, not a forgotten flag: long enough to run both backends side by side, compare response times in real conditions, and confirm that the move to Postgres was felt nowhere.

Once that validation was done, the flag had done its job. I removed it at the same time as Algolia, in the same pass: the database column, the checkbox in settings, the permitted params in the controller, the labels in two languages, and three now-pointless tests. A single boolean already touches six corners of the code; the discipline is less about never adding one than about dismantling it the moment it has stopped being useful.

What this is not

No case against Algolia here. It’s an excellent product, and there are contexts where I’d wire it back in without hesitation: a large e-commerce catalogue, a public-facing search, typo tolerance across millions of documents. The tool isn’t the point.

The point is the question you ask before adopting it. Not “what’s the best search?”, but “what search do I need, for this dataset, in this context?”. When you take the time to answer that honestly, you often avoid importing a dependency, a recurring bill, and, in healthcare, a piece of sensitive data that had no reason to travel.

Simplicity is a decision

Absorbing complexity on the provider’s side so the software stays simple for the client applies just as much to the complexity you inflict on yourself. The best code isn’t the one you write most elegantly: it’s the one you remove because you no longer need it, and will never have to maintain again. 331 fewer lines, one fewer dependency, health data that stays home, and a strictly identical interface for the user, response times included. That’s what a good day looks like.

If you’ve got an external dependency under the hood costing you every month without you really knowing what it buys you, we can look together at what deserves to stay and what can come back home.

AI didn't replace my job, it moved my ceiling

2026-06-22T11:00:00+02:00

People regularly ask me whether AI is going to replace developers. The question is backwards. On my projects, AI hasn’t removed a single skill. It moved a constraint I had taken for granted for ten years: my own time.

The real ceiling was never the code

When you build a serious line-of-business application alone or in a pair, what caps your output is the number of hours a human can sustain in a week without breaking quality. A small editor spends their life arbitrating: this week I wire up that integration, so I don’t touch the billing module; this quarter I push a certification through, so the mobile rework waits.

Simon Willison puts it well in a recent post: if AI hasn’t triggered a wave of developer layoffs, it’s because coding is only a small part of the job. Out of 160 companies that filed layoff notices in New York in 2025, “not a single one checked the AI box.” Deciding what to build, specifying it, verifying it, being accountable for what you ship, understanding the business context, none of that automates.

I agree. But I draw a slightly different conclusion than he does. If code is only a small part of the job, then accelerating the code doesn’t change the nature of the work, it changes its capacity. And for a small outfit, capacity is almost everything.

What it concretely changes

The way I work shifted on scoping, on pricing and on running the project.

Scoping. I used to instinctively drop the “correct but expensive” features: the clean degraded mode, the monitoring, the integration tests on an external feed. Not out of laziness, out of a time budget. Today the marginal cost of doing it right has dropped. I wire in the safety net because writing it no longer costs me half a day.

Pricing. A fixed-price quote is a bet on time. When the output ceiling rises, the same scope ships faster, or a more ambitious scope fits the same envelope. That doesn’t mean billing less; it means delivering more value for the price, and moving on to the next job sooner.

Running the project. More back-and-forth with the client, and earlier. Mocking up a variant in an afternoon instead of a week means being able to say “look, here’s what it looks like” before freezing a decision. Velocity isn’t there to produce more lines. It exists to shorten the loop between a business idea and something you can actually touch.

What it doesn’t change (and the anxiety that comes with it)

There’s another, darker reading going around among developers. A post that circulated recently tells the same story from the inside: ten years building deep expertise (finance, debugging, architecture) only to watch it become “promptable” in a few weeks. The anxiety isn’t unemployment, it’s the commoditization of mastery.

I understand the vertigo. But I think it conflates two things: knowing how, and knowing what to do and being accountable for it. AI makes the first abundant. The second (deciding, specifying, verifying, carrying responsibility for what ships to production on a sensitive system) stays rare, and stays mine.

The job doesn’t disappear. It moves up a notch, toward less production and more judgment.

Stepping back

Let me zoom out, owning that this is an opinion and not a proof.

There’s a lot of talk about France’s demographic problem: an inverting age pyramid, the large cohorts retiring, a thinner generation behind them. Public debate fixates on a single variable, the retirement age. It’s one variable among several. Producing more per head is another, and tooling that raises one worker’s capacity feeds directly into it.

I’m not claiming AI fixes demographics, that would be exactly the kind of marketing shortcut I spend my time criticizing. But when one worker can carry a volume of output that took two yesterday, it counts in the equation. It’s less divisive than moving an age slider, and probably more durable. Provided the gains go to the value produced, not to stacking tools for the sake of tooling.

Conclusion

AI didn’t replace my job. It removed the dumbest limit weighing on it: the fact that a day has twenty-four hours. What stays rare (deciding, specifying, verifying, being accountable) hasn’t moved an inch. That’s precisely where the value of an editor lives, solo or not.

If you run a company and you’re wondering where AI has a real effect rather than a cosmetic one, that’s exactly the kind of context we can look at together, and settle what genuinely deserves to be automated.

E-invoicing 2026: the part the platform won't do for you

2026-06-08T15:30:00+02:00

September 2026 is everywhere. In public campaigns, in tax authority emails, in conversations with accountants. The date has entered the scenery, which is not a bad thing: at least this time, nobody should discover the reform the night before with a surprised face and three spreadsheets open.

The problem is not that nobody talks about September 2026. The problem is what people put behind that date. Many still hear it as “the start of e-invoicing”, or as the deadline for large companies that must start issuing. For a small business, the concrete effect is more immediate: from 1 September 2026, your suppliers may send you real electronic invoices, and you must be able to receive them.

Receiving comes before issuing, and it’s exactly the part you don’t control. But the real question, behind the date, isn’t which tool to buy: it’s who is going to wire all this into your software. And there, neither the platform nor the accountant holds the role.

What changed in the system

For two years, the announced design relied on the PPF (the public invoicing portal) as a platform invoices could transit through. The system has since been narrowed: the PPF is no longer the public transit platform companies were expecting, but the infrastructure for the central directory and for reporting data back to the tax authority. Its job is to know who receives what, through which platform, and to concentrate the tax data needed by the DGFiP.

Concretely, that means three things:

B2B invoice transit now goes through certified platforms (the former PDPs), registered by the tax authority. No simple public option where everyone deposits and retrieves invoices.
Chorus Pro remains the reference platform for B2G, invoicing the public sector doesn’t change channel.
Penalties have been strengthened: the per-invoice fine goes from €15 to €50 per invoice, e-reporting from €250 to €500 per transmission (with annual caps).

In the official list at the time of publication, examples include familiar names such as Pennylane, Qonto, Sage, Cegid, Tiime, Indy, Yooz or Esker. This is not a recommendation list, just a useful reminder that reception won’t go through a magic public form, but through an intermediary you actually choose.

The operational calendar remains easy to remember: mandatory reception for everyone on 1 September 2026, issuance for large companies and mid-caps on the same date, issuance for SMEs and micro-businesses a year later.

Why reception is the trap

When people talk about September 2026, the natural reflex is to ask: “do I have to issue?” If you’re an SME or a micro-business, the answer is often no, not yet. That’s where the misunderstanding starts.

When you issue, you hold the schedule. You pick your platform, you migrate when you’re ready, you test on your own flows.

Receiving is the opposite: your supplier decides for you. From 1 September 2026, the moment one of your large or mid-cap suppliers switches to electronic issuance (and they’re required to by that date), you must be able to ingest their invoice. You choose neither the timing, nor the format, nor the platform on the other side. You’re on the receiving end, literally.

And “being able to receive” isn’t having an inbox. In the sense of the reform, an electronic invoice takes one of these baseline formats:

a pure structured XML (UBL or CII),
or a Factur-X: a human-readable PDF/A-3 with the same CII XML embedded inside for the machine.

You can’t tell them apart by eye: both open in a PDF reader. To find out which category your software currently produces, drop one of your invoices into the Factur-X pre-check, the analysis runs in your browser, the file goes nowhere.

Receiving properly therefore means connecting to a certified platform, pulling the flow, parsing the XML, validating it, then reconciling it against your purchase orders and your bookkeeping. It’s an integration project, not a setting to toggle. And it’s exactly the kind of work you underestimate until you’ve done it.

The format isn’t the problem

I wrote two open-source gems around this: einvoicing for the core (generating and reading Factur-X, validation, CII profiles) and einvoicing-connect for the plumbing (Chorus Pro, certified platforms, e-reporting). After running them on real flows, one thing became obvious: the format is the easy part.

Producing a compliant Factur-X is mechanical. A PDF/A-3, a CII XML attached with the right filename and the right profile, a handful of validation rules. A library does this very well:

invoice = Einvoicing::Invoice.new(profile: :en16931)
invoice.add_line(description: "Service", quantity: 1, unit_price: 950_00)
facturx = invoice.to_facturx(pdf: rendered_pdf)   # PDF/A-3 + embedded CII XML

The real work is elsewhere, in the business reconciliation. An incoming invoice has to be linked to the right supplier, the right purchase order, the right VAT, and you have to handle credit notes, partial invoices, cent-level discrepancies, identifiers that never match on the first try. The XML hands you clean data; it doesn’t tell you what to do with it inside your accounting. Reconciliation is where 90% of the effort goes, and no platform will do that part for you.

The role nobody holds

Look at who actually shows up on this. The certified platform delivers a clean flow to your door. The accountant reads the result once it’s in the books. Between the two, there’s a space neither of them covers: making your software (your business app, your ERP, the spreadsheet everything revolves around) ingest that invoice, reconcile it, and do something useful with it. That space is integration. That’s a developer’s job.

Concretely, it comes down to three pieces:

The plumbing. Connecting your existing software to the certified platform’s API so the incoming flow lands inside your system, not in yet another portal someone has to check by hand. Nobody else knows your data model.
The reconciliation. The famous 90%: linking each received invoice to the right supplier, the right purchase order, the right VAT, handling credit notes and discrepancies, inside your business model. No platform will do it, because no platform knows your business.
The lifecycle. The reform requires you to report invoice statuses (received, refused, paid…). Those transitions have to live in your real workflow, not in a separate interface nobody will ever update.

That’s where I sit, and it’s what I wanted to make clear here: I don’t sell a platform. I make your existing software speak the language of the reform (ingest, reconcile, report), where the platform stops and your business begins.

The right question to ask now

The reform is not “2026 for large companies, 2027 for small ones”, but 2026 for everyone on reception, then 2027 for part of the market on issuance.

So the useful question is not only “when do I have to issue?” It’s: “on 1 September 2026, can I receive a structured electronic invoice and integrate it without re-keying it by hand?” If the answer is no, this isn’t next year’s problem. It’s this summer’s.

Picking a certified platform, wiring up reception, testing the parsing on a few real supplier invoices: that’s a calm few-weeks job if you start now, and a painful one if you wait for the first supplier to switch without warning.

Preparing reception before it hurts

A business application, an ERP held together around spreadsheets, an accounting workflow that still works because someone re-keys everything by hand: e-invoicing will quickly reveal the places where the system mostly runs on human patience.

This is the kind of work I handle at SXN Labs: clarify the real need, choose the right level of automation, wire up reception, and make sure invoices land in the right place without adding yet another overbuilt system. If your e-invoicing reception is about to become a painful project, drop me a line.

Hermes: automating my day without handing an AI the keys

2026-06-07T14:00:00+02:00

Hermes is my personal assistant. Mine, not the large open source project that later took the same name. I had already called the folder ~/Hermes before that one shipped. The name was mostly obvious for a system that carries messages, signals and decisions, and the code has no ambition to become a generic product. It is useful to me precisely because it is so personal.

I built it because part of my working life looks like that of many freelancers and small teams. Important things are scattered across Gmail, GitHub, Sentry, Pennylane, Things (my task manager), Markdown files, internal dashboards and a few corners of my brain that would rather have been used for something else. A CI run that fails, a Sentry error that keeps coming back, a quote to follow up on, an invoice to track, a project almost finished that risks getting stuck. None of these is hard on its own. Their accumulation, on the other hand, ends up producing a fairly mediocre kind of mental load.

The ridiculous pitch would be to say I built a “personal agentic operating system”. I could even add “AI-augmented” to make sure I lose everyone except two LinkedIn consultants and a prompt engineering course salesman. The reality is simpler. Hermes is a set of small local agents running on my Mac, with state files, Python scripts, a private dashboard, a few business integrations, and above all fairly strict rules about what they are allowed to do.

Some agents use an LLM. Many do not. That distinction matters, because the right use of AI is not to replace every if with a prayer billed by the million tokens. When a task is deterministic, a dumb reliable script is usually better. When heterogeneous signals need summarizing, an arbitration needs proposing or three clear options need laying out, an LLM can earn its place. Adding AI everywhere is easy. Knowing where it genuinely deserves to enter the loop is the hard part.

A personal tool, not a generic framework

I increasingly think AI becomes genuinely effective when it is embedded in a very personal tool, in the strict sense: a tool built for one person, with their reflexes, their blind spots, their priorities and their way of deciding. Hermes extends how I work rather than bolting onto it, and it carries my information sources, my risk thresholds, my decision habits, and the exact places where I want to take back control.

That is why I am fairly wary of generic agent frameworks sold as shortcuts. They can be useful for prototyping, but their structure already carries a view of what work is: how memory behaves, how tasks are routed, what counts as success, when to escalate, how to notify, what qualifies as an action. Using someone else’s framework without questioning it often means adopting someone else’s logic. Sometimes it fits your problem. More often it fits the demo of whoever wrote it.

We have seen this film before with React SPAs. For years, brochure sites, tiny back offices and rather ordinary forms absorbed Facebook’s complexity while believing they were becoming Facebook. What they mostly got was the mental cost, the oversized bundles, the fragile client state and the hydration bugs, without ever having the problem that justified the architecture. AI is walking the same path whenever people start by picking an agent stack before understanding the actual work to automate.

So Hermes is deliberately built around my constraints. My inbox is my todo list. Things is where the real actions live. The dashboard carries passive information. Telegram is for urgent arbitrations. Clients, quotes, incidents and projects already have their sources of truth. The system does not get to invent a parallel world, it has to connect what already exists and interrupt me only when that is worth the cost.

What the system has to solve

The starting need was not “having an agent”. I did not need one more chatbot to remember to talk to, to re-brief with context, and then to double-check. That is sometimes useful for thinking out loud or producing a draft, but it does not really remove the operational load. It moves that load into a chat window, with a more polished interface and the same problem behind it.

What I wanted was to know each morning what deserves my attention, to avoid finding out too late about a blocked PR or a production error, to track quotes without turning my brain into a low-budget CRM, to keep client context available before a call, and above all to finish the things that are close to done instead of opening fifteen fronts at once. Most of these needs are prosaic. That is exactly why they matter. A useful tool usually starts by removing mundane friction, not by announcing that it will reinvent work.

The boundary I set from the start is simple. Hermes may observe, classify, summarize, prepare, flag and propose. It must not mistake itself for me. It does not publish a quote, does not send a client email, does not make an architecture decision, does not modify a project beyond trivial fixes, and does not manufacture noise to prove it is working. I already have enough software that confuses activity with usefulness.

Anonymized overview. The dashboard keeps actions, signals and agent state in one place, without turning every piece of information into a notification.

Deliberately ordinary architecture

Hermes runs locally on my Mac. A scheduler managed by launchd reads a schedule.toml file, works out which agents are due, applies simple preconditions, then launches the jobs. Runs write their logs, their state, and an HTML dashboard page. Shared state lives in JSON or JSONL files, the more human notes are in Markdown, and deterministic tasks go through Python scripts.

This architecture will impress nobody at an AI conference, and that is fine. I would rather have a system I can understand at 11pm, when something stops working, than a magical platform where three proprietary abstractions hide a cron, a queue and a prompt. The day it breaks, I want to open a file, read a log, work out which agent wrote what, and fix it. The rest is often decoration sold at SaaS prices.

The scheduler also caps concurrency. It does not launch twenty agents because twenty agents exist. Some jobs run in pure Python, particularly where the logic is stable and an LLM call would only add cost and randomness. Others go through a model when they have to aggregate less structured signals. The mix is not very dogmatic, but it has the merit of being honest. AI is a component, not an architectural religion.

Agents with a narrow job

Every agent has a tight scope. That is probably the most important choice in the project. A “general assistant” agent quickly swallows all available context and acts with a confidence inversely proportional to its actual understanding. An agent that reads one specific queue, produces one specific state and writes one specific dashboard is far more boring, and far more usable.

The morning briefing prepares the start-of-day summary: PRs to review, failed tasks, overnight activity, Sentry signals, work queue. Inbox triage reads the Gmail inbox, since my inbox is deliberately a todo list. It classifies threads, spots the ones that are aging, and can draft simple administrative replies, but it never touches client or prospect mail. Project focus picks the three projects to push that day, favoring whatever is close to done, whatever got a client signal, or whatever risks getting stuck.

Dev agent is tighter still. It can handle a few obvious Sentry errors, risk-free Dependabot merges, or mechanical CI fixes. It has no right to do product, architecture, refactoring or ambiguous application bugs. The slightest doubt falls out of scope. Frustrating for a demo, very healthy for a tool that touches real repositories.

The business agents follow the same principle. Pennylane sync pulls invoices, transactions and balances to maintain a cash position, and stays read-only. Estimates tracks quotes and prepares proposals, but nothing is sent or published without explicit approval. Client context keeper rebuilds living client files from quotes, invoices, recent conversations, PRs and incidents, preserving the manual notes. None of this replaces human judgement. It gets me to a decision with the right context already in hand.

Project Focus does not look for the most appealing project. It pushes whatever has to move forward: nearly finished work, recent client signals, explicit blockers.

Attention as a product constraint

The biggest trap in automation is the system that works well enough to produce noise. A useless alert becomes an interruption, a repeated interruption becomes a reflex to ignore, and an ignored system ends up worse than no system at all, because it creates the impression that something is being watched when nobody is listening any more.

So Hermes separates the channels. The dashboard holds passive information, Things holds the actions I actually have to take, Telegram covers emergencies and short arbitrations, and the state files keep history for the next runs. An invoice expected in three days is not necessarily an action. A client to follow up on is. An already merged PR must not spawn a fresh todo because an agent re-read an old JSON file with the administrative enthusiasm of a tax form on amphetamines.

There is deduplication, there are anti-spam windows, there are “one subject, one todo” rules, and there are cases where Hermes explicitly decides to push nothing at me. Less spectacular than an avalanche of notifications, and it is what makes the system usable. Attention is a limited resource, and an assistant that wastes it is working against me, however statistically well-meaning its intentions.

Refusals are a feature

The most important part of Hermes is not the list of what it can do, but the list of what it refuses. No automatic client email. No quote published without explicit approval. No code change beyond a trivial scope. No architecture decision. No Things todo for its own internal plumbing. No “I think that…” when the system could ask a clear question with three actionable options.

This is where the product mindset really counts. When you discover agents, the natural reflex is to add capabilities: answer clients, publish quotes, merge PRs, decide the next piece of work, reorganize the schedule. Some of those may be reasonable one day. But the right question is not “is it technically possible?”. The right question is “which mistake becomes possible if I allow it?”.

An agent that can do everything is not necessarily powerful. It often offers an accident surface with good UX. Hermes is useful because it knows to stop where my judgement is still needed: arbitrating a client need, accepting a commercial risk, approving a proposal, deciding that a request contradicts the reason a piece of software exists. Those decisions are not annoying details waiting to be automated, they are exactly where the value sits.

Memory you can inspect

Hermes memory lives in files. JSON, JSONL, Markdown. Basic, versionable, inspectable, repairable. Each agent reads what it needs and writes into precise areas: dev queue, PR memory, failed tasks, project signals, answers to questions, client files.

I have nothing against semantic search, and Hermes uses it where it adds something. But the operational memory of a working system has to stay readable. An agent that justifies a decision with “I found that in my memory”, with no way to inspect the source, is not intelligent. Nobody can audit it, which is a very modern way of being dangerous.

The dashboard plays the same role. It is not there to look nice, even if I eventually gave it a decent shape because I am weak in the face of a clean interface. Its real job is letting me check that an agent ran, what it saw, what it did, and sometimes what it refused to do. Dates are absolute rather than relative, because “two hours ago” turns false fast in a cached page or a screenshot. Timestamps come from the system, not from the model’s imagination. An agent that writes a future date is not visionary, just broken.

What this really shows

Hermes is a side project, but not a technical whim. I treat my own business as an internal product. The need was never to use AI. The need was to reduce forgotten things, prioritize work that actually matters, keep a usable financial picture, avoid repetitive admin, make client context available at the right moment, and preserve human decisions where they carry value.

That logic looks a lot like the one I apply at client sites. Before building anything, you have to understand the real work: who does what, with which information, in what order, with which risks, and which decisions must absolutely not be automated. Only then do you pick the tool. Sometimes that means a full custom application. Sometimes it means automating three painful steps. Sometimes it mostly means asking Excel to stop playing ERP, CRM, scheduler, reporting layer and collective conscience of the company all at once. Excel is very good, but it too deserves a dignified retirement.

I am not going to publish Hermes as it stands. It contains my professional life, my clients, my finances, my emails and enough internal paths to make any normally constituted CISO cough. The principles, though, are reusable. Start from a recurring friction, separate information from action from decision, give every automation a narrow scope, keep state inspectable, put the human in the loop in the right places, and use an LLM for ambiguity rather than as a replacement for a reliable script.

If any of this sounds familiar

Hermes is personal, but the problem is very common: scattered information, manual processes, forgotten follow-ups, decisions made without the full picture, SaaS tools that are too generic, and an Excel file still standing out of sheer local patriotism. In those situations the right question is rarely “how do we put AI in the company?”. It runs more like this: which tasks keep coming back, which decisions genuinely need a human, which information arrives too late, and which existing tools could be connected instead of replaced.

That is the kind of work I do at SXN Labs, understanding the business, finding the real friction, building the software or the automations that cover the need, then leaving behind a system that is simple to use, observable and maintainable. Not a magic demo. A tool that helps, with enough limits to stay good company.

Connecting INSi with strict TLS and clinical continuity

2026-06-04T18:00:00+02:00

One Tuesday morning, every call from a production healthcare app that I build and maintain to the French national INSi teleservice started failing server-side. Patient identity verification was completely broken.

On the user side, the software did what it was supposed to do: it did not show a stacktrace, it indicated that INS verification had not completed. The patient was there, the care flow could continue, but the identity remained unverified.

The underlying error, captured in Sentry, was a single line:

OpenSSL::SSL::SSLError: SSL_connect returned=1 errno=0
  certificate verify failed (self-signed certificate in certificate chain)

Diagnosis took twenty minutes. The clean fix, two hours. But the point was not to rework the UX or the business behavior. The INSi integration was already running in production with strict TLS verification and correct behavior on failure; the incident mostly exposed one operational subject that had to be made explicit: the IGC-Santé trust chain.

The service had to work again, without weakening TLS, while preserving an important property: an external failure should not block clinical work.

There is a wrong answer to this problem, copy-pasted everywhere on forums, that you absolutely must avoid when you ship patient identity data over the wire. It fixes TLS about as well as removing the engine light fixes a car.

The Actual Need

The business need was not “complete a TLS handshake”. It was simpler:

Verify a patient’s INS identity when the teleservice responds.
Let the clinician keep working when the teleservice does not respond.
Clearly mark the identity data as provisional until it has been verified.
Know before the next outage that a certificate is about to expire.

TLS was only one part of the problem. Important, but not enough. A critical integration also needs an explicit answer for the days when the external dependency does not respond.

What INSi Does

INSi is the CNAM (French health insurance) teleservice that lets a clinical app fetch or verify a patient’s National Health Identifier from civil traits: name, first name, date and place of birth. It is a central building block for producing, exchanging, and archiving healthcare data against the right patient identity.

The endpoint lives on services-ps-tlsm.ameli.fr. It’s SOAP, authenticated by a client certificate issued through the ANS Portail de Confiance. On the server side, the TLS chain roots in the IGC-Santé root CA, the French state authority for healthcare PKI.

That root is in no default system trust store. Not Debian, not Ubuntu, not macOS, not the Mozilla bundle embedded in most HTTP libraries. It’s a specialized government PKI, separate from the public web PKI. If you do not add it explicitly, OpenSSL will not discover it through administrative telepathy.

The Bad Fix

If you search “OpenSSL self-signed certificate in certificate chain Ruby”, you’ll find ten StackOverflow answers all saying the same thing:

# DO NOT do this on a patient identity flow
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

On a personal script scraping a site with a self-signed certificate, that is between you and your conscience. On a flow that ships a patient’s social security number, name, and date of birth to a service authenticated by client certificate? Absolutely not.

Disabling verify_mode means:

Accepting any certificate on the other side, including a MitM attacker on the network.
Punching a hole in the only cryptographic guarantee that the machine you’re talking to is in fact CNAM’s.
Carving into the codebase, durably, a security regression no one will ever revisit.

And for nothing, since the real answer is quick, documentable, and keeps security in place. A useful detail when the payload is patient identity.

The Clean Fix

ANS publishes the IGC-Santé chain publicly on its site (root + intermediates, PEM format). The right reflex:

Download the official chain from the ANS portal.
Verify fingerprints: SHA-256 of the downloaded cert compared against the one served by the live endpoint, and against the one published by ANS. Three sources, one hash. If any of the three disagrees, stop.
Bundle it into the project, under version control, distinct from client certificates (which stay in encrypted credentials).
Point OpenSSL at it when building the SOAP client.

In a Rails app, simplified, this is what Ameli::Insi ends up looking like:

class Ameli::Insi
  def http_client
    Savon.client(
      wsdl: wsdl_path,
      ssl_cert_file: client_cert_path,
      ssl_cert_key_file: client_key_path,
      ssl_ca_cert_file: igc_sante_bundle_path, # bundled public chain
      ssl_verify_mode: :peer                   # strict verification stays on
    )
  end

  private

  def igc_sante_bundle_path
    Rails.root.join("lib", "certs", "igc_sante.pem").to_s
  end
end

To validate end-to-end before even redeploying, openssl does the job:

openssl s_client \
  -connect services-ps-tlsm.ameli.fr:443 \
  -CAfile lib/certs/igc_sante.pem \
  -servername services-ps-tlsm.ameli.fr \
  -showcerts < /dev/null 2>&1 | grep "Verify return code"

Expected output: Verify return code: 0 (ok). From there, the Ruby client works again, in VERIFY_PEER, with no security downgrade.

The Useful Behavior

Once the root cause was fixed, one interesting point was worth making explicit: why had the incident not blocked the clinician?

Because the software did not treat an INSi failure as an exception to throw on screen, but as a business state. When INSi answered, patient identity was verified. When the teleservice did not answer, the technical error stayed in Sentry and the interface told the clinician that INS verification could not be completed.

The application boundary looks like this, simplified:

def fetch_by_traits(patient)
  response = http_client.call(:fetch_by_traits, message: payload_for(patient))
  Ameli::Insi::Identity.from_soap(response)
rescue HTTPI::Error, Savon::Error => e
  Sentry.capture_exception(e, extra: { patient_id: patient.id })
  raise Ameli::Insi::TeleserviceUnavailable
end

The calling controller rescues TeleserviceUnavailable and keeps a provisional identity (the civil traits typed by the clinician, tagged “INS not verified”), with a banner explaining INSi is down and that the record must be re-verified later. The clinician keeps working, the patient isn’t blocked, and the data will be reconciled at the next successful call.

That was already the useful behavior. Not spectacular, not great demo material, but it is what matters in production: an external dependency going down should not stop the care chain. It should become an explicit degraded mode.

The Invisible Work

This incident also brought back an operational point that is easy to underestimate. INSi, MSSanté, and Pro Santé Connect client certificates are renewed manually on the ANS Portail de Confiance, then stored in encrypted credentials. The app can work perfectly for months, until one deadline arrives silently.

The day one expires, you get the same outage again, with a familiar smell and a perfectly reasonable urge to insult a calendar.

So, right after the fix, I added a daily job that walks the inventory of bundled certificates: public chains and client certificates. It reports to Sentry any certificate within 30 days of expiry, then escalates at 7 days or once a certificate has already expired.

I also added a renewal runbook versioned in the repo (lib/certs/README.md), with the PFC procedure step by step. No one will see it as long as it works. When it threatens to break, it will be an actionable warning, not a surprise outage.

A quick map of French healthcare PKI

For anyone discovering the ecosystem, the building blocks look alike and it’s easy to get lost:

INS: the patient’s national health identifier (NIR or NIA + traits). The data.
INSi: the CNAM teleservice that lets you fetch / verify an INS. The API.
MSSanté: secure messaging between professionals and with the patient. Separate PKI, certificates issued by MSSanté operators.
Pro Santé Connect: the state SSO for healthcare professionals (dematerialized CPS card, OIDC).
IGC-Santé: the shared PKI root that signs most of the ANS server side.

Each block is documented, each chain is public and verifiable. The trap is treating this as an annoying technical detail when it is part of the product: identity, security, continuity of care, and operations.

What I Keep From This

When a TLS integration breaks in production, the right answer is almost never “disable verification”. It’s: find the missing trust anchor, make it explicit, version it, audit it over time. The VERIFY_NONE reflex saves ten minutes now and leaves a security debt to age quietly in the codebase.

The other point, more product than TLS, is that any critical integration needs a degraded mode. An external teleservice going down is normal over a decade of operations. Here, that decision already existed on the user side: INS verification failed, the clinician was informed, and care could continue.

The real work was the whole loop: understand the clinical need, make the trust chain explicit, preserve security, rely on the existing business fallback, then monitor certificates so we do not replay the same scene three months later in a different outfit.

If you have one of these at work

French healthcare integrations (INSi, MSSanté, Pro Santé Connect, DMP) are a mix of PKI, certificates, WSDL files, and ANS procedures that require more patience than genius. They work. But you need to frame the business need as much as the technical connection.

This is the kind of work I handle at SXN Labs: understand what actually needs to keep working, simplify the scope, connect it properly, and leave behind a system people can operate. If you have a healthcare teleservice stuck somewhere, drop me a line.

Controlling my Intex spa without its app

2026-05-31T18:00:00+02:00

I have an Intex PureSpa Baltik inflatable spa in the garden. It works great. The iOS app that comes with it, on the other hand, is a disaster: you need a Tuya cloud account, auth drops every three days, half the commands take 10 seconds to land, and the UI looks like a POC abandoned in 2018. For a device that lives on my Wi-Fi 3 meters from my Mac, the round trip through a server in China felt pointlessly absurd.

So I dumped the app and wrote my own. One weekend of reverse engineering, then a few evenings stacking the features the official app will never ship. Here’s how it turned out.

Reverse engineering in 30 minutes

I got insanely lucky: mathieu-mp/aio-intex-spa had already done the thankless work. The spa’s Wi-Fi module listens on TCP port 8990, the protocol is binary with a simple checksum (modulo 0xFF, not 0x100, that’s the classic trap), and the functional commands (power, heat, filtration, bubbles) are toggles: you read the current state and only send if the desired state differs. Idempotent by construction.

I validated it byte-for-byte against my actual spa with a standalone probe.py (stdlib only, zero deps), then packaged that into a pure protocol.py layer that tests offline.

The whole architecture follows from these invariants:

One TCP connection only. The firmware accepts a single client at a time on 8990. Everything goes through one IntexSpaClient with an asyncio lock, owned by one Supervisor.
Polling doubles as keepalive. The firmware closes the socket if nothing talks for too long. So we poll every 10 s, and that also feeds the UI over SSE.
Stale-but-useful. If the spa becomes unreachable, we keep the last known reading and show an “offline” banner. The next poll catches everything up.

What the official app will never do

A real web UI

FastAPI + HTMX + Chart.js (vendored, no CDN, the app lives on the LAN, it has to work if the internet drops). A mobile-first page, a 7-day temperature chart, instant controls. All served by a single uvicorn process on my Mac running 24/7.

A weather-aware scheduler

The Intex app offers a rudimentary timer that isn’t even exposed over the LAN protocol, so I wrote my own. Three primitives: setpoint by time slot, filtration windows, and most importantly “ready by 6 PM” which figures out when to start heating.

The interesting twist is that the heating rate isn’t constant. A spa loses heat proportionally to (water − outdoor air). So I pull local weather from Open-Meteo (free, no API key), learn the thermal loss coefficient from the history of heating and cooling phases, and the scheduler automatically shifts the start time earlier when it’s cold. If the night will be 4 °C, we start heating 90 min ahead; if it’s 18 °C, 30 min is enough.

A camera with cover detection (experimental)

The spa is partly visible in the field of an outdoor IP camera. I plugged in ffmpeg to grab a frame every 10 s, write it atomically (tmp + replace), rebuild a daily mp4 timelapse on the fly, and (for kicks) detect whether the cover is on via a calibratable ROI and a luma + std-dev heuristic. It’s partial and flaky at night, so it isn’t wired into the scheduler in v1. But the plumbing is there for the day it is.

A launchd service that survives silent failures

This is the part that took me the longest and that nobody talks about. On this machine, CPython 3.14 was silently killing the service after ~30 s under launchd. No traceback, no log, just a dying process. The culprit is a segfault in uvloop / httptools / pydantic-core on long loops. Back to 3.12, problem gone. And then all the plist settings you only learn the hard way: ThrottleInterval=15 to avoid respawn loops that saturate launchd, ProcessType=Adaptive (not Background, otherwise jetsam kills us first under memory pressure), ExitTimeOut=20 to let the TCP connection close cleanly, and crucially no --workers 1 on uvicorn (that flag flips it into multiprocess mode and wedges under launchd; the default single-process does exactly what you want).

Stack

Python 3.12 + FastAPI + HTMX + Chart.js + ffmpeg + Open-Meteo + launchd + ngrok for remote access. No database. The whole state fits in a handful of JSON and JSONL files under state/. 135 offline tests that run in 3 seconds without touching the real spa (a fake_spa.py replays the protocol).

The reusable pattern

This black box looks like every other one: a low-end IoT device that demands a cloud account to do the most trivial job. The pattern works for Tuya bulbs, Somfy shutters, and probably half the things in your house too:

Find the open TCP port on the LAN (an nmap usually does it).
Capture a few exchanges with Wireshark from the official app.
Identify the checksum and framing (protocol docs are rarely public, but rarely complicated either).
Rewrite a minimal client, validate byte-for-byte, add what the vendor never wanted to build.
Block the device’s WAN egress at the router, end of phone-home.

The code is public, now split across two repositories: github.com/sxnlabs/onsen-server for the FastAPI service and spa protocol, and github.com/sxnlabs/onsen-app for the application. Permissive licenses. If you have a PureSpa Baltik, you can literally fork the server and install it. And if you have another device with the same pattern, read intex_spa/protocol.py on the server side, it’s a good template for starting your own.

If you have one of these at work

I run into this black-box situation regularly on the consulting side: an industrial machine with an undocumented API, a sensor stuck behind a cloud app that bottlenecks the whole team, a B2B home-automation integration the vendor won’t build. That’s the kind of thing I unblock at SXN Labs. If you have a device that should just talk to your stack, drop me a line.

SXN Labs

What AI didn't make faster

What got faster

Deciding

Specifying

Checking

Securing

Answering for production

What it changes when you commission software

The popover that flickers on hover, the tiny bug that gives everything else away

Why the bubble flickers

Reading an intent rather than raw events

Two details that make the difference

What I take away

An offline handwriting notebook in the browser, no native app

The deploy that wipes the offline notes

The stylus that writes “too thick”

The line that does not stick to the tip

What I take away from it

If this sounds familiar

Connecting a Rails application to French e-prescription through Ordoclic

Software that has to prescribe

Two paths, two regulatory surfaces

What Ordoclic carries

What stays with the vendor

When the partner is down

The Rails side

The CNDA certification belongs to the vendor

The pattern, for other domain vendors

If this is sitting in your backlog

The code was right, the shipped package was not

Works on my machine

Three gaps between the repository and the package

The checks added

Beyond Ruby

VAT is not a rate, it is a regime

Seven regimes, not one rate

The field paper never asked for

Three cents apart, and the invoice is refused

The rates that exist anyway

Why this becomes a business problem

The question to ask your software vendor

What I take away from it

When code describes a feature that doesn't exist

A feature that existed only in the repository

Proving the code is unreachable

Delete the code, preserve the need

What the audit should conclude

Turbo has three scopes, not three tools

Versions and confidence levels

The model in one page

Which primitive should you reach for?

Turbo Drive

What is intercepted, and what is not

The lifecycle

The cache, in numbers

Turbo.config

Prefetching

Turbo Frames

It all comes down to one identifier

The layout, and the static layout trap

The attributes that matter

Turbo Streams

Frames or Streams? What really separates them

The full path, from controller to view

Eight actions, and morph is not one of them

target and targets are not the same thing

The silence when the target does not exist

Adding your own actions

The HTTP status, and why 422

4xx and 5xx: two rendering paths, not one

Morphing

What actually triggers a morph

What morphing changes, line by line

idiomorph decides by identifiers

Node moves, and why Safari differs

Field values are not protected

The protection toolbox

Broadcasts

Four macros, and one asymmetry

Eight actions, and `morph` is not one of them

`target` and `targets` are not the same thing

`current_user` is not available in a broadcast render