evolit 0.1.0-alpha.0

package/src/server.js

@@ -0,0 +1,230 @@
+import http from "node:http";
+import { watch } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { loadEvolitConfig } from "./config.js";
+import { createDeploymentRuntime } from "./deployment-runtime.js";
+import { APP_DIRECTORY, 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";
+
+function getPort(explicitPort) {
+  const port = explicitPort ?? process.env.PORT ?? "3000";
+  return Number.parseInt(String(port), 10);
+}
+
+async function writeResponseBody(response, body) {
+  if (!body || typeof body.getReader !== "function") {
+    response.end(body);
+    return;
+  }
+
+  const reader = body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      response.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  response.end();
+}
+
+async function createRecursiveDirectoryWatcher(rootDirectory, onChange) {
+  const watchers = new Map();
+  let closed = false;
+
+  async function watchDirectory(directory) {
+    if (closed || watchers.has(directory)) {
+      return;
+    }
+
+    let watcher;
+    try {
+      watcher = watch(directory, (eventType, fileName) => {
+        onChange();
+
+        if (eventType === "rename" && fileName) {
+          void watchNewDirectory(path.join(directory, fileName));
+        }
+      });
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+      return;
+    }
+
+    // A deleted directory may emit an error after its watcher has been installed.
+    watcher.on("error", () => {});
+    watchers.set(directory, watcher);
+
+    let entries;
+    try {
+      entries = await fs.readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (error?.code === "ENOENT") {
+        return;
+      }
+      throw error;
+    }
+
+    await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => watchDirectory(path.join(directory, entry.name))),
+    );
+  }
+
+  async function watchNewDirectory(candidate) {
+    try {
+      const stat = await fs.stat(candidate);
+      if (stat.isDirectory()) {
+        await watchDirectory(candidate);
+      }
+    } catch (error) {
+      if (error?.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  await watchDirectory(rootDirectory);
+
+  return {
+    close() {
+      closed = true;
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+      watchers.clear();
+    },
+  };
+}
+
+async function createServer(projectRoot, mode, explicitPort, options = {}) {
+  const evolitConfig = options.evolitConfig ?? await loadEvolitConfig(projectRoot);
+  const responseCacheRuntime = options.responseCacheStore
+    ? {
+      store: options.responseCacheStore,
+      createKey: options.createResponseCacheKey ?? (({ request }) => createDefaultRouteCacheKey(request)),
+    }
+    : await resolveResponseCacheRuntime(projectRoot, mode, evolitConfig);
+  const deploymentRuntime = await createDeploymentRuntime({
+    projectRoot,
+    mode,
+    assetManifest: normalizeClientAssetManifest(options.assetManifest),
+    responseCacheRuntime,
+  });
+  const port = getPort(explicitPort);
+  let invalidationTimer = null;
+  let pendingInvalidation = null;
+  let resolvePendingInvalidation = null;
+  let invalidationPromise = Promise.resolve();
+
+  function scheduleDevelopmentInvalidation() {
+    if (invalidationTimer) {
+      clearTimeout(invalidationTimer);
+    }
+
+    if (!pendingInvalidation) {
+      pendingInvalidation = new Promise((resolve) => {
+        resolvePendingInvalidation = resolve;
+      });
+    }
+
+    invalidationTimer = setTimeout(() => {
+      invalidationTimer = null;
+      const resolve = resolvePendingInvalidation;
+      pendingInvalidation = null;
+      resolvePendingInvalidation = null;
+      invalidationPromise = invalidationPromise
+        .catch(() => {})
+        .then(() => deploymentRuntime.invalidateDevelopmentState());
+      invalidationPromise.then(resolve, resolve);
+    }, 40);
+  }
+
+  const watcher = mode === "development"
+    ? await createRecursiveDirectoryWatcher(
+      path.join(projectRoot, APP_DIRECTORY),
+      scheduleDevelopmentInvalidation,
+    )
+    : null;
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      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 response = await deploymentRuntime.handle(request);
+
+      res.writeHead(response.status, response.headers);
+      await writeResponseBody(res, response.body);
+    } catch (error) {
+      res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+      res.end(error instanceof Error ? error.stack ?? error.message : String(error));
+    }
+  });
+
+  return {
+    port,
+    deploymentRuntime,
+    async listen() {
+      await new Promise((resolve) => {
+        server.listen(port, resolve);
+      });
+      return server;
+    },
+    async close() {
+      if (invalidationTimer) {
+        clearTimeout(invalidationTimer);
+      }
+      watcher?.close();
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+      await deploymentRuntime.close?.();
+    },
+  };
+}
+
+export async function createDevServer(projectRoot, options = {}) {
+  return createServer(projectRoot, "development", options.port, options);
+}
+
+export async function createStartServer(projectRoot, options = {}) {
+  const manifestPath = path.join(
+    projectRoot,
+    INTERNAL_DIRECTORY,
+    BUILD_DIRECTORY,
+    MANIFEST_FILENAME,
+  );
+
+  if (!(await pathExists(manifestPath))) {
+    throw new Error("Build output not found. Run `yarn build` before `yarn start`.");
+  }
+
+  const manifest = await readJson(manifestPath);
+  return createServer(projectRoot, "production", options.port, {
+    ...options,
+    assetManifest: manifest.clientAssets ?? null,
+  });
+}

