DEV Community: DimiDan

Baking Accessibility into Your Design System: A Four-Layer Testing Strategy

DimiDan — Wed, 12 Aug 2026 04:38:49 +0000

Why I care about Accessibility: a short pre-history

Many years ago, at the jam session at friends's place, I met someone with a visual disability. You know standard small talk who works where... But when I mentioned I was a FE dev, the conversation changed instantly. I've been asked with so many questions. Why does one site read perfectly with a screen reader while another is an unnavigable wall of "clickable, clickable, clickable"? Why does a form sometimes announce what a field is for, and sometimes just say "edit text"?

But the question that stuck with me wasn't technical at all. This person asked how to explain to developers that accessibility attributes are so, so important, and how to pass a message to the dev community: please don't ignore us.

I didn't have a good answer that evening. The honest one is uncomfortable: most developers don't ignore accessibility out of malice. They ignore it because nothing in their workflow ever tells them it's broken. Their linter is silent, their tests are green, their PR merges. The people affected are invisible in the feedback loop.

What that conversation left me with is a simple thought I'd put on every developer's wall:

As a dev, you can actually make someone's life better. Don't forget this.

We spend so much time on abstractions (bundle sizes, render cycles, type inference) that it's easy to forget the output is used by people, and for some of them, one aria-label is the difference between finishing a task independently and giving up. Very few professions get such a direct, low-cost way to improve someone's day.

But intent alone doesn't scale: awareness fades, teams change, deadlines press. What scales is wiring that intent into the machinery: the linter, the test suite, the CI gate. When the tooling carries the message, remembering the users who aren't in the room stops depending on any individual's memory.

Here's how we did that, concretely, in a design system.

Why the design system is the leverage point

Accessibility bugs are the most expensive bugs you'll ever ship. Not because they're hard to fix, but because of where they live. A missing aria-label in a product feature affects one screen. The same defect in a design system's Button component affects every screen in every product that consumes it.

That's the bad news. The good news is the inverse is also true: the design system is the single highest-leverage place to enforce accessibility. Fix it once, and every consumer inherits the fix. Test it once, and every consumer inherits the guarantee.

This post walks through a layered, automated accessibility testing strategy we implemented in a component library monorepo: the tooling, the code, the gotchas, and the rollout strategy that kept us from blocking every PR on day one.

Why "just be careful" doesn't work

Without a codified standard, every team makes its own calls on ARIA attributes, color contrast, focus management, and keyboard navigation. The results are predictably inconsistent:

One team's modal traps focus; another's doesn't.
One dropdown is a proper listbox; another is a pile of clickable divs.
Contrast ratios drift as designers tweak tokens without running the numbers. Beyond the degraded experience for anyone using assistive technology, there's real legal exposure. Depending on your market, you may be subject to the ADA (US), AODA (Ontario), EN 301 549 (EU), or similar legislation, most of which anchor to WCAG as the technical standard. Manual audits catch problems after they ship; automation catches them before they merge.

No single tool covers everything, so we layered four:

Layer	Tool	When it runs
Static / lint	`eslint-plugin-jsx-a11y`	Every save & CI lint job
Unit / integration	`vitest` + `axe-core`	Every test run & CI
Visual / interaction	`@storybook/addon-a11y`	Storybook CI build
CI gate	Dedicated workflow	Every PR, blocks merge

Each layer catches a class of defect the previous one can't. Let's go through them.

Layer 1: Static analysis with `eslint-plugin-jsx-a11y`

The cheapest place to catch a defect is in the editor, before the code is even saved. eslint-plugin-jsx-a11y statically analyzes JSX and flags a surprising number of issues: missing alt text, invalid ARIA attributes, click handlers on non-interactive elements, and so on.

Use the strict preset. The recommended preset downgrades several rules to warnings, and warnings are noise that everyone learns to ignore.

// eslint.config.js (the idea, not the full config)
rules: {
  ...jsxA11y.flatConfigs.strict.rules,
  // escalate anything strict still leaves as a warning
  'jsx-a11y/no-autofocus': 'error',
}

What it catches:

// ❌ Lint error: click handler on a non-interactive element
<div onClick={handleSelect}>Select plan</div>

// ✅ Interactive semantics come for free with the right element
<button type="button" onClick={handleSelect}>Select plan</button>

What it can't catch: anything that only exists at runtime: computed ARIA states, focus order, contrast, or how components compose together. For that, we need the DOM.

Layer 2: Unit tests with axe-core

axe-core is the de facto standard accessibility rules engine. Running it against rendered components in your unit test suite means every component gets scanned on every test run, with zero extra CI plumbing.

The key to making this sustainable is a shared helper so every test looks identical. Ours renders the component, runs axe, and exposes both the scan results and the usual testing-library queries:

// test-utils/renderA11y.tsx (sketch)
export async function renderA11y(ui: ReactElement) {
  const result = render(ui);
  const axeResults = await axe.run(result.container, {
    runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'] },
  });
  return { ...result, axeResults };
}

Pair it with an assertion helper (an expectNoViolations(axeResults)) that formats violations into readable strings before asserting. That detail matters more than it looks: when a test fails, the developer should see which rule, which node, and what HTML, not an opaque object diff.

Every component then gets a co-located *.a11y.test.tsx file:

// Switch.a11y.test.tsx (the shape of every such file)
it('has no axe violations', async () => {
  const { axeResults } = await renderA11y(<Switch label="Enable notifications" />);
  expectNoViolations(axeResults);
});

// ...plus targeted checks: aria state exposed to AT, keyboard operability, focus

Beyond the axe scan, add a few targeted assertions per component: the ARIA state is exposed (aria-checked on a switch), it's reachable by Tab, and it's operable by keyboard (Space/Enter toggles it).

Two practical notes:

Test meaningful states, not just the default render. An accordion that passes axe while collapsed can still fail when expanded. Scan open modals, expanded menus, error states, and disabled states.

Enforce the convention structurally. A rule that lives only in a wiki dies in a wiki. We enforce the co-located test file two ways: it's a line item on the PR contribution checklist, and our component scaffolding (a plop generator) creates the *.a11y.test.tsx file automatically for every new component. The path of least resistance is the compliant path.

The jsdom gotcha: no contrast checking

Here's the trap that catches almost everyone: axe-core running in jsdom cannot detect color-contrast violations. jsdom doesn't implement a CSS layout engine or Canvas, so axe has no way to compute foreground/background colors. The color-contrast rule silently reports "incomplete" rather than failing.

If your only accessibility testing is axe-in-jsdom, you have a false sense of security about the single most common WCAG failure on the web. Contrast requires a real browser, which brings us to layer 3.

Layer 3: Storybook as a browser-based scanner

If you maintain a design system, you almost certainly already have Storybook, and every component already has stories covering its visual states. @storybook/addon-a11y runs axe against each story in a real browser, which means contrast checks actually work.

Wire it globally in preview.tsx so every story is scanned by default. Three decisions matter here, not the boilerplate:

// preview.tsx -> parameters.a11y (the decisions that matter)
{
  options: { runOnly: { type: 'tag', values: [/* your WCAG target tags */] } },
  test: 'error', // fail the story in test runs, don't just warn
}

That is: pin the run config to your WCAG target so Storybook and unit tests check the same standard, set it once globally rather than per story, and use 'error' so violations fail rather than warn.

Making suppressions traceable

Sometimes a story legitimately needs to skip the scan: a deliberately broken example in documentation, or a known issue with a fix scheduled. The failure mode to avoid is the silent, permanent suppression that nobody remembers adding.

Our rule: you can suppress a scan, but only with a ticket attached. The helper throws at runtime if the ticket reference doesn't match your tracker's key format:

// a11yException (sketch): a suppression is only valid with a ticket attached
export function a11yException({ ticket, reason }: { ticket: string; reason?: string }) {
  if (!TICKET_PATTERN.test(ticket)) throw new Error('suppression must reference a tracked issue');
  return { a11y: { disable: true, description: `disabled: ${ticket}` } };
}

// usage in a story
parameters: a11yException({ ticket: 'DS-421', reason: 'fails contrast pending token audit' })

This turns suppressions from invisible debt into a queryable backlog: grep for a11yException and you have your remediation list, each entry pointing at a live ticket.

Layer 4: The CI gate, and why we didn't turn it on immediately

The final layer is a dedicated CI workflow that blocks merge on any violation:

# a11y.yml (the essential shape)
on: pull_request
jobs:
  storybook-a11y:
    steps:
      # checkout, node, install...
      - run: pnpm --filter storybook build
      - run: pnpm --filter storybook test-storybook --ci  # axe against every story

Note the division of labor: the axe unit tests already run in the main CI pipeline alongside everything else (turbo test picks them up like any other test file, no special workflow needed). The dedicated workflow exists specifically for the browser-based Storybook scan, because that's the only place contrast and interaction rules can run.

The rollout trap: don't gate before you audit

Here's the strategic decision that saved us weeks of pain. Flipping the CI gate on is trivial; the question is when.

If your color tokens haven't been audited against your contrast target, activating a browser-based contrast gate means every PR that touches a colored component fails, through no fault of the PR author. Nothing kills a quality initiative faster than a gate the team perceives as arbitrary and unfixable at the PR level.

So we phased it:

Phase 1. Ship the lint rules and axe unit tests. These fail only on defects a developer can actually fix in their PR. Zero contrast rules, zero unfair failures.
Phase 1b. Ship the Storybook addon in report mode. Violations are visible in the Storybook UI and in CI logs, building awareness without blocking anyone.
Token audit. Run every color token pair through a contrast checker against your target ratio. Fix the tokens at the token level, so one fix propagates everywhere.
Phase 2. Only after the audit is green, flip the workflow to blocking. Now every failure is a genuine regression, and the gate has credibility. The sequencing principle generalizes: automated gates should only fail on things the person seeing the failure can fix. Systemic debt gets fixed systemically, then the gate protects the clean state.

Choosing a target: AA required, AAA where it's cheap

WCAG 2.2 AA is the right baseline: it's what most legislation references, and it's achievable for every component. We additionally target AAA color contrast (7:1) and enhanced focus indicators where the design tokens allow, for a simple reason: contrast is decided once, centrally, in the token palette. If your foundation tokens can clear 7:1, every consumer gets AAA contrast for free, and you've built headroom against future tightening of standards. Where AAA would force genuinely worse design trade-offs, AA stands.

A side benefit: accessibility tests audit your types

An unexpected payoff from writing an axe test for every existing component: the process surfaced several prop-type gaps that had been silently reducing type safety: a component whose props type omitted children even though it rendered them, another missing its onChange in the public type, a generic defaulting to an empty record. Writing tests that exercise components the way real consumers do is a forcing function that shakes these out. Log them as they surface; each one is coverage fidelity you're currently losing.

The takeaway

No single tool gives you accessibility coverage. The layers compose:

Lint catches structural mistakes at author time, for free.
axe unit tests catch runtime ARIA and semantics defects on every test run, but cannot check contrast in jsdom.
Storybook + addon-a11y runs axe in a real browser, closing the contrast gap using stories you already have.
A blocking CI gate makes the standard non-optional, but only flip it on after you've audited the systemic debt it would surface. And thread traceability through all of it: every suppression carries a ticket, every new component scaffolds its own test, every convention is enforced by tooling rather than memory. The design system is where accessibility leverage lives: instrument it once, and every product you ship inherits the guarantee.

I still think about that conversation. As a dev, you can actually make someone's life better. Don't forget this. And so you can't forget it, encode it into the pipeline: then the reminder arrives on every save, every test run, every pull request.

CRM data, Service Adapter and Integration Contract

DimiDan — Mon, 03 Aug 2026 19:46:38 +0000

You've got one CRM integration in production and it's been fine for months. Now there's a second one to wire up. Same contract, same schema, same node shape. Should be a couple of days.

You pull the first payload from CRM B and put it next to CRM A out of habit.

