refactor(tooling): [MOD-DEV-01] own dev server lifecycle and report port failures

2026-10-18 19:01:20 -08:00 · 2026-09-14 11:29:46 +08:00
1 parent 401d4cdd65
commit 772d79a671
@@ -0,0 +1,247 @@
+{
+  "task": "MOD-DEV-01",
+  "date": "2026-09-14",
+  "baselineCommit": "401d4cdd6557a69f9cfaf564f2b68f8589e526e2",
+  "node": "v24.21.0",
+  "yarn": "1.22.22",
+  "platform": "win32",
+  "dependency": {
+    "name": "mrmime",
+    "version": "2.0.1",
+    "category": "root devDependency",
+    "license": "MIT",
+    "purpose": "MIME lookup only",
+    "lockEntriesAdded": 1,
+    "frozenInstall": "--frozen-lockfile --ignore-scripts",
+    "postinstallExecuted": false
+  },
+  "historicalFailure": {
+    "task": "MOD-DEV-01",
+    "node": "v24.21.0",
+    "servor": "4.0.2",
+    "occupiedPort": 12671,
+    "code": 0,
+    "signal": null,
+    "output": "[ERR] The port you have specified is already in use!\n",
+    "interpretation": "Historical upstream defect reproduction, not candidate success: an occupied requested port exits the entire process with status zero."
+  },
+  "candidate": {
+    "occupiedPortExit": 1,
+    "originalServiceStillResponds": true,
+    "repeatedSamePortLifetimes": 3,
+    "newNodeTests": 8,
+    "cancelledDownloadBytes": 16777216,
+    "heartbeatTest": "Controlled clock; other HTTP and SSE lifecycle tests use real sockets"
+  },
+  "results": [
+    {
+      "file": "refactor/.cache/dev-server-library.log",
+      "passed": 26,
+      "failed": 0,
+      "skipped": 0,
+      "sha256": "abd6fca7249b64a63f9351b1b53f207dac1083fd8d713e23b39bf6e9c1e3f9ee"
+    },
+    {
+      "file": "refactor/.cache/dev-server-ci.log",
+      "passed": 50,
+      "failed": 0,
+      "skipped": 0,
+      "sha256": "04e732cfccb07be92ccdedf5ddc8133b4861f0b631128419c2319183f1aee515"
+    },
+    {
+      "file": "refactor/.cache/dev-server-baseline.log",
+      "passed": 522,
+      "failed": 0,
+      "skipped": 0,
+      "sha256": "a9e44d6c3487319a9b7fbb9058df7a79e3625daf3abb3e4e9cd23c00508e54bd"
+    }
+  ],
+  "logs": [
+    {
+      "file": "refactor/.cache/dev-server-tests-final.log",
+      "sha256": "6cd260af733aa6220d4bf5aeea2307d9140aed7cee9ddb85040c1540c4bcabd3"
+    },
+    {
+      "file": "refactor/.cache/dev-server-types.log",
+      "sha256": "b8ce65e8a25624581da20e526f95117a989ea5c5c3033cc1a3a6861e6cec5f36"
+    },
+    {
+      "file": "refactor/.cache/dev-server-lint-final.log",
+      "sha256": "ccc1f36e43545ccdfb7aef1d55d40496c343ff10c6036c8fd961f378efc48d48"
+    },
+    {
+      "file": "refactor/.cache/dev-server-toolchain.log",
+      "sha256": "1059b56fdfb592beff8f39768d64ad13df19bc9a550a9444a943133278aefb3a"
+    },
+    {
+      "file": "refactor/.cache/dev-server-frozen-install.log",
+      "sha256": "4d0bee94ffb5dd5ee805368049bf45d89de83d9edfbb8fa46deee26977902a33"
+    },
+    {
+      "file": "refactor/.cache/dev-server-browser-verified.log",
+      "sha256": "eda334fa0841c12e815aedfe5aad7c92efaeb0afdb5c01864fdc358ac332829a"
+    },
+    {
+      "file": "refactor/.cache/dev-server-final.log",
+      "sha256": "9062d987689bda3d5285bf51c175350bd938bcbb92db3b86f994d9174a72bf00"
+    }
+  ],
+  "sources": [
+    {
+      "file": "scripts/dev.js",
+      "sha256": "4ef37e14e38ef1219c1f0dd9f477c91142bc222449805b560ed3b210b068655e"
+    },
+    {
+      "file": "scripts/library/development.ts",
+      "sha256": "202d1cfa5cc5ba7a5ee474a5a7e36afaf028b7be834516ab0be5cc97a3a53f71"
+    },
+    {
+      "file": "scripts/library/server.ts",
+      "sha256": "389303abf965e5b8a1138de194b766457f625bf06438b50e48fb388d8a537dfd"
+    },
+    {
+      "file": "scripts/library/assets.ts",
+      "sha256": "639c8137ccce15f903267e066e5dc55b4776c76bdfcfe5550599b15dc17e0f2e"
+    },
+    {
+      "file": "scripts/library/reload.ts",
+      "sha256": "0ee863e38c3065826d6432656e7c7d52ab4326733109195ad57ac6583fc6da58"
+    },
+    {
+      "file": "scripts/library/config.ts",
+      "sha256": "2017a781a78e227e8ecfd98af56ea9d3ae91f4f033f36b371e0efac1995a1aec"
+    },
+    {
+      "file": "scripts/library/vendor.d.ts",
+      "sha256": "af37a4c6bf37fde5c8eff862668f188eb1f3e9e3c12c3d46f563af78bd8b385f"
+    },
+    {
+      "file": "test/dev-server.test.js",
+      "sha256": "9cdb6c7911c036fff84b42edc95cfb039430b618f1ac0c48a736da8c2f646595"
+    },
+    {
+      "file": "test/browser/library-development.spec.js",
+      "sha256": "33e3cd93c726b9b8f3a14d7a98ee7962c0bcc749ac56f6bd9b048b28d7440e7d"
+    },
+    {
+      "file": "package.json",
+      "sha256": "85dcb9c9692d823364ca79d501249aa6e017521b4cd5e720cb1fc2561e0571db"
+    },
+    {
+      "file": "yarn.lock",
+      "sha256": "aa33cfc38c7933ab53ce626a911fdafd7b14023e45f93ca37bf7f2f6a1d3ecce"
+    }
+  ],
+  "browser": {
+    "file": "refactor/.cache/dev-server-browser-verified/report.json",
+    "sha256": "f23105cace080f11a97faaa1992f45cf196bd2fd7c5281f9ef7a0ca7930e5aa2",
+    "stats": {
+      "startTime": "2026-09-14T03:27:04.872Z",
+      "duration": 24092.995,
+      "expected": 6,
+      "skipped": 0,
+      "unexpected": 0,
+      "flaky": 0
+    },
+    "actualDocs": [
+      {
+        "engine": "chromium",
+        "browser": "153.0.8010.12",
+        "platform": "win32",
+        "inputs": [
+          {
+            "file": "docs/uncompiled/artplayer/index.js",
+            "sha256": "a7b9baf492208d8b9b8f56644389b90d23f74df204139ea619efdd667da5ea83"
+          },
+          {
+            "file": "docs/assets/sample/video.mp4",
+            "sha256": "30a2de667ba267b6bc605edcee1c4bd728c048ed76f500ea0e73d1f1a6f8f980"
+          }
+        ],
+        "frameAlpha": 255,
+        "state": {
+          "version": "5.4.1",
+          "typed": 17,
+          "currentTime": 2,
+          "paused": true,
+          "width": 640,
+          "height": 360,
+          "error": 0,
+          "editorModels": 23
+        }
+      },
+      {
+        "engine": "firefox",
+        "browser": "155.0",
+        "platform": "win32",
+        "inputs": [
+          {
+            "file": "docs/uncompiled/artplayer/index.js",
+            "sha256": "a7b9baf492208d8b9b8f56644389b90d23f74df204139ea619efdd667da5ea83"
+          },
+          {
+            "file": "docs/assets/sample/video.mp4",
+            "sha256": "30a2de667ba267b6bc605edcee1c4bd728c048ed76f500ea0e73d1f1a6f8f980"
+          }
+        ],
+        "frameAlpha": 255,
+        "state": {
+          "version": "5.4.1",
+          "typed": 17,
+          "currentTime": 2,
+          "paused": true,
+          "width": 640,
+          "height": 360,
+          "error": 0,
+          "editorModels": 23
+        }
+      },
+      {
+        "engine": "webkit",
+        "browser": "26.6",
+        "platform": "win32",
+        "inputs": [
+          {
+            "file": "docs/uncompiled/artplayer/index.js",
+            "sha256": "a7b9baf492208d8b9b8f56644389b90d23f74df204139ea619efdd667da5ea83"
+          },
+          {
+            "file": "docs/assets/sample/video.mp4",
+            "sha256": "30a2de667ba267b6bc605edcee1c4bd728c048ed76f500ea0e73d1f1a6f8f980"
+          }
+        ],
+        "frameAlpha": 255,
+        "state": {
+          "version": "5.4.1",
+          "typed": 17,
+          "currentTime": 2,
+          "paused": true,
+          "width": 538,
+          "height": 303,
+          "error": 0,
+          "editorModels": 23
+        }
+      }
+    ],
+    "cliShutdown": "IPC emits SIGTERM in child, natural process exit0; not native Unix signal delivery",
+    "fixture": "Real CLI TS/Less/SVG/worker, automatic source/docs reload and compiler failure recovery"
+  },
+  "earlierAttempts": [
+    {
+      "file": "refactor/.cache/dev-server-tests-initial.log",
+      "sha256": "31e84f1014fde74a7c3c0f07a399572c0fb0b2a610d8bd6ee7350165ebf4101c"
+    },
+    {
+      "file": "refactor/.cache/dev-server-browser-docs-initial.log",
+      "sha256": "f60dd2a5b1d59d5dd87519e313d20bf0ab34446a7f3f3ef79b62e16da86a88fb"
+    }
+  ],
+  "limits": [
+    "Windows local runs only; remote OS CI and physical devices remain separate gates",
+    "Docs playback uses tracked core5.4.1, not a newly built release candidate",
+    "Analytics and ads inert in browser fixture",
+    "Build/source/config dependency changes outside selected src still require restart",
+    "Frozen install skipped lifecycle scripts",
+    "No push, publication or package artifact regeneration"
+  ]
+}
@@ -6,8 +6,9 @@ MOD-PLUGIN-01 将 `yarn create:plugin` 的实现拆为严格 TS 渲染/文件写
 运行 `yarn typecheck:scaffold` 与 `yarn test:scaffold`，具体限制和模块地图见
 [生成器维护指南](../scripts/plugin/README.md)。MOD-02 将剩余库构建/开发实现移到
 scripts/library 的严格 TS 模块，保留旧命令/模块入口；其模块地图与生命周期限制见
