evolit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/route-segments.js

@@ -0,0 +1,272 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { html } from "lit";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+
+const SEGMENT_MARKER_PREFIX = "evolit:segment";
+const SEGMENT_MARKER_PATTERN = /<!--evolit:segment:(start|end):([A-Za-z0-9_-]+)-->/g;
+
+function normalizeModulePath(projectRoot, modulePath) {
+  return path.relative(projectRoot, modulePath).split(path.sep).join("/");
+}
+
+function createSegmentId(kind, modulePath, projectRoot) {
+  const relativeModulePath = normalizeModulePath(projectRoot, modulePath);
+  const digest = crypto
+    .createHash("sha256")
+    .update(`${kind}:${relativeModulePath}`)
+    .digest("base64url")
+    .slice(0, 12);
+
+  return `${kind}-${digest}`;
+}
+
+export function createRouteSegmentPlan(route, projectRoot, options = {}) {
+  const layouts = Array.isArray(route?.layouts) ? route.layouts : [];
+  const segments = layouts.map((modulePath, index) => ({
+    id: createSegmentId("layout", modulePath, projectRoot),
+    kind: "layout",
+    depth: index,
+    modulePath: normalizeModulePath(projectRoot, modulePath),
+  }));
+
+  if (typeof route?.page === "string") {
+    segments.push({
+      id: createSegmentId("page", route.page, projectRoot),
+      kind: "page",
+      depth: segments.length,
+      modulePath: normalizeModulePath(projectRoot, route.page),
+    });
+  } else if (typeof options.boundaryModule === "string") {
+    segments.push({
+      id: createSegmentId("boundary", options.boundaryModule, projectRoot),
+      kind: "boundary",
+      depth: segments.length,
+      modulePath: normalizeModulePath(projectRoot, options.boundaryModule),
+    });
+  }
+
+  return segments;
+}
+
+export function wrapRouteSegment(segment, value) {
+  if (!segment?.id) {
+    return value;
+  }
+
+  const startMarker = `<!--${SEGMENT_MARKER_PREFIX}:start:${segment.id}-->`;
+  const endMarker = `<!--${SEGMENT_MARKER_PREFIX}:end:${segment.id}-->`;
+  if (typeof value === "string") {
+    return `${startMarker}${value}${endMarker}`;
+  }
+
+  return html`${unsafeHTML(startMarker)}${value}${unsafeHTML(endMarker)}`;
+}
+
+export function createRouteSegmentPayload(routeResult) {
+  const segments = Array.isArray(routeResult?.segments) ? routeResult.segments : [];
+  if (segments.length === 0) {
+    return null;
+  }
+
+  return {
+    version: 1,
+    url: routeResult.cacheKey ?? routeResult.route?.pathname ?? null,
+    pathname: routeResult.cacheKey?.split("?")[0] ?? routeResult.route?.pathname ?? null,
+    cachePolicy: routeResult.cachePolicy
+      ? {
+        mode: routeResult.cachePolicy.mode,
+        ...(routeResult.cachePolicy.mode === "revalidate"
+          ? { ttlSeconds: routeResult.cachePolicy.ttlSeconds }
+          : {}),
+      }
+      : null,
+    segments: segments.map(({ id, kind, depth, modulePath }) => ({
+      id,
+      kind,
+      depth,
+      modulePath,
+    })),
+  };
+}
+
+export function renderRouteSegmentPayload(payload, scriptId = "__EVOLIT_ROUTE__") {
+  if (!payload) {
+    return "";
+  }
+
+  const serialized = JSON.stringify(payload)
+    .replaceAll("<", "\\u003C")
+    .replaceAll(">", "\\u003E")
+    .replaceAll("&", "\\u0026");
+  return `<script type="application/json" id="${scriptId}">${serialized}</script>`;
+}
+
+/**
+ * Extracts every rendered projection of every route segment from a composed
+ * SSR document. The marker protocol belongs to Evolit; LitSX only renders the
+ * values that contain the markers.
+ */
+export function extractRouteSegmentArtifacts(documentHtml) {
+  if (typeof documentHtml !== "string" || documentHtml.length === 0) {
+    return new Map();
+  }
+
+  const artifacts = new Map();
+  const openSegments = [];
+  SEGMENT_MARKER_PATTERN.lastIndex = 0;
+
+  for (const match of documentHtml.matchAll(SEGMENT_MARKER_PATTERN)) {
+    const [marker, boundary, segmentId] = match;
+    const markerStart = match.index ?? 0;
+    const markerEnd = markerStart + marker.length;
+
+    if (boundary === "start") {
+      openSegments.push({ segmentId, contentStart: markerEnd });
+      continue;
+    }
+
+    const openIndex = openSegments.map((entry) => entry.segmentId).lastIndexOf(segmentId);
+    if (openIndex < 0) {
+      continue;
+    }
+
+    const [{ contentStart }] = openSegments.splice(openIndex, 1);
+    const projections = artifacts.get(segmentId) ?? [];
+    projections.push({
+      projectionId: `${segmentId}:${projections.length}`,
+      html: documentHtml.slice(contentStart, markerStart),
+    });
+    artifacts.set(segmentId, projections);
+  }
+
+  return artifacts;
+}
+
+export function createRouteSegmentDelta(routeResult, documentHtml) {
+  const payload = createRouteSegmentPayload(routeResult);
+  if (!payload) {
+    return null;
+  }
+
+  const artifacts = extractRouteSegmentArtifacts(documentHtml);
+  return {
+    ...payload,
+    segments: payload.segments.map((segment) => ({
+      ...segment,
+      projections: artifacts.get(segment.id) ?? [],
+    })),
+  };
+}
+
+export function createNavigationResponseFromDocument(response) {
+  if (response?.headers?.location && response.status >= 300 && response.status < 400) {
+    return {
+      ...response,
+      headers: {
+        ...(response.headers ?? {}),
+        "content-type": "application/vnd.evolit.navigation+json; charset=utf-8",
+        "cache-control": "no-store",
+        vary: appendVaryHeader(response.headers?.vary, "accept"),
+      },
+      body: JSON.stringify({
+        version: 1,
+        type: "redirect",
+        location: response.headers.location,
+      }),
+    };
+  }
+
+  if (typeof response?.body !== "string") {
+    return response;
+  }
+
+  const routeMatch = response.body.match(
+    /<script type="application\/json" id="__EVOLIT_ROUTE__">([\s\S]*?)<\/script>/,
+  );
+  if (!routeMatch) {
+    return response;
+  }
+
+  let route;
+  try {
+    route = JSON.parse(routeMatch[1]);
+  } catch {
+    return response;
+  }
+
+  const artifacts = extractRouteSegmentArtifacts(response.body);
+  const hydrationMatch = response.body.match(
+    /<script type="application\/json" id="__LITSX_HYDRATION__">([\s\S]*?)<\/script>/,
+  );
+  const titleMatch = response.body.match(/<title>([\s\S]*?)<\/title>/i);
+  const head = extractRouteHeadMarkup(response.body);
+  const documentState = extractDocumentState(response.body);
+  const headAssets = extractRouteHeadAssets(response.body);
+  const body = JSON.stringify({
+    version: 1,
+    type: "route",
+    url: route.url,
+    route: {
+      ...route,
+      segments: route.segments.map((segment) => ({
+        ...segment,
+        projections: artifacts.get(segment.id) ?? [],
+      })),
+    },
+    ...(titleMatch ? { title: titleMatch[1] } : {}),
+    ...(head != null ? { head } : {}),
+    ...(documentState ? { document: documentState } : {}),
+    headAssets,
+    ...(hydrationMatch ? { hydrationData: JSON.parse(hydrationMatch[1]) } : {}),
+  });
+
+  return {
+    ...response,
+    headers: {
+      ...(response.headers ?? {}),
+      "content-type": "application/vnd.evolit.navigation+json; charset=utf-8",
+      "cache-control": "no-store",
+      vary: appendVaryHeader(response.headers?.vary, "accept"),
+    },
+    body,
+  };
+}
+
+export function extractDocumentState(documentHtml) {
+  if (typeof documentHtml !== "string") return null;
+  const match = documentHtml.match(/<script type="application\/json" id="__EVOLIT_DOCUMENT__">([\s\S]*?)<\/script>/i);
+  if (!match) return null;
+  try { return JSON.parse(match[1]); } catch { return null; }
+}
+
+export function extractRouteHeadMarkup(documentHtml) {
+  if (typeof documentHtml !== "string") return null;
+  const match = documentHtml.match(/<!--evolit:route-head:start-->([\s\S]*?)<!--evolit:route-head:end-->/i);
+  return match?.[1] ?? null;
+}
+
+export function extractRouteHeadAssets(documentHtml) {
+  const assets = { styles: [], preloads: [] };
+  if (typeof documentHtml !== "string") return assets;
+
+  for (const match of documentHtml.matchAll(/<link\b[^>]*>/gi)) {
+    const tag = match[0];
+    const kind = tag.match(/\bdata-evolit-route-asset="([^"]+)"/i)?.[1];
+    const href = tag.match(/\bhref="([^"]+)"/i)?.[1];
+    if (!href) continue;
+    if (kind === "style") assets.styles.push(href);
+    if (kind === "preload") assets.preloads.push(href);
+  }
+
+  return assets;
+}
+
+function appendVaryHeader(value, field) {
+  const fields = String(value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (!fields.some((item) => item.toLowerCase() === field.toLowerCase())) fields.push(field);
+  return fields.join(", ");
+}

package/src/scaffold.js

@@ -49,6 +49,10 @@ export async function scaffoldSite(targetDirectory, options = {}) {
   }
 
   await copyDirectory(TEMPLATE_ROOT, absoluteTargetDirectory);
+  await fs.rename(
+    path.join(absoluteTargetDirectory, "yarnrc.yml.template"),
+    path.join(absoluteTargetDirectory, ".yarnrc.yml"),
+  );
   await writeSitePackageJson(absoluteTargetDirectory, siteName);
   await fs.writeFile(
     path.join(absoluteTargetDirectory, "evolit.config.js"),

package/src/server.js

@@ -2,12 +2,15 @@ import http from "node:http";
 import { watch } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { WebSocketServer, WebSocket } from "ws";
 import { loadEvolitConfig } from "./config.js";
 import { createDeploymentRuntime } from "./deployment-runtime.js";
-import { APP_DIRECTORY, BUILD_DIRECTORY, INTERNAL_DIRECTORY, MANIFEST_FILENAME } from "./constants.js";
+import { BUILD_DIRECTORY, INTERNAL_DIRECTORY, MANIFEST_FILENAME } from "./constants.js";
 import { normalizeClientAssetManifest } from "./client-assets.js";
 import { pathExists, readJson } from "./fs-utils.js";
 import { createDefaultRouteCacheKey, resolveResponseCacheRuntime } from "./response-cache.js";
+import { createDevelopmentEventReporter } from "./development-events.js";
+import { createNavigationResponseFromDocument } from "./route-segments.js";
 
 function getPort(explicitPort) {
   const port = explicitPort ?? process.env.PORT ?? "3000";
@@ -35,22 +38,56 @@ async function writeResponseBody(response, body) {
   response.end();
 }
 
-async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
+const LIVE_RELOAD_PATHNAME = "/_evolit/live-reload";
+
+function getResponseHeader(headers, name) {
+  if (headers?.get) {
+    return headers.get(name);
+  }
+
+  return headers?.[name] ?? headers?.[name.toLowerCase()] ?? null;
+}
+
+function injectLiveReloadSnippet(response) {
+  if (
+    typeof response.body !== "string"
+    || !getResponseHeader(response.headers, "content-type")?.includes("text/html")
+  ) {
+    return response;
+  }
+
+  return {
+    ...response,
+    body: response.body.includes("</body>")
+      ? response.body.replace("</body>", `${createLiveReloadSnippet()}</body>`)
+      : `${response.body}${createLiveReloadSnippet()}`,
+  };
+}
+
+function createLiveReloadSnippet() {
+  return `<script data-evolit-live-reload>const evolitProtocol=window.location.protocol==="https:"?"wss:":"ws:";const evolitSocket=new WebSocket(evolitProtocol+"//"+window.location.host+${JSON.stringify(LIVE_RELOAD_PATHNAME)});evolitSocket.addEventListener("message",({data})=>{if(data==="reload")window.location.reload()});</script>`;
+}
+
+async function createRecursiveDirectoryWatcher(rootDirectory, onChange, options = {}) {
   const watchers = new Map();
+  const shouldIgnorePath = options.shouldIgnorePath ?? (() => false);
   let closed = false;
 
   async function watchDirectory(directory) {
-    if (closed || watchers.has(directory)) {
+    if (closed || watchers.has(directory) || shouldIgnorePath(directory)) {
       return;
     }
 
     let watcher;
     try {
       watcher = watch(directory, (eventType, fileName) => {
-        onChange();
+        const changedPath = fileName ? path.join(directory, String(fileName)) : null;
+        if (!changedPath || !shouldIgnorePath(changedPath)) {
+          onChange(changedPath);
+        }
 
-        if (eventType === "rename" && fileName) {
-          void watchNewDirectory(path.join(directory, fileName));
+        if (eventType === "rename" && changedPath && !shouldIgnorePath(changedPath)) {
+          void watchNewDirectory(changedPath);
         }
       });
     } catch (error) {
@@ -82,6 +119,10 @@ async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
   }
 
   async function watchNewDirectory(candidate) {
+    if (shouldIgnorePath(candidate)) {
+      return;
+    }
+
     try {
       const stat = await fs.stat(candidate);
       if (stat.isDirectory()) {
@@ -107,7 +148,34 @@ async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
   };
 }
 
+function createProjectWatchIgnorePath(projectRoot) {
+  const ignoredDirectoryNames = new Set([
+    "node_modules",
+    INTERNAL_DIRECTORY,
+    ".git",
+  ]);
+
+  return (candidate) => {
+    const relativePath = path.relative(projectRoot, candidate);
+    if (
+      relativePath === ".."
+      || relativePath.startsWith(`..${path.sep}`)
+      || path.isAbsolute(relativePath)
+    ) {
+      return true;
+    }
+
+    return relativePath
+      .split(path.sep)
+      .some((segment) => ignoredDirectoryNames.has(segment));
+  };
+}
+
 async function createServer(projectRoot, mode, explicitPort, options = {}) {
+  const reportDevelopmentEvent = mode === "development"
+    ? options.onDevelopmentEvent ?? createDevelopmentEventReporter()
+    : null;
+  reportDevelopmentEvent?.({ type: "server-starting" });
   const evolitConfig = options.evolitConfig ?? await loadEvolitConfig(projectRoot);
   const responseCacheRuntime = options.responseCacheStore
     ? {
@@ -120,14 +188,27 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     mode,
     assetManifest: normalizeClientAssetManifest(options.assetManifest),
     responseCacheRuntime,
+    onDevelopmentEvent: reportDevelopmentEvent,
   });
   const port = getPort(explicitPort);
+  const liveReloadServer = mode === "development" ? new WebSocketServer({ noServer: true }) : null;
+  const liveReloadSockets = new Set();
+  liveReloadServer?.on("connection", (socket) => {
+    liveReloadSockets.add(socket);
+    socket.on("close", () => {
+      liveReloadSockets.delete(socket);
+    });
+  });
   let invalidationTimer = null;
   let pendingInvalidation = null;
   let resolvePendingInvalidation = null;
   let invalidationPromise = Promise.resolve();
+  const pendingChangedPaths = new Set();
 
-  function scheduleDevelopmentInvalidation() {
+  function scheduleDevelopmentInvalidation(changedPath = null) {
+    if (changedPath) {
+      pendingChangedPaths.add(path.resolve(changedPath));
+    }
     if (invalidationTimer) {
       clearTimeout(invalidationTimer);
     }
@@ -141,43 +222,96 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
     invalidationTimer = setTimeout(() => {
       invalidationTimer = null;
       const resolve = resolvePendingInvalidation;
+      const changedPaths = pendingChangedPaths.size > 0
+        ? [...pendingChangedPaths]
+        : null;
+      pendingChangedPaths.clear();
       pendingInvalidation = null;
       resolvePendingInvalidation = null;
       invalidationPromise = invalidationPromise
         .catch(() => {})
-        .then(() => deploymentRuntime.invalidateDevelopmentState());
-      invalidationPromise.then(resolve, resolve);
+        .then(() => deploymentRuntime.invalidateDevelopmentState(changedPaths));
+      invalidationPromise.then(
+        () => {
+          for (const socket of liveReloadSockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+              socket.send("reload");
+            }
+          }
+          resolve();
+        },
+        resolve,
+      );
     }, 40);
   }
 
   const watcher = mode === "development"
     ? await createRecursiveDirectoryWatcher(
-      path.join(projectRoot, APP_DIRECTORY),
+      projectRoot,
       scheduleDevelopmentInvalidation,
+      { shouldIgnorePath: createProjectWatchIgnorePath(projectRoot) },
     )
     : null;
 
   const server = http.createServer(async (req, res) => {
     try {
+      const origin = `http://${req.headers.host ?? `localhost:${port}`}`;
+      const pathname = new URL(req.url ?? "/", origin).pathname;
       await pendingInvalidation;
       await invalidationPromise;
-      const origin = `http://${req.headers.host ?? `localhost:${port}`}`;
       const method = req.method ?? "GET";
       const request = new Request(new URL(req.url ?? "/", origin), {
         method,
         headers: req.headers,
         ...(method === "GET" || method === "HEAD" ? {} : { body: req, duplex: "half" }),
       });
+      const requestStartedAt = performance.now();
       const response = await deploymentRuntime.handle(request);
+      const navigationResponse = String(req.headers.accept ?? "").includes("application/vnd.evolit.navigation+json")
+        ? createNavigationResponseFromDocument(response)
+        : response;
+      const servedResponse = mode === "development"
+        ? injectLiveReloadSnippet(navigationResponse)
+        : navigationResponse;
 
-      res.writeHead(response.status, response.headers);
-      await writeResponseBody(res, response.body);
+      res.writeHead(servedResponse.status, servedResponse.headers);
+      await writeResponseBody(res, servedResponse.body);
+      if (mode === "development" && !pathname.startsWith("/_evolit/")) {
+        const durationMs = Math.round(performance.now() - requestStartedAt);
+        reportDevelopmentEvent({
+          type: "request",
+          method,
+          pathname,
+          status: servedResponse.status,
+          durationMs,
+          cacheState: servedResponse.headers?.["x-evolit-cache"] ?? null,
+        });
+      }
     } catch (error) {
+      reportDevelopmentEvent?.({
+        type: "request-error",
+        method: req.method ?? "GET",
+        pathname: req.url ?? "/",
+        error,
+      });
       res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
       res.end(error instanceof Error ? error.stack ?? error.message : String(error));
     }
   });
 
+  server.on("upgrade", (request, socket, head) => {
+    const origin = `http://${request.headers.host ?? `localhost:${port}`}`;
+    const pathname = new URL(request.url ?? "/", origin).pathname;
+    if (!liveReloadServer || pathname !== LIVE_RELOAD_PATHNAME) {
+      socket.destroy();
+      return;
+    }
+
+    liveReloadServer.handleUpgrade(request, socket, head, (webSocket) => {
+      liveReloadServer.emit("connection", webSocket, request);
+    });
+  });
+
   return {
     port,
     deploymentRuntime,
@@ -185,6 +319,7 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
       await new Promise((resolve) => {
         server.listen(port, resolve);
       });
+      reportDevelopmentEvent?.({ type: "server-ready", port });
       return server;
     },
     async close() {
@@ -192,6 +327,14 @@ async function createServer(projectRoot, mode, explicitPort, options = {}) {
         clearTimeout(invalidationTimer);
       }
       watcher?.close();
+      for (const socket of liveReloadSockets) {
+        socket.close();
+      }
+      if (liveReloadServer) {
+        await new Promise((resolve) => {
+          liveReloadServer.close(resolve);
+        });
+      }
       await new Promise((resolve, reject) => {
         server.close((error) => {
           if (error) {