Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,14 @@
| `src/js/defs.js` | 纯数据汇总出口(大体量数据拆在 `defs/blocks.js`·`defs/complib.js`·`defs/templates.js`,调用方一律从 defs.js import):`BLOCK_DEFS/BLOCK_ORDER/CORE_TYPES`、`THEME_PRESETS`(6 页面主题)、`COMP_LIB`(59 组件)、`UI_THEMES`(7 工具主题)、`BUILTIN_TEMPLATES`(12 官方模板)、`BLOCK_PRESETS`、`defaultProject()` |
| `src/js/themes.js` | **纯函数/数据**:`THEME_SKINS` 材质枚举与本机字体栈、`themeSkin` 兼容兜底、`themePresetPatch` 试穿/套用补丁、`themePresetMatches` 完整匹配、`themeTexture` 卡片/产物共用纹理;不按 presetRef 推断材质 |
| `src/js/macros.js` | 预览专用宏引擎(char/user/random/pick/roll/setvar/getvar/时间类),随机结果带缓存防预览闪变 |
| `src/js/project.js` | 工程存储(v1.27 起分键:`openingPageGen_v1_projIndex` 索引 + `openingPageGen_v1_proj_<id>`,save 只写变化工程;首载自动从旧整表单键 `_projects` 迁移,空间不足回滚保留旧格式)/migrate/normalize(含 `_hoistBg` 背景上收)、撤销重做(20 步快照栈存 JSON 字符串,v1.24 起含 theme)、模板、导入导出(剔除 API Key) |
| `src/js/project.js` | 工程存储(v1.27 起分键:`openingPageGen_v1_projIndex` 索引 + `openingPageGen_v1_proj_<id>`,save 只写变化工程;首载自动从旧整表单键 `openingPageGen_v1_projects` 迁移,空间不足回滚保留旧格式)/migrate/normalize(含 `_hoistBg` 背景上收)、撤销重做(20 步快照栈存 JSON 字符串,v1.24 起含 theme)、模板、导入导出(剔除 API Key) |

| `src/js/ui/core.js` | UI 壳 + `UI.renderAll()` 总入口(各渲染页有独立 try/catch 隔离)+ renderProjectSelect + 预览四件套(mountPreview/fitPreviewHeight/refreshPreview/debouncedPreview)+ 页签切换/全局快捷键/启动;经 `Object.assign(UI,…)` 挂载页面方法(模块顶层不读 UI 值,规避循环 import TDZ) |
| `src/js/ui/renderConfig.js` | 配置页渲染与交互(renderConfig:主题/宏/区块列表拖拽/全局搜索替换 UI 层) |
| `src/js/ui/blockEditors.js` | renderBlockBody 各区块编辑表单 + 组件库插入/选择器弹窗 `openCompPicker` |
| `src/js/ui/renderExport.js` / `renderAI.js` / `renderHelp.js` | 导出页 / AI 助手页 / 说明页渲染 |
| `src/js/ui/renderNh.js` | 漫画导入页:服务探活 / 抓取 / 勾选筛选 / 应用到区块(`scripts/nh-lib.mjs` 直接 import 进 bundle) |
| `src/js/ui/extBridge.js` | 扩展版桥接(写角色卡 / 酒馆当前连接 AI 生成);桥不存在时功能休眠 |
| `src/js/ui/shared.js` | 跨页辅助:bindListEditor / detectFonts |
| `src/js/search.js` | **纯函数**全局搜索替换:collectSearchMatches / replaceAllInString / replaceAllInProject(UI 层仅调 API,逻辑可测) |
| `src/js/fontdetect.js` | **纯函数**字体检测:COMMON_FONTS / BASE_FONTS / fontExists / detectAvailableFonts(ctx 由调用方注入,测试 mock) |
Expand All @@ -70,7 +72,7 @@ localStorage(openingPageGen_* 键)

## 硬约束(红线)