-[库工具维护指南](../scripts/library/README.md)。Servor 端口失败状态和关闭责任由
-MOD-DEV-01 继续处理，不因 TS 迁移而豁免。
+[库工具维护指南](../scripts/library/README.md)。MOD-DEV-01 将 HTTP、静态文件和
+SSE 拆为自有 TS 模块，修复端口失败退出码并明确关闭责任；根开发依赖
+mrmime 2.0.1 只负责 MIME 名称，Servor 仅保留打开浏览器的 helper。

 ENG-06 保留原来的 Vite 7.3.6、Terser、三种库产物及路径，增加选包参数和 TS 入口；未切换 bundler 或运行时依赖。固定工具链仍为 Node 24.21.0 / Yarn 1.22.22。

@@ -48,6 +49,14 @@ Vite 支持 TS 转译，但不替代类型检查，源码检查继续运行 yarn

 dev 仍监听所选包的 src 目录，包外共享文件/tsconfig/依赖变化需要重启；不宣称已做完整依赖图热更新。错误会打印并保留监听，修复后重建；--no-open 仅禁止自动启动外部浏览器，访问地址不变。实际验证中源码修改和错误恢复后手动刷新页面确认了新结果。

+MOD-DEV-01 的自动化测试直接验证自动刷新、真实 JS CLI 的 SIGTERM 自然退出、
+连续复用同一端口，以及实际 docs/Monaco 的 TS 执行和本地 MP4 播放/跳转。
+默认 8082 不变；可设置 ARTPLAYER_DEV_PORT=0 让测试原子分配端口，或指定其他
+固定端口。冲突/无效值退出非零，不停止原服务。会话 close/done 管理源文件与
+docs 监听器、HTTP 请求/连接、SSE 心跳及正在运行的构建；修改生命周期时先跑
+`yarn test:dev-server`，再跑 `library-development.spec.js` 三引擎。
+详细修正与边界见[记录](changes/2026-09-14-MOD-DEV-01-dev-server.md)。
+
 ## 本次发现的 AMD 构建缺陷

 BUILD-AMD-01：旧插件在压缩 UMD 中把参数 t 写死为全局对象。但构建夹具的包装为 function(e,t)，此时 t 是工厂；旧补丁生成 t.artplayerPluginBuildProbe=t()，AMD 返回虽可用，全局导出却不存在。补丁现在读取外层包装的第一个参数。只有实际 outputOptions.format=umd 时处理，避免将内联 worker 的 ES 输出当作 UMD。