CRM A, a monetary field:

{ "key": "estimated_cost", "value": 1275.43, "spec": { "type": "number", "format": "decimal" } }

CRM B, same kind of field:

{ "key": "amount", "value": "6624", "spec": { "type": "number" } }

Huh.

One's a JSON number. One's a string. One tags the format, one doesn't. Both say "type": "number". And every validator between those adapters and your UI is perfectly happy with both.

So what's the issue

This is the part that takes a minute to sit with. You go looking for who got it wrong, and nobody did.

Go read the contract. It says there's a field called value. That's it. It never said what could go in value. So the person building CRM A looked at a number and sent a number. The person building CRM B looked at the same thing and sent a string, probably because that CRM's own API hands back strings. Both reasonable. Both shipped. Both correct against the spec as written.

The contract wasn't violated. It just didn't have an opinion, and two people filled the silence differently.

That's the whole category of problem I want to talk about, because it doesn't show up in code review and it doesn't show up in CI. It shows up eight months later when someone asks why one CRM's totals are off by a cent.

The good idea underneath

Before piling on, credit where it's due, because the foundation here is right.

Every source produces the same node. Consumers never branch on where the data came from.

type FieldNode = {
  key: string
  label: string
  value: ???
  spec: ???
  treePath: string
  children: FieldNode[]
}

One shape, one tree, one set of consumers. Adding a CRM is adapter work and nothing above the boundary moves. This genuinely scales, and if you're designing this today, start here.

But notice what it does to your risk. Two fields carry all the meaning — value and spec. The rest is plumbing. Leave those two vague and the uniformity is a paint job.

Rule 1: name the field, then actually say what goes in it

Here's the type that caused everything above:

value: string | number | null

Looks like a decision. Isn't one. It's a union that permits both answers, which means you'll get both answers the moment two adapters get written in parallel by people who never talk.

So say the thing:

value is a decimal string, or null. Never a JSON number.
Containers (array, object) carry null.
Numeric nodes carry a format.
format: 'money' also carries currency, ISO 4217.

That last one isn't bureaucracy. format: 'decimal' can't tell a cost from a tax rate. They're both decimals. Only the source system knows which one is money, and that fact turns out to constrain your whole architecture. Hold that thought for Rule 3.

And if you're about to argue you don't need strings because you're not doing currency math: value: number still eats integers past 2^53, which is where record IDs live. It mangles anything past 15 significant digits. It'll hand you 1e+21 when you least want it. A decimal string has none of those problems and costs you nothing.

Rule 2: shut the door on undeclared fields

Here's the sequel to the story, and it's more common than the first part.

CRM A's adapter stamps format: "decimal" on every numeric field. Handy. Consumers start reading it. Someone builds a formatting rule on top of it.

Except format was never declared in the schema. It's just riding along in the payload — invisible to validation, missing from your generated client types, guaranteed by nobody. And CRM B doesn't send it at all, so the formatting rule works for half your customers.

Whatever flavor you get, it's one bug: data present, schema silent.

One flag closes the whole category. additionalProperties: false in OpenAPI, .strict() in zod, whatever yours is called. Undeclared fields stop being possible. Everything else you do about this is whack-a-mole.

Fair warning: turning it on will break things that currently work, because at least one of those undeclared fields is load-bearing somewhere. That's not a reason to skip it. The dependency was already there — you just couldn't see it.

Rule 3: the normalization layer can't save you

Okay, so the obvious fix. Build a normalization layer. One place that takes whatever each adapter produces and forces it into canonical form. Money becomes a decimal string, numerics get a format tag, everyone goes home.

You do need that layer. It also can't do the job on its own, and this is the bit I'd most want to hand to past-me.

Picture a money field whose true value is 450.20.

Adapter one does JSON.parse on the CRM response. The value lands in a float64, comes back out as "450.2". Normalization checks it: it's a string, it matches a decimal literal, format's present. Passes.
Adapter two reads the response as text and never touches a float. Emits "450.20". Normalization checks it. Passes, identically.

Your layer cannot tell these apart. Both are well-formed strings. One of them quietly threw information away, and no amount of schema work will catch it, because a validator can only confirm the shape of what you handed it. It can't reconstruct what got dropped before it ever saw the data.

So this isn't one boundary. It's two, doing different jobs:

Boundary	Job	Why it can't fold into the other
Read-time — inside each adapter	Decode source numerics as text. `json.Number` in Go, a reviver in JS, never bare `JSON.parse`. Tag `format` and `currency` from provider field metadata — HubSpot's Properties API, Salesforce `describe()`.	It's the only layer that touches the raw HTTP response. Precision lives or dies here and nowhere else. It's also the only place that knows `Amount` is money and `source_user_id` isn't.
Enforcement — the shared service	Strict schema. Validate your own output. Fail closed. Derive `format` when an adapter didn't send one. Own the spec.	It's the only layer that sees every adapter side by side. One stamping `format` while another skips it is completely invisible from inside either adapter.

Read-time on its own is just a promise everyone makes and nobody keeps, because "be careful with floats" isn't a mechanism. Enforcement on its own validates already-damaged data and hands you a green checkmark.

If you keep one line from this post: the guarantee gets created upstream of where it gets checked. Any design that stuffs all the normalization into one shared service has a hole in it that more schema won't fill.

This is also, incidentally, why "which service owns this fix?" can sit open in a doc for weeks. Every answer is partly right and none of them is enough. When that happens, the question is usually the problem. This one quietly assumed there was one owner.

Rule 4: the mapper that quietly eats your fields

Different failure, same silence.

Early on, your wire type and your domain type are the same type. The only mapper that compiles is a spread:

fields.map(f => ({ ...f, label: f.display_label }))

Nothing can go missing. Not because anyone's being careful — because there's no other way to write it.

Then the domain type picks up something the wire doesn't have. A render hint, say, or a UI kind. Perfectly reasonable in isolation. But now the two types have forked, so you need a translation function, and a translation function is a list of fields:

const map = (f: ApiField): FieldNode => ({
  key: f.key,
  label: f.display_label,
  type: f.children?.length ? 'group' : 'leaf',
  value: String(f.value),
  treePath: f.path,
  children: f.children?.map(map) ?? [],
})

Whatever isn't on that list is gone. Including every field anyone adds to the contract next quarter. And you won't catch it in review, because that mapper is correct for the types it was handed.

Derive the domain type from the wire type instead, and forgetting a field becomes a compile error:

type FieldNode = Omit<WireField, 'display_label'> & { label: string }

Worth saying the other half too: the spread version preserved fields by being transparent, not by being right. It happily carried undeclared junk along with everything else, which is Rule 2's problem wearing a different hat. You want both halves. Parse strictly, then pass through.

Rule 5: don't add a second way to say what something is

Tempting move: put a declared "kind" field next to your structural type. spec.type plus tree position already tells you everything behavioral — expandable, container, nested — but a kind field feels more explicit, so it goes in.

Two things go wrong. It drifts from the structure it's supposed to describe, which is the boring failure. And it tends to land on a property name the wire already uses for something else. Look at type in that mapper above: it's the UI kind in the domain type and the source record type on the wire. That collision is exactly what forced the field-enumerating translation in Rule 4.

Cheap thing to try on your own code right now: for every enum on a core domain type, grep for reads of each member. The ones that get written and never read are telling you the type is carrying a distinction nothing actually needs.

The schema - what it should enforce

value never gets coerced. z.coerce.string() would quietly accept a raw number and enforce absolutely nothing. You want a bad value to fail, not get tidied up behind your back.

The decimal-literal regex is your precision tripwire. Anything that went through a float and back emits exponent notation at large magnitudes, and 1e+21 doesn't match. It only catches the loud cases. The quiet ones are Rule 3's job.

spec is required. Optional-chaining a discriminator is itself the bug. spec?.type makes "field missing" and "value unknown" look identical, and both slide into the same default branch.

currency sits next to format, not inside it. Rule 1's point: only the source system knows which decimals are money, so that tag has to be born at read time.

Where to actually enforce this

Writing the schema is the easy part. Where you run it decides whether it does anything.

The producer validates its own output. Your shared service checks its response before sending and fails closed. Skip this and consumer-side validation just turns a silent bug into a loud one, later, in somebody else's service, at 2am.

The consumer parses at the boundary, per node. A recursive strict schema blows up the entire tree over one malformed grandchild, which means a whole panel disappears because of one bad leaf. Walk the tree, validate node by node, keep the bad ones and mark them unavailable, and report them. Silently dropping them is its own kind of lie — the user just sees a shorter list and no explanation.

And know what none of this covers. A perfectly-shaped value that lost precision upstream passes every check on that list. The read-time boundary needs a shared decode helper and human review, not a test. Fixture-based tests have a cousin of the same blind spot: they'll stay green while the same code fails on the live route, because your fixtures carry fields the real projection drops. Make at least one test exercise the projection itself.

The short version

For every field in your contract: is the content specified, or just the name? A union that permits two encodings is an unspecified field wearing a type annotation.
Is additionalProperties: false on? If not, you have undeclared fields in production right now, and one of them matters.
Where does precision get created versus checked? Different layers means your validator can't verify the thing it looks like it's verifying.
Does any mapper enumerate fields? It's dropping something today and it'll drop everything you add tomorrow.
Does the producer validate its own output, or only the consumer?
Which members of your core enums actually get read?

A contract isn't the fields you named. It's the behaviors you made impossible.

Feels like a feature until it's infrastructure

DimiDan — Mon, 27 Jul 2026 16:01:18 +0000

A while ago I wrote about pricing logic and why it deserves to be treated as infrastructure instead of a pile of UI code. This is the same lesson from a different subsystem: undo/redo in a real-time, event-driven editor. The difference is that this time the payoff is visible, and it showed up a year later in a place we weren't looking.

Features and invariants are different objects

Features have a definition of done you can see. Ship the button, click the button, close the ticket. When a feature half-works, someone notices, because the feature is the thing people look at.

Infrastructure is different. Its job is to hold invariants that other code relies on. For undo/redo the invariant is brutal: every state mutation, from every code path, present and future, must be reversible in chronological order. That invariant doesn't live in any one component. You can't screenshot it. When it erodes, it erodes silently, one unmigrated code path at a time.

Pricing had the same shape. The invariant there was "money math is exact and happens in exactly one place." Every shortcut that looked harmless locally — a parseFloat here, a float multiplication there — chipped at an invariant nobody owned. It was boring until it was wrong.

The thing that decides whether you get this right is a question asked early: is this a feature, or is it infrastructure wearing a feature costume?

The tell: closures vs commands

You can often tell which mental model produced a piece of code by looking at what the abstraction knows about itself.

The obvious way to build undo support is callbacks. Every widget that wants to participate registers a pair of closures: here's how to undo me, here's how to redo me. It works, and it's the version most editors start with.

The problem is that a callback-based undo entry knows nothing. It's two anonymous closures. You can't ask it what it does, which block it touches, whether it succeeded, or when it happened. You can only fire it and hope. Debugging means reading captured variables in a debugger. Testing means reconstructing the exact closure environment.

The command version is self-describing:

class DeleteBlockCommand {
  readonly scope = 'block';
  readonly timestamp: string;
  getCurrentBlockId(): string;
  async undo(): Promise<boolean>;
  async redo(): Promise<boolean>;
}

That difference looks cosmetic. It is not. Because commands carry identity, the system built on them can do things the closure version never could:

One chronological stack across text edits, block moves, and table changes, because everything is comparable.
Retry and failure semantics, because undo() returns a result instead of throwing into the void.
Batching, because commands compose.
Analytics at a handful of seams instead of everywhere.

When architecture pays off

That last bullet deserves its own section, because it's where the decision paid for itself.

