19 Commits
Author SHA1 Message Date
hectorqin dca46d909e perf: harden sync and authentication and defer route loading 2026-11-08 05:17:42 +00:00
hectorqinandClaude Opus 5.5 120827bad6 docs: bring every document in line with the code
Audit of README, docs/, android/README.md, android/contract.md and CLAUDE.md
against the current server, web and Android code: V3 navigation and settings
locations, Docker Hub release images, GitHub clone URL and CI, missing API
endpoints and error codes, architecture of lazy chunks/themes/sources, media
pages and routes, the Android bridge contract, and the new file-management and
member-upload permissions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 02:03:45 +00:00
hectorqinandClaude Opus 5.5 415a9f5dd3 chore: drop CNB config; Android package is com.htmake.readerpro
- Remove .cnb.yml and CNB references in the Dockerfile and Compose file; the
  Compose default image is hectorqin/reader-pro:latest.
- Rename the Android applicationId/namespace and Kotlin package from
  cool.cnb.reader to com.htmake.readerpro (shortcuts, ProGuard, shell check).
  Installs under the old package are a different app and are not migrated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-30 02:03:45 +00:00
hectorqinandClaude Opus 5.5 2f784d1d4e fix(web): mobile PWA style review fixes
- Reader (scroll paging): mask the line the page's bottom edge cuts through
  (clip-path, --reader-page-mask) so no page shows a half-sliced last line;
  re-measured after page-turn animations.
- Landscape sidebar layout: the sidebar owns the left safe-area inset, the page
  column the right one; fix .shelf-head's swapped left/right padding; reader
  top/bottom bars respect left/right insets.
- Guard all :hover rules with (hover: hover) and (pointer: fine), enforced by
  test/design-tokens.test.ts.
- PWA update banner sits above the phone tab bar and reader toolbar.
- Top safe-area on sources header and phone media pages; 16px sidebar search
  on touch (iOS focus zoom); larger hit areas for chips and cover controls.
- Manifest: unified launch colour #FDF9F6, maskable icon, drop
  window-controls-overlay; regenerate branding assets.
- Docs: ui.md safe-area/touch/hover/reader rules, pwa.zh-CN.md icons and
  window notes, CLAUDE.md stale bundle notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 07:35:51 +00:00
hectorqinandClaude Opus 5.5 e426ac8b82 fix(android): replace the broken Gradle wrapper; CI UI review installs server deps
The committed gradle-wrapper.jar was the real 8.11.1 wrapper jar nested
inside another jar, without the org/gradle/cli classes, so ./gradlew failed
everywhere with NoClassDefFoundError: org/gradle/cli/CommandLineParser
(CI was the first place it ran from a fresh checkout). gradlew was a
hand-written launcher and gradlew.bat, which the dev guide tells Windows users
to run, did not exist.

Regenerated with `gradle wrapper --gradle-version 8.11.1` from the official
distribution (sha256 f397b287…, matching services.gradle.org); the jar matches
the published gradle-8.11.1-wrapper.jar.sha256 (2db75c40…). The distribution
URL is unchanged. .gitattributes pins gradlew to LF and *.bat to CRLF.

The UI review job starts its media fixture through server/node_modules/tsx,
so it installs the server's dependencies too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 10:25:40 +00:00
hectorqinandClaude Opus 5.5 392148c8da fix(android): shell contract check counts only page-callable methods
check-shell.sh failed on main in three places, none of them real defects:

- Every `fun` at method indentation counted as a bridge method, so the
  Kotlin-only SpeechBridge.interruptForMedia (called by the media bridge,
  not the page) was reported as undeclared. Only methods directly under
  @JavascriptInterface are the page's contract now.
- configuredServerUrl was declared as an optional *property*
  (`configuredServerUrl?: () => string`), which the declaration reader does
  not see. Written as the equivalent optional method, `configuredServerUrl?(): string`.
- The package/directory check stripped only src/main/java/, so every unit
  test under src/test/java/ was reported as misplaced. Any source set's java/
  root is stripped now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 10:09:32 +00:00