@@ -0,0 +1,110 @@
+# MOD-DEV-01: Owned development server and failure lifecycle
+
+## Scope and reproduced defect
+
+Starting from MOD-02 commit 401d4cdd6557a69f9cfaf564f2b68f8589e526e2,
+replace Servor's HTTP/watch/reload lifetime with small strict TS modules. This
+changes repository development tooling, not any package runtime, declarations,
+DOM hooks or distribution entrypoints. Default port8082, docs root, package output
+paths, old dev command, --no-open and first-success browser opening remain.
+
+The retained `refactor/scripts/servor-port-probe.mjs` reproduces pinned Servor4.0.2
+printing an occupied-port error then exiting0. It uses a private random port;
+the user's existing8082 service is untouched. Missing close ownership was observed
+in upstream source; this does not assert an independently measured upstream leak.
+
+## Structure and resource ownership
+
+- `server.ts`: bind exactly the requested port, own HTTP sockets/request Promises,
+  recursive docs watcher, debounce and shutdown. Fatal errors notify the session
+  immediately so late builds cannot reopen/reload it, then finish cleanup.
+- `assets.ts`: realpath-contained static files, directory/index/fallback routing,
+  classic JS MIME, HTML reload injection, gzip and single media byte ranges.
+  Node stream pipelines release file/compression resources on disconnect and are
+  awaited by shutdown. Outside symlinks/junctions are rejected.
+- `reload.ts`: SSE client set and one shared heartbeat, removed when the final
+  client disconnects or the channel closes. Browser pagehide closes EventSource.
+- `development.ts`: explicit session `{ url, close, done }`, source watcher,
+  serialized/coalesced builds and AbortSignal. Close stops future work and awaits
+  startup/active build, including abort while asynchronous binding is unfinished.
+- `dev.js`: owns/removes SIGINT/SIGTERM handlers, validates optional
+  ARTPLAYER_DEV_PORT and propagates fatal failures as exit1. Port0 requests atomic
+  allocation for tests. Ordinary compiler failures retain the watcher for retry.
+
+The actual module map and modification guidance live in
+[scripts/library/README.md](../../scripts/library/README.md), with test, browser,
+typechecking, CI and development entry documentation updated together.
+`LibraryConfigOptions.outDir` becomes optional to describe existing write:false
+browser resource builds accurately; runtime production config is unchanged.
+
+## Dependencies and compatibility
+
+Add only root devDependency **mrmime2.0.1** (installed MIT license), using its own
+types for MIME lookup. The root Yarn lock gains its single entry. A brief sirv3.0.2
+evaluation was removed: owning range and stream teardown directly keeps these
+critical media-serving semantics visible. Vite dev transforms are unsuitable for
+the existing classic Monaco scripts, and preview process hooks would compete with
+the session's shutdown ownership. Servor4.0.2 stays only for openBrowser and the
+historical probe; its HTTP API is no longer imported or declared.
+
+Yarn1.22.22/Node24.21.0, Lerna, package runtime dependencies and installation hooks
+remain. Frozen install with --ignore-scripts and strict toolchain validation pass;
+the install check does not claim executing postinstall. `test:dev-server` is added
+to `test:node`/`test:library`; existing CI strict types and three-browser jobs cover
+the new modules/spec automatically. No remote workflow run is claimed.
+
+| Surface | Result |
+| --- | --- |
+| Consumer API/types/events/DOM/exports | No package source or public declaration changes |
+| CLI and URLs | Existing commands/default8082 retained; optional port env is additive |
+| Failure | Occupied port now exit1; never kills the pre-existing server |
+| Build/watch | Serial builds, compiler-error recovery and first-success open retained; successful output alone triggers build reload |
+| HTTP | Valid directory slash redirect/index; missing extensionless route returns fallback200 instead of old malformed301 without Location |
+| Media/static HTTP | Correct body-free HEAD, gzip;q=0, byte0-0/suffix/open ranges and 416 for invalid ranges; files remain untransformed |
+| Shutdown | Idempotent close/done, SIGINT/SIGTERM cleanup, no process.exit or global server signal hooks |
+
+These are development-server corrections, not a new public playback API or a
+production hosting replacement. Shared source/config/dependency edits still need
+restart; only selected src builds and docs asset edits are watched.
+
+## Verification and limits
+
+Authoritative results and fingerprints are in
+[dev-server-validation.json](../baselines/dev-server-validation.json).
+
+- 8 new Node tests: real HTTP/HEAD/gzip/ranges and malformed paths, outside
+  junction, real occupied-port CLI exit1 with the original service still serving,
+  three same-port lifetimes with SSE, aborted16MB download, cancellation during
+  startup/build and a separate controlled-clock heartbeat test.
+- 26 library regression tests pass, including real generated plugin builds and
+  consumers. Strict library types and lint pass with the existing one docs type
+  warning. 50 CI regressions and the full baseline suite are recorded separately.
+- Six final Windows browser cases cover real CLI TS/Less/SVG/worker builds,
+  automatic source/docs reload, syntax-error recovery and natural exit0 after
+  invoking the SIGTERM handler. Windows uses IPC to emit that event; native Unix
+  signal delivery remains a remote OS check.
+- Actual docs/Monaco runs TS, plays local MP4, pauses/seeks and yields opaque
+  decoded canvas pixels in Chromium153.0.8010.12, Firefox155.0 and WebKit26.6.
+  Attachments record the actual tracked core5.4.1 and sample hashes, dimensions,
+  time, editor models and browser versions. This validates the replacement server;
+  it does not certify a newly built npm candidate or all editor type diagnostics.
+  Third-party analytics/ads are inert test routes.
+- Initial Node failure was a message-regex assertion against Node's empty
+  AggregateError message; the test now requires exact ECONNREFUSED code. Initial
+  docs failures were an init script writing storage on about:blank and assuming
+  WebKit supplies requestVideoFrameCallback. Restrict storage setup to the owned
+  origin and assert a real decoded canvas frame alongside actual playback/seek.
+  Failed reports are retained; no production pixel or playback assertion removed.
+
+Linux/macOS remote CI, physical devices and release candidate validation remain
+their own gates. These local results close DEV-SERVOR-PORT-01 within this task's
+occupied-port and resource ownership scope, not the whole modernization plan.
+
+## Delivery and rollback
+
+Commit this task alone with [MOD-DEV-01], including source/tests/docs/lock/status.
+Revert that dedicated commit as a unit to restore the previous tooling; doing so
+also restores the recorded upstream port failure. No package artifacts needed
+regeneration, no version bump, push or publication occurs here. Subsequent
+performance measurements must use fresh artifacts because the lock/tooling
+fingerprint changed; previous measurements cannot silently remain current.
@@ -13,6 +13,7 @@
 | `yarn typecheck:docs-tools` / `yarn check:docs-smoke` | 严格检查 TS 示例/声明生成器及 JS/MJS 门面；只读核对确定性生成的 readiness smoke，ci:check 执行 |
 | `yarn typecheck:scaffold` / `yarn test:scaffold` | 严格检查插件生成器与旧 JS 入口；生成包真实构建/类型/分发消费和写入失败回归；分别接入 ci:check 与 test:node |
 | `yarn typecheck:library` / `yarn test:library` | 严格检查库构建/开发 TS 与旧门面；复用真实资源构建、分发、性能证据和生成器回归；类型检查接入 ci:check |
