evolit 0.1.0 → 0.1.2

package/README.md

@@ -8,7 +8,7 @@ This repository now contains the first framework MVP:
 - nested `layout` composition
 - server rendering through `@litsx/ssr`
 - a small `evolit` CLI with `init`, `dev`, `build`, and `start`
-- on-demand compilation of authored `.litsx` modules through `@litsx/compiler`
+- on-demand compilation of authored `.jsx` modules through `@litsx/compiler`
 - a starter template for generating new sites
 
 ## MVP Scope
@@ -26,14 +26,26 @@ It focuses on the core contract that matters first:
 
 Supported authored module extensions:
 
-- `.litsx`
-- `.litsx.jsx`
 - `.js`
 - `.jsx`
 - `.ts`
 - `.tsx`
 - `.mjs`
 
+### Internal imports
+
+Imports beginning with `@/` resolve from the application root in server and browser graphs. This
+keeps internal imports stable when modules move between route directories:
+
+```jsx
+import FeatureCard from "@/app/components/feature-card";
+import { formatPrice } from "@/lib/format-price";
+```
+
+Generated applications declare `"@/*": ["./*"]` in `jsconfig.json`, so editors and typechecking
+use the same convention. An explicit `@/*` mapping in `jsconfig.json` or `tsconfig.json` takes
+priority when an application needs a different source root.
+
 ## Commands
 
 ```sh
@@ -306,20 +318,20 @@ code. Request values are isolated with async request context and are discarded w
 
 ## Route Boundaries
 
-`not-found.litsx` and `error.litsx` are resolved from the current route directory up to `app/`.
-The nearest file wins and its output is wrapped by the route layouts. A root `app/not-found.litsx`
+`not-found.jsx` and `error.jsx` are resolved from the current route directory up to `app/`.
+The nearest file wins and its output is wrapped by the route layouts. A root `app/not-found.jsx`
 also handles unmatched URLs; without one, evolit returns its minimal built-in 404 document.
 
 ```js