hectorqin 3140521ffa fix(android): polish native video player UI 2026-10-01 12:31:26 +08:00
hectorqin 352dccaabe feat(pwa): align app branding and add startup screen 2026-10-01 08:26:08 +08:00
hectorqin f0e6bbf370 fix(android): configure server URL and allow asset origin 2026-10-01 08:06:57 +08:00
hectorqin 73f9eb6e20 feat(media): add isolated media libraries and playback
Support local and OpenList libraries, metadata, independent media navigation, themes, and audio/video playback. Preserve approved v2 prototypes and current documentation; archive superseded review artifacts and keep generated validation output outside version control.
2026-09-27 18:22:51 +08:00
hectorqin 0b7f901db5 chore(server): change default listening port to 5888 2026-09-24 14:50:13 +08:00
cnb.dQC5J6ohAGA dbaac99b45 feat(web): 界面加路由,首页重做
首页(书架)此前是纯命令式拼出来的,而整个客户端没有任何路由:URL 从头到尾不变,
返回键、刷新、分享、收藏一概不成立。

## 路由

`ui/router.ts` 把 fragment 解析成 route,shell 渲染 router 报上来的那个:

  #/shelf             书架
  #/book/<id>         阅读器
  #/library/<路径>    书库里的目录

用 fragment 而不是路径,是因为同一份产物要被两个宿主加载,而两个都服务不了任意路径:
Android 从 appassets.androidplatform.net 加载(那里没有服务端),H5 由 reader 服务端
托管(没有客户端路由回落)。路径式路由会在 vite dev 里正常、在两个生产宿主里 404。

返回走应用自己的屏幕轨迹,不走 history.back():应用里的「返回」是「上一个屏幕」,
而浏览器历史里可能有登录表单或别的站点。轨迹为空时(新标签页里粘贴的链接)替换成父级,
而不是压入——否则那个链接会永远压在书架后面。

走进书库子目录用 replace:书库是一个带面包屑的屏幕,走目录是同一个屏幕改自己的参数。
压栈的话,读者走过四个文件夹再按返回会逐层退出来。

带着链接进来而尚未登录时,route 存在 App.pending 里等在登录页后面,登录后直接落到
目标屏幕,而不是落到一个他从未见过的书架。

Android 外壳的返回手势不需要改动:它看的是 WebView 的 canGoBack(),而路由现在真的
往 WebView 历史里写——之前那段注释描述的行为,从这次起才成立。

## 首页

- 先看到书,再看到控件:标题和封面在最上面,搜索在后,排序与数量贴在它们作用的那一节上。
  旧版把搜索框、数量、四个排序 chip 依次排在封面之前,三行控件才轮到第一本书。
- 排序栏是唯一吸顶的东西,它承载的是读者会滚回去改的两件事。
- 空状态给一条出路(打开书库管理 / 刷新 / 清除搜索),而不是一句「书库还是空的」。
- 冷启动画骨架屏,且按当前密度画——密度不对的骨架屏会让读者看到布局动两次。
- 封面缺图时把书名画成封面,而不是一个灰色方块。

## 顺手修掉的 5 个真缺陷

1. mountUI 在 unmount 之后仍会渲染。屏幕是异步加载的,离开后那条迟到的响应会把
   整棵树画进一个刚被清空的容器;书架迟到的响应会把自己一屏封面画进书库管理器。
2. --safe-left/-right/-top/-bottom 从未在生效的样式表里定义过,只有一份没人 import 的
   死样式表定义过。未定义的自定义属性会让整个 calc() 失效并静默丢弃声明。
3. 封面在 flex 列里没有显式宽度,aspect-ratio 盒子因此收缩到内容宽度:只有书名的封面
   塌成 42px、有图的占满卡片,整排看起来参差不齐。
4. 阅读列在宽屏上被拉伸到 9 列 45px 的封面。现在内容列封顶 68rem,封面随断点变大。
5. 删掉 web/src/ui/styles.css——414 行从未被引用的旧样式,以及 .book-highlight 等
   已经没有任何代码产出的规则。

## 验证

- web 全量 284 项测试通过(新增 router 19 项 + 链接契约 4 项)。
- typecheck / build / check-shell.sh / build-web-assets.sh 均通过。
- 真浏览器实测:深链直开、刷新不丢、返回离开屏幕、登录后落回目标、书库走目录、
  空搜索、粘性工具栏、深浅色、390px 与 1440px 两档宽度。