+| `yarn test:dev-server` | 自有 HTTP/SSE 生命周期、端口冲突退出码、Range/HEAD/gzip、取消与重复启动回归；接入 test:node 和 test:library，真实 docs/CLI 检查进入既有三引擎 browser 矩阵 |
 | `yarn check:editor-types` | 只读核对全部编辑器声明、SDK notices 和实际 libUris；主 TS 5.9.3/历史 4.3.5 整组语义检查，ci:check 执行 |
 | `yarn build:site-assets` / `yarn check:site-assets` | 从站点 browser/ TS 生成三个经典脚本；check 只读，root build:docs 先生成；完整 VitePress 构建另行验收 |
 | `yarn typecheck:site-assets` | 严格检查站点 browser/ 模块；生成脚本由 typecheck:docs-tools 的 checkJs 覆盖；均进入 ci:check |
@@ -4,7 +4,7 @@

 基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 245 项，范围 22 个包及工作区/示例。

-状态：todo 57 / doing 16 / blocked 0 / done 172 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 56 / doing 16 / blocked 0 / done 173 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。

 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。

@@ -402,7 +402,7 @@
 | MOD-01 | workspace<br>Bun 固定版本干净安装试点 | ENG-09 | 独立目录的 Bun 安装与 Yarn 冻结基线对比，默认仍为用户选定的 Yarn | Node 测试仍通过；安装与资源一致才决定采用；不改 bundler；不自动替换默认 packageManager 或维护锁文件 | H | todo |
 | MOD-PLUGIN-01 | workspace<br>迁移插件生成器与类型化模板 | ENG-06, SITE-03 | 保留 create:plugin CLI；纯渲染/文件发布边界、TS 工厂/声明/测试/示例及维护指南 | 防止覆盖现有包或示例；失败回退；生成包可构建并通过严格类型、旧模块消费及测试；不自动修改既有包或运行安装发布 | M | done |
 | MOD-02 | workspace<br>整理剩余开发/构建脚本与插件模板 | ENG-06, SITE-03, MOD-PLUGIN-01 | dev/build/utils/create-plugin 的 TS 与可测 CLI，模板同时提供旧 API | 旧脚本入口保留、新插件类型/测试/示例齐全，Lerna 改动单独取证 | M | done |
