@remixmate/cli 0.9.14 → 0.9.16

package/skills/web-record/SKILL.md

@@ -1,60 +1,58 @@
 ---
 name: web-record
 description: |
-  网页录屏 / 分镜视频技能（录制 webm，默认转码 mp4 + 抽封面 + 上传 VOD 并返回 CDN 地址），基于 Playwright Python。
-  支持：固定时长 / 条件触发（元素出现 / 消失）停止、自动滚动录屏（从头划到尾）、自定义分镜（storyboard）、参数化模板。
-  分镜场景：高亮 / 聚焦 / 放大 / 滚动 / 虚拟光标点击 / 打字 / 悬停 / 字幕 / 标题卡 / 箭头 / 编号序列 / 打码 / 代码行高亮。
-
-  只出视频。要静态截图（png/jpg）请用 web-screenshot / `web_screenshot`。
-
-  当用户提到以下任何需求时，立即使用本 skill：
-  - 录屏、网页录制、录制视频、录一段操作、生成 webm、screencast
-  - 滚动录屏、页面从头划到尾的视频
-  - 多场景视频、分镜视频、storyboard、按时间线编排（红框高亮 / 局部放大 / 滚动介绍）
-  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）的动态视频
-  - 用模板一行出片（github-repo-intro / github-readme-tour / github-code-tour 等）
+  Web-page recording / storyboard video skill (records webm, then by default transcodes to mp4 + grabs a cover frame + uploads to VOD and returns a CDN URL), built on Playwright Python.
+  Supports: fixed-duration recording, condition-triggered stop (element appears / disappears), auto-scroll recording (top to bottom), custom storyboards, and parameterized templates.
+  Storyboard scenes: highlight / focus / zoom / scroll / virtual-cursor click / type / hover / caption / title card / arrow / numbered sequence / redact / code-line highlight.
+
+  Video only. For still screenshots (png/jpg) use web-screenshot / `web_screenshot`.
+
+  Use this skill immediately whenever the user asks for any of:
+  - Screen recording, record a web page, record a video, capture an interaction, produce a webm, screencast
+  - Scroll recording, a video that pans the page from top to bottom
+  - Multi-scene video, storyboard video, timeline-sequenced clips (highlight box / zoom-in / scrolling walkthrough)
+  - Animated demos of clicks / typing / hover (virtual cursor + ripple / typewriter / triggering tooltips)
+  - One-command clips from a template (github-repo-intro / github-readme-tour / github-code-tour, etc.)
 triggers:
-  - 录屏、网页录制、录制视频、录一段操作、生成 webm、screencast
-  - 滚动录屏、页面从头划到尾的视频
-  - 多场景视频、分镜视频、storyboard、按时间线编排
-  - 演示点击 / 输入 / 悬停（虚拟鼠标 + 涟漪 / 打字机 / 触发 tooltip）
-  - 模板视频一行出片、按顺序编号高亮多个区域并录制
+  - Screen recording, record a web page, record a video, capture an interaction, produce a webm, screencast
+  - Scroll recording, a video that pans the page from top to bottom
+  - Multi-scene video, storyboard video, timeline-sequenced clips
+  - Animated demos of clicks / typing / hover (virtual cursor + ripple / typewriter / triggering tooltips)
+  - One-command template clips, numbering and highlighting several regions in sequence and recording it
 ---
 
-# 网页录屏 / 分镜视频 Skill（web_record）
+# Web Recording / Storyboard Video Skill (`web_record`)
 
-录屏入口。静态截图请改用 **web-screenshot / `web_screenshot`**。
+The recording entry point. For still screenshots use **web-screenshot / `web_screenshot`** instead.
 
