DEV Community: OuterSpaceHobo

Dry-run permissions: a button that knows why it's disabled

OuterSpaceHobo — Mon, 12 Oct 2026 06:42:17 +0000

In this post I talk about a small pattern from my side project that turned out to be the useful piece of architecture in it: asking the server "could I do this?" before doing it.

Some context.

I'm building daihon.app, a trainer for spoken Japanese: you go through a dialogue line by line, say your lines out loud, and the browser checks your pronunciation.

Shadowing apps already exist, so the honest reason for building another one was different. I wanted real full stack experience on a stack I'd pick for a serious product: Next.js 16 with the App Router, strict TypeScript, PostgreSQL with Drizzle, my own JWT auth with httpOnly cookies, Zod on every boundary, and a lot of tests. A product with roles, limits and an admin panel is a good excuse to get all of that right.

And roles plus limits is exactly where UI code usually goes bad.

The problem.

There are four kinds of visitors: an anonymous visitor, a guest (no sign up, three trial dialogues), a registered user with a monthly quota, and an admin. Plus states: a banned user, an unverified email, a quota that resets on the 1st.

The default way to handle that is to sprinkle checks over components:

{user.role === 'admin' && <AdminLink />}
<Button disabled={user.isGuest && user.trialsUsed >= 3}>Start</Button>

Every one of these is a copy of a rule that also lives on the server. Copies drift. One day the server lets a guest start a dialogue and the button says no, or worse, the button says yes and the request fails with a 403 nobody explains.

So I set one hard rule for the project: no component decides by itself whether an action is available. It asks the server.

Dry-run.

Every protected route in the app is declared with a chain of guards: is the actor authenticated, not banned, within quota, and so on. The idea of dry-run is simple: run the same chain, but stop before the handler.

There are two ways in:

an X-Dry-Run header on any route, which returns the verdict instead of executing;
a batch endpoint, POST /api/dry-run/batch, that answers up to 20 checks in one request.

Both call the same function. That's important, because if the batch endpoint had its own logic, "direct check says yes, batch says no" would become possible.

The core is short:

export async function evaluateDryRun(entry, context, mode) {
  let code, denial, guardMeta;

  try {
    for (const guard of entry.guards) {
      const result = await guard(context);
      if (!result.allowed) {
        const derived = deniedStateFor(result.code);
        code = result.code;
        denial = entry.stateOf?.(derived) ?? derived;
        guardMeta = result.meta;
        break;
      }
    }
  } catch (error) {
    // the dry-run itself failed: disabled, never enabled
    return { result: shape({ allowed: false, ...DRY_RUN_UNAVAILABLE }, mode, entry), failed: true };
  }

  if (denial === undefined) {
    return { result: shape({ allowed: true, state: 'enabled' }, mode, entry), failed: false };
  }
  return { result: shape({ allowed: false, code, ...denial }, mode, entry, guardMeta), failed: false };
}

The guards in entry.guards are not "similar to" the ones on the real route. They are the same array. The route declares an action key from a registry instead of its own access rules, and takes its chain from there. So "dry-run said yes, the real call said no" can't be expressed in code at all.

What the UI gets back.

Not just a boolean. The response is a state plus a reason:

POST /api/attempts
X-Dry-Run: state

→ 200 {
  allowed: false,
  state: "disabled",            // enabled | disabled | hidden
  code: "GUEST_LIMIT_REACHED",
  messageKey: "dryRun.guestLimit",
  meta: { length: "short", limit: 3, used: 3, unlockedBy: "registration" }
}

The status is 200 even when the answer is no. The check succeeded, the action is just not available. Otherwise every hidden element on a page would show up as a 403 in the console and in monitoring.

hidden vs disabled follows one rule: no permission by role means hidden, no possibility by state means disabled. A guest never sees the admin link (showing it would leak the structure of the product). But a guest who used up three trial dialogues sees the Start button, disabled, with an explanation: "0 of 3 left, sign up to continue".

