feat: add browser tests and lazy catalog architecture

Author: idoly

.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Test
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Ensure Podman is available
+        run: command -v podman || (sudo apt-get update && sudo apt-get install --yes podman)
+      - run: npm ci
+      - run: npm run check
+      - run: npm run format:check
+      - name: Run browser tests in Podman
+        run: npm run test:e2e:podman
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: |
+            playwright-report/
+            test-results/
+          if-no-files-found: ignore
+          retention-days: 7

.gitignore

@@ -1,5 +1,7 @@
 node_modules
 dist
+playwright-report
+test-results
 .vite
 .generated
 .tmp

CHANGELOG.md

@@ -17,9 +17,26 @@
 - 目录现包含 9 个分类、121 个公开可调用 API 和 121 个独立 demo。
 - 新增 API 获得完整中英文说明；`clientOnly` 使用浏览器 demo，两个 HTTP 声明 API 使用请求上下文中的 SSR demo。
 
+### Architecture and Performance
+
+- 生成器新增 `data/catalog-index.json` 轻量发现索引；完整签名、关联类型和 demo 源码继续保存在 `data/catalog.json`。
+- 首页、搜索和侧栏只加载轻量索引，API 功能区与完整目录通过 Solid `lazy()` 按需加载。
+- 浏览器 demo 执行器改为动态导入；结果模型和 SSR demo 分类从运行实现中拆分。
+- Hash 导航接入浏览器历史，支持深链接、前进、后退，并在恢复 API 时同步展开所属分类。
+- 生产入口从 557.46 KB 降至 230.58 KB，gzip 从 116.20 KB 降至 75.48 KB；完整 API 数据进入独立按需 chunk。
+
+### Test Automation
+
+- 引入 `@playwright/test@1.62.0`，浏览器及系统依赖由 `mcr.microsoft.com/playwright:v1.62.0-noble` Podman 镜像提供。
+- 新增桌面搜索与导航、浏览器历史、语言和主题持久化、真实 demo 执行、移动端目录以及按需 chunk 加载测试。
+- 新增 GitHub Actions 工作流，并保留失败截图、视频、trace 和 HTML 报告。
+- `npm test` 统一执行类型检查、格式检查、121 个 demo 验证和容器化端到端测试。
+- 新增测试维护指南与函数代码包交付文档，记录 Podman 排错、`code.zip` 内容、监听端口和启动命令。
+
 ### Verification
 
-- 116 个浏览器 demo 和 5 个 SSR demo 全部通过。
+- 116 个浏览器 demo 和 5 个 SSR demo 全部通过，合计 121/121。
+- Podman Chromium 端到端测试 4/4 通过。
 - 类型检查、格式检查和生产构建通过。
 
 ## 1.2-2.0.0-beta.27 - 2026-07-29

DEPLOYMENT.md

@@ -0,0 +1,62 @@
+# Deployment and Code Package
+
+## 函数代码包
+
+本项目通过生产 Node 服务器同时提供静态页面和 Demo API。每次提交或交付部署版本时，除正常源码变更外，还应在仓库根目录生成一份 `code.zip`。
+
+### 打包前检查
+
+```bash
+npm ci
+npm test
+npm run build
+```
+
+`npm run build` 会重新生成 `data/catalog-index.json` 和 `data/catalog.json`，并将前端生产文件写入 `dist/`。
+
+### 生成 ZIP
+
+代码包必须包含 `node_modules`。在仓库根目录执行：
+
+```bash
+rm -f code.zip
+zip -rq -y code.zip ./ \
+  -x '.git/*' \
+     '.generated/*' \
+     '.tmp/*' \
+     'dist/.vite/*' \
+     'playwright-report/*' \
+     'test-results/*' \
+     'code.zip'
+```
+
+也可以在文件管理器中进入项目根目录，全选所有部署文件和 `node_modules`，右键压缩为 ZIP。ZIP 内应直接看到 `package.json`，不能在外层额外包一层项目目录。
+
+上传前可检查关键内容：
+
+```bash
+unzip -l code.zip | rg '(^|/)(package.json|dist/index.html|scripts/demo/server.mjs|data/catalog.json)$'
+```
+
+### 函数配置
+
+- 监听端口：`9000`
+- 启动命令：`npm start`
+- 健康检查：`GET /health`
+- 可选端口环境变量：`PORT`
+
+如果平台注入 `PORT`，服务器会优先监听该值；此时平台的“监听端口”必须与 `PORT` 一致。
+
+### 使用依赖层
+
+如果通过函数计算平台的“层”提供依赖，可以不把 `node_modules` 放入 ZIP，但依赖层必须与当前 Node.js 版本、CPU 架构和 `package-lock.json` 一致，并包含全部生产依赖。默认交付方式仍是将 `node_modules` 放入 `code.zip`，以减少环境差异。
+
+## Delivery Checklist
+
+Before each deployment handoff:
+
+1. Run the complete test suite and production build.
+2. Generate `code.zip` from the repository root, including `node_modules`.
+3. Verify that `package.json` is at the ZIP root.
+4. Configure port `9000` and startup command `npm start`.
+5. Keep `code.zip` out of Git; it is a delivery artifact and is already ignored.