When we wrote the RFC for the command architecture, one of its stated purposes was to reify editor actions as discrete, self-describing objects. Text edit, block move, style change, table mutation — each one individually addressable, with its own scope, timestamp, payload, and success or failure resolution, all landing on one chronological stack. Granular, per-event control over what happens in the editor. The justification at the time was correctness: reliable undo, reliable ordering, reliable failure handling.

Then product came asking for interaction tracking. Which actions do users perform, how often, in what order.

Look at what an analytics event needs: a name, a subject, a timestamp, structured properties, and confirmation that the thing actually happened. That is a command object. The grain analytics needed was the grain the architecture already had.

Without the command layer, per-action tracking means scattering emit calls across dozens of UI components and hoping every future component remembers to do the same. It also means every one of those call sites independently deciding what counts as success, which in practice means some of them fire on intent rather than outcome and your funnel quietly overcounts.

With the command layer, tracking attaches at a handful of well-defined seams and inherits success-gating for free. No event fires for an action that failed or got rejected, because the command already had to know the difference in order to be undoable.

We didn't design the command pattern for Mixpanel. We designed it for control over events, and analytics turned out to be just another consumer of that control. That's the signature of an infrastructure decision: consumers it wasn't designed for show up later and find what they need already there.

How to spot infrastructure wearing a feature costume

Four questions that would have flagged both pricing and undo/redo early:

Does it cut across features? If every new widget has to remember to participate, it's infrastructure, and "remember to" is not a mechanism.
Does it fail silently? Features fail loudly, in someone's face. Invariants fail quietly, in aggregate, and the first report is a metric that looks slightly off.
Is correctness invisible? If you can't tell it's broken by looking at the screen, you need the architecture to make wrongness impossible, not code review to catch it.
Is "mostly done" meaningfully different from done? For a feature, eighty percent shipped is roughly eighty percent of the value. For an invariant it's zero: a single unmigrated code path is enough to make the guarantee untrue, and untrue guarantees are worse than absent ones because everything downstream is built on them.

The uncomfortable part is that infrastructure decisions are hard to justify during planning, because the strongest argument for one is a consumer you can't name yet. You're asking for extra work now against a payoff you can only describe in the abstract.

A year later, ours had a name.

Claude Code, Bun and TypeScript

DimiDan — Mon, 27 Jul 2026 12:50:21 +0000

Why Claude Code runs on Bun: runtime tradeoffs in TypeScript CLI tooling

Anthropic recently shipped Claude Code — their agentic CLI coding assistant — on Bun instead of Node.js. For most product announcements, the runtime choice would be a footnote. Here it's worth unpacking, because the tradeoffs Anthropic navigated are exactly the ones you hit when building or evaluating TypeScript-heavy developer tooling: startup latency, bundling strategy, native module compatibility, and what "good enough" dependency management actually looks like in 2025.

This isn't a Bun vs. Node benchmarking post. It's an examination of why the decision makes sense for a CLI tool specifically, what it signals about the broader ecosystem, and where the tradeoffs still bite you.

Why runtime choice matters more for CLIs than for servers

For a long-running server process, Node.js startup cost of 50–150ms is irrelevant — you pay it once. For a CLI invoked dozens of times per development session, cold-start latency is a first-class UX concern.

Bun's startup time is consistently in the 5–15ms range for a simple script. Node.js lands closer to 50–80ms before your first line of application code runs. That delta is imperceptible in a single invocation. Run a CLI 30 times in a session and you've saved a couple of seconds — more importantly, you've removed the subjective sense of lag that makes a tool feel heavy.

This is the same reason Deno has gained traction in scripting contexts despite losing the server-side battle to Node. Fast startup is a feature, and for AI-assisted tooling where the human is waiting in a tight feedback loop, it matters.

Bun's bundler as a distribution primitive

Bun ships a first-party bundler. For a CLI, this is significant. The standard Node.js distribution story for a TypeScript CLI involves:

Compile TypeScript with tsc or esbuild
Bundle with esbuild or rollup to collapse the dependency graph
Either ship node_modules (large, fragile) or use a tool like pkg or nexe to produce a single executable
Handle platform-specific native binaries separately

Bun collapses steps 1–3 into a single command:

bun build ./src/index.ts --compile --outfile claude-code

The --compile flag produces a self-contained binary that embeds the Bun runtime. No Node.js installation required on the target machine. For a CLI distributed via npm (npm install -g @anthropic-ai/claude-code), this matters less — you can assume Node is present. But for future distribution channels (Homebrew, direct download, CI runner images), single-binary output is a meaningful operational simplification.

Bun's bundler also strips unused exports aggressively. A TypeScript codebase pulling in large SDKs — the Anthropic SDK, tree-sitter bindings, various language servers — can produce a substantially smaller artifact than a naive tsc + ship-everything approach.

The dependency management story is genuinely better

Bun's package manager is faster than npm by a wide margin — typically 10–25× on a cold install, faster still on cache hits. For a tool like Claude Code that's installed globally and occasionally updated, this shows up as a noticeably snappier install.

Bun uses a binary lockfile (bun.lockb) that's more compact and faster to parse than package-lock.json, but it's not human-readable. If you care about auditing lockfile diffs in code review, you'll need to run bun install --frozen-lockfile in CI and accept that the lockfile diff in your PR is opaque.

More substantively: Bun is node_modules-compatible. It doesn't invent a new module resolution scheme — your existing package.json works. Native modules compiled against Node's ABI mostly work, with exceptions for modules using non-public V8 internals. That's where the real compatibility risk sits.

Where native modules still cause pain

Bun uses JavaScriptCore (JSC) instead of V8. For pure JavaScript and TypeScript, this is transparent. For native addons compiled as .node files via node-gyp, the situation is more complicated.

Modules that use the Node-API (N-API) surface — the stable ABI layer introduced specifically for this kind of portability — generally work fine under Bun. Modules that reach into V8 internals or use older nan-based bindings may not.

For a coding assistant CLI, the relevant native dependencies are typically:

Tree-sitter language parsers (N-API based, generally fine)
OS keychain access (platform-specific, usually N-API)
File system watchers

Anthropic presumably validated these before shipping. But if you're evaluating Bun for your own TypeScript tooling and you depend on something like sharp, better-sqlite3, or canvas, verify native compatibility explicitly before committing.

// Quick compatibility check — run under both Bun and Node, compare output
import { createRequire } from 'module';
const require = createRequire(import.meta.url);

try {
  const nativeAddon = require('./build/Release/addon.node');
  console.log('Native addon loaded:', Object.keys(nativeAddon));
} catch (err) {
  console.error('Native addon failed:', (err as Error).message);
}

TypeScript ergonomics: where Bun earns its keep

Bun executes TypeScript directly without a compilation step — no ts-node, no tsx, no esbuild-register. You write a .ts file and run it:

bun run src/index.ts

This is not TypeScript type-checking. Bun strips types and runs the resulting JavaScript. But for iterating on tooling internals, removing the compilation step from the inner loop is a meaningful quality-of-life improvement.

For production builds of a distributed CLI, you still want tsc --noEmit as a type-check step in CI. The Bun model is: use JSC for fast execution, use TypeScript's type checker separately for correctness. These are separable concerns, and Bun's approach of not conflating them is arguably more honest than ts-node's.

A CI configuration that reflects this split:

jobs:
  build:
    steps:
      - name: Type check
        run: npx tsc --noEmit

      - name: Test
        run: bun test

      - name: Build binary
        run: bun build ./src/index.ts --compile --outfile dist/claude-code

What this signals for the TypeScript tooling ecosystem

The Claude Code runtime decision reflects a broader shift in how TypeScript-native tooling is evaluated. Two years ago, "build on Node.js" was the obvious default. Today, the question is more deliberate: what does this tool actually need from a runtime?

For CLIs and developer tools specifically, the evaluation matrix looks like:

Startup latency: Bun wins, meaningfully
TypeScript execution: Bun wins (no compilation step)
Native module compatibility: Node.js wins, but the gap is narrowing
Ecosystem breadth: Node.js wins (npm packages, community modules, established tooling)
Bundling and distribution: Bun wins for single-binary output
Long-running server processes: Roughly equivalent; Node.js has more production mileage

Anthropic's choice is defensible on every axis that matters for a CLI: fast startup, TypeScript-native execution, and streamlined distribution. The tradeoffs they accepted — opaque lockfiles, some native module risk — are manageable at their scale and usage pattern.

Practical takeaways if you're building TypeScript tooling

If you're maintaining or evaluating a TypeScript CLI or developer tool today:

Audit your native dependencies first. List every package that includes a .node binary. Check the Bun compatibility tracker or run bun install && bun run src/index.ts against your entry point and see what breaks. Native compatibility issues surface immediately.

Use Bun's test runner if you switch. bun test is Jest-compatible (it understands describe, it, expect) and significantly faster. It's the easiest win from a Bun migration.

Keep tsc --noEmit in CI regardless. Bun's type-stripping is not type-checking. Don't let the absence of a build step create a false sense of type safety. The type checker is a separate tool; treat it as one.

Single-binary output is worth evaluating seriously. If your CLI is distributed outside npm — as a GitHub release artifact, inside a Docker image, via Homebrew — bun build --compile simplifies your distribution pipeline in ways that matter operationally.

The broader lesson from Claude Code's stack choice is that runtime selection for TypeScript tooling is now a real engineering decision with real tradeoffs, not a default. Node.js is still the right answer for many contexts. For a fast, TypeScript-heavy CLI where startup latency and developer ergonomics are primary concerns, Bun is increasingly a serious contender — and Anthropic just made that case with a high-visibility production deployment.

React Server Components - The Mental Model Shift

DimiDan — Mon, 20 Jul 2026 14:22:05 +0000

React Server Components are not a performance trick. They are not a simpler way to do SSR. They represent a genuine renegotiation of where computation lives in a React application — and if you approach them as an incremental upgrade, you will architect yourself into corners that are painful to escape.

After working through RSC adoption in production Next.js applications, I want to lay out what actually changes at the architectural level: data fetching patterns, bundle composition, state management boundaries, and how teams need to think about component ownership.

How Shift did happened

Before RSC, the React component tree was a client-side concept. Server rendering was a serialization step — you ran the same component code on the server, emitted HTML, then React rehydrated it on the client. The component tree was fundamentally one thing that happened to run in two places.

RSC breaks this. The component tree now has two genuinely distinct zones with different capabilities, different execution environments, and a one-way data boundary between them. Server Components run exclusively on the server. They can access databases, filesystems, and secrets directly. They never ship to the browser. Client Components are the subset of your tree that runs in the browser — they receive serialized props from the server boundary and manage their own state and effects.

The key constraint is that this boundary is not symmetric. You can compose Client Components inside Server Components by passing them as props (including children). You cannot import a Client Component into a Server Component and expect it to remain a Client Component — it gets treated as a Server Component unless explicitly marked with 'use client'. And you cannot import a Server Component into a Client Component at all.

This asymmetry has real architectural consequences.

Data Fetching: Colocation at Scale

The most immediate change is to data fetching strategy. In a pre-RSC Next.js app, data fetching was pushed to page boundaries — getServerSideProps, getStaticProps, or client-side fetches with TanStack Query. Components deep in the tree couldn't fetch their own data without either prop-drilling from a page or reaching for a client-side solution.

RSC removes that constraint. A deeply nested Server Component can fetch exactly the data it needs:

// app/dashboard/RecentActivity.tsx
// No 'use client' directive — this is a Server Component

import { getRecentActivity } from '@/lib/db/activity';

interface Props {
  userId: string;
}

export async function RecentActivity({ userId }: Props) {
  const activity = await getRecentActivity(userId);

  return (
    <ul>
      {activity.map((item) => (
        <li key={item.id}>
          <span>{item.label}</span>
          <time dateTime={item.timestamp}>{formatRelative(item.timestamp)}</time>
        </li>
      ))}
    </ul>
  );
}

This is genuinely useful. Components declare their own data dependencies. There is no prop-drilling waterfall through parent components that don't need the data. React can parallelize sibling server fetches.

