pattern-dump 0.1.0-alpha.3 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.1.0-alpha.4
+
+Fixes found while moving a third PatternLab styleguide (CTS) to Pattern Dump with hTWOo consumed only as
+pattern packages: its templates, data, scripts and CSS all come from `@n8d/htwoo-patterns` and
+`@n8d/htwoo-core`, and the project compiles only its own SCSS.
+
+### Added
+
+- `styles: false` on a package reference leaves that package's stylesheets out, for a project that
+  compiles them itself; its templates, data, themes, scripts and assets are still used. It also works
+  for a package that another brings in as a peer: name the peer with the option.
+- `themes.dir` is optional: `themes: { default: "<name>" }` alone makes one of your packages' themes the
+  one previews start with. `pd dev` warns when the default matches no theme.
+- A component or variant `.json` that does not parse is reported as a `DATA_INVALID` diagnostic, with
+  the file and, where the parser gives one, the line and column, instead of being dropped silently. An
+  invalid variant file no longer fails the whole render.
+
+### Fixed
+
+- A class belongs to the rule that defines it (the class on its own, such as `.card` or `.card:hover`),
+  not to every rule that mentions it. A project rule that restyles a package class in context
+  (`.tile .hoo-radio`) took the class over, so the package component's CSS was never linked where the
+  class was used.
+- A rule repeated after a different one (A, B, A) keeps its last position in the base layer and in
+  component CSS, as the browser applies it. The first copy was kept, so B won.
+- Included partials keep the caller's data frame, as in stock Handlebars: `@root` is the page's data,
+  and `{{#if @partial-block}}` sees the block of a block call.
+- A configured `styles.entry` list compiles in the order given. It was sorted, which could change the
+  cascade.
+- SCSS can load an installed package by its bare name (`@use '@scope/pkg/…'`) or a `pkg:` URL, without
+  `SASS_PATH`.
+- A data variant reached by its own id (`/preview/atoms/chip~danger`) or included by its handle
+  (`{{> "atoms-chip~danger"}}`) renders on top of its base component's data, as `?variant=` already did.
+- `pd build` copies assets as `pd dev` serves them: where two asset folders share a name, the first one
+  (the project's) wins and the other is left out and reported. A package's `images/` used to overwrite
+  the project's in the snapshot. `pd dev` warns about such folders at startup.
+
 ## 0.1.0-alpha.3
 
 Fixes found while moving a second PatternLab styleguide (n8d) to Pattern Dump.

package/README.md

@@ -4,7 +4,7 @@ A workbench for HTML and CSS design systems, and a successor to PatternLab. Writ
 Handlebars templates with SCSS, data and Markdown docs; Pattern Dump shows them live, checks them, maps
 how they relate, and publishes the result as a static site.
 
-> **Alpha (0.1.0-alpha.3).** Published under the `alpha` tag. Options and file conventions can still change
+> **Alpha (0.1.0-alpha.4).** Published under the `alpha` tag. Options and file conventions can still change
 > between releases.
 
 ## Requirements

package/dist/chunks/{chunk-3WZHFYHZ.js → chunk-NXGPZL5L.js}

@@ -19,7 +19,7 @@ var SHAPE = {
       switch: { values: ["attribute", "stylesheet"] },
       swatch: { keys: { slots: "strings" }, required: ["slots"] }
     },
-    required: ["dir", "default"]
+    required: ["default"]
   },
   assets: {
     keys: {
@@ -107,8 +107,8 @@ function checkValue(value, rule, at, problems) {
     return;
   }
   if (rule === "packages") {
-    const ok = Array.isArray(value) && value.every((p) => typeof p === "string" || isObject(p) && typeof p.name === "string" && (p.exclude === void 0 || isStrings(p.exclude)));
-    if (!ok) fail(`a list of package names or { name, exclude } objects`);
+    const ok = Array.isArray(value) && value.every((p) => typeof p === "string" || isObject(p) && typeof p.name === "string" && (p.exclude === void 0 || isStrings(p.exclude)) && (p.styles === void 0 || typeof p.styles === "boolean"));
+    if (!ok) fail(`a list of package names or { name, exclude, styles } objects`);
     return;
   }
   if (rule === "logo") {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   defineConfig
-} from "./chunks/chunk-3WZHFYHZ.js";
+} from "./chunks/chunk-NXGPZL5L.js";
 export {
   defineConfig
 };

package/dist/pd.js

@@ -2,7 +2,7 @@
 import {
   ConfigError,
   validateConfig
-} from "./chunks/chunk-3WZHFYHZ.js";
+} from "./chunks/chunk-NXGPZL5L.js";
 
 // packages/discovery/src/index.ts
 import { readdir } from "node:fs/promises";