README.md

@@ -10,6 +10,7 @@ The catalog is generated from the packages installed in this repository. It expo
 
 - Node.js `^20.19.0` or `>=22.12.0`
 - npm
+- Podman (for containerized browser tests)
 
 ## Getting Started
 
@@ -23,24 +24,40 @@ Vite prints the local development URL, normally <http://localhost:5173/>.
 ## Commands
 
 ```bash
-npm run dev          # Generate the catalog and start Vite
-npm run generate     # Rebuild the catalog from installed Solid packages
-npm run check        # Regenerate and run TypeScript checks
-npm run build        # Regenerate and create a production build
-npm run preview      # Preview the production build through Vite
-npm start            # Serve the build and Demo APIs with the production Node server
-npm run verify:demos # Verify all browser and SSR examples
-npm run format       # Format project source files with Prettier
-npm run format:check # Check formatting without writing files
+npm run dev              # Generate both catalogs and start Vite
+npm run generate         # Rebuild generated catalog artifacts
+npm run check            # Regenerate and run TypeScript checks
+npm run build            # Regenerate and create a production build
+npm run preview          # Preview the production build through Vite
+npm start                # Serve the build and Demo APIs with the production Node server
+npm test                 # Run the complete static, demo, and browser test suite
+npm run test:e2e         # Run Playwright with a locally installed browser
+npm run test:e2e:podman  # Run Playwright in the pinned browser container
+npm run verify:demos     # Verify all browser and SSR examples
+npm run format           # Format project source files with Prettier
+npm run format:check     # Check formatting without writing files
 ```
 
-`predev`, `precheck`, and `prebuild` regenerate the API catalog automatically.
+`predev`, `precheck`, and `prebuild` regenerate both API catalog artifacts automatically.
+
+## Browser Tests
+
+The end-to-end suite uses Playwright and the `mcr.microsoft.com/playwright:v1.62.0-noble` Podman image. The image owns Chromium and its system libraries, so no browser is installed on the host. The suite builds the production app, starts a Vite preview server inside the temporary container, and covers desktop search and browser history, persisted locale and theme preferences, executable demos, the mobile catalog, and the lazy API chunk boundary.
+
+```bash
+npm run test:e2e:podman
+```
+
+Failures retain screenshots, videos, and Playwright traces under `test-results/`; the HTML report is written to `playwright-report/`. Override the image for an internal registry or mirror with `PLAYWRIGHT_IMAGE` while keeping its Playwright version aligned with `@playwright/test`.
+
+GitHub Actions runs type checks, formatting checks, and the same Podman browser suite on pushes and pull requests. See [tests/README.md](tests/README.md) for the test layers, environment overrides, and artifact workflow.
 
 ## Project Structure
 
 ```text
 data/
-  catalog.json             Generated metadata, locale text pools, and demo source pool
+  catalog-index.json       Lightweight generated navigation and search index
+  catalog.json             Complete metadata, locale text pools, and demo source pool
 
 scripts/
   README.md                 Catalog and demo tooling documentation
@@ -63,7 +80,8 @@ scripts/
 
 src/
   main.tsx                 Browser entry and application composition
-  data/catalog.ts          Typed adapter for generated data
+  data/catalog-index.ts    Eager adapter for lightweight discovery data
+  data/catalog.ts          Lazy adapter for complete API reference data
   features/api/            API page and reference view
   features/demo/           Controller, view, and runtime adapter
   features/home/           Project home page
@@ -73,6 +91,10 @@ src/
   lib/preferences.ts       Safe browser preference adapter
   ui/                      Shared classes, highlighting, and icons
   tailwind.css             CSS-first Tailwind design system
+
+tests/
+  README.md                Test architecture and troubleshooting
+  e2e/                     Playwright production-browser workflows
 ```
 
 `data` is generated, `scripts/catalog` owns catalog content and generation, `scripts/demo` owns executable demo services, and `src` contains the browser application.
@@ -86,7 +108,7 @@ src/
 3. Has at least one callable TypeScript signature.
 4. Is not marked `@internal`.
 
