@playcraft/cli 0.0.43 → 0.0.46

package/project-templates/phaser/skills/playable-placeholder/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: playable-placeholder
+description: >-
+  Develop-stage asset placeholders: WebP images (shapes, gradients, sidecar JSON)
+  and spectral MP3 audio stubs (ANS-style fingerprint + sidecar JSON).
+  Agent MUST load this skill before Tier 2 materialization in rings 1–3 build.
+  Run ensure-project → inventory contract paths → batch-generate → verify → log developer-log.
+---
+
+# Playable Placeholder — Develop 阶段资产占位
+
+> **何时加载**：Developer 进入 `development` / rings 1–3 `build`，且在写 `game/` 之前要做 **Placeholder materialization** 时，**必须先读本 skill**。
+>
+> **用户**：「生成占位图 / 补齐合约路径 / placeholder / 音频 stub」  
+> **Agent**：ensure-project → 盘点 → 批量生成 → `playcraft image|audio info` → 写 developer-log。
+
+**适用角色**：Developer only。Artist / TA 在后续环替换真实资产；代码路径不变。
+
+---
+
+## 5 步快速流程（推荐照抄执行）
+
+```
+① npm run ensure:project
+② 读 layout-spec assetMapping + game/ Preloader → 列缺失路径
+③ 复制模板 → 填 PLACEHOLDERS / PLACEHOLDER_AUDIO → 运行批量脚本
+④ playcraft image info / audio info + npm run dev（无 404）
+⑤ 更新 logs/developer-log.md § Placeholder materialization
+```
+
+### ① 自举
+
+```bash
+npm run ensure:project
+```
+
+确认 `package.json` 含 `placeholder:gen` 与 `placeholder:gen-audio`（ensure-project 会自动合并）。
+
+### ② 盘点（先列清单再生成）
+
+| 来源                                               | 查什么                  |
+| -------------------------------------------------- | ----------------------- |
+| `docs/layout-spec.md` → `assetMapping`             | 图片/音频合约路径、尺寸 |
+| `docs/implementation-plan.md` § 资产               | Feature 绑定的路径      |
+| `game/**` Preloader / `load.audio` / `this.load.*` | 代码实际 load 的路径    |
+
+对每个路径判断 Tier：
+
+| 磁盘已有？ | 代码 load？        | Tier | 动作                        |
+| ---------- | ------------------ | ---- | --------------------------- |
+| ✅         | —                  | 1    | 跳过                        |
+| ❌         | 静态图片合约       | 2    | `placeholder:gen`           |
+| ❌         | MP3 合约           | 2    | `placeholder:gen-audio`     |
+| —          | 仅 `emit('sfx:…')` | 3    | 事件钩子 + log 原因         |
+| —          | 动态数字/计时      | 3    | `fillText` / DOM + log 原因 |
+
+### ③ 批量生成（首选）
+
+**图片** — 一次性 scaffold + 运行：
+
+```bash
+mkdir -p ta-workspace/scripts ta-workspace/tmp
+cp templates/gen-placeholders.template.mjs ta-workspace/scripts/gen-placeholders.mjs
+# 编辑 PLACEHOLDERS 数组（见下方 schema）
+node ta-workspace/scripts/gen-placeholders.mjs
+# 等价: npm run placeholder:gen -- --batch ta-workspace/tmp/placeholders.batch.json
+```
+
+**音频** — Preloader 已绑定 MP3 路径时：
+
+```bash
+cp templates/gen-placeholder-audio.template.mjs ta-workspace/scripts/gen-placeholder-audio.mjs
+# 编辑 PLACEHOLDER_AUDIO 数组
+node ta-workspace/scripts/gen-placeholder-audio.mjs
+```
+
+### ④ 验证
+
+```bash
+playcraft image info --input assets/images/tiles/tile_gold.webp
+playcraft audio info --input assets/audio/sfx/sfx_match.mp3
+npm run dev
+# 控制台无 asset 404 / load error
+```
+
+### ⑤ 记录
+
+填写 `logs/developer-log.md` § **Placeholder materialization**（每张图/每条音频一行）。
+
+---
+
+## 三档策略
+
+| Tier       | 条件                                        | 动作                                                     |
+| ---------- | ------------------------------------------- | -------------------------------------------------------- |
+| **1**      | `playcraft skills link` / ref-flow 已有文件 | 直接用                                                   |
+| **2 图片** | 合约静态图路径缺失                          | `.webp` + 同名 `.json`                                   |
+| **2 音频** | 合约 MP3 路径缺失且代码 load                | `.mp3` + 同名 `.json` +（spectral 时）`.spectrogram.png` |
+| **3**      | 无静态合约 / 仅事件钩子                     | 最小代码 + developer-log 记原因                          |
+
+**禁止**：`playcraft image generate` / `playcraft tools generate-audio` / placehold.co / 手绘美术。
+
+---
+
+## 图片 CLI
+
+**单次**：
+
+```bash
+npm run placeholder:gen -- \
+  -o assets/images/tiles/tile_gold.webp \
+  --size 128x128 --bg ffcc00 --fg 000000 \
+  --text tile_gold --shape auto
+```
+
+**常用参数**：
+
+| 参数      | 示例                                                                                   | 说明                          |
+| --------- | -------------------------------------------------------------------------------------- | ----------------------------- |
+| `-o`      | `assets/.../btn_cta.webp`                                                              | 无扩展名自动补 `.webp`        |
+| `--size`  | `128x128` / `128`                                                                      | 合约精确尺寸                  |
+| `--bg`    | `ffcc00` / `linear:1a1a2e→ff6b35:horizontal` / `radial:ff6b35@center→transparent@edge` | 纯色或渐变                    |
+| `--fg`    | `000000`                                                                               | 说明文字颜色                  |
+| `--text`  | `tile_gold`                                                                            | elementId（默认 output stem） |
+| `--role`  | `CTA button · 主按钮`                                                                  | 可选；默认从 prefix 推断      |
+| `--shape` | `auto` / `circle` / `rounded` / `fill` / …                                             | `auto` 从 label 推断          |
+| `--batch` | `ta-workspace/tmp/placeholders.batch.json`                                             | 批量 JSON 数组                |
+
+**输出**：`<stem>.webp` + `<stem>.json`（每次必写 sidecar）。
+
+### 图片批量 JSON schema
+
+```json
+[
+  {
+    "path": "assets/images/tiles/tile_gold.webp",
+    "size": "128x128",
+    "bg": "ffcc00",
+    "fg": "000000",
+    "label": "tile_gold",
+    "shape": "auto",
+    "role": "tile · 方块"
+  },
+  {
+    "path": "assets/images/ui/btn_cta.webp",
+    "size": "300x100",
+    "bg": "linear:ff6b35→ffcc00:horizontal",
+    "fg": "ffffff",
+    "label": "btn_cta",
+    "shape": "rounded"
+  }
+]
+```
+
+---
+
+## 音频 CLI（频谱指纹 / ANS 思路）
+
+默认 `--mode spectral`：由 `label` 哈希生成独特频谱笔画，develop 环可听可辨，sidecar 记录 strokes。
+
+**单次**：
+
+```bash
+npm run placeholder:gen-audio -- \
+  -o assets/audio/sfx/sfx_match.mp3 \
+  --label sfx_match --type sfx
+```
+
+| 参数              | 默认  | 说明                                |
+| ----------------- | ----- | ----------------------------------- |
+| `--mode spectral` | ✅    | ANS 式频谱指纹 + `.spectrogram.png` |
+| `--silent`        |       | 完全静音 stub                       |
+| `--tone`          |       | 440Hz 调试哔声                      |
+| `--type sfx`      | 0.35s | 短音效                              |
+| `--type bgm`      | 4.0s  | BGM hum；sidecar `loop: true`       |
+
+**输出**：`<stem>.mp3` + `<stem>.json`（必写）；spectral 模式额外 `<stem>.spectrogram.png`。
+
+### 音频批量 JSON schema
+
+```json
+[
+  {
+    "path": "assets/audio/bgm/bgm_main.mp3",
+    "label": "bgm_main",
+    "type": "bgm",
+    "role": "bgm · 主背景音乐"
+  },
+  {
+    "path": "assets/audio/sfx/sfx_match.mp3",
+    "label": "sfx_match",
+    "type": "sfx",
+    "mode": "spectral"
+  },
+  {
+    "path": "assets/audio/sfx/sfx_click.mp3",
+    "label": "sfx_click",
+    "type": "sfx",
+    "mode": "silent"
+  }
+]
+```
+
+---
+
+## Skill Preflight 勾选（developer-log）
+
+在进入 `game/` 编辑前，于 § Skill Preflight 增加：
+
+| Skill                  | 已读 | 用于                                               |
+| ---------------------- | ---- | -------------------------------------------------- |
+| `playable-placeholder` | ☐    | Tier 2 图片/音频批量占位、渐变、频谱 stub、sidecar |
+
+---
+
+## 常见决策
+
+| 问题                             | 答案                                                   |
+| -------------------------------- | ------------------------------------------------------ |
+| 合约要 atlas，develop 怎么占位？ | 每个 `frameId` 单独一张图到各自路径，不拼 sprite sheet |
+| BGM 要循环？                     | 频谱 stub + 代码 `loop: true`；TA 替换 MP3             |
+| 不想 develop 有任何提示音？      | `--silent`                                             |
+| palette 颜色从哪来？             | `layout-spec.md` → `palette` 最近 hex                  |
+| shape 怎么选？                   | 优先 `--shape auto`；`btn_*`→rounded，`tile_*`→circle  |
+| 能否 AI 生图/生音？              | **不能**（build 环禁止）                               |
+
+---
+
+## 脚本与模板
+
+| 资源         | 路径                                              |
+| ------------ | ------------------------------------------------- |
+| 图片生成器   | `skills/_shared/scripts/gen-placeholder.py`       |
+| 音频生成器   | `skills/_shared/scripts/gen-placeholder-audio.py` |
+| 图片批量模板 | `templates/gen-placeholders.template.mjs`         |
+| 音频批量模板 | `templates/gen-placeholder-audio.template.mjs`    |
+| npm          | `placeholder:gen` / `placeholder:gen-audio`       |
+
+详细参数表：[developer-impl-cookbook.md § Asset Placeholder Strategy](../../.claude/agents/refs/developer-impl-cookbook.md#asset-placeholder-strategy-phase-1)。

package/project-templates/phaser/skills/playable-record/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: playable-record
+description: >-
+  Headed 60fps MP4 recording for playables (step ⑤⑥). Agent MUST run
+  ensure-project and debug-playback checks before npm run record:mp4. Use when
+  any skill needs delivery evidence MP4. User never runs record manually.
+---
+
+# Playable Record Playback (MP4)
+
+> **用户**：「录一版当前 playable」— 通常由 **video-validate-loop** 调用，不单独甩命令给用户。
+
+---
+
+## Agent 入口
+
+### 0. 前置（record 前必做）
+
+```bash
+npm run ensure:project
+npm run verify:contract    # 快速断言 window.__playable 已接线
+```
+
+读 `playable-debug`：`game-config.ts` → `SHOW_DEBUG_BUTTON: true`，`SKIP_TRANSITIONS: false`。
+
+**Harness 契约（pass 标准）** — 游戏须通过 `publishPlayableRuntime()` 暴露：
+
+```js
+window.__playable.autoPlay();
+window.__playable.getState(); // { currentPhase, isGameOver }
+window.__playable.getCanvas?.(); // 可选，录屏取 canvas
+window.__playable.hideDebugUi?.(); // 可选，录屏前隐藏 debug UI
+```
+
+Legacy：`MainScene._onDebugAutoPlay()` 仍可通过但会 warn（2026-Q3 移除）。详见 [harness-legacy-deprecation.md](../../docs/team/harness-legacy-deprecation.md)。
+
+### 1. 录屏
+
+```bash
+npm run record:mp4 -- --headed --fps=60
+# focus / lab
+npm run record:focus -- --scope=EVENT --fixture=match-once --headed
+npm run review:assets
+```
+
+### 2. 验收 spec
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,r_frame_rate,duration \
+  -of default=noprint_wrappers=1 recordings/*.mp4
+```
+
+要求：1080×1920，`60/1`，完整局 ~25s。禁止 Playwright 25fps `recordVideo`。
+
+### 3. 产出
+
+`recordings/playable-YYYYMMDD-HHmmss.mp4` → `npm run review:assets` 生成视频关键帧 review sheet → 交给 video-validate-loop validate。
+
+---
+
+> **九步流水线 ⑤⑥**。主流程 [playable-validate](../playable-validate/SKILL.md)。
+
+## When to Apply
+
+- 需要自动跑完一局并导出视频（HOOK → 一键通关 → ENDCARD）
+- 成片需要 BGM / 消牌音效 / 胜利 jingle
+- 不想改游戏源码或打进发布包
+
+## Quick Start
+
+```bash
+brew install ffmpeg          # 若未安装
+cd testN
+npm install
+npm run record:mp4:install   # 安装 Chromium
+npm run record:mp4 -- --headed --fps=60
+# 或直接：
+node ../skills/playable-record/scripts/record-playable.mjs --root=. --headed --fps=60
+```
+
+输出：`recordings/playable-YYYYMMDD-HHmmss.mp4`
+
+录屏后必须运行：
+
+```bash
+npm run review:assets
+```
+
+检查 `validate/art-review/processed-videos-contact-sheet.png`。命令成功只代表 MP4 文件写出来了，不代表画面正确。
+
+## 流程
+
+```
+game/index.html 加载
+  → 等待 window.__playable（或 legacy MainScene HOOK）
+  → canvas.captureStream(60) + masterGain 单路 MediaRecorder
+  → hook-delay 录入场动画（无声）
+  → __playable.autoPlay()（或 legacy evaluate _onDebugAutoPlay()）
+  → 等待 ENDCARD + tail-delay
+  → 停止录制 → ffmpeg 转 MP4
+```
+
+## CLI 参数
+
+| 参数                  | 默认        | 说明                    |
+| --------------------- | ----------- | ----------------------- |
+| `--port=8080`         | 8080        | http-server 端口        |
+| `--out=recordings/`   | recordings/ | MP4 输出目录            |
+| `--fps=60`            | 60          | Canvas 采集帧率         |
+| `--hook-delay=1200`   | 1200        | HOOK 后等待 ms 再自动玩 |
+| `--tail-delay=2500`   | 2500        | ENDCARD 尾帧停留 ms     |
+| `--timeout=180000`    | 180000      | 整局超时 ms             |
+| `--keep-intermediate` | off         | 保留 capture.webm       |
+| `--headed`            | off         | 有界面浏览器（排查用）  |
+
+## 录屏前配置
+
+[`game/config/game-config.js`](../../game/config/game-config.js)：
+
+- `SKIP_TRANSITIONS: false` — 保留完整动画
+- `SHOW_DEBUG_BUTTON: true` — dev 惯例（录屏通过 evaluate 触发，不依赖按钮）
+
+## 音频原理
+
+Playwright `screencast` / `recordVideo` **不含音频且固定 25fps**，不适合游戏录屏。
+
+改用浏览器内 **`canvas.captureStream(60)` + `MediaRecorder`**，单路同时采集画面与 Web Audio：
+
+```
+game.canvas.captureStream(60) ──┐
+                                ├→ MediaRecorder → capture.webm → ffmpeg → MP4
+masterGain → MediaStreamDest ───┘
+```
+
+[`scripts/lib/record-audio-bridge.js`](../../scripts/lib/record-audio-bridge.js) 在 HOOK 阶段注入 `startAvCapture(fps)`，音画同轨，无需手动对轨。
+
+默认 **60fps**；可通过 `--fps=30` 降低体积。
+
+## 故障排查
+
+| 现象          | 处理                                                                        |
+| ------------- | --------------------------------------------------------------------------- |
+| contract 失败 | 先 `npm run verify:contract` — 缺 `window.__playable` 时修 `game/contract/` |
+| MP4 无音轨    | 确认 runtime 已 boot；bridge 会 `audioContext.resume()`                     |
+| 全程静音      | 检查 `__playable.autoPlay()` 或 legacy `_onDebugAutoPlay`                   |
+| 音画漂移      | 确保 screencast 与 MediaRecorder 同时 start/stop                            |
+| WebGL 异常    | 加 `--headed`                                                               |
+| ffmpeg 找不到 | `brew install ffmpeg`                                                       |
+
+## 已知限制
+
+- 音效为 Web Audio 振荡器合成 tone，与游戏内一致，非 MP3 素材
+- 默认不含 Boot loading（screencast 从 HOOK 开始）
+- 仅 dev 页 `game/index.html`
+- 跳过教程（与一键通关相同）
+
+## Related Skills
+
+- [playable-debug](../playable-debug/SKILL.md) — 一键通关链路
+- [playable-validate](../playable-validate/SKILL.md) — 录屏 validate
+
+## Files
+
+- [`scripts/record-playable.mjs`](../../scripts/record-playable.mjs) — 主脚本
+- [`scripts/lib/record-audio-bridge.js`](../../scripts/lib/record-audio-bridge.js) — 浏览器端音频桥

package/project-templates/phaser/skills/playable-record/scripts/lib/build-artifact.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * Knife 12B — validate/build.json read/write helpers (STOP + slice:set + ring gate).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const BUILD_ARTIFACT_SCHEMA = 1;
+
+export function buildArtifactPath(projectDir, sliceId) {
+  if (sliceId) {
+    return path.join(projectDir, 'validate/build', `${sliceId}.json`);
+  }
+  return path.join(projectDir, 'validate/build.json');
+}
+
+export function readBuildArtifact(projectDir, sliceId) {
+  const perSlice = sliceId ? buildArtifactPath(projectDir, sliceId) : null;
+  if (perSlice && fs.existsSync(perSlice)) {
+    try {
+      return JSON.parse(fs.readFileSync(perSlice, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+  const latest = buildArtifactPath(projectDir);
+  if (!fs.existsSync(latest)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(latest, 'utf8'));
+    if (sliceId && data.sliceId && data.sliceId !== sliceId) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+export function writeBuildArtifact(projectDir, artifact) {
+  const dir = path.join(projectDir, 'validate/build');
+  fs.mkdirSync(dir, { recursive: true });
+  const payload = { schemaVersion: BUILD_ARTIFACT_SCHEMA, ...artifact };
+  const json = `${JSON.stringify(payload, null, 2)}\n`;
+  fs.writeFileSync(buildArtifactPath(projectDir, payload.sliceId), json);
+  fs.writeFileSync(buildArtifactPath(projectDir), json);
+  return payload;
+}
+
+/**
+ * @returns {string[]} validation errors (empty = pass)
+ */
+export function validateBuildArtifactForSlice(projectDir, slice) {
+  const errors = [];
+  if (!slice?.sliceId) return ['missing sliceId for build artifact check'];
+  const build = readBuildArtifact(projectDir, slice.sliceId);
+  if (!build) {
+    errors.push(
+      `slice "${slice.sliceId}": missing validate/build.json (run npm run build before slice:set verified)`,
+    );
+    return errors;
+  }
+  if (build.sliceId !== slice.sliceId) {
+    errors.push(
+      `validate/build.json sliceId "${build.sliceId}" does not match active slice "${slice.sliceId}"`,
+    );
+  }
+  if (build.ok !== true) {
+    const problems = Array.isArray(build.problems) ? build.problems.join('; ') : 'build failed';
+    errors.push(`slice "${slice.sliceId}": validate/build.json ok=false — ${problems}`);
+  }
+  const expectedTier = String(slice.evidenceTier || 'probe');
+  if (build.evidenceTier && build.evidenceTier !== expectedTier) {
+    errors.push(
+      `slice "${slice.sliceId}": build evidenceTier "${build.evidenceTier}" != slice "${expectedTier}"`,
+    );
+  }
+  if (expectedTier === 'video-vlm') {
+    const ring = build.iteration || 1;
+    const mp4 = path.join(projectDir, `validate/ring${ring}/autoplay.mp4`);
+    if (!fs.existsSync(mp4)) {
+      errors.push(`slice "${slice.sliceId}": video-vlm tier requires ${path.relative(projectDir, mp4)}`);
+    }
+    const vlmRefs = Array.isArray(build.artifactRefs)
+      ? build.artifactRefs.filter((r) => /vlm-video\.json$/.test(r))
+      : [];
+    const vlmPath = vlmRefs[0]
+      ? path.join(projectDir, vlmRefs[0])
+      : path.join(projectDir, `validate/ring${ring}/vlm-video.json`);
+    if (!fs.existsSync(vlmPath)) {
+      errors.push(`slice "${slice.sliceId}": video-vlm tier requires VLM verdict artifact`);
+    }
+  }
+  return errors;
+}

package/project-templates/phaser/skills/playable-record/scripts/lib/dev-server.mjs

@@ -0,0 +1,104 @@
+/**
+ * Shared dev-server helpers for verify / record / dev:start scripts.
+ *
+ * Single source of truth for how the harness boots a server and discovers the
+ * real listening URL. Previously these were copy-pasted into verify-contract,
+ * verify-firstwin and record-playable, which let the port-detection logic drift.
+ *
+ * Vite runs with strictPort:false, so when the preferred port (3000) is taken it
+ * auto-increments. `detectDevUrl` parses Vite's `Local:` stdout line to recover
+ * the actual port instead of guessing — this is what keeps devUrl correct under
+ * port drift (see docs/harness/experiment-lessons.md §9.2).
+ */
+
+import { spawn } from 'node:child_process';
+
+const LOCAL_URL_RE = /Local:\s+(http:\/\/(?:localhost|127\.0\.0\.1):\d+\/)/;
+
+/** Poll a URL with HEAD until it responds or the timeout elapses. */
+export async function waitForHttp(url, timeoutMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url, { method: 'HEAD' });
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new Error(`Server not ready: ${url}`);
+}
+
+/** Spawn `npm run dev` (Vite) bound to 127.0.0.1 with piped stdio for URL detection. */
+export function startDevServer(cwd) {
+  return spawn('npm', ['run', 'dev', '--', '--host', '127.0.0.1'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/** Spawn a static http-server for the non-dev probe path. */
+export function startHttpServer(port, cwd) {
+  return spawn('npx', ['http-server', '.', '-p', String(port), '-c-1', '--cors'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * Parse a chunk of dev-server output for Vite's `Local: http://…:PORT/` line.
+ * Exposed for unit testing the port-drift case.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function parseLocalUrl(text) {
+  const m = String(text).match(LOCAL_URL_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve the actual dev-server URL by watching stdout/stderr for Vite's
+ * `Local:` line. Falls back to `preferredUrl` if nothing is parsed in time.
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} preferredUrl
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+export function detectDevUrl(child, preferredUrl, timeoutMs = 30000) {
+  return new Promise((res) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      res(preferredUrl);
+    }, timeoutMs);
+    const onData = (data) => {
+      const url = parseLocalUrl(data);
+      if (url) {
+        clearTimeout(timer);
+        cleanup();
+        res(url);
+      }
+    };
+    const cleanup = () => {
+      child.stdout?.off('data', onData);
+      child.stderr?.off('data', onData);
+    };
+    child.stdout?.on('data', onData);
+    child.stderr?.on('data', onData);
+  });
+}
+
+/** Pick a free port starting at `preferred`; skips ports already serving `pathToProbe`. */
+export async function pickServerPort(preferred, pathToProbe = '/game/index.html') {
+  for (let i = 0; i < 20; i += 1) {
+    const port = preferred + i;
+    try {
+      await waitForHttp(`http://127.0.0.1:${port}${pathToProbe}`, 400);
+      // Something already serves here — try the next port.
+      continue;
+    } catch {
+      return port;
+    }
+  }
+  return preferred + 20;
+}