-| MOD-DEV-01 | workspace<br>修复开发服务器失败状态并明确资源生命周期 | MOD-02 | 修复 Servor 占用端口却退出 0 的已复现问题；明确 HTTP/监听/热刷新连接与定时器的启动、失败和关闭责任 | 保持默认 8082、docs 页面、自动刷新和旧 dev 命令；端口冲突退出非零且不终止其他服务，连续启动/停止及编译错误恢复有实际验证；跨平台监听差异单独留证 | M | todo |
+| MOD-DEV-01 | workspace<br>修复开发服务器失败状态并明确资源生命周期 | MOD-02 | 修复 Servor 占用端口却退出 0 的已复现问题；明确 HTTP/监听/热刷新连接与定时器的启动、失败和关闭责任 | 保持默认 8082、docs 页面、自动刷新和旧 dev 命令；端口冲突退出非零且不终止其他服务，连续启动/停止及编译错误恢复有实际验证；跨平台监听差异单独留证 | M | done |
 | MOD-03 | workspace<br>测量并优化核心热路径 | CORE-22, ENG-08 | DOM 读写、进度更新、持久化、初始化的测量与改进 | 相同设备媒体多次比较，契约不变，收益及无效尝试记录；复用 BASE-06 的原始样本与测量限制，至少三组同环境旧新配对，不以单次变快宣称收益 | M | todo |
 | MOD-04 | workspace<br>测量并优化重型插件/proxy | PKG-DANMUKU-09, PKG-MASK-06, PKG-MB-10, ENG-08 | 帧/队列/推理/音画同步与资源长期运行比较 | 不改默认算法/阈值，性能改善有证据；无收益则保留旧实现 | M | todo |
 | MOD-05 | workspace<br>完成工具链与性能采用决策 | MOD-01, MOD-02, MOD-03, MOD-04, MOD-DEV-01 | 最终 runtime/packageManager/构建配置及性能台账 | 干净安装和全包检查通过；Bun 未采用有理由，不为状态强行切换 | M | todo |
