@fastkit/plugboy 1.5.0 → 1.6.0

package/README.md

@@ -190,10 +190,12 @@ Set it in `plugboy.project.ts` to apply defaults to every workspace; a workspace
 value is shallow-merged over the project one, so it only needs to restate the
 keys it changes.
 
-Plugins may seed defaults here during workspace setup — the vanilla-extract
-plugin, for instance, owns `splitting` and `fileName` so the emitted file matches
-the CSS export plugboy declares. A configured value always wins over a plugin
-default, so check the plugin's documentation before overriding a key it manages.
+`splitting` is best left alone. In a workspace with `css: true` entries plugboy
+turns it on and builds the declared stylesheets itself, in dependency order (see
+[Stylesheets of the CSS entries](#stylesheets-of-the-css-entries)); `fileName`
+still names the result. Declaring `splitting` hands the merge back to tsdown as
+written. Plugins may seed other defaults here during workspace setup; a configured
+value always wins over them.
 
 #### CSS Optimization
 
@@ -236,22 +238,40 @@ Both are captured from every stylesheet in the module graph, whether its content
 were authored or generated by a plugin — vanilla-extract emits its `@layer`
 statements into a virtual module, and those are covered too.
 
-#### One stylesheet per CSS entry
+#### Stylesheets of the CSS entries
 
 Every entry with `css: true` gets a `./<entry>.css` export, and each of those files
-is guaranteed to exist and to be usable on its own.
-
-With several such entries the build emits one stylesheet per output *chunk*
-(`css.splitting`), which does not line up: CSS reached from more than one entry is
-moved into a shared chunk and emitted under a hashed name that no export points at,
-and an entry whose CSS comes only from there gets no stylesheet at all. plugboy
-rebuilds each entry's stylesheet from its own CSS plus the CSS of every chunk it
-imports, dependencies first, and drops the leftover per-chunk files. Shared CSS is
-duplicated into each entry that needs it, which is what makes a single
-`./<entry>.css` import complete.
-
-This is skipped when `css.inject` is on, since the JavaScript then imports the
-per-chunk stylesheets by name.
+is guaranteed to exist, to be usable on its own, and to be in **dependency order**:
+a style that another one composes from or imports comes before it. That is what
+lets the rules built on a shared reset, or on the `base` of a vanilla-extract
+`style([base, { … }])`, win over it as intended.
+
+plugboy builds these files itself. The build emits one stylesheet per output
+*chunk* (`css.splitting`), and plugboy concatenates them in the order the chunks
+load — the order Vite uses for `build.cssCodeSplit: false`: each chunk after the
+chunks it imports statically, chunks reached only through `import()` after all of
+those. tsdown's own single-file merge is not used, because it concatenates chunks
+in bundle order, which puts a shared chunk *after* the entries depending on it.
+
+- **One CSS entry**: the package's one stylesheet holds the CSS of every chunk,
+  including what is loaded through `import()` — nothing loads a per-chunk
+  stylesheet at runtime without `css.inject`. It is written under `css.fileName`
+  when that is set.
+- **Several**: each entry's stylesheet holds its own CSS and that of every chunk it
+  reaches. CSS shared between entries is duplicated into each, so a single
+  `./<entry>.css` import is complete.
+
+The per-chunk files are removed afterwards, since no export points at them.
+
+The guarantee is dependency order, per chunk. It is not the order Vite's dev
+server — and so Storybook — applies, which injects styles one module at a time:
+two rules that do not depend on each other can end up in a different relative
+order. If such a pair targets the same element with the same specificity, make the
+intended winner explicit with `@layer` or by composing one from the other.
+
+Nothing is assembled with `css.inject` (the JavaScript then imports the per-chunk
+stylesheets by name, so they stay as emitted), or when `splitting` is declared,
+which leaves the merge to tsdown.
 
 ### defineProjectConfig
 

package/dist/cli.mjs

@@ -1,7 +1,7 @@
-import { i as getWorkspace, t as generateWorkspace } from "./workspace-Dngfi1p6.mjs";
+import { i as getWorkspace, t as generateWorkspace } from "./workspace-DdhCZjQE.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "1.5.0";
+var version = "1.6.0";
 //#endregion
 //#region src/cli.ts
 async function main() {

package/dist/plugboy.d.mts

@@ -320,6 +320,83 @@ declare class Builder {
 //#region src/workspace/generate.d.ts
 declare function generateWorkspace(workspaceName?: string, cwd?: string): Promise<void>;
 //#endregion
+//#region src/workspace/chunk-order.d.ts
+/**
+ * The order in which the chunks of a build load their stylesheets.
+ *
+ * A stylesheet's rules win over an earlier one's at equal specificity, so the
+ * order chunks' CSS is concatenated in is part of what the CSS means. What a
+ * package composes from — a shared reset, a vanilla-extract `style([base, …])`
+ * — has to come before the rules that build on it.
+ *
+ * The bundle's own order does not give that. Entry chunks come first and the
+ * chunks they import follow, so a shared chunk lands *after* the entries that
+ * depend on it. `@tsdown/css` concatenates in that order when `css.splitting` is
+ * off, and so did everything in plugboy that took `Object.values(bundle)` as the
+ * load order.
+ *
+ * This walks the chunk graph the way Vite does for `build.cssCodeSplit: false`:
+ * from each root, static imports first and the chunk itself after them; then the
+ * dynamically imported chunks, which load later, in the order they were reached.
+ * Every CSS producer in plugboy orders by this, so a package gets the same order
+ * whichever of them emitted its styles.
+ */
+/** What the ordering needs to know about a chunk. */
+interface ChunkGraphNode {
+  /** The chunk's name — for an entry chunk, the entry id plugboy declared. */
+  name: string;
+  isEntry: boolean;
+  /** File names of the chunks this one imports statically. */
+  imports: string[];
+  /** File names of the chunks this one imports with `import()`. */
+  dynamicImports: string[];
+}
+/** Chunk file name -> its node. Iteration order is the bundle's. */
+type ChunkGraph = Map<string, ChunkGraphNode>;
+interface BundleChunkLike {
+  type: string;
+  fileName: string;
+  name?: string;
+  isEntry?: boolean;
+  imports?: string[];
+  dynamicImports?: string[];
+}
+/**
+ * Capture the chunk graph of a bundle.
+ *
+ * Call it from `generateBundle`, before `@tsdown/css` runs: that removes the
+ * chunks holding nothing but CSS, together with every import of them, so a
+ * graph captured later has lost exactly the edges that matter here.
+ */
+declare function captureChunkGraph(bundle: Record<string, BundleChunkLike>): ChunkGraph;
+/**
+ * The entry chunks of a graph, in the order the entries were declared.
+ *
+ * `entryIds` are the names plugboy gives the entries (`.` normalized to the
+ * package directory name). Entry chunks it does not name keep the bundle's order,
+ * after the named ones.
+ */
+declare function entryChunksInDeclaredOrder(graph: ChunkGraph, entryIds?: readonly string[]): string[];
+interface OrderChunksOptions {
+  /**
+   * Append the chunks no root reaches, in bundle order. Set it when the result
+   * stands for the whole package; leave it off when it stands for one entry.
+   */
+  includeUnreached?: boolean;
+}
+/**
+ * Chunk file names in load order, starting from `roots`.
+ *
+ * Each chunk appears once, after every chunk it imports statically. Chunks
+ * reached only through `import()` follow all of those.
+ */
+declare function orderChunks(graph: ChunkGraph, roots: readonly string[], options?: OrderChunksOptions): string[];
+/**
+ * Every chunk of the package in load order: the entries as declared, then what
+ * they import dynamically, then anything left over.
+ */
+declare function orderPackageChunks(graph: ChunkGraph, entryIds?: readonly string[]): string[];
+//#endregion
 //#region src/types/dts.d.ts
 interface EmitDTSOptions {
   cwd?: string;
@@ -640,11 +717,14 @@ interface UserWorkspaceConfig extends TSDownSyncOptions {
    * Shallow-merged over the project configuration, so a workspace only needs to
    * restate the keys it changes.
    *
-   * Plugins may seed defaults here during workspace setup (e.g. the
-   * vanilla-extract plugin sets `splitting` / `fileName`, which it needs to own
-   * to keep its CSS pipeline intact). A value declared in the configuration
-   * always wins over such a default — consult the plugin's documentation before
-   * overriding a key it manages.
+   * In a workspace with `css: true` entries, plugboy turns `splitting` on and
+   * builds each declared `./<entry>.css` itself, in dependency order;
+   * `fileName` names the stylesheet of a single CSS entry. Declaring `splitting`
+   * leaves the merge to tsdown as written, which concatenates chunks in bundle
+   * order — leave it unset unless that is what you want.
+   *
+   * Plugins may seed other defaults here during workspace setup. A value declared
+   * in the configuration always wins over such a default.
    *
    * `css.target` defaults to {@link UserWorkspaceConfig.target}.
    *
@@ -1018,4 +1098,4 @@ interface GetWorkspacePackageJsonResult {
 declare function getWorkspacePackageJson<AllowMissing extends boolean | undefined = false>(searchDir?: string, allowMissing?: AllowMissing): Promise<AllowMissing extends true ? GetWorkspacePackageJsonResult | null : GetWorkspacePackageJsonResult>;
 declare function findWorkspacePackages(dir: string): Promise<GetWorkspacePackageJsonResult[]>;
 //#endregion
-export { BuildedHooks, Builder, DANGLING_DTS_SOURCE_MAP_RE, DTSCompilerFunction, DTSCompilerOption, DTSNormalizer, DTSPreserveTypeSettings, DTSPreserveTypeTarget, DTSSettings, EmitDTSOptions, ExposeEntriesSettings, ExternalOption, FindConfigResult, GetProjectPackageJsonResult, GetWorkspacePackageJsonResult, HookArgs, HookName, HookReturnType, HookTypes, Listable, NoExternalOption, NormalizedDTSPreserveTypeSettings, NormalizedDTSPreserveTypeTarget, NormalizedDTSSettings, OptimizeCSSOptions, PROJECT_REQUIRED_FIELDS, Path, PlugboyProject, PlugboyWorkspace, Plugin, ProjectPackageJson, ProjectScriptsTemplate, ProjectSetupContext, RawExposeEntriesSettings, RawWorkspaceEntries, RawWorkspaceEntry, RawWorkspaceEntryObject, ResolvedHooks, ResolvedOptimizeCSSOptions, ResolvedProjectConfig, ResolvedWorkspaceConfig, TSConfigJSON, TSDOWN_SYNC_OPTIONS, TryGetWorkspace, type TsdownPlugin, UnPromisify, UserHooks, UserPluginOption, UserProjectConfig, UserWorkspaceConfig, WORKSPACE_PACKAGE_SYNC_FIELDS, WORKSPACE_REQUIRED_FIELDS, WorkspaceDirs, WorkspaceEntries, WorkspaceEntry, WorkspaceExport, WorkspaceMeta, WorkspaceObjectExport, WorkspacePackageJson, WorkspaceSetupContext, WorkspaceStubLink, WorkspaceStubLinkType, buildHooks, collectExternalStringPrefixes, copyDirSync, createHooksDefaults, definePlugin, defineProjectConfig, defineWorkspaceConfig, exitHook, exposeEntries, extractProjectPlugins, findConfig, findFile, findProjectPlugin, findWorkspacePackages, generateWorkspace, getDirname, getFilename, getProject, getProjectPackageJson, getWorkspace, getWorkspacePackageJson, isFileNotFoundException, isProjectPackageJson, isPromise, isWorkspacePackageJson, loadProjectConfig, loadWorkspaceConfig, mergeChunkAddons, mergeDTSSettingsList, mergeExternals, mergeNoExternals, normalizeDTSPreserveTypeSettings, normalizeDTSPreserveTypeTarget, normalizeDTSSettings, pathExists, resolveBundledConfigOutputFile, resolveListable, resolveOptimizeCSSOptions, resolveRawExposeEntriesSettings, resolveRawWorkspaceEntries, resolveRawWorkspaceEntry, resolveUserHooks, resolveUserPluginOption, resolveUserProjectConfig, resolveUserWorkspaceConfig, rmrf, stripDanglingDTSSourceMaps, syncWorkspacePackageFields, writeFileAtomic };
+export { BuildedHooks, Builder, ChunkGraph, ChunkGraphNode, DANGLING_DTS_SOURCE_MAP_RE, DTSCompilerFunction, DTSCompilerOption, DTSNormalizer, DTSPreserveTypeSettings, DTSPreserveTypeTarget, DTSSettings, EmitDTSOptions, ExposeEntriesSettings, ExternalOption, FindConfigResult, GetProjectPackageJsonResult, GetWorkspacePackageJsonResult, HookArgs, HookName, HookReturnType, HookTypes, Listable, NoExternalOption, NormalizedDTSPreserveTypeSettings, NormalizedDTSPreserveTypeTarget, NormalizedDTSSettings, OptimizeCSSOptions, OrderChunksOptions, PROJECT_REQUIRED_FIELDS, Path, PlugboyProject, PlugboyWorkspace, Plugin, ProjectPackageJson, ProjectScriptsTemplate, ProjectSetupContext, RawExposeEntriesSettings, RawWorkspaceEntries, RawWorkspaceEntry, RawWorkspaceEntryObject, ResolvedHooks, ResolvedOptimizeCSSOptions, ResolvedProjectConfig, ResolvedWorkspaceConfig, TSConfigJSON, TSDOWN_SYNC_OPTIONS, TryGetWorkspace, type TsdownPlugin, UnPromisify, UserHooks, UserPluginOption, UserProjectConfig, UserWorkspaceConfig, WORKSPACE_PACKAGE_SYNC_FIELDS, WORKSPACE_REQUIRED_FIELDS, WorkspaceDirs, WorkspaceEntries, WorkspaceEntry, WorkspaceExport, WorkspaceMeta, WorkspaceObjectExport, WorkspacePackageJson, WorkspaceSetupContext, WorkspaceStubLink, WorkspaceStubLinkType, buildHooks, captureChunkGraph, collectExternalStringPrefixes, copyDirSync, createHooksDefaults, definePlugin, defineProjectConfig, defineWorkspaceConfig, entryChunksInDeclaredOrder, exitHook, exposeEntries, extractProjectPlugins, findConfig, findFile, findProjectPlugin, findWorkspacePackages, generateWorkspace, getDirname, getFilename, getProject, getProjectPackageJson, getWorkspace, getWorkspacePackageJson, isFileNotFoundException, isProjectPackageJson, isPromise, isWorkspacePackageJson, loadProjectConfig, loadWorkspaceConfig, mergeChunkAddons, mergeDTSSettingsList, mergeExternals, mergeNoExternals, normalizeDTSPreserveTypeSettings, normalizeDTSPreserveTypeTarget, normalizeDTSSettings, orderChunks, orderPackageChunks, pathExists, resolveBundledConfigOutputFile, resolveListable, resolveOptimizeCSSOptions, resolveRawExposeEntriesSettings, resolveRawWorkspaceEntries, resolveRawWorkspaceEntry, resolveUserHooks, resolveUserPluginOption, resolveUserProjectConfig, resolveUserWorkspaceConfig, rmrf, stripDanglingDTSSourceMaps, syncWorkspacePackageFields, writeFileAtomic };

package/dist/plugboy.mjs

@@ -1,2 +1,2 @@
-import { $ as resolveOptimizeCSSOptions, A as resolveRawExposeEntriesSettings, B as resolveBundledConfigOutputFile, C as findProjectPlugin, D as loadProjectConfig, E as isProjectPackageJson, F as getFilename, G as mergeChunkAddons, H as stripDanglingDTSSourceMaps, I as isFileNotFoundException, J as isPromise, K as mergeExternals, L as pathExists, M as findConfig, N as findFile, O as resolveUserProjectConfig, P as getDirname, Q as WORKSPACE_REQUIRED_FIELDS, R as rmrf, S as extractProjectPlugins, T as defineProjectConfig, U as exitHook, V as DANGLING_DTS_SOURCE_MAP_RE, W as collectExternalStringPrefixes, X as PROJECT_REQUIRED_FIELDS, Y as resolveListable, Z as TSDOWN_SYNC_OPTIONS, _ as loadWorkspaceConfig, a as syncWorkspacePackageFields, b as resolveUserWorkspaceConfig, c as Builder, d as getWorkspacePackageJson, et as mergeDTSSettingsList, f as Path, g as isWorkspacePackageJson, h as defineWorkspaceConfig, i as getWorkspace, it as createHooksDefaults, j as copyDirSync, k as exposeEntries, l as findWorkspacePackages, m as resolveUserHooks, n as PlugboyWorkspace, nt as normalizeDTSPreserveTypeTarget, o as PlugboyProject, p as buildHooks, q as mergeNoExternals, r as WORKSPACE_PACKAGE_SYNC_FIELDS, rt as normalizeDTSSettings, s as getProject, t as generateWorkspace, tt as normalizeDTSPreserveTypeSettings, u as getProjectPackageJson, v as resolveRawWorkspaceEntries, w as resolveUserPluginOption, x as definePlugin, y as resolveRawWorkspaceEntry, z as writeFileAtomic } from "./workspace-Dngfi1p6.mjs";
-export { Builder, DANGLING_DTS_SOURCE_MAP_RE, PROJECT_REQUIRED_FIELDS, Path, PlugboyProject, PlugboyWorkspace, TSDOWN_SYNC_OPTIONS, WORKSPACE_PACKAGE_SYNC_FIELDS, WORKSPACE_REQUIRED_FIELDS, buildHooks, collectExternalStringPrefixes, copyDirSync, createHooksDefaults, definePlugin, defineProjectConfig, defineWorkspaceConfig, exitHook, exposeEntries, extractProjectPlugins, findConfig, findFile, findProjectPlugin, findWorkspacePackages, generateWorkspace, getDirname, getFilename, getProject, getProjectPackageJson, getWorkspace, getWorkspacePackageJson, isFileNotFoundException, isProjectPackageJson, isPromise, isWorkspacePackageJson, loadProjectConfig, loadWorkspaceConfig, mergeChunkAddons, mergeDTSSettingsList, mergeExternals, mergeNoExternals, normalizeDTSPreserveTypeSettings, normalizeDTSPreserveTypeTarget, normalizeDTSSettings, pathExists, resolveBundledConfigOutputFile, resolveListable, resolveOptimizeCSSOptions, resolveRawExposeEntriesSettings, resolveRawWorkspaceEntries, resolveRawWorkspaceEntry, resolveUserHooks, resolveUserPluginOption, resolveUserProjectConfig, resolveUserWorkspaceConfig, rmrf, stripDanglingDTSSourceMaps, syncWorkspacePackageFields, writeFileAtomic };
+import { $ as resolveListable, A as isProjectPackageJson, B as isFileNotFoundException, C as resolveRawWorkspaceEntry, D as findProjectPlugin, E as extractProjectPlugins, F as copyDirSync, G as DANGLING_DTS_SOURCE_MAP_RE, H as rmrf, I as findConfig, J as collectExternalStringPrefixes, K as stripDanglingDTSSourceMaps, L as findFile, M as resolveUserProjectConfig, N as exposeEntries, O as resolveUserPluginOption, P as resolveRawExposeEntriesSettings, Q as isPromise, R as getDirname, S as resolveRawWorkspaceEntries, T as definePlugin, U as writeFileAtomic, V as pathExists, W as resolveBundledConfigOutputFile, X as mergeExternals, Y as mergeChunkAddons, Z as mergeNoExternals, _ as buildHooks, a as syncWorkspacePackageFields, at as normalizeDTSPreserveTypeSettings, b as isWorkspacePackageJson, c as orderChunks, ct as createHooksDefaults, d as getProject, et as PROJECT_REQUIRED_FIELDS, f as Builder, g as Path, h as getWorkspacePackageJson, i as getWorkspace, it as mergeDTSSettingsList, j as loadProjectConfig, k as defineProjectConfig, l as orderPackageChunks, m as getProjectPackageJson, n as PlugboyWorkspace, nt as WORKSPACE_REQUIRED_FIELDS, o as captureChunkGraph, ot as normalizeDTSPreserveTypeTarget, p as findWorkspacePackages, q as exitHook, r as WORKSPACE_PACKAGE_SYNC_FIELDS, rt as resolveOptimizeCSSOptions, s as entryChunksInDeclaredOrder, st as normalizeDTSSettings, t as generateWorkspace, tt as TSDOWN_SYNC_OPTIONS, u as PlugboyProject, v as resolveUserHooks, w as resolveUserWorkspaceConfig, x as loadWorkspaceConfig, y as defineWorkspaceConfig, z as getFilename } from "./workspace-DdhCZjQE.mjs";
+export { Builder, DANGLING_DTS_SOURCE_MAP_RE, PROJECT_REQUIRED_FIELDS, Path, PlugboyProject, PlugboyWorkspace, TSDOWN_SYNC_OPTIONS, WORKSPACE_PACKAGE_SYNC_FIELDS, WORKSPACE_REQUIRED_FIELDS, buildHooks, captureChunkGraph, collectExternalStringPrefixes, copyDirSync, createHooksDefaults, definePlugin, defineProjectConfig, defineWorkspaceConfig, entryChunksInDeclaredOrder, exitHook, exposeEntries, extractProjectPlugins, findConfig, findFile, findProjectPlugin, findWorkspacePackages, generateWorkspace, getDirname, getFilename, getProject, getProjectPackageJson, getWorkspace, getWorkspacePackageJson, isFileNotFoundException, isProjectPackageJson, isPromise, isWorkspacePackageJson, loadProjectConfig, loadWorkspaceConfig, mergeChunkAddons, mergeDTSSettingsList, mergeExternals, mergeNoExternals, normalizeDTSPreserveTypeSettings, normalizeDTSPreserveTypeTarget, normalizeDTSSettings, orderChunks, orderPackageChunks, pathExists, resolveBundledConfigOutputFile, resolveListable, resolveOptimizeCSSOptions, resolveRawExposeEntriesSettings, resolveRawWorkspaceEntries, resolveRawWorkspaceEntry, resolveUserHooks, resolveUserPluginOption, resolveUserProjectConfig, resolveUserWorkspaceConfig, rmrf, stripDanglingDTSSourceMaps, syncWorkspacePackageFields, writeFileAtomic };

package/dist/{workspace-Dngfi1p6.mjs → workspace-DdhCZjQE.mjs}

@@ -1088,19 +1088,39 @@ function declaredStylesheets(workspace) {
 	return new Set(workspace.exports.filter((exp) => exp.id.endsWith(".css")).map((exp) => path.posix.basename(exp.id)));
 }
 /**
+* The file name of the package's one assembled stylesheet, or `undefined` when
+* plugboy does not assemble one.
+*
+* With a single CSS entry the package publishes one stylesheet holding all of its
+* CSS. `plugboy-assemble-entry-css` writes it under `css.fileName` when that is
+* set, and under the declared `<entry>.css` otherwise. With several CSS entries
+* each gets its own, so there is no package-wide one.
+*/
+function assembledStylesheetName(workspace) {
+	const { cssOptions } = workspace;
+	if (!cssOptions?.splitting || cssOptions.inject) return void 0;
+	const declared = declaredStylesheets(workspace);
+	if (declared.size !== 1) return void 0;
+	return cssOptions.fileName ?? [...declared][0];
+}
+/**
 * Every stylesheet the build has written to `dir`, as file names.
 *
-* The bundle is not the whole story: `plugboy-assemble-entry-css` writes an
-* entry's stylesheet directly to disk when the build produced none for it, so a
-* `writeBundle` stage that only walked the bundle assets would skip exactly the
-* file that needed the most work. The declared exports fill that in — they are the
-* stylesheets the package publishes, so anything present under one of those names
-* belongs in the set.
+* The bundle is not the whole story: `plugboy-assemble-entry-css` writes the
+* declared stylesheets directly to disk, often under a name the build emitted
+* nothing for, so a `writeBundle` stage that only walked the bundle assets would
+* skip exactly the file that needed the most work. The declared exports — and the
+* package stylesheet's `css.fileName`, when one is set — fill that in: they are
+* the stylesheets the package publishes, so anything present under one of those
+* names belongs in the set.
 */
 async function listEmittedStylesheets(workspace, dir, bundle) {
 	const names = /* @__PURE__ */ new Set();
 	for (const chunk of Object.values(bundle)) if (chunk.type === "asset" && chunk.fileName.endsWith(".css")) names.add(chunk.fileName);
-	await Promise.all([...declaredStylesheets(workspace)].map(async (name) => {
+	const assembled = assembledStylesheetName(workspace);
+	const candidates = new Set(declaredStylesheets(workspace));
+	if (assembled) candidates.add(assembled);
+	await Promise.all([...candidates].map(async (name) => {
 		if (names.has(name)) return;
 		try {
 			await fs$1.access(path.join(dir, name));
@@ -1109,6 +1129,38 @@ async function listEmittedStylesheets(workspace, dir, bundle) {
 	}));
 	return [...names];
 }
+/**
+* Fill in the `css` options plugboy needs to deliver its declared stylesheets.
+*
+* `cssEntryIds` are the entries with `css: true`, named as plugboy names them
+* (`.` normalized to the package directory name).
+*
+* By default the build emits one stylesheet per chunk (`splitting: true`) and
+* `plugboy-assemble-entry-css` builds each declared stylesheet from them, in
+* dependency order. tsdown's own single-file merge is not used, because it
+* concatenates chunks in bundle order: a shared chunk lands after the entries
+* that compose from it, and loses to the base styles it was meant to override.
+* A `fileName` is still honored — it names the assembled stylesheet.
+*
+* tsdown merges into one file itself only where plugboy cannot assemble:
+* - `splitting` declared explicitly, which is applied as written;
+* - `inject`, where the JavaScript imports the per-chunk stylesheets by name, so
+*   they have to stay as emitted. One CSS entry then keeps a single file.
+*
+* A single file is named after the CSS entry unless `fileName` says otherwise, so
+* it is the file the `./<entry>.css` export points at. A workspace without CSS
+* entries is left to tsdown's defaults.
+*/
+function resolveCssOptions(css, cssEntryIds) {
+	if (!cssEntryIds.length) return css;
+	const splitting = css?.splitting ?? (css?.inject ? cssEntryIds.length > 1 : true);
+	const resolved = {
+		...css,
+		splitting
+	};
+	if (!splitting && cssEntryIds.length === 1) resolved.fileName ??= `${cssEntryIds[0]}.css`;
+	return resolved;
+}
 //#endregion
 //#region src/postcss/plugin.ts
 async function getPostcss(options) {
@@ -1196,69 +1248,174 @@ function OptimizeCSSPlugin(workspace) {
 	};
 }
 //#endregion
+//#region src/workspace/chunk-order.ts
+/**
+* Capture the chunk graph of a bundle.
+*
+* Call it from `generateBundle`, before `@tsdown/css` runs: that removes the
+* chunks holding nothing but CSS, together with every import of them, so a
+* graph captured later has lost exactly the edges that matter here.
+*/
+function captureChunkGraph(bundle) {
+	const graph = /* @__PURE__ */ new Map();
+	for (const chunk of Object.values(bundle)) {
+		if (chunk.type !== "chunk") continue;
+		graph.set(chunk.fileName, {
+			name: chunk.name ?? chunk.fileName,
+			isEntry: !!chunk.isEntry,
+			imports: [...chunk.imports ?? []],
+			dynamicImports: [...chunk.dynamicImports ?? []]
+		});
+	}
+	return graph;
+}
+/**
+* The entry chunks of a graph, in the order the entries were declared.
+*
+* `entryIds` are the names plugboy gives the entries (`.` normalized to the
+* package directory name). Entry chunks it does not name keep the bundle's order,
+* after the named ones.
+*/
+function entryChunksInDeclaredOrder(graph, entryIds = []) {
+	const rank = (node) => {
+		const index = entryIds.indexOf(node.name);
+		return index === -1 ? entryIds.length : index;
+	};
+	return [...graph].filter(([, node]) => node.isEntry).map(([fileName, node], position) => ({
+		fileName,
+		node,
+		position
+	})).sort((a, b) => rank(a.node) - rank(b.node) || a.position - b.position).map(({ fileName }) => fileName);
+}
+/**
+* Chunk file names in load order, starting from `roots`.
+*
+* Each chunk appears once, after every chunk it imports statically. Chunks
+* reached only through `import()` follow all of those.
+*/
+function orderChunks(graph, roots, options = {}) {
+	const visited = /* @__PURE__ */ new Set();
+	const ordered = [];
+	const dynamic = /* @__PURE__ */ new Set();
+	const walk = (fileName) => {
+		if (visited.has(fileName)) return;
+		visited.add(fileName);
+		const node = graph.get(fileName);
+		if (!node) return;
+		for (const imported of node.imports) walk(imported);
+		for (const imported of node.dynamicImports) dynamic.add(imported);
+		ordered.push(fileName);
+	};
+	for (const root of roots) walk(root);
+	for (const fileName of dynamic) walk(fileName);
+	if (options.includeUnreached) for (const fileName of graph.keys()) walk(fileName);
+	return ordered;
+}
+/**
+* Every chunk of the package in load order: the entries as declared, then what
+* they import dynamically, then anything left over.
+*/
+function orderPackageChunks(graph, entryIds) {
+	return orderChunks(graph, entryChunksInDeclaredOrder(graph, entryIds), { includeUnreached: true });
+}
+//#endregion
 //#region src/workspace/plugins/assemble-entry-css.ts
+/**
+* Plugin that builds every stylesheet plugboy declares — `./<entry>.css` for each
+* `css: true` entry — from the per-chunk stylesheets the build emits, in the
+* order they load.
+*
+* plugboy runs tsdown with `css.splitting` on (see `resolveCssOptions`), which
+* emits one stylesheet per output *chunk*. Neither that nor tsdown's single-file
+* merge matches what plugboy publishes:
+*
+* - tsdown's merge concatenates the chunks in bundle order — entries first,
+*   shared chunks after. A package that composes from a shared base style then
+*   ships the base *after* the rules built on it, and the base wins.
+* - Per-chunk stylesheets are named after chunks. CSS reached from several
+*   entries lands in a shared chunk under a hashed name no export points at, and
+*   an entry whose CSS comes only from there gets no stylesheet at all.
+*
+* So each declared stylesheet is rebuilt here, with the chunks ordered as Vite
+* orders them for `build.cssCodeSplit: false` (`orderChunks`): static imports
+* before their importer, dynamically imported chunks after. Nothing is left for a
+* dynamic `import()` to load, since without `css.inject` the JavaScript imports no
+* stylesheet at all.
+*
+* - **One CSS entry**: the package publishes one stylesheet, so it gets the CSS of
+*   every chunk — the same content tsdown's merge would have produced, in
+*   dependency order. It is written under `css.fileName` when one is set.
+* - **Several**: each gets its own CSS and that of every chunk it reaches. CSS
+*   shared between entries is duplicated into each, which is what makes a single
+*   `./<entry>.css` import complete.
+*
+* The per-chunk stylesheets that were folded in are deleted, since nothing
+* exports them.
+*
+* The chunk graph has to be captured in `generateBundle`, because it is gone by
+* the time the stylesheets exist: a chunk holding nothing but CSS is dropped once
+* tsdown's CSS pipeline (a *post* plugin, so it runs after this hook) has emitted
+* its stylesheet, and its importers' `imports` are emptied along with it. By
+* `writeBundle` the shared chunk is neither in the bundle nor on disk — only its
+* orphaned stylesheet is.
+*
+* Nothing is assembled when tsdown merged the stylesheet itself (`splitting` off,
+* declared explicitly), or with `css.inject`, where the JavaScript imports the
+* per-chunk stylesheets by name.
+*/
 function createAssembleEntryCssPlugin(workspace) {
-	/** Chunk file name -> its identity and static imports, as of `generateBundle`. */
-	const graph = /* @__PURE__ */ new Map();
+	let graph = /* @__PURE__ */ new Map();
 	return definePlugin({
 		name: "plugboy-assemble-entry-css",
 		buildStart() {
-			graph.clear();
+			graph = /* @__PURE__ */ new Map();
 		},
 		generateBundle(_options, bundle) {
-			for (const chunk of Object.values(bundle)) {
-				if (chunk.type !== "chunk") continue;
-				graph.set(chunk.fileName, {
-					name: chunk.name,
-					isEntry: chunk.isEntry,
-					imports: [...chunk.imports]
-				});
-			}
+			graph = captureChunkGraph(bundle);
 		},
 		async writeBundle(options, bundle) {
 			const { dir } = options;
 			if (!dir) return;
-			if (workspace.cssOptions?.inject) return;
+			const { cssOptions } = workspace;
+			if (!cssOptions?.splitting || cssOptions.inject) return;
 			const targets = declaredStylesheets(workspace);
 			if (!targets.size) return;
 			const emitted = new Set(Object.values(bundle).filter((chunk) => chunk.type === "asset" && chunk.fileName.endsWith(".css")).map((chunk) => chunk.fileName));
 			if (!emitted.size) return;
-			/** The stylesheet a chunk owns, if the build emitted one. */
-			const cssOf = (fileName) => {
-				const css = toCssFileName(fileName);
-				return css !== fileName && emitted.has(css) ? css : void 0;
-			};
-			/** Stylesheets an entry needs, dependencies first, each listed once. */
-			const collect = (entryFileName) => {
-				const visited = /* @__PURE__ */ new Set();
+			/** The stylesheets of `chunks`, in the same order, each listed once. */
+			const stylesheetsOf = (chunks) => {
 				const ordered = [];
-				const walk = (fileName) => {
-					if (visited.has(fileName)) return;
-					visited.add(fileName);
-					const node = graph.get(fileName);
-					if (!node) return;
-					for (const imported of node.imports) walk(imported);
-					const css = cssOf(fileName);
-					if (css && !ordered.includes(css)) ordered.push(css);
-				};
-				walk(entryFileName);
+				for (const fileName of chunks) {
+					const css = toCssFileName(fileName);
+					if (css === fileName || !emitted.has(css)) continue;
+					if (!ordered.includes(css)) ordered.push(css);
+				}
 				return ordered;
 			};
-			const folded = /* @__PURE__ */ new Set();
-			await Promise.all([...graph].map(async ([fileName, node]) => {
-				if (!node.isEntry) return;
+			/** Output file name -> the stylesheets it is built from. */
+			const plan = /* @__PURE__ */ new Map();
+			const packageStylesheet = assembledStylesheetName(workspace);
+			if (packageStylesheet) plan.set(packageStylesheet, stylesheetsOf(orderPackageChunks(graph, Object.keys(workspace.entry))));
+			else for (const [fileName, node] of graph) {
+				if (!node.isEntry) continue;
 				const target = `${node.name}.css`;
-				if (!targets.has(target)) return;
-				const sources = collect(fileName);
-				if (!sources.length) return;
+				if (!targets.has(target)) continue;
+				plan.set(target, stylesheetsOf(orderChunks(graph, [fileName])));
+			}
+			const outputs = new Set(plan.keys());
+			const folded = /* @__PURE__ */ new Set();
+			const assembled = await Promise.all([...plan].map(async ([target, sources]) => {
+				if (!sources.length) return void 0;
 				sources.forEach((source) => folded.add(source));
-				if (sources.length === 1 && sources[0] === target) return;
+				if (sources.length === 1 && sources[0] === target) return void 0;
 				const css = (await Promise.all(sources.map((source) => fs$1.readFile(path.join(dir, source), "utf8").catch(() => "")))).filter(Boolean).join("\n");
-				if (!css) return;
-				await fs$1.writeFile(path.join(dir, target), css);
-				folded.add(target);
+				return css ? {
+					target,
+					css
+				} : void 0;
 			}));
-			await Promise.all([...folded].filter((css) => !targets.has(css)).map((css) => fs$1.rm(path.join(dir, css), { force: true })));
+			await Promise.all(assembled.map((output) => output && fs$1.writeFile(path.join(dir, output.target), output.css)));
+			await Promise.all([...folded].filter((css) => !outputs.has(css)).map((css) => fs$1.rm(path.join(dir, css), { force: true })));
 		}
 	});
 }
@@ -1461,8 +1618,10 @@ function createPreserveCssImportsPlugin(workspace) {
 		generateBundle(_options, bundle) {
 			if (!layersByModule.size) return;
 			const sequences = [];
-			for (const chunk of Object.values(bundle)) {
-				if (chunk.type !== "chunk") continue;
+			const ordered = orderPackageChunks(captureChunkGraph(bundle), Object.keys(workspace.entry));
+			for (const fileName of ordered) {
+				const chunk = bundle[fileName];
+				if (chunk?.type !== "chunk") continue;
 				for (const id of chunk.moduleIds) {
 					const names = layersByModule.get(id);
 					if (names) sequences.push(names);
@@ -1669,9 +1828,9 @@ var PlugboyWorkspace = class {
 		];
 		this.hooks = hooks;
 		this.dts = dts;
-		this.cssOptions = css;
 		this.optimizeCSSOptions = optimizeCSS ? resolveOptimizeCSSOptions(optimizeCSS) : false;
 		const entry = {};
+		const cssEntryIds = [];
 		const exports = [{
 			id: `./${PACKAGE_JSON_FILENAME}`,
 			at: `./${PACKAGE_JSON_FILENAME}`
@@ -1685,6 +1844,7 @@ var PlugboyWorkspace = class {
 			const destFullPath = dir.join(dest).value;
 			entry[normalizedId] = src;
 			if (css) {
+				cssEntryIds.push(normalizedId);
 				const cssDest = `./dist/${normalizedId}.css`;
 				exports.push({
 					id: `./${normalizedId}.css`,
@@ -1716,6 +1876,7 @@ var PlugboyWorkspace = class {
 		});
 		this.entry = entry;
 		this.exports = exports;
+		this.cssOptions = resolveCssOptions(css, cssEntryIds);
 		this.builder = new Builder(this);
 	}
 	clean(withDepsAndCache) {
@@ -1772,11 +1933,8 @@ var PlugboyWorkspace = class {
 		cloned.type = cloned.type || "module";
 		await this.hooks.preparePackageJSON(json, this);
 		const sorted = sortPackageJson(cloned);
-		const toStr = JSON.stringify(sorted, null, 2);
-		if (originalJSONString !== toStr) {
-			await writeFileAtomic(this.dir.join(PACKAGE_JSON_FILENAME).value, toStr);
-			this._json = sorted;
-		}
+		if (originalJSONString !== JSON.stringify(sorted)) await writeFileAtomic(this.dir.join(PACKAGE_JSON_FILENAME).value, `${JSON.stringify(sorted, null, 2)}\n`);
+		this._json = sorted;
 		return sorted;
 	}
 	getStubLinks() {
@@ -1960,7 +2118,7 @@ async function generateWorkspace(workspaceName, cwd = process.cwd()) {
 		process.exit(1);
 	}
 	await fs$1.mkdir(workspaceDir);
-	await fs$1.writeFile(path.join(workspaceDir, "package.json"), JSON.stringify(json, null, 2));
+	await fs$1.writeFile(path.join(workspaceDir, "package.json"), `${JSON.stringify(json, null, 2)}\n`);
 	await fs$1.writeFile(path.join(workspaceDir, "README.md"), config.readme(json));
 	if (withGenSource) {
 		const srcDir = path.join(workspaceDir, "src");
@@ -1970,7 +2128,7 @@ async function generateWorkspace(workspaceName, cwd = process.cwd()) {
 		await fs$1.writeFile(path.join(srcDir, "index.ts"), indexCode);
 		await fs$1.writeFile(path.join(srcDir, `${workspaceName}.ts`), modCode);
 		const { tsconfig } = config;
-		if (tsconfig) await fs$1.writeFile(path.join(workspaceDir, "tsconfig.json"), JSON.stringify(tsconfig, null, 2));
+		if (tsconfig) await fs$1.writeFile(path.join(workspaceDir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`);
 		const configFileCode = `${`
 import { defineWorkspaceConfig } from '@fastkit/plugboy';
 
@@ -1985,6 +2143,6 @@ export default defineWorkspaceConfig({
 	}
 }
 //#endregion
-export { resolveOptimizeCSSOptions as $, resolveRawExposeEntriesSettings as A, resolveBundledConfigOutputFile as B, findProjectPlugin as C, loadProjectConfig as D, isProjectPackageJson as E, getFilename as F, mergeChunkAddons as G, stripDanglingDTSSourceMaps as H, isFileNotFoundException as I, isPromise as J, mergeExternals as K, pathExists as L, findConfig as M, findFile as N, resolveUserProjectConfig as O, getDirname as P, WORKSPACE_REQUIRED_FIELDS as Q, rmrf as R, extractProjectPlugins as S, defineProjectConfig as T, exitHook as U, DANGLING_DTS_SOURCE_MAP_RE as V, collectExternalStringPrefixes as W, PROJECT_REQUIRED_FIELDS as X, resolveListable as Y, TSDOWN_SYNC_OPTIONS as Z, loadWorkspaceConfig as _, syncWorkspacePackageFields as a, resolveUserWorkspaceConfig as b, Builder as c, getWorkspacePackageJson as d, mergeDTSSettingsList as et, Path as f, isWorkspacePackageJson as g, defineWorkspaceConfig as h, getWorkspace as i, createHooksDefaults as it, copyDirSync as j, exposeEntries as k, findWorkspacePackages as l, resolveUserHooks as m, PlugboyWorkspace as n, normalizeDTSPreserveTypeTarget as nt, PlugboyProject as o, buildHooks as p, mergeNoExternals as q, WORKSPACE_PACKAGE_SYNC_FIELDS as r, normalizeDTSSettings as rt, getProject as s, generateWorkspace as t, normalizeDTSPreserveTypeSettings as tt, getProjectPackageJson as u, resolveRawWorkspaceEntries as v, resolveUserPluginOption as w, definePlugin as x, resolveRawWorkspaceEntry as y, writeFileAtomic as z };
+export { resolveListable as $, isProjectPackageJson as A, isFileNotFoundException as B, resolveRawWorkspaceEntry as C, findProjectPlugin as D, extractProjectPlugins as E, copyDirSync as F, DANGLING_DTS_SOURCE_MAP_RE as G, rmrf as H, findConfig as I, collectExternalStringPrefixes as J, stripDanglingDTSSourceMaps as K, findFile as L, resolveUserProjectConfig as M, exposeEntries as N, resolveUserPluginOption as O, resolveRawExposeEntriesSettings as P, isPromise as Q, getDirname as R, resolveRawWorkspaceEntries as S, definePlugin as T, writeFileAtomic as U, pathExists as V, resolveBundledConfigOutputFile as W, mergeExternals as X, mergeChunkAddons as Y, mergeNoExternals as Z, buildHooks as _, syncWorkspacePackageFields as a, normalizeDTSPreserveTypeSettings as at, isWorkspacePackageJson as b, orderChunks as c, createHooksDefaults as ct, getProject as d, PROJECT_REQUIRED_FIELDS as et, Builder as f, Path as g, getWorkspacePackageJson as h, getWorkspace as i, mergeDTSSettingsList as it, loadProjectConfig as j, defineProjectConfig as k, orderPackageChunks as l, getProjectPackageJson as m, PlugboyWorkspace as n, WORKSPACE_REQUIRED_FIELDS as nt, captureChunkGraph as o, normalizeDTSPreserveTypeTarget as ot, findWorkspacePackages as p, exitHook as q, WORKSPACE_PACKAGE_SYNC_FIELDS as r, resolveOptimizeCSSOptions as rt, entryChunksInDeclaredOrder as s, normalizeDTSSettings as st, generateWorkspace as t, TSDOWN_SYNC_OPTIONS as tt, PlugboyProject as u, resolveUserHooks as v, resolveUserWorkspaceConfig as w, loadWorkspaceConfig as x, defineWorkspaceConfig as y, getFilename as z };
 
-//# sourceMappingURL=workspace-Dngfi1p6.mjs.map
+//# sourceMappingURL=workspace-DdhCZjQE.mjs.map