But colocation at this level has an architectural cost: it distributes data access logic across the component tree. In large codebases, this creates pressure toward duplicated query logic, inconsistent caching behavior, and data layer concerns bleeding into rendering concerns. The discipline that kept data fetching at page or feature boundaries was a forcing function for clean separation.

The practical answer is a service or repository layer that Server Components call into — not raw database queries inside JSX files. This is not a new idea, but RSC makes it newly necessary to enforce.

Bundle Optimization Is Now Structural

The bundle benefits of RSC are real but understated. It is not just that dependencies don't ship to the client. The server/client boundary is the module graph split point.

Consider a rich-text editor scenario. You have a document viewer that renders stored content, and a document editor that allows mutation. Pre-RSC, both likely live in the client bundle because rendering document content requires the same parser/renderer used for editing. With RSC, the viewer becomes a Server Component that runs the parser on the server and emits HTML. The editor, which genuinely needs client interactivity, is a Client Component. The parser library ships to zero browsers for the view-only case.

This pattern — server for read paths, client boundary for write and interactive paths — maps cleanly onto a lot of B2B SaaS product structures. Dashboards, reports, document feeds: mostly reads. Editors, forms, collaborative tools: require client boundaries.

What changes architecturally is that bundle composition is now a first-class design decision, not a post-hoc optimization. When you create a component, you are deciding which execution environment it belongs to. That decision needs to be visible in your component design conventions, code review checklists, and module organization.

State Management Boundaries

State management under RSC requires explicit rethinking, not just adaptation.

The instinct to reach for Zustand or Redux for shared state runs into a hard constraint: stores initialize and live in the Client Component subtree. Server Components cannot access them. This is correct behavior — but it means you need a clear model for what kind of state lives where.

URL state — search params, filters, pagination — becomes a first-class citizen. Server Components can read URL parameters directly and use them to parameterize data fetches. This moves a lot of state that previously lived in client stores back to the URL, which improves shareability and reduces client-side complexity.

// app/invoices/page.tsx
import { InvoiceList } from './InvoiceList';

interface SearchParams {
  status?: 'paid' | 'pending' | 'overdue';
  page?: string;
}

export default async function InvoicesPage({
  searchParams,
}: {
  searchParams: SearchParams;
}) {
  const status = searchParams.status ?? 'pending';
  const page = Number(searchParams.page ?? '1');

  return <InvoiceList status={status} page={page} />;
}

Server-owned state — user session, feature flags, tenant configuration — can be fetched once in a root Server Component and passed down as props, or accessed directly in any Server Component that needs it, without a context provider.

Client state remains appropriate for: ephemeral UI state (hover, focus, open/closed), optimistic updates, real-time collaboration state (Yjs documents, presence), and anything that responds to user input before a server round-trip.

The architectural mistake to avoid is treating the client state layer as a cache for server data. TanStack Query handles this well, but under RSC the primary data loading path moves to the server. Client-side query caches are better scoped to mutations, optimistic updates, and cases where you genuinely need background refetching without a navigation event.

The Client Boundary as an API Contract

Every 'use client' directive is an interface declaration. The props a Client Component accepts are serializable data flowing from the server domain into the client domain. This is a meaningful constraint: you cannot pass functions (unless they are Server Actions), class instances, or non-serializable objects across this boundary.

Architecturally, this forces clarity. When you design a Client Component, you are defining what the server needs to provide — the same problem as API design. What is the contract, and who owns the schema?

For complex components, this pushes toward explicit prop types that mirror your data model, rather than passing rich objects and picking fields inside the component:

// Clear boundary contract — serializable, explicit
interface DocumentCardProps {
  id: string;
  title: string;
  status: 'draft' | 'published' | 'archived';
  lastEditedAt: string; // ISO string, not Date — must be serializable
  collaboratorCount: number;
}

'use client';

export function DocumentCard({
  id,
  title,
  status,
  lastEditedAt,
  collaboratorCount,
}: DocumentCardProps) {
  // interactive behavior, local state, event handlers
}

This is good discipline regardless of RSC. But RSC turns violations into runtime errors rather than code smell.

Team and Collaboration Implications

At the team level, RSC introduces a new axis of component ownership: server versus client. In organizations where backend and frontend responsibilities overlap — product teams owning full features end-to-end — this is largely positive. Engineers can write data access directly without an API contract mediation step.

In organizations with stronger frontend/backend splits, it creates friction. Server Components that access databases or internal services blur the ownership model. You need explicit team agreements about what Server Components are allowed to call and where the service boundary sits.

RFC-driven engineering practices help here. Before RSC adoption, it is worth writing down:

Which data sources Server Components may access directly versus through an API layer
Conventions for when client boundaries should be introduced (interactive features, real-time state, third-party SDKs)
How Server Actions fit into your mutation story alongside existing API routes
Testing strategy — Server Components require different test infrastructure than Client Components

What This Is Not

RSC does not eliminate the need for a client-side data fetching library. TanStack Query remains the right tool for mutation state, optimistic updates, polling, and any data that needs to stay fresh without a navigation event.

RSC does not make SSR obsolete. Streaming SSR and RSC are complementary. Suspense boundaries work across both.

RSC does not simplify everything. The dual execution model adds cognitive overhead. Developers need to reason about which environment their code runs in, what is available there, and where the serialization boundary sits. That cost is real and needs to be weighed against the benefits for your specific application.

Where It Lands

RSC is the most significant change to React's execution model since hooks. It draws a clear line through the component tree and assigns different capabilities to each side. The teams that will benefit most are those building data-heavy, read-path-dominant applications — dashboards, document tools, B2B reporting surfaces — where the separation between "fetch and render" and "interact and mutate" maps cleanly to the server/client split.

The architectural work is not in learning the API. It is in auditing your existing component and data fetching patterns, defining clear conventions for boundary placement, and communicating those conventions to your team before the codebase drifts into inconsistency.

Done deliberately, RSC moves meaningful computation server-side in a way that is maintainable at scale. Done reactively, it produces a confusing mix of fetching strategies, inconsistent boundary placement, and components that are harder to reason about than what you had before.

The paradigm is sound. The architectural investment is on you.

A critical look at AI terminal coding Assistants

DimiDan — Mon, 20 Jul 2026 14:01:09 +0000

Every few weeks a new AI coding assistant lands on Hacker News with a wave of "this changes everything" comments. OpenCode is the latest terminal-first entry in this space, and the demo looks compelling. But after spending real time with it on a production TypeScript codebase, I want to offer something more useful than another glowing first-impression post: an honest accounting of where these tools help, where they hurt, and what the design decisions of tools like OpenCode reveal about the tradeoffs you're actually accepting.

This isn't a hit piece. It's the kind of evaluation I'd want before spending two weeks integrating a tool into my workflow.

What OpenCode Is Actually Doing

OpenCode is a terminal UI (TUI) coding assistant that wraps an LLM with file-system access, shell execution, and a diff-apply loop. You describe a change in natural language, it reads context from your repo, generates code, and applies it. The pitch is that it stays in the terminal where many engineers already live, avoiding the context-switch to a browser-based chat interface.

The core loop is:

You provide a prompt
The tool reads relevant files (via its own heuristics or your explicit direction)
The LLM generates a diff or full file replacement
OpenCode applies the change and optionally runs a verification command

This is not fundamentally different from what Aider, Claude Code, or Cursor's agent mode do. The differentiation is in the UX layer, the model routing, and the assumptions baked into the context-gathering step — and those assumptions are where things get interesting.

The Context Problem Is Not Solved

The most critical failure mode for any agentic coding tool is context selection. If the model doesn't see the right files, it will generate plausible-looking code that violates your actual constraints — wrong types, ignored abstractions, duplicated logic.

OpenCode, like its peers, uses a mix of:

Git history and file recency
Import graph traversal
Keyword and embedding similarity search
Whatever you explicitly paste in

The problem is that in a real TypeScript monorepo — a Turborepo setup with shared packages, for example — the most important constraints often live outside the file being edited. Your Zod schema in packages/validation, your design token types in packages/tokens, your shared component API in packages/ui. These are the files that determine whether the generated code is actually correct.

When I asked OpenCode to extend a form component, it generated perfectly valid TypeScript that was completely inconsistent with the validation schema the form was bound to. It looked right. It compiled. It was wrong.

// What OpenCode generated — valid TS, wrong contract
type FormValues = {
  email: string;
  role: string; // Should be constrained to z.enum(['admin', 'member', 'viewer'])
};

// What the actual Zod schema required
const formSchema = z.object({
  email: z.string().email(),
  role: z.enum(['admin', 'member', 'viewer']),
});

The tool didn't know about the schema because it wasn't imported in the component file — it was injected via a form context provider three layers up. This is a structural limitation. The import graph traversal is shallow, and the tool has no model of React's runtime dependency patterns.

The Trust Gradient Problem

Here's a subtler issue that doesn't get enough attention: AI coding tools create an uneven trust gradient that's dangerous for code review culture.

When a junior engineer writes code, experienced reviewers bring appropriate skepticism. When an AI tool produces a clean, well-formatted diff with a tidy commit message, it looks more authoritative than it is. I've watched PRs get merged faster when they're AI-assisted because the surface presentation is polished. That's backwards.

AI-generated code requires more scrutiny in specific areas, not less:

Edge case handling: LLMs optimize for the happy path
Security boundaries: Input validation, authorization checks, secrets handling
Performance characteristics: N+1 queries, unnecessary re-renders, missing memoization
Long-term maintainability: Generated code often solves the immediate problem in a way that accumulates tech debt

If your team hasn't explicitly recalibrated review standards for AI-assisted code, do that before adopting any of these tools at scale.

Where Terminal-First Actually Wins

There is genuine value here. Terminal-first AI assistants are meaningfully better than browser chat for a specific category of tasks: exploratory refactoring with tight feedback loops.

Tasks like:

Migrating from one API shape to another across 40 files
Applying a consistent pattern (logging, error boundaries, analytics events) across many components
Converting a class-based module to functional with a known target shape

For these, the apply-verify-iterate loop in a terminal tool is faster than copy-pasting between a chat window and your editor. You stay in one context. You can run your test suite as the verification step. You see diffs without context-switching.

# This kind of workflow works well
opencode "Find all fetch() calls in src/ and wrap them with our
  httpClient utility from lib/http-client.ts, preserving error handling"

# Run tests as verification
npm test -- --watch=false

For mechanical, well-defined transformations with a narrow constraint space, these tools earn their keep.

The Autonomy Dial Is Set Wrong

Most of these tools default to too much autonomy. OpenCode will, by default, apply changes without a confirmation step if a verification command is configured and passes. That sounds reasonable until your verification command is npm run build and the generated code introduces a subtle runtime bug that doesn't surface at build time.

The right default is more conservative: show the diff, wait for approval, then apply. Autonomy should be opt-in per task, not a global opt-out. The tools that get this right — Cursor's agent mode with explicit step approval, Claude Code with its default confirmation prompts — feel fundamentally safer on anything touching production paths.

If you're evaluating OpenCode or similar tools, check the default autonomy settings before you start. Understand exactly what --auto-apply and equivalent flags are doing.

What a Staff Engineer Actually Wants From These Tools

After using several of these tools across real projects, here's what actually matters:

Respects existing conventions. The tool should read your ESLint config, your component patterns, your naming conventions — and follow them without being told explicitly every time. Most tools do this poorly.

Understands project-specific abstractions. If you have a useFormField hook or a DataTable component, the tool should use them, not generate a new implementation from scratch.

Doesn't hide complexity. Generated code should be readable and auditable. A clever solution that works but is hard to reason about is not a win.

Fails loudly, not silently. If the tool can't gather enough context to be confident, it should say so. Hallucinated-but-plausible code is worse than an honest "I don't have enough context for this."

Integrates with your existing feedback loop. Your test suite, your type checker, your linter — not a parallel system.