@@ -624,6 +624,7 @@
 - EX-02: [记录](changes/2026-09-14-EX-02-vue-consumer.md) [记录](baselines/vue-consumer-validation.json) [记录](scripts/vue-consumer.mjs)
 - MOD-PLUGIN-01: [记录](changes/2026-09-14-MOD-PLUGIN-01-scaffold.md) [记录](baselines/scaffold-validation.json)
 - MOD-02: [记录](changes/2026-09-14-MOD-02-library-tooling.md) [记录](baselines/library-tooling-validation.json)
+- MOD-DEV-01: [记录](changes/2026-09-14-MOD-DEV-01-dev-server.md) [记录](baselines/dev-server-validation.json)
 - PKG-FACTORY-01: [记录](baselines/factory-assignment-gaps.json) [记录](baselines/factory-compatibility-proposals.json) [记录](factory-compatibility-decision.md) [记录](changes/2026-09-12-PKG-FACTORY-01-decision.md) [记录](type-compatibility-policy.md) [记录](baselines/factory-compatibility-validation.json) [记录](changes/2026-09-13-PKG-FACTORY-01-compatible-types.md)
 - CORE-25: [记录](changes/2026-09-13-CORE-25-defaults-ssr.md) [记录](baselines/defaults-ssr-validation.json)
 - ENG-12: [记录](changes/2026-09-13-ENG-12-library-public.md) [记录](baselines/library-public-validation.json)
