evolit 0.2.1 → 0.4.0

package/README.md

@@ -46,6 +46,26 @@ 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.
 
+### Interpolated dynamic imports
+
+Relative dynamic imports may use a template literal when every possible module can be discovered
+from the literal path at build time:
+
+```tsx
+const module = await import(`./templates/${locale}/${name}.tsx`);
+```
+
+Evolit treats each interpolation as one wildcard that matches a single path segment. The example
+above discovers `./templates/*/*.tsx`, compiles every matching module, and emits a finite runtime
+dispatcher whose cases preserve the original source specifiers. Interpolations never cross a `/`,
+and there is no framework-imposed candidate limit.
+
+The template must be relative, end in a supported authored module extension, and match at least one
+module during compilation. A runtime value that was not among the discovered candidates rejects the
+import. Development watches the matched directory tree, so adding a new candidate invalidates the
+affected graph. Arbitrary computed specifiers that do not use this template-literal form remain
+outside the statically discoverable graph.
+
 ### Package CSS and static assets
 
 Applications can import stylesheets exposed through package `exports` in the same way as local
@@ -301,6 +321,94 @@ server components and helpers that do not receive route props directly. It retur
 Reading `getRouteState().url` has the same dynamic-rendering semantics as `requestUrl()`; reading
 `params` and `searchParams` participates in the normal segment-cache key tracking.
 
+## LitSX compiler integrations
+
+`evolit.config.js` can configure the native LitSX compiler and register build-tool-neutral LitSX
+integrations. The same declaration is used by development, SSR, hydration, production builds and
+the standalone runtime:
+
+```js
+import { litsxUnoCss } from "@litsx/unocss";
+import { defineEvolitConfig } from "evolit/litsx";
+
+export default defineEvolitConfig({
+  litsx: {
+    compiler: {
+      sourceMaps: true,
+    },
+    integrations: [litsxUnoCss()],
+  },
+});
+```
+
+This is the complete Evolit + UnoCSS setup. The application does not coordinate compiler plugins,
+virtual modules, generation, finalization or global CSS links, and it does not need Vite or
+PostCSS. `@litsx/unocss` remains the owner of candidate extraction and CSS generation; Evolit only
+executes its neutral LitSX lifecycle.
+
+`compiler` accepts the public `TransformLitsxOptions` surface except the values Evolit must own for
+correct server and browser graphs. Evolit always supplies the current `filename`, selects `ssr` per
+target and forces native lowering with `reactCompat: false`; `compiler.sourceMaps` can override the
+existing per-pipeline default without changing applications that omit `litsx`.
+Authoring and output plugins contributed by the application and integrations are composed in
+declaration order rather than replacing framework invariants.
+
+An integration is a descriptor with a unique `name` and `create(context)` method. Each call to
+`create` belongs to exactly one development server, build or standalone runtime, so mutable caches
+must live on the returned instance, never on the descriptor. An instance can contribute:
+
+- `compiler`: native compiler options, including authoring and output plugins.
+- `resolveModule`: sources for integration-owned virtual modules in both server and browser graphs.
+- `processModule`: post-processing, observable dependencies and preliminary outputs for a compiled
+  module.
+- `finalize`: graph-wide assets, styles or modules after every reachable module is known.
+- `invalidate` and `forget`: configuration/dependency refresh and removal of stale module state.
+- `dispose`: idempotent cleanup when the owning server, build or runtime closes.
+
+Declared outputs use stable IDs unique within the pipeline and one of `asset`, `module` or `style`. A module
+may expose a safe `virtual:` specifier; a style with `document: true` is content-hashed, included in
+the client asset manifest and linked once in the document. Evolit publishes a generation only after
+every integration finalizes successfully, so a failed generation cannot expose a partial mix of
+old and new assets.
+
+In development, dependencies reported by compiler plugins and lifecycle hooks are watched together
+with application modules. Invalidating a dependency advances the integration generation, evicts
+affected compiled modules and calls `forget` for modules that leave the graph. Configuration reload
+therefore removes obsolete results instead of accumulating them. Hook failures identify the
+integration, lifecycle phase and relevant module in development; production errors keep the same
+context while redacting project-local absolute paths.
+
+For native Shadow DOM, `@litsx/unocss` serializes component preflight inside each Declarative Shadow
+Root, preserves authored `Component.styles` before generated utilities, and emits the document
+theme/custom-property layers once. Those document variables inherit through Shadow Roots and the
+browser hydrates the server result without switching to `react-compat`.
+
+## Server Setup
+
+Server integrations that need one-time application setup can be registered with
+`server.setup`. A module specifier is compiled as part of the server graph, so the
+setup may be authored in JavaScript or TypeScript:
+
+```js
+// evolit.config.js
+export default {
+  server: {
+    setup: "./src/server/setup.ts",
+  },
+};
+```
+
+The module exports `setup` (or a default function). Evolit invokes it once per
+runtime and once before build-time prerendering with `{ projectRoot, mode }`.
+It may return a cleanup function or `{ dispose() }`; runtime cleanup runs from
+`runtime.close()`.
+
+When `@litsx/urql` is installed, Evolit opens its SSR resource around the whole
+route render and supplies `{ request, responseHeaders }`. Request-derived URQL
+configuration therefore stays isolated per render, extracted SSR data is read
+before the scope closes, and integration response headers are included before
+the response is cached.
+
 ## Extensions
 
 Optional integrations are configured explicitly in `evolit.config.js`. Core only coordinates their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -34,6 +34,10 @@
       "browser": "./src/extensions-client.js",
       "default": "./src/extensions.js"
     },