OpenCode scores well on the last point and poorly on the first two.

The Honest Verdict

OpenCode is a competent implementation of a tool category that is genuinely useful for a subset of tasks. It's not a reason to overhaul your primary workflow, and it's not a substitute for understanding your codebase.

Engineers who get real value from tools like this treat them as accelerators for well-scoped, mechanical work — not as autonomous collaborators on design decisions. The engineers who get burned are the ones who trust the polish of the output over the quality of the reasoning behind it.

Before adopting any AI coding assistant on a production team, answer these questions:

What is the verification gate before AI-generated code merges?
Have we updated code review expectations explicitly?
Do we have a clear list of task types where we won't use AI assistance — auth flows, payment logic, data migrations?
Can the tool understand our project-specific abstractions, or will it work against them?

If you can't answer those confidently, the tool will make things slower, not faster.

The promise of AI coding assistants is real. The current implementations require more critical evaluation than they typically receive.

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

DimiDan — Mon, 20 Jul 2026 13:58:44 +0000

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

A recent thread hit 482 points and 312 comments on the claim that GPT-5 has made meaningful progress on convex optimization problems that have been largely intractable for thirty years. The reaction split cleanly: researchers excited about specific benchmark results, engineers skeptical about practical implications, and a third camp arguing the framing was misleading from the start.

All three groups have valid points. Here's an attempt to untangle them.