-**脚本位置**：本 skill 没有自己的 `scripts/`，复用 web-screenshot 目录下的 `record.py` 与
-`_media_screenshot/` 包（`skill.json` 的 `entry.scriptPath` 相对指向
-`../web-screenshot/scripts/record.py`）。下文命令里的 **`<RecordScript>`** 一律替换为：
+**Script location**: this skill has no `scripts/` of its own — it reuses `record.py` and the `_media_screenshot/` package from the web-screenshot directory (`skill.json`'s `entry.scriptPath` points relatively at `../web-screenshot/scripts/record.py`). Everywhere the commands below say **`<RecordScript>`**, substitute:
 
 ```
 <SkillDir>/../web-screenshot/scripts/record.py
 ```
 
-> 路径约定：读取系统注入的 `Base directory for this skill: <path>` 作为 `<SkillDir>`，切勿硬编码绝对路径。`python` 在 macOS 上可能需写成 `python3`。
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Never hardcode an absolute path.
 
-## 前置依赖
+## Prerequisites
 
 - **Python 3.9+**
-- **`playwright` pip 包 + chromium 内核**：首次运行**自动 bootstrap**（`pip install playwright` + `playwright install chromium`）。
-- **ffmpeg**（可选）：只在 `--no-upload` 的单机路径下用于裁掉开头加载段。默认的上传路径由 ab-render 在转码同一 pass 里裁，本机不需要 ffmpeg。
+- **The `playwright` pip package + the chromium engine**: the first run **bootstraps automatically** (`pip install playwright` + `playwright install chromium`).
+- **ffmpeg** (optional): only needed on the standalone `--no-upload` path, to trim the loading segment off the start. On the default upload path ab-render trims it in the same transcode pass, so no local ffmpeg is required.
 
-## 输出与上传
+## Output and upload
 
-默认行为（**不是**只落一个 webm）：录制 `.webm` → 交给 ab-render 转码 mp4 + 抽封面 → 上传 VOD → 打印可播放的 CDN 地址，并**删除本地 webm**（VOD 已持有）。
+Default behavior (it does **not** just drop a webm): record `.webm` → hand off to ab-render to transcode to mp4 + grab a cover frame → upload to VOD → print a playable CDN URL, and **delete the local webm** (VOD holds the copy).
 
-- `--no-upload`：跳过收尾，只保留本地 `.webm`（此时用本机 ffmpeg 尽力裁开头，缺 ffmpeg 则保留原片并提示）。
-- `--keep-webm`：上传成功后仍保留本地 `.webm`。
-- `--cover-at-sec`：封面抽帧时间点，默认 `0.5` 秒（避开首帧白屏）。
-- `--vod-title`：VOD 资源标题，默认取输出文件名。
+- `--no-upload`: skip the finishing steps and keep only the local `.webm` (in this case local ffmpeg makes a best-effort trim of the start; without ffmpeg the raw clip is kept and a notice printed).
+- `--keep-webm`: keep the local `.webm` even after a successful upload.
+- `--cover-at-sec`: cover-frame timestamp, default `0.5` seconds (avoids a blank first frame).
+- `--vod-title`: VOD asset title, defaults to the output file name.
 
-需要 env **`PRIV_TOKEN`**（鉴权）与 **`REMOTION_RENDER_API_URL`**（ab-render 地址）。未设 `PRIV_TOKEN` 时自动降级为「仅本地文件」并在 stderr 提示；上传过程出错同样降级，不会丢掉已录好的文件。
+Requires the env vars **`PRIV_TOKEN`** (auth) and **`REMOTION_RENDER_API_URL`** (ab-render address). Without `PRIV_TOKEN` it degrades automatically to "local file only" and says so on stderr; an upload failure degrades the same way, so an already-recorded file is never lost.
 
-## 录屏用法
+## Recording usage
 
-### 固定时长录屏
+### Fixed-duration recording
 
 ```bash
 python3 <RecordScript> \
@@ -64,17 +62,17 @@ python3 <RecordScript> \
   --duration 8000
 ```
 
-### 等条件结束（推荐配合 max-duration 防卡死）
+### Stop on a condition (pair it with max-duration so it can't hang)
 
 ```bash
-# 等到 "加载完成" 元素出现就停
+# Stop once the "loaded" element appears
 python3 <RecordScript> \
   --url "https://example.com" \
   --output "loaded.webm" \
   --stop-when-selector "div.loaded" \
   --max-duration 30000
 
-# 等到 loading 转圈消失就停
+# Stop once the loading spinner disappears
 python3 <RecordScript> \
   --url "https://example.com" \
   --output "spinner_done.webm" \
@@ -82,7 +80,7 @@ python3 <RecordScript> \
   --max-duration 30000
 ```
 
-### 组合：先满足谁就停
+### Combined: whichever fires first wins
 
 ```bash
 python3 <RecordScript> \
@@ -93,7 +91,7 @@ python3 <RecordScript> \
   --max-duration 20000
 ```
 
-### 录屏前等页面就绪
+### Wait for the page to be ready before recording
 
 ```bash
 python3 <RecordScript> \
@@ -104,7 +102,7 @@ python3 <RecordScript> \
   --duration 6000
 ```
 
-### 自动滚动录屏（从头划到尾）
+### Auto-scroll recording (top to bottom)
 
 ```bash
 python3 <RecordScript> \
@@ -118,36 +116,36 @@ python3 <RecordScript> \
   --scroll-pause-bottom 1500
 ```
 
-### 模板视频（快捷出片）
+### Template videos (fast path)
 
-`templates/` 下提供参数化的 storyboard 模板，常见结构一行命令出片：
+`templates/` ships parameterized storyboard templates that turn common structures into a one-line command:
 
 ```bash
-# 列出可用模板
+# List available templates
 python3 <RecordScript> --list-templates
 
-# 用 github-repo-intro 模板录任意 GitHub 仓库
+# Record any GitHub repo with the github-repo-intro template
 python3 <RecordScript> \
   --template github-repo-intro \
   --param repo_url=https://github.com/user/repo \
   --output repo.webm
 ```
 
-可重复 `--param key=value` 覆盖模板里的默认值（标签文字、颜色、缩放倍数等）。模板内 `_meta.params` 声明可接收的参数。
+Repeat `--param key=value` to override the template's defaults (label text, colors, zoom factor, etc.). A template's `_meta.params` declares the parameters it accepts.
 
-**当前模板**：
+**Current templates**:
 
-| 名字 | 说明 | 必填参数 |
-|------|------|---------|
-| `github-repo-intro` | GitHub 仓库三连：项目名红框 → star 页面 zoom → README 滚动 | `repo_url` |
-| `github-readme-tour` | 标题卡 → 项目名 → 光标 hover star → README 滚动 → 结尾呼吁 | `repo_url` |
-| `github-code-tour` | 跳转到文件 → 高亮行范围 → 字幕讲解 | `file_url` / `start_line` / `end_line` |
+| Name | Description | Required params |
+|------|-------------|-----------------|
+| `github-repo-intro` | GitHub repo trio: highlight the project name → zoom the star count → scroll the README | `repo_url` |
+| `github-readme-tour` | Title card → project name → cursor hovers star → README scroll → closing call to action | `repo_url` |
+| `github-code-tour` | Jump to a file → highlight a line range → caption walkthrough | `file_url` / `start_line` / `end_line` |
 
-**新增模板**：在 `<SkillDir>/../web-screenshot/templates/` 下放一个 JSON，按 storyboard 格式写场景，里面用 `{{var_name}}` 占位。可选加 `_meta.params` 声明参数（标 `required: true` / `default: ...`）。占位单独成串时会自动转 int/float/bool（如 `"scale": "{{zoom_scale}}"` 渲染后是数字）。
+**Adding a template**: drop a JSON file under `<SkillDir>/../web-screenshot/templates/`, write the scenes in storyboard format, and use `{{var_name}}` placeholders. Optionally add `_meta.params` to declare parameters (marked `required: true` / `default: ...`). A placeholder that is the entire string is auto-converted to int/float/bool (e.g. `"scale": "{{zoom_scale}}"` renders as a number).
 
-### 自定义分镜（storyboard）
+### Custom storyboards
 
-把一系列「场景」组合成一段视频，场景间用 overlay 淡入淡出过渡（**不会黑屏**）。
+Compose a sequence of "scenes" into one video; scenes are joined by an overlay cross-fade (**never a black frame**).
 
 ```bash
 python3 <RecordScript> \
@@ -157,7 +155,7 @@ python3 <RecordScript> \
   --storyboard story.json
 ```
 
-`story.json` 示例：
+Example `story.json`:
 
 ```json
 {
@@ -173,7 +171,7 @@ python3 <RecordScript> \
       "color": "#ff3b30",
       "lineWidth": 5,
       "padding": 10,
-      "label": "项目名称",
+      "label": "Project name",
       "duration": 3000
     },
     {
@@ -184,7 +182,7 @@ python3 <RecordScript> \
       "rampInMs": 900,
       "holdMs": 2200,
       "rampOutMs": 700,
-      "label": "⭐ Star 数量"
+      "label": "⭐ Star count"
     },
     {
       "type": "scroll",
@@ -198,80 +196,80 @@ python3 <RecordScript> \
 }
 ```
 
-**场景类型**：
+**Scene types**:
 
-*视觉强调*
-- `highlight` — 元素红框 + 标签，`padding` / `lineWidth` / `color` / `duration`
-- `focus` — 周围暗化（spotlight）+ 元素描边 + 标签
-- `zoom` — 放大动画
-  - `target: "element"` (默认) — 缩放目标元素本身（弹性曲线）
-  - `target: "page"` — 像浏览器 zoom 一样整个页面以目标元素中心放大
+*Visual emphasis*
+- `highlight` — box around an element + label; `padding` / `lineWidth` / `color` / `duration`
+- `focus` — dim the surroundings (spotlight) + outline the element + label
+- `zoom` — zoom animation
+  - `target: "element"` (default) — scale the target element itself (elastic curve)
+  - `target: "page"` — zoom the whole page around the target element's center, like browser zoom
   - `scale` / `rampInMs` / `rampOutMs` / `holdMs` / `dim` / `label` / `color`
-- `scroll` — 滚动到目标。`fromSelector` 起点、`toSelector` 终点、`step` / `interval` / `duration` / `holdAtEnd`
-- `wait` — 单纯停顿 `duration`
-
-*交互模拟（虚拟光标）*
-- `click` — 光标飞向元素 → 涟漪 → 真实触发 `el.click()`。`moveMs` / `preHoldMs` / `postHoldMs` / `rippleMs` / `color` / `realClick`(默认 true，可设 false 只动画不点)
-- `type` — 光标飞向输入框 → focus → 逐字打字。`text` / `delay`(ms/字) / `clearFirst` / `moveCursor`
-- `hover` — 光标移到元素并触发原生 hover，常用于悬出 tooltip / hover card。`moveMs` / `holdMs`
-
-*注释表达*
-- `arrow` — 从一个锚点画 SVG 弧线箭头指向另一个锚点。锚点 `from` / `to` 形如 `{selector, side}`（side: center/left/right/top/bottom）或 `{x, y}`。`color` / `lineWidth` / `label` / `duration`
-- `sequence` — 多个 selector 顺序出 ①②③ 圆形 badge + 红框 + 标签。`items: [{selector, label}, ...]` / `stepMs` 控制每步间隔 / `color` / `holdMs`
-- `caption` — 顶部/底部滑入字幕条。`text` / `position: top|bottom` / `background` / `color` / `fontSize` / `duration`
-- `title-card` — 全屏开场/结尾大标题卡。`title` / `subtitle`（可选） / `background` / `accent` / `duration`
-- `redact` — 局部打码：blur / pixelate / 实色。`selectors: [...]` 或 `selector` / `mode: "blur" | "pixelate" | "solid"` / `color`(实色时) / `duration`
-
-*GitHub 专属*
-- `code-lines` — 高亮连续代码行范围（默认匹配新版 React blob `[data-line-number="{n}"]`；老版 blob 表格用 `linePattern: "#LC{n}"`）。`startLine` / `endLine` / `linePattern` / `color` / `label` / `duration`
-
-**自动裁剪**：storyboard 模式录制时会等待页面真正稳定（networkidle + skeleton 消失），并在事后用 ffmpeg 帧精度裁掉开头加载段，最终视频长度 ≈ 各场景总时长。
-
-### 完整参数
-
-| 参数 | 说明 | 默认 |
-|------|------|------|
-| `-u` / `--url` | 目标 URL（必填） | — |
-| `-o` / `--output` | 本地输出 `.webm` 路径 | `recording.webm` |
-| `-b` / `--browser` | `chromium` / `firefox` / `webkit`（建议 chromium） | `chromium` |
-| `--device` | 设备模拟 | 无 |
-| `--viewport` | `"宽,高"` | 无 |
-| `--duration` | 固定录制时长（ms） | 无 |
-| `--stop-when-selector` | 选择器出现就停 | 无 |
-| `--stop-when-hidden` | 选择器消失就停 | 无 |
-| `--max-duration` | 条件模式安全上限（ms） | 60000 |
-| `--scroll-through` | 自动从顶部滚到底部 | 关 |
-| `--scroll-step` | 每步像素 | 60 |
-| `--scroll-interval` | 每步间隔（ms） | 50 |
-| `--scroll-pause-top` | 顶部停留（ms） | 800 |
-| `--scroll-pause-bottom` | 底部停留（ms） | 1200 |
-| `--storyboard` | 分镜 JSON 文件路径 | 无 |
-| `--template` | 模板名（templates/<name>.json）；与 `--storyboard` 互斥 | 无 |
-| `--param` | 模板参数 `key=value`，可重复 | 无 |
-| `--list-templates` | 列出可用模板并退出 | — |
-| `--wait-for-selector` | 开始录前等待出现 | 无 |
-| `--wait-for-timeout` | 开始录前固定等待（ms） | 无 |
-| `--color-scheme` | prefers-color-scheme | 无 |
-| `--user-agent` | 覆盖 UA | 无 |
-| `--timeout` | Playwright 全局超时（ms） | 无 |
-| `--ignore-https-errors` | 忽略证书错误 | 关 |
-| `--storage-state` | storageState JSON 文件 | 无 |
-| `--cookies` | cookies JSON 字符串或文件 | 无 |
-| `--no-upload` | 录完不上传，只保留本地 webm | 关（默认上传） |
-| `--vod-title` | 上传到 VOD 的标题 | 输出文件名 |
-| `--cover-at-sec` | 封面抽帧时间点（秒） | 0.5 |
-| `--keep-webm` | 上传成功后保留本地 webm | 关（默认删除） |
-
-至少需提供 `--duration` / `--stop-when-selector` / `--stop-when-hidden` / `--scroll-through` / `--storyboard` / `--template` 之一；组合使用时**先满足谁就停**，同时受 `--max-duration` 兜底。模板 / storyboard JSON 可自带 `url`，此时可省略 `--url`。
-
-## 错误处理
-
-- **首次跑慢**：脚本自动 `pip install playwright` + `playwright install chromium`，耐心等一次即可。
-- **`ModuleNotFoundError: playwright`**：bootstrap 没装上，手动跑 `pip install playwright && playwright install chromium`。
-- **`Executable doesn't exist`**：浏览器内核没装，跑 `playwright install chromium`。
-- **`Timeout ... exceeded`**：拉大 `--timeout`、`--wait-for-timeout`，或换更稳的 `--wait-for-selector`。
-- **录屏文件没产生**：检查 `--output` 后缀是否 `.webm`；查看 stderr 的 `stop reason`。
-- **只拿到本地路径、没有 CDN 地址**：多半是没设 `PRIV_TOKEN`，或收尾失败降级了，stderr 里有原因。
-- **storyboard 开头还有加载残影**：加大 `settleMs` / `waitForReadySelectors`；`--no-upload` 路径还需本机装 ffmpeg。
-- **登录态失效**：重新导出 `storageState` 或更新 `cookies` JSON；`domain` / `path` 必须匹配。
-- **HTTPS 证书报错**：测试环境可加 `--ignore-https-errors`。
+- `scroll` — scroll to a target. `fromSelector` start, `toSelector` end, `step` / `interval` / `duration` / `holdAtEnd`
+- `wait` — plain pause for `duration`
+
+*Interaction simulation (virtual cursor)*
+- `click` — cursor flies to the element → ripple → really fires `el.click()`. `moveMs` / `preHoldMs` / `postHoldMs` / `rippleMs` / `color` / `realClick` (default true; set false to animate without clicking)
+- `type` — cursor flies to the input → focus → types character by character. `text` / `delay` (ms per char) / `clearFirst` / `moveCursor`
+- `hover` — cursor moves onto the element and triggers a native hover; typical for surfacing a tooltip / hover card. `moveMs` / `holdMs`
+
+*Annotation*
+- `arrow` — draw an SVG curved arrow from one anchor to another. Anchors `from` / `to` look like `{selector, side}` (side: center/left/right/top/bottom) or `{x, y}`. `color` / `lineWidth` / `label` / `duration`
+- `sequence` — several selectors get ①②③ circular badges + boxes + labels in order. `items: [{selector, label}, ...]` / `stepMs` controls the gap between steps / `color` / `holdMs`
+- `caption` — caption bar sliding in from the top/bottom. `text` / `position: top|bottom` / `background` / `color` / `fontSize` / `duration`
+- `title-card` — full-screen opening/closing title card. `title` / `subtitle` (optional) / `background` / `accent` / `duration`
+- `redact` — mask a region: blur / pixelate / solid. `selectors: [...]` or `selector` / `mode: "blur" | "pixelate" | "solid"` / `color` (when solid) / `duration`
+
+*GitHub-specific*
+- `code-lines` — highlight a contiguous code-line range (matches the new React blob `[data-line-number="{n}"]` by default; the old table-based blob needs `linePattern: "#LC{n}"`). `startLine` / `endLine` / `linePattern` / `color` / `label` / `duration`
+
+**Automatic trimming**: in storyboard mode the recorder waits for the page to genuinely settle (networkidle + skeletons gone), then trims the leading load segment afterwards with frame-accurate ffmpeg, so the final video length ≈ the sum of the scene durations.
+
+### Full flag list
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-u` / `--url` | Target URL (required) | — |
+| `-o` / `--output` | Local `.webm` output path | `recording.webm` |
+| `-b` / `--browser` | `chromium` / `firefox` / `webkit` (chromium recommended) | `chromium` |
+| `--device` | Device emulation | none |
+| `--viewport` | `"width,height"` | none |
+| `--duration` | Fixed recording length (ms) | none |
+| `--stop-when-selector` | Stop once this selector appears | none |
+| `--stop-when-hidden` | Stop once this selector disappears | none |
+| `--max-duration` | Safety cap for condition modes (ms) | 60000 |
+| `--scroll-through` | Auto-scroll from top to bottom | off |
+| `--scroll-step` | Pixels per step | 60 |
+| `--scroll-interval` | Interval between steps (ms) | 50 |
+| `--scroll-pause-top` | Pause at the top (ms) | 800 |
+| `--scroll-pause-bottom` | Pause at the bottom (ms) | 1200 |
+| `--storyboard` | Storyboard JSON file path | none |
+| `--template` | Template name (`templates/<name>.json`); mutually exclusive with `--storyboard` | none |
+| `--param` | Template parameter `key=value` (repeatable) | none |
+| `--list-templates` | List available templates and exit | — |
+| `--wait-for-selector` | Wait for this selector before recording | none |
+| `--wait-for-timeout` | Fixed wait before recording (ms) | none |
+| `--color-scheme` | prefers-color-scheme | none |
+| `--user-agent` | Override the User-Agent | none |
+| `--timeout` | Playwright global timeout (ms) | none |
+| `--ignore-https-errors` | Ignore certificate errors | off |
+| `--storage-state` | storageState JSON file | none |
+| `--cookies` | cookies JSON string or file | none |
+| `--no-upload` | Skip the upload; keep only the local webm | off (uploads by default) |
+| `--vod-title` | Title for the VOD upload | output file name |
+| `--cover-at-sec` | Cover-frame timestamp (seconds) | 0.5 |
+| `--keep-webm` | Keep the local webm after a successful upload | off (deleted by default) |
+
+At least one of `--duration` / `--stop-when-selector` / `--stop-when-hidden` / `--scroll-through` / `--storyboard` / `--template` must be supplied; when several are combined, **whichever fires first stops the recording**, with `--max-duration` as the backstop. A template / storyboard JSON may carry its own `url`, in which case `--url` can be omitted.
+
+## Error handling
+
+- **The first run is slow**: the script auto-runs `pip install playwright` + `playwright install chromium`. Wait it out once.
+- **`ModuleNotFoundError: playwright`**: the bootstrap did not complete; run `pip install playwright && playwright install chromium` manually.
+- **`Executable doesn't exist`**: the browser engine is missing; run `playwright install chromium`.
+- **`Timeout ... exceeded`**: raise `--timeout` / `--wait-for-timeout`, or switch to a more reliable `--wait-for-selector`.
+- **No recording file produced**: check that `--output` ends in `.webm`; read the `stop reason` on stderr.
+- **Got a local path but no CDN URL**: usually `PRIV_TOKEN` is unset, or the finishing steps failed and it degraded — stderr has the reason.
+- **Loading artifacts still visible at the start of a storyboard**: raise `settleMs` / add `waitForReadySelectors`; the `--no-upload` path additionally needs local ffmpeg.
+- **Session expired**: re-export `storageState` or update the cookies JSON — `domain` / `path` must match.
+- **HTTPS certificate errors**: in test environments add `--ignore-https-errors`.