DEV Community: Esat Turan

Arabic letters stop joining the moment you split the word

Esat Turan — Sun, 06 Sep 2026 08:26:43 +0000

If you have ever rendered Arabic text in a browser and found the letters sitting apart like beads on a string instead of joined into a word, there is a good chance nothing is wrong with your font, your encoding, or your dir attribute. The chance is that something in your code split the string.

I hit this building right-to-left support for ReadKinetic, a speed reader that shows one word at a time. This post is what I measured, including the fix that is recommended everywhere and does not work.

Why splitting is the natural thing to do

Speed readers of the RSVP kind position each word by its optimal recognition point — a letter slightly left of centre that your eye should land on. The word is placed so that letter sits on a fixed mark, and because the mark never moves, your eye never has to.

The obvious implementation splits the word into three: everything before the pivot, the pivot, everything after. You right-align the first piece against the mark, put the pivot on it, left-align the last piece after it. You get exact positioning and a coloured pivot letter for free, because it is now its own element.

In Latin this is invisible. read cut into re, a, d renders identically to read.

In Arabic it is ruinous

Arabic letters are contextual. Most have four forms — isolated, initial, medial, final — and which one the shaper draws depends on the letters beside it. The letter ه is ه alone, هـ at the start, ـهـ in the middle, and ـه at the end. Same character, same code point, four shapes.

When you split a word into separate elements, each fragment is shaped on its own. The shaper has no idea the other pieces exist. A letter that should be medial is now the last letter of its fragment, so it is drawn in its final form, and the next fragment starts a new word as far as the shaper is concerned.

The word does not just look slightly off. It comes apart.

What it costs, measured

I took المكتبة (al-maktaba, "the library"), rendered it whole, then rendered it as three fragments split at the pivot, and measured both.

The fragments came out 11.8% wider than the same word drawn in one piece.

That extra width is the letters disconnecting. Joined Arabic letters share their connecting strokes; isolated and final forms each carry their own terminal, plus the tail that a connected form does not have. Eleven per cent is the visual difference between a word and a pile of letters.

It is also a good signal to test against, because it does not require you to read the script. If splitting a string changes its rendered width, the shaping changed.

Why this ships and stays shipped

Because it is invisible to the person who wrote it.

A developer who does not read Arabic looks at the output and sees Arabic-looking glyphs in the right order, right-to-left, in a reasonable font. Nothing about it says "broken". It takes a reader of the script about a quarter of a second, and they will usually screenshot it rather than file a bug, because explaining it is more work than it is worth.

So it survives review, it survives QA, and it ships. This is the general shape of the problem: the bug is silent to everyone empowered to fix it, and obvious to everyone affected by it.

The fix that is recommended everywhere

Search for this and you will be told to use U+200D ZERO WIDTH JOINER. Append it to the fragment before the cut and prepend it to the fragment after, and each fragment believes it has a neighbour, so the shaper draws connected forms.

For measuring, the same trick is supposed to let you ask "how wide is the first N letters of this word, as they will actually be drawn" by measuring the slice with a joiner stuck on the end.

I implemented it. Then I measured whether it had done anything.

const ctx = document.createElement('canvas').getContext('2d');
ctx.font = '48px "Geeza Pro", "Noto Naskh Arabic", serif';

const ZWJ = String.fromCharCode(0x200D);   // U+200D, the recommended fix

ctx.measureText('المك').width;               // 44.1
ctx.measureText('المك' + ZWJ).width;         // 44.1

Identical. To the tenth of a pixel, with and without the joiner. Canvas measureText was giving me the same number either way, which meant the joiner was not changing the shaping — it was being ignored.

And 44.1 is wrong. Measured in the DOM, where the browser shapes the complete word and I ask where the pivot actually landed inside it, the answer is 28.1 pixels. The canvas was placing my fixation mark sixteen pixels — more than half a letter — away from where the letter was going to be drawn.

Two failures stacked: the fragments were shaped wrong, and the measurement of them was wrong in the same direction, so nothing disagreed with anything and the whole thing looked like it worked.

Ask the browser instead

The only thing that knows where a letter will be drawn is the thing that draws it. So the word goes into a hidden element, complete and unmodified, and a Range over the pivot character reports where it ended up.

probe.textContent = word;                    // whole, never sliced
const range = document.createRange();
range.setStart(probe.firstChild, at);
range.setEnd(probe.firstChild, at + pivot.length);

const box = range.getBoundingClientRect();
const whole = probe.getBoundingClientRect();

// distance from the edge the word STARTS at, which in
// a right-to-left word is the right-hand one
const offset = direction === 'rtl'
    ? whole.right - box.right
    : box.left - whole.left;

The shaper sees a complete word, so it shapes it correctly, and the range reports the position of the pivot within that correct shaping. There is no fragment anywhere in this, which is the point.

Ranges force layout, so this is not free the way canvas is, and it is cached per word. In a reader showing fifteen words a second, the same words come round constantly, and the cache hit rate does the rest.

