DEV Community: Rapls

I Couldn't Read the Code I Wrote With AI Six Months Ago

Rapls — Thu, 04 Jun 2026 07:14:48 +0000

Last week I opened a project I had built almost a year ago. Not because of a bug. A friend mentioned wanting a self-hosted Slack alternative, and I remembered I had made one. So I opened the folder in VS Code, looked at the file tree, picked the file that seemed like a sensible starting point, and opened it.

Five minutes later, I closed it.

I had written this code myself. And I could not tell what it did.

What I had built

Over the spring and summer of 2025, I built a Slack-style team communication tool. Channels, DMs, mentions, notifications, emoji reactions, file attachments, threads, unread badges. Most of what you touch in Slack on a normal day, I had implemented. It ran as a self-hosted theme on my own server.

The reason was ordinary. A paid Slack plan felt like too much for a small outside community, and I was riding the high of AI-assisted coding at the time. "I can probably build this myself." I started without thinking too hard about it.

In the first few weeks, channel lists and message posting came to life. I still remember how good that felt. Ask the AI, get code, paste it, watch it run, move to the next thing. The loop was fun, and somewhere in there adding features quietly became the goal in itself.

Then I shipped it to a client for review, and it went nowhere. No feedback came back, time passed, other work piled up, and the project drifted to the back of my mind. I did not touch it for almost a year.

What I saw when I opened it

Let me be specific about what I found, because the specifics are the whole point.

The first file I opened was the central controller. Dozens of backend files, more once you counted the JavaScript and CSS. I could not remember how I had arrived at this structure, or why.

The functions had names I could no longer read. Abstract labels like processMessage scattered everywhere, and I could not tell which one handled channel messages and which handled DMs without opening each one and reading the body.

So I grepped processMessage. It turned up in three files. The arguments looked similar, the bodies were subtly different. Past me had apparently meant "this one is for channels, this one for DMs, this one for threads." Reading it now, I could not see the difference. Three functions with the same name in three files, where the caller picking the wrong one breaks everything without a single error message.

The helpers had multiplied the same way. getUserNameById, getUserNameFromCache, getUserDisplayName, formatUserName. I wrote every one of them. Tracing which called which, and where each was actually used, ate far more time than I expected.

The comments came in two languages. A line like // Handle the case where user is not authenticated, and right under it a comment in Japanese about refreshing the unread badge. I had not cared at the time. The more honest version: I accepted whatever comments the AI produced and never rewrote them. Every time, I weighed "rewrite this comment" against "add one more feature," and the feature won.

Dead code sat everywhere. A function tagged // TODO: remove after refactoring, still there, called from nowhere. The refactoring never came. A few files were nearly empty, leftovers from a split I planned and abandoned, half-written with the rest still // TODO.

I checked the commit log to find out who wrote all of this. It was me. Every line.

Five minutes, and I closed the editor.

How I had been working

At the time, something like 80% of the code came from AI. I rotated between a few assistants, a CLI coding agent, an in-editor completion tool, and a chat model, building Slack features one at a time.

My day had a shape to it. Morning, coffee, open the editor, decide "today I implement unread counts for channels." Ask the AI how to do it Slack-style, skim the design it returned, say "go with this." The AI wrote the code. I copied and pasted. If it did not run, I pasted the error back, took the fix, and when it ran, moved on.

I had a loose sense of which tool to use for what. Structural thinking went to the CLI agent, small in-file edits to inline completion, research and rubber-ducking to the chat model. There was no real rule behind it. It came down to my mood that day, or whichever tab was already open.

The problem was that I ran at a speed my own understanding never caught up to.

It runs, next. It runs, next.

No spec. No design doc. The file layout was whatever occurred to me in the moment, function responsibilities stayed vague, and the feature count kept climbing. No tests at all. I sprinted in "just make something that works, fast" mode for about half a year.

My judgment got lazier as I went. "I think I wrote this already," I would think, and then searching the old files felt slower than asking the AI to write it again, so I asked again. That is how the same logic ended up in three places. That is where the duplicate-definition mess was born.