@@ -1,5 +1,20 @@
 # 进度与证据

+## MOD-DEV-01 自有开发服务器与关闭流程完成
+
+HTTP、静态资源与 SSE 拆为严格 TS 模块，修复 Servor4.0.2 端口占用却退出0的
+已复现问题。旧 dev 命令/默认8082保留，新增可选 ARTPLAYER_DEV_PORT；冲突退出1，
+原服务继续运行。关闭负责监听器、连接、文件流、心跳/防抖与构建中的异步工作；
+编译错误可恢复，成功构建和 docs HTML 修改均验证自动刷新。根开发依赖新增
+mrmime2.0.1 仅查 MIME，Yarn冻结安装通过；Lerna/安装钩子/包源码与产物未改。
+26项库工具、522项baseline、50项CI通过，严格类型与工具链通过，lint 1既有warning。
+Windows三引擎最终6项通过，包括真实JS命令关闭、Monaco运行TS和本地MP4
+播放/暂停/跳转/解码帧；实际tracked核心5.4.1不等于新npm候选，远端OS与真机
+门槛仍保留。失败尝试和最终报告分开存档。详见[记录](changes/2026-09-14-MOD-DEV-01-dev-server.md)
+和[证据](baselines/dev-server-validation.json)。关闭DEV-SERVOR-PORT-01，245项变为
+173 done、16 doing、56 todo。独立本地提交后核实审计；无推送或发布。
+下一步继续 Auto Thumbnail/VAST 等未完成包与组合验证，VAST默认行为选择仍待答复。
+
 ## MOD-02 库构建与开发脚本 TS 迁移完成

 旧 build/dev/utils/projects/rebuild/build-analysis 入口保留，实现拆为严格 TS
@@ -262,4 +262,4 @@
 | SITE-EDITOR-AMD-01 | resolved / 已复现 | Late Monaco language AMD initialization races with example dependency loading | SITE-03 |
 | VTT-CORE-NAME-01 | open / 已复现 | Published VTT 1.0.1 control name conflicts with the core placeholder introduced in 5.1.7 | PKG-VTT-THUMB-05, REL-08 |
 | SCAFFOLD-OUTPUT-01 | resolved / 已复现 | Plugin generation overwrites existing examples and links to a different example name | MOD-PLUGIN-01 |
