CSS: add support for pseudo element ::first-letter by poire-z · Pull Request #648 · koreader/crengine

poire-z · 2026-01-31T19:18:13Z

fb2def.h: add a few common attributes

Having them known and a fixed id can avoid stylesheet hash mismatches.

lvtext: includes `src->t.offset` in `word->t.start`

AddSourceLine() (used by lvrend to add text fragment) can be provided with a offset value indicating that some leading chars of the source text node should be skipped.
No code was ever providing an offset different than 0, so it didn't matter if things were a bit inconsistent.

We will use that offset to support CSS ::first-letter (in next commit) so make things consistent, with two simple facts:

really only add text starting at offset to m_text
word->t.start counts from the source text node, and not from the offset (which makes things simpler elsewhere, including when dealing with xpointers)

CSS: support for pseudo element `::first-letter`

Handled as another variation of the pseudoElem internal element we introduced to support ::before and ::after, so we benefit from its existing CSS parsing/checking/applying and styles inheritance.

Have it inserted just before the text node it should pick its first letter from, store in a FirstLetter= attribute how many chars should be picked from the next text node and rendered when we render that pseudoElem, and skipped when rendering the text node itself.

Known non-conformance to the CSS specs:

we don't limit which CSS properties can be used (the specs enumarate a subset of known properties).
we may apply it where we should not (ie. among inlines, propagate it from paragraph to a first inline-table...) (Firefox and Chrome already have different behaviours in this regard).
if there are a ::before and a ::first-letter, we won't pick the first letter from that ::before's content, and we will render the ::before BEFORE the first-letter picked from the following text.

First letters can be disabled with using
::first-leter { display: none; }
(display: being one of the property the specs say we should not support, we can use it to disable them with style tweaks.)

Should allow closing:
koreader/koreader#6944
koreader/koreader#9142
koreader/koreader#14391

Discussed in #646.
Done with the help of Github copilot by guiding it step by step along the idea I had in mind. Experience related in #646 (comment).
Full Copilot conversation/copiloting in poire-z#2 (140 conversation posts, 48 commits!...)

This change is

Having them known and a fixed id can avoid stylesheet hash mismatches.

AddSourceLine() (used by lvrend to add text fragment) can be provided with a 'offset' value indicating that some leading chars of the source text node should be skipped. No code was ever providing an offset different than 0, so it didn't matter if things were a bit inconsistent. We will use that offset to support CSS '::first-letter' (in next commit) so make things consistent, with two simple facts: - really only add text starting at offset to m_text - word->t.start counts from the source text node, and not from the offset (which makes things simpler elsewhere, including when dealing with xpointers)

poire-z · 2026-01-31T19:21:13Z

Keeping here the full description Copilot has updated in the top post of poire-z#2, for reference (some bits are not fully true or right).

Adds complete infrastructure for ::first-letter pseudo-element following the established ::after pattern. Creates pseudo elements with proper CSS selector matching and implements text rendering infrastructure.

Changes

CSS Parsing and Style Matching (`lvstsheet.cpp`)

Extended applyToPseudoElement() to handle csspe_first_letter cases
Simplified LVCssSelector::check() for FirstLetter by finding ancestor with HasFirstLetter attribute and delegating to standard checking code
Fixed LVStyleSheet::apply() to properly identify FirstLetter pseudo elements

DOM Element Creation (`lvtinydom.cpp`)

Added attr_HasFirstLetter attribute to mark elements requiring first-letter handling
Implemented ensureFirstLetter() method to consolidate FirstLetter creation logic
- Handles both initial DOM building and runtime stylesheet changes
- Inserts FirstLetter at textNodeIndex position (text shifts forward)
- Supports text nodes at any index (not limited to specific positions)
- Works with elements like  Text where text is at index 2+
Supports ::before and ::first-letter together with consistent ordering: ::before → ::first-letter → text
Added initStyle parameter to handle different contexts (DOM building vs stylesheet re-application)
Modified ldomElementWriter::onBodyExit() to create FirstLetter pseudo-elements
Fixed isBoxingNode() to respect exceptBoxingNodeId for pseudoElems
Fixed createXPointer() to avoid double-counting offsets
Fixed ldomXPointer::getRect() to handle FirstLetter pseudo-elements
Added helper methods getFirstLetterPseudoElem() and getFirstLetterTextNode() for code reuse
- Only checks previous sibling for FirstLetter detection (optimized)
- Works at any text node index
- Handles boxing nodes and display:none checking
- Reduces code duplication across multiple call sites

