ciampo · Jul 13, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
@@ -110,6 +110,9 @@ jobs:
             - name: Type checking
               run: npm run build
 
+            - name: Validate package contents
+              run: npm run lint:package-contents
+
             - name: Audit published dependencies
               if: ${{ matrix.annotations }}
               run: npm run lint:published-deps -- --fail-unused-ignores

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -120,6 +120,7 @@
 		"lint:js:fix": "npm run lint:js -- --fix",
 		"lint:js:prune-suppressions": "npm run lint:js -- --prune-suppressions",
 		"lint:lockfile": "npm run --workspace @wordpress/validation-tools validate-package-lock --",
+		"lint:package-contents": "npm run --if-present --workspaces lint:package-contents",
 		"lint:tsconfig": "npm run --workspace @wordpress/validation-tools validate-tsconfig --",
 		"lint:md:docs": "wp-scripts lint-md-docs",
 		"prelint:php": "npm run other:update-packages:php",

@@ -38,6 +38,10 @@
 
 -   Add regression test coverage for the `ThemeProvider` wrapper's `display: contents` focus behavior ([#80056](https://github.com/WordPress/gutenberg/pull/80056)).
 
+### Code Quality
+
+-   Clean the npm package publish surface, correct ESM declaration export paths, and validate packed test/story artifacts and local export targets ([#79552](https://github.com/WordPress/gutenberg/pull/79552)).
+
 ## 0.17.0 (2026-06-30)
 
 ### Breaking Changes

@@ -23,10 +23,16 @@
 		"npm": ">=10.2.3"
 	},
 	"files": [
-		"src",
 		"build-module",
 		"build-types",
-		"*.md"
+		"src/*-plugins/**",
+		"src/prebuilt/css",
+		"src/prebuilt/js",
+		"*.md",
+		"!build-types/**/*.d.mts.map",
+		"!build-types/**/*.d.ts.map",
+		"!**/stories/**",
+		"!**/test/**"
 	],
 	"type": "module",
 	"module": "build-module/index.mjs",
@@ -67,7 +73,6 @@
 		"./package.json": "./package.json"
 	},
 	"wpScript": true,
-	"types": "build-types",
 	"sideEffects": [
 		"src/prebuilt/css/design-tokens.css"
 	],
@@ -91,6 +96,7 @@
 		"@testing-library/user-event": "^14.6.1",
 		"@types/jest": "^29.5.14",
 		"@types/node": "^20.19.39",
+		"@wordpress/validation-tools": "file:../../tools/validation",
 		"esbuild": "^0.27.2",
 		"esbuild-esm-loader": "^0.3.3",
 		"prettier": "npm:wp-prettier@^3.0.3",
@@ -130,6 +136,7 @@
 		"build:default-ramps": "node --import=esbuild-esm-loader/register bin/generate-default-ramps/index.ts",
 		"build:tokens": "node --import=esbuild-esm-loader/register bin/generate-primitive-tokens/index.ts && node --import=esbuild-esm-loader/register bin/build-design-tokens/index.ts",
 		"build": "npm run build:tokens && npm run build:default-ramps",
+		"lint:package-contents": "wp-validate-package-contents .",
 		"postbuild": "prettier --write tokens/color.json tokens/modes src/prebuilt src/color-ramps/lib/default-ramps.ts docs ../base-styles/internal/_wpds-token-fallbacks.scss"
 	}
 }
@@ -20,6 +20,9 @@
 		"url": "https://github.com/WordPress/gutenberg/issues"
 	},
 	"type": "module",