Then move the word instead of cutting it

With the offset known, the word never needs to be split at all. It is drawn whole in one element and translated so the pivot lands on the mark — the shift is the pivot's own centre, measured from the word's centre.

The shaper only ever sees a complete word. The reader still gets a fixed fixation point. Measured in the running app, the pivot lands within 0.01px of the fixation mark.

Colouring one letter without splitting the text

The remaining problem is that highlighting the pivot letter is also a split. Wrapping it in a span to colour it puts an element boundary inside the word.

It is worth knowing exactly which boundaries hurt, because they are not all the same. Measured just now in Chrome 148, on المكتبة at 48px:

what sits inside the word	rendered width
nothing — the whole word	136.28px
`<span>` around one letter	136.28px
`<span style="color:red">` around one letter	136.28px
three `display:inline-block` pieces	152.31px — 11.8% wider

So a plain or coloured inline span does not break shaping in current Blink. What breaks it is taking the pieces out of the inline flow — inline-block, a float, a block, or three separate elements positioned by hand, which is exactly what the naive RSVP implementation does.

I still did not want to rest on the span. Browsers have genuinely differed here — W3C ISSUE-358 is the working group arguing about whether cursive scripts should connect across inline boundaries at all, with the note that "browsers differ in their behavior" and Firefox possibly only joining when the font matches. A highlight that silently breaks a word on one engine is precisely the bug this whole exercise is about.

So the word is drawn twice. The lower copy is the word in its normal colour. The upper copy is the same word in the highlight colour, absolutely positioned in the same place, and clipped with clip-path: inset(...) to the pivot's own column — the left inset being the pivot's offset, the right inset being everything past it.

Both copies are complete words, shaped independently and identically, so they land on exactly the same pixels. The top one shows through only where the pivot is. One letter is coloured and nothing was ever cut.

What to take from this

If you are rendering Arabic, Persian or Urdu — the three joining scripts I handle — the rule is that a word is atomic. Anything that slices it changes what is drawn. That includes measuring it in slices, which is the version that will get you, because it fails silently and looks like arithmetic.

And do not trust the zero-width joiner without measuring whether it did anything. On canvas, in my testing, it did not.

Hebrew, for what it is worth, is the easy case. It runs right-to-left but its letters do not join, so the ordinary split-at-the-pivot machinery is correct for it with the geometry mirrored.

One honest caveat, which I also put on the Arabic and Hebrew feature page: all of the above is verified by measurement — glyph widths, pivot offsets, page mapping — and not by a person who reads the script. Those are not the same thing. If you read Arabic, Persian, Urdu or Hebrew and something looks wrong, I would genuinely like to hear about it.

Safari dropped my scroll because of a CSS fade on an ancestor

Esat Turan — Tue, 01 Sep 2026 13:09:34 +0000

On my iPhone the rendered pages in ReadKinetic would not scroll. I dragged my finger and nothing happened. Maybe two drags in ten actually did anything. The spots that worked? I could never find them twice in the same place. On Android Chrome it was perfect. I lost three days to this. Three entire days staring at a frozen page.

Two fixes that were right and did not work

A non-passive touchmove listener anywhere above a scroller takes it off the accelerated path. The browser can no longer scroll on the compositor because the handler might still call preventDefault. Every frame waits on JavaScript. Chrome absorbs that. Safari just gets annoyed and drops the scroll. I fixed it. Still broken.

Then I found #root/.app-mode { touch-action: none }. touch-action resolves by walking from your touched element up through every ancestor. One none on that path forbids the pan no matter what the scroller asks for. The shell is overflow:hidden and has nothing of its own to scroll, so it was forbidding a gesture it could not perform. I fixed that too. Still broken.

The fade was the bug

The reading surface had active:brightness-95 and transition-all. A CSS filter animating on touch, on an ancestor of the scroller.

A filter gives an element its own compositing layer. You start animating that filter the exact millisecond a finger lands, right above a scrolling box, and Safari decides to rebuild those layers mid-gesture. It drops the scroll it had already begun.

The sentence that solved it was my own bug report: "the page fades a bit like as if I am choosing it, and then it will not slide." The fade was not a symptom next to the bug. The fade WAS the bug. The drags that worked were just touches that happened not to trigger :active. That is why the working spot could never be found twice.

I shipped the fixes across three deploys. Commit e29359c relaxed the shell from touch-action: none to pan-y and gave every inner scroller pan-y too. Still broken. Commit 85f5d0d detached the non-passive listeners over the PDF surface. Still broken. Commit b5ff883 took the filter off that surface and dropped a legacy -webkit-overflow-scrolling: touch. Fixed. That isolation matters. Removing the filter is what fixed it.

There is a live, draggable reproduction of this in the original post.
Open it on an iPhone, drag the box with the filter on and then off, and compare the counts.
A desktop browser shows no difference — that is expected, this is a mobile compositing behaviour.

