build(packages): ship SPEC.md and sources in the published tarball

.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/<pkg>/`, 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.

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
 

packages/core/dialog/package.json

@@ -9,7 +9,9 @@
     "directory": "packages/core/dialog"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "SPEC.md"
   ],
   "type": "module",
   "sideEffects": false,

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,

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,

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,

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,

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,

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,

packages/react/dialog/package.json

@@ -9,7 +9,9 @@
     "directory": "packages/react/dialog"
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "SPEC.md"
   ],
   "type": "module",
   "sideEffects": false,

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,

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,

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,

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,