- 体积:251KB → 252KB(gzip 79.1KB)。
2026-09-17 18:49:53 +08:00
cnb.dQC5J6ohAGA baf63c5b28 fix(ci): 让 assets 流水线真正验证产物会被打进 APK
web-assets-ci 只跑了 build-web-assets.sh,证明脚本写完了 assets,却没证明
Gradle 会读那个目录 —— 而这两处此前就是漂移的:

- build.gradle.kts 的 assets.srcDirs 指向 android/app/web-assets,
  那是没有任何脚本写入的第三个路径;真正的产物落在
  android/app/src/main/assets/web-assets。于是 staged 的 bundle 不是 assets
  源,APK 照常构建成功,但里面没有客户端,启动即白屏。
- 注释依赖的 README.txt 占位文件已在 c18664f 被删除,所以干净 checkout 里
  这个目录根本不存在,assets.srcDirs 指向一个不存在的路径。
- build-web-assets.sh 的 rm -rf "$dest" 会把那个占位文件一起删掉,
  即使它还在,每次本地构建后工作树都会变脏。

改动:

- build.gradle.kts:assets.srcDirs 指向脚本实际写入的目录,注释写准。
- 恢复 web-assets.sh 目录下的 README.txt 占位,让目录进版本库。
- build-web-assets.sh:清理产物时保留 README.txt,不再制造脏工作树。
- 新增 verify-web-assets.sh:校验产物存在且是构建出的客户端、Gradle 声明的
  路径与产物路径一致、占位文件确实被 git 跟踪。
- .cnb.yml:web-assets-ci 增加该 stage,并把脚本自身 / build.gradle.kts /
  assets 目录纳入 ifModify —— 改这些本来不会触发任何验证。
- PR 侧补 android-contract-checks:桥接契约与渲染词表校验不需要 JDK/SDK,
  秒级,不该等到 main 的完整构建才发现。

