@savvy-web/tsdown-plugins 0.12.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Savvy Web Strategy, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -6,7 +6,7 @@ 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 { readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
@@ -140,7 +140,6 @@ 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;
 			const dtsDeps = dtsNeverBundle.length > 0 || partBundleNodeModules || dts.bundledPackages ? { deps: {
@@ -302,6 +301,7 @@ async function buildTargetGroups(options) {
 				]
 			}));
 		}
+		copyPublicDir(publicDir, outDirFor(options.cwd, group.id));
 	}
 }
 

package/build/sync-public.js

@@ -1,4 +1,6 @@
-import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+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";
 
 //#region src/build/sync-public.ts
@@ -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/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/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/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";
@@ -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).
@@ -1172,6 +1282,9 @@ declare function renderReexportStub(options: {
   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 {
@@ -1220,39 +1333,6 @@ declare function writeResolvedTsconfig(options: ResolvedTsconfigOptions): string
  */
 declare function writeDtsEmitTsconfig(resolvedTsconfigPath: string): 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/package-json-entries.d.ts
 /** @public */
 interface PackageJsonEntriesOptions extends ExtractOptions {
@@ -1798,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 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, analyzeReexportBarrel, applySubdirMetaEntries, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, collectExportNames, computeExeFileName, createEntryName, createTimer, createTsdownLogger, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractEntries, flattenIssues, formatTime, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, syncPublicDir, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, 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,7 +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";
@@ -9,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";
@@ -50,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, analyzeReexportBarrel, applySubdirMetaEntries, buildEmittedManifest, buildMetricsPlugin, buildResolvedTsconfig, buildTargetGroups, cjsDefaultInterop, collectExportNames, computeExeFileName, createEntryName, createTimer, createTsdownLogger, defaultManifestTransform, deriveExportPaths, deriveTargetGroupOptions, emitManifest, extractEntries, flattenIssues, formatTime, generateMeta, isTargetObject, nodeBuiltinDefaultInterop, normalizeBinPaths, normalizeExeOptions, normalizeLooseFiles, normalizeMetaOptions, packageJsonEntries, readTsconfigJsx, removeDeclarationMaps, renderReexportStub, renderReport, resolveJsxConfig, resolveManifest, resolveNextVersions, resolvePortableTsconfig, resolveTargets, rewriteMetaVersions, runExeBuild, runMetaPass, serializeIssues, syncPublicDir, transformBin, transformExports, transformManifest, writeDtsEmitTsconfig, 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/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/tsdown-plugins",
-	"version": "0.12.0",
+	"version": "1.0.1",
 	"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",
@@ -43,6 +43,6 @@
 		"workspaces-effect": "^1.2.0"
 	},
 	"peerDependencies": {
-		"effect": ">=3.21.0"
+		"effect": "^3.21.0"
 	}
 }