evolit 0.1.0-alpha.9 → 0.1.1

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,8 +26,6 @@ It focuses on the core contract that matters first:
 
 Supported authored module extensions:
 
-- `.litsx`
-- `.litsx.jsx`
 - `.js`
 - `.jsx`
 - `.ts`
@@ -76,6 +74,98 @@ The current runtime is split into a few small layers:
 - `src/scaffold.js`: creates new site projects from templates
 - `src/cli.js`: framework entrypoint
 
+## Client Navigation
+
+Evolit hydrates a small browser router automatically for SSR page documents. It requests a route
+delta, replaces only the changed route segment, and keeps parent layouts mounted when possible.
+Plain `<a>` elements remain valid SSR HTML; same-origin links are progressively intercepted after
+hydration.
+
+Use `useNavigation()` inside a LitSX browser component for imperative navigation and pending UI:
+
+```jsx
+import { useNavigation } from "evolit/navigation";
+
+export default function CollectionControls() {
+  const navigation = useNavigation();
+
+  function changeSort(event) {
+    const searchParams = new URLSearchParams(window.location.search);
+    searchParams.delete("page");
+    searchParams.delete("skip");
+    searchParams.set("sort", event.target.value);
+    navigation.push(navigation.createHref("/explore/home-garden", searchParams));
+  }
+
+  return <select onChange={changeSort} disabled={navigation.status === "pending"}>…</select>;
+}
+```
+
+The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, createHref }`:
+
+- `push(target, { scroll: false })` adds a browser-history entry. Pass
+  `scroll: false` to keep the current viewport position.
+- `replace(target, { scroll: false })` updates the current entry, useful for
+  visual-only query state. It accepts the same scroll option.
+- `refresh()` bypasses the client delta cache for the current URL.
+- `createHref(pathname, searchParams)` creates a relative internal URL. It accepts standard
+  `URLSearchParams`, preserving repeated keys such as `facet=brand&facet=material`.
+
+`createHref` can also be imported directly from `evolit/navigation`; it is browser-free and safe to
+share with server-evaluated route code. `useNavigation()` itself is browser-only and must only run
+from a connected client component.
+
+Client components can also read the active route state with browser-only hooks:
+
+```jsx
+import { useParams, useSearchParams } from "evolit/navigation";
+
+const { slug = [] } = useParams();
+const searchParams = useSearchParams();
+const selectedFacets = searchParams.getAll("facet");
+```
+
+Both hooks update after client navigation. `useParams()` returns a read-only snapshot; the
+`URLSearchParams` from `useSearchParams()` is a local snapshot, so build a new href and navigate to
+it to update the URL.
+
+### Development refresh
+
+In development, each browser subscribes its active URL over the Evolit WebSocket. After source
+invalidation, the server renders the fresh SSR representation once per request context and pushes
+the resulting delta directly to its subscribers. No follow-up browser request is needed. Server-only
+module and static-asset changes update only the affected route segment while preserving the document,
+scroll position, and persistent layouts.
+Changes to a hydrated client boundary rebuild its browser artifact and update the stable Evolit
+development proxy registered for that tag. Existing instances receive the new implementation
+without redefining the Custom Element or replacing the document. Invalid deltas and failed hot
+updates still fall back to a document reload.
+
+### Progressive links and forms
+
+Links work without JavaScript. With JavaScript, Evolit intercepts ordinary same-origin left-clicks.
+Set `data-evolit-navigation="false"` on a link to keep native navigation.
+
+Internal `<form method="get">` elements are treated the same way: their successful controls become
+`URLSearchParams` and navigate through a delta. Without JavaScript the browser submits the exact
+same GET form normally. Evolit intentionally does not intercept `POST`, file-upload, external,
+targeted, or opted-out forms.
+
+### Navigation cache and document updates
+
+The browser cache is scoped to browser-history entries, not a global URL map. Going back or forward
+can reuse the delta for that exact entry; opening a new branch after going back discards its known
+forward branch. This avoids an unbounded catalog cache in a long-lived tab.
+
+- `dynamic` routes are never cached in the browser.
+- `revalidate` entries remain reusable only until their route TTL expires.
+- `static` entries remain reusable while their history entry exists in the current tab session.
+
+Each delta also synchronizes route `<title>`, route-specific `<head>` markup, managed styles and
+module preloads, `html`/`body` attributes, scroll position, hash targets, and focus. If a response
+cannot be represented as an Evolit delta —for example a 404 from another adapter— navigation falls
+back to a normal document load.
+
 ## Route Cache Policies
 
 Route modules can export a `routeConfig` object with a `cache` policy:
@@ -104,12 +194,18 @@ export const routeConfig = {
 - `static`: prerender in `build` and serve from the response cache in `start`
 - `revalidate`: cache the HTML response for `N` seconds and regenerate on expiry
 
+Pages without `routeConfig.cache` default to `{ revalidate: 60 }`. This caches a normal SSR
+render by pathname and query string while keeping content fresh without requiring a cache
+declaration on every catalog or CMS page. Declare `cache: "static"` for fully static pages or
+`cache: "dynamic"` when a page must always render per request.
+
 The same semantics work in local development and in production runtimes. Only the backing cache
 store changes.
 
-The default cache key includes the pathname and query string. Reading the `request` prop, request
-headers, cookies, or `requestUrl()` makes the completed render dynamic; it is never stored in the
-HTML response cache. `routeConfig.cache` is the sole authority for HTML caching; setting a
+The default cache key includes the pathname and query string, so `params` and `searchParams` are
+cacheable by URL. Reading the `request` prop, request headers, cookies, or `requestUrl()` makes
+the completed render dynamic; it is never stored in the HTML response cache. `routeConfig.cache`
+is the sole authority for HTML caching; setting a
 `Cache-Control` response header does not alter that policy.
 
 ## Request APIs
@@ -141,22 +237,87 @@ headers. `redirect()` and `permanentRedirect()` end rendering with `307` and `30
 `notFound()` renders a `404`. Reading headers, cookies, or the request URL makes the completed
 render dynamic, so it is not stored by the route response cache.
 
