Implementation of EPUB CFI FragmentSelector

[llemeurfr]

In https://github.com/readium/annotations?tab=readme-ov-file#132-selector we specify the use of the EPUB CFI FragmentSelector for EPUB files. But EPUB CFI implementations are sparse in the world of Reading Systems. What do we do then?

[HadrienGardeur]

I would strongly vote against using CFI as a requirement in this spec.

We've avoided CFI in Readium for several years now and we know that CFI support is inconsistent, not terribly well documented and unavailable in a number of languages that we rely on.

Sticking to other selectors or to widely adopted media fragments on the Web feels like the better option IMO.

A CFI attempts to mash together several pieces of information that are better expressed separately in our case:

• a path to a resource in the publication
• a path into the document tree of a resource
• character/temporal/spatial offsets

[mickael-menu]

Given we don't support reading CFIs in the Readium toolkits, I don't think we should require CFIs for the Annotations document.

[llemeurfr]

I don't disagree, but we need a selector that is a MUST for every implementation of the Annotation model. If not, interoperability will be totally broken.

[mickael-menu]

If it's required and we can't use text selectors, I'd rather have DOM ranges as the requirement for HTML-based publications.

[HadrienGardeur]

I think CSS selectors should be on the table as well for HTML-based publications.

[mickael-menu]

Yes but they are often not enough for a text selection.

[llemeurfr]

Just a note: if the W3C Publishing WG extends EPUB to support vanilla html5 (EPUB 3.4), because EPUB CFIs are tied to XML, they will become unusable on html5 content documents, unless the EPUB CFI spec is re-written accordingly.

[HadrienGardeur]

Another note: one cannot use EPUB CFI selectors on resources that are declared out of the spine.

It's an accumulation of issues with CFI that make them completely unfit for this purpose. Not being able to represent a progression/bookmark out of spine is acceptable, but disallowing highlights/annotations on out of spine items is more of an issue.

