DEV Community: Gabriele Pieretti

Approving a Tool Is Not Approving Data: What Laravel AI SDK 1.0 Changes, and What It Doesn't

Gabriele Pieretti — Fri, 25 Sep 2026 20:23:56 +0000

Laravel AI SDK 1.0 shipped on September 23, and one of the headline features is the Approvable contract: a tool that implements it pauses the agent until a human approves the call, rejects it with a reason, or rewrites the arguments. It is the right thing to have in the framework. But after a year of building a product that sends customer images to a model, my reaction was colder than I expected: tool approval is a control over an action, and the thing that keeps me up at night is a control over data. Those are not the same boundary, and putting them in the same place is an elegant way to get it wrong.

What the contract actually does

The mechanism is clean. A tool declares Approvable, uses the InteractsWithApprovals trait, and when the model decides to call it the conversation stops and hands back the pending calls with the arguments the model picked:

use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;
    // ...
}

You resume by passing a decision per call: approve, reject with a reason the model gets to read, or edit the arguments before the tool runs. It works with prompt, stream, queue and the broadcast methods, so it survives the case where the agent runs on a queue and the approval arrives twenty minutes later from a different HTTP session. That part — persisting the state of a suspended agent — is the boring work nobody wants to rewrite, and it is the real reason to reach for the package.

The mental model it suggests, though, is: the agent proposes, the human confirms, the action runs. That is perfect for DeleteFile, for a refund, for an email going out. It is much weaker when the risky part is not what the tool does, but what the prompt carries with it.

In Miraviso the boundary sits lower down

In Miraviso, the virtual mirror for hair salons, the pipeline has two declared privacy treatments, because they genuinely are two different mechanisms.

The colour try-on runs entirely on the tablet: MediaPipe segmentation on-device, colour composited locally, no frame ever leaving the hardware. The haircut preview does not: that one needs a generative model, it runs on Gemini via Vertex AI in an EU region, it requires explicit consent from the person sitting in the chair, and the result is never written to disk.

Take that second path and try modelling it as an approvable tool. The approval would read something like: "the model wants to call generate_haircut_preview with this image — confirm?" But who confirms? The salon operator — the only person holding the tablet, and the only one the agent loop can question. And the consent I need is not theirs. It belongs to the client, who never touches the interface and who has to be able to say no before the camera does anything useful at all.

Hence the rule I ended up with: human approval inside the agent protects whoever is driving the agent. Consent to processing protects whoever is inside the data. If the only gate lives in the agent loop, I have built a confirmation dialog for the wrong person.

The gate that sits before the model

In my pipeline consent is not a turn in a conversation: it is session state, and the client cannot even compose a generative request until that state exists. The FastAPI endpoint that talks to Vertex refuses upstream, not after the fact, and not by trusting a flag the tablet sent:

@router.post("/preview/cut")
async def preview_cut(req: CutRequest, session: Session = Depends(current_session)):
    if not session.consent.generative_preview:
        raise HTTPException(403, "missing consent for generative preview")
    # from here on the frame only ever exists in memory
    ...

Three practical consequences, all more boring than a PHP contract and all more important:

consent state lives server-side and expires with the chair session, not with the salon account: the next client starts from zero, because the previous client's consent is not a property of the tablet;
revocation has to work mid-flight, which means the gate is rechecked after every await that can take real time, not just at the entrance;
"never written to disk" means never: no temp files, no HTTP client cache, no logs echoing the request body. That is not a property you defend with an architecture decision — you defend it by auditing every library that touches those bytes.

I wrote about that last point separately, because it is a far more common failure than it looks: sensitive data ends up in logs almost always through a failed query or an APM trace, not through a line somebody wrote on purpose.

Where I would use it tomorrow

None of this is a criticism of the package; it is a division of labour. On the back-office side — the Laravel side, where customer records, appointments and invoicing live — an agent that proposes actions and waits for confirmation is exactly the right tool. Merging two duplicate customer records, moving a run of appointments, issuing a credit note: these are operations where the argument the model picked is precisely the thing I want to be able to correct, and being able to rewrite arguments before execution is worth more than being able to say no.

Worth flagging too: per-step middleware, which in 1.0 runs on every generation step instead of once per prompt. You get a PendingStep and can swap the model, strip tools or lower the token budget as the conversation goes on. For a solo founder paying for tokens out of pocket that is a concrete cost lever — dropping the expensive tool after its first use is now one line, and used to be an architecture problem.

The rule I am taking away, and it travels well beyond this SDK: when a framework hands you a gate, ask who is standing on the handle side. If the answer is not the person whose data is passing through, the gate is useful but it is not yours.