-| DEV-SERVOR-PORT-01 | open / 已复现 | Servor exits the entire dev process with status zero when the requested port is occupied | MOD-DEV-01 |
+| DEV-SERVOR-PORT-01 | resolved / 已复现 | Servor exits the entire dev process with status zero when the requested port is occupied | MOD-DEV-01 |
@@ -5919,7 +5919,7 @@
      "id": "DEV-SERVOR-PORT-01",
      "title": "Servor exits the entire dev process with status zero when the requested port is occupied",
      "confirmation": "reproduced",
-      "status": "open",
+      "status": "resolved",
      "owners": [
        "MOD-DEV-01"
      ],
@@ -5930,7 +5930,14 @@
      ],
      "compatibleResolution": "Preserve the default dev URL and CLI while reporting startup failures with nonzero status, without stopping another service. Define ownership of HTTP, watch and reload resources.",
      "closureCriteria": "Real occupied-port and repeated startup/shutdown checks pass for the candidate; build, reload and error recovery remain compatible. Separate source-observed resource ownership limitations from reproduced leaks.",
-      "workspaceState": "Pinned Servor4.0.2 probe prints the occupied-port error and exits0. TS migration retains that upstream behavior; MOD-DEV-01 must resolve it before the final tooling decision. Servor has no exposed close handle; this is a source observation, not a measured leak."
+      "workspaceState": "Owned HTTP/watch/SSE session replaces Servor HTTP. Real occupied-port CLI exits1 and leaves original service alive; repeated same-port shutdown/restart, cancellation, automatic reload and compiler recovery pass on Windows. Remote OS validation remains a separate release gate.",
+      "resolutionEvidence": [
+        "refactor/changes/2026-09-14-MOD-DEV-01-dev-server.md",
+        "refactor/baselines/dev-server-validation.json",
+        "test/dev-server.test.js",
+        "test/browser/library-development.spec.js"
+      ],
+      "resolutionRationale": "Exact port binding rejects with EADDRINUSE; CLI propagates exit1. Explicit close/done owns HTTP sockets, file pipelines, source/docs watchers, SSE heartbeat and active builds. Eight node tests and six Windows real-browser cases cover the stated defect and lifecycle scope without stopping unrelated services."
    }
  ]
 }
@@ -4478,11 +4478,14 @@
      "dependsOn": [
        "MOD-02"
      ],
-      "status": "todo",
+      "status": "done",
      "risk": "M",
      "deliverable": "修复 Servor 占用端口却退出 0 的已复现问题；明确 HTTP/监听/热刷新连接与定时器的启动、失败和关闭责任",
      "acceptance": "保持默认 8082、docs 页面、自动刷新和旧 dev 命令；端口冲突退出非零且不终止其他服务，连续启动/停止及编译错误恢复有实际验证；跨平台监听差异单独留证",
-      "evidence": []
+      "evidence": [
+        "changes/2026-09-14-MOD-DEV-01-dev-server.md",
+        "baselines/dev-server-validation.json"
+      ]
    },
    {
      "id": "MOD-03",
@@ -2,7 +2,9 @@

 `yarn typecheck:library` 检查 scripts/library 的生产构建、开发、配置、banner、
 分析、包选择和重建队列，同时检查旧 JS/MJS 门面。Vite 配置使用已安装的官方
-类型；vendor.d.ts 只描述实际消费的 prompts2.4.2/Servor4.0.2 调用，不声明全 SDK。
+类型；vendor.d.ts 只描述实际消费的 prompts2.4.2/Servor4.0.2 openBrowser 调用，
+不声明全 SDK。MOD-DEV-01 的 HTTP/assets/SSE 模块也在同一严格检查内；
+mrmime2.0.1 使用自带声明，Node HTTP/stream/watch 使用固定 Node 类型。

 `yarn typecheck:scaffold` 检查 scripts/plugin 的严格 TS 模块及旧 JS 命令入口。
 模板本身保留占位符，`yarn test:scaffold` 对实际渲染包执行源码检查和