Expand info on module condition and dual package hazard

[Andarist]

No description provided.

[Andarist]

I think that especially the change to mention neutral platform here is especially important because otherwise this could be misread by other implementers.

[Andarist]

We have also found out that to improve code portability between bundlers etc we are forced to structure things like this when the default export is involved:

// dist/pkg.mjs
export * from "./pkg.cjs.js";
export { _default as default } from "./pkg.cjs.default.js";

// dist/pkg.cjs.default.js
exports._default = require('./pkg.cjs.js').default

// dist/pkg.cjs.js
/*
  transpiled CJS content of the package with all named exports and named default
  don't try to avoid `.default` here
*/

The same problem spills into TS declarations:

// dist/pkg.d.mts
export * from "./index.js"; // yes, we are in the declaration file but we are using .js extension here
export { _default as default } from "./pkg.cjs.default.js";

// dist/pkg.cjs.default.d.ts
export { default as _default } from "./index.js"

// dist/index.d.ts
/*
  actual type declarations produced by TS
*/

I'm not sure if you want to include any of this in your docs though. It gets a little bit crazy and I wish that we wouldn't have to do those steps but here we are.