Originally published at gabrielepieretti.dev.

Storage::path() Could Walk Out of the Disk: The Path Traversal Laravel 13.30 Closes

Gabriele Pieretti — Wed, 16 Sep 2026 13:48:32 +0000

Up to Laravel 13.29, Storage::get('../../../.env') threw an exception while Storage::path('../../../.env') happily returned the absolute path of your .env. Same facade, same disk, same argument, opposite answers. Laravel 13.30, released on September 1, brings the two calls in line. It is worth understanding how the gap existed, where the pattern actually bites, and why the right security fix here is a design habit rather than a flag.

Why two methods on the same facade disagreed

Almost everything you ask of Storage goes through Flysystem: get(), put(), delete(), readStream(). Flysystem normalizes the path before using it and, if the normalized result escapes the disk root, throws PathTraversalDetected. That is why, in years of Laravel applications, nobody worried much about a .. passed to Storage::get(): the framework blocked it for you.

Storage::path() was the exception. It does not read the file; it only returns the native path string, and to do so it went straight to PathPrefixer::prefixPath(), which concatenates the disk prefix with whatever you hand it. No normalization, no check. On the default local disk, path('../../../.env') resolved out of storage/app all the way to the project root. Scoped disks had the same hole: path('../file.txt') walked straight out of the configured prefix as if it were not there.

KIKOmanasijev's PR, merged on August 27 and shipped in 13.30.0, runs path() through the same WhitespacePathNormalizer that Flysystem builds for every other call, with the same defaults. The result is that path() now returns exactly the string the driver computes internally, so the two can no longer disagree about what a path means.

Where the pattern bites: attachment downloads

The code that makes this asymmetry dangerous is trivial, which is exactly why the story interests me. Every line-of-business app has a spot where the user downloads a document: an invoice, an attachment, a report export. The lazy version of that route looks like this:

Route::get('/download', function (Request $request) {
    return response()->download(
        Storage::path($request->query('path'))
    );
});

With ?path=../../../.env, until two weeks ago, that route served your database credentials to anyone with an account. And Storage::path() is precisely the method you reach for when you don't want Flysystem to read the file: when you hand it to response()->download(), to an external process like ImageMagick or LibreOffice for a conversion, to a PDF library that wants a native path. In other words, exactly the cases where the file travels from the disk to the outside world, often after a detour through a queue where nobody checks anymore who asked for what.

After eleven years of building Laravel business applications I have seen enough download routes to say that the "path comes from the query string" variant is not rare. It is almost always born in good faith: the front end already has the path because it received it in a JSON response, and passing it back looks like the simplest thing. It is also the wrong thing, and 13.30 does not change that verdict.

The framework's fix is not your fix

Upgrade to 13.30: it is free and it closes the path() hole. But normalization stops the .., not access to a file inside the disk that does not belong to the person asking. With ?path=invoices/another-customer/2026-03.pdf the path is perfectly legitimate for Flysystem and perfectly illegitimate for you. No normalizer can know that.

The rule I have applied for years is that the path on disk is never an input. It is a column in a table, and the user passes you the row's identifier:

Route::get('/attachments/{attachment}', function (Attachment $attachment) {
    Gate::authorize('view', $attachment);

    return Storage::disk('attachments')->download($attachment->path, $attachment->original_name);
});

Three things happen in three lines. Route model binding turns the input into an existing row or a 404. The policy answers the question the filesystem cannot ask: is this person allowed to see this file? And download() goes through Flysystem, so even if someone one day wrote a row with a strange path, the traversal would still be rejected. The 13.30 fix becomes a third layer of defense, not the only one.

If you truly need path() — for an external process, say — the same discipline applies: the path comes from the model, never from the request, and it is still worth checking that realpath() of the result starts with realpath() of the disk root. It is one extra line that, on Laravel < 13.30, is the only thing between you and your .env.

Fewer places a byte can live, fewer paths to defend

This bug reminded me of a choice I made in Miraviso, my SaaS for hair salons. The haircut preview is generated on a server in the EU, with consent, and is never written to disk: it is born in memory, returned to the salon's tablet, and gone. That decision was not made with path traversal in mind; it came from privacy — a client's face should not outlive the request that generated it. But it has a side effect I appreciate more today: a file that does not exist has no path, and a path that does not exist can be neither traversed nor guessed. The same goes for the sensitive notes, which the server stores as sealed envelopes it cannot open: even an improper download would return something unreadable.

