update deps for flutter 3.44.+

.flutter-version

@@ -1 +1 @@
-3.41.9
+3.44.4

.vscode/settings.json

@@ -53,8 +53,10 @@
     "ascii",
     "Ascii",
     "audioref",
+    "behaviour",
     "charsets",
     "Charsets",
+    "claude",
     "comicbook",
     "CSASCII",
     "dartx",
@@ -69,9 +71,11 @@
     "flutterreadium",
     "gradlew",
     "imgref",
+    "injectables",
     "jsonable",
     "kotlin",
     "kotlinx",
+    "ktlint",
     "lcpl",
     "Mantano",
     "mediatype",
@@ -80,15 +84,18 @@
     "NYPL",
     "opds",
     "Opds",
+    "pbxproj",
     "podfile",
     "podspec",
     "prefs",
     "Prefs",
     "preorder",
+    "pubspec",
     "readium",
     "reflowable",
     "rels",
     "RWPM",
+    "serialised",
     "subcollection",
     "Subcollection",
     "subcollections",
@@ -97,7 +104,9 @@
     "tokensave",
     "Transformability",
     "videoref",
-    "Worktree"
+    "Worktree",
+    "worktrees",
+    "xywh"
   ],
   "java.configuration.updateBuildConfiguration": "interactive",
   "dart.mcpServer": true,

CLAUDE.md

@@ -23,6 +23,7 @@ When upgrading a toolkit, move all three platforms together where API surface ov
 ## Workflow
 
 - `bin/doctor` — verify toolchain. `bin/install` — full bootstrap after clone / dependency change.
+- `bin/update_flutter_version <version>` — update the Flutter SDK minimum version across `.flutter-version` and both pubspecs.
 - **Before any PR:** `bin/format` + `bin/analyze` (both cover all three packages); fix everything they report.
 - **Before declaring any Swift changes done:** run `flutter build ios --no-codesign` in `flutter_readium/example` and fix all errors.
 - **Before declaring any Kotlin changes done:** run `./gradlew :flutter_readium:compileDebugKotlin` in `flutter_readium/example/android/` and fix all errors.
@@ -48,9 +49,23 @@ When upgrading a toolkit, move all three platforms together where API surface ov
 
 ### Android
 
-- After editing any Kotlin file: `ktlint --format`; resolve all violations before committing.
-- Every `PluginLog.*` message starts with `::functionName` (exact enclosing named function).
-- Navigator-dependent `suspend` funcs: capture `navigator` as a local with a `?: run { … return }` guard, then wrap calls in `return withContext(coroutineContext) { }`. Funcs that only delegate to other wrappers skip the guard.
+- **Kotlin formatting**: after writing or editing any Kotlin file, run `ktlint --format` on it. All violations must be resolved before committing.
+- **Android log messages**: every `PluginLog.*` call in Kotlin must start with `::functionName` (double colon, then the exact name of the enclosing function). For lambdas, use the name of the enclosing named function. Example: `Log.d(TAG, "::goBackward. Navigator not ready.")`. Single-colon or missing prefixes are bugs; wrong function names from copy-paste are also bugs.
+- **Android navigator null guard**: every `suspend` function that needs the navigator must capture it as a local variable with a `?: run { }` early-return guard, then wrap direct navigator calls in `return withContext(coroutineContext) { }`. Functions that only call other wrapper functions (e.g. `evaluateJavascript`) do not need their own guard or `withContext` — delegate instead. Example:
+  ```kotlin
+  val navigator = epubNavigator ?: run {
+      PluginLog.w(TAG, "::myFunction. Navigator not ready.")
+      return
+  }
+  return withContext(coroutineContext) { navigator.someCall() }
+  ```
+
+## Build / toolchain facts
+
+- Dart SDK: `>=3.8.0 <4.0.0`. Flutter version pinned in `.flutter-version` (synced to pubspecs via `bin/update_flutter_version`).
+- Android: `minSdkVersion 24`, `compileSdk 36`, Kotlin 2.3.21, AGP 8.13.2, Java 18 source/target.
+- iOS: requires `use_frameworks!` and `use_modular_headers!` in consuming `Podfile` (see top-level `README.md`).
+- Web: webpack 5, TypeScript 5.7+.
 
 ## Gotchas
 

README.md

@@ -36,7 +36,7 @@ The canonical version pins live in `flutter_readium/ios/flutter_readium.podspec`
 | CBZ       |      ✓       |  —  |   —   |           -            |
 | DiViNa    |      ✓       |  —  |  ✓²   | ✓² (Guided Navigation) |
 
