ArtPlayer/scripts/library/README.md

Library build and development tooling

Use Node from .node-version and Yarn Classic 1.22.22. The historical JS/MJS entrypoints remain checked compatibility shims; implementation lives in strict TS. No runtime/build dependency or bundler was replaced by this migration.

Module	Responsibility
projects.ts	Deterministic workspace discovery, CLI selection, non-TTY failure, one JS/TS entry
names.ts	Historical camelCase/PascalCase library global names
config.ts	Vite configuration and resource/worker/output targets; typed with installed Vite declarations
banner.ts	Version/license/notices, UMD AMD/global identity, inline-worker banner removal
production.ts	Sequential package/format builds, checked dist cleanup, docs copy and optional analysis
analysis.ts	Per-build module and artifact size/hash reports outside dist
development.ts	Servor demo startup, initial IIFE build, source watcher, first-success browser opening
rebuild.ts	One active build Promise, coalesced pending changes and later retry after rejection
vendor.d.ts	Only the consumed prompts 2.4.2 / Servor 4.0.2 APIs; verified against installed sources

build.js and dev.js own command execution/error reporting. utils.js, projects.js, rebuild.js and build-analysis.mjs keep their previous named exports. Importing implementation modules does not start a server/build or read the current workspace; the explicit run functions do that work. TypeScript annotation removal uses the canonical Node version; Node 20 consumer validation concerns the built libraries, not executing these repository TS tools.

Stable commands and build behavior

yarn build artplayer artplayer-plugin-chapter
yarn build all --analyze
yarn dev artplayer --no-open
yarn build --help
yarn dev --help
yarn typecheck:library
yarn test:library

No-argument TTY selection uses the same prompts UI. Missing names in non-TTY mode, unknown/inherited project names and ambiguous JS/TS entries fail before cleaning dist or starting the server. Build format order remains modern UMD .js es2020, legacy UMD .legacy.js es2015, then ESM .mjs es2020. Main/legacy use the same Terser options; ESM remains unminified. Notice text, worker handling, AMD globals, default exports, copied docs paths and --analyze output remain intact. A missing or non-string manifest version now fails before that package's dist cleanup. Multi-package builds are sequential, not an all-packages transaction.

Vite types constrain configuration but do not replace source typechecking. Avoid casts that hide incompatible plugin/output types. config.ts deliberately sets publicDir: false so core declaration sources cannot leak into distribution files. Keep unknown UMD wrappers as explicit failures when upgrading Vite/Terser.

Performance artifact verification fingerprints the JS entry shims and all code/JSON under scripts/library/, including additions/removals. Do not reduce that coverage to config.ts alone: banners, name mapping, project discovery or analysis may also affect artifacts. Markdown maintenance changes are not build inputs.

Development lifetime and remaining server work

CLI defaults remain port 8082 and docs/index.html, with output at docs/uncompiled//index.js. The output directory is created before Servor enumerates directories for its Linux file watchers. The internal runDevelop function accepts a port only for isolated callers/tests; the CLI does not add a new flag. Do not stop an unrelated server occupying 8082 to run a test.

Build errors are reported while keeping the source watcher alive. Changes during a build schedule one subsequent build rather than concurrent writes. Browser opening happens once after the first successful build; --no-open suppresses it. Only the package src tree is watched; external dependencies/configuration changes still require restart. Tests use real automatic reload rather than racing it with a second manual navigation.

Servor still owns its HTTP server, docs watchers, reload sockets/timers and SIGINT handler until process exit; its API exposes no close handle. MOD-DEV-01 tracks replacing/adapting that lifetime and fixing its reproduced occupied-port exit code zero. node refactor/scripts/servor-port-probe.mjs reproduces that upstream defect in an isolated child without touching 8082. It is not a candidate-success test. This migration does not claim those server limitations are resolved.

Evidence and regression ownership

• refactor/scripts/build.test.mjs: CLI validation, serialization/error recovery, real TS/JS/Less/SVG/inline-worker builds, CJS/global/AMD/ESM and analysis identity.
• test/library-build.test.js: public files never copied into library dist.
• test/performance-report.test.js: changed/new/removed TS build inputs cannot reuse stale installed performance artifacts.
• test/plugin-scaffold.test.js: newly generated plugins use these real tools.
• test/browser/library-development.spec.js: real dev server in Chromium, Firefox and WebKit, worker messaging, automatic reload, source edits and error recovery. Uses fixture ports and disposes its own child; it does not test media playback.
• node refactor/scripts/library-build-comparison.mjs: copy current package sources into a retained fixture, build all libraries with frozen pre-migration scripts and current scripts at the same paths, compare all artifact hashes. This is an explicit whole-build validation, not part of every quick unit test.

Remote Linux/macOS/Windows CI remains a separate release gate. The local browser evidence for MOD-02 is Windows; source inspection of Linux watcher registration does not substitute for a remote Linux run. Lerna and root installation hooks were not changed. The scaffold's separate guide remains in scripts/plugin/README.md.