+## Extensions
+
+Optional integrations are configured explicitly in `evolit.config.js`. Core only coordinates their
+request and browser-navigation lifecycles: it has no knowledge of tenants, locales, catalogues, or
+message formats. Plugins run in declaration order. Each request hook receives the URL produced by
+the preceding hook; a `rewrite` continues the chain, while a `redirect` or `Response` stops it.
+
+```js
+// evolit.config.js
+import { defineEvolitPlugin } from "evolit/extensions";
+
+export default {
+  plugins: [defineEvolitPlugin({
+    name: "tenant-prefix",
+    onRequest({ pathname, headers, set }) {
+      const tenant = headers().get("x-tenant") ?? "public";
+      set("tenant", tenant);
+      if (pathname === "/shop") return { rewrite: `/tenants/${tenant}/shop` };
+    },
+    client: {
+      module: "@example/evolit-tenant/client",
+      options: { prefix: "/tenants" },
+    },
+  })],
+};
+```
+
+`onRequest` is server-only. It can read the `Request`, headers, cookies and URL, set JSON-serializable
+request values, rewrite internally, or return `{ redirect, status? }` / a Web `Response`. Reading
+request-bound data marks the request dynamic. Server components and handlers read the values without
+prop drilling:
+
+```js
+import { getRequestContext } from "evolit/server";
+
+export default async function TenantPage() {
+  const { tenant } = getRequestContext();
+  return `<main>Tenant: ${tenant}</main>`;
+}
+```
+
+The `client.module` is a bare package specifier and is the only extension code included in the
+browser build. It must export a named `navigation` object (or `default`) with optional hooks:
+
+```js
+// @example/evolit-tenant/client
+export const navigation = {
+  // Synchronous and idempotent: it may run for generated links and intercepted links.
+  transformUrl({ url, options }) {
+    return url.startsWith(options.prefix) ? url : `${options.prefix}${url}`;
+  },
+  async beforeNavigate({ url }) {
+    if (url.endsWith("/blocked")) return false;
+  },
+  afterNavigate({ from, url }) {
+    // Browser-only analytics or state synchronization.
+  },
+};
+```
+
+`transformUrl` runs for `createHref()` and before a SPA navigation; `beforeNavigate` can transform
+or cancel a navigation, and `afterNavigate` runs after its delta is applied. Hooks are sequential
+and later hooks receive the URL returned by earlier hooks. Browser modules must not import server
+code. Request values are isolated with async request context and are discarded when rendering ends.
+
 ## 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
@@ -231,6 +392,33 @@ export default {
 };
 ```
 
+For monorepos, development watches only the application project by default. Additional source
+trees can be opted into explicitly; generated output and dependency directories below every root
+remain ignored:
+
+```js
+export default {
+  development: {
+    managedSourceRoots: ["../packages/design-system/src"],
+  },
+};
+```
+
+Imports outside these roots remain unmanaged and produce the existing development warning.
+
+Evolit normally discovers browser boundaries from the static module graph and reconciles that
+inventory with the components actually emitted by SSR. A genuinely computed import cannot be
+enumerated at build time, so production applications can declare only those exceptional modules:
+
+```js
+export default {
+  clientBoundaries: ["./src/components/dynamic-card.jsx", "@acme/ui/product-card"],
+};
+```
+
+These modules are materialized as build artifacts, but are not automatically imported or
+preloaded. They reach the browser only when an SSR hydration root references them.
+
 The framework also exports `ObjectStorageResponseCacheStore`, which is intended for object-store
 backends such as S3. A concrete app can wire it to the AWS SDK without pulling AWS dependencies
 into `evolit` itself.

package/package.json

@@ -1,35 +1,47 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.1",
   "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"
+    "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",
+    "./navigation": {
+      "browser": "./src/navigation-client.js",
+      "default": "./src/navigation-server.js"
+    },
     "./server": {
       "browser": "./src/request-context-browser.js",
       "default": "./src/server-api.js"
-    }
+    },
+    "./extensions": {
+      "browser": "./src/extensions-client.js",
+      "default": "./src/extensions.js"
+    },
+    "./internal/development-hot": "./src/development-hot-client.js"
   },
   "scripts": {
     "dev": "node ./src/cli.js dev",
     "build": "node ./src/cli.js build",
     "start": "node ./src/cli.js start",
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
+    "test:browser": "playwright test",
     "typecheck": "litsx-tsc -p jsconfig.json --noEmit",
     "release:check": "yarn test && yarn typecheck && yarn pack --dry-run"
   },
@@ -43,14 +55,15 @@
   "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.9.5-canary-feat-ssr-20260726184312",
-    "@litsx/core": "0.17.0-canary-feat-ssr-20260726184312",
-    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260726184312",
+    "@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",
     "lit": "^3.3.3",
     "magic-string": "^1.1.0",
@@ -58,7 +71,17 @@
     "typescript": "^6.0.0",
     "ws": "^8.18.3"
   },
+  "peerDependencies": {
+    "@litsx/urql": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@litsx/urql": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@playwright/test": "^1.62.0",
+    "@webcomponents/scoped-custom-element-registry": "^0.0.10",
     "vite": "^8.1.5"
   }
-}
+}