The meta part is what makes the explanation possible. The registry knows the action, but only the guard knows the actor: how much is left and when it resets. So the guard returns those numbers with its denial, and the client builds the message from them.

The mapping from error code to state lives in one table on the project, shared by server and client. A second copy on the client would drift silently.

The component.

On the client a component asks by action key, not by URL:

<Gated action="attempt.start.short" skeleton={<ButtonSkeleton />}>
  {({ state, messageKey, meta }) => (
    <Button disabled={state !== 'enabled'} hint={messageKey && t(messageKey, meta)}>
      {t('dialogue.start')}
    </Button>
  )}
</Gated>

hidden renders nothing;
disabled renders the element inactive, with the reason next to it. For the Start button that's a caption right under it: a tooltip doesn't exist on touch screens or for keyboard users, and this is the one reason people really need to read;
enabled is a normal render.

A provider collects all keys requested on the page and sends them in one batch. Two components with the same key share one check. A key that appears later (conditional render) gets added to the next batch with a 50 ms debounce, so late subscribers don't each fire their own request.

There is no polling. Verdicts get invalidated on events: login, logout, starting an attempt, role change. Without that, the Start button would happily stay enabled after the guest used their last trial.

Skeletons that don't blink.

While a verdict is pending, Gated shows a skeleton of the same shape and size as the final element, so the page doesn't jump.

But a skeleton shown right away has its own problem: on a fast connection it turns into a grey flash for a few dozen milliseconds, which looks broken. So there are two thresholds: if the answer comes faster than 150 ms, no skeleton at all. If the skeleton did appear, it stays for at least 300 ms. One small hook does that for the whole project, not only for dry-run.

Fail closed.

What if the database is down and a guard throws? The catch block above answers that: the dry-run result is disabled with an "unavailable" message. Never enabled.

The project has a general rule for degradation: fail open for convenience, fail closed for access. A broken check is allowed to make a button inactive. It is never allowed to make it active.

One more case from the same family: an X-Dry-Run header with an unknown value returns a validation error. Ignoring an unknown header would mean executing a real mutation where the client asked for a check.

On the client a network error is not the same as a denial either. The hook returns a tagged union, pending | ready | error, and on error the element is disabled with a connection message instead of silently disappearing.

Whole sections.

For the admin panel there is a boundary around the whole section:

<DryRunBoundary
  action="admin.summary.view"
  skeleton={<PageSkeleton />}
  denied={({ messageKey }) => <AccessDenied messageKey={messageKey} />}
>
  {children}
</DryRunBoundary>