I still do not think using AI was the mistake. Without that speed, the tool would never have reached "done" at all. The mistake was quieter than that. While the AI wrote, I stopped acting as a reviewer and turned into a copy-paste middleman. I gave away the one job that was actually mine, deciding whether the code was any good.

The AI of early 2025 is not the AI of 2026

One more thing worth being honest about.

AI coding in 2025 had not matured into what it is now. The models I leaned on were strong for their moment, but a step below today's. The quality of the code, and the ability to hold a structure together across a project, were simply different.

Ask for the same thing in slightly different words and you got completely different code. It did not remember the previous design. Ask it to refactor one function and it would rewrite two neighbors along the way, and I would lose time diffing to work out what had even changed. Context windows were shorter, so pasting a long file left the AI quietly working from the first half only. I did not notice. I talked to it as though it had read the whole file, and many of its answers assumed just the top of it. Some of today's dead code almost certainly comes from places I waved through on "it runs, so fine."

Run a long project with an AI like that, and the code turns to spaghetti on schedule. I never adapted my style to the AI's quirks. Every new feature got a new session and a new file. "Start fresh" instead of "continue from last time," again and again, until the design had no through-line left.

Today's agents hold long context and reason across files. Ask for a feature and they read the project first, reuse an existing function when one fits, and follow the existing naming when one does not. The design consistency I fought for a year ago is now carried, in part, by the tool itself.

Code written with the AI of early 2025 still carries that era's limits, set in amber. I could hand it to a current model and say "clean this up," but the cleanup might quietly take the original behavior with it, so I have not pulled that trigger yet.

None of this is the AI's fault. Running without understanding its quirks was mine. I only wish the version of me who saw "AI coding is fast" had also seen the bill that comes due later.

How I am dealing with it now

Honestly, I am not, not yet.

There is too much source, and I am still working out where to even start reading. This is a long way from "jump in and fix it."

Here is the plan.

First, have a current AI read the whole codebase and give me a map, what each file does and where each function gets called, written back in something I can actually read. The starting prompt is roughly "list the five main files in this project and describe each one's responsibility in one short sentence." Having an AI explain code an AI wrote is an odd loop to stand in, but right now it is the most realistic move I have.

Next, hunt down and delete the dead code. That part is greppable, and static analysis catches it fast, PHPStan or Psalm on the PHP side, ESLint rules on the JavaScript side, flagging unused methods and unreachable blocks. I never ran any of it back then, so step one is simply getting the project to pass through the tools at all.

Then reorganize by feature. Right now channels, DMs, and threads share a file in some places and scatter across files in others. I want one feature per file or directory, channel/, dm/, thread/, notification/, attachment/, holding only what each one needs.

Only after that will I be ready to write a spec. Read the code, infer what past me was trying to do, and reconstruct the spec after the fact. This is the part I dread. "What did I build this for" is going to land on me more than once while I write it.

No deadline. I will chip at it between paying work. It might take half a year, or I might decide to rebuild from scratch. Rebuilding turning out faster is a common enough ending in real life.

Notes to my future self

I am writing this down now, because if I do not, I will do it all again.

Write a spec for each feature, however small, what this channel can do, when this notification fires, in plain language. When "I think I wrote this already" shows up, go find it instead of regenerating it. Keep an AI session continuous within a feature instead of opening a fresh one every time. And read what the AI writes as a reviewer, not a middleman.

That last one is really the whole thing.

The speed was real, and I would use AI the same way again. I would just stay in the chair as the person who decides what is good, instead of handing that chair to the model and reducing myself to the one who copies and pastes.

A reworked English version of a post I first wrote in Japanese.

The WordPress AI Client silently dropped my chat history — and threw no error

Rapls — Thu, 28 May 2026 23:28:55 +0000

Verified on WordPress 7.0 RC3, and re-confirmed on the 7.0 stable release. PHP 8.3.30. Because I implemented this against RC3, I'm writing with the assumption that the AI Client API may still move — but the behaviors described here (with_history()'s type, the role enum, the decryption-notice path) were identical between RC3 and stable.

WordPress 7.0 shipped with the AI Client built into core. If a site admin wires up a provider in Connectors, a plugin can reach the model behind it without carrying any API keys of its own.