-² DiViNa audio narration is driven by a Guided Navigation document and synchronises at the page
+² DiViNa audio narration is driven by a Guided Navigation document and synchronizes at the page
 level on all platforms (on Web, ts-toolkit has no DiViNa navigator, so images are rendered by a
 plugin-side navigator). Panel-level zoom (the segments' `xywh` regions) is not yet implemented on
 any platform.
@@ -68,11 +68,19 @@ LCP-protected publications are not currently supported. The underlying toolkits
 
 | Requirement | Version                |
 | ----------- | ---------------------- |
-| Flutter     | 3.32.0+                |
+| Flutter     | see `.flutter-version` |
 | Dart SDK    | 3.8.0+                 |
 | Android     | `minSdkVersion` 24     |
 | iOS         | 15.0+                  |
 
+The Flutter version is pinned in `.flutter-version`. To update it, run:
+
+```bash
+bin/update_flutter_version <version>   # e.g. bin/update_flutter_version 3.45.0
+```
+
+This syncs the version to `.flutter-version` and both pubspec files, then run `bin/install` to fetch updated dependencies.
+
 ## Getting started
 
 Add the dependency to your app's `pubspec.yaml`:

bin/update_flutter_version

@@ -0,0 +1,55 @@
+#!/bin/bash
+#
+# Update the Flutter SDK minimum version across the repo.
+#
+# Updates:
+#   1. `.flutter-version` — CI source of truth (single-line version number)
+#   2. `flutter_readium/pubspec.yaml`     — environment.flutter constraint
+#   3. `flutter_readium_platform_interface/pubspec.yaml` — same
+#
+# Usage:
+#   bin/update_flutter_version <version>    # e.g. bin/update_flutter_version 3.45.0
+
+# Bootstrap PATH / REPO_ROOT for non-interactive shells (repo convention).
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/_common.sh"
+
+VERSION="${1:-}"
+
+if [ -z "$VERSION" ]; then
+  echo "Usage: bin/update_flutter_version <version>"
+  echo "Example: bin/update_flutter_version 3.45.0"
+  exit 1
+fi
+
+if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+  echo "ERROR: version must be semver (e.g. 3.45.0), got: $VERSION"
+  exit 1
+fi
+
+FLUTTER_VERSION_FILE="$REPO_ROOT/.flutter-version"
+PLUGIN_PUBSPEC="$REPO_ROOT/flutter_readium/pubspec.yaml"
+IFACE_PUBSPEC="$REPO_ROOT/flutter_readium_platform_interface/pubspec.yaml"
+
+# --- Update .flutter-version ------------------------------------------------
+echo "$VERSION" > "$FLUTTER_VERSION_FILE"
+if [ "$(cat "$FLUTTER_VERSION_FILE")" != "$VERSION" ]; then
+  echo "ERROR: failed to write $FLUTTER_VERSION_FILE"
+  exit 1
+fi
+echo "  $FLUTTER_VERSION_FILE → $VERSION"
+
+# --- Update pubspec flutter constraints -------------------------------------
+for pubspec in "$PLUGIN_PUBSPEC" "$IFACE_PUBSPEC"; do
+  sed -i '' -E \
+    "s/(flutter:[[:space:]]*[\"']?)(>=)[0-9]+\.[0-9]+\.[0-9]+([\"']?)/\1>=${VERSION}\3/" \
+    "$pubspec"
+  if ! grep -q "flutter:.*>=${VERSION}" "$pubspec"; then
+    echo "ERROR: failed to update flutter constraint in $pubspec"
+    exit 1
+  fi
+  echo "  $pubspec → flutter: >=${VERSION}"
+done
+
+echo ""
+echo "Flutter version updated to $VERSION"
+echo "Don't forget to run 'bin/install' to fetch updated dependencies."

docs/parity/flutter-version-update-plan.md

@@ -0,0 +1,53 @@
+# Plan: Document and script Flutter version updates
+
+## Discovery findings
+- `.flutter-version` exists at repo root with value `3.44.4`
+- All 11 GitHub workflows already read from it via `cat .flutter-version` steps
+- CI instructions (`.github/instructions/ci.instructions.md`) document *how* workflows consume it, but not that users should update it
+- README.md "Minimum requirements" table says Flutter 3.32.0+ (outdated vs pubspec's 3.44.0)
+- CLAUDE.md Build/toolchain facts says `Flutter >=3.44.0` (correct but not linked to `.flutter-version`)
+- `flutter_readium/pubspec.yaml` has `flutter: '>=3.44.0'` in environment
+
+## Alignment decisions
+- Script name: `bin/update_flutter_version` (clear, consistent with existing naming)
+- Initial `.flutter-version` value: already `3.44.4`, script should accept a version argument
+
+## Design
+
+**Steps**
+1. **Create `bin/update_flutter_version <version>`** — modeled after `bin/prepare-release` pattern:
+   - Sources `_common.sh` for `REPO_ROOT`
+   - Validates semver input (e.g., `3.45.0`)
+   - Writes version to `.flutter-version` (single line)
+   - Updates `flutter_readium/pubspec.yaml` `environment.flutter` from `'>=X.Y.Z'` to `'>=A.B.C'` using the provided version as the new minimum
+   - Prints summary of changes made
+
+2. **Update README.md** "Minimum requirements" section:
+   - Change Flutter row from `3.32.0+` → reference `.flutter-version` as source of truth (currently stale — says 3.32.0 but pubspec says 3.44.0)
+   - Add a note for contributors pointing to `bin/update_flutter_version`
+
+3. **Update CLAUDE.md**:
+   - In the Workflow section, add `bin/update_flutter_version <version>` alongside existing bin scripts (`bin/doctor`, `bin/install`, etc.)
+   - In Build/toolchain facts, clarify that the Flutter version is pinned in `.flutter-version` and synced to pubspec via the script
+
+**Relevant files**
+- `bin/update_flutter_version` — **new file**, modeled after `bin/prepare-release` pattern (source `_common.sh`, argument parsing, validation)
+- `README.md` — "Minimum requirements" table + note about `.flutter-version`
+- `CLAUDE.md` — Workflow section (add script to bin list), Build/toolchain facts (link to `.flutter-version`)
+
+**Verification**
+1. `bash -n bin/update_flutter_version` — syntax check
+2. Run `bin/update_flutter_version 3.45.0` and verify:
+   - `.flutter-version` contains `3.45.0`
+   - `flutter_readium/pubspec.yaml` has `flutter: '>=3.45.0'`
+   - Revert back to `3.44.4` / `>=3.44.0`
+3. `bin/format && bin/analyze` — no regressions from doc changes
+
+**Decisions**
+- Script takes a single positional argument (the new Flutter version, e.g., `3.45.0`) — not a constraint string like `>=3.45.0`. The script constructs the pubspec constraint.
+- Only updates `flutter_readium/pubspec.yaml`, NOT `flutter_readium_platform_interface/pubspec.yaml` — the platform interface inherits the same SDK constraint from the plugin's dependency, and changing it would require separate consideration. (User only mentioned `flutter_readium/pubspec.yaml`.)
+- `.flutter-version` is the single source of truth for CI; pubspec minimum is derived by the script.
+
+**Further Considerations**
+1. Should the script also update `flutter_readium_platform_interface/pubspec.yaml`'s `environment.flutter`? Currently it's separate — worth confirming before implementing.
+2. The README.md "Minimum requirements" table currently says 3.32.0+ which is stale. Should we also fix this discrepancy as part of the same PR, or keep it scoped to documentation additions only?

flutter_readium/README.md

@@ -64,7 +64,7 @@ CBZ, DIVINA, and LCP-protected publications are not currently supported. The und
 
 | Requirement | Version                |
 | ----------- | ---------------------- |
-| Flutter     | 3.32.0+                |
+| Flutter     | 3.44.4+                |
 | Dart SDK    | 3.8.0+                 |
 | Android     | `minSdkVersion` 24     |
 | iOS         | 15.0+                  |

flutter_readium/android/build.gradle

@@ -29,7 +29,6 @@ rootProject.allprojects {
 }
 
 apply plugin: 'com.android.library'
-apply plugin: 'kotlin-android'
 apply plugin: 'kotlin-parcelize'
 
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget

flutter_readium/android/gradle.properties

@@ -1,3 +1,5 @@
 org.gradle.jvmargs=-Xmx1536M
 android.useAndroidX=true
+android.newDsl=false
+android.builtInKotlin=false
 

flutter_readium/android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip

flutter_readium/example/android/app/build.gradle.kts

@@ -1,6 +1,5 @@
 plugins {
   id("com.android.application")
-  id("kotlin-android")
   // The Flutter Gradle Plugin must be applied after the Android and Kotlin Gradle plugins
   id("dev.flutter.flutter-gradle-plugin")
 }

flutter_readium/example/android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.13-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-all.zip