hidden turns into a 404 (the section doesn't confirm it exists), disabled into an "access denied" screen.

And here is the part I want to underline: dry-run is UX, not security. The admin layout has its own server check, and every admin endpoint has its guards. Dry-run only makes sure the UI tells the truth about what those guards will say.

Cheap on purpose.

Dry-run checks are not written to the activity log. Every user action in the app is logged (it's a product requirement), but a log row per check would make the fastest growing table grow on every page view.

Testing it.

Because everything goes through one registry, the tests are generic:

for every action, a dry-run doesn't change the database (snapshot before and after, through both the header and the batch);
dry-run and the real call give consistent verdicts. This is generated from the registry, not written by hand;
completeness: an action key without a route, or a route that isn't in the registry or the explicit public list, fails the test run.

The first two prove the mechanism works for what is in the registry. The third proves the registry has everything it should.

Was it worth it?

Mostly yes. Adding a role or a limit now means touching guards and the registry, not hunting through components. The UI can always say why something isn't available, and that's the part users notice.

The cost is one extra request per page (batched) and some discipline: every new action needs a registry entry. Writing a test that fails when you forget it is what keeps that discipline from being a promise.

The app is live at daihon.app: open a dialogue as a guest, finish three, and you'll see the disabled Start button explaining itself.

Thank you for reading. Feedback is highly appreciated!

Why the dialogues in my Japanese speaking trainer aren't made up

OuterSpaceHobo — Tue, 06 Oct 2026 14:00:00 +0000

In this post I talk about how dialogues for my Japanese speaking trainer are put together, and why "just ask a model to write a conversation" was a no go.

Some context.

For a few years now I have been learning Japanese and even passed JLPT N2 this summer. At some point speaking became the weakest part. Reading and listening can be done alone with any amount of material. Speaking needs a partner, or at least a script worth repeating out loud.

Shadowing apps exist, and so do AI chat partners. With the chat option I kept running into the same thing: you talk with a model about who knows what, and you have no idea how natural its Japanese is. Plus, as a learner, you are the last person who could tell.

What I wanted was boring in a good way: short model dialogues, like the ones in a decent textbook, for everyday situations, at N5 to N3 level. One role is yours. You read it out loud, the browser recognizes your speech, and you only move on once the line is said correctly.

So I built daihon.app (台本, "script"). The trainer itself is a separate story. This one is about the content.

The problem with dialogues.

There are no native speakers on the project, and no native proofreading is coming. In a speaking trainer an unnatural line isn't just a typo: you drill it until it's automatic, so you memorize the mistake together with the pronunciation.

So "sounds natural to me" can't be the quality bar. Naturalness has to rest on something you can check.

And it breaks on two separate levels:

the line: do people actually say this?
the flow: do people say this at this point of a conversation?

Borrowing good sentences only fixes the first one. A dialogue stitched together from perfect sentences is a Frankenstein: every part is real, the whole thing is dead. Which is why most of the work goes into the skeleton, not into the lines.

Start from a real conversation.

A dialogue starts as a sequence of moves taken from an actual conversation. Roughly like this, for a restaurant call:

staff:    greeting + asks which area
customer: area and number of people, in one go
staff:    two options with prices
customer: picks one + asks about the time
staff:    confirms + asks about smoking
customer: short answer, doesn't repeat the question

This is exactly the kind of thing you don't get by inventing. On move four a textbook author writes a long polite question. A real customer says 六時でも大丈夫ですか and stops.

The sources are public research corpora of everyday Japanese and open-licensed sentence collections. All of them are credited. Some of them don't allow taking text at all, and that's fine: the structure of a conversation (who speaks when, what kind of move, how long) is a fact, not someone's text. So the closed corpora work where they matter most, on the skeleton, and actual wording only comes from sources whose license allows it.

One thing learned the hard way: a drill is not a conversation. Textbook exercises train one move, so they all have the same shape: question, answer, clarification, thanks. My first batch used them as skeletons and came out as ten dialogues you could not tell apart. Textbooks are still useful as a list of situations and vocabulary, just not as a source of flow.

What a line has to prove.

There is no such thing as an unchecked line. Each one carries a note of where it came from, and there are three kinds:

Taken as is from a source that allows it.
A slot swap in a real sentence pattern. 何名様ですか becomes 何時からですか: the construction is real, only the slot changes. This is how a line gets adjusted to the level without breaking grammar.
Written by me, but the phrase has to show up in a corpus search. This catches calques and "textbook Japanese": if the phrase doesn't occur anywhere, people probably don't say it.

The third kind is a necessity. At N5 about half the lines need simplifying, and the simplified version still has to be checkable.

Zero hits doesn't always mean "wrong", though. Sometimes the construction is fine and only a specific word pair is rare. Sometimes you searched for the wrong spelling: one of the corpora writes numbers with digits, so 三十分 gives zero and ３０分 gives over a hundred. And sometimes zero means exactly what it looks like. One line had every word backed by a source, and still the whole frame (a medicine that 咳が止まる) wasn't something people say, while the neighbouring frame with に効く was common. Checking words one by one can't see that. Checking the whole frame sees it immediately.

Rules a text has to pass.

A few rules came out of this that I now check every dialogue against:

Short reactions are real lines. そうですか, なるほど, ええ make up a big share of real conversation, so they stay. (With one technical catch: the speech synthesizer returns silence for a lonely ええ。, so a reaction always comes with something after it.)
Ellipsis where Japanese uses ellipsis. The answer doesn't repeat the question, and 私は only appears for contrast. These two give away textbook Japanese from the very first line. The echo is surprisingly easy to miss by eye, because you only see it in the pair, not in the line. Once you strip the final か from the question and compare the predicates, it shows up right away.
Not every partner line is a question. Strictly alternating question/answer is the shape of an exercise.
A turn is a move, not an answer. In real talk people usually say two things per turn: they answer and add a reason, a caveat, a counter question.

The rule I didn't see coming: one reading only.

This one is specific to a trainer that checks your speech.

Your spoken line is compared against the expected reading. If a word has two accepted readings, you can say the second one, be completely right, and still fail the line.

Numbers are the main suspects. 四十分 is fine as both よんじっぷん and よんじゅっぷん. 七時 is both しちじ and ななじ. 船便 is both ふなびん and せんびん. Destination 〜行き is both ゆき and いき, and that one sneaks in with any place name.

Fix: move the time to a neighbour that has one reading (六時半 instead of 七時). The scene doesn't change at all, and the line becomes passable for everyone who says it correctly.

Writing in several passes.

Drafts are written with an LLM, but not in one go. Each dialogue goes through several separate passes: collect the material and the skeleton, write the text, review, translate. Each pass starts fresh.

The fresh start for the review is the whole point. A session that just wrote a line also remembers why it wrote it, and it won't argue with itself. A clean pass reads the dialogue the way a reader does, and checks the flow, the tone and whether the scene is believable. The material from the first pass stays as the reference, so the review can still answer "was this intended?".

Translations come last and only touch translations. The Japanese text is final by then.

Audio.

The partner's lines are voiced with an open source offline TTS, generated once and stored, not requested on the fly. Two speakers, so the roles are easy to tell apart by ear. Getting the loudness even was its own small adventure: the standard one-step normalization didn't reach the target on lines under three seconds, and neighbouring lines differed by about 6 LU. Measuring each file and applying the exact gain fixed it.

Where it is now.

30 dialogues so far, 10 each for N5, N4 and N3. The pipeline is slow on purpose: a dialogue that takes a few sessions to make is still cheaper than a learner memorizing a sentence nobody says.

It's still a portfolio project, and I'm sure some lines can be better. If you're a native speaker or a teacher and something sounds off, I'd really like to hear it.

Try it here: daihon.app. No sign up needed for the first three dialogues.

Thank you for reading. Feedback is highly appreciated!

How I made free OCR chrome extension for Japanese language learners.

OuterSpaceHobo — Thu, 06 Apr 2023 14:26:51 +0000

In this article I talk about how I decided to create my first open source project after completing JS & React courses.

For some years I have been casually learning Japanese language and in my studies I heavily preferred immersive approach.

But Japanese language (as well as Chinese & partially Korean) have a pretty high bar for casual reading because not only one have to learn two alphabets, but also memorize at least few hundreds kanji.

The regular need switch from reading light text/manga (or watching youtube, dorama etc.) to some dictionary tab just to find this one unknown or forgotten kanji was really ruining the experience.

I discovered some awesome resources like Yomichan (highly recommend checking it out), which recognize text under mouse cursor and provide translation and annotation from given dictionaries.

Unfortunately none of free options used OCR so that one could check any pic be it manga panel or subtitles in paused video right from the same tab. So I decided to make one myself!

ScanLingua(project name proudly accepted from chatGPT suggestions).

I decided to start with chrome extension and used knowledge, gained from selfstudy and Jad Joubran JS & React courses (cool courses btw).

This is my of first/experimental and kind of portfolio project, so I tested different approaches and thus it may seem inconsistent, but thats the point.

Project structure.

Features two main parts: servise_worker and content_script, which are separate React Apps.

servise_worker is responsible for manifest, fetch and main popup render and content_script provides logic and render overlay & popup within current (active) tab.

content_script is bundled in single file inside servise_worker/public.

Apps exchange necessary data via chrome messaging with unique IDs like so:

// content_script

async function requestTranslation () {
    const requestId = getRandomInt(100000) 
    const response = await chrome.runtime.sendMessage({type: "request-translation", requestId}); 
    const res = await new Promise((resolve, reject) => {
        requests.set(requestId, resolve) 
        setTimeout(reject, 60*1000) //60sec
    })
    return res
}

// service_worker

chrome.runtime.onMessage.addListener(gotMessage)

async function gotMessage(request, sendResponse) {
    if (request.type == "request-translation") {
        const rawTranslation = await translateZone(visionText)
        const translation = await unEscape(rawTranslation)
        await sendTranslation(request.requestId, translation)
    }
}

async function sendTranslation(requestId, translation) {
    const [tab] = await chrome.tabs.query({active: true, lastFocusedWindow: true});
    const response = await chrome.tabs.sendMessage(tab.id, {type: "your-translation", requestId, translation});
}

Active tab overlay and canvas.

I started to implement crop zone selection functionality with creating main overlay div and five static children (top, bottom, right, left, zone).

And then passed on mousedown and on mousemove coords (x1, y1, x2, y2) to children divs sides so they change dynamically.

To capture selected zone on mouseup I used chrome captureVisibleTab and drew OffscreenCanvas on it with zone div coords.

I rushed to convert data to base64 and finally call OCR API, but the results were incorrect, and visualized zone image showed this:

The zone was off and looked zoomed in. At first it was frustrating but thanks to that Window.devicePixelRatio was discovered along with the source of problem — display ratio 2 on Mac. I’m kinda glad I found this early because be my display ratio 1 it would pass the radar just to appear later on other displays.

Styling.

Another problem was the need isolate active tab popup styles from the page in was injected into. Upon some research I decided between creating an iFrame or manually overriding conflicting styles.

Considering the active tab popup will host only one button and some styled text inside, iFrame looked like overkill so I went with override option. I also tried using React Styled Components since it is mandatory to bundle content_script in one .js file.

Used APIs.

For OCR & translation ScanLingua uses Google vision and translation APIs.

This APIs are not free, but provide 1000 free vision requests and 500 000 free character translation rep month which should suffice for personal use. One just have to create appropriate API key and pay attention for APIs usage to not exceed free monthly limits (key setup instruction provided).

To help User track key usage simple hotkey counter is set at extension Home tab.

For Kanji annotation I picked awesome free open source dictionary Jotoba (it also takes data from various resources, such as KanjiDic, Jisho and many other; since Jotoba API is free its availability is not guaranteed).

Next steps.

It is still raw & buggy, but already usable in general. Proof of concept release pushed to store:

ScanLingua - Chrome Web Store

Scan, recognize and translate parts of your screen.

chromewebstore.google.com

Repo:

OuterSpaceHobo / ScanLingua

Free open source chrome extension for immersive japanese, chinese and korean language learners.

ScanLingua

ScanLingua provides Japanese, Chinese and Korean text recognition of selected screen areas with translation, kanji annotation and audio.

Check on subtitles, manga panels or any CJK text;
Edit recognized text and alter annotations;
Create and export cards to Anki via Anki-connect;
Free and open source, secure by design;
Packed with local OCR engine and dictionaries.
Interface localization for en, es, fr, ja, ko, pt, th, tr, vi, zh.

Demo video: https://www.youtube.com/watch?v=u-YYc9RSiXo

ScanLingua uses Baidu's PaggleOCR (PP-OCRv5) for recognition and KANJIDIC2, CC-CEDICT, CC-KEDICT dictionaries, licensed under 'CC BY-SA 4.0', for characters annotation. Translation and audio (TTS) are handled by free native chrome APIs.

To-Do list:

Advanced setting - local model endpoins option;
Advanced setting - dictionary annotation translation;
Local usage statistics page and crop history;
Style themes;

Feedback is highly appreciated!

Troubleshooting

If screenshot hotkey don't work try to set it manually at chrome://extensions/shortcuts for "take-screenshot" command;
If you just…

View on GitHub

I plan to work on UI, fix errors and expand existing functionality.

Thank you for reading. Feedback is highly appreciated!