Text Formatting Infrastructure (`lvtextfm.cpp`)

Changed word->t.start to be absolute positions (including offset)
Updated buffer calculations and text copying to account for offsets
Fixed link detection and character replacement to use absolute positions

DOM Traversal and Text Rendering (`lvrend.cpp`)

Implemented FirstLetter handling in renderFinalBlock() and getRenderedWidths() using helper methods
Optimized setNodeStyle() to call ensureFirstLetter() before ensurePseudoElement(true) for early return optimization
Fixed getRenderedWidths() to handle ::before/::after text length
Factorized duplicated code using helper methods

Implementation Details

ensureFirstLetter() Method:

Inserts FirstLetter at position textNodeIndex (text node shifts forward to textNodeIndex + 1)
Works correctly when textNodeIndex == 0 (no pseudo-elements) or > 0 (after ::before or other elements)
Natural pseudo-element ordering: ::before → ::first-letter → text
Only checks previous sibling (index-1) for existing FirstLetter
Handles three contexts:
1. setNodeStyle during DOM building (sets attribute, returns if no children)
2. onBodyExit during DOM building (finds text node, creates pseudoElem)
3. Stylesheet re-application (creates pseudoElem if needed)
Avoids duplicate creation by checking for existing FirstLetter pseudo-elements

Helper Methods:

getFirstLetterPseudoElem(): Finds FirstLetter from text node, checks previous sibling, handles boxing nodes
getFirstLetterTextNode(): Finds text node following FirstLetter pseudo-element
Both methods check display:none and return NULL if not displayed

Pseudo-element Ordering:

Consistent ::before → ::first-letter → text ordering
::first-letter picks letter from text node (not from ::before content)
Simplified, non-spec behavior but more predictable
Performance optimized with early exit and single sibling check

XPointer Handling:

When offset < src->t.offset, pointer refers to FirstLetter text
Uses helper methods to find pseudo-element and handle rectangle retrieval
word->t.start stored as absolute position for consistency
Fixes text selection highlighting issues

display:none Support:

Users can disable with *::first-letter { display: none !important; }
FirstLetter elements remain in DOM but ignored during rendering
Centralized checking in helper methods

FirstLetter Scope:

Only applies when directly preceding text node or wrapped in boxing nodes
Regular inline elements not traversed (create own formatting context)

Selector Matching:

Finds ancestor with HasFirstLetter attribute
Delegates to standard rule-checking code
Eliminates code duplication

Text Offset Mechanism:

Buffer creation skips first N characters based on offset
Word positions stored as absolute (including offset)
XPointer offsets and word positions aligned

Frenzie · 2026-01-31T22:00:21Z

Now you can ask Copilot to review this PR. 😄

Frenzie · 2026-01-31T22:02:22Z

+// Misc other attributes commonly found in books (ie. with cover SVG wrappers)
+XS_ATTR( viewBox )
+XS_ATTR( preserveAspectRatio )
+XS_ATTR2( aria_hidden, "aria-hidden" )


Should a few others like aria-label/labelled-by also be added then? I don't think I've spotted any in the wild, but I have seen it advocated in for example https://www.tpgi.com/using-aria-enhance-svg-accessibility/.

If you feel like compiling those that feel like they can be found in books and providing the list, we can add them, there is room.

Frenzie · 2026-01-31T22:09:35Z

