feat/nota comics by m-abs · Pull Request #94 · Notalib/flutter_readium

m-abs · 2026-04-08T12:58:27Z

feat(NotaComicBooks): handle nota comic books.
feat(NotaComic): Full page rendering
fix(android): location change were delayed, which broke animations
update comic css

…c mode

m-abs · 2026-04-08T15:31:23Z

Missing iOS part

Call window.flutterReadium.setSegmentDuration from synced narration
Update EPubPreferences to accept all readium values and the new blackAndWhiteComicMode
- Changes to blackAndWhiteComicMode should result in call to window.SetBlackAndWhiteMode(${preferences.blackAndWhiteComicMode})

Copilot

Pull request overview

Adds a new “Nota comic book” rendering path by moving comic handling into the injected Readium helper bundle, introducing full-page overlay rendering (with optional B/W mode), and wiring segment-duration-based panning to synced audio/navigation. Also refactors Android preference plumbing to a richer, typed FlutterEpubPreferences model and updates helper-scripts tooling/demo setup.

Changes:

Replace the legacy comics.* injected assets with a new NotaComicBookPage implementation bundled into flutterReadiumTools.*.
Add/propagate a blackAndWhiteComicMode preference and update Android preference parsing/storage to FlutterEpubPreferences.
Improve Android navigation/sync behavior (segment duration propagation, script/style injection filtering, and sync-audio locator handling).

Reviewed changes

Copilot reviewed 34 out of 36 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
flutter_readium/ios/flutter_readium/Sources/flutter_readium/ReadiumReaderView.swift	Updates user-script injection and ToC script; currently leaves broken refs to removed comics assets.
flutter_readium/example/lib/state/text_settings_bloc.dart	Adds `blackAndWhiteComicMode` to state and forwards it into EPUB preferences.
flutter_readium/assets/helpers/flutterReadiumTools.js	Updates the bundled injected helper JS (now includes Nota comic logic).
flutter_readium/assets/helpers/flutterReadiumTools.css	Updates the bundled injected helper CSS for Nota comic overlay + existing styles.
flutter_readium/assets/helpers/comics.js	Removes legacy comics bundle.
flutter_readium/assets/helpers/comics.css	Removes legacy comics styles.
flutter_readium/assets/_helper_scripts/webpack.config.ts	Stops building the legacy `comics` entrypoint.
flutter_readium/assets/_helper_scripts/src/types.ts	Renames/extends types and adds `figureQuerySelector` + `window.readium` typing.
flutter_readium/assets/_helper_scripts/src/NotaComicBookPage.ts	New Nota comic overlay renderer and Readium scroll interception.
flutter_readium/assets/_helper_scripts/src/NotaComicBookPage.scss	New overlay CSS + B/W filter + (intended) scroll lock + area hiding.
flutter_readium/assets/_helper_scripts/src/FlutterReadiumTools.ts	Integrates Nota comic initialization and adds segment-duration plumbing + global helpers.
flutter_readium/assets/_helper_scripts/src/demo/DemoComicPanning.ts	Updates demo to use `flutterReadiumTools.` instead of legacy `comics.`.
flutter_readium/assets/_helper_scripts/src/ComicBookPage.ts	Removes legacy comic renderer implementation.
flutter_readium/assets/_helper_scripts/src/ComicBookPage.scss	Removes legacy comic renderer styles.
flutter_readium/assets/_helper_scripts/src/ComicBookCalc.ts	Refactors keyframe generation + adds full-page frame calc + timing tweaks.
flutter_readium/assets/_helper_scripts/public/books/xkcd/index.html	Updates demo markup to figure + areas format expected by Nota comic logic.
flutter_readium/assets/_helper_scripts/public/books/comic-panning/media-overlay.json	Removes old demo book overlay.
flutter_readium/assets/_helper_scripts/public/books/comic-panning/index.html	Removes old demo book HTML.
flutter_readium/assets/_helper_scripts/package.json	Adds dev-server dep and adjusts scripts.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/Utils.kt	Adds helpers to convert dynamic maps into kotlinx `JsonElement` for prefs decoding.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/ReadiumReaderWidget.kt	Switches preferences parsing to `FlutterEpubPreferences` with `Map<String, Any>`.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/ReadiumReader.kt	Filters script/style injection to HTML-like resources; adds segmentDuration plumbing.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/ReadiumExtensions.kt	Removes legacy comics injection; exposes `readiumColorFromCSS` for new prefs model.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/navigators/SyncAudiobookNavigator.kt	Uses a flow-driven locator sync (with segment-duration propagation) and removes last-item tracking.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/navigators/EpubNavigator.kt	Stores `FlutterEpubPreferences`, updates preferences + toggles B/W comic mode via JS, and pushes segment duration into JS.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/models/FlutterMediaOverlayItem.kt	Adds computed segment `duration`.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/models/FlutterMediaOverlay.kt	Uses `mediaType.isHtml` instead of explicit MediaType checks.
flutter_readium/android/src/main/kotlin/dk/nota/flutter_readium/FlutterEpubPreferences.kt	New serializable preferences model + conversion to Readium `EpubPreferences`.
flutter_readium_platform_interface/lib/src/reader/reader_tts_preferences.dart	Minor typing improvement for voices map.
flutter_readium_platform_interface/lib/src/reader/reader_epub_preferences.dart	Major expansion of EPUB prefs model + JSON parsing/serialization + new comic mode flag.
.vscode/tasks.json	Adds helper-scripts build task.
.vscode/settings.json	Marks generated/bundled JS/CSS as excluded + readonly in VS Code.
.vscode/launch.json	Adds preLaunch helper build and a demo launcher.
.vscode/extensions.json	Recommends ESLint/Prettier extensions.