-// app/blog/error.litsx
+// app/blog/error.jsx
 export default async function BlogError({ error }) {
   return `<p>Could not load this post: ${error.message}</p>`;
 }
 ```
 
-Boundaries always bypass the route response cache. `loading.litsx` is intentionally not supported
+Boundaries always bypass the route response cache. `loading.jsx` is intentionally not supported
 yet: it requires an end-to-end streaming document transport rather than an HTML-string fallback.
-In production, `error.litsx` receives a generic error with an opaque `digest`; the original error
+In production, `error.jsx` receives a generic error with an opaque `digest`; the original error
 is reported only on the server.
 
 ## Route Handlers
@@ -414,7 +426,7 @@ enumerated at build time, so production applications can declare only those exce
 
 ```js
 export default {
-  clientBoundaries: ["./src/components/dynamic-card.litsx", "@acme/ui/product-card"],
+  clientBoundaries: ["./src/components/dynamic-card.jsx", "@acme/ui/product-card"],
 };
 ```
 

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "evolit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/litsxdev/nextsx.git"
+    "url": "git+https://github.com/litsxdev/evolit.git"
   },
   "bugs": {
-    "url": "https://github.com/litsxdev/nextsx/issues"
+    "url": "https://github.com/litsxdev/evolit/issues"
   },
-  "homepage": "https://github.com/litsxdev/nextsx#readme",
+  "homepage": "https://github.com/litsxdev/evolit#readme",
   "files": [
     "src",
     "templates/default/app/**",
     "templates/default/jsconfig.json",
     "templates/default/yarnrc.yml.template"
   ],
-  "bin": "./src/cli.js",
+  "bin": "src/cli.js",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -55,13 +55,13 @@
   "author": "LitSX Team",
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=20.19.5"
+    "node": "^22.18.0 || >=24.11.0"
   },
   "dependencies": {
     "@jridgewell/remapping": "^2.3.5",
-    "@litsx/compiler": "0.10.0-canary-feat-ssr-20260802205539",
-    "@litsx/core": "0.17.0-canary-feat-ssr-20260802205539",
-    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260802205539",
+    "@litsx/compiler": "1.0.0-next.8",
+    "@litsx/core": "1.0.0-next.5",
+    "@litsx/ssr": "1.0.0-next.3",
     "@litsx/typescript": "^0.9.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",

package/src/build.js

@@ -344,7 +344,7 @@ export async function buildProject(projectRoot) {
         if (assetResolver(moduleId) || clientAssets.byPublicPath?.[moduleId]) continue;
         const importerPath = routeResult.boundaryModule
           ?? routeResult.route?.page
-          ?? path.join(projectRoot, "app", "page.litsx");
+          ?? path.join(projectRoot, "app", "page.jsx");
         let sourcePath = null;
         if (moduleId.startsWith("file:")) {
           try { sourcePath = fileURLToPath(moduleId); } catch {}

package/src/compiler.js

@@ -52,6 +52,175 @@ function shouldCompileModule(filePath) {
   return MODULE_EXTENSIONS.some((extension) => filePath.endsWith(extension));
 }
 
+function containsJsxSyntax(source, filePath) {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let containsJsx = false;
+
+  function visit(node) {
+    if (
+      ts.isJsxElement(node)
+      || ts.isJsxSelfClosingElement(node)
+      || ts.isJsxFragment(node)
+    ) {
+      containsJsx = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return containsJsx;
+}
+
+function containsLitsxComponentMetadata(source, filePath) {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+  let containsMetadata = false;
+
+  function visit(node) {
+    if (
+      ts.isBinaryExpression(node)
+      && node.operatorToken.kind === ts.SyntaxKind.EqualsToken
+      && ts.isPropertyAccessExpression(node.left)
+      && ts.isIdentifier(node.left.expression)
+      && /^[A-Z]/.test(node.left.expression.text)
+      && ["elements", "styles", "properties", "shadowRootOptions", "expose", "lightDom"].includes(node.left.name.text)
+    ) {
+      containsMetadata = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sourceFile);
+  return containsMetadata;
+}
+
+function isLitsxAuthoredModule(filePath, source) {
+  return (
+    filePath.endsWith(".jsx")
+    || filePath.endsWith(".tsx")
+    || containsJsxSyntax(source, filePath)
+    || containsLitsxComponentMetadata(source, filePath)
+  );
+}
+
+function createIdentitySourceMap(source, sourcePath) {
+  return JSON.parse(new MagicString(source).generateMap({
+    hires: true,
+    includeContent: true,
+    source: sourcePath.split(path.sep).join("/"),
+  }).toString());
+}
+
+function collectSideEffectImports(source, sourcePath) {
+  const sourceFile = ts.createSourceFile(
+    sourcePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  return sourceFile.statements
+    .filter((statement) => ts.isImportDeclaration(statement) && statement.importClause == null)
+    .map((statement) => ({
+      source: statement.moduleSpecifier.text,
+      statement: source.slice(statement.getStart(sourceFile), statement.end),
+    }));
+}
+
+function restoreSideEffectImports(source, sourcePath, transformed, sourceMaps) {
+  const transformedSpecifiers = new Set(
+    [...transformed.code.matchAll(MODULE_SPECIFIER_PATTERN)]
+      .map((match) => match[1] ?? match[2])
+      .filter(Boolean),
+  );
+  const missingImports = collectSideEffectImports(source, sourcePath)
+    .filter((entry) => !transformedSpecifiers.has(entry.source));
+  if (missingImports.length === 0) {
+    return transformed;
+  }
+
+  const magicSource = new MagicString(transformed.code);
+  magicSource.prepend(`${missingImports.map((entry) => entry.statement).join("\n")}\n`);
+  let map = transformed.map ?? null;
+
+  if (sourceMaps && map) {
+    const intermediateSourceId = `${sourcePath.split(path.sep).join("/")}#evolit-side-effects`;
+    const restoredMap = magicSource.generateMap({
+      hires: true,
+      includeContent: false,
+      source: intermediateSourceId,
+    });
+    map = remapping(restoredMap.toString(), (mappedSource) => (
+      mappedSource.endsWith("#evolit-side-effects") ? transformed.map : null
+    ));
+  }
+
+  return {
+    ...transformed,
+    code: magicSource.toString(),
+    map,
+  };
+}
+
+async function transformModuleSource(source, {
+  sourcePath,
+  sourceMaps,
+  ssr = false,
+}) {
+  if (isLitsxAuthoredModule(sourcePath, source)) {
+    const transformed = await transformLitsx(source, {
+      filename: sourcePath,
+      sourceMaps,
+      ssr,
+    });
+    return restoreSideEffectImports(source, sourcePath, transformed, sourceMaps);
+  }
+
+  if (sourcePath.endsWith(".ts")) {
+    const result = ts.transpileModule(source, {
+      fileName: sourcePath,
+      compilerOptions: {
+        inlineSources: sourceMaps,
+        module: ts.ModuleKind.ESNext,
+        sourceMap: sourceMaps,
+        target: ts.ScriptTarget.ESNext,
+      },
+    });
+    const map = sourceMaps && result.sourceMapText
+      ? JSON.parse(result.sourceMapText)
+      : null;
+    if (map) {
+      map.sources = [sourcePath.split(path.sep).join("/")];
+      map.sourcesContent = [source];
+    }
+    return {
+      code: result.outputText.replace(/\n?\/\/# sourceMappingURL=.*$/u, ""),
+      map,
+      metadata: {},
+    };
+  }
+
+  return {
+    code: source,
+    map: sourceMaps ? createIdentitySourceMap(source, sourcePath) : null,
+    metadata: {},
+  };
+}
+
 function isStaticAssetPath(filePath) {
   return STATIC_ASSET_EXTENSIONS.some((extension) => filePath.endsWith(extension));
 }
@@ -537,8 +706,24 @@ async function resolveProjectPathAlias(projectRoot, specifier) {
   return null;
 }
 
+async function resolveProjectRootAlias(projectRoot, specifier) {
+  if (!specifier.startsWith("@/") || specifier.length === 2) return null;
+
+  const normalizedProjectRoot = path.resolve(projectRoot);
+  const candidatePath = path.resolve(normalizedProjectRoot, specifier.slice(2));
+  const relativePath = path.relative(normalizedProjectRoot, candidatePath);
+  const isOutsideProject =
+    relativePath === ".."
+    || relativePath.startsWith(`..${path.sep}`)
+    || path.isAbsolute(relativePath);
+  if (isOutsideProject) return null;
+
+  return resolveImportPath(path.join(normalizedProjectRoot, "__alias__.js"), candidatePath);
+}
+
 async function resolveProjectMappedImport(projectRoot, importerPath, specifier) {
   return await resolveProjectPathAlias(projectRoot, specifier)
+    ?? await resolveProjectRootAlias(projectRoot, specifier)
     ?? await resolveProjectPackageImportMap(importerPath, specifier);
 }
 
@@ -938,8 +1123,9 @@ async function compileModuleGraphUncached(entryPath, options = {}) {
 
     await ensureDirectory(path.dirname(outputPath));
     const source = await fs.readFile(sourcePath, "utf8");
-    const transformed = await transformLitsx(source, {
-      filename: sourcePath,
+    const transformed = await transformModuleSource(source, {
+      projectRoot,
+      sourcePath,
       sourceMaps,
       ssr,
     });
@@ -1163,7 +1349,11 @@ export async function collectClientGraphInventory(entryPaths, options = {}) {
     if (visited.has(sourcePath)) return;
     visited.add(sourcePath);
     const source = await fs.readFile(sourcePath, "utf8");
-    const transformed = await transformLitsx(source, { filename: sourcePath, sourceMaps: false });
+    const transformed = await transformModuleSource(source, {
+      projectRoot,
+      sourcePath,
+      sourceMaps: false,
+    });
     const isServer = isCompiledServerComponentModule(transformed.code);
     const isComponent = isCompiledClientBoundaryModule(transformed.code);
     if (isComponent && !isServer) {

package/src/constants.js

@@ -13,8 +13,6 @@ export const DEPLOY_ASSETS_MANIFEST_FILENAME = "deploy-assets.json";
 export const DEPLOY_SERVER_MANIFEST_FILENAME = "deploy-server.json";
 
 export const MODULE_EXTENSIONS = [
-  ".litsx",
-  ".litsx.jsx",
   ".tsx",
   ".ts",
   ".jsx",

package/src/deployment-runtime.js

@@ -423,7 +423,7 @@ export async function createRequestRenderer({
 
     const importerPath = routeResult?.boundaryModule
       ?? routeResult?.route?.page
-      ?? path.join(projectRoot, "app", "page.litsx");
+      ?? path.join(projectRoot, "app", "page.jsx");
     if (moduleId.startsWith("/")) {
       const projectSpecifier = `.${moduleId}`;
       return resolveProjectModuleSpecifier(projectRoot, importerPath, projectSpecifier);

package/src/index.js

@@ -92,7 +92,7 @@ export { cookies } from "./request-context.js";
 export { headers } from "./request-context.js";
 
 /**
- * Signals a 404 response and renders the nearest `not-found.litsx` boundary when available.
+ * Signals a 404 response and renders the nearest `not-found.jsx` boundary when available.
  *
  * @returns {never}
  */

package/src/render.js

@@ -1,8 +1,7 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { html } from "lit";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
-import { renderToString } from "@litsx/ssr";
+import { html, renderToString } from "@litsx/ssr";
 import { discoverAppRouteHandlers, discoverAppRoutes, matchRoute } from "./app-discovery.js";
 import { importCompiledModule } from "./compiler.js";
 import { APP_DIRECTORY, MODULE_EXTENSIONS } from "./constants.js";

package/src/request-context.js

@@ -201,7 +201,7 @@ export function permanentRedirect(location) {
 }
 
 /**
- * Stops route execution with a 404 signal for the nearest `not-found.litsx` boundary.
+ * Stops route execution with a 404 signal for the nearest `not-found.jsx` boundary.
  *
  * @returns {never}
  */

package/src/route-segments.js

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
 import path from "node:path";
-import { html } from "lit";
+import { html } from "@litsx/ssr";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 
 const SEGMENT_MARKER_PREFIX = "evolit:segment";

package/src/scaffold.js

@@ -16,6 +16,9 @@ async function writeSitePackageJson(targetDirectory, siteName) {
     version: "0.1.0",
     private: true,
     type: "module",
+    engines: {
+      node: "^22.18.0 || >=24.11.0",
+    },
     scripts: {
       dev: "evolit dev",
       build: "evolit build",
@@ -23,7 +26,7 @@ async function writeSitePackageJson(targetDirectory, siteName) {
       typecheck: "litsx-tsc -p jsconfig.json --noEmit",
     },
     dependencies: {
-      "@litsx/core": "0.17.0-canary-feat-ssr-20260726130435",
+      "@litsx/core": "1.0.0-next.5",
       evolit: frameworkVersion,
     },
     devDependencies: {

package/src/server-api.js

@@ -13,7 +13,7 @@ export { cookies } from "./request-context.js";
 export { headers } from "./request-context.js";
 
 /**
- * Signals a 404 response and renders the nearest `not-found.litsx` boundary when available.
+ * Signals a 404 response and renders the nearest `not-found.jsx` boundary when available.
  *
  * @returns {never}
  */

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

@@ -0,0 +1,37 @@
+import { css } from "lit";
+
+export default function FeatureCard({ title, body }) {
+  return (
+    <article class="card">
+      <h2 class="title">{title}</h2>
+      <p class="body">
+        {body}
+      </p>
+    </article>
+  );
+}
+
+FeatureCard.styles = css`
+  :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);
+  }
+`;

package/templates/default/app/{page.litsx → page.jsx}

@@ -1,4 +1,4 @@
-import FeatureCard from "./components/feature-card.litsx";
+import FeatureCard from "@/app/components/feature-card";
 
 export default async function HomePage() {
   return (
@@ -20,7 +20,7 @@ export default async function HomePage() {
       <div class="features">
         <FeatureCard
           title="File Routing"
-          body="Every app/page.litsx becomes an addressable route, with dynamic segments reserved for the next iteration."
+          body="Every app/page.jsx becomes an addressable route, with dynamic segments reserved for the next iteration."
         />
         <FeatureCard
           title="SSR Boundary"
@@ -28,7 +28,7 @@ export default async function HomePage() {
         />
         <FeatureCard
           title="Compiler Reuse"
-          body="Authored .litsx source is compiled through the public @litsx/compiler facade instead of a parallel transform path."
+          body="Authored .jsx source is compiled through the public @litsx/compiler facade instead of a parallel transform path."
         />
       </div>
     </section>

package/templates/default/jsconfig.json

@@ -6,9 +6,14 @@
     "allowJs": true,
     "checkJs": false,
     "strict": false,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "jsxImportSource": "@litsx/core",
     "allowArbitraryExtensions": true,
+    "paths": {
+      "@/*": [
+        "./*"
+      ]
+    },
     "plugins": [
       {
         "name": "@litsx/typescript"

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

@@ -1,35 +0,0 @@
-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>
-  );
-}