evolit 0.1.3 → 0.1.5

package/README.md

@@ -46,6 +46,31 @@ Generated applications declare `"@/*": ["./*"]` in `jsconfig.json`, so editors a
 use the same convention. An explicit `@/*` mapping in `jsconfig.json` or `tsconfig.json` takes
 priority when an application needs a different source root.
 
+### Package CSS and static assets
+
+Applications can import stylesheets exposed through package `exports` in the same way as local
+stylesheets:
+
+```js
+import "@scope/design-system/tokens.css";
+import "@scope/design-system/theme.css";
+```
+
+Evolit resolves package subpaths with ESM `import` conditions, emits exported CSS through the
+route static-asset pipeline, and adds the resulting stylesheet URLs to the rendered document.
+Relative `@import` rules and `url(...)` references inside package CSS are emitted and rewritten
+from their location within `node_modules`. Bare package imports that resolve to JavaScript continue
+to use the shared vendor runtime; hydration metadata uses that same canonical package URL so an
+external component is evaluated only once. CSS and other static assets do not enter vendor chunks.
+
+Packages declared by the application remain package dependencies even when a workspace manager
+links them to sources elsewhere in a monorepo. Evolit uses the declared package name and its
+browser `exports` subpath as the public identity; the physical symlink or real filesystem path is
+used only to verify package ownership and is never exposed as an `__unmanaged__` client module.
+During `evolit build`, a package reached by the production SSR graph that is declared only in
+`devDependencies` produces a warning. Its package identity is preserved, but applications should
+move it to `dependencies` or keep development dependencies installed in the production runtime.
+
 ## Commands
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

package/src/build.js

@@ -10,6 +10,8 @@ import {
 import {
   collectTransitiveAssetPreloads,
   collectTransitiveStyleUrls,
+  buildSharedVendorRuntime,
+  canonicalizePackageModuleId,
   createAssetResolver,
   createHydrationBootstrap,
   createStaticAssetPublicUrlMap,
@@ -70,6 +72,31 @@ const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".js", "text/javascript; charset=utf-8"],
 ]);
 
+function getBarePackageName(specifier) {
+  if (typeof specifier !== "string" || specifier.length === 0) return null;
+  const segments = specifier.split("/");
+  return specifier.startsWith("@")
+    ? segments.length >= 2 ? `${segments[0]}/${segments[1]}` : null
+    : segments[0];
+}
+
+export function collectSsrDevDependencyWarnings(packageJson, packageSpecifiers) {
+  const productionDependencies = new Set([
+    ...Object.keys(packageJson?.dependencies ?? {}),
+    ...Object.keys(packageJson?.optionalDependencies ?? {}),
+    ...Object.keys(packageJson?.peerDependencies ?? {}),
+  ]);
+  const devDependencies = new Set(Object.keys(packageJson?.devDependencies ?? {}));
+  return [...new Set(packageSpecifiers
+    .map(getBarePackageName)
+    .filter((packageName) => (
+      packageName
+      && devDependencies.has(packageName)
+      && !productionDependencies.has(packageName)
+    )))]
+    .sort();
+}
+
 function getContentTypeForBuildArtifact(filePath) {
   return CONTENT_TYPE_BY_EXTENSION.get(path.extname(filePath)) ?? "application/octet-stream";
 }
@@ -128,12 +155,15 @@ async function writeDeploymentRuntimeEntry(buildRoot) {
   return runtimeEntryPath;
 }
 