Comments suppressed due to low confidence (1)

flutter_readium/ios/flutter_readium/Sources/flutter_readium/ReadiumReaderView.swift:434

initUserScripts still references comicJsKey/comicCssKey in the script arrays, but their declarations were removed. This will not compile, and even if reintroduced it would crash at runtime if comics.js/.css assets are no longer shipped. Remove the comics entries from jsScripts/addCssScripts (or re-add the lookup keys and ensure the assets exist) so only the bundled flutterReadiumTools.* assets are injected.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-08T15:36:13Z

+    }
+  }
+
+  #onResize = (): void => this.scrollToId(this.#lastElementId);


#onResize calls scrollToId(this.#lastElementId) even when #lastElementId is still null (e.g. before any navigation), which will trigger the "scrollToId called with empty id" warning on every resize. Guard against null (e.g., only call when #lastElementId is truthy) to avoid noisy logs and unnecessary work.

Suggested change

#onResize = (): void => this.scrollToId(this.#lastElementId);

#onResize = (): void => {

if (this.#lastElementId) {

this.scrollToId(this.#lastElementId);

}

};

Copilot · 2026-04-08T15:36:13Z

 class TextSettingsState {
  TextSettingsState({
    required this.verticalScroll,
    required this.fontSize,
    required this.theme,
    required this.highlight,
    this.pageMargins,
+    this.blackAndWhiteComicMode = false,
  });

  bool verticalScroll;
  int fontSize;
  TextSettingsTheme theme;
  TextSettingsTheme highlight;
  double? pageMargins;
+  bool blackAndWhiteComicMode;



blackAndWhiteComicMode was added to the state, but TextSettingsState.copyWith() doesn’t allow updating it. Any future toggle event will be forced to recreate state manually (or will silently fail to update this field). Add a blackAndWhiteComicMode parameter to copyWith and pass it into the new TextSettingsState instance.

Copilot · 2026-04-08T15:36:14Z

+    final verticalScroll = jsonObject.optNullableBoolean('verticalScroll', remove: true);
+    final spread = jsonObject.opt('spread', remove: true); // Replace with actual parsing if needed
+    final textAlign = jsonObject.opt('textAlign', remove: true); // Replace with actual parsing if needed
+    final textColor = jsonObject.optNullableString('textColor', remove: true);
+    final textNormalization = jsonObject.optNullableBoolean('textNormalization', remove: true);


spread and textAlign are read with opt() and passed through without parsing. textAlign is declared as TextAlign?, so if the JSON provides a string (as is typical), this will throw a runtime type error. Use optNullableString() and parse via TextAlign.fromJson(...) (and similarly for any other enum-like fields) to make JSON parsing robust.

Copilot · 2026-04-08T15:36:14Z

+    final themeStr = jsonObject.optNullableString('theme', remove: true);
+    final theme = ThemeType.fromJson(themeStr);
+    final typeScale = jsonObject.optDouble('typeScale', remove: true);
+    final verticalText = jsonObject.optNullableBoolean('verticalText', remove: true);
+    final wordSpacing = jsonObject.optDouble('wordSpacing', remove: true);
+    final blackAndWhiteComicMode = jsonObject.optBoolean('blackAndWhiteComicMode', remove: true);


typeScale/wordSpacing are read using optDouble() without checking key presence. When missing, optDouble defaults to double.nan, which then gets serialized back out and can poison downstream preference merging. Use optNullableDouble() (or provide a sane fallback) so absent values remain null.

Copilot · 2026-04-08T15:36:14Z

+  @override
+  Map<String, dynamic> toJson() => {}
+    ..putOpt('backgroundColor', backgroundColor?.toCSS())
+    ..putOpt('columnCount', columnCount?.toJson())
+    ..putOpt('fontFamily', fontFamily)
+    ..putOpt('fontSize', fontSize)
+    ..putOpt('fontWeight', fontWeight)
+    ..putOpt('hyphens', hyphens)


toJson() now emits non-string values (ints/doubles/bools/enums), but the iOS plugin side currently casts the method-channel arguments to [String: String] (see ReadiumReaderView.swift), which will crash at runtime. Either keep encoding values as strings for compatibility, or update the iOS handler and its EPUBPreferences.init(fromMap:) to accept Any values like Android now does.

Copilot · 2026-04-08T15:36:14Z

+declare const readium: Readium | undefined;

-export class FlutterReadiumTools {
+class FlutterReadiumTools {
  get #isScrollModeEnabled(): boolean {
-    return readium.isReflowable === true && getComputedStyle(document.documentElement).getPropertyValue('--USER__view')?.trim() === 'readium-scroll-on"';
+    return readium?.isReflowable === true && getComputedStyle(document.documentElement).getPropertyValue('--USER__view')?.trim() === 'readium-scroll-on"';
  }


readium is now declared as Readium | undefined, but the rest of this file still assumes it exists in several code paths (e.g. methods that call into readium.* without guarding). If this bundle is loaded in contexts without the injected Readium API (like the helper-scripts demo pages), calling those methods will throw at runtime. Either make readium non-optional again (if it’s guaranteed), or consistently guard accesses and return sensible fallbacks when it’s missing.

Copilot · 2026-04-08T15:36:15Z

 import org.readium.r2.shared.ExperimentalReadiumApi
 import org.readium.r2.shared.publication.Locator
 import org.readium.r2.shared.publication.Publication
+import org.readium.r2.shared.publication.html.cssSelector


The import org.readium.r2.shared.publication.html.cssSelector appears unused in this file (the code references locator.locations.cssSelector directly). Removing it will avoid an unused import warning and keep dependencies tidy.

Suggested change

import org.readium.r2.shared.publication.html.cssSelector

This is incorrect org.readium.r2.shared.publication.html.cssSelector is a helper needed for locator.locations.cssSelector

Copilot · 2026-04-08T15:36:15Z

+    const figureId = figureElement.id;
+    const comicImgId = comicImg.id || figureId;
+    if (comicImgId == figureId) {
+      delete figureElement.id;


delete figureElement.id doesn’t clear the element’s id attribute (it only attempts to delete an own JS property, and id is an accessor on the prototype). In the common case where comicImg.id is empty, this leaves both the <figure> and <img> sharing the same id, which can break getElementById lookups. Use figureElement.removeAttribute('id') or figureElement.id = '' instead.

Suggested change

delete figureElement.id;

figureElement.removeAttribute('id');

…Locator from matching them

Copilot

Pull request overview

Copilot reviewed 48 out of 51 changed files in this pull request and generated 9 comments.

Comments suppressed due to low confidence (1)

flutter_readium/ios/flutter_readium/Sources/flutter_readium/ReadiumReaderView.swift:433

initUserScripts() still references comicJsKey/comicCssKey in the jsScripts / addCssScripts arrays, but the lookupKey definitions for those variables were removed in this PR. This will fail to compile, and it also looks inconsistent with Android where comics.js/comics.css injection was removed. Either reintroduce the variables or (more likely) drop the comics assets entirely here and only inject flutterReadiumTools.js / flutterReadiumTools.css.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+import CopyPlugin from 'copy-webpack-plugin';
+import HtmlWebpackPlugin from 'html-webpack-plugin';
+import webpack from 'webpack';
 import { getEnvVariables, outputPath, resolveApp } from './webpack.tools';


+import TerserPlugin from 'terser-webpack-plugin';
+import webpack from 'webpack';


+import MiniCssExtractPlugin from 'mini-css-extract-plugin';
 import * as webpack from 'webpack';
 import { merge } from 'webpack-merge';


+  /// Font size for text content.
+  final int? fontSize;
+


+    final scroll = jsonObject.optNullableBoolean('scroll', remove: true);
+    final spread = jsonObject.opt('spread', remove: true);
+    final textAlign = jsonObject.optEnumFromString('textAlign', TextAlign.values, remove: true);


+      this.#container.classList.remove(activeComicPageContainerClass);
+      for (let child of this.#container.childNodes) {
+        this.#container.removeChild(child);
+      }


+  @override
+  Map<String, dynamic> toJson() => {}
+    ..putOpt('backgroundColor', backgroundColor?.toCSS())
+    ..putOpt('columnCount', columnCount?.toJson())
+    ..putOpt('fontFamily', fontFamily)
+    ..putOpt('fontSize', fontSize)
+    ..putOpt('fontWeight', fontWeight)
+    ..putOpt('hyphens', hyphens)
+    ..putOpt('imageFilter', imageFilter?.toJson())
+    ..putOpt('language', language)
+    ..putOpt('letterSpacing', letterSpacing)
+    ..putOpt('ligatures', ligatures)
+    ..putOpt('lineHeight', lineHeight)
+    ..putOpt('pageMargins', pageMargins)
+    ..putOpt('paragraphIndent', paragraphIndent)
+    ..putOpt('paragraphSpacing', paragraphSpacing)
+    ..putOpt('publisherStyles', publisherStyles)
+    ..putOpt('readingProgression', readingProgression?.toJson())
+    ..putOpt('scroll', scroll)
+    ..putOpt('spread', spread)
+    ..putOpt('textAlign', textAlign?.name)
+    ..putOpt('textColor', textColor?.toCSS())
+    ..putOpt('textNormalization', textNormalization)
+    ..putOpt('theme', theme?.toJson())
+    ..putOpt('typeScale', typeScale)
+    ..putOpt('verticalText', verticalText)
+    ..putOpt('wordSpacing', wordSpacing)
+    ..put('blackAndWhiteComicMode', blackAndWhiteComicMode)
+    ..put('disableSynchronization', disableSynchronization);


      'preceding::*[@epub:type="pagebreak" or @type="pagebreak" or @role="doc-pagebreak" or contains(@class,"pagebreak")][1]',
      element,
-      (prefix: string) => {
+      (prefix: string | null) => {


+/**
+  * Prevent scrolling of the body when a comic book page is active.
+  */
+body:has(div.nota-comicbook-page-container.active) {


Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

ddfreiling

Looks good so far, minor comment on the casing here.

ddfreiling · 2026-04-14T14:59:08Z

+            epubNavigator?.updatePreferences(preferences.toEpubPreferences())
+
+            if (preferences.blackAndWhiteComicMode != oldBlackAndWhiteComicMode) {
+                epubNavigator?.evaluateJavascript("window.SetBlackAndWhiteMode(${preferences.blackAndWhiteComicMode})")


I think this should follow camelCase like the rest of our JS interface.

This is included in #100

m-abs added 6 commits April 1, 2026 14:48

feat(NotaComicBooks): handle nota comic books.

d21aa0b

feat(NotaComic): Full page rendering

4171b9b

fix(android): location change were delayed, which broke animations

b39cc89

Merge branch 'main' into feat/nota-comics

ed5736b

update comic css

353fa42

feat: Full EpubPreferences from Dart to Kotlin + black and white comi…

67be359

…c mode

m-abs requested review from Copilot and ddfreiling April 8, 2026 15:29

Copilot started reviewing on behalf of m-abs April 8, 2026 15:29 View session

Copilot AI reviewed Apr 8, 2026

View reviewed changes

m-abs and others added 11 commits April 9, 2026 12:49

chor: update helper deps and fix compile issues

a769f7a

minor clean in the javascript lib

94f4a2d

fix: new epub preferences enums had some naming conflicts

241ba2a

use TextAlign from dart:ui instead of own enum

f015184

remove decorations when the audio player is disposed

d803f1c

make the page-break display: inline-block to prevent findFirstVisible…

ee05244

…Locator from matching them

Merge branch 'main' into feat/nota-comics

ff5e8a0

feat(EPUBPreferences): added disableSynchronization

90df35c

chor: add documentation to Dart EPUBPreferences

839194c

Merge branch 'main' into feat/nota-comics

49971e3

make event classes immutable

438b195

m-abs requested a review from Copilot April 14, 2026 12:19

Copilot started reviewing on behalf of m-abs April 14, 2026 12:20 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

m-abs and others added 4 commits April 14, 2026 14:32

add nota test comic

f183a97

fix scss, forgot to rename a class selector

a1b3c34

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

feat: comics support on iOS

7aa970b

fix(iOS): handle expanded EPUBPreferences

fac6048

ddfreiling requested changes Apr 14, 2026

View reviewed changes

ddfreiling added 2 commits April 15, 2026 10:07

fix: iOS comic support

cafa32a

chore: add log in case SetBlackAndWhiteMode fails on iOS

7c0de45

m-abs marked this pull request as ready for review April 16, 2026 11:36

m-abs mentioned this pull request Apr 16, 2026

fix/gotolocator with progression #99

Merged

m-abs requested a review from ddfreiling April 16, 2026 11:49

m-abs merged commit 427a490 into main Apr 16, 2026

m-abs deleted the feat/nota-comics branch April 16, 2026 13:26

	delete figureElement.id;
	figureElement.removeAttribute('id');

		import TerserPlugin from 'terser-webpack-plugin';
		import webpack from 'webpack';

Conversation

m-abs commented Apr 8, 2026

Uh oh!

m-abs commented Apr 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

m-abs Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

ddfreiling left a comment

Choose a reason for hiding this comment

Uh oh!

ddfreiling Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

m-abs Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants