@savvy-web/tsdown-plugins 0.11.2 → 1.0.0

package/README.md

@@ -41,6 +41,7 @@ export default defineConfig({
 
 - **Entry detection** — `packageJsonEntries` and `extractEntries` derive build entries from a package's `exports` and `bin`, matching the rules used across the Silk Suite builders.
 - **Manifest transforms** — `transformManifest`, `transformExports`, `transformBin` and `normalizeBinPaths` rewrite a source `package.json` into a publishable one; `emitManifest` is the rolldown plugin that writes it. A dual-format build emits both `import` and `require` export conditions, and a `"./package.json": "./package.json"` entry is added to the exports map so consumers can `import "<pkg>/package.json"`.
+- **Ambient `.d.ts` exports** — `extractAmbientDts` and `classifyDtsExport` pick the types-only, hand-authored declaration exports out of a package's `exports` map; `transformExports` rewrites each to a key-derived `{ types }` pointer and `copyAmbientDts` copies the source declaration verbatim into every target dir, preserving its extension. `findRelativeSpecifiers` rejects a non-self-contained declaration and `mixedDtsExportError` rejects an export that mixes a hand-authored `types` with a runtime source.
 - **Catalog resolution** — `resolveManifest` resolves `catalog:` and `workspace:` specifiers against the workspace, delegating to `workspaces-effect`'s `CatalogResolver`.
 - **Multi-target resolution** — `resolveTargets` turns a `publishConfig.targets` map into the distinct byte-variant groups to build and the registry bindings for each; `writeTargetsBinding` persists that resolution as `dist/prod/targets.json` for the release step.
 - **JSX resolution** — `resolveJsxConfig` and `readTsconfigJsx` derive the effective JSX transform from a package's tsconfig, with an explicit override winning.

package/build/build-target-groups.js

@@ -1,15 +1,24 @@
+import { analyzeReexportBarrel, collectExportNames, renderReexportStub } from "../dts/reexport-stub.js";
+import { writeDtsEmitTsconfig } from "../dts/resolved-tsconfig.js";
 import { emitManifest } from "../manifest/emit-manifest.js";
 import { buildMetricsPlugin } from "../report/metrics-plugin.js";
 import { createTimer } from "../report/timer.js";
 import { createTsdownLogger } from "../report/tsdown-logger.js";
 import { cjsDefaultInterop } from "./cjs-default-interop.js";
 import { nodeBuiltinDefaultInterop } from "./node-builtin-default-interop.js";
-import { syncPublicDir } from "./sync-public.js";
+import { copyPublicDir } from "./sync-public.js";
 import { deriveDeclarationsPassOptions, deriveDtsPassOptions, deriveTargetGroupOptions, outDirFor } from "./target-groups.js";
-import { dirname, join } from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
 
 //#region src/build/build-target-groups.ts
 /**
+* Entry name of the conventional primary (".") export, which `createEntryName` maps to "index". It is
+* the re-export-stub base: a secondary entry that re-exports a subset of it gets a thin stub pointing
+* here instead of a self-contained rollup.
+*/
+const STUB_BASE_ENTRY = "index";
+/**
 * Run tsdown.build() per TargetGroup. Composable so the escape hatch gets multi-group too.
 *
 * Each group runs TWO passes to the SAME outDir:
@@ -28,6 +37,7 @@ import { dirname, join } from "node:path";
 async function buildTargetGroups(options) {
 	const build = options.build ?? (await import("tsdown")).build;
 	const publicDir = join(options.cwd, "public");
+	const dtsEmitTsconfigPath = writeDtsEmitTsconfig(options.tsconfigPath);
 	const collector = options.collector;
 	const verbose = options.verbose ?? false;
 	const instrument = (groupId) => collector === void 0 ? {} : {
@@ -68,7 +78,7 @@ async function buildTargetGroups(options) {
 				cwd: options.cwd,
 				version: options.version,
 				entry: part.entry,
-				tsconfigPath: options.tsconfigPath,
+				tsconfigPath: dtsEmitTsconfigPath,
 				devManifest: options.devManifest,
 				...partExternals !== void 0 ? { externals: partExternals } : {},
 				...partBundledPackages !== void 0 ? { bundledPackages: partBundledPackages } : {},
@@ -130,39 +140,93 @@ async function buildTargetGroups(options) {
 					...metricsPlugins(group.id, "js")
 				]
 			}));
-			if (isBase) syncPublicDir(publicDir, join(js.outDir, "public"));
 			const dtsNeverBundle = [...partExternals ?? [], ...partDtsExternals ?? []];
 			if (Object.keys(dts.entry).length === 0) continue;
-			await timed(group.id, "dts", () => build({
-				config: false,
-				cwd: options.cwd,
-				entry: dts.entry,
-				outDir: partOutDir,
-				format: dts.format,
-				platform: dts.platform,
-				sourcemap: dts.sourcemap,
-				unbundle: dts.unbundle,
-				clean: false,
-				fixedExtension: dts.fixedExtension,
-				dts: dts.dts,
-				define: dts.define,
-				...instrument(group.id),
-				...dtsNeverBundle.length > 0 || partBundleNodeModules || dts.bundledPackages ? { deps: {
-					...dtsNeverBundle.length > 0 ? { neverBundle: dtsNeverBundle } : {},
-					...partBundleNodeModules ? {
-						skipNodeModulesBundle: false,
-						...dts.bundledPackages ? { dts: { alwaysBundle: dts.bundledPackages } } : {}
-					} : dts.bundledPackages ? {
-						skipNodeModulesBundle: true,
-						dts: { alwaysBundle: dts.bundledPackages }
-					} : {}
-				} } : {},
-				plugins: [
-					...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
-					...options.extraPlugins ?? [],
-					...metricsPlugins(group.id, "dts")
-				]
-			}));
+			const dtsDeps = dtsNeverBundle.length > 0 || partBundleNodeModules || dts.bundledPackages ? { deps: {
+				...dtsNeverBundle.length > 0 ? { neverBundle: dtsNeverBundle } : {},
+				...partBundleNodeModules ? {
+					skipNodeModulesBundle: false,
+					...dts.bundledPackages ? { dts: { alwaysBundle: dts.bundledPackages } } : {}
+				} : dts.bundledPackages ? {
+					skipNodeModulesBundle: true,
+					dts: { alwaysBundle: dts.bundledPackages }
+				} : {}
+			} } : {};
+			const stubEntries = /* @__PURE__ */ new Map();
+			const readSource = (src) => {
+				try {
+					return readFileSync(isAbsolute(src) ? src : join(options.cwd, src), "utf-8");
+				} catch {
+					return;
+				}
+			};
+			const baseSrc = dts.entry[STUB_BASE_ENTRY];
+			if (baseSrc !== void 0 && Object.keys(dts.entry).length > 1) {
+				const baseSource = readSource(baseSrc);
+				const base = baseSource !== void 0 ? collectExportNames(baseSource) : void 0;
+				if (base?.complete === true) for (const [entryName, entrySource] of Object.entries(dts.entry)) {
+					if (entryName === STUB_BASE_ENTRY || entryName.includes("/")) continue;
+					const source = readSource(entrySource);
+					if (source === void 0) continue;
+					const analysis = analyzeReexportBarrel(source);
+					if (!analysis.isPureNamedReexportBarrel) continue;
+					const all = [...analysis.valueNames, ...analysis.typeNames];
+					if (all.length === 0 || !all.every((n) => base.names.has(n))) continue;
+					stubEntries.set(entryName, {
+						valueNames: analysis.valueNames,
+						typeNames: analysis.typeNames
+					});
+				}
+			}
+			await timed(group.id, "dts", async () => {
+				for (const [entryName, entrySource] of Object.entries(dts.entry)) {
+					const stub = stubEntries.get(entryName);
+					if (stub !== void 0) {
+						const variants = [{
+							file: `${entryName}.d.ts`,
+							spec: `./${STUB_BASE_ENTRY}.js`
+						}];
+						if (dts.format.includes("cjs")) variants.push({
+							file: `${entryName}.d.cts`,
+							spec: `./${STUB_BASE_ENTRY}.cjs`
+						});
+						for (const variant of variants) {
+							const content = renderReexportStub({
+								valueNames: stub.valueNames,
+								typeNames: stub.typeNames,
+								baseSpecifier: variant.spec
+							});
+							writeFileSync(join(partOutDir, variant.file), content, "utf-8");
+							collector?.recordEmitted(group.id, "dts", {
+								path: variant.file,
+								bytes: Buffer.byteLength(content)
+							});
+						}
+						continue;
+					}
+					await build({
+						config: false,
+						cwd: options.cwd,
+						entry: { [entryName]: entrySource },
+						outDir: partOutDir,
+						format: dts.format,
+						platform: dts.platform,
+						sourcemap: dts.sourcemap,
+						unbundle: dts.unbundle,
+						clean: false,
+						fixedExtension: dts.fixedExtension,
+						dts: dts.dts,
+						define: dts.define,
+						...instrument(group.id),
+						...dtsDeps,
+						plugins: [
+							...dts.format.includes("cjs") ? [nodeBuiltinDefaultInterop(), cjsDefaultInterop()] : [],
+							...options.extraPlugins ?? [],
+							...metricsPlugins(group.id, "dts")
+						]
+					});
+				}
+			});
 			if (js.isProd && options.emitDeclarations === true && Object.keys(decl.entry).length > 0) {
 				const partDeclDir = part.outSubdir !== void 0 ? join(decl.outDir, part.outSubdir) : decl.outDir;
 				try {
@@ -237,6 +301,7 @@ async function buildTargetGroups(options) {
 				]
 			}));
 		}
+		copyPublicDir(publicDir, outDirFor(options.cwd, group.id));
 	}
 }
 

package/build/strip-maps.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
 import { readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 
 //#region src/build/strip-maps.ts
 /**

package/build/sync-public.js

@@ -1,5 +1,7 @@
+import { ConfigValidationError } from "../errors.js";
+import { findRelativeSpecifiers } from "../dts/relative-imports.js";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
 
 //#region src/build/sync-public.ts
 /** Recursively collect every file path under `dir`, relative to `base`. */
@@ -17,52 +19,76 @@ function sameBytes(a, b) {
 	if (statSync(a).size !== statSync(b).size) return false;
 	return readFileSync(a).equals(readFileSync(b));
 }
-/** Remove empty directories under `dir` (deepest-first); `dir` itself is left in place. */
-function pruneEmptyDirs(dir) {
-	for (const entry of readdirSync(dir, { withFileTypes: true })) {
-		if (!entry.isDirectory()) continue;
-		const sub = join(dir, entry.name);
-		pruneEmptyDirs(sub);
-		if (readdirSync(sub).length === 0) rmSync(sub, {
-			recursive: true,
-			force: true
-		});
-	}
+/** Throw the standard public-asset collision error for a destination-relative path. */
+function throwPublicCollision(rel) {
+	throw new ConfigValidationError({
+		path: `public/${rel}`,
+		reason: `public asset "${rel}" collides with a built output at the package root — rename or remove it`
+	});
 }
 /**
-* Mirror `sourceDir` into `targetDir`, idempotently.
+* Copy the CONTENTS of `sourceDir` into `outDir`, additively.
 *
-* Replaces tsdown's built-in `copy`, whose non-recursive mkdir throws `EEXIST` when the target
-* already exists (re-builds, `prepare`-on-install, concurrent turbo invocations). Behavior:
+* Each `sourceDir/<rel>` copies to `outDir/<rel>` — only the `public/` directory itself is dropped;
+* the substructure under it is preserved (`public/tsconfig/ecma.json` becomes `<pkg>/tsconfig/ecma.json`,
+* NOT `<pkg>/ecma.json`). The published manifest mirrors this drop via `transformExports`, which strips
+* a leading `public/` from export values. This function NEVER deletes: `outDir` is the shared package
+* root that the JS/dts passes own, so deleting "files not in source" would wipe the build product.
+* Stale-asset pruning on a non-clean rebuild is therefore out of scope (a full build's `clean: true` handles it).
 *
-* - source absent: no-op.
-* - target absent: copy `sourceDir` wholesale.
-* - target present: copy only files that are new or whose bytes differ, then delete target files
-*   that no longer exist in the source and prune the directories left empty.
-*
-* The byte-diff keeps unchanged files (and their timestamps) untouched, so a large copied asset
-* tree — e.g. the mcp markdown corpus — is not rewritten on every build.
+* Collision guard: when a destination already exists, identical bytes mean a prior copy of the same
+* asset (skipped); anything else — differing bytes, a directory where a file is needed, or a file
+* where a parent directory is needed — means a built output occupies that path, so it throws
+* {@link ConfigValidationError} rather than clobbering it or surfacing a raw fs error.
 * @public
 */
-function syncPublicDir(sourceDir, targetDir) {
+function copyPublicDir(sourceDir, outDir) {
 	if (!existsSync(sourceDir)) return;
-	if (!existsSync(targetDir)) {
-		cpSync(sourceDir, targetDir, { recursive: true });
-		return;
-	}
-	const sourceFiles = listFilesRel(sourceDir);
-	const sourceSet = new Set(sourceFiles);
-	for (const rel of sourceFiles) {
+	for (const rel of listFilesRel(sourceDir)) {
 		const src = join(sourceDir, rel);
-		const dst = join(targetDir, rel);
+		const dst = join(outDir, rel);
+		if (existsSync(dst)) {
+			if (statSync(dst).isFile() && sameBytes(src, dst)) continue;
+			throwPublicCollision(rel);
+		}
+		try {
+			mkdirSync(dirname(dst), { recursive: true });
+			copyFileSync(src, dst);
+		} catch (err) {
+			const code = err.code;
+			if (code === "ENOTDIR" || code === "EEXIST" || code === "EISDIR") throwPublicCollision(rel);
+			throw err;
+		}
+	}
+}
+/**
+* Copy each ambient `.d.ts` export's source verbatim into `outDir/<outName>`, byte-stable (an
+* unchanged file keeps its timestamp). The copy is NOT compiled or bundled, so the build owns two
+* fast-fail checks: the source must exist, and it must be self-contained — a relative
+* import/export/reference would not resolve once the file is flattened to the package root.
+*
+* Throws {@link ConfigValidationError} on a missing source or any relative specifier.
+* @public
+*/
+function copyAmbientDts(options) {
+	for (const a of options.ambient) {
+		const src = join(options.srcCwd, a.source);
+		if (!existsSync(src)) throw new ConfigValidationError({
+			path: `exports."${a.exportKey}"`,
+			reason: `ambient .d.ts source not found: ${a.source}`
+		});
+		const relativeSpecifiers = findRelativeSpecifiers(readFileSync(src, "utf-8"), a.source);
+		if (relativeSpecifiers.length > 0) throw new ConfigValidationError({
+			path: `exports."${a.exportKey}"`,
+			reason: `ambient .d.ts "${a.source}" has relative import(s) [${relativeSpecifiers.join(", ")}] that cannot resolve after a verbatim copy — use bare package specifiers or self-contained declare module/global blocks`
+		});
+		const dst = join(options.outDir, a.outName);
 		if (!existsSync(dst) || !sameBytes(src, dst)) {
 			mkdirSync(dirname(dst), { recursive: true });
 			copyFileSync(src, dst);
 		}
 	}
-	for (const rel of listFilesRel(targetDir)) if (!sourceSet.has(rel)) rmSync(join(targetDir, rel), { force: true });
-	pruneEmptyDirs(targetDir);
 }
 
 //#endregion
-export { syncPublicDir };
+export { copyAmbientDts, copyPublicDir };

package/config-validation/ConfigValidatorLive.js

@@ -3,8 +3,8 @@ import { normalizeLooseFiles } from "../build/loose-files.js";
 import { ConfigValidator } from "./ConfigValidator.js";
 import { normalizeExeOptions } from "../exe/config.js";
 import { resolveTargets } from "../targets/resolve-targets.js";
-import { Effect, Layer } from "effect";
 import { existsSync, statSync } from "node:fs";
+import { Effect, Layer } from "effect";
 
 //#region src/config-validation/ConfigValidatorLive.ts
 const VALID_SYNTAX_KINDS = /* @__PURE__ */ new Set([

package/dts/reexport-stub.js

@@ -0,0 +1,92 @@
+import ts from "typescript";
+
+//#region src/dts/reexport-stub.ts
+function parse(source, fileName) {
+	return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+}
+/**
+* Analyze an entry source as a candidate pure re-export barrel: classify its re-exported names into
+* value vs type-only and report whether it is expressible as a thin stub. Pure parsing — no I/O.
+*
+* @public
+*/
+function analyzeReexportBarrel(source, fileName = "entry.ts") {
+	const sf = parse(source, fileName);
+	const valueNames = [];
+	const typeNames = [];
+	let pure = true;
+	for (const stmt of sf.statements) {
+		if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier !== void 0) {
+			const clause = stmt.exportClause;
+			if (clause !== void 0 && ts.isNamedExports(clause)) {
+				for (const el of clause.elements) (stmt.isTypeOnly || el.isTypeOnly ? typeNames : valueNames).push(el.name.text);
+				continue;
+			}
+			pure = false;
+			continue;
+		}
+		pure = false;
+	}
+	return {
+		valueNames,
+		typeNames,
+		isPureNamedReexportBarrel: pure
+	};
+}
+/**
+* Collect every name a module exports (named re-exports, namespace re-exports, and local `export`
+* declarations). Used to test whether a barrel's re-exports are a strict subset of a base entry, so
+* a stub re-exporting from that base resolves every symbol. Pure parsing — no I/O.
+*
+* @public
+*/
+function collectExportNames(source, fileName = "entry.ts") {
+	const sf = parse(source, fileName);
+	const names = /* @__PURE__ */ new Set();
+	let complete = true;
+	const addBindingName = (name) => {
+		if (ts.isIdentifier(name)) names.add(name.text);
+		else for (const el of name.elements) if (ts.isBindingElement(el)) addBindingName(el.name);
+	};
+	for (const stmt of sf.statements) {
+		if (ts.isExportDeclaration(stmt)) {
+			const clause = stmt.exportClause;
+			if (clause === void 0) {
+				if (stmt.moduleSpecifier !== void 0) complete = false;
+				continue;
+			}
+			if (ts.isNamespaceExport(clause)) {
+				names.add(clause.name.text);
+				continue;
+			}
+			for (const el of clause.elements) names.add(el.name.text);
+			continue;
+		}
+		if (!(ts.canHaveModifiers(stmt) ? (ts.getModifiers(stmt) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword) : false)) continue;
+		if (ts.isVariableStatement(stmt)) for (const decl of stmt.declarationList.declarations) addBindingName(decl.name);
+		else if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt) || ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt) || ts.isModuleDeclaration(stmt)) && stmt.name !== void 0 && ts.isIdentifier(stmt.name)) names.add(stmt.name.text);
+	}
+	return {
+		names,
+		complete
+	};
+}
+/**
+* Render a thin re-export-stub `.d.ts`/`.d.cts` body: named re-exports of `valueNames` and
+* `typeNames` from `baseSpecifier` (the published file of the base entry, e.g. `./index.js` for the
+* ESM `.d.ts` or `./index.cjs` for the CJS `.d.cts`). Names are sorted so the output is
+* deterministic. Returns the empty string when there is nothing to re-export.
+*
+* @public
+*/
+function renderReexportStub(options) {
+	const sortedValues = [...options.valueNames].sort();
+	const sortedTypes = [...options.typeNames].sort();
+	const lines = [];
+	if (sortedValues.length > 0) lines.push(`export { ${sortedValues.join(", ")} } from "${options.baseSpecifier}";`);
+	if (sortedTypes.length > 0) lines.push(`export type { ${sortedTypes.join(", ")} } from "${options.baseSpecifier}";`);
+	return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+
+//#endregion
+export { analyzeReexportBarrel, collectExportNames, renderReexportStub };

package/dts/relative-imports.js

@@ -0,0 +1,32 @@
+import ts from "typescript";
+
+//#region src/dts/relative-imports.ts
+const isRelative = (s) => s.startsWith("./") || s.startsWith("../");
+/**
+* Find every relative module specifier in a declaration source: static `import`/`export … from`,
+* `import("…")` type nodes, and `/// <reference path="…" />`. Pure parsing — no I/O.
+*
+* A non-empty result means the file is NOT self-contained and would break when copied verbatim to a
+* flattened output location, so the ambient-copy step rejects it.
+* @public
+*/
+function findRelativeSpecifiers(source, fileName = "ambient.d.ts") {
+	const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+	const found = /* @__PURE__ */ new Set();
+	for (const ref of sf.referencedFiles) if (isRelative(ref.fileName)) found.add(ref.fileName);
+	const visit = (node) => {
+		if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier !== void 0 && ts.isStringLiteral(node.moduleSpecifier)) {
+			if (isRelative(node.moduleSpecifier.text)) found.add(node.moduleSpecifier.text);
+		} else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && ts.isStringLiteral(node.argument.literal)) {
+			if (isRelative(node.argument.literal.text)) found.add(node.argument.literal.text);
+		} else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference) && ts.isStringLiteral(node.moduleReference.expression)) {
+			if (isRelative(node.moduleReference.expression.text)) found.add(node.moduleReference.expression.text);
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(sf);
+	return [...found];
+}
+
+//#endregion
+export { findRelativeSpecifiers };