That model does not apply to everything. A business app has to keep invoices, and invoices have to be downloadable. But the question to ask is the one I asked for Miraviso: does this file need to exist on disk, and for how long? Every file you decide not to write is a download route you do not have to protect.

What to do today

Upgrade to 13.30 and grep your code for Storage::path( and ->path(: for every hit, trace the argument back to its origin. If at any point you reach $request, that is the route to rewrite with a binding and a policy, whatever framework version you run. It is a less entertaining audit than a minesweeper that never makes you guess, but the rule there is the same: a cell only opens once you can prove it is safe.

Originally published at gabrielepieretti.dev. I write about Laravel, privacy-by-design and building a vertical B2B SaaS solo — more here.

Laravel's Native Vector Search Now Speaks MariaDB — Plain MySQL Is Still Left Out

Gabriele Pieretti — Tue, 08 Sep 2026 16:13:32 +0000

Originally published on my blog.

On August 20, PR #61250 was merged into Laravel's 13.x branch, bringing the query builder's native vector search — whereVectorSimilarTo and friends — to MariaDB. Until then it was PostgreSQL-with-pgvector only. I care about this for two reasons: I spent eleven years building business software on Laravel and MySQL, and the way the PR is written is a small lesson in driver design worth more than the feature itself. There's a third, less cheerful reason too: if your projects run on plain MySQL, as most of my older ones do, you're still left out — and not because anyone was lazy.

What was there before: a hard-coded check

Laravel 13 ships four methods for working with embeddings straight from the query builder: whereVectorSimilarTo, whereVectorDistanceLessThan, orderByVectorDistance and selectVectorDistance. The idea is the usual one: you write the query in fluent PHP, the framework compiles it into the right SQL for your database.

Except that until mid-August, "your database" meant exactly one. Inside Query\Builder sat a hand-written instanceof PostgresConnection check, and the distance SQL itself — pgvector's <=> operator — was inlined right there in the builder rather than living in the driver's grammar. It worked, but it was the classic kind of debt you don't notice until somebody tries to add a second database.

What the PR does: move the question where it belongs

The refactoring is small and clean. The question "does this driver know how to compute vector distances?" moves from the connection class to the grammar, via a pair of methods — supportsVectorDistance() and compileVectorDistanceExpression($column) — that each driver can override. It's the same pattern Laravel has used for years for compileRandom() or savepoint support: a base implementation on the grammar, per-driver overrides.

With the question in the right place, adding MariaDB becomes almost trivial: its grammar compiles the distance into vec_distance_cosine(), the native function MariaDB has shipped since 11.7 Community (11.4.5-3 on Enterprise), alongside a real VECTOR column type. The schema side — typeVector() and vector indexes — already existed from an earlier PR; only the query side was missing. Five days later a follow-up, #61337, landed with an SQL fix and an AsVector Eloquent cast.

This is what I take home as someone who designs APIs, even before wearing the user hat: the moment you catch yourself writing instanceof SomethingConnection outside the driver, the feature is living in the wrong place. You'll ship the first database either way; it's the second one that hands you the bill.

The uncomfortable part: plain MySQL stays out

And my MySQL-based systems? Nothing. whereVectorSimilarTo() on a standard MySQL connection still throws a RuntimeException — the PR merely updated the message to mention MariaDB. The reason isn't Laravel: MySQL Community and Enterprise, in the standard binaries, have no native vector distance function. DISTANCE() and VECTOR_DISTANCE() exist only on HeatWave (so, on OCI) and on MySQL AI. If you're not on Oracle's cloud, there is no SQL to compile.

Just as interesting is what the PR refused to do: a PHP-side fallback that fetches rows and computes similarity in memory. It would have been convenient to announce and disastrous to use — it would silently break the semantics of limit() and pagination, and change the performance contract of the query without telling anyone. Letting the exception fly is the honest choice: a clear error today beats a mysterious slowdown in production six months from now.

What I'd actually do

For an existing MySQL application that wants semantic search — matching "frizz treatment" when the user types "puffy hair", say — I see three options today, in my order of preference:

Evaluate moving to MariaDB, if your app uses MySQL in a standard enough way that the migration is boring rather than heroic. With this PR, MariaDB has become the cheapest way to get native vectors while staying in the MySQL family.
A separate service just for search — a small Postgres with pgvector next to the main MySQL, kept in sync from application events. More moving parts, but it doesn't touch the database everything else lives on.
Wait, which is a legitimate strategy: semantic search in a line-of-business app is almost always a nice-to-have, and wrong infrastructure is paid for over years.

For new projects the question settles itself: when I picked Postgres for Miraviso, vectors weren't even on my radar, but this is exactly the kind of dividend a conservative database choice keeps paying. And the flip side is worth stating too: none of these queries help you with data you encrypt client-side. Miraviso's sensitive notes — the ones the server stores as envelopes it cannot open — can never end up in a server-side vector index: you can't embed text you can't read. It's a useful reminder that semantic search is a data processing operation like any other, and deserves the same care in deciding.

Where this is heading

The refactoring opens a wider door than the single feature: now that distance compilation lives in the grammar, adding a driver or a different metric is a small PR, not open-heart surgery on the builder. There's already a proposal to make the distance metric configurable (cosine, euclidean) instead of assumed. That direction looks right to me: a query builder that treats vectors as a driver capability, declared by the grammar, exactly like the rest of its SQL. Meanwhile, those of us on plain MySQL at least get an error message that tells the truth.

Thirty Days to Migrate: When Your SaaS Depends on a Model That's About to Disappear

Gabriele Pieretti — Tue, 08 Sep 2026 16:13:19 +0000

Originally published on my blog.

On August 27, Google moved Gemini Omni 1.1 Flash, its video generation model, to general availability under the stable ID gemini-omni-1.1-flash. In the same move, the old gemini-omni-flash-preview endpoint was scheduled for deprecation on September 30. Do the math: roughly thirty days to migrate, retest, and ship. I don't use that model — the haircut preview in Miraviso works on images, not video — but the pattern is exactly the risk anyone lives with once a hosted model sits inside their product. And in my case there's an extra twist worth writing down: a privacy-first architecture takes away precisely the tool you'd want for managing the migration.

The pattern: GA is good news with a deadline inside

The sequence is familiar by now: a model ships as a preview, you integrate it because it's the only way to get that capability, the product grows to depend on it, and one day GA arrives — good news — bundled with a shutdown date for the preview, which is a deadline on your calendar set by somebody else. The Omni transition has all the typical details, too: a separate channel ID on Vertex AI (gemini-omni-1.1-flash-preview, which is not the stable Gemini API ID despite the nearly identical name), new controls the preview never had, and — according to third-party reports I've read, worth verifying against the official pricing pages — no clearly published GA price at announcement time. Migrating is not swapping a string: it's retesting quality, latency, and cost with your inputs, because the release notes won't do that for you.

Thirty days is tight if you learn about the migration from the deprecation email. It's comfortable if, the day the email lands, all you have to do is run a procedure that already exists. That's the entire difference.

My case: half the product is immune, half is not

Miraviso has two deliberately different technical paths, and this story lights both of them up. The color try-on runs entirely on the salon's tablet with on-device MediaPipe: the video never leaves the device. That path is structurally immune to endpoint deprecations — the model ships with the app, and nobody can switch it off remotely. It's an under-discussed benefit of going on-device: not just privacy and latency, but independence from someone else's release calendar.

The haircut preview, on the other hand, is generated server-side in the EU, with Gemini on Vertex AI, after the client's consent. There the dependency is real, and it's the price of a capability you can't get on-device today. That path lives on Google's calendar, and has to be designed with that in mind.

The twist: you can't regression-test data you don't keep

The standard way to handle a model swap is a regression corpus: sample real production inputs, replay them against the new model, compare outputs. Well — I can't. By design, not by accident: preview images are never written to disk. They pass through, get processed, return to the tablet, gone. It's one of the promises the product stands on, and it doesn't become negotiable just because it would be convenient.

The consequence is that the test corpus has to be built outside production traffic, and in advance. Concretely, that means three things:

An explicit, consented golden set: images collected specifically for testing — your own, volunteers who signed up for that exact purpose, or datasets with a suitable license — covering the cases that actually matter: hair types, skin tones, real salon lighting, crooked framing. It's not a poor substitute for production data: it's the only corpus you have, so its quality is the ceiling on the quality of your tests.
The model behind a hard boundary: one place in the code that knows which model is called and how. If the endpoint name shows up in multiple files, scattered environment variables, or stored job templates, then step one of any migration — finding every occurrence — is already an afternoon-long project.
Evaluation criteria that don't require the originals: if you compare old vs. new by eye on the golden set, fine — but the criteria for what makes a preview "acceptable" must be written down beforehand, because aesthetic judgment under mid-migration pressure is the worst judgment you will ever exercise.

The deadline is the product working as intended

There's a lazy reading of news like this: "big tech keeps killing your APIs, what a disaster." I don't share it. A vendor that moves a model to GA and retires the preview is doing serious catalog maintenance; the alternative — eternal previews nobody promises to maintain — is worse. The deprecation isn't the problem. The problem is arriving at it with no golden set, no boundary around the model, and the endpoint ID copy-pasted into four places.

The rule I hold myself to is trivial to state: every capability bought from a hosted model must have, from day one, an answer to the question "how do I replace this?". Not a detailed plan — an answer. If the answer is "I don't know", that's not a dependency, it's a lien on the product. And much like the data that ends up in your logs without anyone deciding it should, the right time to think about it is while the architecture is still fresh — not when the email with the date inside arrives.

Sensitive Data in Your Logs: What Laravel 13.27's Binding Masking Fixes (and What It Doesn't)

Gabriele Pieretti — Tue, 01 Sep 2026 13:22:46 +0000

Originally published on gabrielepieretti.dev.

When a query fails, Laravel builds a QueryException whose message contains the SQL with every bound value interpolated into it. That's great while you're debugging. In production it means every failed insert copies customer data — an email, a name, maybe a national ID — into your logs, into the failed_jobs table, and into your APM traces. Laravel 13.27, released on August 26, finally ships a switch to turn that interpolation off. It's worth being precise about what it closes, and what it doesn't.

The problem: exceptions get written down

A QueryException message is designed to be read by a developer mid-debug: insert into users (email) values (?) tells you nothing about which row broke, the version with the value tells you immediately. The trouble is that the message doesn't stay on that developer's screen. It's a string attached to an exception, and exceptions get recorded everywhere:

in the log file or channel you configured in logging.php;
in the exception column of failed_jobs, because the failed-job provider casts the exception to a string and inserts it as-is;
in the spans of your APM or OpenTelemetry agent, if you run one;
in whatever error-tracking service your exception reporting ships data to.

Each of those places becomes an undeclared copy of the data you were writing to the database — with different retention, different access rules, and almost never accounted for when someone fills in a data-processing register. Across eleven years of building Laravel back-office systems, I've watched application logs get read by far more people than ever had database access. That's normal; logs exist to be read. The question is what ends up in them without anyone having decided it.

What Laravel 13.27 does

Version 13.27 introduces the per-connection option mask_bindings_in_exception_messages. The key ships in the framework's own config/database.php on all five default connections, so even an application that never published that file can enable it with a single environment variable:

DB_MASK_BINDINGS=true

With the flag on, the exception message keeps its placeholders:

SQLSTATE[23000]: Integrity constraint violation: 1062
Duplicate entry 'ada@example.com' for key 'users_email_unique'
(SQL: insert into `users` (`email`, `name`, `national_id`)
 values (?, ?, ?))

Notice the detail: the duplicate value still appears in the first line, because that part of the message comes from the database driver, not from Laravel. The flag masks the framework's interpolation — it doesn't rewrite what MySQL says. That's still a lot: the full insert with three columns of personal data is gone. But it's not a complete scrub of the message.

Why I'd turn it on almost everywhere

The cost of the flag is that when an exception fires in production you no longer see the values at a glance: you have to recover the bindings some other way — logging them separately to a channel with short retention and tight access, or reproducing the case in development. That's real friction. But the right question isn't "does this make debugging harder?", it's "who reads my logs, and how long do they stick around?". If the answer includes a third-party service, an APM, or months of retention, then binding interpolation is a category of personal-data processing you never declared to anyone — including yourself.

The threat model is bigger than one flag

This release matters to me because it touches a principle I built Miraviso around — it's my SaaS for hair salons: sensitive data has to be protected not just where you think you store it, but in every place your infrastructure re-copies it without asking. Logs, queues, traces, log backups, snapshots: every component that serializes state to help you debug is a potential shadow archive.

In Miraviso, the notes a salon keeps about its clients can contain allergies and scalp conditions, and there I took the conclusion all the way: those notes are encrypted with a key derived on the device, and the server stores envelopes it cannot open. I wrote about that design in a dedicated post. The property that's relevant here is that the envelope design makes the logging problem structurally impossible for those fields: if the plaintext never exists server-side, no exception, however verbose, can interpolate it into a message. There's no flag to remember to enable, no misconfigured APM agent that can betray you.

I'm not arguing every field deserves that treatment — the same segmentation I apply there applies here. Most data can live in plaintext on the server, and for that data Laravel 13.27's flag is the right move: cheap, immediate, reversible. A small set of fields is delicate enough that leaking them should be impossible rather than unlikely. The test for telling them apart never changes: does the server have a legitimate need to read this value? If not, make sure it can't.

What to do today

If you run a Laravel application in production that handles personal data, the list is short. Upgrade to 13.27 and set DB_MASK_BINDINGS at least in production. Then open failed_jobs and look at the exception column of your old records: the flag protects the future, it doesn't clean up the past, and those rows have whatever retention you gave them — often forever. Finally, ask which other components of your stack cast exceptions to strings and keep them around. It's a less entertaining exercise than writing nonogram solvers, but it makes your next audit a great deal shorter.

Vue's Vapor Mode Is Almost Here. Writing Browser Games With No Framework Taught Me Why It Matters

Gabriele Pieretti — Tue, 25 Aug 2026 16:28:49 +0000

Vue 3.6 entered release-candidate stage in July, and with it Vapor Mode is finally feature-complete: single-file components that compile straight to direct DOM operations, skipping the virtual DOM entirely. A stable release is expected this autumn.

I use Vue daily in client work, so I care about this for the usual reasons - smaller bundles, faster updates. But I have a second, stranger reason to care: for the past while I've been hand-writing logic games for my personal site - a nonogram, a minesweeper variant, numberlink, mastermind, a 3D Rubik's cube with a built-in solver, a speedcubing timer. Each game is one page, no framework, no heavy libraries. Just state and direct DOM manipulation. And that experience is basically a preview of what Vapor Mode does - except I've been the compiler.

What you learn when there's no virtual DOM to hide behind

Take the nonogram. The board is a grid of cells; a click toggles one cell and possibly updates a couple of row/column clue indicators. In a naive framework mental model, the "view" is a function of the whole board state, and something diffs its way to the minimal change. Writing it by hand, you can't afford that mental model. You think in deltas: this click changes this cell's class and these two clue elements, nothing else. You write exactly those three DOM operations and you're done.

The minesweeper was the same lesson at higher stakes. Mine is a no-guess variant - every generated grid is verified by a solver so you're never forced into a 50/50. When a flood-fill reveals eighty cells at once, you feel every unnecessary DOM touch. So you batch: compute the full set of cells to reveal in pure JS, then apply the class changes in one pass. State first, DOM second, and only the DOM that actually changed.

The 3D Rubik's cube pushed this furthest. Animating layer turns and running solvers (layer-by-layer, CFOP, optimal) means the interesting work is entirely in the state model - the DOM/render layer is a thin projection of it. Once you structure things that way, "rendering" stops being the hard part of the app.

What this says about Vapor Mode

Three takeaways from doing manually what Vapor now does at compile time:

First, the virtual DOM was never primarily a performance feature. It's a developer experience feature: it lets you write view = f(state) and not think about deltas. The diffing is the price you pay for that mental model, not a speed trick. Vapor's bet is that a compiler can keep the declarative authoring model and emit the delta-based code I was writing by hand - the best of both.

Second, the discipline that no-framework code forces on you - keep state pure, treat the DOM as a projection - is exactly the discipline that makes components fast in any framework. If your component's state is tangled with its DOM, no rendering strategy saves you.

Third, there's a real ceiling on how much this matters. My games are the favorable case for direct DOM updates: high-frequency, localized mutations on large grids. A typical CRUD form re-renders so rarely that VDOM overhead is noise. If your Vue app is mostly forms and tables, Vapor will shrink your bundle more than it speeds up your interactions - still worth it, but know which benefit you're buying.

Would I still hand-write the games after Vapor lands?

Yes - but for a different reason than performance. Keeping each game dependency-free means the pages will still work untouched in ten years, and writing the update logic myself is half the fun. But for product work, Vapor is the right direction: it takes the rendering strategy that low-level code teaches you and makes it the default output of the declarative code you'd write anyway.

One caveat: 3.6 is still RC as I write this. Feature-complete is not stable - I'm not shipping it to client projects until the stable release, expected this autumn.

The games are all playable at gabrielepieretti.dev if you want to see the hand-rolled version of "vapor mode" in action.

The GPU that says yes and does nothing: debugging real-time hair segmentation on mid-range Android

Gabriele Pieretti — Mon, 17 Aug 2026 13:14:55 +0000

We build a virtual mirror for hair salons: a tablet
camera feed where the customer's hair changes colour in real time while they move their head.
Two constraints shaped every decision.

The first is privacy: no frame ever leaves the device. Everything runs locally — the model,
the fonts, the runtime — with no CDN dependency, because a CDN request would both break
offline use and leak the salon's IP to a third party.

The second is hardware: salons don't buy flagship tablets. We had to work on whatever
mid-range Android is on the counter.

This is what we learned making it fast enough. All numbers were measured on real devices with
diagnostics built into the engine — none of them are estimates.

The bug that looked like slowness

Our starting point was bad in a confusing way. A Pixel 8 Pro ran at 9 fps — poor, but working.
A Samsung A56 (Exynos 1580, Mali GPU) showed no colour at all.

The cause took a while to find, and it's the most useful thing in this article:

MediaPipe's ImageSegmenter with the GPU delegate was created without throwing, ran in 5 ms,
and returned zero hair pixels. Both the confidence mask and the category mask came back
empty. Every time.

Our fallback to CPU only triggered on exceptions. There were no exceptions. So it never
triggered, and the app simply looked slow instead of broken.

A clean comparison, same scene minutes apart:

Delegate	Mask coverage	Time per frame
CPU	1.5–2.1 %	483 ms
GPU	0.0 %	5 ms

Note the trap in that table. The GPU path is 96× faster precisely because it isn't doing
anything. If you benchmark by timing alone, the broken path wins.

The lesson: don't assume that a delegate which constructs successfully actually works.
Check the output, not the exit code. We now measure mask coverage and surface it in the
diagnostics.

Detecting it at runtime

The fix is a fallback that rebuilds the engine on CPU. The rule matters more than it looks:

After five consecutive empty masks, having never seen a good one in the whole session,
rebuild on CPU.

The condition is "never seen a mask", not "empty right now". An empty mask right now is
completely normal — it happens whenever nobody is in front of the lens. We had to encode the
difference between broken and nobody's there.

On the A56 this took us from 2 fps to 14 fps with colour applied.

The field confirmed it, months later

We shipped that fallback on the strength of a coverage number, which is a slightly
uncomfortable place to be: we knew that the delegate returned nothing, not why. The answer
arrived from a beta tester, as a photo of their phone screen. MediaPipe was failing a
RET_CHECK on every single segmentForVideo call:

Confidence mask count mismatch, 0 vs 2

The GPU graph was asking for two masks and receiving zero — at runtime, on every frame,
while construction succeeded cleanly. That is exactly why an exception-based fallback can
never catch it, and it's why a plain "Retry" button wouldn't have helped either: retrying
rebuilds the same broken graph.

Two cheap safety nets came out of that, both costing nothing per frame. If nothing has been
drawn two seconds after start, fall back from requestVideoFrameCallback to
requestAnimationFrame — on some WebViews the former exists but never fires. And do a
one-pixel readPixels, once, to find out whether the canvas is coming out black. We
had shipped a version where the error line was written into an element that
display: none had already hidden, so a broken device showed a black mirror and said nothing
at all. Errors you can't see are errors you can't fix.

A diagnostic that costs more than what it measures

While chasing this, we left outputCategoryMask enabled from an earlier experiment. The
diagnostic itself became a significant part of the frame budget. Worth remembering when your
measurements start shaping the thing you're measuring.

It was never the model

With the GPU path honest, we profiled the Pixel 8 Pro's 9 fps. The model inference cost 6 ms.
The other 126 ms were ours:

66 ms in a JavaScript loop recolouring pixels one at a time
two GPU→CPU readbacks per frame, one of them costing 123 ms

That's the whole story of most "the ML model is too slow" complaints we've had since: the
model was never the problem. The problem was everything we did around it.

Fix 1 — recolour in a fragment shader (66 ms → 0)

The per-pixel JavaScript loop moved into a fragment shader. This is the obvious one, and it's
free: the pixels are already on the GPU.

Fix 2 — decouple the mask from the draw

Hair does not move at 60 Hz. We were segmenting every frame for no reason.

segmentForVideo is synchronous, and on an Exynos it costs 437 ms of blocked main thread.
Now we segment one frame in every PASSO_SEG, and draw the video on all of them using the
most recent mask. The step adapts to the device.

This is the change that fixed the A56, and it's worth stressing: we expected to need a Web
Worker and we didn't. Decoupling cadence was enough.

Fix 3 — share the WebGL context with MediaPipe (123 ms → 0)

This was the big one. We were copying the mask out of MediaPipe and back into our own
pipeline, round-tripping through the CPU.

MediaPipe accepts a canvas in its options. Pass it the same canvas you're drawing on, and
you can take the mask with getAsWebGLTexture() — it never leaves the GPU.

One catch, learned the hard way: MediaPipe recycles that texture under your feet. Binding
it directly made the colour flicker. We copy it into our own texture with a shader, which is
still enormously cheaper than a CPU round trip.

Fix 4 — drop `preserveDrawingBuffer` (5 ms per frame)

preserveDrawingBuffer: true costs real time on every single frame. We only needed it to
capture a still of the current look, which is a rare user action.

We defer the capture to the next draw call, within the same task, and read it there. Verified
on device.

Two more things worth knowing

MediaPipe will not start inside a type: "module" worker. It dies with
ModuleFactory not set, because its WASM loader registers the factory via importScripts(),
which doesn't exist in module workers. If you want MediaPipe in a worker, you need a classic
worker — or you don't get one.

Freeze the frame in a texture before you segment. If you segment first and draw after,
the video has already advanced, and the hair lags behind the head permanently. Not
occasionally. Always.

Pick the specialised model. We were running selfie_multiclass, which segments six classes
when we needed one. Switching to the dedicated hair_segmenter: 780 KB instead of 16 MB, and
the official Pixel 6 figures are 58 ms vs 217 ms on CPU, 52 ms vs 71 ms on GPU. Our consumer
APK dropped from 40.7 MB to 25.8 MB.

Where we landed

132 ms → 17 ms per frame. 9 fps → 15 fps on the Pixel 8 Pro, and 2 → 14 on the A56.

You'll notice 17 ms per frame should mean roughly 58 fps, and we get 15. That's honest and
worth explaining: the remaining ceiling is no longer in our code. It's in how the WebView is
composited inside Flutter, and we haven't opened that front yet.

We also kept the old CPU 2D path as a fallback for devices without WebGL2. That's not
nostalgia — a canvas has exactly one context. If you request WebGL and it fails, you can't
fall back to 2D on the same canvas. You have to decide before you commit.

The takeaway

Four of the five wins here came from removing work we had added ourselves, not from making the
model faster. And the single largest discovery — the silently empty GPU delegate — wasn't a
performance problem at all. It was a correctness bug wearing a performance costume, and it was
invisible until we measured the output instead of the duration.

If you're building anything similar: instrument mask coverage, not just milliseconds. The
frame that takes 5 ms might be the one doing nothing.

The engine described here ships in Miraviso, a consultation tool for hair salons: the customer sees the colour and the haircut before the stylist starts.

If you'd rather look at it than read about it, the same engine is in a free consumer app — Miraviso Colore on Google Play. No account, no sign-up, and the camera pipeline runs entirely on the device, which you can check by putting the phone in airplane mode: the mirror keeps working. Tap the "Miraviso" header inside the colour screen and the status line turns into the live diagnostics described above — frame budget broken down by stage, the delegate in use, and the mask coverage number that this whole article is about. Each tap cycles: off → automatic → force GPU → force CPU. If you want to see the empty-mask failure for yourself, force GPU on a mid-range device and watch conf sit at 0.0 %.

Happy to answer questions about the WebGL side in the comments.

DEV Community: Gabriele Pieretti

Approving a Tool Is Not Approving Data: What Laravel AI SDK 1.0 Changes, and What It Doesn't

What the contract actually does

In Miraviso the boundary sits lower down

The gate that sits before the model

Where I would use it tomorrow

Storage::path() Could Walk Out of the Disk: The Path Traversal Laravel 13.30 Closes

Why two methods on the same facade disagreed

Where the pattern bites: attachment downloads

The framework's fix is not your fix

Fewer places a byte can live, fewer paths to defend

What to do today

Laravel's Native Vector Search Now Speaks MariaDB — Plain MySQL Is Still Left Out

What was there before: a hard-coded check

What the PR does: move the question where it belongs

The uncomfortable part: plain MySQL stays out

What I'd actually do

Where this is heading

Thirty Days to Migrate: When Your SaaS Depends on a Model That's About to Disappear

The pattern: GA is good news with a deadline inside

My case: half the product is immune, half is not

The twist: you can't regression-test data you don't keep

The deadline is the product working as intended

Sensitive Data in Your Logs: What Laravel 13.27's Binding Masking Fixes (and What It Doesn't)

The problem: exceptions get written down

What Laravel 13.27 does

Why I'd turn it on almost everywhere

The threat model is bigger than one flag

What to do today

Vue's Vapor Mode Is Almost Here. Writing Browser Games With No Framework Taught Me Why It Matters

The GPU that says yes and does nothing: debugging real-time hair segmentation on mid-range Android

The bug that looked like slowness

Detecting it at runtime

The field confirmed it, months later

A diagnostic that costs more than what it measures

It was never the model

Fix 1 — recolour in a fragment shader (66 ms → 0)

Fix 2 — decouple the mask from the draw

Fix 3 — share the WebGL context with MediaPipe (123 ms → 0)

Fix 4 — drop preserveDrawingBuffer (5 ms per frame)

Two more things worth knowing

Where we landed

The takeaway

Fix 4 — drop `preserveDrawingBuffer` (5 ms per frame)