@@ -420,6 +420,7 @@ function _plainPre(code) {
 import { HtmlValidate } from "html-validate";
 import Handlebars from "handlebars";
 import { readFile } from "node:fs/promises";
+import { basename as basename2 } from "node:path";
 var htmlValidator = new HtmlValidate({
   rules: {
     "element-permitted-content": "error",
@@ -441,6 +442,36 @@ function deepMerge(target, ...sources) {
   return target;
 }
 var safePart = (n) => n.replace(/[^a-zA-Z0-9-]/g, "-").toLowerCase();
+function jsonErrorPosition(reason, text) {
+  const lineColumn = /line (\d+) column (\d+)/.exec(reason);
+  if (lineColumn) return { line: Number(lineColumn[1]), column: Number(lineColumn[2]) };
+  const position = /position (\d+)/.exec(reason);
+  if (!position) return {};
+  const lines = text.slice(0, Number(position[1])).split("\n");
+  return { line: lines.length, column: lines[lines.length - 1].length + 1 };
+}
+async function readDataFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf-8");
+  } catch {
+    return {};
+  }
+  try {
+    return { data: JSON.parse(text) };
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    return {
+      diagnostic: {
+        kind: "DATA_INVALID",
+        source: "render",
+        severity: "error",
+        message: `${basename2(path)} is not valid JSON (${reason}); its data was not used`,
+        location: { file: path, ...jsonErrorPosition(reason, text) }
+      }
+    };
+  }
+}
 function registerHelpers(env, mintId, getLastId, projectHelpers, helperRegistrars) {
   env.registerHelper("id", (name) => mintId(name));
   env.registerHelper("getId", (name) => mintId(name));
@@ -521,30 +552,34 @@ var createRenderer = (options) => {
       discoveryMap ??= maps.discoveryMap;
       handleMap ??= maps.handleMap;
     }
-    const entry = discoveryMap.get(input.component);
-    if (!entry) throw new Error(`[renderer] Component not found: "${input.component}"`);
+    let componentId = input.component;
+    let variant = input.variant;
+    const tilde = componentId.indexOf("~");
+    if (tilde > 0 && !variant && discoveryMap.has(componentId.slice(0, tilde))) {
+      variant = componentId.slice(tilde + 1);
+      componentId = componentId.slice(0, tilde);
+    }
+    const entry = discoveryMap.get(componentId);
+    if (!entry) throw new Error(`[renderer] Component not found: "${componentId}"`);
     let templateHbsPath = entry.hbsPath;
     let variantJsonPath;
-    if (input.variant) {
-      const variantEntry = discoveryMap.get(`${input.component}~${input.variant}`);
-      if (!variantEntry) throw new Error(`[renderer] Variant not found: "${input.component}~${input.variant}"`);
+    if (variant) {
+      const variantEntry = discoveryMap.get(`${componentId}~${variant}`);
+      if (!variantEntry) throw new Error(`[renderer] Variant not found: "${componentId}~${variant}"`);
       if (variantEntry.ownMarkup && variantEntry.hbsPath) {
         templateHbsPath = variantEntry.hbsPath;
       }
       variantJsonPath = variantEntry.jsonPath;
     }
     const templateSrc = templateHbsPath ? await readFile(templateHbsPath, "utf-8") : "";
-    let defaultData = {};
-    if (entry.jsonPath) {
-      try {
-        defaultData = JSON.parse(await readFile(entry.jsonPath, "utf-8"));
-      } catch {
-      }
-    }
-    let variantData;
-    if (variantJsonPath) {
-      variantData = JSON.parse(await readFile(variantJsonPath, "utf-8"));
-    }
+    const dataDiagnostics = /* @__PURE__ */ new Map();
+    const readData = async (path) => {
+      const { data: data2, diagnostic } = await readDataFile(path);
+      if (diagnostic) dataDiagnostics.set(path, diagnostic);
+      return data2;
+    };
+    const defaultData = (entry.jsonPath ? await readData(entry.jsonPath) : void 0) ?? {};
+    const variantData = variantJsonPath ? await readData(variantJsonPath) : void 0;
     const data = deepMerge(
       structuredClone(options.globalData ?? {}),
       defaultData,
@@ -552,7 +587,7 @@ var createRenderer = (options) => {
       input.data
     );
     const env = Handlebars.create();
-    const componentSlug = safePart(input.component.replace(/[\\/]/g, "-"));
+    const componentSlug = safePart(componentId.replace(/[\\/]/g, "-"));
     let currentBase = `pd-${componentSlug}`;
     const idCache = /* @__PURE__ */ new Map();
     let lastMintedId = "";
@@ -572,13 +607,12 @@ var createRenderer = (options) => {
       if (!compEntry?.hbsPath) continue;
       try {
         const partialSrc = await readFile(compEntry.hbsPath, "utf-8");
-        let childDefaults = {};
-        if (compEntry.jsonPath) {
-          try {
-            childDefaults = JSON.parse(await readFile(compEntry.jsonPath, "utf-8"));
-          } catch {
-          }
-        }
+        const childData = compEntry.jsonPath ? await readDataFile(compEntry.jsonPath) : {};
+        const childDataPath = compEntry.jsonPath;
+        const variantTilde = compId.indexOf("~");
+        const baseJsonPath = variantTilde > 0 ? discoveryMap.get(compId.slice(0, variantTilde))?.jsonPath : void 0;
+        const baseData = baseJsonPath ? await readDataFile(baseJsonPath) : {};
+        const childDefaults = deepMerge(structuredClone(baseData.data ?? {}), childData.data);
         const childTemplate = env.compile(partialSrc);
         const capturedDefaults = childDefaults;
         const partialSlug = safePart(compId.replace(/[\\/]/g, "-"));
@@ -595,13 +629,16 @@ var createRenderer = (options) => {
               invocationCounters.set(counterKey, n + 1);
               thisBase = n === 0 ? currentBase : `pd-${partialSlug}-${n}`;
             }
+            if (childData.diagnostic && childDataPath) dataDiagnostics.set(childDataPath, childData.diagnostic);
+            if (baseData.diagnostic && baseJsonPath) dataDiagnostics.set(baseJsonPath, baseData.diagnostic);
             const savedBase = currentBase;
             currentBase = thisBase;
             const merged = deepMerge(
               structuredClone(capturedDefaults),
               context != null && typeof context === "object" && !Array.isArray(context) ? context : {}
             );
-            const runtime = opts?.fn ? { partials: { ...env.partials, "@partial-block": opts.fn } } : void 0;
+            const data2 = { ...opts?.data, ...opts?.fn ? { "partial-block": opts.fn } : {} };
+            const runtime = opts?.fn ? { data: data2, partials: { ...env.partials, "@partial-block": opts.fn } } : { data: data2 };
             const result = childTemplate(merged, runtime);
             currentBase = savedBase;
             return result;
@@ -613,7 +650,7 @@ var createRenderer = (options) => {
     const html = env.compile(templateSrc)(data, {
       partials: { ...env.partials, "@partial-block": () => "" }
     });
-    const diagnostics = [];
+    const diagnostics = [...dataDiagnostics.values()];
     const htmlReport = htmlValidator.validateStringSync(html);
     for (const result of htmlReport.results) {
       for (const msg of result.messages) {
@@ -662,7 +699,7 @@ var createRenderer = (options) => {
       }
     } catch {
     }
-    const meta = diagnostics.length > 0 ? { componentId: input.component, variant: input.variant, diagnostics } : void 0;
+    const meta = diagnostics.length > 0 ? { componentId, variant, diagnostics } : void 0;
     return { html, document: buildDocument(html, options), ...meta ? { meta } : {} };
   };
 };
@@ -685,9 +722,26 @@ import * as sass from "sass";
 import postcss from "postcss";
 import autoprefixer from "autoprefixer";
 import { build as esbuildBuild } from "esbuild";
+import { existsSync } from "node:fs";
 import { readdir as readdir2 } from "node:fs/promises";
-import { join as join2, extname, resolve } from "node:path";
+import { dirname as dirname2, join as join2, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+var packageOptionsCache = /* @__PURE__ */ new Map();
+function sassPackageOptions(entryFile) {
+  const start = dirname2(resolve(entryFile));
+  let options = packageOptionsCache.get(start);
+  if (!options) {
+    const loadPaths = [];
+    for (let dir = start; ; dir = dirname2(dir)) {
+      const modules = join2(dir, "node_modules");
+      if (existsSync(modules)) loadPaths.push(modules);
+      if (dirname2(dir) === dir) break;
+    }
+    options = { loadPaths, importers: [new sass.NodePackageImporter(start)] };
+    packageOptionsCache.set(start, options);
+  }
+  return options;
+}
 async function collectScssFiles(dir) {
   const files = [];
   async function walk(current) {
@@ -710,7 +764,7 @@ async function collectScssFiles(dir) {
   return files;
 }
 async function compileSassFileWithDeps(filePath) {
-  const result = sass.compile(filePath);
+  const result = sass.compile(filePath, sassPackageOptions(filePath));
   const processed = await postcss([autoprefixer]).process(result.css, { from: void 0 });
   const deps = result.loadedUrls.filter((u) => u.protocol === "file:").map((u) => fileURLToPath(u)).filter((p) => resolve(p) !== resolve(filePath));
   return { css: processed.css, deps };
@@ -1182,7 +1236,7 @@ async function loadGlobalData(dataDirs) {
 
 // packages/dev-server/src/surfacing.ts
 import { mkdir, readFile as readFile5, writeFile } from "node:fs/promises";
-import { join as join7, relative as relative3 } from "node:path";
+import { join as join8, relative as relative3 } from "node:path";
 
 // packages/dev-server/src/flattening.ts
 import { parse as parseHtml } from "node-html-parser";
@@ -1428,11 +1482,108 @@ function pdScratchDir(root) {
   return join5(tmpdir(), "pattern-dump", key);
 }
 
+// packages/dev-server/src/server-config.ts
+import { basename as basename3, join as join6, resolve as resolve4 } from "node:path";
+function shadowedAssetRoots(assetRoots) {
+  const first = /* @__PURE__ */ new Map();
+  const shadowed = [];
+  for (const root of assetRoots) {
+    const by = first.get(basename3(root));
+    if (by === void 0) first.set(basename3(root), root);
+    else if (by !== root) shadowed.push({ root, by });
+  }
+  return shadowed;
+}
+var DEFAULT_SWATCH_SLOTS = ["--bodyBackground", "--themePrimary", "--accent"];
+function resolveServerConfig(config, cwd, opts = {}, packages = []) {
+  const port2 = opts.port ?? Number(process.env["PD_PORT"] ?? 4e3);
+  const wsPort = opts.wsPort ?? Number(process.env["PD_WS_PORT"] ?? port2 + 1);
+  const patternsDir = resolve4(cwd, config.patternsDir);
+  const stylesDir = resolve4(cwd, config.styles.dir);
+  const stylesEntries = config.styles.entry ? (Array.isArray(config.styles.entry) ? config.styles.entry : [config.styles.entry]).map((e) => resolve4(stylesDir, e)) : void 0;
+  const inPackage = (p, rel) => join6(p.dir, rel);
+  const asList = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
+  const patternRoots = [
+    { dir: patternsDir, ...config.exclude?.length ? { exclude: config.exclude } : {} },
+    ...packages.filter((p) => p.manifest.patterns).map((p) => ({
+      dir: inPackage(p, p.manifest.patterns),
+      source: p.name,
+      ...p.exclude.length ? { exclude: p.exclude } : {}
+    }))
+  ];
+  const styleRoots = [
+    { dir: stylesDir, entries: stylesEntries, base: config.documentBase },
+    ...packages.filter((p) => p.manifest.styles && p.styles).map((p) => {
+      const dir = inPackage(p, p.manifest.styles.dir);
+      const entries = asList(p.manifest.styles.entry).map((e) => resolve4(dir, e));
+      return { dir, entries: entries.length ? entries : void 0, source: p.name, base: p.manifest.styles.documentBase };
+    })
+  ];
+  const themePackages = packages.filter((p) => p.manifest.themes);
+  const themeDirs = [
+    ...config.themes?.dir ? [resolve4(cwd, config.themes.dir)] : [],
+    ...themePackages.map((p) => inPackage(p, p.manifest.themes.dir))
+  ];
+  const switches = [config.themes?.switch, ...themePackages.map((p) => p.manifest.themes.switch)];
+  const themeSwitch = switches.includes("stylesheet") ? "stylesheet" : "attribute";
+  const assetRoots = [
+    ...asList(config.assets?.dir).map((d) => resolve4(cwd, d)),
+    ...packages.flatMap((p) => (p.manifest.assets ?? []).map((a) => inPackage(p, a)))
+  ];
+  const globalScripts = [.../* @__PURE__ */ new Set([
+    ...packages.flatMap((p) => p.manifest.globalScripts ?? []),
+    ...config.globalScripts ?? []
+  ])];
+  const scriptsDirs = [
+    ...config.scriptsDir ? [resolve4(cwd, config.scriptsDir)] : [],
+    ...packages.filter((p) => p.manifest.scripts).map((p) => inPackage(p, p.manifest.scripts))
+  ];
+  const documentBaseEnabled = Array.isArray(config.documentBase) && config.documentBase.length > 0 || packages.some((p) => p.styles && (p.manifest.styles?.documentBase?.length ?? 0) > 0);
+  return {
+    port: port2,
+    wsPort,
+    cwd,
+    config,
+    packages,
+    patternRoots,
+    patternDirs: patternRoots.map((r) => r.dir),
+    styleRoots,
+    dataDirs: [
+      ...packages.filter((p) => p.manifest.data).map((p) => inPackage(p, p.manifest.data)),
+      ...config.dataDir ? [resolve4(cwd, config.dataDir)] : []
+    ],
+    helperPaths: [
+      ...packages.filter((p) => p.manifest.helpers).map((p) => inPackage(p, p.manifest.helpers)),
+      ...config.helpers ? [resolve4(cwd, config.helpers)] : []
+    ],
+    scriptsDirs,
+    patternsDir,
+    stylesDir,
+    stylesEntries,
+    themeDirs,
+    themesDir: themeDirs[0] ?? null,
+    defaultTheme: config.themes?.default ?? themePackages[0]?.manifest.themes?.default,
+    assetRoots,
+    assetRootNames: assetRoots.map((r) => basename3(r)),
+    assetsDir: assetRoots[0] ?? null,
+    assetsCss: config.assets?.css ?? [],
+    scriptsDir: scriptsDirs[0] ?? null,
+    globalScripts,
+    withGlobalScripts: (own) => [.../* @__PURE__ */ new Set([...globalScripts, ...own ?? []])],
+    overviewsEnabled: config.overviews !== false,
+    documentBaseEnabled,
+    themeSwitch,
+    swatchSlots: config.themes?.swatch?.slots ?? DEFAULT_SWATCH_SLOTS,
+    packageSwatchSlots: DEFAULT_SWATCH_SLOTS
+  };
+}
+
 // packages/dev-server/src/style-index.ts
-import { dirname as dirname2, join as join6, relative as relative2, resolve as resolve4 } from "node:path";
-import { existsSync } from "node:fs";
+import { dirname as dirname3, join as join7, relative as relative2, resolve as resolve5 } from "node:path";
+import { existsSync as existsSync2 } from "node:fs";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import postcss3 from "postcss";
+import selectorParser from "postcss-selector-parser";
 import { SourceMapConsumer } from "source-map";
 import * as sass2 from "sass";
 
@@ -1444,6 +1595,10 @@ function cssNodeText(node) {
   const text = node.toString();
   return node.type === "atrule" && !node.nodes ? `${text};` : text;
 }
+function addLastOccurrence(bucket, chunk) {
+  bucket.delete(chunk);
+  bucket.add(chunk);
+}
 function joinCssChunks(chunks) {
   const charset = [];
   const imports = [];
@@ -1455,6 +1610,33 @@ function joinCssChunks(chunks) {
   }
   return [...charset.slice(0, 1), ...imports, ...rest].join("\n");
 }
+var selectorClassCache = /* @__PURE__ */ new Map();
+function selectorClasses(selector) {
+  const cached = selectorClassCache.get(selector);
+  if (cached) return cached;
+  const defines = /* @__PURE__ */ new Set();
+  const mentions = /* @__PURE__ */ new Set();
+  try {
+    selectorParser((list) => {
+      list.each((complex) => {
+        const contextFree = !complex.some((node) => node.type === "combinator");
+        complex.walkClasses((cls) => {
+          (contextFree && cls.parent === complex ? defines : mentions).add(cls.value);
+        });
+      });
+    }).processSync(selector);
+  } catch {
+    for (const m of selector.matchAll(/\.([\w-]+)/g)) defines.add(m[1]);
+  }
+  for (const name of defines) mentions.delete(name);
+  const result = { defines: [...defines], mentions: [...mentions] };
+  selectorClassCache.set(selector, result);
+  return result;
+}
+function claimRank(owner, defines) {
+  return (defines ? 2 : 0) + (owner === "__base__" ? 0 : 1);
+}
+var indexRanks = /* @__PURE__ */ new WeakMap();
 var strippedIdCache = /* @__PURE__ */ new WeakMap();
 function strippedIds(componentIds) {
   let map = strippedIdCache.get(componentIds);
@@ -1507,55 +1689,72 @@ function missingDocumentBase(stylesDir, base2) {
   return (base2 ?? []).filter((entry) => {
     const e = normalizeBaseEntry(entry);
     if (e === "") return false;
-    const dir = dirname2(join6(stylesDir, e));
+    const dir = dirname3(join7(stylesDir, e));
     const name = e.split("/").pop();
-    return ![join6(stylesDir, e), join6(dir, `${name}.scss`), join6(dir, `_${name}.scss`)].some(existsSync);
+    return ![join7(stylesDir, e), join7(dir, `${name}.scss`), join7(dir, `_${name}.scss`)].some(existsSync2);
   });
 }
 function extractClassesFromCompiled(consumer, root, entryFile, stylesDir, componentIds) {
   const classMap = /* @__PURE__ */ new Map();
   const baseModules = /* @__PURE__ */ new Map();
+  const ranks = /* @__PURE__ */ new Map();
   root.walkRules((rule) => {
-    const classMatches = rule.selector.match(/\.([\w-]+)/g);
-    if (!classMatches) return;
+    const { defines, mentions } = selectorClasses(rule.selector);
+    if (defines.length === 0 && mentions.length === 0) return;
     const pos = rule.source?.start;
     if (!pos) return;
     const original = consumer.originalPositionFor({ line: pos.line, column: pos.column - 1 });
     if (!original.source) return;
-    const originPath = original.source.startsWith("file://") ? fileURLToPath2(original.source) : resolve4(dirname2(entryFile), original.source);
+    const originPath = original.source.startsWith("file://") ? fileURLToPath2(original.source) : resolve5(dirname3(entryFile), original.source);
     const resolved = resolveScssToComponent(originPath, stylesDir, componentIds);
     const owner = resolved ?? "__base__";
     const modulePath = resolved === null ? resolveSharedModulePath(originPath, stylesDir, true) : null;
-    for (const cls of classMatches) {
-      const name = cls.slice(1);
-      if (!classMap.has(name)) classMap.set(name, owner);
-      if (modulePath && classMap.get(name) === "__base__" && !baseModules.has(name)) {
+    const claim = (name, rank) => {
+      const prev = ranks.get(name);
+      if (prev === void 0 || rank > prev) {
+        classMap.set(name, owner);
+        ranks.set(name, rank);
+        if (modulePath && owner === "__base__") baseModules.set(name, modulePath);
+        else baseModules.delete(name);
+      } else if (modulePath && owner === "__base__" && classMap.get(name) === "__base__" && !baseModules.has(name)) {
         baseModules.set(name, modulePath);
       }
-    }
+    };
+    for (const name of defines) claim(name, claimRank(owner, true));
+    for (const name of mentions) claim(name, claimRank(owner, false));
   });
-  return { classMap, baseModules };
+  return { classMap, baseModules, ranks };
 }
 async function attributeClassesFromFile(entryFile, stylesDir, componentIds) {
   try {
-    const compiled = sass2.compile(entryFile, { sourceMap: true });
+    const compiled = sass2.compile(entryFile, { sourceMap: true, ...sassPackageOptions(entryFile) });
     if (!compiled.sourceMap) return null;
     const consumer = new SourceMapConsumer(compiled.sourceMap);
     const root = postcss3.parse(compiled.css);
-    const { classMap } = extractClassesFromCompiled(consumer, root, entryFile, stylesDir, componentIds);
-    return classMap;
+    const { classMap, ranks } = extractClassesFromCompiled(consumer, root, entryFile, stylesDir, componentIds);
+    return { classMap, ranks };
   } catch {
     return null;
   }
 }
 async function patchClassOwnerIndex(entryFile, changedCompId, stylesDir, componentIds, index) {
+  const ranks = indexRanks.get(index);
   for (const [cls, owner] of index) {
-    if (owner === changedCompId) index.delete(cls);
+    if (owner === changedCompId) {
+      index.delete(cls);
+      ranks?.delete(cls);
+    }
   }
   const fresh = await attributeClassesFromFile(entryFile, stylesDir, componentIds);
   if (!fresh) return false;
-  for (const [name, owner] of fresh) {
-    if (owner === changedCompId && !index.has(name)) index.set(name, owner);
+  for (const [name, owner] of fresh.classMap) {
+    if (owner !== changedCompId) continue;
+    const rank = fresh.ranks.get(name) ?? 0;
+    const prev = ranks?.get(name);
+    if (!index.has(name) || prev !== void 0 && rank > prev) {
+      index.set(name, owner);
+      ranks?.set(name, rank);
+    }
   }
   return true;
 }
@@ -1563,6 +1762,8 @@ async function buildAllStyleData(roots, componentIds, entryOverride) {
   if (verboseTiming) console.time("[dev-server:timing] full classOwnerIndex build");
   const styleUsesModules = /* @__PURE__ */ new Map();
   const classIndex = /* @__PURE__ */ new Map();
+  const classRanks = /* @__PURE__ */ new Map();
+  indexRanks.set(classIndex, classRanks);
   const baseProvenance = /* @__PURE__ */ new Map();
   const componentCssBuckets = /* @__PURE__ */ new Map();
   const baseCssByRoot = [];
@@ -1580,12 +1781,11 @@ async function buildAllStyleData(roots, componentIds, entryOverride) {
       entryFiles = [...styleRoot.entries];
     } else {
       try {
-        entryFiles = await collectScssFiles(stylesDir);
+        entryFiles = (await collectScssFiles(stylesDir)).sort();
       } catch {
         entryFiles = [];
       }
     }
-    entryFiles.sort();
     for (const entryFile of entryFiles) {
       let originPathFor2 = function(node) {
         const pos = node.source?.start;
@@ -1595,18 +1795,18 @@ async function buildAllStyleData(roots, componentIds, entryOverride) {
           column: pos.column - 1
         });
         if (!original.source) return null;
-        return original.source.startsWith("file://") ? fileURLToPath2(original.source) : resolve4(dirname2(entryFile), original.source);
+        return original.source.startsWith("file://") ? fileURLToPath2(original.source) : resolve5(dirname3(entryFile), original.source);
       };
       var originPathFor = originPathFor2;
       const compOwner = resolveScssToComponent(entryFile, stylesDir, componentIds);
       let compiled;
       try {
-        compiled = sass2.compile(entryFile, { sourceMap: true });
+        compiled = sass2.compile(entryFile, { sourceMap: true, ...sassPackageOptions(entryFile) });
       } catch {
         continue;
       }
       if (compOwner) {
-        const deps = compiled.loadedUrls.filter((u) => u.protocol === "file:").map((u) => fileURLToPath2(u)).filter((p) => resolve4(p) !== resolve4(entryFile));
+        const deps = compiled.loadedUrls.filter((u) => u.protocol === "file:").map((u) => fileURLToPath2(u)).filter((p) => resolve5(p) !== resolve5(entryFile));
         for (const dep of deps) {
           const depComp = resolveScssToComponent(dep, stylesDir, componentIds);
           if (depComp !== null && depComp !== compOwner) {
@@ -1641,7 +1841,7 @@ async function buildAllStyleData(roots, componentIds, entryOverride) {
         const nodeText = cssNodeText(node);
         const owner = inBase(originPath) ? "__base__" : resolveScssToComponent(originPath, stylesDir, componentIds) ?? "__base__";
         if (owner === "__base__") {
-          baseCssBucket.add(nodeText);
+          addLastOccurrence(baseCssBucket, nodeText);
           if (reportOutside && !inBase(originPath)) {
             const seen = outsideRules.get(originPath) ?? /* @__PURE__ */ new Set();
             seen.add(nodeText);
@@ -1649,16 +1849,23 @@ async function buildAllStyleData(roots, componentIds, entryOverride) {
           }
         } else {
           const bucket = componentCssBuckets.get(owner) ?? /* @__PURE__ */ new Set();
-          bucket.add(nodeText);
+          addLastOccurrence(bucket, nodeText);
           componentCssBuckets.set(owner, bucket);
         }
       });
-      const { classMap: perFileClasses, baseModules: perFileBaseModules } = extractClassesFromCompiled(consumer, root, entryFile, stylesDir, componentIds);
+      const { classMap: perFileClasses, baseModules: perFileBaseModules, ranks: perFileRanks } = extractClassesFromCompiled(consumer, root, entryFile, stylesDir, componentIds);
       for (const [name, owner] of perFileClasses) {
-        if (!classIndex.has(name)) classIndex.set(name, owner);
-      }
-      for (const [name, mod] of perFileBaseModules) {
-        if (!baseProvenance.has(name)) baseProvenance.set(name, mod);
+        const rank = perFileRanks.get(name) ?? 0;
+        const prev = classRanks.get(name);
+        const mod = perFileBaseModules.get(name);
+        if (prev === void 0 || rank > prev) {
+          classIndex.set(name, owner);
+          classRanks.set(name, rank);
+          if (mod) baseProvenance.set(name, mod);
+          else baseProvenance.delete(name);
+        } else if (mod && classIndex.get(name) === "__base__" && !baseProvenance.has(name)) {
+          baseProvenance.set(name, mod);
+        }
       }
     }
     baseCssByRoot[baseCssByRoot.length - 1] = [...baseCssBucket];
@@ -1688,7 +1895,7 @@ async function surfaceCollisions(collisions, cwd, hotreloader) {
     hotreloader.push(messages[i]);
     console.warn(`[dev-server] HANDLE_COLLISION: "${col.handle}" \u2014 incumbent: ${col.incumbentPath} \u2014 quarantined: ${col.quarantinedPath}`);
   }
-  if (collisions.length > 0) console.warn(`[dev-server] collisions listed in ${join7(pdScratchDir(cwd), "CONFLICTS.generated.md")}`);
+  if (collisions.length > 0) console.warn(`[dev-server] collisions listed in ${join8(pdScratchDir(cwd), "CONFLICTS.generated.md")}`);
   const md = collisions.length === 0 ? "# Conflicts\n\nNo handle collisions detected.\n" : [
     "# Conflicts",
     "",
@@ -1704,7 +1911,7 @@ async function surfaceCollisions(collisions, cwd, hotreloader) {
   try {
     const dir = pdScratchDir(cwd);
     await mkdir(dir, { recursive: true });
-    await writeFile(join7(dir, "CONFLICTS.generated.md"), md, "utf-8");
+    await writeFile(join8(dir, "CONFLICTS.generated.md"), md, "utf-8");
   } catch (e) {
     console.warn("[dev-server] Could not write CONFLICTS.generated.md to scratch dir:", e);
   }
@@ -1725,12 +1932,12 @@ async function surfaceFlattening(discoveryMap, registry, cwd) {
   const md = renderFlatteningReport(clusters);
   if (clusters.length) {
     const members = clusters.reduce((n, c3) => n + c3.members.length, 0);
-    console.warn(`[dev-server] FLATTENED: ${clusters.length} cluster(s) across ${members} components \u2014 see ${join7(pdScratchDir(cwd), "FLATTENED.generated.md")}`);
+    console.warn(`[dev-server] FLATTENED: ${clusters.length} cluster(s) across ${members} components \u2014 see ${join8(pdScratchDir(cwd), "FLATTENED.generated.md")}`);
   }
   try {
     const dir = pdScratchDir(cwd);
     await mkdir(dir, { recursive: true });
-    await writeFile(join7(dir, "FLATTENED.generated.md"), md, "utf-8");
+    await writeFile(join8(dir, "FLATTENED.generated.md"), md, "utf-8");
   } catch (e) {
     console.warn("[dev-server] Could not write FLATTENED.generated.md to scratch dir:", e);
   }
@@ -1747,11 +1954,21 @@ function surfaceDocumentBase(roots, outsideList, cwd) {
   const examples = files.slice(0, 3).map(([path]) => relative3(cwd, path)).join(", ");
   console.log(`[dev-server] base layer: ${rules} rule(s) from ${files.length} file(s) that no component owns and documentBase does not list, e.g. ${examples}`);
 }
+function surfaceAssetRoots(assetRoots, cwd) {
+  for (const { root, by } of shadowedAssetRoots(assetRoots)) {
+    console.warn(`[dev-server] assets: ${relative3(cwd, root)} is hidden by ${relative3(cwd, by) || "."}, which has the same folder name; its files are not served`);
+  }
+}
+function surfaceDefaultTheme(defaultTheme, themeNames) {
+  if (!defaultTheme || themeNames.includes(defaultTheme)) return;
+  const available = themeNames.length ? `available: ${[...themeNames].sort().join(", ")}` : "no theme folder is configured or provided by a package";
+  console.warn(`[dev-server] themes.default "${defaultTheme}" matches no theme; ${available}`);
+}
 
 // packages/dev-server/src/diagnostics.ts
 import { createHash as createHash2 } from "node:crypto";
 import { readFile as readFile6, writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
-import { join as join8 } from "node:path";
+import { join as join9 } from "node:path";
 
 // packages/a11y/src/producer.ts
 import { createRequire } from "node:module";
@@ -1905,7 +2122,7 @@ function assembleGraph(audits) {
 }
 var GRAPH_ARTIFACT_VERSION = 1;
 function graphArtifactPath(root) {
-  return join8(pdScratchDir(root), "diagnostics-graph.json");
+  return join9(pdScratchDir(root), "diagnostics-graph.json");
 }
 async function readDiagnosticsArtifact(root) {
   try {
@@ -1960,101 +2177,15 @@ async function persistSlices(root, slices, discoveryMap, globalData) {
   await writeDiagnosticsArtifact(root, { version: GRAPH_ARTIFACT_VERSION, hashes, graph: assembleGraph([...slices.values()]) });
 }
 
-// packages/dev-server/src/server-config.ts
-import { basename as basename2, join as join9, resolve as resolve5 } from "node:path";
-var DEFAULT_SWATCH_SLOTS = ["--bodyBackground", "--themePrimary", "--accent"];
-function resolveServerConfig(config, cwd, opts = {}, packages = []) {
-  const port2 = opts.port ?? Number(process.env["PD_PORT"] ?? 4e3);
-  const wsPort = opts.wsPort ?? Number(process.env["PD_WS_PORT"] ?? port2 + 1);
-  const patternsDir = resolve5(cwd, config.patternsDir);
-  const stylesDir = resolve5(cwd, config.styles.dir);
-  const stylesEntries = config.styles.entry ? (Array.isArray(config.styles.entry) ? config.styles.entry : [config.styles.entry]).map((e) => resolve5(stylesDir, e)) : void 0;
-  const inPackage = (p, rel) => join9(p.dir, rel);
-  const asList = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
-  const patternRoots = [
-    { dir: patternsDir, ...config.exclude?.length ? { exclude: config.exclude } : {} },
-    ...packages.filter((p) => p.manifest.patterns).map((p) => ({
-      dir: inPackage(p, p.manifest.patterns),
-      source: p.name,
-      ...p.exclude.length ? { exclude: p.exclude } : {}
-    }))
-  ];
-  const styleRoots = [
-    { dir: stylesDir, entries: stylesEntries, base: config.documentBase },
-    ...packages.filter((p) => p.manifest.styles).map((p) => {
-      const dir = inPackage(p, p.manifest.styles.dir);
-      const entries = asList(p.manifest.styles.entry).map((e) => resolve5(dir, e));
-      return { dir, entries: entries.length ? entries : void 0, source: p.name, base: p.manifest.styles.documentBase };
-    })
-  ];
-  const themePackages = packages.filter((p) => p.manifest.themes);
-  const themeDirs = [
-    ...config.themes ? [resolve5(cwd, config.themes.dir)] : [],
-    ...themePackages.map((p) => inPackage(p, p.manifest.themes.dir))
-  ];
-  const switches = [config.themes?.switch, ...themePackages.map((p) => p.manifest.themes.switch)];
-  const themeSwitch = switches.includes("stylesheet") ? "stylesheet" : "attribute";
-  const assetRoots = [
-    ...asList(config.assets?.dir).map((d) => resolve5(cwd, d)),
-    ...packages.flatMap((p) => (p.manifest.assets ?? []).map((a) => inPackage(p, a)))
-  ];
-  const globalScripts = [.../* @__PURE__ */ new Set([
-    ...packages.flatMap((p) => p.manifest.globalScripts ?? []),
-    ...config.globalScripts ?? []
-  ])];
-  const scriptsDirs = [
-    ...config.scriptsDir ? [resolve5(cwd, config.scriptsDir)] : [],
-    ...packages.filter((p) => p.manifest.scripts).map((p) => inPackage(p, p.manifest.scripts))
-  ];
-  const documentBaseEnabled = Array.isArray(config.documentBase) && config.documentBase.length > 0 || packages.some((p) => (p.manifest.styles?.documentBase?.length ?? 0) > 0);
-  return {
-    port: port2,
-    wsPort,
-    cwd,
-    config,
-    packages,
-    patternRoots,
-    patternDirs: patternRoots.map((r) => r.dir),
-    styleRoots,
-    dataDirs: [
-      ...packages.filter((p) => p.manifest.data).map((p) => inPackage(p, p.manifest.data)),
-      ...config.dataDir ? [resolve5(cwd, config.dataDir)] : []
-    ],
-    helperPaths: [
-      ...packages.filter((p) => p.manifest.helpers).map((p) => inPackage(p, p.manifest.helpers)),
-      ...config.helpers ? [resolve5(cwd, config.helpers)] : []
-    ],
-    scriptsDirs,
-    patternsDir,
-    stylesDir,
-    stylesEntries,
-    themeDirs,
-    themesDir: themeDirs[0] ?? null,
-    defaultTheme: config.themes?.default ?? themePackages[0]?.manifest.themes?.default,
-    assetRoots,
-    assetRootNames: assetRoots.map((r) => basename2(r)),
-    assetsDir: assetRoots[0] ?? null,
-    assetsCss: config.assets?.css ?? [],
-    scriptsDir: scriptsDirs[0] ?? null,
-    globalScripts,
-    withGlobalScripts: (own) => [.../* @__PURE__ */ new Set([...globalScripts, ...own ?? []])],
-    overviewsEnabled: config.overviews !== false,
-    documentBaseEnabled,
-    themeSwitch,
-    swatchSlots: config.themes?.swatch?.slots ?? DEFAULT_SWATCH_SLOTS,
-    packageSwatchSlots: DEFAULT_SWATCH_SLOTS
-  };
-}
-
 // packages/dev-server/src/packages.ts
-import { existsSync as existsSync2, readFileSync } from "node:fs";
-import { dirname as dirname3, join as join10 } from "node:path";
+import { existsSync as existsSync3, readFileSync } from "node:fs";
+import { dirname as dirname4, join as join10 } from "node:path";
 function findPackageDir(name, root) {
   let dir = root;
   for (; ; ) {
     const candidate = join10(dir, "node_modules", name);
-    if (existsSync2(join10(candidate, "package.json"))) return candidate;
-    const parent = dirname3(dir);
+    if (existsSync3(join10(candidate, "package.json"))) return candidate;
+    const parent = dirname4(dir);
     if (parent === dir) return null;
     dir = parent;
   }
@@ -2062,7 +2193,7 @@ function findPackageDir(name, root) {
 function loadPatternPackages(references, root) {
   const out = [];
   const seen = /* @__PURE__ */ new Set();
-  const visit = (name, extraExclude, direct, from) => {
+  const visit = (name, direct, from) => {
     if (seen.has(name)) return;
     const dir = findPackageDir(name, from);
     if (!dir) {
@@ -2082,14 +2213,16 @@ function loadPatternPackages(references, root) {
       version: pkg.version ?? "0.0.0",
       dir,
       manifest: pkg.patternDump,
-      exclude: [...pkg.patternDump.exclude ?? [], ...extraExclude],
-      direct
+      exclude: [...pkg.patternDump.exclude ?? [], ...options.get(name)?.exclude ?? []],
+      direct,
+      styles: options.get(name)?.styles ?? true
     });
-    for (const peer of Object.keys(pkg.peerDependencies ?? {})) visit(peer, [], false, dir);
+    for (const peer of Object.keys(pkg.peerDependencies ?? {})) visit(peer, false, dir);
   };
+  const options = /* @__PURE__ */ new Map();
+  for (const ref of references ?? []) if (typeof ref !== "string") options.set(ref.name, ref);
   for (const ref of references ?? []) {
-    const { name, exclude } = typeof ref === "string" ? { name: ref, exclude: [] } : { name: ref.name, exclude: ref.exclude ?? [] };
-    visit(name, exclude, true, root);
+    visit(typeof ref === "string" ? ref : ref.name, true, root);
   }
   return out;
 }
@@ -2125,7 +2258,7 @@ async function runDiagnosticsAudit(config, cwd) {
 
 // packages/dev-server/src/static-build.ts
 import { cp, mkdir as mkdir3, rm, stat as stat2, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname4, join as join11, relative as relative4, resolve as resolve6, sep } from "node:path";
+import { dirname as dirname5, join as join11, relative as relative4, resolve as resolve6, sep } from "node:path";
 
 // packages/dev-server/src/http-utils.ts
 import { readFile as readFile7 } from "node:fs/promises";
@@ -2246,7 +2379,7 @@ async function buildStaticSite(config, root, opts) {
     }
     const type = res.headers.get("content-type") ?? "";
     const target = diskPath(outDir, file);
-    await mkdir3(dirname4(target), { recursive: true });
+    await mkdir3(dirname5(target), { recursive: true });
     if (isText(type)) {
       const body = await res.text();
       const out = withBasePath(body, basePath);
@@ -2266,7 +2399,7 @@ async function buildStaticSite(config, root, opts) {
     if (done.has(file)) return;
     done.add(file);
     const target = diskPath(outDir, file);
-    await mkdir3(dirname4(target), { recursive: true });
+    await mkdir3(dirname5(target), { recursive: true });
     const out = withBasePath(body, basePath);
     await writeFile3(target, out);
     report.bytes += Buffer.byteLength(out);
@@ -2329,7 +2462,13 @@ async function buildStaticSite(config, root, opts) {
     } else {
       log("\u2026 corpus audit left out (build.audit: false / --no-audit)");
     }
+    const shadowed = new Map(shadowedAssetRoots(cfg.assetRoots).map((s) => [s.root, s.by]));
     for (const [i, rootDir] of cfg.assetRoots.entries()) {
+      const by = shadowed.get(rootDir);
+      if (by !== void 0) {
+        report.warnings.push(`assets: ${relative4(root, rootDir)} is hidden by ${relative4(root, by) || "."}, which has the same folder name; left out`);
+        continue;
+      }
       const exists = await stat2(rootDir).then((s) => s.isDirectory(), () => false);
       if (!exists) continue;
       await cp(rootDir, join11(outDir, "assets", cfg.assetRootNames[i]), { recursive: true });
@@ -2345,7 +2484,7 @@ async function buildStaticSite(config, root, opts) {
     const shell = withBasePath(buildShellHtml(runtime), basePath);
     for (const route of routes) {
       const target = diskPath(outDir, staticPathFor(route));
-      await mkdir3(dirname4(target), { recursive: true });
+      await mkdir3(dirname5(target), { recursive: true });
       await writeFile3(target, shell);
       report.files++;
       report.bytes += Buffer.byteLength(shell);
@@ -2361,11 +2500,11 @@ async function buildStaticSite(config, root, opts) {
 
 // packages/dev-server/src/requires.ts
 import { readFile as readFile8 } from "node:fs/promises";
-import { existsSync as existsSync3 } from "node:fs";
-import { basename as basename3, join as join12, relative as relative5 } from "node:path";
+import { existsSync as existsSync4 } from "node:fs";
+import { basename as basename4, join as join12, relative as relative5 } from "node:path";
 function normalizeScriptId(raw) {
   let s = raw.trim().replace(/^\[(.+)\]$/, "$1").trim();
-  s = basename3(s);
+  s = basename4(s);
   s = s.replace(/\.(ts|js)$/, "");
   return s;
 }
@@ -2430,7 +2569,7 @@ function hideSvg(svg) {
   return svg.replace(/<svg(\s|>)/, '<svg$1style="display:none;position:absolute" aria-hidden="true" ');
 }
 async function reportUnresolvableScripts(discoveryMap, scriptsDirs, globalScripts, cwd) {
-  const resolves = (id) => scriptsDirs.some((d) => existsSync3(join12(d, `${id}.ts`)));
+  const resolves = (id) => scriptsDirs.some((d) => existsSync4(join12(d, `${id}.ts`)));
   const where = scriptsDirs.length ? scriptsDirs.map((d) => relative5(cwd, d) || d).join(" or ") : "no scriptsDir configured";
   for (const id of globalScripts) {
     if (id.includes("://") || resolves(normalizeScriptId(id))) continue;
@@ -2493,9 +2632,9 @@ function applyStyleData(state, data) {
 }
 
 // packages/dev-server/src/routes.ts
-import { basename as basename4, extname as extname2, join as join18, relative as relative6 } from "node:path";
+import { basename as basename5, extname as extname2, join as join18, relative as relative6 } from "node:path";
 import { readFile as readFile15, stat as stat4 } from "node:fs/promises";
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } from "node:fs";
 
 // packages/dev-server/src/component-tree.ts
 import { readFile as readFile11 } from "node:fs/promises";
@@ -2880,7 +3019,7 @@ async function _resolveFence(info, content, idx, renderComponent, out, discovery
 
 // packages/dev-server/src/css-closure.ts
 import { readFile as readFile13 } from "node:fs/promises";
-import { dirname as dirname5, resolve as resolve7 } from "node:path";
+import { dirname as dirname6, resolve as resolve7 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import postcss4 from "postcss";
 import * as sass3 from "sass";
@@ -2888,7 +3027,7 @@ import { SourceMapConsumer as SourceMapConsumer2 } from "source-map";
 import { parse as parseHtml2 } from "node-html-parser";
 async function recomputeComponentCss(entryFile, compId, stylesDir, componentIds, inBase = () => false) {
   try {
-    const compiled = sass3.compile(entryFile, { sourceMap: true });
+    const compiled = sass3.compile(entryFile, { sourceMap: true, ...sassPackageOptions(entryFile) });
     const rawMap = compiled.sourceMap;
     if (!rawMap) return null;
     const consumer = new SourceMapConsumer2(rawMap);
@@ -2899,10 +3038,10 @@ async function recomputeComponentCss(entryFile, compId, stylesDir, componentIds,
       if (!pos) return;
       const original = consumer.originalPositionFor({ line: pos.line, column: pos.column - 1 });
       if (!original.source) return;
-      const originPath = original.source.startsWith("file://") ? fileURLToPath3(original.source) : resolve7(dirname5(entryFile), original.source);
+      const originPath = original.source.startsWith("file://") ? fileURLToPath3(original.source) : resolve7(dirname6(entryFile), original.source);
       if (inBase(originPath)) return;
       const originComp = resolveScssToComponent(originPath, stylesDir, componentIds);
-      if (originComp === compId) bucket.add(cssNodeText(node));
+      if (originComp === compId) addLastOccurrence(bucket, cssNodeText(node));
     });
     return joinCssChunks(bucket);
   } catch {
@@ -3238,10 +3377,10 @@ function normalizeAssetRefs(text, rootNames) {
 }
 
 // packages/dev-server/src/assets.ts
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
-function resolveDevUiDist(moduleUrl, exists = existsSync4) {
+function resolveDevUiDist(moduleUrl, exists = existsSync5) {
   const packaged = fileURLToPath4(new URL("./dev-ui/", moduleUrl));
   if (exists(`${packaged}main.js`)) return packaged;
   return fileURLToPath4(new URL("../../../apps/dev-ui/dist/", moduleUrl));
@@ -3314,7 +3453,7 @@ async function handleRequest(req, res, ctx) {
         return;
       }
       const themeName = decodeURIComponent(
-        basename4(pathname, ".css")
+        basename5(pathname, ".css")
       );
       if (state.themeCss.has(themeName)) {
         res.writeHead(200, { "Content-Type": "text/css" });
@@ -3331,10 +3470,10 @@ async function handleRequest(req, res, ctx) {
         res.end("No scriptsDir configured");
         return;
       }
-      const scriptId = normalizeScriptId(decodeURIComponent(basename4(pathname, ".js")));
+      const scriptId = normalizeScriptId(decodeURIComponent(basename5(pathname, ".js")));
       try {
         if (!state.scriptCache.has(scriptId)) {
-          const entryPoint = scriptsDirs.map((d) => join18(d, `${scriptId}.ts`)).find((f) => existsSync5(f));
+          const entryPoint = scriptsDirs.map((d) => join18(d, `${scriptId}.ts`)).find((f) => existsSync6(f));
           if (entryPoint === void 0) {
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end(`No script "${scriptId}": scripts are TypeScript, so ${scriptId}.ts is expected in ` + scriptsDirs.map((d) => relative6(cwd, d) || d).join(" or "));
@@ -3623,12 +3762,12 @@ function describeBindError(e, port2, role, ports) {
 }
 
 // packages/dev-server/src/watch.ts
-import { basename as basename5, extname as extname3, relative as relative7, resolve as resolve8 } from "node:path";
+import { basename as basename6, extname as extname3, relative as relative7, resolve as resolve8 } from "node:path";
 import chokidar from "chokidar";
 function startWatching(ctx) {
   const { cfg, state, render, tracker, hotreloader } = ctx;
   const { patternsDir, stylesDir, styleRoots, patternRoots, patternDirs, swatchSlots, cwd } = cfg;
-  const themesDir = cfg.config.themes ? cfg.themesDir : null;
+  const themesDir = cfg.config.themes?.dir ? cfg.themesDir : null;
   const scriptsDir = cfg.config.scriptsDir ? cfg.scriptsDirs[0] ?? null : null;
   const inProjectBase = documentBaseMatcher(stylesDir, cfg.config.documentBase);
   const watchDirs = [patternsDir, stylesDir, ...themesDir ? [themesDir] : [], ...scriptsDir ? [scriptsDir] : []];
@@ -3647,7 +3786,7 @@ function startWatching(ctx) {
       hotreloader.push({
         type: "error",
         scope: "build",
-        message: `SCSS ${basename5(file)} \u2014 ${message.split("\n")[0]}`
+        message: `SCSS ${basename6(file)} \u2014 ${message.split("\n")[0]}`
       });
     }
     state.scssGraphDirty = true;
@@ -3692,10 +3831,10 @@ function startWatching(ctx) {
     }
     const orderedHrefs = await closureHrefs(timestamp);
     for (const m of pending) hotreloader.push({ ...m, orderedHrefs });
-    console.log(`[dev-server] CSS updated (recompiled: ${effectiveFiles.map((f) => basename5(f)).join(", ")})`);
+    console.log(`[dev-server] CSS updated (recompiled: ${effectiveFiles.map((f) => basename6(f)).join(", ")})`);
   }
   async function restyleAll(allIds, timestamp, files, hadCompileErrors) {
-    const names = files.map((f) => basename5(f)).join(", ");
+    const names = files.map((f) => basename6(f)).join(", ");
     if (hadCompileErrors) {
       console.warn(`[dev-server] CSS not updated \u2014 compile errors (recompiled: ${names})`);
       return;
@@ -3757,7 +3896,7 @@ function startWatching(ctx) {
     }
     if (ext === ".scss") {
       if (themesDir && filePath.startsWith(themesDir)) {
-        const themeName = basename5(filePath, ".theme.scss");
+        const themeName = basename6(filePath, ".theme.scss");
         try {
           const css = await compileSassFile(filePath);
           state.themeCss.set(themeName, css);
@@ -3793,7 +3932,7 @@ function startWatching(ctx) {
         if (verboseTiming) console.log(`[dev-server:timing] diagnostics: live re-audit ${componentId} (1 component; total ${state.liveReauditCount})`);
       }
     } else if (ext === ".ts" && scriptsDir && filePath.startsWith(scriptsDir)) {
-      const scriptId = basename5(filePath, ".ts");
+      const scriptId = basename6(filePath, ".ts");
       state.scriptCache.delete(scriptId);
       if (state.lastComponentId) {
         hotreloader.push({ type: "content-swap", componentId: state.lastComponentId });
@@ -3839,7 +3978,7 @@ function startWatching(ctx) {
 
 // packages/dev-server/src/export-io.ts
 import { readFile as readFile16, writeFile as writeFile4, mkdir as mkdir4 } from "node:fs/promises";
-import { dirname as dirname6, join as join19, relative as relative8, resolve as resolve9 } from "node:path";
+import { dirname as dirname7, join as join19, relative as relative8, resolve as resolve9 } from "node:path";
 
 // packages/dev-server/src/export.ts
 var escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -4033,7 +4172,7 @@ async function writeExport(families, sink) {
   for (const family of families) {
     const baseRel = `${family.baseId}.hbs`;
     const basePath = join19(sink, baseRel);
-    await mkdir4(dirname6(basePath), { recursive: true });
+    await mkdir4(dirname7(basePath), { recursive: true });
     await writeFile4(basePath, family.baseHbs, "utf-8");
     files.push(baseRel);
     if (family.baseData) {
@@ -4078,7 +4217,7 @@ async function writeThreadedIncluders(threaded, patternsDir, sink) {
     rewrites += res.rewrites;
     const rel = relative8(patternsDir, hbsPath);
     const outPath = join19(sink, rel);
-    await mkdir4(dirname6(outPath), { recursive: true });
+    await mkdir4(dirname7(outPath), { recursive: true });
     await writeFile4(outPath, res.hbs, "utf-8");
     files.push(rel);
   }
@@ -4238,7 +4377,7 @@ async function startDevServer(config, cwd, opts = {}) {
       try {
         const css = await compileSassFile(join20(dir, `${name}.theme.scss`));
         state.themeCss.set(name, css);
-        const slots = config.themes && dir === cfg.themeDirs[0] ? swatchSlots : cfg.packageSwatchSlots;
+        const slots = config.themes?.dir && dir === cfg.themeDirs[0] ? swatchSlots : cfg.packageSwatchSlots;
         state.themeTokens.set(name, await extractThemeTokens(name, css, slots, dir));
       } catch (e) {
         console.warn(`[dev-server] Theme compile error (${name}):`, e);
@@ -4247,6 +4386,7 @@ async function startDevServer(config, cwd, opts = {}) {
       }
     }
   }
+  surfaceDefaultTheme(cfg.defaultTheme, [...state.themeCss.keys()]);
   {
     const dr = await buildDiscoveryMap(patternRoots);
     state.discoveryResult = dr;
@@ -4260,6 +4400,7 @@ async function startDevServer(config, cwd, opts = {}) {
     const styleData = await buildAllStyleData(styleRoots, allComponentIds);
     applyStyleData(state, styleData);
     surfaceDocumentBase(styleRoots, styleData.baseOutsideList, cwd);
+    surfaceAssetRoots(cfg.assetRoots, cwd);
     await reportUnresolvableScripts(dr.discoveryMap, cfg.scriptsDirs, cfg.globalScripts, cwd);
   }
   const boot = {
@@ -4301,9 +4442,9 @@ async function startDevServer(config, cwd, opts = {}) {
 
 // packages/core/src/index.ts
 import { build as esbuild } from "esbuild";
-import { existsSync as existsSync6 } from "node:fs";
+import { existsSync as existsSync7 } from "node:fs";
 import { readFile as readFile17, writeFile as writeFile5, unlink, mkdir as mkdir5 } from "node:fs/promises";
-import { join as join21, dirname as dirname7, resolve as resolve10, relative as relative9, isAbsolute } from "node:path";
+import { join as join21, dirname as dirname8, resolve as resolve10, relative as relative9, isAbsolute } from "node:path";
 import { tmpdir as tmpdir2 } from "node:os";
 import { createHash as createHash3 } from "node:crypto";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
@@ -4331,7 +4472,7 @@ async function runAudit(root, configPath, format = "md") {
   const { graph, reaudited, reused, artifactPath } = await runDiagnosticsAudit(config, root);
   const report = formatAudit(graph, format);
   const ext = format === "json" ? "json" : format === "text" ? "txt" : "md";
-  const reportPath = join21(dirname7(artifactPath), `diagnostics-report.${ext}`);
+  const reportPath = join21(dirname8(artifactPath), `diagnostics-report.${ext}`);
   await writeFile5(reportPath, report, "utf-8");
   console.log(report);
   const affected = new Set(graph.occurrences.map((o) => o.component)).size;
@@ -4417,14 +4558,14 @@ async function runExport(root, configPath, outDir) {
 }
 async function loadConfig(root, configPath) {
   if (configPath) {
-    if (!existsSync6(configPath)) {
+    if (!existsSync7(configPath)) {
       throw new ConfigError(`--config file not found: ${configPath}`);
     }
     return validateConfig(await readConfigFile(configPath), configPath);
   }
   for (const name of ["pattern-dump.config.ts", "pattern-dump.config.json"]) {
     const path = join21(root, name);
-    if (existsSync6(path)) return validateConfig(await readConfigFile(path), name);
+    if (existsSync7(path)) return validateConfig(await readConfigFile(path), name);
   }
   throw new ConfigError(
     `No pattern-dump.config.ts or pattern-dump.config.json found in ${root} (and no --config given)`
@@ -4639,14 +4780,14 @@ var USAGE = `Usage: pd <command> [options]
   help [command]   Show this help`;
 
 // packages/cli/src/init/run.ts
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync8 } from "node:fs";
 import { readFile as readFile19 } from "node:fs/promises";
-import { basename as basename6, dirname as dirname9, join as join23, relative as relative11, resolve as resolve12 } from "node:path";
+import { basename as basename7, dirname as dirname10, join as join23, relative as relative11, resolve as resolve12 } from "node:path";
 
 // packages/cli/package.json
 var package_default = {
   name: "@pattern-dump/cli",
-  version: "0.1.0-alpha.3",
+  version: "0.1.0-alpha.4",
   private: true,
   description: "The pd command and the published pattern-dump package.",
   type: "module",
@@ -4682,7 +4823,7 @@ var PD_VERSION = package_default.version;
 
 // packages/cli/src/init/files.ts
 import { mkdir as mkdir6, readdir as readdir5, readFile as readFile18, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname8, join as join22, relative as relative10, sep as sep2 } from "node:path";
+import { dirname as dirname9, join as join22, relative as relative10, sep as sep2 } from "node:path";
 async function readTemplateDir(dir) {
   const out = [];
   async function walk(current) {
@@ -4706,7 +4847,7 @@ async function applyPlan(target, plan) {
   await mkdir6(target, { recursive: true });
   for (const file of plan.writes) {
     const abs = join22(target, file.path);
-    await mkdir6(dirname8(abs), { recursive: true });
+    await mkdir6(dirname9(abs), { recursive: true });
     await writeFile6(abs, file.content, { flag: "wx" });
   }
   await writeFile6(join22(target, "package.json"), plan.packageJson.content);
@@ -4789,12 +4930,12 @@ function mergePackageJson(current, answers, packageName) {
 function dependencySpec(pdSource, cwd) {
   if (pdSource === void 0) return `^${PD_VERSION}`;
   const asPath = resolve12(cwd, pdSource);
-  if (existsSync7(asPath)) return `file:${asPath}`;
+  if (existsSync8(asPath)) return `file:${asPath}`;
   return pdSource.startsWith(`${PD_PACKAGE_NAME}@`) ? pdSource.slice(PD_PACKAGE_NAME.length + 1) : pdSource;
 }
 async function insideGitRepo(target, io) {
   let dir = target;
-  while (!existsSync7(dir) && dirname9(dir) !== dir) dir = dirname9(dir);
+  while (!existsSync8(dir) && dirname10(dir) !== dir) dir = dirname10(dir);
   return await io.run("git", ["rev-parse", "--is-inside-work-tree"], dir) === 0;
 }
 async function runInit(cmd, io) {
@@ -4819,7 +4960,7 @@ async function runInit(cmd, io) {
   }
   const pkgPath = join23(target, "package.json");
   let packageJson = null;
-  if (existsSync7(pkgPath)) {
+  if (existsSync8(pkgPath)) {
     try {
       packageJson = JSON.parse(await readFile19(pkgPath, "utf8"));
     } catch (e) {
@@ -4829,7 +4970,7 @@ async function runInit(cmd, io) {
   }
   const prompt = io.interactive && !cmd.yes;
   const existingName = typeof packageJson?.name === "string" ? packageJson.name : void 0;
-  const name = cmd.name ?? (prompt ? await io.ask("Project name", existingName ?? toPackageName(basename6(target))) : existingName ?? toPackageName(basename6(target)));
+  const name = cmd.name ?? (prompt ? await io.ask("Project name", existingName ?? toPackageName(basename7(target))) : existingName ?? toPackageName(basename7(target)));
   const brand = cmd.brand ?? (prompt ? await io.ask("Title in the Nav Rail", name) : name);
   const examples = cmd.examples ?? (prompt ? await io.confirm("Include starter components", true) : true);
   const gitDefault = !await insideGitRepo(target, io);
@@ -4837,7 +4978,7 @@ async function runInit(cmd, io) {
   const install = cmd.install ?? (prompt ? await io.confirm("Run npm install", true) : true);
   const answers = { name, brand, examples, dependency };
   const templates = await readTemplates(io.templatesDir);
-  const result = planInit(templates, answers, { packageJson, exists: (p) => existsSync7(join23(target, p)) }, PD_PACKAGE_NAME);
+  const result = planInit(templates, answers, { packageJson, exists: (p) => existsSync8(join23(target, p)) }, PD_PACKAGE_NAME);
   if (!result.ok) {
     io.log(`\u2717 ${result.reason}`);
     return 1;
@@ -4877,7 +5018,7 @@ async function runInit(cmd, io) {
 }
 
 // packages/cli/src/init/local-build.ts
-import { existsSync as existsSync8, statSync } from "node:fs";
+import { existsSync as existsSync9, statSync } from "node:fs";
 import { join as join24 } from "node:path";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 var BUILT = [
@@ -4896,9 +5037,9 @@ var mtime = (path) => {
 };
 function detectLocalBuild(moduleUrl, packageName, version) {
   const repo = fileURLToPath6(new URL("../../../", moduleUrl)).replace(/[\\/]$/, "");
-  if (!existsSync8(join24(repo, "packages/cli/src/distribution.ts"))) return null;
+  if (!existsSync9(join24(repo, "packages/cli/src/distribution.ts"))) return null;
   const tarball = join24(repo, ".pd-pack", `${packageName}-${version}.tgz`);
-  if (!existsSync8(tarball)) return { repo, tarball: null, stale: false };
+  if (!existsSync9(tarball)) return { repo, tarball: null, stale: false };
   const newestBuild = Math.max(...BUILT.map((p) => mtime(join24(repo, p))));
   return { repo, tarball, stale: newestBuild > mtime(tarball) };
 }

package/dist/types/config/index.d.ts

@@ -37,9 +37,10 @@ export interface StylesConfig {
     entry?: string | string[];
 }
 export interface ThemesConfig {
-    /** Directory of theme files (custom-property value-sets). */
-    dir: string;
-    /** Default theme name applied via data-theme on the preview body. */
+    /** Directory of the project's own theme files (custom-property value-sets). Leave it out to use
+     *  only the themes pattern packages provide, with `default` naming one of them. */
+    dir?: string;
+    /** Default theme name applied via data-theme on the preview body: a project theme or a package's. */
     default: string;
     /** Switch wiring: attribute toggle (default) or per-theme stylesheet swap. */
     switch?: ThemeSwitch;
@@ -66,10 +67,17 @@ export interface ShellConfig {
  * invoking `cwd`. This holds even when the file is supplied via `--config` from outside the
  * root — which is what lets PD open a read-only project it does not own.
  */
-/** A pattern package named in the config: the npm name, or the name plus extra excludes. */
+/**
+ * A pattern package named in the config: the npm name, or the name plus options.
+ * - `exclude`: extra globs of the package's templates to hide.
+ * - `styles: false`: leave the package's stylesheets out (its templates, data, themes, scripts and
+ *   assets are still used), e.g. when the project compiles that CSS itself. A package reached only
+ *   as another package's peer can be named here just to carry this option.
+ */
 export type PackageReference = string | {
     name: string;
     exclude?: string[];
+    styles?: boolean;
 };
 export interface PatternDumpConfig {
     sourceDir: string;

package/dist/types/contracts/dev-protocol.d.ts

@@ -70,7 +70,7 @@ export interface TreeNode {
     children?: TreeNode[];
 }
 export type DiagnosticSeverity = "error" | "warning" | "info";
-export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION";
+export type DiagnosticKind = "RENDER_ERROR" | "UNFILLED_REQUIRED" | "SHAPE_MISMATCH" | "HTML_INVALID" | "CASCADE_WARNING" | "A11Y" | "HIGHLIGHT_FALLBACK" | "HANDLE_COLLISION" | "DATA_INVALID";
 /** Fields every diagnostic carries, whichever engine produced it. */
 interface DiagnosticBase {
     severity: DiagnosticSeverity;
@@ -81,7 +81,7 @@ interface DiagnosticBase {
     ruleId?: string;
     /** JSON Schema / data pointer, e.g. "#/properties/label" — schema kinds only. */
     path?: string;
-    /** Source-file position — RENDER_ERROR, best-effort. */
+    /** Source-file position — RENDER_ERROR and DATA_INVALID, best-effort. */
     location?: {
         file?: string;
         line?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-dump",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
   "keywords": [
     "design-system",
@@ -69,6 +69,7 @@
     "markdown-it": "^14.2.0",
     "node-html-parser": "^7.1.0",
     "postcss": "^8.5.15",
+    "postcss-selector-parser": "^7.1.1",
     "sass": "^1.100.0",
     "shiki": "^4.1.0",
     "source-map": "^0.6.1",