rpg-engine 0.0.0-stage → 0.1.1

package/dist/dashboard/guide/zh.md

@@ -0,0 +1,308 @@
+<!-- Translated from en.md, part by part, by npm run translate: c38df721 53ff5eaa 2020efdb f4fdeebb 80a7cfb9 23c5f59b b8f80c05 8c9f41da 0b4a6ef8 338535a6 728ca4a5 e2839149. Change the English, then run it again. -->
+# RPG Engine：完整指南
+
+**RPG Engine** 让你和一位 **AI 主持人**一起玩桌面角色扮演游戏。你在**聊天**里和主持人交谈；RPG Engine 在幕后工作：它**记住世界**，**掷骰子**，**记账**。聊天旁边，你在浏览器里开着一个页面，也就是**仪表盘**，上面有你的角色卡、骰子、地图和日志。
+
+本指南写给玩家：你不需要会编程。
+
+## 快速开始 <!-- icon: send -->
+
+1. 从 [nodejs.org](https://nodejs.org) 安装 **Node.js**（LTS 版本）。
+2. 安装一个 **AI 智能体**，也就是主持人运行所在的程序，并登录：例如 Claude Code 或 Codex（[2.4](#24-connect-your-ai)）。
+3. 在终端里安装 RPG Engine：`npm install -g rpg-engine`。
+4. 创建战役：`rpg init "The Salt Isles"`。
+5. 进入新文件夹：`cd "The Salt Isles"`，然后在那里启动你的智能体：Claude Code 用 `claude`，Codex 用 `codex`。它问你是否信任这个文件夹时，选择“是”（[2.4](#24-connect-your-ai)），然后写下 *你好！我们开始吧。* 主持人会回复你仪表盘的链接。
+
+## 1. RPG Engine 是什么 <!-- icon: about -->
+
+| 谁 | 做什么 |
+|---|---|
+| **你** | 扮演你的角色：角色做什么、说什么、尝试什么。 |
+| **主持人**（AI） | 讲述故事，扮演其他所有人，决定发生什么，要求掷骰。 |
+| **RPG Engine** | 把世界存在文件里，掷骰子，计算生命值、金钱、时间和距离，在你发现之前保守秘密。 |
+
+世界在每个夜晚之间保持不变，即使换了新聊天，甚至换了另一个 AI：
+
+- **说过的话都算数。**死去的反派不会复活。
+- **骰子是真的。**主持人无法左右骰子，除非你选了最简单的难度。
+- **秘密始终是秘密。**主持人不会告诉你角色不知道的事。
+- **世界在运转。**你休息或赶路时，威胁在逼近，你能看到它们的迹象。
+- **战役就是你电脑上的一个文件夹：**想停就停，以后再接着玩。
+
+目前 RPG Engine 只支持一个游戏系统，**第五版**，基于免费的系统参考文档 5.1（System Reference Document 5.1）。其他系统以后会有（[以后会有](#9-coming-later)）。
+
+---
+
+## 2. 开始使用 <!-- icon: path -->
+
+### 2.1 你需要什么
+
+- 一台装有 Windows、macOS 或 Linux 的电脑，以及一个网页浏览器。
+- **Node.js 22** 或更新版本，从 [nodejs.org](https://nodejs.org) 获取。它自带 `npm`，用来安装 RPG Engine。
+- 一个**终端**：在 Windows 上是“终端”或 PowerShell；在 macOS 上是“终端”。要在某个文件夹里打开终端，右键点击该文件夹，选择**在终端中打开**（Windows）或**服务 > 新建位于文件夹的终端窗口**（macOS）。
+- 一个给主持人用的 **AI 智能体**（[2.4](#24-connect-your-ai)），并选它提供的**最大模型**：小模型更容易被说动而泄露秘密或改变规则。
+
+### 2.2 安装
+
+```text
+npm install -g rpg-engine
+```
+
+用 `rpg --version` 检查是否安装成功。每个战役你只需用一次 `rpg`，用来创建战役；之后由你的智能体自动启动 RPG Engine。
+
+### 2.3 创建战役
+
+在你存放游戏的文件夹里打开终端（做法见 [2.1](#21-what-you-need)）：
+
+```text
+rpg init "The Salt Isles"
+```
+
+这会生成文件夹 `The Salt Isles`，里面是一个新战役；用 `cd "The Salt Isles"` 进入它。记住它在哪里：每次游玩都要回到这里。其余的一切，你之后在聊天或仪表盘里再选；`rpg init --help` 会列出现在就能选的选项，例如 `--language it` 或 `--difficulty hard`。
+
+主持人无法替你创建战役：在 `init` 之前，没有任何东西告诉你的智能体 RPG Engine 在哪里。
+
+### 2.4 连接你的 AI
+
+主持人运行在一个 **AI 智能体**里：这是一个在终端或桌面上运行的 AI 应用，能够处理你电脑上的文件，例如 Claude Code 或 Codex。只有普通聊天，例如 claude.ai 或 ChatGPT，或者手机应用，是不够的：主持人需要读取你电脑上战役的文件。每个智能体都需要自己的套餐和登录：Claude Code 需要付费的 Claude 套餐，Codex 需要 ChatGPT 登录。你只需从它自己的页面安装一次：[Claude Code](https://code.claude.com/docs/en/setup)，[Codex](https://learn.chatgpt.com/docs/codex/cli)。
+
+- **Claude Code**：在战役文件夹里输入 `claude`。它问你是否信任这个文件夹时，选择 **Yes, I trust this folder**；注意，默认选中的答案是 *No, exit*。
+- **Codex**：在战役文件夹里输入 `codex`，它问你是否信任这个文件夹时，回答 yes。如果用它的桌面应用，请在设置里确认游戏聊天已关闭记忆功能。
+- **其他智能体**：在战役文件夹里启动它，并给它 MCP 服务器 `rpg mcp`。RPG Engine 是标准的 MCP 服务器：任何支持 MCP 的智能体都可以当主持人，包括本地运行的。
+
+我们用 **Claude Code** 游玩和测试；**Codex** 已接入并检查过，但还没有用它玩过完整的战役；`init` 也会设置 **Gemini CLI**。战役会关闭智能体自带的记忆：游戏存在它的文件里，这样回到存档时才是真正地回去。
+
+### 2.5 第一次聊天
+
+随便写点什么，比如 *你好！我们开始吧。* 在每次聊天的第一个回复里，主持人都会给出**你的仪表盘链接**，类似 `http://127.0.0.1:4750`：打开它，放在聊天旁边。
+
+在主持人的消息之间，你的智能体会显示它用到的工具：不要打开工具的详情（在 Claude Code 里是 ctrl+o），其中可能有秘密。
+
+新战役会经历三个阶段，显示在仪表盘顶部：**1 设置**（你想怎么玩），**2 零号团**（你在游戏中创建角色），**3 开玩**。
+
+### 2.6 设置：选择你的玩法
+
+主持人只问还缺的内容，一次问几个问题；仪表盘的**设置**步骤会把同样的问题显示成卡片。写下“你来定”，主持人就会替你选。一切之后都可以更改，在聊天里或在**设置**里。
+
+| 设置 | 决定什么 | 可选值 |
+|---|---|---|
+| **导师** | 主持人教你规则的多少 | 关闭、提示、教程 |
+| **难度** | 世界有多难 | 故事、简单、普通、困难、残酷 |
+| **致命度** | 战斗中倒下意味着什么 | 叙事（永不死亡）、史诗（只在关键时刻）、骰子 |
+| **存档** | 你何时可以回头 | 永久死亡、检查点、自由（[3.8](#38-saves-and-going-back)） |
+| **严谨度** | 食物、光照和旅行遵循规则的紧密程度 | 流畅、规则、模拟 |
+| **骰子** | 谁来掷你的骰子 | 数字、实体 |
+| **单位** | 距离和重量 | 公制、英制 |
+| **同伴** | 谁与你同行 | 无、与你一起创建、由主持人创建、游戏中相遇 |
+| **图片** | 地点、任务和所遇之人的图片 | 无、按需、新地点、任务和所遇之人（[3.11](#311-pictures)） |
+| **底线**和**帷幕** | 什么永不出现，什么只在幕后发生 | 列表 |
+| **语言** | 游戏和仪表盘的语言 | 任意 |
+
+第五版还有**成长方式**：经验值或里程碑。
+
+如果没有写好的世界，主持人还会问一个**设定**（类型、基调、几个元素，用你自己的话）和**准备方式**：边玩边即时构建世界，或在开始时一次全部构建。
+
+**主持人的风格**不会被问到，但你可以在聊天或**设置**里更改：**文风**（平实、文学、通俗、诙谐），它编造的**故事**（情境、篇章、章节、悬疑），一位可供**模仿**的作者，或者**用你自己的话**说的任何其他要求。
+
+### 2.7 零号团：你的角色
+
+你和主持人一起创建角色，就像在桌边一样。每个选择都由你做，除非你请主持人代选：你可以带着完整的想法、模糊的想法，或者什么都不带来。在掷任何骰子之前，主持人会告诉你属性值是怎么生成的。角色背景故事不是必需的；如果你写了，主持人会用你的话把它记下来。然后主持人会询问你角色的图片（[3.7](#37-your-characters-story-and-picture)）。RPG Engine 会算出角色卡：你从不需要自己算数。
+
+---
+
+## 3. 游玩 <!-- icon: chat -->
+
+### 3.1 和主持人交谈
+
+用你自己的话，写下你的角色做什么或说什么：
+
+> 我问旅店老板，今晚还有谁路过。
+
+要跳出故事发言，请写在方括号里：*[擒抱是怎么运作的？]* 主持人也会用方括号回答。
+
+你说出你尝试什么；主持人说出发生什么。主持人从不替你的角色做决定，也从不谈论引擎。你可以问它怎么使用仪表盘。
+
+### 3.2 掷骰
+
+只有结果不确定且重要时，主持人才会要求掷骰，并且会先说明赌注是什么。然后：
+
+- **在仪表盘上**，横幅会为每个检定显示一个按钮，例如 *杂技 +4 · 优势*。点击它：骰子会落在页面上，主持人会收到结果。你也可以点击角色卡上亮起的那一行，从骰盘里掷骰，或在横幅里写点别的。
+- **手动**，在横幅的角落或**设置**里选择：横幅会告诉你该掷什么，你从角色卡或骰盘里自己掷。
+- **实体骰子**，在骰子设置为实体时：你写下掷出的点数，*[我掷出了 14。]*，RPG Engine 会加上你的调整值。
+
+**自由掷骰**：点击角色卡上的任意数字，或打开骰盘，随便掷着玩。它们不计入任何结果，主持人也看不到。
+
+**主持人的掷骰**会显示在你的掷骰栏里，秘密掷骰除外。你随时可以问 *[刚才那次掷骰是真的吗？]*：对于秘密掷骰，主持人会给出一个指纹，证明它是在你提问之前掷出的。
+
+### 3.3 场景与战斗
+
+故事以**场景**推进：一场战斗、一次交谈、探索、旅行、一次休息。每个场景结束时，游戏会自动存档，场景也会进入你的日志。
+
+战斗中，主持人会讲述每个不属于你的回合，并在你可以做决定的地方停下。**战斗**部分会显示回合顺序、你队伍的生命值，以及敌人用文字描述的受伤程度。如果你的角色倒下，死亡豁免会大大地显示在页面上。
+
+### 3.4 时间、旅行与运转的世界
+
+RPG Engine 记录日期；两次游玩之间不会流逝时间。说出你要休息，*我们进行一次长休*，休息就会恢复该恢复的东西。说出你去哪里，*我们沿路向北去罗卡*，RPG Engine 会算出路线、距离和天数，途中发生事件时会停下。金钱按游戏中的货币计算，找零也包括在内。
+
+反派有带期限的计划。每过新的一天，主持人都会推进那些时间已经推动的威胁，你会看到它们的迹象，但永远看不到时钟本身。
+
+### 3.5 地图
+
+**世界**显示你的角色知道的地点、它们之间的道路和你走过的路径，其余部分笼罩在迷雾中。**场景**显示你所在地点的地图（如果有的话），以及谁站在哪里；在战斗中轮到你时，你无法到达的格子会被遮住。主持人问你移动到哪里时，点一个格子，或者写出来，例如 *E4*。
+
+### 3.6 任务、日志与笔记
+
+你的角色接下的事务会成为**日志**里的任务，附有目标、期限和衡量方式；给它加星，就能让它一直显示在场景顶部。日志还会一个场景接一个场景地讲述你的**故事**，并保存你的**笔记**：笔记是私密的，除非你**分享**其中一条，主持人会把它当作你的想法，而不是事实。
+
+### 3.7 你角色的故事与图片
+
+在你的角色卡上，**描述**卡片里有一个框，用来写角色的故事：你同意后，主持人会把故事写进去。要添加图片，可以给主持人一个文件（PNG、JPEG、WebP 或 SVG，最大 5 MB），并告诉它文件在你电脑上的位置，也可以让它生成一幅肖像（[3.11](#311-pictures)）：*[给我画一幅肖像：灰色头发编成辫子，下巴上有一道疤。]*
+
+### 3.8 存档与回头
+
+RPG Engine 在每个场景结束时保存整个战役。其余由**存档**设置决定：
+
+| 存档 | 想存就存 | 回头 |
+|---|---|---|
+| **永久死亡** | 否 | 永不 |
+| **检查点** | 否 | 回到上一个存档，仅在你的角色死亡时 |
+| **自由** | 是 | 回到任意存档 |
+
+在所有模式下，你都可以**重新开始**，从游戏开始处或从零号团开始。在聊天里或在**存档**里操作。
+
+回头之后，请**开启一个新聊天**：旧聊天还记得被撤销的内容。在新聊天里写 *继续*，然后在存档里按下**我已开启新聊天**。
+
+### 3.9 游戏时段：停下与回来
+
+想停就停：*[今晚就到这里吧。]* 一切都已存进文件。要回来，在战役文件夹里启动你的智能体，写下 *继续*：主持人会给你一段简短的回顾，然后接着玩。
+
+### 3.10 主持人的心情
+
+仪表盘顶部的机器人就是主持人：它的表情随故事的基调变化，从不泄露你还不知道的事。聊天关闭时，它会睡着。
+
+### 3.11 图片
+
+RPG Engine 可以按**图片**设置，生成你到达的地点、接下的任务和遇到的人的图片，你要求时还会生成你角色的肖像。它使用你电脑上已有的东西和你自己的登录：**Codex** 负责绘制，否则由 **Claude Code** 绘制。**设置**会告诉你这台电脑能不能生成，以及不能时该如何配置。你随时可以把自己的图片交给主持人。
+
+### 3.12 安全：底线、帷幕与停止
+
+**底线**永不出现在游戏里；**帷幕**只在幕后发生。你可以随时写下 *[停]*：主持人会立刻放弃那些内容，并把它加入你的底线。
+
+### 3.13 改变主意
+
+每项设置都可以更改，在聊天里或在**设置**里。主持人在没有规则书依据时做出的裁定，会成为一条**先例**，这样下次同样的问题会得到同样的答案。
+
+---
+
+## 4. 仪表盘 <!-- icon: party -->
+
+这是你自己电脑上的一个页面，只能在那台电脑的浏览器里打开，聊天开着时才有内容。聊天关闭后，它会显示 *未连接*；下次聊天时会自动恢复。
+
+- **队伍**：你的角色卡和同伴的角色卡。点击一个数字即可掷骰；把鼠标悬停在上面，可以看到它的来源。旁边是掷骰记录。
+- **场景**：你在哪里，它的图片和地图，谁在场，正在发生什么。
+- **战斗**：仅在战斗中出现：回合、参战者、你手边有什么。
+- **日志**：任务、故事、你的笔记。
+- **世界**：你的角色所了解的世界地图。
+- **骰盘**：选择骰子和调整值，然后掷出。
+- **存档**、**帮助**、**设置**和**关于**，以图标形式排在这一行的末尾。设置里还有页面自身的偏好：主题、骰子音效、骰子样式。
+
+主持人问你事情时，它的横幅会一直停在顶部，无论你在哪个部分。
+
+---
+
+## 5. 游戏系统与家规 <!-- icon: dice -->
+
+### 5.1 什么是游戏系统
+
+一个游戏的数据：它的角色卡、数值、生物、物品、法术和规则文本。每个战役使用一个系统。RPG Engine 负责算出角色卡，以及消耗和恢复的内容；某项特性如何运作，由主持人阅读规则后裁定，就像在桌边一样。
+
+### 5.2 内置第五版
+
+SRD 5.1 的种族、职业、子职业、一个背景和一个专长；319 个法术，以及武器、护甲、魔法物品和怪物；规则章节，主持人会按原文逐字阅读；完整的角色卡，自动算好。
+
+你也可以游玩 SRD 里没有的内容，只要来自你拥有的书：主持人会把它写成你战役的页面，RPG Engine 会把它们当作自己的内容来处理。RPG Engine 只附带开放内容；你的主持人所知道的并不受此限制。
+
+### 5.3 家规与你自己的补充
+
+告诉主持人：*[家规：攻击掷出自然 1 时，你会掉落武器。]* 它会把这条记作桌边的约定，需要时也会写一个页面或在角色卡上加一个数值。已经写好的家规可以作为文本文件放进战役的 `rules` 文件夹。
+
+### 5.4 添加或导入你自己的游戏系统
+
+暂不支持：目前 RPG Engine 只玩第五版（[以后会有](#9-coming-later)）。
+
+---
+
+## 6. 扩展 <!-- icon: plus -->
+
+暂不支持。扩展将在游戏系统之上为战役增加内容：一个世界、一场冒险、天气这样的功能、可分享的家规。
+
+---
+
+## 7. 战役从何而来，以及它的语言 <!-- icon: world -->
+
+### 7.1 拥有世界的三种方式
+
+- **即时构建**：根据你的设定，主持人在你需要之前，才构建每个地点、人物和情节，并把它们保存下来。
+- **开始时准备**：同上，只是世界在游玩之前就建好。
+- **来自你自己的冒险**：给主持人一份文本或 PDF，请它布置好，*[把这场冒险布置成我们的战役。里面的内容一点都别告诉我。]* 它会写出地点、人物和秘密。目前还没有导入按钮。
+
+一个战役只玩一次：要再玩同一场冒险，请创建新战役。
+
+### 7.2 语言
+
+每个战役一种语言，即主持人的语言，仪表盘随之变化。仪表盘自带 26 种语言。其他任何语言，会由 Codex 或 Claude Code 在你的电脑上翻译；没有它们的话，则由主持人在聊天里翻译。第五版的意大利语术语来自官方意大利语 SRD；规则文本仍是英文，主持人会用你的语言讲述。
+
+---
+
+## 8. 写给好奇的你：战役文件夹 <!-- icon: list -->
+
+你完全不需要打开它，而且里面藏着战役的秘密。文件夹里有：`campaign.yaml`（你的设置）、`state.yaml`（游戏进行到哪里）、`world/`（每个角色、地点、任务等各有一页 markdown）、`rules/`（你的房规）、`images/`、`log.jsonl`（每一次改动）、`.saves/`、`.player/`（你的笔记），以及一些小文件，用来告诉 AI 代理 RPG Engine 在哪里。这些页面使用 Obsidian 的格式。如果你手动改了某一页，主持人会在下一次回答时得知。
+
+RPG Engine 只在这个文件夹里工作：它只在这里读写游戏，绝不会碰你的其他文件。在文件夹之外，它只保留自己的一个数据文件夹（存放仪表盘的翻译，以及你允许安装时的 Codex 或 Claude Code），还有画图时用到的临时文件夹。你的代理在电脑上想做其他任何事，都会先问你。
+
+主持人用的每一条命令，你也可以在战役文件夹里运行：`rpg --help` 会列出全部命令。很多命令会打印出战役的秘密。
+
+---
+
+## 9. 以后会有 <!-- icon: hourglass -->
+
+- **你来当主持人**，由 AI 扮演队伍。
+- **作者模式**：和 AI 一起写一场冒险，然后导出并分享。
+- **同一台电脑上的多名玩家**，各自带着自己的角色，在同一个聊天里轮流行动。
+- **扩展**：设置、冒险、功能和家规。
+- **导入**你的规则书和冒险。
+- **其他游戏**：更多游戏系统，以及你自己的系统。
+
+---
+
+## 10. 问题与故障 <!-- icon: info -->
+
+### 问题
+
+**我需要懂规则吗？**不需要。选择教程导师，想问什么就在方括号里问。
+
+**主持人会作弊吗？**它无法更改 RPG Engine 已掷出的结果，也无法更改已确定的事实；唯一的例外是故事难度。
+
+**要花钱吗？**RPG Engine 是免费的。主持人运行在你的智能体套餐上，或者用本地模型运行在你自己的电脑上。一晚的游戏就是一场很长的聊天：在最小的套餐上，你可能在晚上结束前就达到套餐的上限。图片和翻译用的是同一个套餐。
+
+**我能在手机上玩吗？**不能：主持人运行在你的电脑上，仪表盘也只能在那里打开。
+
+**我能和朋友一起玩吗？**暂时不能：目前是一名玩家、一个角色，加上同伴（[以后会有](#9-coming-later)）。
+
+**下次能换一个 AI 吗？**可以：在另一个智能体里打开这个战役，写下 *继续*。
+
+### 故障
+
+**仪表盘打不开。**问主持人：`[仪表盘的链接是什么？]`。只有在该战役里开着聊天、且主持人给出第一个回复之后，它才能用。
+
+**主持人似乎不懂这个游戏。**你的智能体没有加载 RPG Engine。请检查你是在战役文件夹里启动它的，并且选择了信任。在 Claude Code 里，写 `/mcp` 并重新连接 `rpg`。在 Codex 里，在战役文件夹中运行 `codex mcp list`，结果里必须有 `rpg`。如果找不到 `rpg --version`，请重新安装 RPG Engine（[2.2](#22-install)）。
+
+**更新。**再运行一次 `npm install -g rpg-engine`，然后开启一个新聊天：正在运行的主持人仍然使用它启动时的版本。
+
+**主持人记得我撤销过的事。**开启一个新聊天，并在存档里按下**我已开启新聊天**。
+
+**没有出现图片。**设置 > 图片会告诉你这台电脑能不能生成，以及怎么设置。
+
+**安装失败，或 `rpg` 无法启动。**`node --version` 必须显示 22 或更高。在 Windows 上，请不要把 RPG Engine 和你的战役放在含有 `&` 的路径里。
+
+**仪表盘链接变了。**另一个程序占用了常用的地址；主持人会给你新的链接。

package/dist/dashboard/guide-blocks.js

@@ -0,0 +1,72 @@
+// The markdown the guide is written in (D-413), read into blocks: headings, with an icon in a comment after them (<!-- icon: dice -->); paragraphs, lists,
+// tables, quotes, code. guide-markdown.tsx draws them.
+/** The blocks of a markdown text; its comments, but a heading's icon, left out. */
+export function markdownBlocks(text) {
+    const lines = text.replace(/\r\n/g, "\n").replace(/<!--(?!\s*icon:)[\s\S]*?-->/g, "").split("\n");
+    const blocks = [];
+    let index = 0;
+    // The lines from here on that go together: each the next, while it is one.
+    const run = (belongs) => {
+        const taken = [];
+        while (index < lines.length && belongs(lines[index])) {
+            taken.push(lines[index]);
+            index += 1;
+        }
+        return taken;
+    };
+    while (index < lines.length) {
+        const line = lines[index];
+        const heading = /^(#{1,6})\s+(.*?)\s*(?:<!--\s*icon:\s*([\w-]+)\s*-->)?\s*$/.exec(line);
+        if (line.trim() === "") {
+            index += 1;
+        }
+        else if (heading !== null) {
+            blocks.push({ kind: "heading", level: heading[1].length, text: heading[2], ...(heading[3] === undefined ? {} : { icon: heading[3] }) });
+            index += 1;
+        }
+        else if (line.startsWith("```")) {
+            index += 1;
+            const code = run((one) => !one.startsWith("```"));
+            index += 1;
+            blocks.push({ kind: "code", text: code.join("\n") });
+        }
+        else if (/^-{3,}\s*$/.test(line)) {
+            blocks.push({ kind: "rule" });
+            index += 1;
+        }
+        else if (line.startsWith("|")) {
+            const [head = [], , ...rows] = run((one) => one.startsWith("|")).map(cells);
+            blocks.push({ kind: "table", head, rows });
+        }
+        else if (line.startsWith(">")) {
+            blocks.push({ kind: "quote", blocks: markdownBlocks(run((one) => one.startsWith(">")).map((one) => one.replace(/^> ?/, "")).join("\n")) });
+        }
+        else if (listItem(line) !== undefined) {
+            const ordered = listItem(line)?.ordered ?? false;
+            const items = run((one) => one.trim() !== "" && (listItem(one)?.ordered === ordered || (listItem(one) === undefined && /^\s/.test(one))));
+            blocks.push({ kind: "list", ordered, items: items.reduce((all, one) => (listItem(one) === undefined ? [...all.slice(0, -1), `${all.at(-1) ?? ""} ${one.trim()}`] : [...all, listItem(one)?.text ?? ""]), []) });
+        }
+        else {
+            const paragraph = run((one) => one.trim() !== "" && !/^(#{1,6}\s|```|>|\|)/.test(one) && listItem(one) === undefined);
+            blocks.push({ kind: "paragraph", text: paragraph.map((one) => one.trim()).join(" ") });
+        }
+    }
+    return blocks;
+}
+/** A heading's anchor as GitHub makes it: 2.4 Connect your AI, 24-connect-your-ai. */
+export function anchorOf(heading) {
+    return heading.trim().toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-");
+}
+/** A line's text without its marks, as a card's preview says it. */
+export function plainText(text) {
+    return text.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/\*\*|\*|`/g, "");
+}
+/** A list item's mark and text: - text, or 1. text; undefined for another line. */
+function listItem(line) {
+    const item = /^([-*]|\d+\.)\s+(.*)$/.exec(line);
+    return item === null ? undefined : { ordered: /\d/.test(item[1]), text: item[2] };
+}
+/** A table row's cells: | a | b |, a and b. */
+function cells(line) {
+    return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim());
+}

package/dist/dashboard/guide-markdown.js

@@ -0,0 +1,63 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "preact/jsx-runtime";
+/** Blocks drawn as the page's elements: headings one level under the card's, each with the anchor given by its place among them; a link to an anchor calls go. */
+export function Blocks({ blocks, anchors, go }) {
+    return _jsx(_Fragment, { children: blocks.map((block, index) => _jsx(BlockView, { block: block, anchors: anchors, go: go }, index)) });
+}
+/** A line's text with its bold, italic, code and links. */
+export function Inline({ text, go }) {
+    const parts = [];
+    const marks = /\*\*(.+?)\*\*|\*(.+?)\*|`([^`]+)`|\[([^\]]+)\]\(([^)\s]+)\)/g;
+    let from = 0;
+    for (const match of text.matchAll(marks)) {
+        parts.push(text.slice(from, match.index));
+        const [, bold, italic, code, label, target] = match;
+        const key = match.index;
+        if (bold !== undefined) {
+            parts.push(_jsx("strong", { children: _jsx(Inline, { text: bold, go: go }) }, key));
+        }
+        else if (italic !== undefined) {
+            parts.push(_jsx("em", { children: _jsx(Inline, { text: italic, go: go }) }, key));
+        }
+        else if (code !== undefined) {
+            parts.push(_jsx("code", { children: code }, key));
+        }
+        else {
+            parts.push(_jsx(LinkView, { label: label ?? "", target: target ?? "", go: go }, key));
+        }
+        from = match.index + match[0].length;
+    }
+    parts.push(text.slice(from));
+    return _jsx(_Fragment, { children: parts });
+}
+function BlockView({ block, anchors, go }) {
+    switch (block.kind) {
+        case "heading": {
+            const Tag = `h${Math.min(block.level + 1, 6)}`;
+            return (_jsx(Tag, { id: anchors.get(block), children: _jsx(Inline, { text: block.text, go: go }) }));
+        }
+        case "paragraph":
+            return (_jsx("p", { children: _jsx(Inline, { text: block.text, go: go }) }));
+        case "list": {
+            const items = block.items.map((item, index) => (_jsx("li", { children: _jsx(Inline, { text: item, go: go }) }, index)));
+            return block.ordered ? _jsx("ol", { children: items }) : _jsx("ul", { children: items });
+        }
+        case "table":
+            return (_jsx("div", { class: "guide-table", children: _jsxs("table", { children: [_jsx("thead", { children: _jsx("tr", { children: block.head.map((cell, index) => (_jsx("th", { scope: "col", children: _jsx(Inline, { text: cell, go: go }) }, index))) }) }), _jsx("tbody", { children: block.rows.map((row, index) => (_jsx("tr", { children: row.map((cell, column) => (_jsx("td", { children: _jsx(Inline, { text: cell, go: go }) }, column))) }, index))) })] }) }));
+        case "quote":
+            return (_jsx("blockquote", { children: _jsx(Blocks, { blocks: block.blocks, anchors: anchors, go: go }) }));
+        case "code":
+            return _jsx("pre", { children: _jsx("code", { children: block.text }) });
+        case "rule":
+            return null;
+    }
+}
+/** A link: to a heading of the guide, which go brings into sight; to a page of the web, in a new tab. */
+function LinkView({ label, target, go }) {
+    if (target.startsWith("#")) {
+        return (_jsx("a", { href: target, onClick: (event) => {
+                event.preventDefault();
+                go(target.slice(1));
+            }, children: _jsx(Inline, { text: label, go: go }) }));
+    }
+    return (_jsx("a", { href: target, target: "_blank", rel: "noreferrer", children: _jsx(Inline, { text: label, go: go }) }));
+}

package/dist/dashboard/help.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+// Help (D-409, D-413): the complete guide, in the page's language, as its markdown file has it (guide/<code>.md): what it is, an index of chips, and each of
+// its parts a card that folds, the first two open. Its anchors are the English guide's, so that a link finds its heading in every language.
+import { useEffect, useMemo, useState } from "preact/hooks";
+import { CardHeader } from "./card.js";
+import { anchorOf, markdownBlocks, plainText } from "./guide-blocks.js";
+import { Blocks, Inline } from "./guide-markdown.js";
+import { Icon, iconPath, isIconName } from "./icons.js";
+import { PageHead } from "./pages.js";
+import { pageLanguageOf, t } from "./text.js";
+/** How to play with RPG Engine: the guide, from installing it to the campaign's folder. */
+export function Help() {
+    const language = pageLanguageOf(document.documentElement.lang);
+    const guide = useGuide(language);
+    const [open, setOpen] = useState(() => new Set([0, 1]));
+    const [sought, setSought] = useState();
+    const { lead, parts, anchors } = useMemo(() => guideParts(guide.own, guide.english), [guide]);
+    const toggle = (index, event) => {
+        event.preventDefault();
+        setOpen((before) => new Set(before.has(index) ? [...before].filter((one) => one !== index) : [...before, index]));
+    };
+    // A chip of the index, or a link to a heading, opens its card and brings the heading into sight.
+    const go = (anchor) => {
+        const index = parts.findIndex((part) => [part.heading, ...part.blocks].some((block) => anchors.get(block) === anchor));
+        if (index >= 0) {
+            setOpen((before) => new Set([...before, index]));
+            setSought(anchor);
+        }
+    };
+    useEffect(() => {
+        if (sought === undefined) {
+            return;
+        }
+        const target = document.getElementById(sought);
+        setSought(undefined);
+        if (target === null) {
+            return;
+        }
+        // Under the bar that comes while scrolling, which the heading's scroll-margin cannot know before it comes; the focus where the eye goes.
+        const bar = document.querySelector(".top-bar");
+        const above = (bar === null || getComputedStyle(bar).display === "none" ? 0 : bar.offsetHeight) + 16;
+        const top = target.getBoundingClientRect().top + window.scrollY - above;
+        window.scrollTo({ top, behavior: matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : "smooth" });
+        const focused = target instanceof HTMLDetailsElement ? target.querySelector("summary") : target;
+        if (focused !== null && focused.tagName !== "SUMMARY") {
+            focused.tabIndex = -1;
+        }
+        focused?.focus({ preventScroll: true });
+    }, [sought]);
+    return (_jsxs("section", { class: "page-stack help", "aria-labelledby": "help-title", children: [_jsx(PageHead, { section: "help", id: "help-title" }), _jsx("div", { class: "help-lead", children: _jsx(Blocks, { blocks: lead, anchors: anchors, go: go }) }), _jsx("nav", { class: "help-index", "aria-label": t("Contents"), children: parts.map((part) => (_jsxs("button", { type: "button", class: "help-chip", onClick: () => go(anchors.get(part.heading) ?? ""), children: [_jsx(Icon, { name: iconOf(part.heading) }), _jsx(Inline, { text: part.heading.text, go: go })] }, part.heading.text))) }), _jsx("div", { class: "help-cards", children: parts.map((part, index) => (_jsxs("details", { id: anchors.get(part.heading), class: "group help-card", open: open.has(index), children: [_jsx(CardHeader, { icon: iconPath(iconOf(part.heading)), title: _jsx("h3", { children: part.heading.text }), preview: plainText(part.blocks.find((block) => block.kind === "paragraph")?.text ?? ""), open: open.has(index), onToggle: (event) => toggle(index, event) }), _jsx("div", { class: "guide", children: _jsx(Blocks, { blocks: part.blocks, anchors: anchors, go: go }) })] }, part.heading.text))) })] }));
+}
+/** The guide in a language, and in English for its anchors; empty until they are read. */
+function useGuide(language) {
+    const [guide, setGuide] = useState({ own: "", english: "" });
+    useEffect(() => {
+        let current = true;
+        const read = (code) => fetch(`/guide/${code}.md`).then((response) => (response.ok ? response.text() : "")).catch(() => "");
+        void Promise.all([read("en"), language === "en" ? Promise.resolve(undefined) : read(language)]).then(([english, own]) => {
+            if (current) {
+                setGuide({ own: own === undefined || own === "" ? english : own, english });
+            }
+        });
+        return () => {
+            current = false;
+        };
+    }, [language]);
+    return guide;
+}
+/** The guide's lead, the lines before its first part, its title aside; its parts; and each heading's anchor, the English one at its place. */
+function guideParts(own, english) {
+    const blocks = markdownBlocks(own);
+    const headings = blocks.filter((block) => block.kind === "heading");
+    const englishHeadings = markdownBlocks(english).filter((block) => block.kind === "heading");
+    const sameShape = headings.length === englishHeadings.length && headings.every((heading, index) => heading.level === englishHeadings[index]?.level);
+    const anchors = new Map(headings.map((heading, index) => [heading, anchorOf((sameShape ? englishHeadings[index] : heading)?.text ?? heading.text)]));
+    const first = blocks.findIndex((block) => block.kind === "heading" && block.level === 2);
+    const lead = (first < 0 ? blocks : blocks.slice(0, first)).filter((block) => !(block.kind === "heading" && block.level === 1));
+    const parts = [];
+    for (const block of first < 0 ? [] : blocks.slice(first)) {
+        if (block.kind === "heading" && block.level === 2) {
+            parts.push({ heading: block, blocks: [] });
+        }
+        else {
+            parts.at(-1)?.blocks.push(block);
+        }
+    }
+    return { lead, parts, anchors };
+}
+/** A part's icon, as its heading names it; a book when it names none the page has. */
+function iconOf(heading) {
+    return heading.icon !== undefined && isIconName(heading.icon) ? heading.icon : "help";
+}