What Convex Optimization Actually Is (And Why It's Everywhere)

Convex optimization is the class of problems where you minimize a convex function over a convex set. The key property: any local minimum is a global minimum. That makes convex problems tractable in a way that general optimization problems are not.

This shows up constantly in engineering infrastructure:

ML training — loss surfaces are often non-convex, but large subproblems (SVM training, certain regularization schemes) are convex and solved with specialized solvers like CVXPY or Gurobi
Compiler backends — register allocation and instruction scheduling have convex relaxations that inform heuristics
Resource allocation — cloud schedulers, network routing, and capacity planning often reduce to linear or quadratic programs
Financial modeling — portfolio optimization under constraints is a textbook convex problem

The "30-year gap" framing refers to open problems around scalability and solver efficiency — specifically, the gap between what interior-point methods can handle in theory and what's practical at production scale.

Solvers like MOSEK and SCS are excellent. They're also slow at scale, sensitive to problem conditioning, and require expert formulation. That last point is the friction that actually matters for engineering teams.

What the GPT-5 Results Actually Show

The specific claims center on GPT-5's ability to:

Correctly formulate optimization problems from natural-language descriptions
Identify when a problem has convex structure that allows efficient solving
Generate CVXPY or similar solver code that compiles and runs correctly
In some benchmarks, suggest reformulations that meaningfully improve solver performance

This is not "GPT-5 solved convex optimization." It's closer to: GPT-5 has become a competent co-pilot for the formulation step, which is where most engineering time actually goes.

To make this concrete — if you're building a job scheduler and need to minimize total latency subject to resource constraints, writing that as a proper LP or QP has always required knowing the vocabulary: decision variables, objective function, constraint matrices. That knowledge barrier is real. Most backend engineers reach for heuristics not because an optimal formulation wouldn't be better, but because they don't want to spend three days reading Boyd and Vandenberghe.

# What you used to need domain knowledge to write:
import cvxpy as cp
import numpy as np

# Job scheduling: minimize makespan across n jobs, m machines
n_jobs, n_machines = 10, 3
processing_times = np.random.randint(1, 10, (n_jobs, n_machines))

x = cp.Variable((n_jobs, n_machines), boolean=True)
makespan = cp.Variable()

constraints = [
    cp.sum(x, axis=1) == 1,  # each job assigned to exactly one machine
    makespan >= cp.sum(cp.multiply(processing_times, x), axis=0)
]

objective = cp.Minimize(makespan)
problem = cp.Problem(objective, constraints)
problem.solve()

GPT-5 can now generate that correctly from a plain-English description of the scheduling problem. More importantly, it can flag when you've accidentally written a non-convex constraint that will cause the solver to fail silently or return garbage.

The Skepticism in the Thread Is Legitimate

The 312-comment thread wasn't just noise. The pushback clustered around several real concerns.

"Benchmark performance doesn't transfer to production problems." True. The benchmarks use well-conditioned, textbook-scale problems. Real scheduling problems have messy side constraints, integer variables, and numerical conditioning issues that stress even expert formulations. GPT-5 generating plausible-looking CVXPY code is not the same as that code solving your actual problem.

"This conflates formulation assistance with algorithmic progress." Also true. The headline "closing a 30-year gap" implies progress on solver algorithms — faster interior-point methods, better preconditioning, novel dual decompositions. That's not what's being described. What's being described is better tooling around using existing solvers. Valuable, but a different category of claim.

"LLMs hallucinate constraints." This is the one that should give you pause before deploying any of this. GPT-4 can generate convex-looking constraint sets that are subtly non-convex — the kind of error that doesn't throw an exception, but silently returns a wrong answer. GPT-5 is better at catching these, but "better" doesn't mean "safe to run unsupervised in a production resource allocator."

The honest framing: this is a significant improvement in the accessibility of optimization tooling, not a breakthrough in optimization theory.

What This Actually Changes for Engineering Teams

If you're building backend infrastructure, developer tooling, or any system that currently uses heuristics because "setting up a proper solver seemed like too much work," the calculus has shifted.

The formulation barrier is lower. You can describe your problem in prose, get a working CVXPY sketch, and iterate from there. That's genuinely useful even if you still need to validate the output carefully.

Debugging solver failures is faster. Infeasibility and numerical issues in optimization problems have always been hard to diagnose. Having a model that can look at your problem and say "this constraint is likely causing infeasibility because X" cuts debugging time substantially.

The integration surface with existing infrastructure is unchanged. CVXPY still calls MOSEK or SCS. Solver performance characteristics are the same. If your problem is too large for current solvers, GPT-5 doesn't fix that. You still need decomposition, approximation, or a different approach.

For teams building scheduling systems, ML infrastructure, or resource allocation layers — say, a Node.js/TypeScript backend calling out to a Python optimization service — the practical win is in prototyping speed and reducing the expertise required to reach a working formulation.

// A backend service that now has a shorter path to proper optimization
// instead of a hand-rolled heuristic
async function scheduleJobs(jobs: Job[], machines: Machine[]): Promise<Assignment[]> {
  // Previously: greedy heuristic because writing the LP felt like too much
  // Now: call a Python optimization service with a properly formulated problem
  // generated and validated with AI assistance
  const formulation = await optimizationService.solve({
    type: 'linear_program',
    objective: 'minimize_makespan',
    jobs,
    machines,
  });
  return formulation.assignments;
}

Where to Be Careful

A few concrete cautions before building this into critical infrastructure.

Always verify the problem class. If the model says your problem is convex, check it. A non-convex problem handed to a convex solver will either fail noisily or return a locally optimal point far from the global optimum. In a scheduler or resource allocator, that has real consequences.

Numerical conditioning still requires human attention. LLMs generate well-scaled constraint matrices for textbook problems. Your production problem has characteristics the model hasn't seen. Check condition numbers. Know your solver's tolerance settings.

Don't skip domain expert review. The formulation step is where domain knowledge matters most — not just mathematical correctness, but whether the optimization objective actually captures what you care about. GPT-5 can give you a mathematically valid LP that optimizes the wrong thing because it misunderstood a business constraint.

The Actual Opportunity

The real engineering opportunity here isn't "replace your solver with GPT-5." It's closer to: a class of infrastructure problems previously gated behind specialized knowledge is now more accessible to generalist engineers.

That has compounding effects. Teams that previously used greedy heuristics because the optimization setup cost was too high can now prototype proper formulations. Those prototypes, even if they need expert refinement, start from a better place than a hand-rolled approximation.

For developer tooling specifically — compilers, build systems, deployment schedulers — this opens up experimentation with optimization-based approaches that teams routinely deprioritized because of implementation cost.

The 30-year gap in optimization theory hasn't closed. But the gap between optimization theory and something an engineering team can actually use got meaningfully smaller. That's a more modest claim than the headline suggested — but it's a real one, and it's worth taking seriously.

Fintech Frontend Engineering and Financial Services

DimiDan — Sat, 27 Jun 2026 20:10:21 +0000

Most frontend engineers entering fintech underestimate how much the domain changes what good looks like. It's not just stricter security requirements or more complex forms. The regulatory, compliance, and payments context fundamentally reshapes how you architect UI, how you reason about state, how you handle errors, and what "done" means.

This post is a reference for frontend engineers — particularly those operating at staff level, where you're expected to contribute credibly beyond UI concerns — moving into or deeper into fintech. It covers the conceptual terrain: compliance constraints, payments flows, and the architectural patterns that emerge from them.

Why Domain Fluency Matters at the Frontend Layer

At staff level, you're expected to make architectural decisions that won't rot under you. In fintech, those decisions carry regulatory surface area. A poorly designed state machine for a payments flow isn't just a UX bug — it can result in double charges, incomplete settlements, or audit failures.

Frontend engineers who treat fintech as "the same job with stricter validation" tend to build systems that handle happy paths correctly but crack under the domain's actual failure modes:

Idempotency violations from optimistic UI updates
Race conditions between transaction state and UI state
Accessibility failures that violate regulatory obligations (WCAG is a legal requirement in financial services in several jurisdictions)
Audit trail gaps caused by insufficient event logging at the client layer

Domain fluency means you can anticipate these failure modes before they're filed as incidents.

The Compliance Layer Is an Architectural Constraint

In most product domains, compliance is a checklist you run through late in a feature cycle. In fintech, it's a first-class architectural input.

KYC and KYB Flows

Know Your Customer (KYC) and Know Your Business (KYB) verification flows are often the first complex frontend engineering problem you'll encounter. They look like multi-step forms, but they behave like state machines with external dependencies.

A KYC flow typically involves:

Document collection (government ID, proof of address)
Submission to a third-party verification provider (e.g., Persona, Onfido, Jumio)
Asynchronous verification (taking minutes to days)
Status polling or webhook-triggered state transitions
Remediation loops for rejected submissions

The frontend architecture needs to handle the async nature explicitly. A naive implementation that treats verification as a synchronous form submission will fail badly. You need a durable state model:

type KYCStatus =
  | { stage: 'not_started' }
  | { stage: 'documents_pending' }
  | { stage: 'submitted'; submittedAt: string }
  | { stage: 'under_review' }
  | { stage: 'approved'; approvedAt: string }
  | { stage: 'rejected'; reason: string; retryAllowed: boolean }
  | { stage: 'manual_review' };

This discriminated union pattern forces every rendering path to handle every state explicitly. When the backend team adds a new status, TypeScript surfaces every unhandled case in the UI. In regulated flows, "we missed a status" is not an acceptable postmortem entry.

Audit Trails and Immutability

Regulatory frameworks — PCI-DSS, SOX, GDPR, FCA rules — often require that financial actions be attributable, timestamped, and non-repudiable. This has direct implications for how you design frontend event logging.

Client-side events that touch payment initiation, consent recording, or document submission should be:

Emitted as structured, typed events
Correlated with a server-side trace ID
Stored immutably (no update or delete semantics at the log layer)

This is not analytics. It's an audit trail. Design it accordingly.

Payments Flows: The State Machine Problem

A payments flow is a distributed state machine with multiple participants: the user, your frontend, your backend, and a payments processor (Stripe, Adyen, Braintree). The frontend's job is to accurately reflect state transitions that it does not fully control.

Idempotency and Optimistic UI

Optimistic UI — updating local state before server confirmation — is a standard pattern for improving perceived performance. In payments, it's dangerous without careful design.

Consider a "Pay Now" button. If a user taps it and the network is slow, they may tap again. Without idempotency keys on the backend and request deduplication on the frontend, you risk two charges.

The correct pattern:

const usePaymentSubmit = () => {
  const idempotencyKey = useRef(crypto.randomUUID());
  const [status, setStatus] = useState<'idle' | 'submitting' | 'success' | 'error'>('idle');

  const submit = async (paymentDetails: PaymentDetails) => {
    if (status === 'submitting' || status === 'success') return;
    setStatus('submitting');

    try {
      await initiatePayment({
        ...paymentDetails,
        idempotencyKey: idempotencyKey.current,
      });
      setStatus('success');
    } catch (err) {
      setStatus('error');
      // Do NOT reset idempotencyKey — allow retry with the same key
    }
  };

  return { submit, status };
};

The idempotency key persists across retries intentionally. If the first request succeeded but the response was lost in transit, a retry with the same key returns the original result rather than creating a second transaction.

Terminal vs. Non-Terminal States

Transaction states divide into terminal (no further transitions possible) and non-terminal (may still change). SETTLED and REFUNDED are terminal. PENDING and PROCESSING are not.

UI that treats a non-terminal state as final is incorrect. A payment showing PROCESSING needs a polling mechanism or a WebSocket subscription to eventually converge to SETTLED or FAILED. Users who close the browser and return need to see the current state, not a cached intermediate state.

Your state management layer needs to distinguish between local UI state and remote transaction state, and it needs a reconciliation mechanism:

// TanStack Query handles staleness and refetching cleanly
const { data: transaction } = useQuery({
  queryKey: ['transaction', transactionId],
  queryFn: () => fetchTransaction(transactionId),
  refetchInterval: (data) => {
    // Stop polling once we reach a terminal state
    const terminalStates = ['settled', 'failed', 'refunded', 'cancelled'];
    return data && terminalStates.includes(data.status) ? false : 2000;
  },
});

Regulatory UI Obligations

Accessibility Is Not Optional

In the UK, the Equality Act 2010 requires that financial services be accessible. In the EU, the European Accessibility Act came into full force in June 2025. In the US, the DOJ has increasingly cited WCAG 2.1 AA as the standard for ADA compliance in financial services litigation.

WCAG compliance in fintech is a legal obligation, not a nice-to-have. A payment form with poor focus management, missing ARIA labels on error states, or keyboard traps isn't just a bad experience — it's a liability.

For complex flows (multi-step forms, modal confirmation dialogs, dynamic error states), you need to:

Manage focus programmatically on step transitions
Announce dynamic content changes via aria-live regions
Associate error messages with their inputs via aria-describedby
Test with actual screen readers, not just automated scanners

Consent and Disclosure UI

Many financial actions require explicit, recorded consent: terms of service acceptance, fee disclosures, risk warnings. The UI patterns here are legally significant.

A pre-checked checkbox, an auto-dismissing modal, or a disclosure hidden below the fold can each invalidate consent in regulatory terms. These components need compliance review, not just product review.

When building consent components, treat the consent event as a domain event with a typed payload:

type ConsentEvent = {
  type: 'consent_recorded';
  userId: string;
  consentType: 'terms_of_service' | 'fee_disclosure' | 'risk_warning';
  documentVersion: string;
  timestamp: string; // ISO 8601
  ipAddress: string; // captured server-side
  userAgent: string;
};

The frontend initiates this event; the backend records it immutably.

Architecture Patterns That Emerge from Fintech Constraints

Strict Data Flow and Validation

Financial data has tight schemas. An amount field that accepts string when it should be number in minor currency units, or an ambiguously formatted date, can cause downstream failures in payment processing. Use Zod (or an equivalent schema library) to validate API responses at the boundary:

import { z } from 'zod';

const TransactionSchema = z.object({
  id: z.string().uuid(),
  amountMinorUnits: z.number().int().positive(),
  currency: z.string().length(3), // ISO 4217
  status: z.enum(['pending', 'processing', 'settled', 'failed', 'refunded']),
  createdAt: z.string().datetime(),
});

type Transaction = z.infer<typeof TransactionSchema>;

This validation belongs at the API client layer, not scattered across components. When a backend team changes a field type, you catch it at the boundary — not in a production error report.

Feature Flagging and Progressive Rollouts

Financial features can't be safely rolled back mid-transaction. A user who has started a payment flow under version A of your app cannot safely complete it under version B if the flow structure has changed. Feature flags and cohort-based rollouts are therefore critical infrastructure, not optional.

Design new payment flows as entirely separate routes or experiences, keeping the old flow live until the rollout is complete and all in-flight transactions have resolved.

Sensitive Data Handling on the Client

Card numbers, bank account details, and government ID numbers should never pass through your application's JavaScript. Use iframe-based tokenization (Stripe Elements, Adyen Web Components) so sensitive data travels directly from the browser to the processor. Your app receives a token, not the raw data.

This isn't just a security best practice — it substantially reduces your PCI-DSS compliance scope.

What This Means for a Frontend Engineer in Practice

Building in fintech means accepting that:

Every flow has a failure mode that matters more than the happy path. Design for settled, failed, and pending, not just success.
State machines are load-bearing structures. Informal state management — boolean flags, nested conditionals — will break in a domain with this many states and transitions.
Compliance constraints are design constraints. Engage with them early, not at the end of a sprint.
The TypeScript type system is a compliance tool. Exhaustive unions and strict validation at API boundaries catch domain errors before they become incidents.

Frontend engineers who understand the domain can challenge product decisions, identify compliance risks in designs, and write code that reflects the actual semantics of financial operations. That's the difference between owning a UI layer and being a full contributor to a fintech product.

The investment in domain knowledge pays back quickly — and in fintech, the cost of not making it is measured in real money.

Prefer duplication over the wrong abstraction

DimiDan — Tue, 23 Jun 2026 03:18:00 +0000

Sandi Metz wrote The Wrong Abstraction in 2016. It keeps resurfacing — in high-scoring HN threads, architecture Slack channels, and code review comments — whenever a team is staring at a function that started as a clean DRY consolidation and has since acquired seven parameters, three feature flags, and a comment that says # don't touch this.

The core argument is simple: duplication is far cheaper than the wrong abstraction. Once you've built the wrong abstraction, you're not starting from a clean slate — you're inheriting someone else's sunk cost, and every new requirement gets jammed into a shape that doesn't quite fit.

I've spent a lot of time at the intersection where this matters most: design systems, editor foundations, and cross-team API contracts. These are exactly the contexts where the abstraction temptation is strongest — and where getting it wrong is most expensive.

Why the wrong abstraction is so easy to create

Abstractions don't usually start wrong. They start reasonable.

You have two components that render a card. They share 80% of their structure. You extract a Card component, parameterize the differences, and ship it. Six months later, Card has a variant prop with eight values, a withBorder flag, a compact prop, a headerSlot, and a suppressDefaultPadding escape hatch added by someone who needed the component to do something the abstraction never anticipated.

The problem isn't that the original extraction was wrong. The problem is what happened next: every new use case was treated as a reason to extend the existing abstraction rather than a signal to question whether the abstraction still fit.

Metz identifies the specific failure mode: the abstraction is not the thing itself, it's a theory about the thing. When the theory is wrong, new data doesn't correct it — it gets explained away by adding parameters.

The cost of inline duplication is lower than it looks

When two components share markup, the instinct is to extract immediately. But consider what you actually know at extraction time:

You know what the two existing callers need.
You don't know what the third caller will need.
You don't know which parts of the shared structure are incidentally similar versus structurally equivalent.

Incidental similarity is the trap. Two things can look identical for completely different reasons. A StatusBadge and a CategoryTag might render the same pill shape today. That doesn't mean they'll evolve together. Extracting them into a shared Pill component couples their evolution even if their domains have nothing in common.

Duplication, in this case, is not laziness — it's preserving optionality. Each component can change shape independently when its domain requirements diverge, which they will.

// Two components that look identical today
const StatusBadge = ({ status }: { status: OrderStatus }) => (
  <span className={`badge badge--${status}`}>{STATUS_LABELS[status]}</span>
);

const CategoryTag = ({ category }: { category: ProductCategory }) => (
  <span className={`badge badge--${category}`}>{CATEGORY_LABELS[category]}</span>
);

// Six months later, StatusBadge needs a tooltip and an ARIA live region.
// CategoryTag needs a remove button and a count indicator.
// The shared abstraction would now be a liability.

If you'd extracted a Pill component on day one, you'd now be untangling it. Instead, two independent components diverge cleanly.

When shared primitives are genuinely correct

None of this means "never abstract." The argument is about wrong abstractions, not abstractions generally. There's a category of shared code that genuinely belongs together: primitives that are structurally equivalent by design, not incidentally similar by coincidence.

In a design system, a Button component is a real abstraction. It exists because button behavior, accessibility semantics, focus management, and visual consistency are supposed to be uniform across every surface. The shared implementation isn't an accident — it's the point. When the design system updates the focus ring to meet WCAG 2.2 criteria, you want every button in the product to update from one change.

The test for a real abstraction is whether its callers are supposed to be coupled. If coupling them is a feature — consistent behavior, enforced constraints, centralized correctness — the abstraction earns its place. If coupling them is just an artifact of current visual similarity, it's a liability.

A useful heuristic for architecture reviews:

Does this abstraction encode a rule, or does it encode a coincidence?

A Button encodes a rule: interactive elements with this semantic role should behave this way. A Pill extracted from StatusBadge and CategoryTag encodes a coincidence: these two things look the same right now.

The parameter accumulation signal

You rarely see a wrong abstraction clearly at creation time. The signal appears later, in how the abstraction responds to pressure.

Right abstractions absorb new requirements gracefully. You add a new button variant: <Button variant="ghost">. The existing API handles it cleanly. The abstraction was modeling something real, and the new case fits the model.

Wrong abstractions resist new requirements. You need the card component to suppress its default padding in one specific context. There's no clean way to express that, so you add suppressDefaultPadding={true}. The prop name itself is a confession — it's not modeling a concept, it's punching an escape hatch through the existing model.

Parameter accumulation — especially boolean flags or parameters that only matter to one caller — is the clearest signal that an abstraction has outlived its theory.

// This function signature is a warning sign
function formatUserName(
  user: User,
  options: {
    includeTitle?: boolean;
    shortForm?: boolean;
    uppercaseLastName?: boolean; // added for the export feature
    omitMiddleName?: boolean;    // added for the badge component
    legalFormat?: boolean;       // added for contract generation
  }
): string

This function is doing five jobs. It's no longer a formatting function — it's a dispatch table that routes to five different formatting strategies based on flags. The right move is to inline the relevant logic at each call site, or to create five clearly-named functions that each do one thing.

The recovery path: inline before you re-extract

Metz's prescription is specific: when you recognize a wrong abstraction, don't refactor it — inline it. Copy the abstraction's code back to each call site, restore the parameters to their concrete values, delete the dead branches, and see what you actually have.

This is uncomfortable. It feels like moving backward. But what you get after inlining is the truth: the actual logic each caller needs, without the mediation of a theory that no longer fits.

From that position, you can see whether a new abstraction is warranted. Sometimes the call sites look very different after inlining — which tells you the old abstraction was hiding real divergence. Sometimes they look nearly identical — which means a better abstraction is now obvious, because you're working from real requirements rather than accumulated historical ones.

I've done this with editor extension configurations, design token resolution logic, and API response normalization layers. Every time, the inline step was the uncomfortable-but-necessary precondition for getting the abstraction right.

The cross-team dimension

At staff level, wrong abstractions have a social dimension that makes them harder to fix. When an abstraction is owned by one team and consumed by three others, inlining it requires coordination. The owning team has to be willing to let go of something they built. The consuming teams have to accept temporary duplication. Everyone involved has to resist the pull toward "let's just add another parameter."

This is where architecture reviews and RFCs earn their keep. The time to debate whether an abstraction is modeling the right thing is before three teams build on top of it — not after. A good RFC process forces the question: is this abstraction encoding a rule that should govern all callers, or is it encoding one team's current needs in a shape that will constrain everyone else later?

The answer isn't always to avoid the shared abstraction. Sometimes the shared primitive is genuinely the right call. But asking the question explicitly, with concrete examples of what future callers might need, catches a lot of wrong abstractions before they get adopted.

The actual takeaway

Metz's essay persists because it names something that's easy to see in retrospect and hard to see in the moment. The wrong abstraction feels like good engineering when you create it. It reduces line count, eliminates repetition, and looks clean. The cost shows up later, incrementally, as each new requirement gets shoe-horned in.

The discipline it requires is specific: resist the extraction until you understand what the shared structure actually represents. Duplicate freely when the similarity is incidental. Extract confidently when the abstraction encodes a real rule. And when you inherit something that's accumulated enough parameters to be unreadable, have the resolve to inline it before you try to fix it.

Duplication is recoverable. The wrong abstraction is a debt that compounds.

When an AI Agent joins your Yjs room

DimiDan — Sun, 21 Jun 2026 03:18:14 +0000

Wiring an LLM as a first-class Yjs peer is architecturally sound — but it invalidates three silent assumptions your collaboration stack already makes about peer symmetry: throughput, undo ownership, and presence cadence.

You've tuned a Yjs provider under real collaborative load. You know the feeling before you can name it — one heavy client starts lagging the room, presence updates stutter, and you end up adding a debounce somewhere and calling it done.

Now imagine that client generates text at 3,000 words per minute, never goes offline, and has its own awareness cursor.

That's not a sidebar feature. That's a new class of peer, and your collaboration architecture wasn't designed for it.

The Demo Is Real — But It Skips the Hard Parts

In April 2026, a working demo wired an LLM as a genuine server-side Yjs document peer — same transport as the human editors, same CRDT, its own awareness state. The implementation uses y-prosemirror and the standard awareness protocol directly. If you've shipped TipTap collaboration, you already have every dependency it needs.

The architecture is correct. Making the agent a server-side peer — rather than a client-side bolt-on posting diffs over a REST endpoint — gives you one convergence model instead of two, real presence semantics for the agent, and a clean separation between the LLM streaming layer and the document state layer.

But the demo establishes the peer model. It doesn't stress-test what happens to your existing assumptions once that peer is running.

The Silent Assumption Every CRDT Implementation Makes

Here it is — the assumption baked into the Yjs awareness protocol, the undo manager, and your backpressure strategy, the one nobody wrote down because it was always true until now:

All peers produce operations at roughly human speed.

Not identical speed. Human typists vary. But they land in the same order of magnitude. The entire design space — how often you broadcast awareness, how you scope undo history, whether you need per-peer rate limiting at the application layer — rests on that implicit contract.

An AI agent at 1,000–4,000 words per minute is 25–100× outside that range. It doesn't just stress your transport. It invalidates the mental model.

Here's what actually breaks.

1. Backpressure: The Chokepoint You Don't Have

A central OT server can throttle any client trivially — it's the authority, it controls the queue. A CRDT peer model has no natural chokepoint. That's the tradeoff you accepted when you chose Yjs, and it's usually fine because human peers self-limit.

An agent peer doesn't self-limit. Left unrestricted, its doc.transact() calls will flood the sync cycle and starve human-paced operations of their share of the convergence window. This is write starvation — the same class of problem as database concurrency — and it manifests as cursor lag and dropped presence updates for everyone else in the room.

The fix doesn't belong at the transport layer. It belongs between the LLM's streaming output and the Yjs document write:

// Token bucket between LLM stream and Yjs write
const agentBucket = new TokenBucket({
  capacity: 50,     // max queued ops
  refillRate: 10,   // ops per 100ms — keeps agent below human starvation threshold
});

llmStream.on('token', async (token) => {
  await agentBucket.consume(1);
  ydoc.transact(() => {
    ytext.insert(insertionPoint, token);
  }, agentOrigin);
});

The numbers are illustrative — tune them against your provider and room size. The point is that the rate limit lives at the application layer, scoped to the agent's origin, so human operations always get a guaranteed share of the convergence window regardless of how fast the model is generating.

This is also where the CRDT-vs-OT debate gets re-litigated in 2026. The peer model is still right for human collaboration. For AI agents specifically, you're adding a lightweight central constraint back in — not for correctness, but for fairness.

2. Undo History: The Origin Problem You Probably Already Have

y-undomanager scopes undo history by origin. This is correct behavior and it's documented. But "correct" and "deliberate" aren't the same thing.

If the agent's operations share an origin with the user's, Ctrl+Z becomes a coin flip. If the agent gets its own origin — which it should — you now have a second question: should user-facing undo ever surface agent operations, and if so, in what order relative to the user's own history?

There's no universal answer, but there is a clear principle: give the agent a separate UndoManager with its own trackedOrigins, and expose agent-undo as a distinct UI affordance, not the default Ctrl+Z path.

const userUndoManager = new Y.UndoManager(ytext, {
  trackedOrigins: new Set([userOrigin]),
});

const agentUndoManager = new Y.UndoManager(ytext, {
  trackedOrigins: new Set([agentOrigin]),
});

// User's Ctrl+Z only touches userUndoManager.
// "Reject AI suggestion" calls agentUndoManager.undo().
// These stacks don't interfere.

This is the same design decision you face when adding comment marks or tracked-change marks to ProseMirror — marks that describe content rather than being content need a separate lifecycle from marks the user controls directly. The agent peer is the document-level version of that same pattern.

If you've ever had a user accidentally undo a comment thread someone else left, you've already felt this problem. The fix is the same: make the ownership boundary explicit at the manager level, not implicit in a if (origin === agentOrigin) return buried in a command handler.

3. Presence and Awareness: Coalesce or Drown

The awareness protocol was designed for human-paced cursor updates. A few broadcasts per second per peer is normal; the rendering layer handles it fine.

An agent generating 3,000 wpm produces position changes at a rate no human can visually process. Broadcasting all of them is noise on the wire and in the React render cycle.

Two things to do. First, coalesce awareness updates on a fixed interval for agent peers — not per-operation:

let pendingAwarenessUpdate: ReturnType<typeof setTimeout> | null = null;

function updateAgentAwareness(pos: number) {
  if (pendingAwarenessUpdate) return;
  pendingAwarenessUpdate = setTimeout(() => {
    provider.awareness.setLocalStateField('cursor', { anchor: pos, head: pos });
    pendingAwarenessUpdate = null;
  }, 300);
}

Second, add a type field to the agent's awareness state so the rendering layer can distinguish it from a human cursor without conditional logic scattered across components:

provider.awareness.setLocalState({
  type: 'agent',
  streaming: true,
  name: 'AI Assistant',
  cursor: { anchor: insertionPoint, head: insertionPoint },
});

"AI is writing" and "another person is typing" are different affordances. They deserve different visual treatments and different update rates. Encoding that distinction in the awareness state lets the rendering layer make the right call in one place.

What This Means for Your RFC

The agent-as-peer pattern is the right architecture. Connecting the LLM to Yjs is not the hard part.

The hard part is going back through every assumption your collaboration system makes about peer symmetry and making those assumptions explicit — so you can break them deliberately for the agent peer without breaking them for everyone else.

Concretely: your backpressure strategy assumed no single peer can dominate the convergence cycle, so it needs an application-layer token bucket scoped to the agent's origin. Your undo history assumed all tracked origins belong to the user, so the agent needs a separate UndoManager surfaced as a distinct UI action. Your awareness rendering assumed cursor updates arrive at human speed, so agent presence needs coalescing and a type discriminant in the awareness state.

None of these are hard to implement once you've named them. The risk is shipping the integration without naming them and finding the failure modes through user reports six weeks later when the collaborative load is real and the undo history is a mess.

Treat rate limiting, undo isolation, and presence coalescing as first-class line items in the RFC. Not edge cases caught in code review.

The April 2026 demo and companion repo are at electric.ax/blog/2026/04/08/ai-agents-as-crdt-peers-with-yjs. The y-prosemirror + awareness setup maps directly onto a TipTap stack — worth reading alongside the Yjs UndoManager docs if you're planning the integration.

Why this, why now: The April 2026 demo is the first working implementation of the agent-as-Yjs-peer pattern on a production-equivalent stack (y-prosemirror, awareness protocol, Durable Streams), and it landed just weeks ago. The "agent velocity problem" it surfaces is genuinely new — CRDT literature has no prior answer for asymmetric peer throughput at this scale — and every team currently building collaborative AI editing features will hit the same three failure modes. Writing this now, before the pattern calcifies into bad defaults, is exactly the right time.

Global Precision & Financial Calculations

DimiDan — Sat, 30 May 2026 02:17:28 +0000

Global Precision and how it could impact the financial calculations

When you're building anything that handles money, someone eventually asks:
"how many decimal places should we use?" The tempting answer is to pick a
number — 2, or maybe 5 to be safe — set it globally, and move on. It feels
like a reasonable call. It's not.

I've debugged precision bugs that traced back exactly to this decision.
Once you understand why a single global precision fails, you can't unsee it.

The core problem is that different parts of a financial system have genuinely
different precision requirements, and treating them the same introduces errors
at the boundaries.

Billing calculations that appear on invoices need 2 decimal places. That's
cent precision. That's what customers see, what they're charged, what appears
on the contract. Showing 4 decimal places here is wrong for a different reason —
you're creating a number that can't be represented in any real currency.

Analytics calculations — revenue attribution, cohort aggregations, lifetime
value — need more precision. When you're summing thousands of transactions
before producing a final figure, rounding to 2 places at each step accumulates
error that compounds in ways that matter at scale.

Internal calculations — intermediate values mid-computation — should use the
highest precision you can reasonably sustain, precisely because they feed into
further operations. Rounding early and then doing arithmetic on the rounded
value is one of the most common sources of financial calculation bugs I've
encountered.

If you apply a global setting, you're either truncating precision your
analytics pipeline actually needs, or you're putting 4-decimal numbers on
customer invoices. Neither is acceptable.

The model that works is precision as an explicit input to each domain calculator,
with sensible per-domain defaults:

type PrecisionConfig = {
  internalCalcPlaces: number;
  displayPlaces: number;
  storagePlaces: number;
};

const BILLING_PRECISION: PrecisionConfig = {
  internalCalcPlaces: 5,
  displayPlaces: 2,
  storagePlaces: 2
};

The engine computes everything at internal precision. It rounds to display
or storage precision only when producing output — at the domain boundary,
not in the middle of a calculation chain.

This brings us to what I think is the subtlest and most consequential mistake
in financial arithmetic: rounding order.

Consider a line item. Unit price $10.333..., quantity 3, 10% discount.

Round early: you get $10.33 × 3 = $30.99, apply discount, round to $27.89.

Round late — maintain full precision through the chain: $10.333... × 3 × 0.9 = $27.899...,
round only at output: $27.90.

One cent difference on one line item. Across a large pricing table with currency
conversion also in the chain, accumulated rounding error is real, customer-visible,
and extremely difficult to debug once it's in production — because the bug is
in the order of operations, not in any individual calculation.

Round at output boundaries. Never in the middle of a computation chain.

Currency conversion adds another layer to this. Rates are typically 4–6 decimal
places. If you convert and immediately round to 2 decimal places before doing
further arithmetic, you've thrown away precision you needed. Convert at full
internal precision, display-round last.

And never convert and re-convert. Round-trip currency conversion
(USD → EUR → USD) with intermediate rounding will not give you back the
original number. If any part of your system displays a converted value and
then uses that displayed value in further calculation, you have a latent
bug waiting for the right combination of exchange rate and amount to surface it.

The practical steps are straightforward: define precision per domain, make
it an explicit parameter rather than global configuration, add a lint rule
that forbids raw Number arithmetic in your calculation package, and treat
output boundaries as the one and only place where rounding is allowed.

It sounds like ceremony until you've spent a day debugging a $0.01 discrepancy
on a $50,000 contract that a customer has already signed and is asking why
the numbers don't match.

Precision bugs that involve accumulated rounding are the hardest to reproduce
consistently — they depend on exact input combinations and operation order.
Has anyone built regression suites specifically for these? Property-based
testing feels like the right tool but I'm curious what others have actually shipped.

Pricing logic feels boring until it's wrong.

DimiDan — Thu, 21 May 2026 03:03:11 +0000

Build it like infrastructure from day one.
Most pricing engines are built wrong. Here's what I'd do instead.
If you're building a CPQ product — or any SaaS tool where users configure and price deals — your pricing logic is probably living in the wrong place.
It's in a component. Or a utility function called from three different places. Or worse, duplicated between your frontend table renderer and your backend invoice service, silently drifting apart until a customer notices the numbers don't match.
I've thought a lot about how to architect this properly. Here's what I'd do.

First: treat pricing as infrastructure, not a feature
The moment you have billing frequency, line-item discounts, currency formatting, and tax rules composing together, you don't have a utility anymore. You have a domain. It deserves its own package, its own test suite, and its own ownership.
A shared @your-org/pricing-engine package — published internally, consumed by your frontend, your backend, and your export pipeline — means one place where

unitPrice × quantity × frequency = subtotal

is defined. Not three.
Why does this matter in practice? Consider this scenario:
A sales rep quotes a client €90/month per seat for a SaaS tool, after a 10% discount, converted from USD. That number needs to be:

Identical in the live proposal table the rep is editing
Identical in the PDF the client downloads and signs
Identical in the invoice the billing system generates on day one
Identical in the revenue report the finance team pulls at month end

If your frontend, your PDF export service, and your billing backend each have their own implementation of applyDiscount() and convertCurrency(), you will eventually have a discrepancy. Not maybe. Eventually.

Never use floating-point arithmetic for money. Ever.

0.1 + 0.2 === 0.30000000000000004

This isn't a JavaScript quirk. It's IEEE 754 — the way binary floating-point works at a hardware level. And it will silently corrupt your customer invoices.
A real example of how this surfaces: a pricing table with 7 line items, each with a percentage discount and a currency conversion applied. By the time you sum those rows, the float drift compounds. Your table shows $1,200.00. Your invoice says $1,199.99. Your customer notices. Your support team gets a ticket. Your engineers spend a day debugging something that was never going to work correctly.
Use decimal.js or equivalent to it. Treat it as a hard rule, not a code style preference. Decimal arithmetic is slower — negligibly so at any realistic pricing table scale. There is no valid argument for floating-point in customer-facing money calculations.

Keep your engine pure
A pricing engine should be a pure function:

inputs → outputs

No Redux. No React. No HTTP calls. No side effects. Just data in, calculated data out.
What the engine looks like from the outside

const result = computeTablePricing({
  rows: [
    {
      id: "row-1",
      unitPrice: new Decimal("100.00"),
      quantity: new Decimal("5"),
      billingFrequency: "monthly",
      discount: { type: "percentage", value: new Decimal("10") }
    }
  ],
  currency: { code: "EUR", symbol: "€", symbolPosition: "front", decimalPlaces: 2 },
  settings: { taxRate: new Decimal("0") }
});

// result.rows["row-1"].subtotal === Decimal("450.00")
// result.frequencyTotals.monthly === Decimal("450.00")
// result.grandTotal === Decimal("450.00")

This matters more than it sounds. A pure engine:

Runs identically on web, server, React Native, and in a unit test
Can be validated against your old implementation in shadow mode before touching production
Can be reasoned about without understanding your component tree
Can be tested with plain input/output assertions — no mocking, no rendering, no Redux store setup

The billing frequency problem — a concrete example of why this matters
Let's say you want to add billing frequency to your pricing table. Line items can be one-time, monthly, or annual. The footer should show a subtotal per frequency group.
In a component-centric architecture, you add grouping logic to your table renderer. Then you realize your PDF export also needs frequency subtotals, so you add it there too. Then billing needs it. Three implementations. Three places to get out of sync.
With an engine, billing frequency is just a first-class input field on each row:

billingFrequency: 'one-time' | 'weekly' | 'monthly' | 'quarterly' | 'annual'

The engine computes frequency subtotals as outputs. The table reads them. The PDF reads them. The billing service reads them. Same numbers everywhere, because it's the same function.

The discount composition problem — where things really break
Discounts are where scattered pricing logic becomes a genuine product risk.
Consider what a real CPQ discount model looks like:

A rep can apply up to 10% at line-item level without approval
Anything above 10% needs manager sign-off
There's a volume discount: 5+ seats get an additional 5% off
There's a seasonal promotion: 15% off annual plans in Q4
These can stack — but only in specific combinations

If discount logic lives in your table component, how does your catalog apply the same rules? How does your billing service validate that the agreed discount is still applied at invoice time? How do you write a unit test for the approval threshold without rendering a table?
The answer is: you can't, cleanly. You end up with discount logic scattered across five files, each with slightly different behavior.
In an engine architecture, discount application is a shared rule:

// shared/discount-application.ts
export function applyDiscount(
  baseAmount: Decimal,
  discount: { type: 'percentage' | 'fixed'; value: Decimal }
): { discountedAmount: Decimal; discountAmount: Decimal } {
  const discountAmount =
    discount.type === 'percentage'
      ? baseAmount.mul(discount.value).div(100)
      : discount.value;

  return {
    discountedAmount: baseAmount.minus(discountAmount),
    discountAmount
  };
}

One function. Tested once. Used by the table calculator, the catalog calculator, the billing service, and the approval workflow validator. Identical behavior everywhere by definition.

The feature composition problem — this is the real ceiling
Individual features are manageable. The problem is when they compose.
A line item that has:

Billing frequency: monthly
Discount: 10% off
Currency: EUR, converted from USD at current rate
Tax: 20% VAT applied after discount

...needs to produce exactly the same number in your live editor, your PDF, your invoice, and your analytics pipeline. Every combination of features multiplies the number of cases where scattered logic can diverge.
This is what actually blocks CPQ roadmaps. Not any individual feature — the combinatorial explosion of feature interactions when your calculation logic is spread across the codebase.

Let your state layer stay clean
In a Redux architecture, the pattern that actually works:

Redux stores confirmed inputs only (what the user committed — prices, quantities, discounts, frequencies)
Selectors derive all calculated values by passing those inputs through the engine
Components never calculate — they only display

// selector reads inputs from Redux, derives outputs via engine
const selectTablePricingResult = createSelector(
  [selectTablePricingInputs],
  (inputs) => computeTablePricing(inputs) // pure function, memoized automatically
);

This eliminates an entire class of bugs where your displayed subtotal disagrees with what gets saved, invoiced, or exported. The Redux store is always clean data. Derived values are never persisted. There is no ambiguity about whether a stored subtotal field is a user input or a computed value — a distinction that causes real bugs in collaborative editing and undo/redo flows.

The migration play — how to get there without breaking production
If you're refactoring an existing system rather than greenfielding, shadow mode is your best friend.
Run the new engine in parallel with your old implementation. For every calculation your old code produces, the engine produces the same calculation independently. Log any divergence. Ship zero user-facing changes until the outputs match exactly — across every row type, every discount combination, every currency, every edge case you can throw at it.
Silent arithmetic regressions on customer invoices are not a recoverable situation. Shadow mode gives you mathematical certainty before you flip the switch.
The sequencing I'd recommend:

Engine package first — pure functions, no UI changes, full test coverage
New features through the engine — billing frequency, discounts, anything net-new goes through the engine from day one, minimizing regression risk on existing behavior
Shadow mode on existing features — validate the engine matches current behavior exactly
Migrate existing consumers — replace old calculations one surface at a time, behind a feature flag
Remove the old code — only after full coverage and monitoring confirms correctness

What this unlocks long-term
Once you have a pure, shared pricing engine, a lot of things that were hard become straightforward:

Backend adoption: Your invoice service imports the same npm package your frontend uses. Calculation discrepancies between frontend and backend become structurally impossible
Mobile: React Native consumes the same engine. No separate mobile pricing logic
Analytics: Revenue reports use the same calculation rules as the proposals that generated the revenue
Formula engine: User-programmable pricing formulas

(=quantity * unitPrice * (1 - discount))

become an extension of the engine, not a rewrite of it.

The point
Pricing logic feels boring until it's wrong. Build it like infrastructure from day one — pure, shared, tested, and decoupled from your UI layer. The payoff isn't visible immediately. It's visible when your fifth pricing feature composes correctly with your first four without a single edge case meeting.
Have you tackled pricing complexity at scale? Curious what patterns have worked — especially around currency and tax.

DEV Community: DimiDan

Baking Accessibility into Your Design System: A Four-Layer Testing Strategy

Why I care about Accessibility: a short pre-history

Why the design system is the leverage point

Why "just be careful" doesn't work

Layer 1: Static analysis with eslint-plugin-jsx-a11y

Layer 2: Unit tests with axe-core

The jsdom gotcha: no contrast checking

Layer 3: Storybook as a browser-based scanner

Making suppressions traceable

Layer 4: The CI gate, and why we didn't turn it on immediately

The rollout trap: don't gate before you audit

Choosing a target: AA required, AAA where it's cheap

A side benefit: accessibility tests audit your types

The takeaway

CRM data, Service Adapter and Integration Contract

So what's the issue

The good idea underneath

Rule 1: name the field, then actually say what goes in it

Rule 2: shut the door on undeclared fields

Rule 3: the normalization layer can't save you

Rule 4: the mapper that quietly eats your fields

Rule 5: don't add a second way to say what something is

The schema - what it should enforce

Where to actually enforce this

The short version

Feels like a feature until it's infrastructure

Features and invariants are different objects

The tell: closures vs commands

When architecture pays off

How to spot infrastructure wearing a feature costume

Claude Code, Bun and TypeScript

Why Claude Code runs on Bun: runtime tradeoffs in TypeScript CLI tooling

Why runtime choice matters more for CLIs than for servers

Bun's bundler as a distribution primitive

The dependency management story is genuinely better

Where native modules still cause pain

TypeScript ergonomics: where Bun earns its keep

What this signals for the TypeScript tooling ecosystem

Practical takeaways if you're building TypeScript tooling

React Server Components - The Mental Model Shift

How Shift did happened

Data Fetching: Colocation at Scale

Bundle Optimization Is Now Structural

State Management Boundaries

The Client Boundary as an API Contract

Team and Collaboration Implications

What This Is Not

Where It Lands

A critical look at AI terminal coding Assistants

What OpenCode Is Actually Doing

The Context Problem Is Not Solved

The Trust Gradient Problem

Where Terminal-First Actually Wins

The Autonomy Dial Is Set Wrong

What a Staff Engineer Actually Wants From These Tools

The Honest Verdict

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

GPT-5 and Convex Optimization: What the Claims Actually Mean for Engineering Tooling

What Convex Optimization Actually Is (And Why It's Everywhere)

What the GPT-5 Results Actually Show

The Skepticism in the Thread Is Legitimate

What This Actually Changes for Engineering Teams

Where to Be Careful

The Actual Opportunity

Fintech Frontend Engineering and Financial Services

Why Domain Fluency Matters at the Frontend Layer

The Compliance Layer Is an Architectural Constraint

KYC and KYB Flows

Audit Trails and Immutability

Payments Flows: The State Machine Problem

Idempotency and Optimistic UI

Terminal vs. Non-Terminal States

Regulatory UI Obligations

Accessibility Is Not Optional

Consent and Disclosure UI

Architecture Patterns That Emerge from Fintech Constraints

Strict Data Flow and Validation

Feature Flagging and Progressive Rollouts

Sensitive Data Handling on the Client

Layer 1: Static analysis with `eslint-plugin-jsx-a11y`