验证:check-shell / build-web-assets / verify-web-assets 全部通过;
把 assets.srcDirs 改回错误路径可复现失败。.cnb.yml 通过语法/语义/Schema 校验。
2026-09-17 10:30:00 +08:00
cnb.dQC5J6ohAGA 0370cd98e8 feat: HTTP TTS 与双端兼容朗读,书架体验与自定义设置
朗读(Closes #13 的朗读部分)

新增服务端 HTTP TTS 代理与客户端第二、第三个朗读引擎,三者在同一个
SpeechEngine 接口下可切换:

- 服务端 GET /api/v1/tts 代理 TTS_URL 指向的合成服务(edge-tts / Piper
  等兼容形态),只代理不内置合成模型;GET /api/v1/tts/voices 回答
  「这个实例能用什么」,未配置时返回 http:false 而不是 404。
  按句合成、磁盘缓存、上游返回非 audio/* 时明确报错(一个指到网页的
  TTS_URL 会以 200 返回 HTML,塞进 audio 里既没声音也没事件)。
  /tts 是精确的查询串令牌白名单项之一:<audio src> 无法带 Authorization。
- 客户端 HttpTtsEngine 用 <audio> 而不是 Web Audio,事件驱动推进队列。
- 客户端 NativeTtsEngine 走 Android 外壳新增的 speech 接口(shell v3):
  WebView 自带的合成器与系统的是两个引擎,手机系统装好的中文语音经常
  不在 getVoices() 里,这是「朗读没有中文声音」最常见的原因。
- speechAvailability 决定 auto 用哪个引擎:native → system → http。
- 原 TtsEngine 抽出 loadQueue/onChunk/onState 为公开字段以结构化满足接口。

书架

- 排序:最近更新 / 最近入库 / 书名 / 作者,中文按数字大小排。
  排序规则抽到 shelf-order.ts,离线路径与服务端用同一条规则。
- 密度、作者显隐、封面进度条;搜索一键清空 + 回车即搜;下拉刷新。
- 服务端 BookDto 增加 addedAt,否则客户端离线排序无法复现服务端结果。

自定义设置

- 朗读引擎可选(引擎多于一个时才显示该行);音调行只对有声调的引擎出现。
- 书架设置独立成 sheet,与阅读面板分开。

测试与文档

- server: tts.test.ts(10 例)。web: tts-http / speech / shelf-order
  新增 39 例,合计 245 passing。
- android/scripts/check-shell.sh 修正为同时校验嵌套的 speech 接口,
  之前它只能看到一个顶层接口。
- README / docs/api.md / docs/architecture.md 补齐三个引擎的取舍、
  环境变量与错误码。

Ref: #13
2026-09-16 23:29:41 +08:00
CodeBuddy b9b9c63605 merge: 把 main 合并进按窗口读取分支,并修正目录书页契约的两处缺陷
冲突只有两处文档(README 的测试计数与端点清单、docs/api.md 的 /manifest 说明),
两边各自都是对的,所以按并集处理:计数取本分支的实际值,端点清单保留 main 新增的
/items、/toc、/file、/library/formats。

合并后按契约把两边一起验了一遍,发现目录书这条链路上有两个会被静默吞掉的缺陷,
都是「服务端仍回 200、读者看到的是坏内容」那一类:

1. 「卷」的判据里有一句 `images === 0`。整卷系列里放一张封面扫描是常态,于是
   `第01卷.cbz` 与 `第02卷/` 并列、旁边再有张图时,整个系列会被判成「不是漫画」,
   而它也不是别的格式的书——书架上直接消失。判据改成按来源问:压缩包的页就在包里,
   一个压缩包本身就是一卷;卷子目录要往下看才知道有没有页。散图仍由 MIN_IMAGES 管,
   既不能否定同级存在的整卷,也不该在自己是唯一页源时被当成书。

2. 页的资源引用被 API 层按「列表下标」拼成了 `page:<index>`,而这个格式的引用形态是
   `page:<卷>:<页>`。「一个压缩包算一页」意味着一个卷在列表里的下标与它在卷里的位置
   无关,于是按 `page:1` 去问一卷时格式处理器解不出引用,异常回退到「当普通文件发」,
   客户端请求一页、拿到的是那个压缩包——状态码 200,内容不对。引用现在由同一次页面
   遍历给出(manifest 的 files[].ref),/file 原样回传,不再有第二处实现。

顺带修正三处文档与实际不符的地方:`.cbr`/`.rar` 并未被解析(原「不做」清单暗示只有它
不做)、嵌套深度措辞与实现(读到第 4 层,且内嵌压缩包不展开)、README 的测试计数。

server 137/137(typecheck + test + build),web 179 vitest + 29 node:test(typecheck + test + build)。
2026-09-16 22:49:45 +08:00
cnb.dQC5J6ohAGA c18664f1e3 feat(reader): 按窗口读取、真机可编译的 Android 壳,以及分章契约的收口
两件事:把 PR #8 里那四项合并进来(A 选项),然后把 issue 里一直没落地的
「一次只取一章」从服务端契约一路做到客户端。

## 一、PR #8 的四项(Android 外壳最值钱)

- Android 原生整页图渲染:NativePageView + 桥接 v2(renderPage/hidePage)。
  只画整页图,EPUB 永远留在 WebView;画不了就返回 false 回退,不出现空白页。
- 离线队列:脏集合语义固定为契约,补上「请求在途时位置被改写」的三条用例。
- TXT 编码探测:GB18030 与 Big5 都解一遍再按损坏证据评分选优。
  原来「先 GB18030 失败再 Big5」永远走不到第二步——两者字节范围重叠,
  同一串字节通常两边都能解出合法字符,繁体书会整本乱码。
- 格式嗅探:magic number 优先于扩展名,并明确拒绝非书籍的媒体容器。

## 二、Android 壳第一次真的编译通过

上一轮说「没有 JDK/SDK,只写了契约」,这一轮补上了环境并真的编译。
编译立刻暴露三处——都是只有编译才能发现的:

- colors.xml 的注释里写了 --reader-paper。XML 禁止注释中出现双连字符,
  AAPT 直接拒绝整个文件。Android 壳此前从未构建过,所以从未发现。
- NativePageView.kt 用了 Uint8Array。那是 JavaScript 类型,Kotlin 里不存在;
  桥接的另一侧是 ByteArray。
- AndroidManifest.xml 引用了 @mipmap/ic_launcher,而资源里没有这个文件。

三条都让 :app:assembleDebug 失败,也就是说这个 APK 此前根本产不出来。
现在是 BUILD SUCCESSFUL,产物 3.6MB。

## 三、分窗读取:从契约做到客户端

服务端:
- /manifest 省略 group 现在等价于 group=0。原来省略意味着「发全部条目」,
  于是一本 1200 章的书在它最需要快的那个请求(打开书)里收到 1200 条记录,
  等于分窗对不传参的客户端完全失效。要完整结构用 ?group=all。
- /toc 在没有 OPF 标题映射时回落到章节自身的第一个标题。手作 EPUB 大量
  没有标题映射,原来整本目录会读成「第 1 章 … 第 300 章」,等于没有目录。
- 扫描时的 spine 读取不再解析 NCX 与 nav:扫一遍全库本该只读一次包文档。
- 尾部 Range(bytes=-N)在超过 8MB 时退化为整包响应并撤回 Accept-Ranges。
  前向流无法跳到文件末尾,服务这种请求意味着为三个字节读完整个 400MB 漫画包。

客户端:
- 新增 formats/remote-zip.ts:走 HTTP Range 的只读 ZIP,让浏览器端也能不下整本书。
- 新增 formats/windowed.ts:分窗文档。分窗是传输边界,目录必须完整,两者分开
  —— 合在一起就是原来目录面板显示「第 1 章 – 第 40 章」的原因。
- reader-screen 接上 /toc,并且点击目录项会先取对应窗口再跳。

## 验证

server:  133/133(typecheck + test + build)
web:     179 vitest + 29 node:test(typecheck + test + build)
android: BUILD SUCCESSFUL,app-debug.apk 3.6MB
shell:   契约双向校验 + 渲染模式词表校验通过
2026-09-16 19:51:38 +08:00
cnb.dQC5J6ohAGA 5f1e29a3e5 fix(server,docs): 目录书页面清单成为契约,修正三处会让书静默消失的缺陷 2026-09-16 18:40:37 +08:00
cnb.dQC5J6ohAGA ca68a03e5d merge: 解决 auto/init-server-scaffold-81b3 与 main 的冲突
两个分支各自演进:一侧引入格式注册表、H5 客户端与 Android 外壳,另一侧
引入漫画目录书与逐页取图。冲突集中在扫描器、metadata、library 路由和 web
客户端,逐项按「两边能力都要保留」的原则合并。

合并后修复了 4 个被冲突掩盖的真实缺陷:

- scanner 同时保留了两套目录书实现,类型检查与测试均无法通过;改为统一
  走格式注册表,目录书在文件遍历之前发现,其内容不再重复入库。
- /manifest 的 files 对漫画目录书返回的是文件夹路径,客户端无法逐页取图;
  改为由 manifest 派生真实页路径。
- 单个文件端点只认 book_files 行,漫画目录书的每一页都 404;改为目录书
  额外认领其目录下的路径,并修正路径归一化使穿越尝试仍被拒绝。
- 目录书判定只看图片数量,会把夹着一本书的目录整体吞掉;改为注册表驱动
  的判定,含书籍文件的目录始终是书架。

同时修复了 web 端两套测试运行器互相无法执行对方用例的问题(vitest 与
node:test 混跑会静默跳过),以及 web 侧 5 处类型错误。

Ref: #9
2026-09-16 18:04:11 +08:00
CodeBuddy 8570fb12ef docs(android): 定义外壳与 H5 的接口契约,暂不写不可验证的代码
本环境没有 JDK 与 Android SDK,编译不了的 APK 不放进来。

写下来的是已被验证的部分:
- 按 kind 分流的渲染分工(用户那条「epub 走 H5、其他走原生」),
  契约点在 web/src/ui/reader-view.ts 的 capabilities()
- 桥接对象契约(web/src/bridge.ts 已实现读取侧,且无桥时正常工作)
- 离线缓存与断点续传所需的接口,服务端已就绪
- 硬件键、返回回调的接法,以及明确标出哪些回调还没实现

同时写清开工需要什么(JDK/SDK/产物复制),避免下一轮重新推一遍。
2026-09-16 15:29:11 +08:00