1. **组件库 `COMP_LIB`**(`defs/complib.js`,55+ 条带 cat 分类):无 id 选择器(**例外**:`opg-` 前缀 id 供 CSS 交互组件如多标签页/求签,多次插入共享状态为已知取舍)、无全局选择器;`<script>` 仅音乐播放器/交互计数器/点击切换消息三个特例(IIFE 局部作用域 + `data-bound` 防重绑,交互一律 addEventListener 禁用内联 onclick);类名一律 `opg-` 前缀隔离;假设深色生成底;430px 手机宽适配。组件插入走 `openCompPicker` 弹窗(blockEditors)
1. **组件库 `COMP_LIB`**(`defs/complib.js`,59 条带 cat 分类):无 id 选择器(**例外**:`opg-` 前缀 id 供 CSS 交互组件如多标签页/求签,多次插入共享状态为已知取舍)、无全局选择器;`<script>` 仅音乐播放器/交互计数器/点击切换消息三个特例(IIFE 局部作用域 + `data-bound` 防重绑,交互一律 addEventListener 禁用内联 onclick);类名一律 `opg-` 前缀隔离;假设深色生成底;430px 手机宽适配。组件插入走 `openCompPicker` 弹窗(blockEditors)
2. **gen 产物自包含**:style+script 全内联;容器 `opg-{id}` 前缀隔离;同类区块多实例用 `display:contents` 作用域层(`.opg-{id}-bk{i}`)
3. **宏双轨**:`gen/body.js` 的 `tx`(预览经 Macros.apply 替换)/`raw`(导出原样保留交酒馆解析)——新增区块渲染必须双轨支持,只写一边会让预览或导出失真
4. **工具 UI 主题**:`tool.css` 的 `html[data-theme='x']` 块必须覆盖**全部令牌**(`:root` 的全部令牌,含 `--star-c`——星夜主题星点背景依赖)+ `#topbar/#tabs/#main` z-index 三件套(若用 body::before 纹理层);`bronze` 是 `:root` 默认,不挂 data-theme 属性
Expand Down
42 changes: 34 additions & 8 deletions PITFALLS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,40 +47,66 @@
(backHome、rememberKey 都走这套)。
13. **会话级敏感数据**(API Key 类):模块级变量暂存 + normalize 默认值 + `exportData` 剔除,
三处联动;任何「记住我」开关关掉时必须顺手清已落盘的旧值。
14. **撤销快照在「改动之后」拍**:saveSnapshot 存的是改动后状态——先拍快照再改数据时,拍的
内容与栈顶相同被去重**静默吞掉**(project.js 直接 return),改动后的状态永不入栈:一次
Ctrl+Z 连跳两步、redo 永远回不到已写入态(v1.27.1 漫画导入「应用到区块」踩过)。凡
「await 确认 → 改数据」的处理器,saveSnapshot 放赋值之后;blockEditors 清空漫画页的
「先拍 + 改完补拍」写法碰巧有效但冗余,别模仿。

## 五、构建 / 验证 / 提交