-export async function buildProject(projectRoot) {
+export async function buildProject(projectRoot, options = {}) {
   const evolitConfig = await loadEvolitConfig(projectRoot);
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
+  const packageClientSpecifiers = new Set(
+    extensionClientDescriptors.map((descriptor) => descriptor.module),
+  );
   const sharedVendorOptions = {
-    additionalEntrySpecifiers: extensionClientDescriptors.map((descriptor) => descriptor.module),
+    additionalEntrySpecifiers: [],
   };
   const routes = await discoverAppRoutes(projectRoot);
   const routeHandlers = await discoverAppRouteHandlers(projectRoot);
@@ -144,6 +174,19 @@ export async function buildProject(projectRoot) {
   const deployHandlers = [];
   const compiledClientBoundaries = new Map();
   const inventoriesBySourceEntry = new Map();
+  const ssrPackageImports = new Set();
+
+  async function compileProductionServerEntry(sourcePath) {
+    const result = await compileModuleGraph(sourcePath, {
+      projectRoot,
+      mode: "production",
+      sourceMaps: false,
+      ssr: true,
+      target: "server",
+    });
+    result.packageImports.forEach((specifier) => ssrPackageImports.add(specifier));
+    return result;
+  }
 
   function getEntryInventory(entryPath) {
     let inventory = inventoriesBySourceEntry.get(entryPath);
@@ -174,13 +217,7 @@ export async function buildProject(projectRoot) {
   await ensureDirectory(buildRoot);
 
   for (const routeHandler of routeHandlers) {
-    await compileModuleGraph(routeHandler.handler, {
-      projectRoot,
-      mode: "production",
-      sourceMaps: false,
-      ssr: true,
-      target: "server",
-    });
+    await compileProductionServerEntry(routeHandler.handler);
 
     const handlerModule = await importCompiledModule(routeHandler.handler, {
       projectRoot,
@@ -204,22 +241,10 @@ export async function buildProject(projectRoot) {
   }
 
   for (const route of routes) {
-    await compileModuleGraph(route.page, {
-      projectRoot,
-      mode: "production",
-      sourceMaps: false,
-      ssr: true,
-      target: "server",
-    });
+    await compileProductionServerEntry(route.page);
 
     for (const layoutPath of route.layouts) {
-      await compileModuleGraph(layoutPath, {
-        projectRoot,
-        mode: "production",
-        sourceMaps: false,
-        ssr: true,
-        target: "server",
-      });
+      await compileProductionServerEntry(layoutPath);
 
     }
 
@@ -228,13 +253,7 @@ export async function buildProject(projectRoot) {
       ...(route.errorBoundaries ?? []).map((boundary) => boundary.module),
     ];
     for (const boundaryPath of new Set(boundaryModules)) {
-      await compileModuleGraph(boundaryPath, {
-        projectRoot,
-        mode: "production",
-        sourceMaps: false,
-        ssr: true,
-        target: "server",
-      });
+      await compileProductionServerEntry(boundaryPath);
     }
 
     const toProjectRelative = (filePath) => path.relative(projectRoot, filePath).split(path.sep).join("/");
@@ -247,13 +266,21 @@ export async function buildProject(projectRoot) {
     const allAssets = new Set();
     const allClientBoundaries = new Set();
     for (const [entryPath, entryInventory] of inventoriesByEntry) {
+      const packageBoundarySources = new Set(
+        (entryInventory.packageClientBoundaries ?? []).map((entry) => entry.sourcePath),
+      );
+      for (const packageBoundary of entryInventory.packageClientBoundaries ?? []) {
+        packageClientSpecifiers.add(packageBoundary.specifier);
+      }
       serverAssetImportsByEntry[toProjectRelative(entryPath)] = {
         styles: entryInventory.styles.map((filePath) => getClientStaticAssetModule(projectRoot, filePath)),
         assets: entryInventory.assets.map((filePath) => getClientStaticAssetModule(projectRoot, filePath)),
       };
       entryInventory.styles.forEach((filePath) => allStyles.add(filePath));
       entryInventory.assets.forEach((filePath) => allAssets.add(filePath));
-      entryInventory.clientBoundaries.forEach((filePath) => allClientBoundaries.add(filePath));
+      entryInventory.clientBoundaries
+        .filter((filePath) => !packageBoundarySources.has(filePath))
+        .forEach((filePath) => allClientBoundaries.add(filePath));
     }
     await emitClientStaticAssets([...allStyles, ...allAssets], {
       projectRoot,
@@ -268,12 +295,23 @@ export async function buildProject(projectRoot) {
     }
     for (const [entryPath, entryInventory] of inventoriesByEntry) {
       clientBoundariesByEntry[toProjectRelative(entryPath)] = entryInventory.clientBoundaries
+        .filter((clientBoundary) => !(entryInventory.packageClientBoundaries ?? [])
+          .some((packageBoundary) => packageBoundary.sourcePath === clientBoundary))
         .map((clientBoundary) => compiledBoundaryModules.get(clientBoundary))
         .filter(Boolean)
         .sort();
     }
   }
 
+  const projectPackageJson = JSON.parse(await fs.readFile(path.join(projectRoot, "package.json"), "utf8"));
+  const warn = options.onWarning ?? console.warn;
+  for (const packageName of collectSsrDevDependencyWarnings(projectPackageJson, [...ssrPackageImports])) {
+    warn(
+      `[evolit] Production SSR imports ${JSON.stringify(packageName)}, but it is declared only in devDependencies. `
+      + "Move it to dependencies or ensure production installations include development dependencies.",
+    );
+  }
+
   const configuredClientBoundaries = evolitConfig.clientBoundaries ?? [];
   if (!Array.isArray(configuredClientBoundaries)) {
     throw new Error("Expected clientBoundaries in evolit.config.js to be an array of module specifiers.");
@@ -295,8 +333,10 @@ export async function buildProject(projectRoot) {
     await compileProductionClientBoundary(sourcePath);
   }
 
+  sharedVendorOptions.additionalEntrySpecifiers = [...packageClientSpecifiers].sort();
   const clientAssets = await emitBundledClientAssets(projectRoot, {
     entryClientModules,
+    additionalVendorSpecifiers: sharedVendorOptions.additionalEntrySpecifiers,
     serverAssetImportsByEntry,
     clientBoundariesByEntry,
   });
@@ -306,8 +346,12 @@ export async function buildProject(projectRoot) {
   const routeResolver = await createRouteResolver(projectRoot, "production", {
     staticAssetPublicUrls,
   });
+  const sharedRuntime = await buildSharedVendorRuntime(projectRoot, "production", sharedVendorOptions);
+  clientAssets.sharedImports = { ...sharedRuntime.imports };
+  const packageImports = sharedRuntime.imports;
   const assetResolver = createAssetResolver(projectRoot, {
     assetManifest: clientAssets,
+    packageImports,
   });
   const hydrationModuleUrl = await resolveSharedVendorModuleUrl(
     projectRoot,
@@ -341,6 +385,33 @@ export async function buildProject(projectRoot) {
       ].filter((moduleId) => typeof moduleId === "string" && moduleId.length > 0))];
       const unresolved = [];
       for (const moduleId of renderedModules) {
+        const packageSpecifier = await canonicalizePackageModuleId(
+          projectRoot,
+          moduleId,
+          packageClientSpecifiers,
+        );
+        if (packageSpecifier) {
+          const publicUrl = packageImports[packageSpecifier] ?? null;
+          if (!publicUrl) {
+            unresolved.push(moduleId);
+            continue;
+          }
+          const previousPublicUrl = assetResolver(moduleId);
+          for (const root of result.hydrationData?.roots ?? []) {
+            if (root?.moduleId === moduleId) root.moduleId = packageSpecifier;
+          }
+          if (Array.isArray(result.clientImports)) {
+            result.clientImports = result.clientImports.map((value) => (
+              value === moduleId || value === previousPublicUrl ? publicUrl : value
+            ));
+          }
+          if (Array.isArray(result.hydrationData?.clientImports)) {
+            result.hydrationData.clientImports = result.hydrationData.clientImports.map((value) => (
+              value === moduleId || value === previousPublicUrl ? publicUrl : value
+            ));
+          }
+          continue;
+        }
         if (assetResolver(moduleId) || clientAssets.byPublicPath?.[moduleId]) continue;
         const importerPath = routeResult.boundaryModule
           ?? routeResult.route?.page
@@ -406,6 +477,7 @@ export async function buildProject(projectRoot) {
           result.hydrationData,
           projectRoot,
           resolveHydrationRootClientImports(result.hydrationData, assetResolver),
+          assetResolver,
         ),
         assetResolver,
         hydrationModuleUrl,
@@ -420,6 +492,7 @@ export async function buildProject(projectRoot) {
           result.hydrationData,
           projectRoot,
           resolveHydrationRootClientImports(result.hydrationData, assetResolver),
+          assetResolver,
         ),
       );
     },

package/src/client-assets.js

@@ -144,35 +144,84 @@ export async function resolvePackageRoot(packageName, options = {}) {
   }
 
   const pendingResolution = (async () => {
-    let packageEntryPath;
-    try {
-      packageEntryPath = createRequire(path.join(resolveFrom, "package.json")).resolve(packageName);
-    } catch {
-      packageEntryPath = requireFromHere.resolve(packageName);
-    }
-    let currentPath = path.dirname(packageEntryPath);
-
-    while (true) {
-      const packageJsonPath = path.join(currentPath, "package.json");
+    const resolvers = [
+      createRequire(path.join(resolveFrom, "package.json")),
+      requireFromHere,
+    ];
 
+    for (const resolver of resolvers) {
       try {
+        const packageJsonPath = resolver.resolve(`${packageName}/package.json`);
         const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
         if (packageJson?.name === packageName) {
-          return { packageRoot: currentPath, packageJson };
+          return { packageRoot: path.dirname(packageJsonPath), packageJson };
         }
       } catch {
-        // Keep walking up until we find the owning package root.
+        // Some packages intentionally do not export package.json. Resolve the
+        // entrypoint below and walk back to its owning manifest instead.
       }
+    }
 
-      const parentPath = path.dirname(currentPath);
-      if (parentPath === currentPath) {
+    let packageEntryPath = null;
+    let resolutionError = null;
+    for (const resolver of resolvers) {
+      try {
+        packageEntryPath = resolver.resolve(packageName);
         break;
+      } catch (error) {
+        resolutionError = error;
       }
+    }
+    if (packageEntryPath) {
+      let currentPath = path.dirname(packageEntryPath);
+
+      while (true) {
+        const packageJsonPath = path.join(currentPath, "package.json");
 
-      currentPath = parentPath;
+        try {
+          const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+          if (packageJson?.name === packageName) {
+            return { packageRoot: currentPath, packageJson };
+          }
+        } catch {
+          // Keep walking up until we find the owning package root.
+        }
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) {
+          break;
+        }
+
+        currentPath = parentPath;
+      }
     }
 
-    throw new Error(`Unable to resolve package root for ${packageName}`);
+    const packageSegments = packageName.split("/");
+    const validPackageSegments = packageSegments.length === 1
+      || (packageSegments.length === 2 && packageSegments[0].startsWith("@"));
+    if (validPackageSegments && packageSegments.every((segment) => segment && segment !== "." && segment !== "..")) {
+      let currentPath = resolveFrom;
+      while (true) {
+        const packageJsonPath = path.join(currentPath, "node_modules", ...packageSegments, "package.json");
+        try {
+          const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+          if (packageJson?.name === packageName) {
+            return {
+              packageRoot: await fs.realpath(path.dirname(packageJsonPath)),
+              packageJson,
+            };
+          }
+        } catch {
+          // Continue through the normal node_modules ancestor lookup.
+        }
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) break;
+        currentPath = parentPath;
+      }
+    }
+
+    throw resolutionError ?? new Error(`Unable to resolve package root for ${packageName}`);
   })();
 
   packageRootCache.set(cacheKey, pendingResolution);
@@ -190,6 +239,14 @@ function pickBrowserExportTarget(target) {
     return target;
   }
 
+  if (Array.isArray(target)) {
+    for (const candidate of target) {
+      const resolved = pickBrowserExportTarget(candidate);
+      if (resolved) return resolved;
+    }
+    return null;
+  }
+
   if (!target || typeof target !== "object") {
     return null;
   }
@@ -202,6 +259,33 @@ function pickBrowserExportTarget(target) {
     ?? null;
 }
 
+function resolveBrowserPackageExport(exportsField, exportKey) {
+  if (typeof exportsField === "string" || Array.isArray(exportsField)) {
+    return exportKey === "." ? pickBrowserExportTarget(exportsField) : null;
+  }
+  if (!exportsField || typeof exportsField !== "object") {
+    return null;
+  }
+  if (!Object.keys(exportsField).some((key) => key.startsWith("."))) {
+    return exportKey === "." ? pickBrowserExportTarget(exportsField) : null;
+  }
+  if (exportsField[exportKey] != null) {
+    return pickBrowserExportTarget(exportsField[exportKey]);
+  }
+
+  for (const [pattern, target] of Object.entries(exportsField)) {
+    const wildcardIndex = pattern.indexOf("*");
+    if (wildcardIndex < 0) continue;
+    const prefix = pattern.slice(0, wildcardIndex);
+    const suffix = pattern.slice(wildcardIndex + 1);
+    if (!exportKey.startsWith(prefix) || !exportKey.endsWith(suffix)) continue;
+    const wildcard = exportKey.slice(prefix.length, exportKey.length - suffix.length);
+    const resolved = pickBrowserExportTarget(target);
+    if (resolved) return resolved.replace("*", wildcard);
+  }
+  return null;
+}
+
 export async function resolveBrowserSpecifierFilePath(specifier, options = {}) {
   if (!isBareSpecifier(specifier)) {
     return null;
@@ -222,17 +306,15 @@ export async function resolveBrowserSpecifierFilePath(specifier, options = {}) {
     const { packageName, subpath } = parsedSpecifier;
     const { packageRoot, packageJson } = await resolvePackageRoot(packageName, { projectRoot: resolveFrom });
     const exportKey = subpath.length > 0 ? `./${subpath}` : ".";
-    const exportsField = packageJson.exports;
-    const exportTarget = pickBrowserExportTarget(
-      exportsField && typeof exportsField === "object" && Object.keys(exportsField).some((key) => key.startsWith("."))
-        ? exportsField[exportKey]
-        : exportKey === "." ? exportsField : null,
-    );
-    const fallbackTarget = subpath.length > 0
-      ? `./${subpath}`
-      : typeof packageJson.browser === "string"
-        ? packageJson.browser
-        : packageJson.module ?? packageJson.main ?? null;
+    const hasExports = packageJson.exports != null;
+    const exportTarget = resolveBrowserPackageExport(packageJson.exports, exportKey);
+    const fallbackTarget = hasExports
+      ? null
+      : subpath.length > 0
+        ? `./${subpath}`
+        : typeof packageJson.browser === "string"
+          ? packageJson.browser
+          : packageJson.module ?? packageJson.main ?? null;
     let resolvedTarget = exportTarget ?? fallbackTarget;
     if (resolvedTarget && packageJson.browser && typeof packageJson.browser === "object") {
       const normalizedTarget = resolvedTarget.startsWith("./")
@@ -264,6 +346,79 @@ export async function resolveBrowserSpecifierFilePath(specifier, options = {}) {
   }
 }
 
+export async function resolveDeclaredPackageNames(projectRoot) {
+  try {
+    const packageJson = JSON.parse(await fs.readFile(path.join(projectRoot, "package.json"), "utf8"));
+    return new Set([
+      ...Object.keys(packageJson.dependencies ?? {}),
+      ...Object.keys(packageJson.optionalDependencies ?? {}),
+      ...Object.keys(packageJson.peerDependencies ?? {}),
+      ...Object.keys(packageJson.devDependencies ?? {}),
+    ]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return new Set();
+    throw error;
+  }
+}
+
+export async function canonicalizePackageModuleId(projectRoot, moduleId, packageSpecifiers = []) {
+  const declaredPackageNames = await resolveDeclaredPackageNames(projectRoot);
+  const specifiers = [...new Set(packageSpecifiers)]
+    .filter((specifier) => {
+      const parsed = parsePackageSpecifier(specifier);
+      return parsed && declaredPackageNames.has(parsed.packageName);
+    });
+  if (specifiers.includes(moduleId)) {
+    return moduleId;
+  }
+
+  let sourcePath = null;
+  if (typeof moduleId === "string" && moduleId.startsWith("file:")) {
+    try { sourcePath = fileURLToPath(moduleId); } catch { return null; }
+  } else if (typeof moduleId === "string" && path.isAbsolute(moduleId)) {
+    sourcePath = moduleId;
+  }
+  if (!sourcePath || sourcePath.startsWith(`${path.sep}_evolit${path.sep}`)) {
+    return null;
+  }
+
+  let realSourcePath;
+  try {
+    realSourcePath = await fs.realpath(sourcePath);
+  } catch {
+    realSourcePath = path.resolve(sourcePath);
+  }
+
+  const exactMatches = [];
+  const packageMatches = [];
+  for (const specifier of specifiers) {
+    const parsed = parsePackageSpecifier(specifier);
+    try {
+      const [{ packageRoot }, entryPath] = await Promise.all([
+        resolvePackageRoot(parsed.packageName, { projectRoot }),
+        resolveBrowserSpecifierFilePath(specifier, { projectRoot }),
+      ]);
+      const [realPackageRoot, realEntryPath] = await Promise.all([
+        fs.realpath(packageRoot),
+        fs.realpath(entryPath),
+      ]);
+      const relativePath = path.relative(realPackageRoot, realSourcePath);
+      const belongsToPackage = relativePath === ""
+        || (relativePath !== ".."
+          && !relativePath.startsWith(`..${path.sep}`)
+          && !path.isAbsolute(relativePath));
+      if (!belongsToPackage) continue;
+      packageMatches.push(specifier);
+      if (realEntryPath === realSourcePath) exactMatches.push(specifier);
+    } catch {
+      // An unrelated or unavailable optional package cannot own this module.
+    }
+  }
+
+  if (exactMatches.length === 1) return exactMatches[0];
+  return packageMatches.length === 1 ? packageMatches[0] : null;
+}
+
 export function getSharedOutputRoot(projectRoot, mode) {
   return path.join(
     projectRoot,
@@ -1082,6 +1237,10 @@ function toPublicHydrationModuleId(projectRoot, moduleId) {
     return `/${relativePath}`;
   }
 
+  if (isBareSpecifier(moduleId)) {
+    return moduleId;
+  }
+
   if (moduleId.startsWith("/")) {
     return moduleId;
   }
@@ -1113,12 +1272,19 @@ function getServerOutputRoot(projectRoot) {
 
 export function createAssetResolver(projectRoot, options = {}) {
   const assetManifest = normalizeClientAssetManifest(options.assetManifest);
+  const packageImports = options.packageImports instanceof Map
+    ? options.packageImports
+    : new Map(Object.entries(options.packageImports ?? {}));
 
   return function assetResolver(moduleId) {
     if (typeof moduleId !== "string" || moduleId.length === 0) {
       return null;
     }
 
+    if (packageImports.has(moduleId)) {
+      return packageImports.get(moduleId);
+    }
+
     let relativeClientModule = null;
     if (path.isAbsolute(moduleId) && !isVirtualClientModuleId(moduleId)) {
       relativeClientModule = toClientModuleRelativePath(projectRoot, moduleId);
@@ -1220,6 +1386,7 @@ export function normalizeHydrationDataForClient(
   hydrationData,
   projectRoot = null,
   additionalClientImports = [],
+  assetResolver = null,
 ) {
   if (!hydrationData || typeof hydrationData !== "object") {
     return hydrationData ?? null;
@@ -1256,7 +1423,9 @@ export function normalizeHydrationDataForClient(
   const clientImports = [...new Set([
     ...(Array.isArray(hydrationData.clientImports) ? hydrationData.clientImports : []),
     ...(Array.isArray(additionalClientImports) ? additionalClientImports : []),
-  ].filter((value) => typeof value === "string" && value.length > 0))];
+  ]
+    .map((value) => typeof assetResolver === "function" ? assetResolver(value) ?? value : value)
+    .filter((value) => typeof value === "string" && value.length > 0))];
 
   Object.defineProperties(normalizedHydrationData, {
     payload: {
@@ -1786,10 +1955,15 @@ async function bundleClientAssets(projectRoot, options = {}) {
   const scriptAssetRecords = [];
   let nextRollupCache = options.rollupCache ?? null;
   if (Object.keys(inputEntries).length > 0) {
-    const sharedVendorSpecifiers = await collectClientVendorSpecifiers(projectRoot, [], {
-      mode,
-      entryClientModules: [...entryClientModules],
-    });
+    const sharedVendorSpecifiers = [...new Set([
+      ...await collectClientVendorSpecifiers(projectRoot, [], {
+        mode,
+        entryClientModules: [...entryClientModules],
+      }),
+      ...(Array.isArray(options.additionalVendorSpecifiers)
+        ? options.additionalVendorSpecifiers.filter((specifier) => isBareSpecifier(specifier))
+        : []),
+    ])].sort();
     const sharedRuntime = await buildSharedVendorRuntime(projectRoot, mode, {
       additionalEntrySpecifiers: sharedVendorSpecifiers,
     });
@@ -2227,6 +2401,9 @@ export function normalizeClientAssetManifest(manifest) {
     chunks: Array.isArray(manifest.chunks) ? manifest.chunks : [],
     styles: Array.isArray(manifest.styles) ? manifest.styles : [],
     resources: Array.isArray(manifest.resources) ? manifest.resources : [],
+    sharedImports: manifest.sharedImports && typeof manifest.sharedImports === "object"
+      ? manifest.sharedImports
+      : {},
     serverAssetImportsByEntry:
       manifest.serverAssetImportsByEntry && typeof manifest.serverAssetImportsByEntry === "object"
         ? manifest.serverAssetImportsByEntry

package/src/compiler.js

@@ -19,6 +19,7 @@ import { ensureDirectory } from "./fs-utils.js";
 
 const MODULE_SPECIFIER_PATTERN =
   /\b(?:import|export)\s+(?:[^"']*?\s+from\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+const CSS_DEPENDENCY_PATTERN = /(?:@import\s+(?:url\(\s*)?["']([^"']+)["']\s*\)?|url\(\s*["']?([^"')]+)["']?\s*\))/g;
 const RESOLVABLE_IMPORT_EXTENSIONS = [
   ...MODULE_EXTENSIONS,
   ...STATIC_ASSET_EXTENSIONS,
@@ -497,7 +498,8 @@ function createStaticAssetStubSource(relativeAssetPath, mode, target = "server",
 }
 
 async function resolveImportPath(importerPath, specifier) {
-  const basePath = path.resolve(path.dirname(importerPath), specifier);
+  const cleanSpecifier = String(specifier).split("?")[0].split("#")[0];
+  const basePath = path.resolve(path.dirname(importerPath), cleanSpecifier);
   const candidates = [basePath];
 
   if (!hasResolvableImportExtension(basePath)) {
@@ -521,6 +523,29 @@ async function resolveImportPath(importerPath, specifier) {
   return null;
 }
 
+async function collectStaticAssetGraph(entryPath, collected = new Set()) {
+  const normalizedEntryPath = path.resolve(entryPath);
+  if (collected.has(normalizedEntryPath) || !isStaticAssetPath(normalizedEntryPath)) {
+    return collected;
+  }
+
+  collected.add(normalizedEntryPath);
+  if (!isStyleAssetPath(normalizedEntryPath)) {
+    return collected;
+  }
+
+  const source = await fs.readFile(normalizedEntryPath, "utf8");
+  for (const match of source.matchAll(CSS_DEPENDENCY_PATTERN)) {
+    const specifier = match[1] ?? match[2];
+    if (!specifier || !isRelativeSpecifier(specifier)) continue;
+    const resolvedPath = await resolveImportPath(normalizedEntryPath, specifier);
+    if (resolvedPath && isStaticAssetPath(resolvedPath)) {
+      await collectStaticAssetGraph(resolvedPath, collected);
+    }
+  }
+  return collected;
+}
+
 async function loadProjectPathAliases(projectRoot) {
   if (projectPathAliasesCache.has(projectRoot)) return projectPathAliasesCache.get(projectRoot);
   const pending = (async () => {
@@ -660,12 +685,15 @@ async function resolveProjectPackageImport(projectRoot, importerPath, specifier)
     try {
       const packageJson = JSON.parse(await fs.readFile(path.join(packageRoot, "package.json"), "utf8"));
       const exportKey = parsed.subpath ? `./${parsed.subpath}` : ".";
+      const hasExports = packageJson.exports != null;
       let target = resolvePackageExports(packageJson.exports, exportKey)
-        ?? (parsed.subpath
-          ? `./${parsed.subpath}`
-          : typeof packageJson.browser === "string"
-            ? packageJson.browser
-            : packageJson.module ?? packageJson.main);
+        ?? (hasExports
+          ? null
+          : parsed.subpath
+            ? `./${parsed.subpath}`
+            : typeof packageJson.browser === "string"
+              ? packageJson.browser
+              : packageJson.module ?? packageJson.main);
       if (target && packageJson.browser && typeof packageJson.browser === "object") {
         const normalizedTarget = target.startsWith("./") ? target : `./${target}`;
         const browserTarget = packageJson.browser[normalizedTarget]
@@ -812,6 +840,7 @@ async function rewriteRelativeSpecifiers({
   staticAssetFiles,
   managedSourceRoots,
   serverExportsByModule,
+  packageImports,
 }) {
   const magicSource = new MagicString(code);
   let didRewrite = false;
@@ -828,8 +857,28 @@ async function rewriteRelativeSpecifiers({
     const aliasedImportPath = isBareSpecifier(specifier)
       ? await resolveProjectMappedImport(projectRoot, sourcePath, specifier)
       : null;
+    const packageImportPath = isBareSpecifier(specifier) && !aliasedImportPath
+      ? await resolveProjectPackageImport(projectRoot, sourcePath, specifier)
+      : null;
+    const packageAssetPath = packageImportPath && isStaticAssetPath(packageImportPath)
+      ? packageImportPath
+      : null;
 
-    if (target === "client" && isBareSpecifier(specifier) && !aliasedImportPath) {
+    if (
+      target === "server"
+      && isBareSpecifier(specifier)
+      && !aliasedImportPath
+      && !packageAssetPath
+    ) {
+      packageImports?.add(specifier);
+    }
+
+    if (
+      target === "client"
+      && isBareSpecifier(specifier)
+      && !aliasedImportPath
+      && !packageAssetPath
+    ) {
       const sourceMetadata = moduleMetadata.get(sourcePath) ?? {
         moduleImports: new Set(),
         vendorImports: new Set(),
@@ -841,11 +890,13 @@ async function rewriteRelativeSpecifiers({
       continue;
     }
 
-    if (!isRelativeSpecifier(specifier) && !aliasedImportPath) {
+    if (!isRelativeSpecifier(specifier) && !aliasedImportPath && !packageAssetPath) {
       continue;
     }
 
-    const resolvedImportPath = aliasedImportPath ?? await resolveImportPath(sourcePath, specifier);
+    const resolvedImportPath = packageAssetPath
+      ?? aliasedImportPath
+      ?? await resolveImportPath(sourcePath, specifier);
     if (!resolvedImportPath) {
       continue;
     }
@@ -875,7 +926,10 @@ async function rewriteRelativeSpecifiers({
         );
       }
     } else if (isStaticAssetPath(resolvedImportPath)) {
-      staticAssetFiles?.add(resolvedImportPath);
+      const staticAssetGraph = await collectStaticAssetGraph(resolvedImportPath);
+      for (const staticAssetPath of staticAssetGraph) {
+        staticAssetFiles?.add(staticAssetPath);
+      }
       const relativeAssetPath = toOutputRelativePath(projectRoot, resolvedImportPath);
       const assetOutputPath = path.join(outputRoot, relativeAssetPath);
       const stubOutputPath = `${assetOutputPath}.mjs`;
@@ -888,8 +942,14 @@ async function rewriteRelativeSpecifiers({
       );
 
       if (target === "client") {
-        await ensureDirectory(path.dirname(assetOutputPath));
-        await fs.copyFile(resolvedImportPath, assetOutputPath);
+        for (const staticAssetPath of staticAssetGraph) {
+          const staticAssetOutputPath = path.join(
+            outputRoot,
+            toOutputRelativePath(projectRoot, staticAssetPath),
+          );
+          await ensureDirectory(path.dirname(staticAssetOutputPath));
+          await fs.copyFile(staticAssetPath, staticAssetOutputPath);
+        }
         const sourceMetadata = moduleMetadata.get(sourcePath) ?? {
           moduleImports: new Set(),
           vendorImports: new Set(),
@@ -1102,6 +1162,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
   const staticAssetFiles = new Set();
   const moduleMetadata = new Map();
   const serverExportsByModule = new Map();
+  const packageImports = new Set();
   const serverImportQuery = target === "server" && mode === "development"
     ? `t=${Date.now()}`
     : null;
@@ -1171,6 +1232,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
       staticAssetFiles,
       managedSourceRoots,
       serverExportsByModule,
+      packageImports,
     });
 
     await fs.writeFile(outputPath, rewritten.code, "utf8");
@@ -1200,6 +1262,7 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
     entrypoint: await compileModule(entryPath),
     outputRoot,
     sourceFiles: [...new Set([...visited.keys(), ...staticAssetFiles])],
+    packageImports: [...packageImports].sort(),
   };
 }
 
@@ -1239,8 +1302,6 @@ export async function compileModuleGraph(entryPath, options = {}) {
   }
 }
 
-const CSS_DEPENDENCY_PATTERN = /(?:@import\s+(?:url\(\s*)?["']([^"']+)["']\s*\)?|url\(\s*["']?([^"')]+)["']?\s*\))/g;
-
 function normalizeProjectRelativePath(projectRoot, filePath) {
   return toOutputRelativePath(projectRoot, filePath).split(path.sep).join("/");
 }
@@ -1266,6 +1327,7 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
   const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
   const visited = new Set();
   const boundaries = new Set();
+  const packageBoundaries = new Map();
   const styles = new Set();
   const assets = new Set();
 
@@ -1374,7 +1436,10 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
       if (!resolved) continue;
       if (shouldCompileModule(resolved)) {
         if (isBareSpecifier(specifier) && aliasResolved == null) {
-          if (componentImportSpecifiers.has(specifier)) boundaries.add(resolved);
+          if (componentImportSpecifiers.has(specifier)) {
+            boundaries.add(resolved);
+            packageBoundaries.set(specifier, resolved);
+          }
         } else {
           await visit(resolved, true);
         }
@@ -1390,6 +1455,9 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
   for (const entryPath of entryPaths) await visit(entryPath);
   return {
     clientBoundaries: [...boundaries].sort(),
+    packageClientBoundaries: [...packageBoundaries]
+      .map(([specifier, sourcePath]) => ({ specifier, sourcePath }))
+      .sort((left, right) => left.specifier.localeCompare(right.specifier)),
     styles: [...styles].sort(),
     assets: [...assets].sort(),
     sourceFiles: [...visited].sort(),
@@ -1406,8 +1474,13 @@ export async function emitClientStaticAssets(assetPaths, options = {}) {
   const outputRoot = getTypedOutputRoot(projectRoot, mode, "client");
   const emitted = [];
 
+  const expandedAssetPaths = new Set();
   for (const assetPath of new Set(assetPaths ?? [])) {
     if (!isStaticAssetPath(assetPath)) continue;
+    await collectStaticAssetGraph(assetPath, expandedAssetPaths);
+  }
+
+  for (const assetPath of expandedAssetPaths) {
     const relativePath = normalizeProjectRelativePath(projectRoot, assetPath);
     const outputPath = path.join(outputRoot, relativePath.split("/").join(path.sep));
     await ensureDirectory(path.dirname(outputPath));

package/src/deployment-runtime.js

@@ -13,6 +13,7 @@ import {
 import {
   collectTransitiveAssetPreloads,
   collectTransitiveStyleUrls,
+  canonicalizePackageModuleId,
   createAssetResolver,
   createHydrationBootstrap,
   createStaticAssetPublicUrlMap,
@@ -46,6 +47,20 @@ import {
   resolveEvolitExtensions,
   runRequestExtensions,
 } from "./extensions.js";
+
+function isBarePackageModuleId(value) {
+  return typeof value === "string"
+    && value.length > 0
+    && !value.startsWith(".")
+    && !value.startsWith("/")
+    && !value.startsWith("@/")
+    && !value.startsWith("#")
+    && !value.startsWith("file:")
+    && !value.startsWith("node:")
+    && !value.startsWith("data:")
+    && !value.startsWith("http:")
+    && !value.startsWith("https:");
+}
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
   [".svg", "image/svg+xml"],
@@ -240,27 +255,32 @@ export async function createRequestRenderer({
   extensions = [],
 }) {
   let currentAssetManifest = normalizeClientAssetManifest(assetManifest);
+  const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
+  const extensionClientSpecifiers = extensionClientDescriptors.map((descriptor) => descriptor.module);
+  const packageClientSpecifiers = new Set(extensionClientSpecifiers);
+  const persistedSharedImports = currentAssetManifest?.sharedImports ?? {};
+  const packageImports = new Map(Object.entries(persistedSharedImports));
+  const packageImportUrls = new Set(packageImports.values());
   let currentAssetResolver = createAssetResolver(projectRoot, {
     assetManifest: currentAssetManifest,
+    packageImports,
   });
-  const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
-  const extensionClientSpecifiers = extensionClientDescriptors.map((descriptor) => descriptor.module);
-  const sharedVendorOptions = { additionalEntrySpecifiers: extensionClientSpecifiers };
-  let currentHydrationModuleUrl = await resolveSharedVendorModuleUrl(
-    projectRoot,
-    mode,
+  const sharedVendorOptions = { additionalEntrySpecifiers: [...packageClientSpecifiers] };
+  const resolveSharedModuleUrl = (specifier, options = sharedVendorOptions) => (
+    persistedSharedImports[specifier]
+    ?? (mode === "development"
+      ? resolveSharedVendorModuleUrl(projectRoot, mode, specifier, options)
+      : null)
+  );
+  let currentHydrationModuleUrl = await resolveSharedModuleUrl(
     "@litsx/ssr/hydration",
-    sharedVendorOptions,
   );
-  let currentNavigationModuleUrl = await resolveSharedVendorModuleUrl(
-    projectRoot,
-    mode,
+  let currentNavigationModuleUrl = await resolveSharedModuleUrl(
     "evolit/navigation",
-    sharedVendorOptions,
   );
   let currentNavigationExtensions = await Promise.all(extensionClientDescriptors.map(async (descriptor) => ({
     ...descriptor,
-    module: await resolveSharedVendorModuleUrl(projectRoot, mode, descriptor.module, sharedVendorOptions),
+    module: await resolveSharedModuleUrl(descriptor.module),
   })));
   const devBundledEntries = new Set();
   const devPreparedClientModules = new Set();
@@ -359,11 +379,13 @@ export async function createRequestRenderer({
       retainOutputPaths: devPreviousAssetOutputPaths,
       serverAssetImportsByEntry: devServerAssetImportsByEntry,
       clientBoundariesByEntry: devClientBoundariesByEntry,
+      additionalVendorSpecifiers: [...packageClientSpecifiers],
     });
     currentAssetManifest = bundledClientAssets.manifest;
     devPreviousAssetOutputPaths = new Set();
     currentAssetResolver = createAssetResolver(projectRoot, {
       assetManifest: currentAssetManifest,
+      packageImports,
     });
     currentHydrationModuleUrl = await resolveSharedVendorModuleUrl(
       projectRoot,
@@ -405,6 +427,7 @@ export async function createRequestRenderer({
     return (
       typeof currentAssetResolver(moduleId) === "string"
       || typeof currentAssetManifest?.byPublicPath?.[moduleId] === "string"
+      || packageImportUrls.has(moduleId)
     );
   }
 
@@ -447,6 +470,46 @@ export async function createRequestRenderer({
     ].filter((moduleId) => typeof moduleId === "string" && moduleId.length > 0))];
     const unresolvedModules = [];
     for (const moduleId of renderedModules) {
+      const packageSpecifier = isBarePackageModuleId(moduleId)
+        ? moduleId
+        : await canonicalizePackageModuleId(projectRoot, moduleId, packageClientSpecifiers);
+      if (packageSpecifier) {
+        packageClientSpecifiers.add(packageSpecifier);
+        sharedVendorOptions.additionalEntrySpecifiers = [...packageClientSpecifiers].sort();
+        const publicUrl = packageImports.get(packageSpecifier) ?? await resolveSharedModuleUrl(
+          packageSpecifier,
+          {
+            assetManifest: currentAssetManifest,
+            entryClientModules: [...devBundledEntries],
+            additionalEntrySpecifiers: sharedVendorOptions.additionalEntrySpecifiers,
+          },
+        );
+        if (publicUrl) {
+          const previousPublicUrl = currentAssetResolver(moduleId);
+          packageImports.set(packageSpecifier, publicUrl);
+          packageImportUrls.add(publicUrl);
+          currentAssetResolver = createAssetResolver(projectRoot, {
+            assetManifest: currentAssetManifest,
+            packageImports,
+          });
+          for (const root of result.hydrationData?.roots ?? []) {
+            if (root?.moduleId === moduleId) root.moduleId = packageSpecifier;
+          }
+          if (Array.isArray(result.clientImports)) {
+            result.clientImports = result.clientImports.map((value) => (
+              value === moduleId || value === previousPublicUrl ? publicUrl : value
+            ));
+          }
+          if (Array.isArray(result.hydrationData?.clientImports)) {
+            result.hydrationData.clientImports = result.hydrationData.clientImports.map((value) => (
+              value === moduleId || value === previousPublicUrl ? publicUrl : value
+            ));
+          }
+          continue;
+        }
+        unresolvedModules.push(moduleId);
+        continue;
+      }
       const sourcePath = await resolveRenderedClientSource(moduleId, routeResult);
       if (sourcePath) devKnownClientBoundarySources.add(path.resolve(sourcePath));
       if (hasClientArtifact(moduleId)) continue;
@@ -575,6 +638,7 @@ export async function createRequestRenderer({
           result.hydrationData,
           projectRoot,
           resolveHydrationRootClientImports(result.hydrationData, currentAssetResolver),
+          currentAssetResolver,
         ),
         assetResolver(moduleId) {
           return currentAssetResolver(moduleId);
@@ -591,9 +655,10 @@ export async function createRequestRenderer({
           result.hydrationData,
           projectRoot,
           resolveHydrationRootClientImports(
-              result.hydrationData,
-              currentAssetResolver,
-            ),
+            result.hydrationData,
+            currentAssetResolver,
+          ),
+          currentAssetResolver,
         ),
       );
     },
@@ -678,6 +743,7 @@ export async function createRequestRenderer({
           currentAssetManifest = null;
           currentAssetResolver = createAssetResolver(projectRoot, {
             assetManifest: currentAssetManifest,
+            packageImports,
           });
           devRollupCache = null;
           for (const clientModule of affectedClientModules) {
@@ -726,11 +792,24 @@ export async function createRequestRenderer({
       ])));
       const inventory = {
         clientBoundaries: [...new Set([...inventoriesByEntry.values()].flatMap((entry) => entry.clientBoundaries))].sort(),
+        packageClientBoundaries: [...new Map(
+          [...inventoriesByEntry.values()]
+            .flatMap((entry) => entry.packageClientBoundaries ?? [])
+            .map((entry) => [entry.specifier, entry]),
+        ).values()].sort((left, right) => left.specifier.localeCompare(right.specifier)),
         styles: [...new Set([...inventoriesByEntry.values()].flatMap((entry) => entry.styles))].sort(),
         assets: [...new Set([...inventoriesByEntry.values()].flatMap((entry) => entry.assets))].sort(),
         sourceFiles: [...new Set([...inventoriesByEntry.values()].flatMap((entry) => entry.sourceFiles))].sort(),
       };
-      const clientBoundaries = inventory.clientBoundaries;
+      const packageBoundarySources = new Set(
+        inventory.packageClientBoundaries.map((entry) => entry.sourcePath),
+      );
+      for (const packageBoundary of inventory.packageClientBoundaries) {
+        packageClientSpecifiers.add(packageBoundary.specifier);
+      }
+      sharedVendorOptions.additionalEntrySpecifiers = [...packageClientSpecifiers].sort();
+      const clientBoundaries = inventory.clientBoundaries
+        .filter((clientBoundary) => !packageBoundarySources.has(clientBoundary));
       for (const clientBoundary of clientBoundaries) {
         devKnownClientBoundarySources.add(path.resolve(clientBoundary));
       }
@@ -747,6 +826,8 @@ export async function createRequestRenderer({
           assets: entryInventory.assets.map((filePath) => getClientStaticAssetModule(projectRoot, filePath)),
         };
         devClientBoundariesByEntry[entryKey] = entryInventory.clientBoundaries
+          .filter((filePath) => !(entryInventory.packageClientBoundaries ?? [])
+            .some((packageBoundary) => packageBoundary.sourcePath === filePath))
           .map((filePath) => getCompiledClientModule(projectRoot, filePath))
           .sort();
       }