+	"bin": {
+		"wp-validate-package-contents": "./validate-package-contents.mjs"
+	},
 	"devDependencies": {
 		"@mawesome/dependency-audit": "^0.4.5",
 		"@wordpress/create-block": "file:../../packages/create-block",

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const [ packagePath, ...extraArgs ] = process.argv.slice( 2 );
+
+if ( ! packagePath || extraArgs.length ) {
+	console.error(
+		'Usage: node tools/validation/validate-package-contents.mjs <package-directory>'
+	);
+	process.exit( 1 );
+}
+
+const packageRoot = resolve( process.cwd(), packagePath );
+const packageJson = JSON.parse(
+	readFileSync( join( packageRoot, 'package.json' ), 'utf8' )
+);
+const npmExecPath = process.env.npm_execpath;
+const packResult = spawnSync(
+	npmExecPath ? process.execPath : 'npm',
+	[
+		...( npmExecPath ? [ npmExecPath ] : [] ),
+		'pack',
+		'--dry-run',
+		'--json',
+	],
+	{
+		cwd: packageRoot,
+		encoding: 'utf8',
+		env: {
+			...process.env,
+			npm_config_cache:
+				process.env.WORDPRESS_PACKAGE_NPM_CACHE ??
+				join( tmpdir(), 'wordpress-package-npm-cache' ),
+		},
+		shell: ! npmExecPath && process.platform === 'win32',
+	}
+);
+
+if ( packResult.error ) {
+	throw packResult.error;
+}
+
+if ( packResult.status !== 0 ) {
+	process.stderr.write( packResult.stdout ?? '' );
+	process.stderr.write( packResult.stderr ?? '' );
+	process.exit( packResult.status ?? 1 );
+}
+
+const [ pack ] = JSON.parse( packResult.stdout );
+const packedPaths = pack.files.map( ( { path } ) => path );
+const packedPathSet = new Set( packedPaths );
+const disallowedPathPatterns = [
+	/(^|\/)(__fixtures__|__snapshots__|__tests__|fixtures|stories|test|tests)(\/|$)/,
+	/(^|\/)[^/]+\.(spec|test)\.[^/]+$/,
+	/(^|\/)[^/]+\.stor(?:y|ies)\.[^/]+$/,
+];
+const disallowedPaths = packedPaths.filter( ( path ) =>
+	disallowedPathPatterns.some( ( pattern ) => pattern.test( path ) )
+);
+
+/**
+ * @param {unknown} value Export map value.
+ * @return {string[]} Concrete local export target paths.
+ */
+function getLocalExportTargets( value ) {
+	if ( typeof value === 'string' ) {
+		return value.startsWith( './' ) && ! value.includes( '*' )
+			? [ value.slice( 2 ) ]
+			: [];
+	}
+
+	if ( Array.isArray( value ) ) {
+		return value.flatMap( getLocalExportTargets );
+	}
+
+	if ( ! value || typeof value !== 'object' ) {
+		return [];
+	}
+
+	return Object.values( value ).flatMap( getLocalExportTargets );
+}
+
+const missingExportTargets = getLocalExportTargets(
+	packageJson.exports
+).filter( ( path ) => ! packedPathSet.has( path ) );
+
+if ( packedPaths.length === 0 ) {
+	console.error( 'The package tarball does not include any files.' );
+}
+
+if ( disallowedPaths.length ) {
+	console.error(
+		[
+			'The package tarball includes disallowed files:',
+			...disallowedPaths.map( ( path ) => `- ${ path }` ),
+		].join( '\n' )
+	);
+}
+
+if ( missingExportTargets.length ) {
+	console.error(
+		[
+			'The package tarball is missing exported targets:',
+			...missingExportTargets.map( ( path ) => `- ${ path }` ),
+		].join( '\n' )
+	);
+}
+
+if (
+	packedPaths.length === 0 ||
+	disallowedPaths.length ||
+	missingExportTargets.length
+) {
+	process.exit( 1 );
+}
+
+console.log(
+	`Validated ${ packedPaths.length } packed files for ${
+		packageJson.name ?? packageRoot
+	}.`
+);
@@ -0,0 +1,131 @@
+/* global afterEach, expect, test */
+
+/**
+ * External dependencies
+ */
+const { spawnSync } = require( 'node:child_process' );
+const { mkdtempSync, mkdirSync, rmSync, writeFileSync } = require( 'node:fs' );
+const { tmpdir } = require( 'node:os' );
+const { dirname, join } = require( 'node:path' );
+
+const validatorPath = join( __dirname, 'validate-package-contents.mjs' );
+const temporaryRoots = [];
+
+afterEach( () => {
+	for ( const root of temporaryRoots.splice( 0 ) ) {
+		rmSync( root, { force: true, recursive: true } );
+	}
+} );
+
+function createPackage( { files, packageJson } ) {
+	const root = mkdtempSync( join( tmpdir(), 'validate-package-contents-' ) );
+	temporaryRoots.push( root );
+
+	for ( const [ path, contents ] of Object.entries( files ) ) {
+		const filePath = join( root, path );
+		mkdirSync( dirname( filePath ), { recursive: true } );
+		writeFileSync( filePath, contents );
+	}
+
+	writeFileSync(
+		join( root, 'package.json' ),
+		JSON.stringify(
+			{
+				name: 'test-package',
+				version: '1.0.0',
+				...packageJson,
+			},
+			null,
+			'\t'
+		) + '\n'
+	);
+
+	return root;
+}
+
+function runValidator( packageRoot ) {
+	return spawnSync( process.execPath, [ validatorPath, packageRoot ], {
+		encoding: 'utf8',
+		env: {
+			...process.env,
+			WORDPRESS_PACKAGE_NPM_CACHE: join(
+				tmpdir(),
+				'wordpress-package-npm-cache'
+			),
+		},
+	} );
+}
+
+test( 'passes for a package with clean packed contents', () => {
+	const packageRoot = createPackage( {
+		files: {
+			'index.js': "export const value = 'ok';\n",
+			'index.d.ts': 'export declare const value: string;\n',
+			'styles.css': '.test {}\n',
+		},
+		packageJson: {
+			files: [ 'index.js', 'index.d.ts', 'styles.css' ],
+			exports: {
+				'.': {
+					types: './index.d.ts',
+					default: './index.js',
+				},
+				'./styles.css': './styles.css',
+			},
+		},
+	} );
+
+	const result = runValidator( packageRoot );
+
+	expect( result.status ).toBe( 0 );
+	expect( result.stdout ).toMatch(
+		/Validated \d+ packed files for test-package\./
+	);
+} );
+
+test.each( [ 'index.test.js', 'index.story.js' ] )(
+	'fails when packed contents include %s',
+	( disallowedPath ) => {
+		const packageRoot = createPackage( {
+			files: {
+				'index.js': "export const value = 'ok';\n",
+				[ disallowedPath ]: "import './index.js';\n",
+			},
+			packageJson: {
+				files: [ 'index.js', disallowedPath ],
+				exports: './index.js',
+			},
+		} );
+
+		const result = runValidator( packageRoot );
+
+		expect( result.status ).not.toBe( 0 );
+		expect( result.stderr ).toContain(
+			`The package tarball includes disallowed files:\n- ${ disallowedPath }`
+		);
+	}
+);
+
+test( 'fails when an exported target is missing from the package', () => {
+	const packageRoot = createPackage( {
+		files: {
+			'index.js': "export const value = 'ok';\n",
+		},
+		packageJson: {
+			files: [ 'index.js' ],
+			exports: {
+				'.': {
+					types: './index.d.ts',
+					default: './index.js',
+				},
+			},
+		},
+	} );
+
+	const result = runValidator( packageRoot );
+
+	expect( result.status ).not.toBe( 0 );
+	expect( result.stderr ).toMatch(
+		/The package tarball is missing exported targets:\n- index\.d\.ts/
+	);
+} );