Peach: Local-first video metadata scraper and media manager.
ADR-0031:前端改用 React + Tailwind v4 + BoardUI 原版源码,继续按页面绞杀式迁移
- 状态:Accepted
- 日期:2026-09-15
- 修订:2026-09-15 补齐迁移桥接契约、弹层样式作用域、上游升级方式、lint 边界与验收定义;同日写下前端基础库的取舍与引入时机。2026-09-16 活动页迁入后 Query 的引入时机与共用方式按实际落地改写;同日配置页外壳与换头像迁入、Preact 移除后,挂载方式只剩 React 档一种,JSX 运行时不再分档;同日复核页迁入、已迁八页外观对回迁移前基线后,补页面外观以基线 CSS 为准的判据与玻璃面高对比回退的归属。2026-09-27 数据管理、重复文件与资源同步迁入:资源同步照 ADR-0080 的契约改写(空文件夹并入资源同步,失效记录永久删除、走危险确认),这一块的外观基线取合入 ADR-0080 后的旧代码,不取迁移开工时的;回收站只是目录网格的一种状态,随馆藏网格一起迁。同日艺人、创作者、厂牌、事务所与标签五个索引页迁入:页内状态(过滤词、词表、视图、类型)全由地址栏承载,从导航进入回到默认档;壳保留骨架、取图链与
setSelectMode,选择开关经新增的updateIsland推进页面;基线里被通用.meta规则误伤的标签间距不照抄。同日整页空态对回旧.emptystate(沉一档底色、20px 浮层圆角、54px 描边图标方框),播放列表/playlists列表页迁入:点开一份之后的/playlists/:playlist/:item仍是遗留层队列播放器;停在这一页时壳经updateIsland推revision,页面只重取、不重挂;列表键staleTime: 0,因为壳里的「存为播放列表」「加入播放列表」仍在 React 外写 - 关系:替代 ADR-0022 的框架与样式选择;沿用它的绞杀式迁移、构建产物入库、
/dist/路由与单一测试入口;ADR-0014 的 Video.js 保留。
背景
ADR-0022 选了 Preact 加手写 CSS,BoardUI 的外观靠把样式规则抄进 web/css/ 与 web/board.css。抄写没有单一真相:同一个 token 在 BoardUI 与 board.css 各有一份定值,浅色中性灰、焦点蓝和跟随系统深色的三档文字色都对不上,界面反复「没对齐」。
BoardUI 通过 shadcn 注册表发布 React + Tailwind v4 源码,表单与弹层交互建在 React Aria 上。留在 Preact 里,要么继续抄样式,要么经 preact/compat 运行 React Aria 并自行验证每个组件的焦点、弹层与键盘行为。
2026-09-14 在配置页「访问密码」分区做了试点:BoardUI 源码逐字复制,React 子树由 Preact 岛经 ReactSlot 挂载,与旧样式表同页共存。量到的代价与约束:
peach-react.jsgzip 110.6 kB,只在挂 React 子树的页面动态加载;peach-react.cssgzip 11.8 kB,每页加载;- 旧样式表不分层,其中
button,input{color:inherit}这类标签规则会压过层叠层里的工具类; - Tailwind Preflight 铺到整页会改掉未迁移页面的标题、表单与图片基线;
board.css的同名 token 排在后面,会盖过theme.css的上游值;- 旧的全局
:focus-visible会给 React 输入框多画一圈。
测试也要换写法。tests/test_web_ui.py 639 个用例里有 597 个只读旧前端源码的字符串;页面迁走后,这批断言如果改绑新源码的字符串,等于把「没对齐」从 CSS 挪进测试。
曾评估但不采用的方案:
- 继续 Preact + 手写 CSS:正是反复没对齐的来源。
- Preact +
preact/compat跑 BoardUI:兼容层下 React Aria 的焦点管理、Portal 与键盘行为需要逐组件验证,升级时还要重验。Peach 不承担这份适配维护。 - 只引入 Tailwind、组件自己写:样式仍是抄的,只是换成类名。
- 整站 React 重写:没有可验收的中间态,违反「替代实现测试通过后才删旧代码」。
- Next.js:本次迁移用不到它的路由与服务端能力;静态导出同样不需要 Node 运行时,但既有 Vite 构建加 Python 静态服务已经满足需要,换框架只增加迁移面。
- 用 ESLint 承载
@shadcn/lint:@typescript-eslint/parser的 peer 只到 TypeScript 6.0,项目用的是 7.0.2。
决策
技术栈与上游源码
- 新页面与迁移页面用 React 19 + TypeScript(strict)+ Tailwind v4,源码在
frontend/src/react/,单测用 vitest。 - 前端只有 React 一种渲染层,
frontend/src里 JSX 只出现在src/react/;frontend/src/react/tsconfig.json只为逐字复制的 BoardUI 源码放宽exactOptionalPropertyTypes与noUncheckedIndexedAccess两条,其余继承全局配置。Vite 与 tsc 都取离文件最近的 tsconfig。 - BoardUI 源码日常开发只读:从注册表逐字复制到
frontend/src/react/boardui/,来源与条目哈希记在ORIGIN.md,逐文件 SHA-256 记在UPSTREAM.sha256。Peach 需要不同组合或外观时,在src/react/下 Peach 自己的目录里组合,差异写进ORIGIN.md。 - 页面外观以该页迁移前的基线 CSS 为准,不以「BoardUI 里长什么样」为准:卡面、读数卡、分段控件、空态这类跨页共用的面收在
src/react/components/各自一处(card.tsx按基线选filled/outlined/raised),页面不自己拼类名串。测试只钉数据流与结构,钉不住外观,验收要对照迁移前提交的样式表与骨架逐块核卡面、网格列数、控件形态。 - 上游升级走独立提交:整文件重新复制,同一提交更新
ORIGIN.md条目哈希、UPSTREAM.sha256、theme.css与相关依赖,跑web域回归。发现上游缺陷时同样以组合件绕开或等上游修复后整文件替换,不在副本上打补丁。没有引用者的上游文件连同哈希行一起删除。哈希只证明副本没有偏离登记版本,组件行为仍由 vitest 与浏览器断言验证。
应用入口与共享源码
主界面入口为 frontend/src/react/bootstrap.tsx,由 Application 管理启动与清理;应用适配按职责放在 frontend/src/application/,页面模型与控制器放在对应 React 域。vite.config.ts 直接构建 peach-app.js 与 peach-app.css,主界面模块不外置、不分割。@peach/* 直接解析到共享源码,React、Query、历史、shell、头像助手与偏好 store 各只有一份。独立页面包与本机开发取证工具按各自边界另行构建。
- 迁移节奏不变:逐页替换,每次一到两个页面、独立分支集成;旧渲染函数、旧 CSS 与旧断言随页面删除,不保留双实现。
- 页面与页面里的附属面只由路由树画:每一页(每条路径都由路由树按匹配打开),以及页面里的附属面(首页筛选条、首页新作行、目录页处理横幅、顶栏搜索下拉),都由
RouterRoot这一棵 React 根经 portal 画进壳的容器,不为某一页或某一块另建 React 根,也不另设第二套挂载入口;不跟某一页走的常驻层按名字登记在常驻表里,同样由这一棵根画:它们没有首屏取数,打开后一直算当前页,收起只卸组件、不撤宿主;壳与它们说话的命令式句柄保留,壳仍经application-residents.ts的loadXxx(host)取句柄,各层组件订阅自己的 store,句柄里的绘制照旧同步完成。批量条、配色卡、管理页头、沉浸、设置面板、侧栏与舞台都在常驻表里;图片灯箱与全站 Toast 压在所有页面之上,同样各有一棵常驻根(见下文)。页面元素决定什么时候开、什么时候收,经frontend/src/history/managed.ts下令:打开时先取齐首屏写进 Query 缓存(取完数才画,中止或壳已离开这一页就放弃这一次),再在同一个任务里换掉骨架、放进宿主,让路由树同步画出首帧(壳紧接着就读页面结构);每次打开领一个新代次,页面按代次重挂、重取;打开之后壳的开关经就地更新合进同一份 props,不重挂、不重取,还没画完或已收起的容器上是空操作;收起时中止在途请求、撤宿主。壳在claimSurface换页时收#stats与#index,所以离开页面后组件不再活着,轮询随组件一起停;目录页处理横幅与首页新作行不在这两个容器里,由它们自己的路由判据收,顶栏搜索下拉常驻、从不收。一棵根里的一处渲染错误不能带走别的面:路由树给每一面各套一层错误边界,一面抛错只空出那一面并撤掉它的登记,壳下次打开时能重开(常驻面的宿主是壳的节点,只卸组件、不撤宿主),错误照旧经reportError上报一次;根上不套边界,后退前进的派发点与<Routes>不随某一面出错而卸掉。馆藏媒体卡与网格(catalog-grid)挂在#grid与#nrow上,claimSurface离开目录与回收站时一并卸掉;卡片的选中、待删、稍后看等状态一律写在data-*上,壳不往 React 管的类名上加东西,壳里的 Shift 连选与选中态经就地更新推进去。垃圾文件队列(junk-queue)与它共用#grid这一个容器:壳经paintGridIsland记住当前挂的是哪个岛,换岛先卸旧岛再挂新岛;它的计数行经 portal 画进壳的#count,处置与撤销仍由壳发写操作。实体资料页是一座entity-page岛、一棵 React 根:资料卡、筛选浮层(交集条、两排玻璃与内容区头)、新作那一行与正文读同一份页内状态,所以不拆成几座岛;四块的宿主仍由壳在#index里排好([data-entity-hero]、[data-entity-filter]、[data-entity-body],根挂在第一格上),岛用 portal 画进去,深链冷启动时的骨架也仍由壳按这几格铺。取数全在岛里:/api/entity、新作、作品列表与照片各有 Query 键['entity', kind, name]、['entity-items', kind, name, query, revision]、['entity-photos', kind, name, set, seed]、['feed-new', 实体 id],prefetch把四样取齐再画,骨架与整页一次换掉。地址栏仍是筛选与视图的唯一真相源、归壳写:壳从 URL 读出filters与media当 props 递进来,岛改筛选、换视图只调actions.route,壳写好地址再经就地更新推回,岛按新键重取;前进后退落在同一实体时也只推 props、不重挂。换统称、添别名、订阅与发现源开关这些写操作在岛里发,站内跳转仍走壳的openEntity/openItem,壳只剩openEntity/routeEntityPage这一个入口。名册直接用索引页的PeopleGrid,作品网格直接渲染catalog-grid的组件而不嵌套挂岛,点开一张图直接调 React 的灯箱,只把「在资源管理器中显示」经actions.revealSource(id)回壳(路径不进浏览器)。未入库的新作那一行(ADR-0042)首页与资料页共用feed-new组件与同族查询键['feed-new', 实体 id | 'home']:首页那一行由路由树画进#feedNew,换筛选只按代次重取、不重挂,离开目录页才卸;资料页那一行是entity-page里的同一组件。卡片 HTML 仍由壳的feedRowHtml拼。图片灯箱(photo-lightbox)和全站 Toast(toaster.tsx)一样不跟某一页走:它压在所有页面之上、哪一页都能打开,不该跟某个页面容器同生共死,所以@peach/react导出命令式的openPhotoLightbox(index, slides, {revealSource})/closePhotoLightbox(),在document.body末尾一个常驻宿主[data-photo-lightbox-host]上只建一棵根,每次打开换新的key让 Swiper 从头建、关闭把根渲染成空;实体页的照片墙与关注详情的大图都调它,Swiper 仍从/vendor/swiper/按需加载、只用核心 API。关注页/follow归follow-feed整页岛(和关注管理页一样挂在#stats上),是第一个自己拥有取数的页面岛:/api/follow与凭据两趟都在岛的 TanStack Query 里;地址栏仍是筛选的唯一真相源、归壳写,壳从 URL 读出view连同这一次进页的取样种子seed当 props 递进来,岛改筛选只调actions.route(view),壳写好地址再经就地更新推回,岛按新键取数、只让列表区铺骨架,页头与三排取样不重洗;标记状态、稍后看、检查更新与往回抓一页都由岛的useMutation发,壳的followWrite随之删掉。关注详情/follow/item/:id是舞台#stage里的follow-detail组件:条目 Query 先扫follow-feed的列表缓存,没有才取/api/follow?item=,followData已删;状态、稍后看与隐藏媒体的写操作在岛里发;<video>由岛画、经actions.mountPlayer交壳挂 Video.js 并拿回清理函数。舞台开关、小窗与回执仍在壳;侧栏只收计数:列表经actions.loaded交标签计数,深链直接进详情时列表不挂岛,由详情的actions.present按这一条的标签算好,壳再推给常驻面sidebar。作品详情/item/:id与/mix、/parts、/editions、/playlists/:playlist/:item四种队列是同一舞台里的item-detail岛:两座详情都画在舞台里,Video.js 与氛围光由舞台的播放区挂;条目、队列与相关作品各有 Query 键['item', id]、['item-queue', kind, id]、['item-related', id, limit],队列由岛按种类自己取,同一队列里换条不重取;评分、标签、反馈、稍后看、喜爱理由与播放列表排序移出都在岛里发,保存 Mix 的命名表单仍由壳弹进舞台同一层。队列行两座岛共用components/mix-queue.tsx。舞台本身是常驻面stage(frontend/src/react/stage/):<dialog id="stage">、进出场、骨架、两座详情与小窗是同一座面,宿主是body直接子元素[data-stage-host]、换哪一条详情都不换;舞台在第一次打开详情时经application-residents.ts的loadStage(host)登记进常驻表,覆盖组的元素按匹配经它返回的StageApi(open、update、exit、dispose、requestClose与小窗几项)开关详情,壳不再自己开舞台,detailReturnPath、followDetailReturnPath、detailOriginAnchor这些「关掉回哪里」的状态仍在壳。Video.js 与它挂的控件、统计角标、右键菜单、流会话与遥测是frontend/src/player/下的命令式 TypeScript 模块,不进 React 渲染,仍用 vendored 的videojs;舞台里的播放区在 effect 里调mountPlayer(video, options)并拿回清理函数,小窗与舞台共用同一个播放器实例。沉浸模式/immerse归常驻面immerse(frontend/src/react/immerse/):全屏连播层、每一格的<video>、手势、动作键、作者与标题、进度条都在岛里,选择器一律data-*;它和舞台一样常驻、哪一页都能打开,所以登记在常驻表里并保留命令式句柄:沉浸面在第一次打开时经application-residents.ts的loadImmerse(host)登记进常驻表,壳只经ImmerseApi(open(startId)、close、isOpen、activeVideo)下命令。片单与每一条的详情由岛取,Query 键['immerse-list', 查询串, seed, draw]与作品详情共用的['item', id];看过、高潮、不喜欢由岛的useMutation发,回执写回同一条['item', id]、目录卡与壳的条目缓存。每一格经mountPlayer(video, {kind: 'immerse', …})挂一层不带控件的 Video.js,每格一个流会话,切走、关闭时按会话取消。地址栏归壳写:岛换条只调host.route(id),壳用 replace 写/immerse?id=,关闭调host.closed;首页筛选口径经host.filters()读壳的同一份状态。/immerse在页面组里有元素,按匹配经ImmerseApi.open打开。地址离开/immerse时保留已打开的沉浸面,关闭键与 Escape 经既有关闭流程回首页;壳保留关闭流程及快捷键守卫里对immerseOpen()的判断。首页的两排头像、标签条、交集条、排序与版式键归catalog-filter岛:壳经paintCatalogFilter(patch)就地推当前口径,动作经CatalogFilterActions回壳改地址栏与取数;barsContext这份口径仍在壳。顶栏搜索的下拉、补全与键盘归search岛,经expose交出SearchApi(close());搜索框的窄屏展开、失焦兜底与全局 Escape 仍在壳。顶栏齿轮打开的设置面板与侧栏排序归常驻面settings-panel:宿主由常驻面的place在第一次打开时建在document.body末尾,壳经loadSettingsPanel(host)把它登记进常驻表后拿到SettingsPanelApi(open(section)、close、isOpen、reveal)。界面偏好仍是壳启动时归一化的那一个appSettings对象,岛经createSettingsStore读写同一个对象并落盘,改完经changed(effect)回调壳去重画受影响的面;跟账本走的几项经/api/settings写,成功后落进同一个对象。左侧抽屉#drawer里的导航列、导航上那块滑动玻璃与按语境出现的筛选分组归常驻面sidebar(frontend/src/react/sidebar/):收起态就是抽屉本身那条图标列,导航顺序、按下态与玻璃只有一份,所以不拆成边栏与抽屉两座;壳启动时先按同一份顺序同步写sidebarSkeletonHtml骨架,Application 启动时经application-residents.ts的loadSidebar(host)登记进常驻表,由路由树画进#drawerScroll、在首帧的同一个任务里换掉骨架,壳只经SidebarApi(render(props)、navChanged())推内容。导航顺序读写设置面板那同一份appSettingsstore,设置面板或这一列自己拖动改了顺序,岛按 store 的通知当场重排;筛选口径、barsContext、聚合与计数仍由壳算好当 props 推(目录与资料页一份catalog、关注页与关注详情一份follow,作品详情、管理区与索引页只画导航),点下去经host.toggleChip/navTo回壳,所以沉浸与首页筛选条读的仍是同一份state。玻璃 portal 挂在#drawer上而不住在岛画进去的#drawerScroll里,切页重画时动画不断。抽屉开合、遮罩、底栏三枚键与品牌仍在壳,岛画好后壳把品牌与开合键挪进标题行;新增 React Query 键为零。管理区的页头(管理条页签、面包屑、标题与说明行)归常驻面manage-header,底部批量选择条归常驻面batch-dock,两面都由路由树画进壳的常驻节点([data-manage-header]、[data-batch-dock],本身display: contents):壳同步先写骨架,Application 启动时经application-residents.ts的loadManageHeader(host)/loadBatchDock(host)登记进常驻表、换掉骨架,此后只经render(props)推当前管理区、菜单项与读数,或选中数、语境(目录、回收站、垃圾、关注)与垃圾页的已排除态。当前在哪个管理区仍由壳从路由表推(manageSection),回收站读数由目录计数写进壳的trashCount,同页重画沿用旧读数、离开回收站才清;面包屑左键回壳的openDataCleanup,清空回收站回壳的emptyTrash。批量条的外壳复用components/selection-dock.tsx,键按迁移前基线量;选中集、setSelectMode与 Shift 连选仍在壳,按键经host.run(group, operation)分派回壳的批量函数,写操作与撤销不进岛。这两面与回收站的危险键读styles.css里同一条[data-danger]规则,不各写一份红。 - 卡片图片助手只有一份:封面与头像的 HTML、人脸取景、图片回落链、按原尺寸摆小图与悬停预览收在
frontend/src/card-art/,Application 与组件按源码路径或@peach/card-art引用同一个模块实例,随主包发出:代表作表、悬停配置和 document 上那组取景监听全站只能有一份,打两份就是壳写一张表、岛读另一张。岛不再经宿主回调向壳借这些函数。它们仍吐 HTML 字符串,岛用dangerouslySetInnerHTML接:回落链会原地换src或摘掉元素,取景往<img>上写内联样式,微光在框上加类名,这些 DOM 侧改动交给 React 管会在下一次渲染被冲掉。代表作表(representatives.ts)仍由壳取/api/tops时写,随目录数据流一起进 Query;悬停预览要的选择态、打码开关与延时由壳经configureHoverPreview注入取值函数,每次现读。 - 外观应用层同理只有一份:界面偏好的归一化与
appSettingsStore单例、主题、密度、卡片与照片墙版式、光晕与强调色的写入收在frontend/src/appearance/,Application 与组件按@peach/appearance直接引用共享源码。壳在模块体里同步调用这些写入函数,<html>、<body>属性与--tile等变量在启动阶段同步写好。版式函数只收壳算好的判据(首页还是 JAV、是否竖屏),自己不读state与路由;账本下发设置后要重画哪一块,由壳的 effect 表决定。侧栏底部的配色卡是常驻面glow-picker,宿主仍是壳建的popover元素,开合、锚定与和媒体库菜单互斥沿用wireAnchoredMenu;不换 BoardUI Popover,是因为玻璃材质与开合动效都在那一份里,换掉就要复刻第二份。配色卡和设置面板的预设格是同一个glow-preset-grid组件,订阅同一份 store,任一边改了,另一边当场对齐。 - 业务状态只有一份:取数与缓存归 TanStack Query,所有 React root 共用一个
QueryClient,同一份真相只用一个queryKey,第二个读者读同一个键;节律不同的两份真相分键(来源列表由用户改、由写操作换单条,封面任务由后台推进、按状态轮询),合成一键会让轮询重画用户正在填的表单。写操作用useMutation,成功后用setQueryData换局部,不为一次写入重取整页;页面之间不另起一套订阅传数据,也不在遗留层与 React 两侧各存一份同一数据。页面经 props 拿遗留能力、经回调(如receipt、onPicked)交回结果。需要的遗留能力(confirmModal、来源图标表、番号标题)只经@peach/legacy/*的声明模块或 props 传入的遗留函数调用,不抄一份。 - 壳与岛共用同一个
QueryClient:实例建在frontend/src/query/,Application 与组件按@peach/query直接引用共享源码;@tanstack/query-core只打进主包一份,否则notifyManager、focusManager、onlineManager这些单例会分成两套,观察者与缓存不在同一套调度里。Application 在启动路径上直接fetchQuery。壳原有的条目缓存CACHE删除,['item', id]只放详情投影,卡片投影不写进去(卡片的tags是字符串数组,详情的是对象数组,混进同一个键会被当成详情读);唯一读卡片字段的回收站点击改为直接收那张卡。筛选栏数据归catalog-bars.ts:['facets', 口径, 代次]与['tops', 参数, 口径, 代次],staleTime30 秒;两排共用同一页续页请求,30 秒内回到同一口径时复用,所以请求比迁移前少,界面不变。写操作与手动刷新调dropBars()让代次加一,保证一定重取;不用整族removeQueries,因为它会取消在途请求,等它的调用方会拿到CancelledError。 - 壳自己的内存状态也只有一份:目录口径(
state、barsContext与详情打开前的那份快照)、选择集与选择模式、详情与关注详情「关掉回哪里」的来处、跳到配置页某一节与活动页预填这类一次性请求,存放在frontend/src/shell/的一个 TS 单例里,随主包发出,Application 与组件直接引用它读写;路由树里的 React 组件接手这些页面时读写同一个实例,不在组件里另存一份。单例保住壳今天的对象语义:整体重建的写点换引用,其余写点原地改同一个对象的字段,barsContext.filters与state仍是同一个对象,选择集仍是同一个Set;每次写入后通知订阅者,读者按单调递增的版本号接useSyncExternalStore。改成不可变更新会改变两份引用之间的别名关系,那是可见行为的变化,不在这一层做。服务端事实(来源在线状态、目录总数、聚合、实体形态、回收站计数)不进这个单例,按上一条归 TanStack Query;壳路由派发用来判过期的代次计数器(surfaceEpoch)也不进,派发搬进路由树后由路由树的开次代次(openEpoch)接替。 - 浏览器历史也只有一份:
frontend/src/history/用 React Router 自带的UNSAFE_createBrowserHistory({ v5Compat: true })建全站唯一的历史对象,Application 与路由树按@peach/history直接引用同一源码实例。启动路径通过它写地址;<BrowserRouter>自建的历史只听popstate,看不见壳写进去的条目。不引独立的history包,因为它已停更,条目格式也和 React Router 内置那份不同。UNSAFE_是非公开导出,升级 React Router 时可能静默失效,frontend/test/history/与frontend/test/react/router.test.tsx是它的报警线。路由树用底层<Router location navigationType navigator>,仍属 Declarative 模式;不用unstable_HistoryRouter,因为它把更新包进startTransition,连续两次变化会并成一次渲染。派发规则:每次历史变化领一个序号,壳经shellNavigate写地址时当场认领(页面换档经ShellActions交壳写回地址的也走它),页面元素不重开;覆盖元素接手该次详情请求,详情内认领的地址改写不重复打开;后退前进、React 子树发起的导航与壳的actions.navigate没人认领,派发一次并领一个开次代次(openEpoch),按匹配画的页面元素按代次重挂重取或就地推。每条路径都有元素,壳不再接派发,也没有路由表。判据用序号不用地址,因为地址不变的popstate照样要重开那一屏;覆盖组的元素同样按派发序号挂 key,history.state为空的后退也重开同一条。路由根在历史变化的同一次调用里同步提交(flushSync),壳接着写宿主时上一页的 portal 已经卸掉。元素打开那一屏的动作放在提交阶段之外,因为侧栏等常驻面的句柄内部用flushSync同步绘制,同一棵根在提交阶段里不会同步刷新。 - 管理区页面由路由树按匹配打开:统计、来源与凭证、活动、诊断等十一条管理路径在页面组里各有元素(
frontend/src/react/router/pages/managed.tsx),/resource-sync与/configuration#libraryProcessing是改写到数据管理的重定向。元素按路径加开次代次(useOpenEpoch())挂 key:派发一次就是打开一次,同一路径再打开重挂重取;经shellNavigate认领的写地址(复核页换分类、关注管理换页签)代次不变,不重开;带上路径是因为认领式改写到另一条管理路径时代次也不变,同一个元素类型会被原地复用。元素挂上经ShellActions.surfaceChanged让壳收起别的面;去处不是覆盖地址时,覆盖元素在卸载后的微任务收舞台,再在#stats里铺这一页的骨架(与壳冷启动铺的是同一张,键相同就不重画),然后走openManagedRoute:释放上一页,领一个 revision,按MANAGED_ROUTES里该路径的prefetch取齐首屏数据,再在同一个任务里清空#stats、挂上宿主并通知ManagedSurface用flushSync画,所以不会先出空骨架。首帧 props(只读态、配置权限、引导标记、配置页页签)由元素自算。#stats里的整页只由openManagedRoute换上;此外只有元素铺骨架,以及关注页打开前先释放画着的管理页。路径集合由ManagedPath类型定死,MANAGED_ROUTES必须逐条覆盖。页面要用壳的能力(开详情、按标签回目录等)经configureRouter(actions)传入的ShellActions拿,不 importapp.js。元素从 effect 里写地址一律排进微任务并带存活守卫:路由根在历史变化的同一次调用里同步提交,提交阶段里同步写地址会再要一次同步提交。页面组按background ?? location匹配,详情舞台压在/item/:id上时下面那页不拆。 - 索引页与资料页同样由路由树按匹配打开,画进
#index:managed.ts按容器分槽,#stats与#index各记一页;资料页只收#index,所以从管理页进资料页时管理页只是被藏起来、照旧活着。索引五页(INDEX_ROUTES)与资料页五个模式(ENTITY_ROUTES,/performers/*等)的元素在frontend/src/react/router/pages/index-entity.tsx,kind与name由元素从地址解(先整段解码再按段切,名字里的斜杠吃掉剩下全部段)。资料页的框架(资料卡、筛选浮层、新作行、正文四块)由元素排好,经openManagedRoute的place在首屏取齐那一刻换进#index;浮层吸顶要求父盒就是#index,新作行是遗留层卡片,所以框架不进 React。打开之后的开关(换筛选、换视图、换版式、选择模式)合进画着的那一页,不重挂也不重取。页内改地址参数(索引页过滤词与页签、资料页筛选、排序、换一批、照片视图)经ShellActions交壳,由shellNavigate认领写入:不认领就会派发成一次重开,每敲一个字就重挂一次。后退前进各走各的:索引页按开次代次挂 key、按地址重开,资料页按kind与name挂 key、同一实体只换参数时就地推。壳要重开画着的那一页(批量操作后重取、筛选回退、点开的正是画着的那一位)不写地址,把@peach/shell的pageOpens计数加一,元素整页重开,同一微任务里的换页与重开合成一次。筛选条的资料页语境不再存进barsContext,由currentBarsContext()推导:变量是作品详情就用变量,否则#index里画着资料页就按那一页的 props 推,再否则用变量。推导源用画着的那一页而不用地址,因为后退前进进详情时地址已经是/item/:id,资料页还压在下面。 - 播放列表页与关注页画进
#stats,但不算管理区:两页登记在BROWSE_ROUTES,由路由树按匹配打开(frontend/src/react/router/pages/follow.tsx),元素不按开次代次挂 key,卸载时也不释放#stats;壳要整页打开时把pageOpens加一,写地址一律经shellNavigate认领。关注页分两种进法:已经停在/follow时再点侧栏或点「去看更新」算重新进入,重掷取样种子、滚动记忆清零;从别页点侧栏、后退前进与关掉详情算回到,地址带上一次的view。列表还画着时两种都就地推新代次、重取、回顶,不重挂;列表已被收掉时整页打开,列表读缓存不重取,滚回记下的位置。取样种子、代次与滚动位置记在@peach/shell的 store 里。播放列表页由侧栏、后退前进、关掉详情进来都整页打开;停在这一页时的「换一批」推 store 的playlistsRevision,只重读、不重挂。/follow/item/:id按背景匹配时列表压在详情下面;深链进详情没有背景,不挂列表,这与/item/:id深链补画目录是两条规则。关注页首屏的骨架淡出经place交给元素的reveal(内部是revealSkeleton):写入那一步只放空宿主,页面紧接着在同一个任务里由flushSync画满,骨架与整页之间没有空帧。详情深链/follow/item/:id由壳让出#stats,关掉详情回到列表时才画。关注页的助手与动作由ShellActions.follow在打开时交进来:卡片按引用比较,它们拼的 HTML、碰的 DOM 与写的地址都还在壳里。 - 目录网格与垃圾队列画进
#grid,表按页面分键:CATALOG_ROUTES只有两个键,/是目录网格(首页、未看、稍后看、标记与回收站画的都是这一张),/junk-files是垃圾队列;槽里记的是画着哪一页,不是地址。<Routes>另按CATALOG_PATHS声明六条地址路径。按地址分键会在三处出错:网格在/trash打开之后去/是就地推,槽里的路径不跟着变;?state=ads落在/上,画的是垃圾队列;冷启动落在详情地址上时,网格在/item/:id底下补画。六条地址路径由路由树按匹配打开(frontend/src/react/router/pages/catalog.tsx),元素按这两个页面键挂 key、不按开次代次:代次变化只让元素按地址重建筛选并重取,从详情关掉回来、后退前进经过详情都不重挂。目录筛选state由目录元素按地址与appSettings重建:排序与方向进地址,换排序用 replace 写入、不加后退步;取样种子不写进地址(地址上手写的?seed=照读),进首页重掷、目录内沿用;loc的缺省值看来源是否在线;owner按地址重读,region沿用旧值;缩略图版式只在启动时读;barsContext.filters与state是同一个对象。页内换筛选、排序与 JAV 切换先写 store,再经shellNavigate认领写地址(JAV 切换写homePath()),元素订阅 store 重取,不重挂。壳的判据改读槽:gridPainted()看managedEntry($('#grid')),gridTaken()再算上首屏取数中的那一次。#grid只在clearCatalogGrid里收;claimSurface只收#stats与#index;releaseManagedRoute必须点名容器,没有无参的「全部收起」。目录首屏的骨架淡出经revealRoutedPage;垃圾队列不在打开前取数,画上就铺自己的骨架。 - 详情条目记下压在哪一页上,路由树分页面组与覆盖组:作品详情、四种队列与关注详情(
OVERLAY_PATHS)的历史条目在usr里带{ backgroundLocation: { pathname, search }, overlay }。背景在壳决定打开的那一刻经holdOverlayBackground快照,不在 push 那一刻读地址,因为队列打开意图由路由树的QueueRequests接手,先铺舞台骨架并取数,实际数字条目和首屏确定后才 push 队列地址;当前已在详情地址上(同队列换条、关注组内换条、从详情点开另一条)就沿用上一条的背景,不嵌套。背景另记在overlay.ts,和壳给关闭用的detailReturnPath、followDetailReturnPath分开,两者的清空时机不同。关掉详情、删掉当前条目、后退前进与启动时先清空。只存路径与查询串,不存 DOM、对象或条目key,因为条目跨刷新存活而内存不在。RouterRoot里的<Routes>分成两组:页面组location={background ?? location},详情压在哪一页上就还匹配那一页,location一直给,不给与给之间会多包一层LocationContext,path="*"的元素会被重挂;覆盖组按真实地址匹配OVERLAY_PATHS,元素按导航序号接走普通点卡的一次性请求或打开历史条目;冷启动条目虽然已认领,initialOverlayOpened仍允许首次打开,后续只改写条目的认领 replace 不重开,两组都不报没有路由;页面组的 location 不变时后退进详情,覆盖组照样按序号重开。后退前进时读条目里的背景,三处行为由用户定:后退前进进到详情时,覆盖组元素经adoptOverlayState接上这一条的背景,之后换条、展开小窗照样带它;打开详情的那一处用takeOverlayReturn取来处,取一次就清,关掉回到条目记的那一页;关注详情的来处带着筛选查询串。同一个队列里换条不改来处,播放列表关掉回打开队列那一刻的列表页并重读。启动不读(用户定,保持现状):条目跨刷新仍带着usr,页面组在启动那一条上不用它,刷新、新标签页与深链落在详情上时都当作没有背景:/item/:id下面画目录网格(非首页口径),/follow/item/:id下面不画列表,关掉回各自的缺省来处(作品详情/、关注详情/follow)。之后的后退前进照常按条目里的背景匹配:从详情进统计页再后退回详情、关掉,回到并画出来处那一页。/immerse在页面组里,不算覆盖层,不带背景;页面元素打开沉浸,换条由壳认领 replace 写地址,不重开;POP 离开地址时保留沉浸打开,Escape 或关闭键收起并回首页。 - 入口页由独立页面包画,不进主界面的包:首次运行页与完成页由
peach-pages.js/peach-pages.css画(frontend/vite.pages.config.ts),登录页与错误页也由它画,这个包因此免登录可取(ADR-0094)。服务端在未配置时只吐一张薄壳:color-scheme、主题预读、Inter 字体与挂载点;题目、默认值、显隐规则、校验文案与完成后的入口都来自GET /api/setup/questions与POST /api/setup,页面骨架上的固定文案归前端。这个包自成一份,不加载主包peach-app.js:首启时没有主界面的壳和登录态,主界面出错也拖不垮首启。独立包将用到的共享控件源码直接打入,不借主界面的模块或会话。用户已定的四条:控件全用 BoardUI,像素差随之而来;浏览器禁用 JS 时首启页打不开,填错时就地标出、已填内容不丢;首启页认用户手动选的深浅色,与登录页同一套预读,并加载 Inter;独立包完成后的自动跳转用脚本定时,和设置页重启后跳转共用RESTART_REDIRECT_MS。从局域网打开未配置的服务时,题目接口回 403,页面只画一句「请在运行 Peach 的这台电脑上打开设置」,不画一张提交必被拒的表单。字段错误按读屏可播报的写法挂在各自输入框下,焦点落到第一个出错的字段。 - Peach 自己以 HTML 字符串拼出的 Board 风格组件随使用它们的页面改写成
src/react/下的组合件,复用其中的数据与布局计算:board-metrics.ts、board-sankey.ts、board-analytics.ts已随统计页与口味页改写并删除;board-controls.ts剩下的是给遗留页共用的 DOM 行为(范围输入读数、全站 tooltip、下划线 Tabs 与分段控件的滑块),读者只剩各页骨架(复核页迁走后页面里没有遗留读者,.follow-workspace-switch只剩骨架里那一份),随最后一个遗留读者一起删。跨页共用的卡面与外壳先于第二个读者进src/react/components/:mix-card.tsx与use-stack-flip.ts是一叠视频的卡(翻页时序照抄遗留wireStackFlip),首页 Mix 卡迁入时直接换用;modal-frame.tsx是模态弹层唯一的外壳(form档 540px 对应ui-kit/modal.css的.ui-geist-modal),页面不再各自拼ModalOverlay。 - 模块边界:主界面由 Application、React 路由树与域控制器组成,发布
peach-app.js与peach-app.css。共享助手以源码别名引用,不发布运行时桥接产物或/js/垫片。board.css中与 BoardUI 同名的 token 按实际var()读者归零清理;骨架、全局外壳和第三方样式仍需的隔离保留。
新旧样式并存
以下做法只服务于新旧样式表同页的阶段,由 tests/test_frontend_build.py 的 BoardTokenTests、ReactBundleTests 钉住:
- 工具类不进层叠层,旧样式表的标签规则因此压不过类名;
- Preflight 逐字包进
@scope (.peach-react); - React 容器上按
theme.css的:root与.dark块重新声明同名 token。这份声明不是手工副本,BoardTokenTests逐条比对它与theme.css,不一致即失败; - 全局
:focus-visible排除.peach-react子树; - React 子树里复刻的旧玻璃面,其高对比回退仍写在
web/board.css,按data-*属性(data-glass-pane)认人:frontend/test/legacy-class-names.test.ts禁止 React 产物与遗留样式表出现同名类。
作用域覆盖弹层:React Aria 的 Popover、Select 列表与 Dialog 经 Portal 渲染到容器外。Application 的 Providers 用 UNSAFE_PortalProvider 把它们统一挂到 body 末尾一个同样带 .peach-react 的容器,读到的 token、Preflight 与焦点规则和页面内一致。弹层不塞进可能裁切它的局部容器。
旧样式表全部退出后重新评估上述五条:仍被第三方样式(如 Video.js)需要的隔离保留并写明原因,其余删除,Tailwind 回到上游默认的层叠层写法。
测试与门槛
- 沿用 ADR-0022:
npm run build的产物提交进web/dist/,运行时不需要 Node;/dist/{path}路由不变;测试入口仍是scripts/test.ps1/scripts/test.sh的web域;依赖精确锁定,在 docs/FRONTEND.md 登记用途。 - 旧断言先分类再删。页面迁走时,它在
tests/test_web_ui.py等处的源码字符串断言逐条归入三类,去向写进提交说明:- 设计决定(用户定过的颜色、状态色块、焦点样式)写成
frontend/e2e/design-*.test.ts里读getComputedStyle的断言,或由 lint 规则覆盖; - 行为(提交什么、错误写回哪个字段、控件何时可用)写成 vitest;
- 布局与运行期问题(溢出、等待态、控制台报错)归
frontend/e2e/smoke.test.ts。 - 三类各管一件事:lint 查源码是否守约定,
getComputedStyle查浏览器实际应用的样式,vitest 与浏览器交互查点击和键盘行为,互不替代。
- 设计决定(用户定过的颜色、状态色块、焦点样式)写成
- lint:
npm run lint用 Oxlint 跑@shadcn/lint的六条规则,只查src/react/、排除boardui/;web域与 CI 都执行。no-restyle按settings.shadcn.ui(@/components)识别 BoardUI 组件,所以 Peach 代码一律经@/components/...别名引用 BoardUI,不写相对路径;- 规则约束的是随手改颜色、间距与组件外观。由数据决定的几何(进度、定位、媒体尺寸)走 SVG/元素属性或 React Aria 自带定位;确需内联样式时逐行禁用并在同一行写明原因,不整条关规则。
- 哈希:
tests/test_frontend_build.py按UPSTREAM.sha256逐文件比对boardui/。 - 页面稳定判据:冒烟先断言目标页面主体已出现(成功内容、空态或错误态之一),再等
aria-busy与data-skeleton消失。只看等待标记消失不算稳定:页面完全没渲染时也没有这两个标记。React 子树在请求期间写aria-busy,首屏骨架写data-skeleton;BoardUI 组件不带加载态,由 Peach 的组合件补上。
后果
- 迁移期同一页会有两种外观:未迁移的分区仍是旧写法。
- 主界面加载
peach-app.css,体积随组件与共享控件变化,当前值记在 docs/FRONTEND.md。 - Oxlint 的 JS 插件 API 仍是 alpha,
@shadcn/lint只有 0.1.0:两者精确钉版本,升级前先跑web域。eslint作为@shadcn/lint的 peer 会装进node_modules,不调用。 - 冒烟与设计决定断言依赖 npm、ffmpeg 与 Chrome。本机缺任一项时整组显式跳过,这只适用于非验收运行。CI 的
web-bundle任务跑 typecheck、lint、vitest 与 build,不跑 e2e;CI 接入带浏览器的 e2e 任务、并在 CI 里把缺依赖判为失败之前,迁移分支须在本机web域输出里确认 e2e 实际执行。 ReactBundleTests与BoardTokenTests里只在新旧并存期成立的断言,随「新旧样式并存」一节的做法一起删除。
验收门槛
- 每个迁移分支:
- 目标页面在桌面与 390×844 下功能等价;
web域与full全绿,含 tsc、vitest、lint、冒烟与设计决定断言,e2e 显示为跳过的运行不算通过;- 反复进入、离开、返回页面,以及请求未完成时切页,都不重复请求、不留旧数据覆盖新页面,控制台无报错;
- 页面含弹层时,在浏览器里核对明暗主题、焦点进出与恢复、层叠顺序与滚动锁定;
web/dist/与源码一致;旧断言的去向写进提交说明。
- 迁移完成的定义:
- 应用入口为
Application,不发布web/app.js、运行时桥包或/js/垫片;@peach/legacy/*仅作为共享源码别名; - 并存期断言按上一节删除;
tests/test_web_ui.py里依赖旧实现的断言迁移或删除完毕,仍然成立的静态资源、页面服务与构建契约测试保留或迁往对应测试文件;- AGENTS.md 与 README 的前端章节只描述 React。
- 应用入口为
修订:浏览器用例在 CI 执行,冒烟逐路由写明主体(2026-09-15)
「后果」里约定:CI 接入带浏览器的 e2e 任务、并把缺依赖判为失败之前,迁移分支须在本机确认 e2e 实际执行。
当时 python 矩阵没有 Node、frontend/node_modules、ffmpeg 与 Chrome,tests/test_web_e2e.py 在 CI 上每次都跳过;
冒烟也只等 aria-busy 与 data-skeleton 消失,「页面稳定判据」要求的主体断言还没有落到用例里。两件事现已接入:
- 需要 Node、前端依赖、ffmpeg 或 Chrome 的用例统一经
tests/support/conditions.py的missing_prerequisite判定:本机缺失时显式跳过,GITHUB_ACTIONS=true时判失败。test_frontend_build.py的 tsc、lint、vitest 同一口径。 - CI 新增
web-e2ejob,在windows-latest上装齐四样、经PEACH_E2E_CHROME指定 Chrome, 执行web域并纳入verified汇总;矩阵扩成全量时 Windows 全量行已含web域,它按条件跳过, 同一批用例不跑两遍。python矩阵里core以外的行也装 Node,Windows 行 另装 ffmpeg 与 Chrome,否则全量行上的这些用例会判失败。工作流结构由test_frontend_build.py断言。 本机确认 e2e 实际执行那一条随之由 CI 兜住;本机跳过仍不算验收通过。 frontend/e2e/smoke.test.ts为每条路由写明主体:路由自己的标题,加上内容区、索引条目或明确的空态。 先等主体可见,再settle,再量几何。新增路由要同时写明它的主体。
修订:前端基础库随页面引入,不预装(2026-09-15)
外部审查按 master a1ff3cf6 逐项评估了迁移期常被一并推荐的基础库。判据只有一条:页面既然要改写,比较的是改写后
的长期维护成本,不是「现在多装一个依赖」;已有实现不是保留它的理由,但业务语义(身份、分页口径、显式触发)不随库
一起换掉。取舍如下,引入时机都绑在对应页面的迁移分支上,不单独开「装库」的提交。
| 库 | 决定 | 时机与边界 |
|---|---|---|
| TanStack Query | 引入 | 随第一个整页归 React 的页面进入:活动页的三段读 /api/tasks 一个 queryKey,轮询写成 refetchInterval。高清版页随页面迁移接进同一个 client,前端没有 Preact signals store、frontend/src/state/ 与 refreshStore,@preact/signals 不在依赖清单里;数据管理卡片的总数在数据管理页迁移时读高清版页同一个 queryKey。API 地址、响应类型、错误文案与 useAction 的提交互斥保留。所有 React root 共用 frontend/src/react/query.ts 里那一个 QueryClient:retry: 0,不因窗口聚焦或重新挂载自动重取(首屏由页面级 prefetch 决定,重进页面就是重取);本机接口用 networkMode: 'always';对外部来源的采集与追更仍只由用户显式触发,不进 Query 的自动重取;后台任务的状态是本机端点,按 running 开关 refetchInterval 跟进度,跟的是状态不是重新触发;首屏读到的旧终态不画成新结果,只有本次启动过或本次见过 running 的那一趟才发回执;AbortSignal 必须传到实际 fetch |
| TanStack Table | 已引入(8.21.3) | 随关注管理的表格视图进入:BoardUI 的 Data Table 本身由它驱动,Peach 逐字复制的是 table 条目,data-table 是只有示例的 block、依赖的条目 Peach 没有,只读不抄;别名表、只读信息表用 BoardUI 基础 Table。选择以来源 ID、条目 ID 为身份(getRowId),卡片与表格两个视图共用一份选择集合,跨页批量以 ID 集合为准;排序作用于整个结果集:数据能一次取完时由前端对全集排(manualSorting,/api/follow 一次回全部来源),取不完时由后端全量排,两种都不许把「只排当前页」表现成排了整个结果集 |
| React Router | 外壳阶段接管 | 8.4.0 以 Declarative 模式接管客户端导航:历史写入与后退前进的派发归它,页面与覆盖详情都登记在路由树,壳没有路由表;tests/test_legacy_shell_routes.py 冻结页面全集,核对页面组、覆盖组互不相交、壳列为空;不在别的 React 子树里另设路由。数字 ID 校验、实体名称吃掉后续含斜杠的路径、返回列表的状态与播放期间的导航行为归路由树,web/js/routes.js 不再发布 |
| TanStack Virtual | 随馆藏网格迁移引入;旧壳先用 content-visibility 缓解 |
见下节实测:连续加载到 1500 张卡片时滚动帧间隔到 48 ms,给卡片加一条 content-visibility: auto 就降到 18 ms。网格是分段、竖屏带、悬停预览与就地舞台的组合,不是均匀列表,虚拟化要同时解决动态高度、滚动位置恢复与页内查找,所以在网格迁到 React 时作为该页的设计输入一起做,不在旧壳里再写一份。旧壳阶段只加那条 CSS,随 web/css/12-cards.css 的改动走 e2e |
| Vidstack、Uppy、Refine | 不引入 | Video.js 保留(ADR-0014),只迁播放器的 React 接入;Peach 的入口是扫描、挂载与来源采集,没有上传中心;已有自己的业务接口、复核与任务处理,不再套资源管理层 |
馆藏网格连续加载的实测
2026-09-15,1500 部合成库(scripts/demo_dataset.py,占位短片、无缩略图),回环 peach serve --no-auth,
无头 Chrome 1280×800,每批 60 张,沿 #loadSentinel 连续加载;脚本与原始结果在
<私有验证记录>。
| 卡片 | DOM 元素 | JS 堆 MB | 帧间隔均值 ms(原样) | 最长帧 ms(原样) | 帧间隔均值 ms(加 content-visibility: auto) |
最长帧 ms(同) |
|---|---|---|---|---|---|---|
| 61 | 3862 | 3.2 | 6.6 | 12.5 | 6.7 | 14.9 |
| 610 | 28306 | 3.8 | 13.2 | 20.3 | 8.4 | 11.5 |
| 915 | 41886 | 4.8 | 30.3 | 42.6 | 11.0 | 13.1 |
| 1525 | 69037 | 6.6 | 47.7 | 59.7 | 18.2 | 24.6 |
帧间隔取往返滚动 30 帧的均值。每张卡片约 45 个元素;堆与强制布局的开销都小,涨的是滚动时的每帧工作量,
原样十批之后就贴近 16.7 ms 的帧预算。对照组只多一条 #grid article.card{content-visibility:auto;contain-intrinsic-size:auto 320px},
DOM 数不变,浏览器跳过视口外卡片的渲染,1500 张时仍在预算附近。真实库的卡片带缩略图与悬停预览,只会更重;
无头 Chrome 没有 GPU 合成,绝对值偏高,趋势成立。