On my iPhone 16 Pro running iOS 26.6, with the filter off, every drag scrolled the box. With the filter on I had to try up to 25 times before one drag took. That is the part that surprised me. It is not a slower scroll or a janky one. Most of the time there is no scroll at all, and then one works for no reason you can see. Note that this is the box that fails, not the page around it, which scrolls fine throughout.

A bare version of that box, with no framework around it, is at readkinetic.com/repro/safari-filter-scroll.html.

Filed as WebKit bug 322849, under Compositing. Simon Fraser from the WebKit team answered the same day:

I believe this happens when we remove and re-add a UIScrollView to the view hierarchy as ancestor layers change.

That explains the part I could not. On iOS the browser does not scroll an overflow area itself. It hands the job to a real UIScrollView. Change the compositing layers above it and that view gets detached and put back, and a UIScrollView that disappears in the middle of a gesture takes the touch it was tracking with it.

So it is not a slow scroll or a dropped frame. For a moment the thing doing the scrolling does not exist. That is also why one drag in twenty five works. It depends on whether the view happened to survive that particular gesture.

The bug is open and unassigned. No fix, no timeline. But I know what I was looking at now.

The harder problem underneath

Honestly the Safari mess was secondary. Scrolling a page means absolutely nothing if the page does not know which words it holds. Everything in this reader is a word index. Your place, your marks, find, the chapters, the seek rail. A page image drawn beside the wrong words breaks the whole app. You tap a line and go somewhere else. Find highlights the wrong page. The rail lies.

Counting the words does not work

The obvious approach is walking the pages and keeping a running total. It drifts. The finished text splits differently from the way the counter assumed. A word broken across a line as "men-tion" gets rejoined into one word after the counter has already counted two. The error accumulates. The first page is right and the ninetieth is a paragraph out.

There is an interactive version of this in the original post — you can switch between counting and
matching and watch the pages land or drift: https://www.readkinetic.com/blog/how-a-pdf-page-knows-its-words

So the pages are found, not counted

I join pages with a blank line. This makes each page's opening words the opening of a paragraph. The reader already computes paragraphs. I match anchors against paragraph starts, searching forward from wherever the last page landed. Every match is local and cheap.

Then three things broke.

A page can open on a one-word paragraph

Every story opens "I. / A SCANDAL IN BOHEMIA / I. / To Sherlock Holmes she is always the woman." The first paragraph is the single word "I."

That can never match a four-word anchor. The page that begins a story never matched. Because each search starts where the last one landed, the failures compound. Page 41 of 306 reported it began at word 16.

Stranded after dialogue

The forward search looked twelve paragraphs ahead. I reasoned no page makes more than twelve. Two people talking makes thirty one-line paragraphs without trying. The page after a conversation was out of range before it was ever looked for.

What happens when a chapter matches the table of contents?

The first story page opens "I. A SCANDAL IN BOHEMIA". The contents page twenty words earlier reads "I. A Scandal in Bohemia / II. The Red-Headed League". The first four words are the same words.

So the story page matched its own entry in the contents, at word ten. The contents page was left spanning 1 word with 74 hit boxes stacked on it. It looked like the entire page highlighting at once when you tapped anything on it.

I changed the comparison to 8 opening words. They diverge at the sixth. I expanded the window to 64. Now 304 of 304 pages with a usable anchor land exactly on their own opening words.

One box per word, not one per line

pdf.js returns a text item per run. A run is usually a whole line. One hit box over that means tapping anywhere on a line goes to the line's first word. It reads like the page picked a paragraph instead of the word under your finger.

The file does not say where the words inside a run are. I mount a canvas to measure each word's offset within the run, scaled so the total matches the width the file reports.

Then each word is matched to a book index with its neighbours confirmed. A page holds "the" thirty times. A word is identified by its spelling and its neighbours' spelling, never by spelling alone.

Measured across four pages spread through the book: 370/370, 352/352, 374/374 and 296/296 boxes on consecutive indices. No duplicates. Nothing out of order.

Letterspaced titles

Letterspaced titles arriving as "T h e" are repaired per line, but only when ≥4 tokens and ≥80% are lone letters. A page of set theory is full of lone = and ∅, and welding those to their operands would break a book to fix a title. It changes exactly two lines in Sherlock.

The final cost

All parsing, rendering and storage happens client-side with no server. I use three IndexedDB stores (book_metadata, book_content, book_source) because figures living in metadata made the shelf load 8.2 MB per book.

A 1,390-page PDF opens and scrolls. Canvases mounted at any moment: 4 to 6, not 1,390. Pages are memoised. currentIndex is handed only to the page that holds it. The text layer is one hit surface per page with coordinate hit-testing, instead of roughly 1,700 absolutely positioned spans.

DOM nodes in the scroller dropped from 2,904 to 1,224. Median frame through a sustained scroll is 6 ms. p95 is 12 ms.

RSVP removes regressions and parafoveal processing. Comprehension falls off past roughly 500 wpm for anything longer than a sentence (Rayner et al., 2016). It works, but your brain has physical limits.