My chatbot plugin used to carry OpenAI, Claude, Gemini, and OpenRouter itself — encrypting each provider's key, picking models, normalizing responses. I wrote that whole layer by hand. The 7.0 AI Client was an offer to hand that layer to the platform. I wanted to take it: keys and models, out of the plugin, into Connectors.

There was one tension. Most users are still on pre-7.0 WordPress. I could add a new provider, but I couldn't break a single line on older installs. The new path had to lie dormant on top of an AI Client that doesn't exist yet.

The migration itself should have been just accepting the offer: detect, connect, stay asleep on old environments. Not hard, I thought.

What actually ate my time was none of those. It was a single spot.

Passing history to `with_history()` — that one spot

It was passing the conversation history to with_history(). That's where I fell, twice.

The first fall was the loud one. The plugin keeps history as a plain ChatML-style array — ['role' => 'user', 'content' => '…']. I passed it straight through.

// the plugin's internal history (a plain ChatML-style array)
$history = [
    ['role' => 'user',      'content' => "What's the weather in Tokyo?"],
    ['role' => 'assistant', 'content' => "It's sunny."],
    ['role' => 'user',      'content' => "And in Osaka?"],
];

$response = wp_ai_client_prompt( "And in Osaka?" )
    ->with_history( $history )   // passing the array as ONE argument
    ->generate_text();

This doesn't work. The AI Client's withHistory() is withHistory( Message ...$messages ) — a typed variadic that expects a sequence of Message objects. Hand it one raw array and it tries to bind that array to $messages[0], which raises a TypeError (array given, Message expected).

I half-expected the WordPress wrapper to catch this. It doesn't. WP_AI_Client_Prompt_Builder::__call only catches Exception. A TypeError is an Error, not an Exception, so it sails right past the catch and blows up loudly. Which, it turns out, was the kind of failure I should be grateful for. You notice it immediately.

The second fall was the quiet one.

Having crashed loudly, I wrote code that builds Message objects correctly: fold roles to user/model, wrap each text in a MessagePart, put that in an array, pass it to UserMessage/ModelMessage, and finally spread it into with_history().

use WordPress\AiClient\Messages\DTO\UserMessage;
use WordPress\AiClient\Messages\DTO\ModelMessage;
use WordPress\AiClient\Messages\DTO\MessagePart;

private function apply_history( array $history ): array {
    $messages = [];
    foreach ( $history as $turn ) {
        $text = (string) ( $turn['content'] ?? '' );
        if ( '' === $text ) {
            continue; // skip empty turns
        }
        $part = new MessagePart( $text );          // a single string => a text part

        // fold everything that isn't "user" into "model" (two-value coercion)
        $messages[] = ( ( $turn['role'] ?? '' ) === 'user' )
            ? new UserMessage(  [ $part ] )
            : new ModelMessage( [ $part ] );
    }
    return $messages;
}

$messages = $this->apply_history( $history );
$response = wp_ai_client_prompt( $latest_user_text )
    ->with_history( ...$messages )   // spread into the variadic
    ->generate_text();