package/dts/resolved-tsconfig.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
-import { writeFileSync } from "node:fs";
+import { existsSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 
 //#region src/dts/resolved-tsconfig.ts
@@ -47,6 +47,33 @@ function writeResolvedTsconfig(options) {
 	writeFileSync(path, `${JSON.stringify(cfg, null, "	")}\n`, "utf-8");
 	return path;
 }
+/**
+* Derive a dts-EMIT variant of an already-written resolved tsconfig that adds
+* `stableTypeOrdering: true`, and return its path. This makes the TypeScript declaration emitter
+* (rolldown-plugin-dts on `typescript@6`) order union/type members deterministically, so a
+* multi-union `.d.ts` (e.g. an Effect `Layer.Layer<…>` requirement channel) does not flip member
+* order across otherwise-identical builds (#156). It is kept in a SEPARATE file from the
+* api-extractor tsconfig on purpose: `@microsoft/api-extractor` pins `typescript ~5.9`, which
+* predates the flag and hard-errors on the unknown compiler option — so only the emit passes
+* (which run on TS6) ever see it, while the api-extractor compile reads the original clean config.
+*
+* Best-effort: if the base tsconfig cannot be read or parsed (e.g. a synthetic test path that was
+* never written), the original path is returned unchanged — the emit then simply keeps TS's
+* default ordering rather than aborting the build at this layer.
+*
+* @public
+*/
+function writeDtsEmitTsconfig(resolvedTsconfigPath) {
+	const absBase = isAbsolute(resolvedTsconfigPath) ? resolvedTsconfigPath : resolve(resolvedTsconfigPath);
+	if (!existsSync(absBase)) return resolvedTsconfigPath;
+	const cfg = {
+		extends: absBase,
+		compilerOptions: { stableTypeOrdering: true }
+	};
+	const path = join(tmpdir(), `tsconfig-dts-emit-${process.pid}-${absBase.replace(/[^\w]/g, "_")}.json`);
+	writeFileSync(path, `${JSON.stringify(cfg, null, "	")}\n`, "utf-8");
+	return path;
+}
 
 //#endregion
-export { buildResolvedTsconfig, writeResolvedTsconfig };
+export { buildResolvedTsconfig, writeDtsEmitTsconfig, writeResolvedTsconfig };

package/entry/ambient-dts.js

@@ -0,0 +1,102 @@
+import { ConfigValidationError } from "../errors.js";
+import { createEntryName } from "./extract.js";
+
+//#region src/entry/ambient-dts.ts
+const DECLARATION_EXTS = [
+	".d.ts",
+	".d.cts",
+	".d.mts"
+];
+/** The declaration-file extension of a path, or undefined when it is not a declaration file. @public */
+function declarationExt(p) {
+	return DECLARATION_EXTS.find((e) => p.endsWith(e));
+}
+/**
+* Classify an export value:
+* - `ambient` — a types-only declaration source (bare `.d.ts` string, or `{ types: "*.d.ts" }` with no runtime source).
+* - `mixed` — a declaration `types` AND a compilable runtime source (`import`/`require`/`default` → `.ts`/`.tsx`).
+* - `none` — anything else (normal runtime export, json, etc.).
+* @public
+*/
+function classifyDtsExport(value) {
+	if (typeof value === "string") return declarationExt(value) !== void 0 ? {
+		kind: "ambient",
+		source: value
+	} : { kind: "none" };
+	if (value && typeof value === "object") {
+		const o = value;
+		const typesVal = typeof o.types === "string" ? o.types : void 0;
+		const typesIsDecl = typesVal !== void 0 && declarationExt(typesVal) !== void 0;
+		const hasRuntime = Object.entries(o).some(([k, v]) => k !== "types" && typeof v === "string" && declarationExt(v) === void 0);
+		if (typesIsDecl) return hasRuntime ? { kind: "mixed" } : {
+			kind: "ambient",
+			source: typesVal
+		};
+	}
+	return { kind: "none" };
+}
+/**
+* Output basename (including the preserved declaration extension) for an ambient export, derived
+* from the export KEY — consistent with how JS entries are named. @public
+*/
+function ambientOutName(exportKey, source, exportsAsIndexes = false) {
+	const ext = declarationExt(source) ?? ".d.ts";
+	return `${createEntryName(exportKey, exportsAsIndexes)}${ext}`;
+}
+/** The shared mixed-export error (Decision 2), used by both the extractor and the manifest transform. @public */
+function mixedDtsExportError(exportKey) {
+	return new ConfigValidationError({
+		path: `exports."${exportKey}"`,
+		reason: "an export with a runtime source (import/require/default) cannot also hand-author its `types` as a .d.ts; the bundler generates types from the source"
+	});
+}
+/**
+* Extract the types-only `.d.ts` exports from a package's `exports` map. Pure.
+* Throws {@link ConfigValidationError} on a mixed export (Decision 2) or an ambient-vs-ambient
+* output-name collision. @public
+*/
+function extractAmbientDts(pkg, options = {}) {
+	const exports = pkg.exports;
+	if (!exports || typeof exports !== "object") return [];
+	const exportsAsIndexes = options.exportsAsIndexes ?? false;
+	const out = [];
+	const byName = /* @__PURE__ */ new Map();
+	for (const [key, value] of Object.entries(exports)) {
+		if (key === "./package.json" || key.endsWith(".json")) continue;
+		if (declarationExt(key) !== void 0) continue;
+		const cls = classifyDtsExport(value);
+		if (cls.kind === "none") continue;
+		if (cls.kind === "mixed") throw mixedDtsExportError(key);
+		const outName = ambientOutName(key, cls.source, exportsAsIndexes);
+		const prev = byName.get(outName);
+		if (prev !== void 0) throw new ConfigValidationError({
+			path: `exports."${key}"`,
+			reason: `ambient .d.ts export flattens to "${outName}", colliding with export key "${prev}". Rename one so each produces a distinct file.`
+		});
+		byName.set(outName, key);
+		out.push({
+			exportKey: key,
+			source: cls.source,
+			outName
+		});
+	}
+	return out;
+}
+/**
+* Throw {@link ConfigValidationError} if any ambient output name collides with a JS build-entry name.
+* The JS entry names carry no extension, so each ambient `outName` is compared with its declaration
+* extension stripped. @public
+*/
+function assertNoEntryCollisions(jsEntryNames, ambient) {
+	const js = new Set(jsEntryNames);
+	for (const a of ambient) {
+		const base = a.outName.replace(/\.d\.(ts|cts|mts)$/, "");
+		if (js.has(base)) throw new ConfigValidationError({
+			path: `exports."${a.exportKey}"`,
+			reason: `ambient .d.ts export "${a.outName}" collides with the JS build entry "${base}". Rename the export so each produces a distinct output.`
+		});
+	}
+}
+
+//#endregion
+export { ambientOutName, assertNoEntryCollisions, classifyDtsExport, declarationExt, extractAmbientDts, mixedDtsExportError };

package/entry/package-json-entries.js

@@ -1,6 +1,6 @@
 import { extractEntries } from "./extract.js";
-import { resolve } from "node:path";
 import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 
 //#region src/entry/package-json-entries.ts
 /**

package/exe/build.js

@@ -1,8 +1,8 @@
 import { buildMetricsPlugin } from "../report/metrics-plugin.js";
 import { createTimer } from "../report/timer.js";
 import { createTsdownLogger } from "../report/tsdown-logger.js";
-import { join } from "node:path";
 import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 //#region src/exe/build.ts

package/index.d.ts

@@ -1,4 +1,11 @@
-import { CatalogAssemblyError, CatalogResolutionError, ManifestLike, ManifestLike as ManifestLike$1 } from "workspaces-effect";
+/**
+ * Find every relative module specifier in a declaration source: static `import`/`export … from`,
+ * `import("…")` type nodes, and `/// <reference path="…" />`. Pure parsing — no I/O.
+ *
+ * A non-empty result means the file is NOT self-contained and would break when copied verbatim to a
+ * flattened output location, so the ambient-copy step rejects it.
+ * @public
+ */import { CatalogAssemblyError, CatalogResolutionError, ManifestLike, ManifestLike as ManifestLike$1 } from "workspaces-effect";
 import { Plugin } from "rolldown";
 import { Context, Effect, Layer, Schema } from "effect";
 import { JsxEmit, ModuleDetectionKind, ModuleKind, ModuleResolutionKind, NewLineKind, ParsedCommandLine, ScriptTarget } from "typescript";
@@ -177,21 +184,21 @@ declare const DiagnosticEntry_base: Schema.Class<DiagnosticEntry, {
   line: Schema.optional<typeof Schema.Number>;
   column: Schema.optional<typeof Schema.Number>;
 }>, never, {
-  readonly text: string;
-} & {
-  readonly source: "tsdown" | "rolldown" | "api-extractor";
-} & {
-  readonly level: "warn" | "error";
+  readonly ciFatal?: boolean | undefined;
 } & {
   readonly code?: string | undefined;
 } & {
-  readonly ciFatal?: boolean | undefined;
+  readonly column?: number | undefined;
 } & {
   readonly file?: string | undefined;
 } & {
   readonly line?: number | undefined;
 } & {
-  readonly column?: number | undefined;
+  readonly level: "error" | "warn";
+} & {
+  readonly source: "api-extractor" | "rolldown" | "tsdown";
+} & {
+  readonly text: string;
 }, {}, {}>;
 /**
  * A captured warning or error, from tsdown's logger, rolldown's onLog, or API Extractor.
@@ -208,11 +215,11 @@ declare const EmittedFile_base: Schema.Class<EmittedFile, {
   bytes: typeof Schema.Number;
   gzip: Schema.optional<typeof Schema.Number>;
 }>, never, {
-  readonly path: string;
+  readonly gzip?: number | undefined;
 } & {
   readonly bytes: number;
 } & {
-  readonly gzip?: number | undefined;
+  readonly path: string;
 }, {}, {}>;
 /**
  * One emitted output file with its in-memory byte size (gzip only when --verbose).
@@ -229,11 +236,11 @@ declare const PassReport_base: Schema.Class<PassReport, {
   files: Schema.Array$<typeof EmittedFile>;
   ms: typeof Schema.Number;
 }>, never, {
-  readonly ms: number;
+  readonly files: readonly EmittedFile[];
 } & {
-  readonly id: "js" | "dts" | "loose" | "exe" | "meta";
+  readonly id: "dts" | "exe" | "js" | "loose" | "meta";
 } & {
-  readonly files: readonly EmittedFile[];
+  readonly ms: number;
 }, {}, {}>;
 /**
  * One build pass within a target group (js / dts / loose / exe / meta).
@@ -260,17 +267,17 @@ declare const TargetGroupReport_base: Schema.Class<TargetGroupReport, {
 }>, never, {
   readonly entries: readonly string[];
 } & {
-  readonly id: string;
+  readonly errors: readonly DiagnosticEntry[];
 } & {
-  readonly timings: ReportTimings;
+  readonly id: string;
 } & {
   readonly passes: readonly PassReport[];
 } & {
-  readonly warnings: readonly DiagnosticEntry[];
+  readonly suppressed: readonly DiagnosticEntry[];
 } & {
-  readonly errors: readonly DiagnosticEntry[];
+  readonly timings: ReportTimings;
 } & {
-  readonly suppressed: readonly DiagnosticEntry[];
+  readonly warnings: readonly DiagnosticEntry[];
 }, {}, {}>;
 /** @public */
 declare class TargetGroupReport extends TargetGroupReport_base {}
@@ -762,23 +769,156 @@ declare function nodeBuiltinDefaultInterop(): Plugin;
  */
 declare function removeDeclarationMaps(pkgDir: string): string[];
 //#endregion
+//#region src/errors.d.ts
+declare const MetaGenerationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "MetaGenerationError";
+} & Readonly<A>;
+/**
+ * API Extractor meta generation failed for an entry.
+ *
+ * @public
+ */
+declare class MetaGenerationError extends MetaGenerationError_base<{
+  readonly entry: string;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+declare const ConfigValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "ConfigValidationError";
+} & Readonly<A>;
+/**
+ * A savvy.build.ts or publishConfig.targets config is structurally invalid; raised before any build work.
+ *
+ * @public
+ */
+declare class ConfigValidationError extends ConfigValidationError_base<{
+  readonly path: string;
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+//#endregion
+//#region src/entry/extract.d.ts
+/** @public */
+interface PackageJsonLike {
+  readonly exports?: unknown;
+  readonly bin?: unknown;
+}
+/** @public */
+interface ExtractOptions {
+  readonly exportsAsIndexes?: boolean | undefined;
+  /** Source paths to NOT turn into JS build entries (e.g. an exe entry compiled as a SEA). */
+  readonly excludeSources?: ReadonlyArray<string> | undefined;
+}
+/** @public */
+interface ExtractResult {
+  /** entry name to TS source path */
+  readonly entries: Record<string, string>;
+  /** entry name to original export key (for downstream output-map alignment) */
+  readonly exportPaths: Record<string, string>;
+}
+/**
+ * Map an export key to the tsdown entry name (the emitted output basename).
+ *
+ * `.` becomes `index`; otherwise the leading `./` is stripped and, unless
+ * `exportsAsIndexes` is set, nested slashes are flattened to dashes
+ * (e.g. `./changesets/markdownlint` to `changesets-markdownlint`). The manifest
+ * transform reuses this so the declared output path always matches the emitted file.
+ *
+ * @internal
+ */
+declare const createEntryName: (exportKey: string, exportsAsIndexes: boolean) => string;
+/** @public */
+declare function extractEntries(pkg: PackageJsonLike, options?: ExtractOptions): ExtractResult;
+//#endregion
+//#region src/entry/ambient-dts.d.ts
+/** The declaration-file extension of a path, or undefined when it is not a declaration file. @public */
+declare function declarationExt(p: string): ".d.ts" | ".d.cts" | ".d.mts" | undefined;
+/** Classification of a single export value for ambient-.d.ts handling. @public */
+type DtsExportClass = {
+  readonly kind: "ambient";
+  readonly source: string;
+} | {
+  readonly kind: "mixed";
+} | {
+  readonly kind: "none";
+};
+/**
+ * Classify an export value:
+ * - `ambient` — a types-only declaration source (bare `.d.ts` string, or `{ types: "*.d.ts" }` with no runtime source).
+ * - `mixed` — a declaration `types` AND a compilable runtime source (`import`/`require`/`default` → `.ts`/`.tsx`).
+ * - `none` — anything else (normal runtime export, json, etc.).
+ * @public
+ */
+declare function classifyDtsExport(value: unknown): DtsExportClass;
+/**
+ * Output basename (including the preserved declaration extension) for an ambient export, derived
+ * from the export KEY — consistent with how JS entries are named. @public
+ */
+declare function ambientOutName(exportKey: string, source: string, exportsAsIndexes?: boolean): string;
+/** The shared mixed-export error (Decision 2), used by both the extractor and the manifest transform. @public */
+declare function mixedDtsExportError(exportKey: string): ConfigValidationError;
+/** One ambient `.d.ts` export resolved for copy + manifest. @public */
+interface AmbientDtsEntry {
+  readonly exportKey: string;
+  readonly source: string;
+  readonly outName: string;
+}
+/** @public */
+interface ExtractAmbientOptions {
+  readonly exportsAsIndexes?: boolean | undefined;
+}
+/**
+ * Extract the types-only `.d.ts` exports from a package's `exports` map. Pure.
+ * Throws {@link ConfigValidationError} on a mixed export (Decision 2) or an ambient-vs-ambient
+ * output-name collision. @public
+ */
+declare function extractAmbientDts(pkg: PackageJsonLike, options?: ExtractAmbientOptions): ReadonlyArray<AmbientDtsEntry>;
+/**
+ * Throw {@link ConfigValidationError} if any ambient output name collides with a JS build-entry name.
+ * The JS entry names carry no extension, so each ambient `outName` is compared with its declaration
+ * extension stripped. @public
+ */
+declare function assertNoEntryCollisions(jsEntryNames: ReadonlyArray<string>, ambient: ReadonlyArray<AmbientDtsEntry>): void;
+//#endregion
 //#region src/build/sync-public.d.ts
 /**
- * Mirror `sourceDir` into `targetDir`, idempotently.
+ * Copy the CONTENTS of `sourceDir` into `outDir`, additively.
  *
- * Replaces tsdown's built-in `copy`, whose non-recursive mkdir throws `EEXIST` when the target
- * already exists (re-builds, `prepare`-on-install, concurrent turbo invocations). Behavior:
+ * Each `sourceDir/<rel>` copies to `outDir/<rel>` — only the `public/` directory itself is dropped;
+ * the substructure under it is preserved (`public/tsconfig/ecma.json` becomes `<pkg>/tsconfig/ecma.json`,
+ * NOT `<pkg>/ecma.json`). The published manifest mirrors this drop via `transformExports`, which strips
+ * a leading `public/` from export values. This function NEVER deletes: `outDir` is the shared package
+ * root that the JS/dts passes own, so deleting "files not in source" would wipe the build product.
+ * Stale-asset pruning on a non-clean rebuild is therefore out of scope (a full build's `clean: true` handles it).
  *
- * - source absent: no-op.
- * - target absent: copy `sourceDir` wholesale.
- * - target present: copy only files that are new or whose bytes differ, then delete target files
- *   that no longer exist in the source and prune the directories left empty.
+ * Collision guard: when a destination already exists, identical bytes mean a prior copy of the same
+ * asset (skipped); anything else — differing bytes, a directory where a file is needed, or a file
+ * where a parent directory is needed — means a built output occupies that path, so it throws
+ * {@link ConfigValidationError} rather than clobbering it or surfacing a raw fs error.
+ * @public
+ */
+declare function copyPublicDir(sourceDir: string, outDir: string): void;
+/** @public */
+interface CopyAmbientDtsOptions {
+  /** The ambient exports to copy (from `extractAmbientDts`). */
+  readonly ambient: ReadonlyArray<AmbientDtsEntry>;
+  /** Package root the `source` paths are relative to. */
+  readonly srcCwd: string;
+  /** The built package dir to copy into (e.g. `dist/dev/pkg`). */
+  readonly outDir: string;
+}
+/**
+ * Copy each ambient `.d.ts` export's source verbatim into `outDir/<outName>`, byte-stable (an
+ * unchanged file keeps its timestamp). The copy is NOT compiled or bundled, so the build owns two
+ * fast-fail checks: the source must exist, and it must be self-contained — a relative
+ * import/export/reference would not resolve once the file is flattened to the package root.
  *
- * The byte-diff keeps unchanged files (and their timestamps) untouched, so a large copied asset
- * tree — e.g. the mcp markdown corpus — is not rewritten on every build.
+ * Throws {@link ConfigValidationError} on a missing source or any relative specifier.
  * @public
  */
-declare function syncPublicDir(sourceDir: string, targetDir: string): void;
+declare function copyAmbientDts(options: CopyAmbientDtsOptions): void;
 //#endregion
 //#region src/catalog/resolve-catalogs.d.ts
 /**
@@ -817,36 +957,6 @@ interface NextVersions {
  */
 declare function resolveNextVersions(cwd: string): Promise<NextVersions>;
 //#endregion
-//#region src/errors.d.ts
-declare const MetaGenerationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
-  readonly _tag: "MetaGenerationError";
-} & Readonly<A>;
-/**
- * API Extractor meta generation failed for an entry.
- *
- * @public
- */
-declare class MetaGenerationError extends MetaGenerationError_base<{
-  readonly entry: string;
-  readonly reason: string;
-}> {
-  get message(): string;
-}
-declare const ConfigValidationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
-  readonly _tag: "ConfigValidationError";
-} & Readonly<A>;
-/**
- * A savvy.build.ts or publishConfig.targets config is structurally invalid; raised before any build work.
- *
- * @public
- */
-declare class ConfigValidationError extends ConfigValidationError_base<{
-  readonly path: string;
-  readonly reason: string;
-}> {
-  get message(): string;
-}
-//#endregion
 //#region src/exe/config.d.ts
 /**
  * Default Node runtime embedded in the SEA (parity with the vitest-agent reference).
@@ -1109,6 +1219,72 @@ declare class ConfigValidator extends ConfigValidator_base {}
  */
 declare const ConfigValidatorLive: Layer.Layer<ConfigValidator, never, never>;
 //#endregion