-The generated `data/catalog.json` stores metadata, categories, localized prose, demo source, and compact record indexes. [src/data/catalog.ts](src/data/catalog.ts) validates and expands it for the application. Do not edit or manually format this generated file.
+The generator writes two artifacts. `data/catalog-index.json` contains only the bilingual summaries and identity fields needed by navigation and search. `data/catalog.json` stores complete signatures, related types, localized prose pools, and demo source. [src/data/catalog-index.ts](src/data/catalog-index.ts) loads the index eagerly, while [src/data/catalog.ts](src/data/catalog.ts) validates and expands the complete catalog only when an API page is opened. Do not edit or manually format either generated file.
 
 English and Chinese API prose is resolved by `scripts/catalog/locale-en.mjs` and `scripts/catalog/locale-zh-cn.mjs`. Each strategy contains the current API content and a resolver for APIs discovered in later package versions. Every API has its own language-neutral, complete demo program in `scripts/catalog/demos.mjs`.
 
@@ -130,9 +152,11 @@ Current verified surface:
 
 ## Frontend Architecture
 
-The application is a Solid single-page interface with hash-based API selection. It does not use a router or external state manager. A single optional active-document ID represents both home and API routes, avoiding duplicated route state.
+The application is a Solid single-page interface with hash-based API selection. It does not use a router or external state manager. A single optional active-document ID represents both home and API routes, while a small history adapter keeps deep links and browser back/forward navigation synchronized.
 
+- Navigation and search use a lightweight generated index; complete reference data and the API feature load on demand.
 - Demo execution stays in the feature controller; inline and fullscreen editors share one implementation.
+- The browser runtime is dynamically imported only when an example executes; result types and SSR classification live in a dependency-light model.
 - Tailwind CSS v4 provides the CSS-first design system and utility styles.
 - Prism provides TypeScript/TSX highlighting.
 - Lucide provides interface icons.
@@ -146,6 +170,8 @@ The application is a Solid single-page interface with hash-based API selection.
 
 Detailed maintenance documentation:
 
+- [Deployment and code packaging](./DEPLOYMENT.md)
 - [Release changes](./CHANGELOG.md)
 - [Catalog and demo tooling](./scripts/README.md)
+- [Testing and browser automation](./tests/README.md)
 - [Adding a locale](./src/features/i18n/README.md)

README.zh-CN.md

@@ -10,6 +10,7 @@
 
 - Node.js `^20.19.0` 或 `>=22.12.0`
 - npm
+- Podman（用于容器化浏览器测试）
 
 ## 快速开始
 
@@ -23,24 +24,40 @@ Vite 会输出本地开发地址，通常为 <http://localhost:5173/>。
 ## 常用命令
 
 ```bash
-npm run dev          # 生成目录并启动 Vite
-npm run generate     # 根据已安装的 Solid 包重新生成目录
-npm run check        # 重新生成目录并执行 TypeScript 检查
-npm run build        # 重新生成目录并构建生产版本
-npm run preview      # 通过 Vite 预览生产构建
-npm start            # 使用生产 Node 服务器提供构建产物和示例接口
-npm run verify:demos # 验证全部浏览器与 SSR 示例
-npm run format       # 使用 Prettier 格式化项目源码
-npm run format:check # 仅检查格式，不写入文件
+npm run dev              # 生成两个目录产物并启动 Vite
+npm run generate         # 重新生成目录产物
+npm run check            # 重新生成目录并执行 TypeScript 检查
+npm run build            # 重新生成目录并构建生产版本
+npm run preview          # 通过 Vite 预览生产构建
+npm start                # 使用生产 Node 服务器提供构建产物和示例接口
+npm test                 # 执行完整静态、Demo 与浏览器测试
+npm run test:e2e         # 使用本机已安装的浏览器运行 Playwright
+npm run test:e2e:podman  # 在固定版本浏览器容器中运行 Playwright
+npm run verify:demos     # 验证全部浏览器与 SSR 示例
+npm run format           # 使用 Prettier 格式化项目源码
+npm run format:check     # 仅检查格式，不写入文件
 ```
 