package/src/ssr-adapter.js

@@ -0,0 +1,189 @@
+import { renderBootstrap, renderDocument } from "@litsx/ssr";
+
+function escapeHtmlAttribute(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll('"', """)
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+function normalizeHeadMarkup(value) {
+  if (Array.isArray(value)) {
+    return value.filter(Boolean).join("\n");
+  }
+
+  return typeof value === "string" ? value : "";
+}
+
+function resolveDocumentMetadata(routeMetadata = {}, adapterOptions = {}) {
+  const description =
+    routeMetadata.description ?? adapterOptions.description ?? "A LitSX application";
+  const extraHead = [
+    description
+      ? `<meta name="description" content="${escapeHtmlAttribute(description)}" />`
+      : "",
+    normalizeHeadMarkup(adapterOptions.head),
+    normalizeHeadMarkup(routeMetadata.head),
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  return {
+    lang: String(routeMetadata.lang ?? adapterOptions.lang ?? "en"),
+    title: String(routeMetadata.title ?? adapterOptions.title ?? "evolit"),
+    head: extraHead,
+    htmlAttributes: {
+      ...(adapterOptions.htmlAttributes ?? {}),
+      ...(routeMetadata.htmlAttributes ?? {}),
+    },
+    bodyAttributes: {
+      ...(adapterOptions.bodyAttributes ?? {}),
+      ...(routeMetadata.bodyAttributes ?? {}),
+    },
+  };
+}
+
+function createHtmlDocument({ body, metadata = {} }) {
+  const title = metadata.title ? String(metadata.title) : "evolit";
+  const description =
+    metadata.description ? String(metadata.description) : "A LitSX application";
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtmlAttribute(metadata.lang ?? "en")}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>${description ? `
+    <meta name="description" content="${escapeHtmlAttribute(description)}" />` : ""}
+${metadata.head ? `    ${String(metadata.head).split("\n").join("\n    ")}` : ""}
+  </head>
+  <body>${body}</body>
+</html>`;
+}
+
+function createRouteHeaders(routeResult, headers = {}) {
+  return {
+    ...headers,
+    ...(routeResult.responseHeaders ?? {}),
+  };
+}
+
+function responseHeadersToObject(headers) {
+  const values = Object.fromEntries(headers.entries());
+  if (typeof headers.getSetCookie === "function") {
+    const cookies = headers.getSetCookie();
+    if (cookies.length > 0) {
+      values["set-cookie"] = cookies;
+    }
+  }
+  return values;
+}
+
+export function createSsrAdapter(options = {}) {
+  return {
+    name: options.name ?? "litsx-ssr",
+    async renderRouteTree(routeResult) {
+      if (routeResult.type === "handler") {
+        return {
+          status: routeResult.response.status,
+          headers: responseHeadersToObject(routeResult.response.headers),
+          body: routeResult.response.body,
+        };
+      }
+
+      if (routeResult.type === "not-found" && !routeResult.tree) {
+        return {
+          status: 404,
+          headers: createRouteHeaders(routeResult, { "content-type": "text/html; charset=utf-8" }),
+          body: "<!DOCTYPE html><html><body><h1>404</h1><p>Route not found.</p></body></html>",
+        };
+      }
+
+      if (routeResult.type === "redirect") {
+        return {
+          status: routeResult.status ?? 307,
+          headers: createRouteHeaders(routeResult, {
+            location: routeResult.location,
+            "content-type": "text/html; charset=utf-8",
+          }),
+          body: "<!DOCTYPE html><html><body><p>Redirecting...</p></body></html>",
+        };
+      }
+
+      if (typeof routeResult.tree === "string") {
+        const metadata = resolveDocumentMetadata(routeResult.metadata, options);
+        return {
+          status: routeResult.status ?? 200,
+          headers: createRouteHeaders(routeResult, { "content-type": "text/html; charset=utf-8" }),
+          body: createHtmlDocument({
+            body: routeResult.tree,
+            metadata: {
+              ...routeResult.metadata,
+              ...metadata,
+              description: routeResult.metadata?.description ?? options.description,
+            },
+          }),
+        };
+      }
+
+      const documentOptions = resolveDocumentMetadata(routeResult.metadata, options);
+      const bootstrap = options.bootstrap ?? false;
+      const result = await renderDocument(routeResult.tree, {
+        ...documentOptions,
+        assetResolver: options.assetResolver,
+        bootstrap,
+        clientEntry: options.clientEntry,
+        template: options.template,
+      });
+
+      const generatedBootstrap =
+        !options.bootstrap && !options.clientEntry && typeof options.resolveBootstrap === "function"
+          ? await options.resolveBootstrap({ routeResult, result })
+          : "";
+      const additionalHead =
+        typeof options.resolveAdditionalHead === "function"
+          ? await options.resolveAdditionalHead({ routeResult, result })
+          : "";
+      const documentWithAdditionalHead = additionalHead
+        ? result.document.replace("</head>", `${additionalHead}\n</head>`)
+        : result.document;
+      const transformedDocument =
+        typeof options.transformDocument === "function"
+          ? await options.transformDocument({
+            routeResult,
+            result,
+            document: documentWithAdditionalHead,
+          })
+          : documentWithAdditionalHead;
+
+      if (generatedBootstrap) {
+        const bootstrapMarkup = renderBootstrap({
+          bootstrap: {
+            content: generatedBootstrap,
+          },
+        });
+        const documentWithBootstrap = transformedDocument.replace(
+          "</body>",
+          `${bootstrapMarkup}\n</body>`,
+        );
+
+        return {
+          status: routeResult.status ?? 200,
+          headers: createRouteHeaders(routeResult, { "content-type": "text/html; charset=utf-8" }),
+          body: documentWithBootstrap,
+        };
+      }
+
+      return {
+        status: routeResult.status ?? 200,
+        headers: createRouteHeaders(routeResult, { "content-type": "text/html; charset=utf-8" }),
+        body: transformedDocument,
+      };
+    },
+  };
+}
+
+export async function renderRouteTreeWithAdapter(routeResult, adapter = createSsrAdapter()) {
+  return adapter.renderRouteTree(routeResult);
+}

package/templates/default/app/about/page.litsx

@@ -0,0 +1,20 @@
+export const metadata = {
+  title: "About | evolit",
+  description: "What evolit is trying to become",
+};
+
+export default async function AboutPage() {
+  return (
+    <section>
+      <h1>About evolit</h1>
+      <p>
+        The goal is not to clone Next.js mechanically. The goal is to offer the same level of
+        application ergonomics for LitSX-authored user interfaces: routing, layouts, SSR,
+        build orchestration, and Web Platform server APIs.
+      </p>
+      <p>
+        This starter is the first end-to-end slice needed to evolve that runtime in the open.
+      </p>
+    </section>
+  );
+}

package/templates/default/app/assets.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/templates/default/app/components/feature-card.litsx

@@ -0,0 +1,35 @@
+export default function FeatureCard({ title, body }) {
+  static styles = `
+    :host {
+      display: block;
+    }
+
+    .card {
+      padding: 24px;
+      border-radius: 18px;
+      background: rgba(255, 255, 255, 0.06);
+      border: 1px solid rgba(255, 255, 255, 0.08);
+      backdrop-filter: blur(12px);
+    }
+
+    .title {
+      margin: 0 0 12px;
+      font-size: 1.25rem;
+    }
+
+    .body {
+      margin: 0;
+      line-height: 1.7;
+      color: rgba(248, 247, 241, 0.78);
+    }
+  `;
+
+  return (
+    <article class="card">
+      <h2 class="title">{title}</h2>
+      <p class="body">
+        {body}
+      </p>
+    </article>
+  );
+}

package/templates/default/app/global.css

@@ -0,0 +1,27 @@
+main {
+  min-height: 100vh;
+  padding: 48px 24px;
+  color: #f8f7f1;
+  background: radial-gradient(circle at top, rgba(239, 148, 89, 0.22), transparent 34%), linear-gradient(180deg, #10161f 0%, #182332 100%);
+  font-family: Iowan Old Style, Palatino Linotype, Book Antiqua, Georgia, serif;
+}
+
+.shell { max-width: 960px; margin: 0 auto; }
+header { margin-bottom: 40px; }
+.wordmark {
+  display: inline-block;
+  padding: 8px 12px;
+  border: 1px solid rgba(248, 247, 241, 0.18);
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  font-size: 12px;
+}
+
+.intro { display: grid; gap: 20px; margin-bottom: 40px; }
+.eyebrow { margin: 0; letter-spacing: 0.18em; text-transform: uppercase; font-size: 12px; color: rgba(248, 247, 241, 0.56); }
+h1 { margin: 0; font-size: clamp(3rem, 7vw, 5.5rem); line-height: 0.94; }
+.summary { max-width: 720px; margin: 0; line-height: 1.8; color: rgba(248, 247, 241, 0.76); }
+.features { display: grid; gap: 18px; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); }
+
+section { max-width: 720px; display: grid; gap: 20px; }
+section p { margin: 0; line-height: 1.8; color: rgba(248, 247, 241, 0.78); }

package/templates/default/app/layout.litsx

@@ -0,0 +1,18 @@
+export const metadata = {
+  title: "evolit",
+  description: "A Next.js-style runtime for LitSX",
+};
+
+export default async function RootLayout({ children }) {
+  return (
+    <main>
+      <div class="shell">
+        <header>
+          <div class="wordmark">evolit</div>
+        </header>
+        {children}
+      </div>
+    </main>
+  );
+}
+import "./global.css";

package/templates/default/app/page.litsx

@@ -0,0 +1,36 @@
+import FeatureCard from "./components/feature-card.litsx";
+
+export default async function HomePage() {
+  return (
+    <section>
+      <div class="intro">
+        <p class="eyebrow">LitSX application framework</p>
+        <h1>
+          Next.js ideas,
+          <br />
+          LitSX authored.
+        </h1>
+        <p class="summary">
+          This starter proves the first framework contract: routes from <code>app/</code>,
+          nested layouts, request-aware page modules, and server rendering for LitSX-authored
+          UI.
+        </p>
+      </div>
+
+      <div class="features">
+        <FeatureCard
+          title="File Routing"
+          body="Every app/page.litsx becomes an addressable route, with dynamic segments reserved for the next iteration."
+        />
+        <FeatureCard
+          title="SSR Boundary"
+          body="The framework now renders route trees through @litsx/ssr while keeping the adapter boundary internal."
+        />
+        <FeatureCard
+          title="Compiler Reuse"
+          body="Authored .litsx source is compiled through the public @litsx/compiler facade instead of a parallel transform path."
+        />
+      </div>
+    </section>
+  );
+}

package/templates/default/jsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowJs": true,
+    "checkJs": false,
+    "strict": false,
+    "jsx": "preserve",
+    "jsxImportSource": "@litsx/core",
+    "allowArbitraryExtensions": true,
+    "plugins": [
+      {
+        "name": "@litsx/typescript"
+      }
+    ]
+  },
+  "include": [
+    "app/**/*",
+    "evolit.config.js"
+  ]
+}