+//#region src/dts/reexport-stub.d.ts
+/**
+ * The analysis of an entry source treated as a candidate re-export barrel.
+ *
+ * @public
+ */
+interface ReexportBarrelAnalysis {
+  /** Value (non-type-only) names the module re-exports, after `as` aliasing. */
+  readonly valueNames: ReadonlyArray<string>;
+  /** Type-only names the module re-exports (`export type { … }`), after `as` aliasing. */
+  readonly typeNames: ReadonlyArray<string>;
+  /**
+   * True iff EVERY top-level statement is a NAMED re-export `from` another module
+   * (`export { … } from "…"` / `export type { … } from "…"`). A module that declares anything
+   * locally, re-exports a namespace (`export * as NS from`), star-re-exports (`export * from`), or
+   * has a bare `export { … }` without `from` is NOT a pure named barrel and cannot be expressed as
+   * a thin re-export stub of another entry.
+   */
+  readonly isPureNamedReexportBarrel: boolean;
+}
+/**
+ * The set of names a module exports, plus whether that set is fully known.
+ *
+ * @public
+ */
+interface ModuleExportNames {
+  readonly names: ReadonlySet<string>;
+  /**
+   * False when the module contains a star re-export (`export * from "…"`) whose target exports
+   * cannot be enumerated from this source alone — the name set is then a lower bound, not complete,
+   * so callers must not use it for a strict subset decision.
+   */
+  readonly complete: boolean;
+}
+/**
+ * Analyze an entry source as a candidate pure re-export barrel: classify its re-exported names into
+ * value vs type-only and report whether it is expressible as a thin stub. Pure parsing — no I/O.
+ *
+ * @public
+ */
+declare function analyzeReexportBarrel(source: string, fileName?: string): ReexportBarrelAnalysis;
+/**
+ * Collect every name a module exports (named re-exports, namespace re-exports, and local `export`
+ * declarations). Used to test whether a barrel's re-exports are a strict subset of a base entry, so
+ * a stub re-exporting from that base resolves every symbol. Pure parsing — no I/O.
+ *
+ * @public
+ */
+declare function collectExportNames(source: string, fileName?: string): ModuleExportNames;
+/**
+ * Render a thin re-export-stub `.d.ts`/`.d.cts` body: named re-exports of `valueNames` and
+ * `typeNames` from `baseSpecifier` (the published file of the base entry, e.g. `./index.js` for the
+ * ESM `.d.ts` or `./index.cjs` for the CJS `.d.cts`). Names are sorted so the output is
+ * deterministic. Returns the empty string when there is nothing to re-export.
+ *
+ * @public
+ */
+declare function renderReexportStub(options: {
+  readonly valueNames: ReadonlyArray<string>;
+  readonly typeNames: ReadonlyArray<string>;
+  readonly baseSpecifier: string;
+}): string;
+//#endregion
+//#region src/dts/relative-imports.d.ts
+declare function findRelativeSpecifiers(source: string, fileName?: string): string[];
+//#endregion
 //#region src/dts/resolved-tsconfig.d.ts
 /** @public */
 interface ResolvedTsconfigOptions {
@@ -1139,39 +1315,23 @@ declare function buildResolvedTsconfig(options: ResolvedTsconfigOptions): Resolv
  * @public
  */
 declare function writeResolvedTsconfig(options: ResolvedTsconfigOptions): string;
-//#endregion
-//#region src/entry/extract.d.ts
-/** @public */
-interface PackageJsonLike {
-  readonly exports?: unknown;
-  readonly bin?: unknown;
-}
-/** @public */
-interface ExtractOptions {
-  readonly exportsAsIndexes?: boolean | undefined;
-  /** Source paths to NOT turn into JS build entries (e.g. an exe entry compiled as a SEA). */
-  readonly excludeSources?: ReadonlyArray<string> | undefined;
-}
-/** @public */
-interface ExtractResult {
-  /** entry name to TS source path */
-  readonly entries: Record<string, string>;
-  /** entry name to original export key (for downstream output-map alignment) */
-  readonly exportPaths: Record<string, string>;
-}
 /**
- * Map an export key to the tsdown entry name (the emitted output basename).
+ * Derive a dts-EMIT variant of an already-written resolved tsconfig that adds
+ * `stableTypeOrdering: true`, and return its path. This makes the TypeScript declaration emitter
+ * (rolldown-plugin-dts on `typescript@6`) order union/type members deterministically, so a
+ * multi-union `.d.ts` (e.g. an Effect `Layer.Layer<…>` requirement channel) does not flip member
+ * order across otherwise-identical builds (#156). It is kept in a SEPARATE file from the
+ * api-extractor tsconfig on purpose: `@microsoft/api-extractor` pins `typescript ~5.9`, which
+ * predates the flag and hard-errors on the unknown compiler option — so only the emit passes
+ * (which run on TS6) ever see it, while the api-extractor compile reads the original clean config.
  *
- * `.` becomes `index`; otherwise the leading `./` is stripped and, unless
- * `exportsAsIndexes` is set, nested slashes are flattened to dashes
- * (e.g. `./changesets/markdownlint` to `changesets-markdownlint`). The manifest
- * transform reuses this so the declared output path always matches the emitted file.
+ * Best-effort: if the base tsconfig cannot be read or parsed (e.g. a synthetic test path that was
+ * never written), the original path is returned unchanged — the emit then simply keeps TS's
+ * default ordering rather than aborting the build at this layer.
  *
- * @internal
+ * @public
  */
-declare const createEntryName: (exportKey: string, exportsAsIndexes: boolean) => string;
-/** @public */
-declare function extractEntries(pkg: PackageJsonLike, options?: ExtractOptions): ExtractResult;
+declare function writeDtsEmitTsconfig(resolvedTsconfigPath: string): string;
 //#endregion
 //#region src/entry/package-json-entries.d.ts
 /** @public */
@@ -1718,5 +1878,5 @@ declare function resolveTargets(options: {
   baseName: string;
 }): TargetResolution;
 //#endregion
-export { BuildCollector, BuildCollectorTag, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, type CssOptions, DEFAULT_EXE_NODE_VERSION, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, EnvironmentDetector, EnvironmentDetectorLive, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, ExecutorResolverLive, type ExtractOptions, type ExtractResult, FormatSelector, FormatSelectorLive, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type LooseFileSpec, type LooseFiles, type ManifestLike, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OutputFormat, OutputRenderer, OutputRendererLive, type PackageJsonEntriesOptions, type PackageJsonLike, type PassKind, type PassReport, type PkgOsCpu, type PlainDiagnostic, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type RenderReportOptions, type RenderedOutput, ReportPipelineLive, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, TsconfigResolver, type TsdocOptions, type TsdocTagDefinition, type TsdownBuild, type TsdownLogger, type ValidationInput, type WarningSuppressionRule, applySubdirMetaEntries, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, computeExeFileName, createEntryName, createTimer, createTsdownLogger, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractEntries, flattenIssues, formatTime, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, syncPublicDir, transformBin, transformExports, transformManifest, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };
+export { type AmbientDtsEntry, BuildCollector, BuildCollectorTag, type BuildEmittedManifestOptions, type BuildFormat, type BuildGroupSpec, type BuildIssues, type BuildPlatform, type BuildReport, BuildReport as BuildReportSchema, type BuildTargetGroupsOptions, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, type CopyAmbientDtsOptions, type CssOptions, DEFAULT_EXE_NODE_VERSION, type DeriveOptions, type DerivedTsdownOptions, type DiagnosticEntry, type DiagnosticInput, type DtsExportClass, type DualExports, type EmitManifestOptions, type EmittedFile, type EntryOverride, type Environment, EnvironmentDetector, EnvironmentDetectorLive, type ExeBuild, type ExeConfig, type ExeRewrite, type ExeSeaConfig, type ExeTarget, type ExeTargetInput, type Executor, ExecutorResolver, ExecutorResolverLive, type ExtractAmbientOptions, type ExtractOptions, type ExtractResult, FormatSelector, FormatSelectorLive, type Formatter, type FormatterContext, type GenerateMetaOptions, type Json, JsonFormatter, type JsxConfig, type LooseFileSpec, type LooseFiles, type ManifestLike, MarkdownFormatter, MetaGenerationError, type MetaOptions, type MetaResult, type ModuleExportNames, type NextVersions, type NormalizedExe, type NormalizedLooseFile, type NormalizedMeta, type OutputFormat, OutputRenderer, OutputRendererLive, type PackageJsonEntriesOptions, type PackageJsonLike, type PassKind, type PassReport, type PkgOsCpu, type PlainDiagnostic, type PortableTsconfig, type PublishTargetObject, type PublishTargetValue, type PublishTargets, type ReexportBarrelAnalysis, type RenderReportOptions, type RenderedOutput, ReportPipelineLive, ReportTimings, type ResolvedCompilerOptions, type ResolvedGroup, type ResolvedTarget, type ResolvedTsconfig, type ResolvedTsconfigOptions, type RunExeBuildOptions, type RunMetaPassOptions, SilentFormatter, type TargetGroupId, type TargetGroupRef, type TargetGroupReport, TargetGroupReport as TargetGroupReportSchema, type TargetResolution, TerminalFormatter, type Timer, type TransformManifestOptions, type TsconfigJsx, TsconfigResolver, type TsdocOptions, type TsdocTagDefinition, type TsdownBuild, type TsdownLogger, type ValidationInput, type WarningSuppressionRule, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, isTargetObject, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,5 +1,9 @@
+import { analyzeReexportBarrel, collectExportNames, renderReexportStub } from "./dts/reexport-stub.js";
+import { buildResolvedTsconfig, writeDtsEmitTsconfig, writeResolvedTsconfig } from "./dts/resolved-tsconfig.js";
 import { resolveManifest } from "./catalog/resolve-catalogs.js";
+import { ConfigValidationError, MetaGenerationError } from "./errors.js";
 import { createEntryName, extractEntries } from "./entry/extract.js";
+import { ambientOutName, assertNoEntryCollisions, classifyDtsExport, declarationExt, extractAmbientDts, mixedDtsExportError } from "./entry/ambient-dts.js";
 import { defaultManifestTransform, normalizeBinPaths, transformBin, transformExports, transformManifest } from "./manifest/transform.js";
 import { buildEmittedManifest, emitManifest } from "./manifest/emit-manifest.js";
 import { buildMetricsPlugin } from "./report/metrics-plugin.js";
@@ -7,10 +11,10 @@ import { createTimer, formatTime } from "./report/timer.js";
 import { createTsdownLogger } from "./report/tsdown-logger.js";
 import { cjsDefaultInterop } from "./build/cjs-default-interop.js";
 import { nodeBuiltinDefaultInterop } from "./build/node-builtin-default-interop.js";
-import { syncPublicDir } from "./build/sync-public.js";
+import { findRelativeSpecifiers } from "./dts/relative-imports.js";
+import { copyAmbientDts, copyPublicDir } from "./build/sync-public.js";
 import { deriveTargetGroupOptions } from "./build/target-groups.js";
 import { buildTargetGroups } from "./build/build-target-groups.js";
-import { ConfigValidationError, MetaGenerationError } from "./errors.js";
 import { normalizeLooseFiles } from "./build/loose-files.js";
 import { removeDeclarationMaps } from "./build/strip-maps.js";
 import { resolveNextVersions } from "./changesets/next-versions.js";
@@ -19,7 +23,6 @@ import { DEFAULT_EXE_NODE_VERSION, normalizeExeOptions } from "./exe/config.js";
 import { isTargetObject } from "./targets/config.js";
 import { resolveTargets } from "./targets/resolve-targets.js";
 import { ConfigValidatorLive } from "./config-validation/ConfigValidatorLive.js";
-import { buildResolvedTsconfig, writeResolvedTsconfig } from "./dts/resolved-tsconfig.js";
 import { packageJsonEntries } from "./entry/package-json-entries.js";
 import { runExeBuild } from "./exe/build.js";
 import { computeExeFileName } from "./exe/filename.js";
@@ -49,4 +52,4 @@ import { ReportPipelineLive, renderReport } from "./report/pipeline.js";
 import { writeTargetsBinding } from "./targets/binding.js";
 import { CatalogAssemblyError, CatalogResolutionError } from "workspaces-effect";
 
-export { BuildCollector, BuildCollectorTag, BuildReport as BuildReportSchema, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, EnvironmentDetector, EnvironmentDetectorLive, ExecutorResolver, ExecutorResolverLive, FormatSelector, FormatSelectorLive, JsonFormatter, MarkdownFormatter, MetaGenerationError, OutputRenderer, OutputRendererLive, ReportPipelineLive, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsconfigResolver, applySubdirMetaEntries, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, computeExeFileName, createEntryName, createTimer, createTsdownLogger, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractEntries, flattenIssues, formatTime, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, syncPublicDir, transformBin, transformExports, transformManifest, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };
+export { BuildCollector, BuildCollectorTag, BuildReport as BuildReportSchema, CatalogAssemblyError, CatalogResolutionError, CiAnnotationsFormatter, ConfigValidationError, ConfigValidator, ConfigValidatorLive, DEFAULT_EXE_NODE_VERSION, EnvironmentDetector, EnvironmentDetectorLive, ExecutorResolver, ExecutorResolverLive, FormatSelector, FormatSelectorLive, JsonFormatter, MarkdownFormatter, MetaGenerationError, OutputRenderer, OutputRendererLive, ReportPipelineLive, ReportTimings, SilentFormatter, TargetGroupReport as TargetGroupReportSchema, TerminalFormatter, TsconfigResolver, ambientOutName, analyzeReexportBarrel, applySubdirMetaEntries, assertNoEntryCollisions, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, classifyDtsExport, collectExportNames, computeExeFileName, copyAmbientDts, copyPublicDir, createEntryName, createTimer, createTsdownLogger, declarationExt, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractAmbientDts, extractEntries, findRelativeSpecifiers, flattenIssues, formatTime, generateMeta, isTargetObject, mixedDtsExportError, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, writeIssuesArtifact, writeResolvedTsconfig, writeTargetsBinding };

package/jsx/config.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
 //#region src/jsx/config.ts
 /**

package/manifest/transform.js

@@ -1,4 +1,5 @@
 import { createEntryName } from "../entry/extract.js";
+import { ambientOutName, classifyDtsExport, mixedDtsExportError } from "../entry/ambient-dts.js";
 import sortPackageJson from "sort-package-json";
 
 //#region src/manifest/transform.ts
@@ -83,6 +84,16 @@ const tsConditions = (exportKey, dual, subdirExports) => ({
 	...dual ? { require: toBuiltCjs(exportKey, subdirExports) } : {}
 });
 /**
+* A `./public/<path>` export value points into the staged `public/` dir, whose CONTENTS `copyPublicDir`
+* copies into the package root (only the `public/` segment is dropped; substructure is kept). So the
+* published manifest value drops that same `public/` segment: `./public/tsconfig/ecma.json` becomes
+* `./tsconfig/ecma.json`, resolving the file copyPublicDir placed at `<pkg>/tsconfig/ecma.json`.
+* Non-strings and non-public values pass through unchanged.
+*/
+function stripPublicPrefix(value) {
+	return typeof value === "string" && value.startsWith("./public/") ? `./${value.slice(9)}` : value;
+}
+/**
 * Rewrite an exports map: TS string targets become a types/import conditions object.
 * Each TS condition also gets a `require` entry when `dual` is `true` (uniform) or when
 * the export key is in the `dual` Set (per-entry).
@@ -95,12 +106,18 @@ const tsConditions = (exportKey, dual, subdirExports) => ({
 * @public
 */
 function transformExports(exports, dual = false, subdirExports) {
-	if (typeof exports === "string") return isTs(exports) ? tsConditions(".", isDualKey(dual, "."), subdirExports) : exports;
+	if (typeof exports === "string") return isTs(exports) ? tsConditions(".", isDualKey(dual, "."), subdirExports) : stripPublicPrefix(exports);
 	if (exports && typeof exports === "object") {
 		const out = {};
 		for (const [key, value] of Object.entries(exports)) {
-			if (key === "./package.json" || key.endsWith(".json")) {
-				out[key] = value;
+			if (key === "./package.json" || key.endsWith(".json") || isDeclarationFile(key)) {
+				out[key] = stripPublicPrefix(value);
+				continue;
+			}
+			const cls = classifyDtsExport(value);
+			if (cls.kind === "mixed") throw mixedDtsExportError(key);
+			if (cls.kind === "ambient") {
+				out[key] = { types: `./${ambientOutName(key, cls.source)}` };
 				continue;
 			}
 			if (typeof value === "string" && isTs(value)) out[key] = tsConditions(key, isDualKey(dual, key), subdirExports);

package/meta/generate.js

@@ -2,8 +2,8 @@ import { runApiExtractor } from "./api-extractor.js";
 import { mergeApiModels } from "./merge-models.js";
 import { resolvePortableTsconfig } from "./tsconfig-resolver.js";
 import { writeTsdocConfig } from "./tsdoc-config.js";
-import { join } from "node:path";
 import { copyFileSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 
 //#region src/meta/generate.ts
 function unscopedName(name) {

package/meta/tsconfig-resolver.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { JsxEmit, ModuleDetectionKind, ModuleKind, ModuleResolutionKind, NewLineKind, ScriptTarget, flattenDiagnosticMessageText, getParsedCommandLineOfConfigFile, sys } from "typescript";
 
 //#region src/meta/tsconfig-resolver.ts

package/meta/tsdoc-config.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { StandardTags } from "@microsoft/tsdoc";
 import deepEqual from "deep-equal";
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "0.11.2",
+	"version": "1.0.0",
 	"private": false,
 	"description": "Interface-only tsdown/rolldown plugin pack powering @savvy-web/bundler",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/tsdown-plugins",

package/report/issues-artifact.js

@@ -1,5 +1,5 @@
-import { dirname, join } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 //#region src/report/issues-artifact.ts
 /** Copy a DiagnosticEntry to a plain object, omitting undefined optionals for stable output. */

package/targets/binding.js

@@ -1,5 +1,5 @@
-import { join } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 
 //#region src/targets/binding.ts
 /**