-`predev`、`precheck` 和 `prebuild` 会自动重新生成 API 目录。
+`predev`、`precheck` 和 `prebuild` 会自动重新生成两个 API 目录产物。
+
+## 浏览器测试
+
+端到端测试使用 Playwright 和 Podman 镜像 `mcr.microsoft.com/playwright:v1.62.0-noble`。Chromium 及其系统依赖均由镜像提供，宿主机无需安装浏览器。测试会在临时容器中构建生产版本、启动 Vite 预览服务，并覆盖桌面端搜索与浏览器历史、语言和主题持久化、可执行示例、移动端目录以及 API chunk 懒加载边界。
+
+```bash
+npm run test:e2e:podman
+```
+
+失败时，截图、视频和 Playwright trace 会保留在 `test-results/`，HTML 报告输出到 `playwright-report/`。内部镜像仓库或镜像代理可通过 `PLAYWRIGHT_IMAGE` 覆盖默认镜像，但镜像中的 Playwright 版本必须与 `@playwright/test` 保持一致。
+
+GitHub Actions 会在 push 和 pull request 时执行类型检查、格式检查和同一套 Podman 浏览器测试。测试分层、环境变量和失败产物排查方式见 [tests/README.md](tests/README.md)。
 
 ## 项目结构
 
 ```text
 data/
-  catalog.json             生成的元数据、本地化文本池和示例源码池
+  catalog-index.json       生成的轻量导航与搜索索引
+  catalog.json             完整元数据、本地化文本池和示例源码池
 
 scripts/
   README.md                 目录和示例工具文档
@@ -63,7 +80,8 @@ scripts/
 
 src/
   main.tsx                 浏览器入口与应用组合
-  data/catalog.ts          生成数据的类型适配器
+  data/catalog-index.ts    轻量发现数据的首屏适配器
+  data/catalog.ts          完整 API 参考数据的懒加载适配器
   features/api/            API 页面与参考视图
   features/demo/           示例控制器、视图与运行时适配器
   features/home/           项目首页
@@ -73,6 +91,10 @@ src/
   lib/preferences.ts       安全的浏览器偏好适配器
   ui/                      共享样式、代码高亮与图标
   tailwind.css             Tailwind CSS 设计系统
+
+tests/
+  README.md                测试架构与问题排查
+  e2e/                     Playwright 生产浏览器流程
 ```
 
 `data` 保存生成产物，`scripts/catalog` 负责目录内容与生成，`scripts/demo` 负责可执行示例服务，`src` 包含浏览器应用。
@@ -86,7 +108,7 @@ src/
 3. 至少有一个可调用的 TypeScript 签名。
 4. 没有标记为 `@internal`。
 
-生成的 `data/catalog.json` 保存元数据、分类、本地化内容、示例源码和紧凑记录索引。[src/data/catalog.ts](src/data/catalog.ts) 负责验证并展开数据供应用使用。不要编辑或手动格式化该生成文件。
+生成器会写入两个产物。`data/catalog-index.json` 只包含导航和搜索所需的双语摘要与标识字段；`data/catalog.json` 保存完整签名、关联类型、本地化文本池和示例源码。[src/data/catalog-index.ts](src/data/catalog-index.ts) 在首屏加载轻量索引，[src/data/catalog.ts](src/data/catalog.ts) 仅在打开 API 页面时验证并展开完整目录。不要编辑或手动格式化这两个生成文件。
 
 中英文 API 内容分别由 `scripts/catalog/locale-en.mjs` 和 `scripts/catalog/locale-zh-cn.mjs` 解析。每种策略包含当前 API 内容，以及用于处理未来新增 API 的回退解析器。每个 API 都在 `scripts/catalog/demos.mjs` 中拥有独立、完整且与语言无关的示例程序。
 
@@ -130,9 +152,11 @@ SSR 示例为只读，只执行可信的生成源码。源码和请求正文上
 
 ## 前端架构
 
-应用是使用 Hash 选择 API 的 Solid 单页界面，不依赖路由器或外部状态管理器。首页和 API 页面由单一的可选当前文档 ID 表达，避免维护重复路由状态。
+应用是使用 Hash 选择 API 的 Solid 单页界面，不依赖路由器或外部状态管理器。首页和 API 页面由单一的可选当前文档 ID 表达，小型历史适配层负责同步深链接和浏览器前进、后退行为。
 
+- 导航与搜索使用轻量生成索引；完整参考数据和 API 功能区按需加载。
 - 示例执行由功能控制器负责，内嵌与全屏编辑器复用同一实现。
+- 浏览器运行时仅在执行示例时动态导入；结果类型和 SSR 分类位于无重依赖的模型层。
 - Tailwind CSS v4 提供 CSS-first 设计系统和工具类。
 - Prism 提供 TypeScript/TSX 代码高亮。
 - Lucide 提供界面图标。
@@ -146,6 +170,8 @@ SSR 示例为只读，只执行可信的生成源码。源码和请求正文上
 
 详细维护文档：
 
+- [部署与代码包](./DEPLOYMENT.md)
 - [版本变更](./CHANGELOG.md)
 - [目录与示例工具](./scripts/README.md)
+- [测试与浏览器自动化](./tests/README.md)
 - [添加语言](./src/features/i18n/README.md)