+    "./litsx": {
+      "types": "./src/litsx-pipeline.d.ts",
+      "default": "./src/litsx-pipeline.js"
+    },
     "./internal/development-hot": "./src/development-hot-client.js"
   },
   "scripts": {
@@ -71,7 +75,7 @@
     "ws": "^8.18.3"
   },
   "peerDependencies": {
-    "@litsx/urql": "^0.3.0"
+    "@litsx/urql": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@litsx/urql": {
@@ -79,8 +83,10 @@
     }
   },
   "devDependencies": {
+    "@litsx/unocss": "1.0.0-next.8",
     "@playwright/test": "^1.62.0",
     "@webcomponents/scoped-custom-element-registry": "^0.0.10",
+    "unocss": "66.8.1",
     "vite": "^8.1.5"
   }
 }

package/src/build.js

@@ -51,7 +51,14 @@ import {
 import { serializeRouteCachePolicy } from "./route-config.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { ensureDirectory, writeJson } from "./fs-utils.js";
-import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
+import {
+  appendSsrUrqlData,
+  applySsrUrqlRequestContext,
+  createSsrUrqlRequestContext,
+  runWithOptionalSsrUrqlScope,
+} from "./urql-ssr.js";
+import { runServerSetup } from "./server-setup.js";
+import { createLitsxPipeline, mergeLitsxAssetsIntoManifest } from "./litsx-pipeline.js";
 
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
@@ -157,6 +164,20 @@ async function writeDeploymentRuntimeEntry(buildRoot) {
 
 export async function buildProject(projectRoot, options = {}) {
   const evolitConfig = await loadEvolitConfig(projectRoot);
+  const litsxPipeline = await createLitsxPipeline({
+    projectRoot,
+    mode: "production",
+    config: evolitConfig,
+  });
+  let serverSetupCleanup = null;
+  let buildError = null;
+  try {
+    serverSetupCleanup = await runServerSetup({
+      projectRoot,
+      mode: "production",
+      evolitConfig,
+      litsxPipeline,
+    });
   const extensions = resolveEvolitExtensions(evolitConfig);
   const extensionClientDescriptors = getExtensionClientDescriptors(extensions);
   const packageClientSpecifiers = new Set(
@@ -183,6 +204,7 @@ export async function buildProject(projectRoot, options = {}) {
       sourceMaps: false,
       ssr: true,
       target: "server",
+      litsxPipeline,
     });
     result.packageImports.forEach((specifier) => ssrPackageImports.add(specifier));
     return result;
@@ -191,7 +213,7 @@ export async function buildProject(projectRoot, options = {}) {
   function getEntryInventory(entryPath) {
     let inventory = inventoriesBySourceEntry.get(entryPath);
     if (!inventory) {
-      inventory = collectClientGraphInventory([entryPath], { projectRoot });
+      inventory = collectClientGraphInventory([entryPath], { projectRoot, litsxPipeline });
       inventoriesBySourceEntry.set(entryPath, inventory);
     }
     return inventory;
@@ -205,6 +227,7 @@ export async function buildProject(projectRoot, options = {}) {
       mode: "production",
       sourceMaps: true,
       target: "client",
+      litsxPipeline,
     });
     clientModule = path.relative(clientBuild.outputRoot, clientBuild.entrypoint)
       .split(path.sep)
@@ -224,6 +247,7 @@ export async function buildProject(projectRoot, options = {}) {
       mode: "production",
       ssr: true,
       target: "server",
+      litsxPipeline,
     });
     const methods = Object.keys(handlerModule)
       .filter((name) => /^[A-Z]+$/.test(name) && typeof handlerModule[name] === "function")
@@ -334,18 +358,20 @@ export async function buildProject(projectRoot, options = {}) {
   }
 
   sharedVendorOptions.additionalEntrySpecifiers = [...packageClientSpecifiers].sort();
-  const clientAssets = await emitBundledClientAssets(projectRoot, {
+  let clientAssets = await emitBundledClientAssets(projectRoot, {
     entryClientModules,
     additionalVendorSpecifiers: sharedVendorOptions.additionalEntrySpecifiers,
     serverAssetImportsByEntry,
     clientBoundariesByEntry,
   });
+  const integrationOutputs = await litsxPipeline?.finalize({
+    routes,
+    routeHandlers,
+  });
+  clientAssets = mergeLitsxAssetsIntoManifest(clientAssets, integrationOutputs);
   const staticAssetPublicUrls = createStaticAssetPublicUrlMap(clientAssets);
   await rewriteServerAssetPlaceholders(projectRoot, clientAssets);
 
-  const routeResolver = await createRouteResolver(projectRoot, "production", {
-    staticAssetPublicUrls,
-  });
   const sharedRuntime = await buildSharedVendorRuntime(projectRoot, "production", sharedVendorOptions);
   clientAssets.sharedImports = { ...sharedRuntime.imports };
   const packageImports = sharedRuntime.imports;
@@ -353,6 +379,11 @@ export async function buildProject(projectRoot, options = {}) {
     assetManifest: clientAssets,
     packageImports,
   });
+  const routeResolver = await createRouteResolver(projectRoot, "production", {
+    staticAssetPublicUrls,
+    assetResolver,
+    litsxPipeline,
+  });
   const hydrationModuleUrl = await resolveSharedVendorModuleUrl(
     projectRoot,
     "production",
@@ -412,7 +443,21 @@ export async function buildProject(projectRoot, options = {}) {
           }
           continue;
         }
-        if (assetResolver(moduleId) || clientAssets.byPublicPath?.[moduleId]) continue;
+        const directPublicUrl = assetResolver(moduleId)
+          ?? (clientAssets.byPublicPath?.[moduleId] ? moduleId : null);
+        if (directPublicUrl) {
+          if (Array.isArray(result.clientImports)) {
+            result.clientImports = result.clientImports.map((value) => (
+              value === moduleId ? directPublicUrl : value
+            ));
+          }
+          if (Array.isArray(result.hydrationData?.clientImports)) {
+            result.hydrationData.clientImports = result.hydrationData.clientImports.map((value) => (
+              value === moduleId ? directPublicUrl : value
+            ));
+          }
+          continue;
+        }
         const importerPath = routeResult.boundaryModule
           ?? routeResult.route?.page
           ?? path.join(projectRoot, "app", "page.jsx");
@@ -462,6 +507,7 @@ export async function buildProject(projectRoot, options = {}) {
         ])]
         : [];
       const styleUrls = [...new Set([
+        ...(clientAssets.documentStyles ?? []),
         ...collectTransitiveStyleUrls(clientImports, clientAssets),
         ...resolveServerStyleUrls(routeResult, projectRoot, clientAssets),
       ])];
@@ -541,23 +587,32 @@ export async function buildProject(projectRoot, options = {}) {
       seenPrerenderTargets.add(targetPathname);
 
       const targetRequest = new Request(`http://evolit.local${targetPathname}`);
-      const { routeResult, response } = await runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+      const urqlRequestContext = createSsrUrqlRequestContext(targetRequest);
+      const { routeResult, response } = await runWithOptionalSsrUrqlScope(urqlRequestContext, async (urqlAdapter) => {
         const resolvedRouteResult = await routeResolver.resolveRequest(targetRequest);
         if (resolvedRouteResult.type !== "route" || resolvedRouteResult.cachePolicy.mode === "dynamic") {
           return { routeResult: resolvedRouteResult, response: null };
         }
 
         const renderedResponse = await renderRouteTreeWithAdapter(resolvedRouteResult, ssrAdapter);
+        const responseWithData = urqlAdapter
+          ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
+          : renderedResponse;
         return {
           routeResult: resolvedRouteResult,
-          response: urqlAdapter
-            ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
-            : renderedResponse,
+          response: applySsrUrqlRequestContext(
+            resolvedRouteResult,
+            responseWithData,
+            urqlRequestContext,
+          ),
         };
       });
       if (!response) {
         continue;
       }
+      if (routeResult.cachePolicy.mode === "dynamic") {
+        continue;
+      }
       if (response.status !== 200) {
         continue;
       }
@@ -630,6 +685,11 @@ export async function buildProject(projectRoot, options = {}) {
         cache: sortedRouteCache.find((entry) => entry.pathname === artifact.routePathname)?.cache
           ?? "static",
       })),
+      ...(integrationOutputs?.assets ?? []).map((asset) => ({
+        kind: asset.kind,
+        outputPath: toBuildRelativePath(projectRoot, asset.outputPath),
+        integration: asset.integration,
+      })),
     ],
   };
   const manifestPath = path.join(buildRoot, MANIFEST_FILENAME);
@@ -657,4 +717,21 @@ export async function buildProject(projectRoot, options = {}) {
   await writeJson(path.join(buildRoot, DEPLOY_SERVER_MANIFEST_FILENAME), deployServer);
 
   return manifestPath;
+  } catch (error) {
+    buildError = error;
+    throw error;
+  } finally {
+    let cleanupError = null;
+    try {
+      await serverSetupCleanup?.();
+    } catch (error) {
+      cleanupError = error;
+    }
+    try {
+      await litsxPipeline?.dispose();
+    } catch (error) {
+      cleanupError ??= error;
+    }
+    if (!buildError && cleanupError) throw cleanupError;
+  }
 }

package/src/client-assets.js

@@ -2483,6 +2483,7 @@ export function normalizeClientAssetManifest(manifest) {
       manifest.clientBoundariesByEntry && typeof manifest.clientBoundariesByEntry === "object"
         ? manifest.clientBoundariesByEntry
         : {},
+    documentStyles: Array.isArray(manifest.documentStyles) ? manifest.documentStyles : [],
     assets: manifest.assets,
   };
 }