BookShelves — Native EPUB Reader for macOS and iOS (looking for feedback)

[rfog]

I don't know how you are building the definitive CSS for each book, @QuietShelfLife, but as developer myself, I will start with an empty CSS. First step should be importing the ones in the ePub itself (yes, some ebooks have multiple CSS), skipping conflicts or starting with the biggest one and importing the others item by item, and finally import your own to complete the holes in the CSS ebook. Last step will be overwrite the customizations made by the reader in the app options.

That way I think you don't need to stay with custom optimizations. The only thing you need is a strong piece of code that will review and incorporate or overwrite the added sub-CSS options.

[QuietShelfLife]

@rfog That's essentially the approach — book CSS loads first, then app defaults fill in anything unspecified, and user settings override last. The issue JSWolf found is that our defaults were too aggressive in a couple of places (widows/orphans and line-height), overriding values the book already set. Fixing that now along with user-adjustable margins and line height. Should be in the next release.

[JSWolf]

Originally Posted by QuietShelfLife

@rfog That's essentially the approach — book CSS loads first, then app defaults fill in anything unspecified, and user settings override last. The issue JSWolf found is that our defaults were too aggressive in a couple of places (widows/orphans and line-height), overriding values the book already set. Fixing that now along with user-adjustable margins and line height. Should be in the next release.

I just installed a new release. It's still unreadable. I reported it again.

When you have no line height, YOU DO NOT SPECIFY ONE! You let the font do the work. Also, when there are no paragraph gaps specified, again the font does the work at going from one paragraph to another. When windows and orphans are specified to a value of 1, you don't have your own defaults override that because those defaults don't work.

As for the line height, this is what you do when you don't have a line height setting or it's turned off.

[rfog]

Originally Posted by QuietShelfLife

@rfog That's essentially the approach — book CSS loads first, then app defaults fill in anything unspecified, and user settings override last. The issue JSWolf found is that our defaults were too aggressive in a couple of places (widows/orphans and line-height), overriding values the book already set. Fixing that now along with user-adjustable margins and line height. Should be in the next release.

Then you have a bug in your code. If a later import/mix CSS overwrites some settings, it is doing it wrong except if you want that overwritten.

A working algorithm could be as easy as start with an empty dictionary data structure with a list in each node and then fill it with each CSS. Then you start with your full master CSS as dictionary with the selector as key, and the declaration block as a list of pairs. And then follow the reverse: starting with your full dictionary, go across low-to-high priority ebook and UI customizations, and for each selector in the other CSS, evaluate the declaration block and for each pair, if they are valid ones, replace or add it in the master CSS. No error can happen. If an ebook CSS contains widows and orphans, they will overwrite your own master CSS, and if not, it will respect master ones. And same with any other declaration pair for each selector.

[QuietShelfLife]

@JSWolf The fix for widows/orphans and line-height isn't in the current App Store version yet — that's why it still looks the same. When I said "next release" in my last post I meant the one I'm still building. I'll post here the moment it's on the App Store so you know which version to grab. My plan is to wrap the default in :where(), so the publisher CSS "wins". For line-height I'm still undecided, it will be user configurable.

@rfog Appreciate the suggestion — that's roughly the direction. The tricky part is knowing when a property is "missing" vs intentionally unset by the book, but a dictionary merge with priority levels is a clean way to handle it.

[JSWolf]

Originally Posted by QuietShelfLife

@JSWolf The fix for widows/orphans and line-height isn't in the current App Store version yet — that's why it still looks the same. When I said "next release" in my last post I meant the one I'm still building. I'll post here the moment it's on the App Store so you know which version to grab. My plan is to wrap the default in :where(), so the publisher CSS "wins". For line-height I'm still undecided, it will be user configurable.

@rfog Appreciate the suggestion — that's roughly the direction. The tricky part is knowing when a property is "missing" vs intentionally unset by the book, but a dictionary merge with priority levels is a clean way to handle it.

Thank you. I'll wait for the new version. I'll install the new version on my iPad Pro 13" and try it from there as well.

[JSWolf]

I notice there are new versions being released that have nothing to do with the rendering issues. Why are you working on things that are not nearly as important as proper rendering?

I just had a look at the CSS for the eBook I'm using to check the app and the CSS for <p> has a bottom margin of 0. So there should be no paragraph spaces.
CSS for <p>

p {
  margin-top: 0;
  margin-bottom: 0;
  text-indent: 1.2em;
  widows: 1;
  orphans: 1;
}

[QuietShelfLife]

Hi JSWolf,

Thanks for the specific CSS example — that's exactly what I needed. You're right: when a book sets margin-bottom: 0 on paragraphs, we should respect that.

I found the issue. We fixed the widows/orphans override back in 1.0.12, but the default paragraph margin (margin-bottom: 1em) still has the same problem — it's injected at normal specificity, which means it overwrites the publisher's zero margins due to cascade order.

The fix is the same approach: wrap it in :where() so publisher CSS always wins.