You've also heard Brady yesterday during the TPAC meeting: CFIs are a pain to deal with, that's reason enough to avoid them (like we've been doing successfully for years in Readium).

[llemeurfr]

The issue with resources that are out of the spine only exists because of the mandatory presence of the left part of the CFI expression. Remove the left part and the problem is gone.

[danielweck]

... and in general, EPUB "non linear" spine items (i.e. resources such as HTML documents explicitly referenced in the spine but marked as linear=no, or simply absent from the spine reading order but linked to from other documents) have an unclear processing model.
This under-specification has been the cause of subtly different interpretations and implementations of features that deal with documents in the context of "document set" / "document sequence": Media Overlays, TTS readaloud, annotations, layout/pagination, etc.

More to the point of discussion here: using a "full" epubcfi() expression in an annotation selector that is already associated with a specific document is arguably redundant, but that's how it is presented in the W3C specification (although frankly very underspecified anyway). A "partial" CFI expression would suffice. In fact at that point I would also argue that the "epubcfi(xxxx)" syntax is not only incorrect (because it is designed for "full" CFI including the OPF-to-HTML '!' indirection), it is also a waste of bytes because conformsTo already indicates what the value represents and essentially what a parser should expect. In my view, #epubcfi(xxx) is a syntax designed for embedding in URLs (so that the Fragment can tell the URL parser what it is), there's really no need for preserving this syntactic piece of information in payloads that already indicate what the data format is (anyway, that's just a minor grievance of mine :)

All that said, that's what the W3C spec. indicates we should do, so I would go with it no just to "play nice" but also for interop purposes: Apache, Hypothesis, etc. ... even if in the real world we all know how inconsistent CFI processing (generation and consumption) is! Even ignoring CFI for a moment, I personally feel uncomfortable with the choice of Unicode code points for text position selector, when character offsets in DOM Range and JavaScript are widely interpreted as code units (UTF-16/UCS2), which is why EPUB CFI aligned on code units too. I also struggle with the fact that unlike DOM Ranges (which is ultimately the arbiter of how we encode user selections and restore them from the serialisation format) the W3C annotation model text position selector doesn't explicitly reference the DOM text node the char offset applies to (this has to be inferred based on some underspecified text normalisation rules, potentially across element boundaries). The prefix/suffix + exact selector encoding is also underspecified (insignificant whitespaces collapsed? based on what heuristics?), compared with the more recent Google Text Fragment draft spec. which clearly highlights how complicated and subtle DOM text processing is (taking into account visibility, collapsibility/reveal)

[llemeurfr]

@danielweck the last part of your comment (from "I also struggle...") does not seem to be related to EPUB CFIs, but TextPositionSelector. It should be another discussion item.

[danielweck]

yes sorry for the rant, I just wanted to give additional context for a bigger picture of the tradeoffs.
overall I am not against CFI, no more than the other methods of expressing content selections.

[danielweck]

Useful links:

• https://github.com/fread-ink/epub-cfi-resolver
• https://github.com/vivliostyle/vivliostyle.js/blob/master/packages/core/src/vivliostyle/cfi.ts
• https://github.com/johnfactotum/foliate-js/blob/main/epubcfi.js
• https://github.com/futurepress/epub.js/blob/master/src/epubcfi.js -- https://github.com/futurepress/EpubCFI/blob/master/src/epubcfi.js
• https://github.com/readium/readium-cfi-js
• https://github.com/satorumurmur/bibi/blob/master/__src/bibi/extensions/epubcfi.js
• https://github.com/hypothesis/client/blob/main/src/shared/cfi.ts
• Colibrio? https://api-docs.colibrio.com/web/3.12.0/modules/colibrio_core_selector_epubcfi.html

Related discussions:

• Content iterator go-toolkit#82 (comment)
• CFI Validation w3c/epubcheck#150 (comment)
• Readium cfi and epubjs cfi futurepress/epub.js#1358 (comment)

[llemeurfr]

The alternative, as you said elsewhere @danielweck, is the VivlioStyle version, in ts, "seems robust as it is deployed in their web reader as a core mechanism to reference content".

[danielweck]

As mentioned previously in our internal Slack discussions, I think the VivlioStyle implementation is more likely to deliver the performance and robustness Thorium needs, and the code is more maintained / more modern than the old Readium codebase (which is based on a PegJS parser generator)

[llemeurfr]

After test, the VivlioStyle version does not handle ranges, only pointers. And it does not handle the index of the pointed resource in the EPUB OPF, therefore cannot be complete (which is a current requirement in the W3C Annotation Model). Therefore unusable.

[danielweck]

Just a clarification: the lack of support for OPF / spine item indirection is not a deal-breaker, because we would need to implement read/write (consumption and generation) of full CFI expressions anyway (including the left hand side part) in the application layer where the notion of publication / spine items exists.

What Thorium can benefit from is an off-the-shelf CFI parser+DOM-Range mapper, and CFI generator, both of which operate in webviews outside of the higher-level streamer/publication context (we're not even going to use a proper navigator to handle the W3C Annotations data model batch conversions at import/export time, a webview or a virtual DOM will suffice).

As for missing support for DOM Ranges in VivlioStyle's implementation, it is indeed a shame, and although it would be "relatively easy" to add parsing logic in their forked code, it will not be trivial (can of worms waiting to erupt) and frankly we have other pressing priorities at the moment than offering super-robust support for CFI (which, I predict, will exhibit broken interoperability with other reading systems even if internally Thorium's implementation is the most "correct" as per the specification).

[larscwallin]

Can we please just continue to work on the EPUBCFI specification. Spawning something new will with high likelyhood end up being something very similar to EPUBCFI once all stakeholders have had their say.

In reponse to your comment @danielweck on the redundancy of the OPF portion of the path, that is only a thing within the context of WebAnnotations. The EPUBCFI, being "canonical", needs to stand on it's own.

The wide spread adoption of EPUB is finally spreading outside the trade book sector. This is not the time to be pragmatic about topics of infrastructural importance.

And @llemeurfr regarding:

"We will then insist that EPUB CFIs are not considered in W3C work because the spec is terrible and must be re-written, ..."

It is not a terrible spec. Nor is it perfect. There are many parts that need clarification and examples, but it is very much a working technology. We have very much proven that this is the case.

I will endevor to make the code available for all to enjoy Q1 2025.

I would like to suggest that @danielweck have a chat with Andreas (who implemented our parser etc) for more details.
And also @llemeurfr, can you fix so that Andreas gets to be an invited expert in the EPUBCFI group?

Happy holidays everyone!