(For readability I'm using use here. The production code references MessagePart etc. by string class name behind class_exists() — it actually checks all three of MessagePart / UserMessage / ModelMessage — so the file doesn't fatal on pre-7.0 sites where the DTO classes don't exist. That guard is exactly what sets up the real trap.)

One honest note about the role folding. Collapsing everything non-user into model isn't sloppiness; it's a bet leaning on an assumption. The AI Client's role enum has only two values, user and model. System goes through a separate path (using_system_instruction), and system messages are split off upstream — so what reaches apply_history() is effectively just user and assistant/bot. The two-value coercion holds. But it holds because of that assumption. If an input ever violates it, a system turn silently becomes a model turn. Safe today — but the safety lives in the precondition, not in the code.

And the real trap was past this point.

I had the marshalling right. Build the Message, wrap it, spread it. The first-fall TypeError was gone. Relaxing there was how I walked into the second fall.

The production code wraps that same marshalling in a try/catch. The reason is pre-7.0 compatibility: old WordPress doesn't have the AI Client DTO classes, so if anything throws mid-build, I don't want to fatal the whole site. So I check class_exists() for the DTOs, wrap the whole construction in try/catch(\Throwable), and if anything goes wrong, abandon the history entirely and move on.

// production structure (simplified)
if ( ! class_exists( $message_part_class ) ) {
    // …log only when WP_DEBUG…
    return; // return without building history
}

try {
    // …build MessagePart / UserMessage / ModelMessage and call with_history() …
} catch ( \Throwable $e ) {
    // …log only when WP_DEBUG…
    return; // return without building history
}

The design is sound. Better to drop the context once and still answer than to crash on an old install. That was the call. The problem is that this defense never tells anyone it gave up.

apply_history() returns void. When it takes the skip path, with_history() is never called. What's left on the builder is the system instruction plus the single latest turn that went into wp_ai_client_prompt(). generate_text() returns 200 like nothing happened. The conversation looks fine. It just doesn't remember two turns ago. No error log. No exception. The response is valid. The only thing missing is the context.

And the thing that actually fires in production isn't the class_exists() branch. Once wp_ai_client_prompt() exists, the AI Client is loaded, so the DTOs autoload fine. class_exists() going false is the latent trap — for when the SDK moves a namespace or changes structure down the line. The branch that actually drops history is try/catch(\Throwable): if the SDK's signature shifts even a little (the UserMessage argument shape, the with_history type, the role enum), the marshalling you wrote correctly throws, gets caught here, and the history quietly disappears.

Here's the clincher on the silence. Both skip paths log only inside if ( defined('WP_DEBUG') && WP_DEBUG ). Production has WP_DEBUG off. So the defensive code does write a log — and the log itself goes silent in production. The safety net swallows the failure, and the alarm that was supposed to announce it is switched off behind a flag. The well-meaning defense muted itself twice. The failure happens. The signal that it happened goes nowhere.

The difference between the first fall and the second was, in the end, the guard itself. The unguarded minimal repro crashes with a TypeError and you notice immediately. The guarded production code swallows the same failure and calmly returns a response with the context stripped out. Crashing would have been the kinder behavior.

How I actually noticed this — I no longer have the exact record. But my verification notes from the time had "multi-turn conversation returns a reply that accounts for earlier turns" standing as its own checklist item. This is the kind of break that doesn't show up in unit tests and only surfaces when you talk to it across several turns by hand, so I suspect I hit it somewhere in that manual check.

The keyless provider broke an assumption the whole plugin was built on

Past the silence of with_history(), a completely different kind of problem was waiting. Not about types. The AI Client broke an assumption the entire plugin held without anyone ever writing it down: every provider has an API key inside the plugin.

wpai hands its key off to Connectors. There is no wpai API key inside the plugin. That one fact surfaced from places I never expected. From the shallow end:

The shallowest hole: the settings schema

First it was just teaching the schema a new provider. Without wpai in the allowlist, in_array rejects it and the selection resets (an invalid value falls back to the previously saved value, or openai if none). Add wpai_model to sanitize, give it an empty default. The dull kind of work that breaks if you forget it.

But there's something to notice here. Every other provider has both _api_key and _model. wpai has only _model.

openai     :  openai_api_key      +  openai_model
openrouter :  openrouter_api_key  +  openrouter_model
wpai       :  (no key field)       +  wpai_model

There is no wpai_api_key anywhere. Being keyless is visible as a hole in the settings schema — the quietest tear in the "every provider has a key field" assumption. At this point I didn't realize it was the omen of the two below.

The middle: the REST pre-check

The chat REST pre-check decrypts the active provider's key before the call and, if it's empty, returns 400 api_key_missing and bails early. "Confirm the key exists before calling." Reasonable — no point shipping a request to the model without a key.

wpai doesn't fit that. Having no key is normal for it, so I wrapped the whole pre-check in a name-based exempt: not a capability test, just !== 'wpai'.

What happened there wasn't only an exemption — it was a move of the availability check. Other providers verify availability "before the call, by key." wpai verifies it "at call time, by Connector availability," delegated to is_supported_for_text_generation(). The same "is this usable?" question shifted from a key-existence check to a call-time capability check. An assumption learned an exception.

The deepest: the decryption-failure notice

This is the heart of the chapter. An admin notice, "Failed to decrypt the API key," was misfiring for wpai users. At first I thought it was a gap in my wpai handling. It wasn't. wpai only dragged into the light something that had been broken for far longer.

The misfire was a three-step chain. A migration routine that runs every time the settings page loads (maybe_migrate_legacy_keys()) sweeps every provider's key. Inside that loop, it called a decrypt wrapper that raises a global transient on failure. And the notice's display check looked only at that transient plus a capability — and displayed unconditionally. It never asked which provider failed, or whether that provider was the active one.

So: a user who switched to OpenAI still has an old Claude key sitting around that can no longer be decrypted after a salt change. They open the settings page. The migration touches that dead key, a global alarm goes up. They're running OpenAI just fine, but they catch a "decryption failed" because of a Claude key they abandoned. The alarm is ringing correctly. It's just pointing at the wrong thing. The signal is emitted — but the truth it points to is the wrong truth.

Here's what clicked. This misfire was never a bug wpai introduced. It became possible the moment the design allowed multiple providers' keys to be stored at once — one active provider, but any old key could raise the global alarm. Nobody hit that path, so nobody noticed. Adding a keyless provider, and finally asking "whose key is this, and is it the active one?", was what surfaced it.

So I didn't fix it by adding a wpai exception. I generalized the display check into a four-gate test.

// notice display check: "is the ACTIVE provider's own key actually the problem?"
if (active === 'wpai')                        return;  // (1) keyless => plugin-side key is irrelevant
if (active's *_api_key is empty)              return;  // (2) never set
if (active's own key decrypts fine)           return;  // (3) failure belongs to some other unused provider
// (4) only here: the active provider's own key is genuinely broken
show_notice();

=== 'wpai' isn't a tacked-on exception. It's the first branch of the question "is the active provider's own key actually the problem?" The ordering itself says so.

The takeaway, I think, is this. Adding a new abstraction doesn't just cost you N new exceptions. Sometimes it surfaces the fact that an invariant was never holding in the first place. wpai broke one of my two unspoken assumptions — "every provider has a key" — and taught me the other one, "a decryption failure means the one key is broken," had been false all along.

The assumption that "every provider has an API key" was false from the start.

Retrying once on the `temperature` 400

That was the heavy stuff. The last one is a humbler move, worth recording.

When the model behind Connectors is GPT-5 or an o-series, it won't accept a custom temperature and returns 400. Those models have a fixed temperature, so the value you specify gets rejected. Known behavior.

The handling is grubby. If the first generation returns an error, and the error body contains the word temperature, and I actually specified a custom temperature — only when all three line up, I strip temperature and send once more.

// first attempt: with temperature
$text = $this->build_prompt($prompt, $system, $history, $options, false)->generate_text();

// only if the error body contains "temperature" AND I set a temperature: drop it and retry, once
if (is_wp_error($text)
    && stripos($text->get_error_message(), 'temperature') !== false
    && isset($options['temperature'])
) {
    $text = $this->build_prompt($prompt, $system, $history, $options, true)->generate_text();
}
// no loop, no recursion, no flag. "exactly once" is guaranteed by the structure.

The humbleness is in two places.

One: the decision is a substring match on a human-readable message, not a structured code. stripos just fishes for the word temperature. It bets on the wording of the message, not a stable contract like an error code. The third isset guard pulls its weight — if a temperature error shows up when I never set one, it won't waste a retry.

Two: there's nothing watching to enforce "exactly once." No loop, no recursion, no retry flag. The retry is a single if block, and the strip is build_prompt() with $skip_temperature = true, which omits the using_temperature() call entirely — not resetting to 1.0, just dropping the parameter and deferring to the model default. Straight-line code, so there's nothing to bound.

But, to be honest: because this is a substring match on the error body, the day the SDK rewords or localizes that message, it stops working silently. A signal that arrives today, gone one day without telling anyone. It's a bet on a known, sufficiently stable quirk — made knowingly.

A note to my next self

The three sections are different stories — a story about types, about invariants, about a substring match. But re-reading them, the same shape runs underneath. In each one, the breakage happened. What went wrong was that the signal of it had come apart from the truth.

Pass a raw array to with_history() and it crashes loudly. But wrap it in a compatibility defense and the failure starts quietly dropping the history, and the log that would say so never reaches anyone behind WP_DEBUG. The signal is absent. The decryption notice is the inverse: the alarm rings fine — it just points at an old key you don't even use anymore. The signal points at the wrong truth. The temperature substring match works today and, the day the SDK rewords the message, stops working without a word. The signal vanishes.

In every case, the breakage didn't get communicated correctly.

To write this, I went looking for how I noticed all this at the time. I re-read the code, traced the commit log, checked the records of my work sessions and the verification notes I'd left. Nothing. The moment of noticing isn't recorded anywhere. What remained was the way I'd written the defensive comments and where I'd placed the try/catch — the marks left in the code, and only those.

What carried my past self's decisions to my future self wasn't memory. It was the code.

If that's true, then the defensive code and comments I write today are a note to a self who will have forgotten all of it. Not a resolution — just a fact. So:

Give the safety net an alarm that actually rings. Don't hide the log behind WP_DEBUG. When you fall back to a default — dropping history, folding a role, swinging at a string — leave a mark so the fallback can be heard. What breaks quietly also robs you of the chance to fix it quietly.

The next self to open this will probably remember none of it. The only thing that remembers is the code.

Originally published on raplsworks.com. The broader read on the WP AI Client API and the migration plan for this plugin is in the companion piece.

Building "あ" -> "雨": Japanese Suggest Without IME Access

Rapls — Sun, 19 Apr 2026 03:55:46 +0000

This article was originally published on my blog (Rapls Works) in Japanese. I've translated and adapted it for dev.to readers, with extra context for non-Japanese audiences.

You've probably seen this: type あ into Google's Japanese search box, and you instantly see kanji suggestions — 雨 (rain), 赤 (red), 青 (blue), 秋 (autumn). Nice UX. So I tried to build it on my own site.

My first instinct: "I'll just read the IME's conversion candidates from JavaScript."

Turns out, that's impossible by design. Browsers deliberately hide IME internals from the DOM, for some very good security reasons we'll get into.

So I had to route around it. The trick is to maintain your own {kanji, reading} dictionary and do a prefix search against the reading field in hiragana. Instead of piggybacking on the IME, you ignore it and build your own lookup.

Bonus: the techniques in this post apply to Chinese, Korean, and Vietnamese input too — anywhere the browser's composition API is involved.

TL;DR

IME candidates are unreachable from JavaScript for privacy reasons
Build your own reading dictionary and do startsWith prefix search
Use compositionstart / compositionend to gate searches during IME composition
Debounce (~150ms) to avoid flicker during consecutive confirmations

Tested on Chrome 147 / macOS Tahoe 26.4 / ES6+ (April 2026).

Why You Can't Read IME Candidates

Short answer: IMEs run at the OS level, and browsers intentionally don't expose their internal state to JavaScript. This is a security and privacy decision.

Think about it. If a website could read your IME's suggestion list, it would see what you're about to type before you confirm it. Worse, IMEs have learning features — they remember family names, addresses, and employer names you've typed before. Leaking that to websites would be a huge privacy problem.

What browsers give you instead: just two signals — whether composition is in progress, and whether it's finished. Nothing about the candidates themselves.

So you need a different approach.

Mental Shift: "Conversion" → "Search"

Forget the IME. Maintain a dictionary of {text, reading} pairs yourself, and do prefix matching on the reading.

Dictionary:
  { text: "雨",   reading: "あめ" }   // rain
  { text: "赤",   reading: "あか" }   // red
  { text: "青",   reading: "あお" }   // blue
  { text: "秋",   reading: "あき" }   // autumn

Input "あ"   → all readings starting with "あ" match → 雨, 赤, 青, 秋
Input "あめ" → only readings starting with "あめ" → 雨

Japanese words are typed from the first character onward, so prefix search fits naturally. The candidate list narrows as the user types — exactly how Google's suggestions feel.

Three pieces to build: dictionary, search logic, UI. Let's go.

The `input` Event Misfire Problem

If you're coming from building English autocomplete, you're used to just listening to input. That doesn't work here.

When typing あめ via the IME, a, m, e keypresses fire the input event three times before confirmation:

1. Press "a"     → input fires (field: "あ")    ← not confirmed
2. Press "m"     → input fires (field: "あm")   ← not confirmed
3. Press "e"     → input fires (field: "あめ")  ← not confirmed
4. Press Enter   → input fires (field: "あめ")  ← confirmed

If you search on every input, you'll flash candidates at あ, clear them at あm, flash them again at あめ, then settle at あめ. The UI jitters horribly.

The Fix: `compositionstart` / `compositionend`

Browsers expose three events for IME composition state:

compositionstart — IME composition begins
compositionupdate — composition text changes (e.g., romaji → hiragana)
compositionend — composition finishes (user confirms)

The right place to trigger search is compositionend. Search only on confirmation, and the misfire problem is gone.

Cross-Browser Caveat

e.isComposing on the input event can be unreliable, particularly on older Safari and iOS. Keep a manual flag as a backup:

const input = document.getElementById('searchInput');
let isComposing = false;

// Composition start → set flag
input.addEventListener('compositionstart', () => {
  isComposing = true;
});

// Composition end → clear flag → search
input.addEventListener('compositionend', () => {
  isComposing = false;
  performSearch(input.value);
});

// Input event → skip if composing
input.addEventListener('input', (e) => {
  if (e.isComposing || isComposing) {
    return;  // noop during composition
  }
  performSearch(e.target.value);  // non-IME input (e.g., English)
});

The double check e.isComposing || isComposing absorbs browser differences. Works on Chrome, Firefox, Safari, Edge.

Debounce: Stop Flicker on Consecutive Confirmations

We've fixed composition. Next problem: consecutive confirmations.

Typing 天気予報 (weather forecast) typically happens as two IME confirmations: てんき then よほう. If we search on each, the てんき results flash and disappear. Useless flicker.

Debounce: wait for input to stop changing for ~150ms before running the callback. While the user keeps typing, reset the timer. When they settle, run once.

function debounce(func, delay) {
  let timeoutId = null;

  return function(...args) {
    if (timeoutId !== null) {
      clearTimeout(timeoutId);
    }
    timeoutId = setTimeout(() => {
      func.apply(this, args);
    }, delay);
  };
}

const debouncedSearch = debounce(performSearch, 150);

100–300ms is typical. 150ms hits the sweet spot for local searches (dictionary in memory) — essentially instant to the user.

Prefix Search

function searchByReading(query) {
  const q = query.toLowerCase().trim();
  if (!q) return [];

  // Match on reading OR on the text itself
  let results = dictionary.filter(item => {
    return item.reading.startsWith(q) ||
           item.text.toLowerCase().startsWith(q);
  });

  // Exact matches first, then prefer shorter readings
  results.sort((a, b) => {
    const aExact = a.reading === q || a.text.toLowerCase() === q;
    const bExact = b.reading === q || b.text.toLowerCase() === q;
    if (aExact && !bExact) return -1;
    if (!aExact && bExact) return 1;
    return a.reading.length - b.reading.length;
  });

  return results.slice(0, 10);
}

We match both reading and text so アメリカ (America, in katakana) matches on both あめりか (hiragana) and アメリカ.

Sort by exact match first, then prefer shorter readings (more specific). Cap at 10 — too many options hurts usability.

Don't Skip HTML Escaping

Injecting dictionary entries into the DOM without escaping opens an XSS hole. Even if your dictionary is 100% under your control today, you'll likely add user-submitted entries or API data later. Escape from day one.

function escapeHtml(text) {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

// When inserting into DOM
li.innerHTML = `
  ${escapeHtml(item.text)}
  ${escapeHtml(item.reading)}
`;

textContent + reading back via innerHTML auto-escapes <, &, etc. Boring but essential.

All Together

// === Dictionary ===
const dictionary = [
  { text: '雨',       reading: 'あめ' },
  { text: '赤',       reading: 'あか' },
  { text: '青',       reading: 'あお' },
  { text: '秋',       reading: 'あき' },
  { text: '朝',       reading: 'あさ' },
  { text: 'アメリカ', reading: 'あめりか' },
  { text: '天気',     reading: 'てんき' },
  { text: '天気予報', reading: 'てんきよほう' },
  // ... customize for your domain
];

// === Utilities ===
function debounce(func, delay) {
  let timeoutId = null;
  return function(...args) {
    if (timeoutId !== null) clearTimeout(timeoutId);
    timeoutId = setTimeout(() => func.apply(this, args), delay);
  };
}

function escapeHtml(text) {
  const div = document.createElement('div');
  div.textContent = text;
  return div.innerHTML;
}

// === Search ===
function searchByReading(query) {
  const q = query.toLowerCase().trim();
  if (!q) return [];

  let results = dictionary.filter(item =>
    item.reading.startsWith(q) || item.text.toLowerCase().startsWith(q)
  );

  results.sort((a, b) => {
    const aExact = a.reading === q || a.text.toLowerCase() === q;
    const bExact = b.reading === q || b.text.toLowerCase() === q;
    if (aExact && !bExact) return -1;
    if (!aExact && bExact) return 1;
    return a.reading.length - b.reading.length;
  });

  return results.slice(0, 10);
}

// === Main ===
const input = document.getElementById('searchInput');
let isComposing = false;

input.addEventListener('compositionstart', () => { isComposing = true; });
input.addEventListener('compositionend', () => {
  isComposing = false;
  updateSuggestions(input.value);
});

function updateSuggestions(query) {
  const results = searchByReading(query.trim());
  console.log('Results:', results);
  // → next step: render UI
}

const debouncedUpdate = debounce(updateSuggestions, 150);

input.addEventListener('input', (e) => {
  if (e.isComposing || isComposing) return;
  debouncedUpdate(e.target.value);
});

Verify the Behavior

Typing あめ via IME and confirming:

1. Press "a"      → compositionstart → isComposing = true
2. input event    → skipped (isComposing is true)
3. Press "m", "e" → same, skipped
4. Press Enter    → compositionend → isComposing = false → updateSuggestions('あめ')
5. Results: [{ text: '雨', reading: 'あめ' }, { text: 'アメリカ', reading: 'あめりか' }]

Typing test without IME:

1. No compositionstart → isComposing stays false
2. input event → debouncedUpdate called
3. 150ms later → updateSuggestions runs

Both paths work correctly.

Works for CJK, Not Just Japanese

One thing worth calling out: this same pattern works for Chinese, Korean, and Vietnamese too. The composition events are defined at the browser level, not specific to Japanese. If you're building a multilingual input UX, the same compositionstart / compositionend logic covers all CJK-family input.

Next: The UI Layer

At this point we have the brain — IME handling + search logic. The body — dropdown UI, keyboard navigation (↑/↓/Enter/Escape), focus management, click handling — is coming in the follow-up.

The sequel will also cover server-side integration, external API patterns, and performance tuning (trie structures, Web Workers for >10k entry dictionaries).

👉 Part 2 (originally in Japanese, code blocks in English): Japanese Suggest — Full Version: Keyboard Operations, blur Pitfalls, API Integration

Related deep-dive — I also wrote about a weird macOS bug where the first character of Japanese input sometimes commits as English. It's a good look at how IME composition interacts with OS-level input handling:

👉 The "First Character Stuck in English" Problem on macOS

Summary

"あ → 雨" is solved with prefix search on readings, not IME conversion. IME candidates are off-limits to browsers, so maintain your own dictionary and use startsWith for matching.

The Japanese-specific challenge is coexisting with the IME. Use compositionstart / compositionend to gate searches, and add debouncing to prevent flicker. Put those together and you have autocomplete that feels native to Japanese input.

Have you built Japanese or CJK autocomplete before? I'd love to hear about your approach — especially if you've tackled this with a larger dictionary (Trie/WFST structures, etc.) or with a server-side lookup. Drop it in the comments.

This post was originally published at Rapls Works. If you're into WordPress plugin development, Japanese i18n, or edge-case IME behavior, there's more over there.