docs(repo): use explicit '.' export mapping in ESM-only playbook\n\n- Update exports snippet to nest under '.' for better tooling compatibility\n- Adjust verification jq command to match the new exports shape\n\nRefs #1934

Author: CharlieHelps

.charlie/playbooks/upgrade-plugin-to-esm-only.md

@@ -11,27 +11,26 @@ Upgrade a single plugin under `packages/<name>` to publish ESM-only output with
 ## Steps
 
 1. Identify the target package
-
    - Set a shell variable for reuse: `PKG=packages/<name>`.
 
 2. Package metadata: ESM-only and minimums
-
    - Edit `$PKG/package.json`:
-   - Set `"type": "module"`.
-   - Replace legacy `main/module/exports.require` with ESM-only exports:
-     ```json
-     "exports": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-     "types": "./dist/index.d.ts"
-     ```
-   - Set minimums: `"engines": { "node": ">=20.19.0" }` and `"peerDependencies": { "rollup": ">=4.0.0" }`.
-   - Keep `rollup` as a devDependency only if tests use it. Otherwise remove it.
-   - Ensure published files include dist but exclude maps:
-     ```json
-     "files": ["dist", "!dist/**/*.map", "README.md", "LICENSE"]
-     ```
+     - Set `"type": "module"`.
+     - Replace legacy `main/module/exports.require` with ESM-only exports:
+       ```json
+       "exports": {
+         ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+       },
+       "types": "./dist/index.d.ts"
+       ```
+     - Set minimums: `"engines": { "node": ">=20.19.0" }` and `"peerDependencies": { "rollup": ">=4.0.0" }`.
+     - Keep `rollup` as a devDependency only if tests use it. Otherwise remove it.
+     - Ensure published files include dist but exclude maps:
+       ```json
+       "files": ["dist", "!dist/**/*.map", "README.md", "LICENSE"]
+       ```
 
 3. Build scripts: TypeScript emit to dist
-
    - Prefer a tsc-only build for packages that do not need bundling:
      - In `$PKG/package.json`, set scripts:
        ```json
@@ -44,9 +43,7 @@ Upgrade a single plugin under `packages/<name>` to publish ESM-only output with
    - If this package still needs bundling for tests/examples, keep its Rollup config but point inputs at the TypeScript output in `dist/` instead of sources.
 
 4. TypeScript config: emit ESM to `dist/`
-
    - Create or update `$PKG/tsconfig.json` to extend the shared plugin config and emit declarations:
-
      ```json
      {
        "extends": "../../.config/tsconfig.base.json",
@@ -60,18 +57,15 @@ Upgrade a single plugin under `packages/<name>` to publish ESM-only output with
        "include": ["src/**/*"]
      }
      ```
-
    - Delete any package-local `rollup` build scripts that produced CJS, and remove any `types/` folder if declarations were hand-authored (they will now be generated).
 
 5. Source: convert to pure ESM and modern Node APIs
-
    - Replace `require`, `module.exports`, and `__dirname` patterns with ESM equivalents.
    - Use `node:` specifiers for built-ins (e.g., `import path from 'node:path'`).
    - Prefer URL utilities where needed (`fileURLToPath(new URL('.', import.meta.url))`).
    - Inline and export public types from `src/index.ts`; avoid separate `types/` unless unavoidable.
 
 6. Tests: drop CJS branches; ESM everywhere
-
    - Remove CJS-specific branches/assertions from tests.
    - Keep the existing runner (AVA) if it already handles ESM in Node 20. If the package already uses Vitest in this repo, keep that pattern.
    - Ensure Rollup bundles created in tests are `await bundle.close()`-d to avoid leaks.
@@ -90,7 +84,7 @@ Upgrade a single plugin under `packages/<name>` to publish ESM-only output with
   ```
 - Type declarations resolve for consumers:
   ```bash
-  jq -r '.types, .exports.types, .exports.import' $PKG/package.json
+  jq -r '.types, .exports["."]?.types, .exports["."]?.import' $PKG/package.json
   ```
 - Runtime smoke (Node ESM import works):
   ```bash