feat: delete stale outputs after emit

AGENTS.md

@@ -87,7 +87,7 @@ CLI (src/run.ts → src/cli.ts)
   → buildWithConfigs()
   → buildSingle() for each config
     → Hook: build:prepare
-    → cleanOutDir()
+    → finishOutput() after emit, cleaning the union of every build that shares the outDir
     → getBuildOptions() → constructs Rolldown config
     → Hook: build:before
     → rolldownBuild() / rolldownWatch()

docs/options/cleaning.md

@@ -1,12 +1,16 @@
 # Cleaning
 
-By default, `tsdown` will **clean the output directory** (`outDir`) before each build. This ensures that any files from previous builds are removed, preventing outdated or unused files from remaining in your output.
+By default, `tsdown` removes **stale files** from the output directory (`outDir`). Files that the build emits again are overwritten in place. Files left over from a previous build, and nothing else that the new build produced, are deleted only after the new output is on disk.
 
-If you want to disable this behavior and keep existing files in the output directory, you can use the `--no-clean` option:
+Watch mode uses the same rule on every successful rebuild. A tool that reads `outDir` while `tsdown --watch` is running (Vite, Nest, `tsc --watch`) keeps seeing the previous files until each one is replaced. The directory is not emptied first.
+
+Builds that share an output directory, including the ESM and CJS formats of one package, are cleaned together. Each format keeps the files it just emitted. Only files that none of them emitted again are removed, and only after the last of those builds has finished.
+
+Disable cleaning entirely with `--no-clean`:
 
 ```bash
 tsdown --no-clean
 ```
 
 > [!NOTE]
-> By default, all files in the output directory will be removed before the build process begins. Make sure this behavior aligns with your project requirements to avoid accidentally deleting important files.
+> `clean: true` still deletes every file under the clean target that this build did not emit. Do not point it at a directory that contains files you need to keep.

docs/zh-CN/options/cleaning.md

@@ -1,12 +1,16 @@
 # 清理
 
-默认情况下，`tsdown` 会在每次构建之前**清理输出目录**（`outDir`）。这可以确保移除之前构建中生成的文件，防止过时或未使用的文件留在输出目录中。
+默认情况下，`tsdown` 会移除输出目录（`outDir`）中的**过期文件**。本次构建再次生成的文件会被原地覆盖；上次构建留下、而这次没有再生成的文件，只会在新产物写入磁盘之后被删除。
 
-如果您希望禁用此行为并保留输出目录中的现有文件，可以使用 `--no-clean` 选项：
+监听模式在每次成功的重新构建后使用同一规则。在 `tsdown --watch` 运行时读取 `outDir` 的工具（Vite、Nest、`tsc --watch`）会一直看到上一份文件，直到该文件被替换。目录不会先被清空。
+
+写入同一输出目录的构建（包括同一个包的 ESM 和 CJS）会一起清理。每个格式保留自己刚写出的文件。只有当它们都不再生成的文件，才会在最后一个构建结束后被删除。
+
+用 `--no-clean` 可以完全关闭清理：
 
 ```bash
 tsdown --no-clean
 ```
 
 > [!NOTE]
-> 默认情况下，输出目录中的所有文件将在构建过程开始之前被删除。请确保此行为符合您的项目需求，以避免意外删除重要文件。
+> `clean: true` 仍会删除清理目标中本次构建没有生成的全部文件。不要把它指向还需要保留其他文件的目录。

skills/tsdown/references/option-cleaning.md

@@ -1,10 +1,10 @@
 # Output Directory Cleaning
 
-Control how the output directory is cleaned before builds.
+Control how stale output files are removed.
 
 ## Overview
 
-By default, tsdown **cleans the output directory** before each build to remove stale files from previous builds.
+By default, tsdown **overwrites emitted files and then deletes only stale ones**. The output directory is not emptied before a single build or a watch rebuild. Several one-shot builds that run together still wipe their clean targets first so they can share one directory.
 
 ## Basic Usage
 
@@ -31,15 +31,16 @@ export default defineConfig({
 
 ### With Cleaning (Default)
 
-Before each build:
-1. All files in `outDir` are removed
-2. Fresh build starts with empty directory
-3. Only current build outputs remain
+For a single build and for watch rebuilds:
+1. Emitted files are overwritten in place
+2. After the write succeeds, files under the clean target that were not emitted are removed
+3. The output directory itself stays in place the whole time
+
+Several one-shot builds started together still wipe their clean targets before emitting.
 
 **Benefits:**
-- No stale files
-- Predictable output
-- Clean slate each build
+- No stale files once the build finishes
+- Watchers of `outDir` keep resolving the previous output during the rebuild
 
 ### Without Cleaning
 
@@ -158,32 +159,9 @@ export default defineConfig({
 
 ## Watch Mode Behavior
 
-In watch mode, cleaning behavior is important:
-
-### Clean on First Build Only
-
-```ts
-export default defineConfig((options) => ({
-  entry: ['src/index.ts'],
-  watch: options.watch,
-  clean: !options.watch,  // Only clean initial build
-}))
-```
-
-**Result:**
-- First build: Clean
-- Subsequent rebuilds: Incremental
-
-### Always Clean
-
-```ts
-export default defineConfig({
-  watch: true,
-  clean: true,  // Clean every rebuild
-})
-```
+With `clean: true` (the default), a watch rebuild overwrites the files it emits and, after that write succeeds, deletes outputs from the previous build that were not emitted again. Consumers watching `outDir` do not see the directory disappear between rebuilds.
 
-**Trade-off:** Slower rebuilds, but always fresh output.
+`clean: false` keeps every previous file, including hashed chunks that are no longer part of the build.
 
 ## Tips