To your point about priorities — the recent releases (1.0.13–1.0.15) were crash fixes and iCloud reliability issues that were affecting a lot of users. Rendering is definitely not off the radar, and your reports are directly shaping what gets fixed.

[JSWolf]

Originally Posted by QuietShelfLife

Hi JSWolf,

Thanks for the specific CSS example — that's exactly what I needed. You're right: when a book sets margin-bottom: 0 on paragraphs, we should respect that.

I found the issue. We fixed the widows/orphans override back in 1.0.12, but the default paragraph margin (margin-bottom: 1em) still has the same problem — it's injected at normal specificity, which means it overwrites the publisher's zero margins due to cascade order.

The fix is the same approach: wrap it in :where() so publisher CSS always wins.

To your point about priorities — the recent releases (1.0.13–1.0.15) were crash fixes and iCloud reliability issues that were affecting a lot of users. Rendering is definitely not off the radar, and your reports are directly shaping what gets fixed.

I cannot read any books. The rendering needs to take top priority and these cloud crashes and wait. Once you get the rendering and settings for rendering fixed/added then you can work on cloud crashes. You have to do make rendering the priority and all else can wait.

[pdurrant]

Originally Posted by JSWolf

I cannot read any books. The rendering needs to take top priority and these cloud crashes and wait. Once you get the rendering and settings for rendering fixed/added then you can work on cloud crashes. You have to do make rendering the priority and all else can wait.

Well, those are your priorities. They may not be the priorities that make business sense.

[JSWolf]

Originally Posted by pdurrant

Well, those are your priorities. They may not be the priorities that make business sense.

Proper rendering does not make business sense? That doesn't make any sense. Proper rendering should the the top priority before all else.

[JSWolf]

This is becoming worse then silly. Why ad Mobi to an ePub reader? Mobi can be converted to ePub. And you are adding features and doing things that do not fix the main core problem. The problem is that the program is UNFIT FOR READING EBOOKS!

You are not fixing the main issue. All this other stuff is crap when the program cannot properly render eBooks.

[QuietShelfLife]

Fair pushback, Jon. To be specific about what 1.0.13–1.0.15 actually shipped, since "rendering vs. crashes" is a bit of a false split here:

• 1.0.13 — fixed a crash on iOS 26.3+ where Apple Intelligence indexing the PDF reader would take down the app. Users on the current iOS couldn't open PDFs at all. Also bounds-check fixes for malformed EPUB/ZIP archives (security).
• 1.0.14 — actually was rendering work: bundled STIX Two Math for proper MathML on iOS, cleaned up font stacks across all languages, switched CJK to serif so those books read like books.
• 1.0.15 — added HuffCDIC MOBI support (books that wouldn't open before now do), and fixed a freeze when importing large Calibre libraries — also a "can't read books" problem, just one rung earlier in the chain.

So the honest answer is: every one of those releases unblocked someone who also couldn't read. Your reports are next in the queue — the :where() wrap for the paragraph margin is in the build I'm preparing now, alongside the line-height control. I'll post here the day it's on the App Store with the version number so you can grab it directly.

[JSWolf]

Originally Posted by QuietShelfLife

Fair pushback, Jon. To be specific about what 1.0.13–1.0.15 actually shipped, since "rendering vs. crashes" is a bit of a false split here:

• 1.0.13 — fixed a crash on iOS 26.3+ where Apple Intelligence indexing the PDF reader would take down the app. Users on the current iOS couldn't open PDFs at all. Also bounds-check fixes for malformed EPUB/ZIP archives (security).
• 1.0.14 — actually was rendering work: bundled STIX Two Math for proper MathML on iOS, cleaned up font stacks across all languages, switched CJK to serif so those books read like books.
• 1.0.15 — added HuffCDIC MOBI support (books that wouldn't open before now do), and fixed a freeze when importing large Calibre libraries — also a "can't read books" problem, just one rung earlier in the chain.

So the honest answer is: every one of those releases unblocked someone who also couldn't read. Your reports are next in the queue — the :where() wrap for the paragraph margin is in the build I'm preparing now, alongside the line-height control. I'll post here the day it's on the App Store with the version number so you can grab it directly.

PDF and Mobi are just BLOAT for an ePub reader. While you are fixing some things, you're fixing the wrong things. The ePub rendering is still terrible. Please drop PDF and drop Mobi and fix the ePub rendering and then work on everything else (except adding useless formats).

[rfog]

Originally Posted by JSWolf

PDF and Mobi are just BLOAT for an ePub reader. While you are fixing some things, you're fixing the wrong things. The ePub rendering is still terrible. Please drop PDF and drop Mobi and fix the ePub rendering and then work on everything else (except adding useless formats).

Please calm down. It's his app, and he's prioritizing what he wants. He's being remarkably politically correct with you, considering how grumpy you are.

It's not just you and your almost absurd demands regarding CSS. If you're so keen on having perfect CSS, you can build an app too, especially now with vibe coding.