14. **lint 报错先读规则头注释**——每条规则都写着为什么存在(多是事故换来的),绕过即重蹈。
15. **浏览器冒烟陷阱**(IAB 门面实测):
15. **lint 报错先读规则头注释**——每条规则都写着为什么存在(多是事故换来的),绕过即重蹈。
16. **浏览器冒烟陷阱**(IAB 门面实测):
- `fill()` 不触发 `change`——依赖 change 落盘的输入,测试时要
`dispatchEvent(new Event('change',{bubbles:true}))` 或真实失焦;别信「填了就生效」;
- locator 可达名带 emoji 常匹配不上,改在 evaluate 里 querySelector 后派发 click;
- `tab.playwright.keyboard` 不存在,发 Esc 用 `tab.cua.keypress({keys:['Escape']})`;
- `file://` 不能导航,先起本地静态服务再开 127.0.0.1;
- 预览页有**两个 iframe,第二个才是预览帧**(第一个是外框)。
16. **看着像坑但别动**:dist 里二十多个 `<style>` 全是组件字符串内嵌样式(组件插入时才解析,
17. **看着像坑但别动**:dist 里二十多个 `<style>` 全是组件字符串内嵌样式(组件插入时才解析,
合并破坏自包含硬约束);`core.js` 不加 beforeunload(pagehide 已同步强写兜底,弹窗纯打扰);
`src/` 就是未压缩源码,别想着给 dist 留可读版。
17. **提交前 `git status --short` 核对**——v1.19 漏 add 过 renderHelp.js(amend 补救)。
18. **提交前 `git status --short` 核对**——v1.19 漏 add 过 renderHelp.js(amend 补救)。
推送走项目级代理 `http.proxy=127.0.0.1:7897`(配置与排查见 AGENTS.md 顶部)。
18. **零依赖走 HTTP 代理出网**:Node 全局 fetch 只认 `NODE_USE_ENV_PROXY=1` 的环境变量路径
19. **零依赖走 HTTP 代理出网**:Node 全局 fetch 只认 `NODE_USE_ENV_PROXY=1` 的环境变量路径
(且进程环境在启动时固定——改了系统代理后必须重启服务进程才生效,v1.21 实测踩过)。
要运行时指定代理只能手工 CONNECT 隧道(net 连代理 → CONNECT 域名:443 → tls 包隧道)。
**坑**:预连 socket 用 `https.Agent({createConnection})` 或 `agent:false+createConnection`
封装,实测握手正常但请求永远无响应——直接在 tls socket 上手写 HTTP 请求最稳
(`Connection: close` 读到尾 + chunked 解码,先例见 scripts/nh-import.mjs 的 proxyGet)。
顺带:spawn 的工作目录被删会让整个 shell 工具链 ENOENT(报错指向 bash.exe 缺失,
实为 cwd 缺失),先重建目录再 cd 走。
19. **构建期内嵌的资源改完必须重建**(v1.26 助手小包):`build.js` 把 ZIP 以 base64 注进
20. **构建期内嵌的资源改完必须重建**(v1.26 助手小包):`build.js` 把 ZIP 以 base64 注进
`window.OPG_HELPER_ZIP`,改 `scripts/nh-import.mjs` 等四件套后不 `npm run build`,
单文件里就是过期小包——用户下载到的助手版本与工具不符。两条闸门挡这个:
`smoke-static.mjs` 断言「内嵌 === 用当前脚本现组装」,`smoke-browser.mjs` 真实点按钮
下载再比字节。别绕过它们,也别把 ZIP 改成 deflate(固定 store-only + 固定时间戳才保证
同输入同字节,压缩会让字节随 zlib 版本浮动,两处比对就失去意义)。
20. **`fs.watch` 递归在 Windows 上只覆盖一层子目录**:watch 模式原先只盯 `src/`,现在补了
21. **`fs.watch` 递归在 Windows 上只覆盖一层子目录**:watch 模式原先只盯 `src/`,现在补了
`scripts/` 的平铺监听(`HELPER_WATCH` 白名单)。若以后把小包脚本挪进子目录,监听要跟着调。
21. **「同输入同字节」必须先解决行尾**(v1.26.1 实发版本抓到):v1.26.0 的 Release 资产比本地
22. **「同输入同字节」必须先解决行尾**(v1.26.1 实发版本抓到):v1.26.0 的 Release 资产比本地
小 416 字节,根因是 `opg-nh.bat` 在 CI(Linux 检出)是 LF、本地(Windows 检出)是 CRLF。
凡是把仓库文件内容打进产物再跨平台比对的场景,**读盘后立刻按目标平台归一化行尾**再算
哈希/CRC——固定 DOS 时间戳只解决了「时间戳浮动」,行尾是另一半。现在的做法是在
`helperFiles` 出口统一 `normalizeEol`(bat→CRLF、其余→LF),并配 `.gitattributes`。
23. **gen.test.js 的字符串断言钉住运行时脚本内部变量名**(`ACT`→`CFG`、`META`、`WALL`、`NAMES`、
`BTN` 等)——这是有意为之,锁的是产物脚本的形状。重构 scripts.js 的配置结构时这些断言会
连环红,属预期:同步更新断言即可,别为绿测在模板里保留旧变量名(v1.27.1 多实例重构的处理方式)。
24. **切段与匹配共用同一字符类时,段内正则的同类兜底是死代码**:parsePageExpr 先按
`[,,、\s]+` 切段,段内正则 `\s*[-~~]\s*` 的空格兜底永远匹配不到——`1 - 20` 被拆成
'1'/'-'/'20' 静默只取两端点(v1.27.1 修复,归一化放切段之前)。写「先 split 再 match」
的解析时先想清楚分隔符由谁消费。

## 六、工具界面 DOM / CSS

25. **同级 z-index 弹层按 DOM 顺序绘制**:统一模态(`.opg-modal-root`,2147483647)与自绘
fixed 弹层(搜索替换/写卡同为 2147483647)叠放时,后 append 的盖住先 append 的——
`_modalRoot` 首次确认后常驻 body,会话内第二个才打开的自绘弹层会把确认框盖在底下
(不可见不可点,看似按钮失灵,v1.27.1 修复)。现在 `_showModal` 每次弹出重挂 body 末尾。
**不能反过来调低自绘弹层的 z-index**:tool.css 主题纹理层 `body::before` 用
z-index 2147483646(pointer-events:none 但绘制在上),弹层降到 100 以下纹理会浮在弹层上
(组件库选择器 z-index:100 就带着这层纹理,属已知观感)。
26. **新增自绘弹层必须挂 `.opg-ov` 类**:core.js 的 Ctrl+Z/Ctrl+Y 与扩展环境 Esc 守卫只认
`.opg-modal-root.show` 与 `.opg-ov`;漏挂的弹层打开时按 Ctrl+Z 照样 undo,renderAll 重建
数据后弹层闭包把输入写进已回退的旧对象——用户看到「插入成功」,重渲染后内容消失
(v1.27.1 组件库选择器踩过)。现存四个:组件库选择器 / 搜索替换 / 新建工程 / 写卡弹窗。
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,7 @@ opening-page-generator/
├── scripts/ # 辅助脚本
│ ├── nh-import.mjs # nhentai 导入(页面服务 / CLI / CONNECT 隧道代理)
│ ├── nh-install.mjs # 注册 / 移除 opg-nh:// 本地协议
│ ├── opg-nh.bat # 协议注册双击批处理(进助手小包,检出 CRLF)
│ ├── nh-lib.mjs # 抓取与解析公共库
│ ├── smoke-static.mjs # 构建后静态冒烟
│ ├── smoke-browser.mjs # 无头浏览器冒烟(playwright)
Expand Down
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
"postbuild": "node scripts/smoke-static.mjs",
"watch": "node build.js --watch",
"test": "vitest run",
"test:watch": "vitest",
"smoke": "node scripts/smoke-static.mjs && node scripts/smoke-browser.mjs",
"lint": "node lint.js",
"nh": "node scripts/nh-import.mjs",
Expand Down
1 change: 0 additions & 1 deletion tests/complib.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,6 @@ describe('random_nr 不重复随机',()=>{
});
it('{{random_nr::}} 宏可被 apply 识别',()=>{
const out=Macros.apply('你好 {{random_nr::甲::乙::丙}}',[{k:'char',v:'x'}]);
console.log('random_nr out:',JSON.stringify(out));
expect(['你好 甲','你好 乙','你好 丙']).toContain(out);
});
});
Expand Down
15 changes: 4 additions & 11 deletions tests/gen.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ describe('Gen.build 转义与宏',()=>{
expect(html).toContain('常见问题');
});
it('bgm 首曲目名预览替换宏',()=>{
const p=proj([{type:'bgm',enabled:true,tracks:[{name:'{{char}}之歌',url:'https://x/a.mp3'}],volume:50,loop:true,showTitle:false,title:'',useTavernCmd:false}]);
const p=proj([{type:'bgm',enabled:true,tracks:[{name:'{{char}}之歌',url:'https://x/a.mp3'}],volume:50,loop:true,showTitle:false,title:''}]);
p.macros=[{k:'char',v:'艾莉丝'}];
expect(Gen.build(p,{isPreview:true})).toContain('艾莉丝之歌');
expect(Gen.build(p,{isPreview:false})).toContain('{{char}}之歌');
Expand Down Expand Up @@ -236,7 +236,7 @@ describe('Gen.build 边界与安全回归',()=>{
expect(html2).not.toContain('"null"');
});
it('bgm 音量 0 不被兜底吞成 50(falsy-0 回归)',()=>{
const b={type:'bgm',enabled:true,tracks:[{name:'x',url:'https://x/a.mp3'}],volume:0,loop:true,showTitle:false,title:'',useTavernCmd:false};
const b={type:'bgm',enabled:true,tracks:[{name:'x',url:'https://x/a.mp3'}],volume:0,loop:true,showTitle:false,title:''};
const html=Gen.build(proj([b]),{isPreview:false});
expect(html).toContain('value="0"');
});
Expand Down Expand Up @@ -364,7 +364,6 @@ describe('Gen.auditCompat 兼容审查',()=>{
const many=Array.from({length:16},(_,i)=>'(组'+i+')').join('');
fb.html='<div>'+many+'</div>';
expect(Gen.auditCompat(p).items.some(x=>/捕获组约 16 个/.test(x.msg))).toBe(true);
expect(Gen.auditCompat(p).items.some(x=>/捕获组约 16 个/.test(x.msg))).toBe(true);
});
it('自由 HTML 区块启用判提示(全权限警示)',()=>{
const p=defaultProject('t');
Expand Down Expand Up @@ -729,6 +728,7 @@ describe('Gen.build 新增五区块(更新日志/闸门/解码/卡池/彩蛋
expect(html).not.toContain('-decl">');
expect(html).not.toContain('-clrow');
expect(html).not.toContain('-egg"');
expect(html).not.toContain('-brv">');
});
it('changelog:版本|日期|内容解析,多段并入内容',()=>{
const html=Gen.build(proj([{type:'changelog',enabled:true,showTitle:true,title:'日志',lines:'v1.0|2025-05-01|发布|首版'}]),{isPreview:false});
Expand Down Expand Up @@ -816,9 +816,6 @@ describe('Gen 完整文档与正则脚本选项',()=>{
});

describe('Gen.build 模糊揭示区(blurreveal)',()=>{
it('默认工程产物不含模糊揭示 DOM(默认停用)',()=>{
expect(Gen.build(defaultProject('t'),{isPreview:false})).not.toContain('-brv">');
});
it('每行一段输出 seg+遮罩,点击脚本随实例输出',()=>{
const html=Gen.build(proj([{type:'blurreveal',enabled:true,showTitle:true,title:'雾语',hint:'点击显示',lines:'第一段\n第二段'}]),{isPreview:false});
expect(html).toContain('-revt">雾语');
Expand Down Expand Up @@ -885,9 +882,7 @@ describe('gate 六主题(经典/帷幕/法阵/金库/扫描/年龄)',()=>{
});
it('经典主题:无年龄内容与脚本,checkbox id 带块索引',()=>{
const html=Gen.build(proj([{type:'gate',enabled:true,title:'开始',text:'引言',buttonText:'进入'}]),{isPreview:false});
expect(html).toMatch(/id="opg-[a-z0-9]+-bk0-gateck"/);
expect(html).toContain('-gatecover">');
expect(html).toContain('-gatebtn">进入');
expect(html).toMatch(/id="opg-[a-z0-9]+-bk0-gateck"/); /* 覆盖断言见「checkbox 与全屏封面 label 联动」,此处只留 bk0 索引与无 age 徽章 */
expect(html).not.toContain('-gagebadge');
expect(html).not.toContain('gateleave');
});
Expand Down Expand Up @@ -942,7 +937,6 @@ describe('gate 六主题(经典/帷幕/法阵/金库/扫描/年龄)',()=>{
const mk=t=>Gen.build(proj([{type:'gate',enabled:true,theme:t,title:'开始',text:'引言',buttonText:'进入',logo:'LOGO'}]),{isPreview:false});
const cur=mk('curtain');
expect(cur).toContain('-gcurr');
expect(cur).toContain('-gcurval');
expect(cur).toContain('-gcurlogo">LOGO');
const seal=mk('seal');
expect(seal).toContain('-gsealtick');
Expand All @@ -956,7 +950,6 @@ describe('gate 六主题(经典/帷幕/法阵/金库/扫描/年龄)',()=>{
const scan=mk('scan');
expect(scan).toContain('-gscanlogo">LOGO');
expect(scan).toContain('-gscanwait');
expect(scan).toContain('-gscandone');
expect(scan).toContain('<svg');
});
it('未知 theme 回落经典(兼容旧工程/手改数据)',()=>{
Expand Down
11 changes: 1 addition & 10 deletions tests/project.test.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
/* 工程数据规范化 / 迁移逻辑单元测试 */
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { Project, setUI } from '../src/js/project.js';
import { BLOCK_DEFS, BLOCK_ORDER, BUILTIN_TEMPLATES, THEME_PRESETS, defaultProject } from '../src/js/defs.js';
import { contrastRatio } from '../src/js/utils.js';
import { BLOCK_DEFS, BLOCK_ORDER, BUILTIN_TEMPLATES, defaultProject } from '../src/js/defs.js';
/* 读取分键存储(v1.27):索引键 + 每工程独立键 */
const storedProjects=()=>JSON.parse(localStorage.getItem(Project.LS_INDEX)||'[]').map(id=>JSON.parse(localStorage.getItem(Project.LS_PROJ+id)));

Expand Down Expand Up @@ -490,14 +489,6 @@ describe('撤销栈纳入主题(v1.24)',()=>{
});

describe('主题预设(v1.24 整套观感包)',()=>{
it('6 套预设均带背景且文字色对底色对比度达标(≥4.5:1)',()=>{
for(const t of THEME_PRESETS){
expect(t.theme.bg,`${t.name} 缺背景`).toBeTruthy();
const bg=t.theme.bg.type==='gradient'?(t.theme.bg.color||''):t.theme.bg.color;
const cr=contrastRatio(t.theme.textColor,bg);
expect(cr,`${t.name} 文字对比度 ${cr}`).toBeGreaterThanOrEqual(4.5);
}
});
it('defaultProject theme 含 bg 与 presetRef 默认值',()=>{
const p=defaultProject('t');
expect(p.theme.bg).toEqual({type:'gradient',color:'#1a1a2e',color2:'#2d1b3d'});
Expand Down
3 changes: 1 addition & 2 deletions tests/themes.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,7 @@ describe('页面预设与材质纯函数',()=>{
expect(purple.theme).toMatchObject({primary:'#7c6cf0',accent:'#e8c47c',textColor:'#f0f0f5',radius:12,titleAlign:'center',motion:'full',bg:{type:'gradient',color:'#161228',color2:'#261b42'}});
expect(purple.theme.skin).toBe('nebula');
expect(purple.theme.headingFont).toBeTruthy();
expect(purple.theme.fontName).toBe('');
expect(purple.caption).toBeTruthy();expect(purple.specimen).toBeTruthy();expect(purple.folio).toBeTruthy();
expect(purple.theme.fontName).toBe(''); /* caption/specimen/folio 由下方六套循环统一覆盖 */
});
it('六套预设名称保持不变,全部六套各有独立皮肤与标题字体',()=>{
expect(THEME_PRESETS.map(t=>t.name)).toEqual(['紫夜幻金','荆棘王室','狐火缘日','蓝电义体','渊语回廊','档案机']);
Expand Down
Loading