+                            if ( props & (CH_PROP_UPPER | CH_PROP_LOWER | CH_PROP_DIGIT | CH_PROP_SIGN) ) {
+                                // Found the start of the first letter
+                                foundFirstLetter = true;
+                                i++;


Would this be clearer in the foundFirstLetter block?

Can you be more explicite ?

When I looked at this I thought huh, that's funny, they both do i++. Which made me think I'd either put it before the condition:

while ( i < len ) { lUInt16 props = lGetCharProps(text[i]); i++;

Or like:

if ( props & (CH_PROP_UPPER | CH_PROP_LOWER | CH_PROP_DIGIT | CH_PROP_SIGN) ) { // Found the start of the first letter foundFirstLetter = true; // not here break; } i++; } // Now grab any trailing modifiers/punctuation that are part of the first letter if ( foundFirstLetter ) { // but here i++; while ( i < len ) {

But it's just a an idle thought, do whatever you prefer obviously. ^_^

Yes, I indeed prefer it written like you did.

Handled as another variation of the pseudoElem internal element we introduced to support ::before and ::after, so we benefit from its existing CSS parsing/checking/applying and styles inheritance. Have it inserted just before the text node it should pick its first letter from, store in a FirstLetter= attribute how many chars should be picked from the next text node and rendered when we render that pseudoElem, and skipped when rendering the text node itself. Known non-conformance to the CSS specs: - we don't limit which CSS properties can be used (the specs enumarate a subset of known properties). - we may apply it where we should not (ie. among inlines, propagate it from paragraph to a first inline-table...) (Firefox and Chrome already have different behaviours in this regard). - if there are a ::before and a ::first-letter, we won't pick the first letter from that ::before's content, and we will render the ::before BEFORE the first-letter picked from the following text. First letters can be disabled with using ::first-leter { display: none; } ('display:' being one of the property the specs say we should not support, we can use it to disable them with style tweaks.)

poire-z · 2026-02-01T08:18:13Z

To be bumped after next stable release.

poire-z added 2 commits January 31, 2026 20:03

fb2def.h: add a few common attributes

4f8b59f

Having them known and a fixed id can avoid stylesheet hash mismatches.

This was referenced Jan 31, 2026

Implement CSS parsing and pseudo element creation for ::first-letter poire-z/crengine#2

Closed

Tentative support for ::first-letter poire-z/crengine#1

Closed

Frenzie reviewed Jan 31, 2026

View reviewed changes

Frenzie approved these changes Jan 31, 2026

View reviewed changes

poire-z force-pushed the first_letter branch from 126ca27 to 2f60657 Compare January 31, 2026 23:17

poire-z merged commit fab44f6 into koreader:master Feb 1, 2026
1 check passed

poire-z deleted the first_letter branch February 1, 2026 08:03

This was referenced Feb 14, 2026

bump crengine: CSS enhancements and other fixes, improve text selection koreader/koreader-base#2270

Merged

bump base & crengine: CSS enhancements and other fixes koreader/koreader#14979

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CSS: add support for pseudo element ::first-letter#648

CSS: add support for pseudo element ::first-letter#648
poire-z merged 3 commits into
koreader:masterfrom
poire-z:first_letter

poire-z commented Jan 31, 2026 •

edited by Frenzie

Loading

Uh oh!

poire-z commented Jan 31, 2026

Uh oh!

Frenzie commented Jan 31, 2026

Uh oh!

Frenzie Jan 31, 2026 •

edited

Loading

Uh oh!

poire-z Jan 31, 2026

Uh oh!

Frenzie Jan 31, 2026

Uh oh!

poire-z Jan 31, 2026

Uh oh!

Frenzie Jan 31, 2026

Uh oh!

poire-z Jan 31, 2026

Uh oh!

Uh oh!

poire-z commented Feb 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

poire-z commented Jan 31, 2026 • edited by Frenzie Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

fb2def.h: add a few common attributes

lvtext: includes src->t.offset in word->t.start

CSS: support for pseudo element ::first-letter

Uh oh!

poire-z commented Jan 31, 2026

Changes

CSS Parsing and Style Matching (lvstsheet.cpp)

DOM Element Creation (lvtinydom.cpp)

Text Formatting Infrastructure (lvtextfm.cpp)

DOM Traversal and Text Rendering (lvrend.cpp)

Implementation Details

Uh oh!

Frenzie commented Jan 31, 2026

Uh oh!

Frenzie Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

poire-z Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Frenzie Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

poire-z Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Frenzie Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

poire-z Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

poire-z commented Feb 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

poire-z commented Jan 31, 2026 •

edited by Frenzie

Loading

lvtext: includes `src->t.offset` in `word->t.start`

CSS: support for pseudo element `::first-letter`

CSS Parsing and Style Matching (`lvstsheet.cpp`)

DOM Element Creation (`lvtinydom.cpp`)

Text Formatting Infrastructure (`lvtextfm.cpp`)

DOM Traversal and Text Rendering (`lvrend.cpp`)

Frenzie Jan 31, 2026 •

edited

Loading