From 827c079716e6dcb5d78e9341285627137cf0ade3 Mon Sep 17 00:00:00 2001 From: Ivan Banov Date: Wed, 12 Aug 2026 14:32:13 +0200 Subject: [PATCH] build(packages): ship SPEC.md and sources in the published tarball MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tarball carried dist and README.md only, so the two things you want when a behavior surprises you — the spec that defines the contract and the code that implements it — were reachable only by finding the repo and guessing which tag matches the installed version. Add src and SPEC.md to files across every publishable package and both scaffold templates, so new primitives inherit it. Resolution is untouched: publishConfig still points main, types, and exports at dist, and the sources are inert payload. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/publish-spec-and-source.md | 25 +++++++++++++++++++ ARCHITECTURE.md | 4 +++ packages/core/dialog/package.json | 4 ++- packages/core/utils/controllable/package.json | 4 ++- packages/core/utils/overlay/package.json | 4 ++- packages/dom/utils/focus-trap/package.json | 4 ++- packages/dom/utils/navigation/package.json | 4 ++- packages/dom/utils/overlay/package.json | 4 ++- packages/dom/utils/scroll-lock/package.json | 4 ++- packages/react/dialog/package.json | 4 ++- .../react/hooks/use-focus-trap/package.json | 4 ++- .../react/hooks/use-scroll-lock/package.json | 4 ++- .../packages/core/__name__/package.json | 4 ++- .../packages/react/__name__/package.json | 4 ++- 14 files changed, 65 insertions(+), 12 deletions(-) create mode 100644 .changeset/publish-spec-and-source.md diff --git a/.changeset/publish-spec-and-source.md b/.changeset/publish-spec-and-source.md new file mode 100644 index 0000000..b7c7fa1 --- /dev/null +++ b/.changeset/publish-spec-and-source.md @@ -0,0 +1,25 @@ +--- +'@dunky.dev/controllable': patch +'@dunky.dev/dialog': patch +'@dunky.dev/dom-focus-trap': patch +'@dunky.dev/dom-navigation': patch +'@dunky.dev/dom-overlay': patch +'@dunky.dev/dom-scroll-lock': patch +'@dunky.dev/overlay': patch +'@dunky.dev/react-dialog': patch +'@dunky.dev/react-use-focus-trap': patch +'@dunky.dev/react-use-scroll-lock': patch +--- + +Ship `SPEC.md` and the TypeScript sources in the published package, alongside +the built `dist`. + +The tarball used to carry `dist` and `README.md` only, so the two things you +actually want when a behavior surprises you — the spec that defines the contract +and the code that implements it — were reachable only by finding the repo and +guessing which tag matches the installed version. Both now sit in +`node_modules//`, pinned to the exact version installed. + +Nothing about resolution changes: `publishConfig` still points `main`, `types`, +and `exports` at `dist`, and the sources are inert payload — read them, don't +import them. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 8c30a8f..eec9e68 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -248,6 +248,10 @@ directory into the templates — the script discovers it. See `packages/react/.storybook`, run with `pnpm dev [substrate]`. - Publishable packages are listed explicitly in `tsdown.config.ts`; a private package gets a tsconfig path but is never published. +- A published tarball carries `dist`, `src`, and the package's docs + (`README.md`, `SPEC.md`; pnpm copies in the root `LICENSE`). Consumers import + `dist` — `publishConfig` points every entry at it. The source and spec ship + so they can be read. ## Versioning diff --git a/packages/core/dialog/package.json b/packages/core/dialog/package.json index 357ead8..7d84745 100644 --- a/packages/core/dialog/package.json +++ b/packages/core/dialog/package.json @@ -9,7 +9,9 @@ "directory": "packages/core/dialog" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/core/utils/controllable/package.json b/packages/core/utils/controllable/package.json index 1bcced0..7ef54dc 100644 --- a/packages/core/utils/controllable/package.json +++ b/packages/core/utils/controllable/package.json @@ -9,7 +9,9 @@ "directory": "packages/core/utils/controllable" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/core/utils/overlay/package.json b/packages/core/utils/overlay/package.json index ebe012a..14435db 100644 --- a/packages/core/utils/overlay/package.json +++ b/packages/core/utils/overlay/package.json @@ -9,7 +9,9 @@ "directory": "packages/core/utils/overlay" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/dom/utils/focus-trap/package.json b/packages/dom/utils/focus-trap/package.json index e2b87d0..cb85526 100644 --- a/packages/dom/utils/focus-trap/package.json +++ b/packages/dom/utils/focus-trap/package.json @@ -9,7 +9,9 @@ "directory": "packages/dom/utils/focus-trap" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/dom/utils/navigation/package.json b/packages/dom/utils/navigation/package.json index 2c9769a..bd2bf3d 100644 --- a/packages/dom/utils/navigation/package.json +++ b/packages/dom/utils/navigation/package.json @@ -9,7 +9,9 @@ "directory": "packages/dom/utils/navigation" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/dom/utils/overlay/package.json b/packages/dom/utils/overlay/package.json index 151860c..15c4a2e 100644 --- a/packages/dom/utils/overlay/package.json +++ b/packages/dom/utils/overlay/package.json @@ -9,7 +9,9 @@ "directory": "packages/dom/utils/overlay" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/dom/utils/scroll-lock/package.json b/packages/dom/utils/scroll-lock/package.json index 9450692..b3b0169 100644 --- a/packages/dom/utils/scroll-lock/package.json +++ b/packages/dom/utils/scroll-lock/package.json @@ -9,7 +9,9 @@ "directory": "packages/dom/utils/scroll-lock" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/react/dialog/package.json b/packages/react/dialog/package.json index d9c035e..7cc4d70 100644 --- a/packages/react/dialog/package.json +++ b/packages/react/dialog/package.json @@ -9,7 +9,9 @@ "directory": "packages/react/dialog" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/react/hooks/use-focus-trap/package.json b/packages/react/hooks/use-focus-trap/package.json index 3c37363..38635be 100644 --- a/packages/react/hooks/use-focus-trap/package.json +++ b/packages/react/hooks/use-focus-trap/package.json @@ -9,7 +9,9 @@ "directory": "packages/react/hooks/use-focus-trap" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/packages/react/hooks/use-scroll-lock/package.json b/packages/react/hooks/use-scroll-lock/package.json index 9592854..23b9db4 100644 --- a/packages/react/hooks/use-scroll-lock/package.json +++ b/packages/react/hooks/use-scroll-lock/package.json @@ -9,7 +9,9 @@ "directory": "packages/react/hooks/use-scroll-lock" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/scripts/templates/packages/core/__name__/package.json b/scripts/templates/packages/core/__name__/package.json index 93777dd..462e70a 100644 --- a/scripts/templates/packages/core/__name__/package.json +++ b/scripts/templates/packages/core/__name__/package.json @@ -9,7 +9,9 @@ "directory": "packages/core/__name__" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false, diff --git a/scripts/templates/packages/react/__name__/package.json b/scripts/templates/packages/react/__name__/package.json index 3e72385..0573ec7 100644 --- a/scripts/templates/packages/react/__name__/package.json +++ b/scripts/templates/packages/react/__name__/package.json @@ -9,7 +9,9 @@ "directory": "packages/react/__name__" }, "files": [ - "dist" + "dist", + "src", + "SPEC.md" ], "type": "module", "sideEffects": false,