@jk2908/solas 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.4 - 2026-05-29
+
+- Added `router.refresh()` to the browser router, and made it clear that it clears the current route cache before fetching a fresh RSC payload.
+- Reworked browser-router response caching so prefetched RSC responses can be reused by later navigations without a second fetch.
+- Documented client routing and generated route typing in the README, including `useRouter()`, `router.go()`, `router.prefetch()`, `router.refresh()`, `Link` prefetch behaviour, and typed `Route.Metadata`/`Route.StaticParams` usage.
+- Added a refresh demo route to the basic example app for manual regression testing.
+
+## 0.4.3 - 2026-05-27
+
+- Updated README docs to show that `dynamic()` must be awaited in request-time deferred `ppr` usage examples.
+- Clarified route docs for `+endpoint.ts`, including that endpoint files can be placed anywhere in `app/` and how GET requests are resolved when `+page.tsx` and `+endpoint.ts` share a route.
+- Tightened README language around experimental status, `url`, and `trustedOrigins`/CSRF guidance.
+
 ## 0.4.2 - 2026-05-22
 
 - Changed `precompress` to default to `false`, so Solas no longer emits precompressed build output unless you opt in.

package/README.md

@@ -2,7 +2,7 @@
 
 Solas is a minimal React meta-framework powered by Vite, created for experimenting with routing, streaming, and prerendering with React Server Components.
 
-It has not been rigorously tested yet (there are currently no automated tests) ... and broken behaviour should be expected.
+Solas is experimental and currently has no automated test suite, so expect rough edges.
 
 Solas currently requires Bun 1.2+ on your `PATH`. You can still manage dependencies with `npm`, `pnpm`, or `yarn`, but the Solas CLI and Vite plugin runtime use Bun APIs directly.
 
@@ -56,7 +56,7 @@ Use these filename conventions:
 
 - `+layout.tsx`: shared layout for a route branch.
 - `+page.tsx`: page component for a route.
-- `+endpoint.ts`: request handler for non-page routes.
+- `+endpoint.ts`: request handler. Can be placed in any folder and responds to all HTTP methods for its route path.
 - `+middleware.ts`: middleware that runs for the current route branch and is inherited by child routes. Parent and child middleware stack together.
 - `+loading.tsx`: loading fallback inherited by child routes.
 - `+401.tsx`: boundary for unauthorised responses in the current route branch and its children.
@@ -68,6 +68,107 @@ Nested folders create nested routes. Dynamic segments use `[param]`, and catch-a
 
 Status boundaries follow the same override pattern as layouts: a child route uses the nearest matching boundary file above it, and a more specific boundary replaces a parent one.
 
+If a route has both `+page.tsx` and `+endpoint.ts`, Solas selects the GET handler by `Accept` header:
+
+- `Accept: text/html` or `text/x-component`: render `+page.tsx`
+- other GET requests (for example `application/json`): run `+endpoint.ts` `GET`
+
+Non-GET methods (`POST`, `PUT`, `PATCH`, `DELETE`) always run `+endpoint.ts`.
+
+## Client Routing
+
+Import client navigation helpers from `@jk2908/solas/router`.
+
+```tsx
+import { Link, useRouter } from '@jk2908/solas/router'
+```
+
+Solas generates route types for your app. `Link` and `router.go(...)` use those generated route types for autocomplete and type checking:
+
+```tsx
+<Link href="/posts" />
+<Link href="/p/:id" params={{ id: 'post-1' }} />
+
+await router.go('/posts')
+await router.go('/p/:id', { params: { id: 'post-1' } })
+```
+
+That gives you:
+
+- autocomplete for known route paths
+- required params for dynamic routes like `/p/:id`
+- rejected params for static routes that do not accept them
+- typed query and navigation options on `router.go(...)`
+
+Use `Link` for same-origin app navigation. Prefetching is opt-in:
+
+```tsx
+<Link href="/posts">Posts</Link>
+<Link href="/posts" prefetch="intent">Prefetch on focus or touch</Link>
+<Link href="/posts" prefetch="hover">Prefetch on hover</Link>
+<Link href="/p/:id" params={{ id: 'post-1' }}>Typed params</Link>
+```
+
+`prefetch="none"` is the default. Solas does not automatically prefetch routes unless you opt in with `Link` or call `router.prefetch(...)` yourself.
+
+Use `useRouter()` inside client components for programmatic navigation, prefetching, and refreshing the current route:
+
+```tsx
+'use client'
+
+import { useRouter } from '@jk2908/solas/router'
+
+export function Controls() {
+	const router = useRouter()
+
+	return (
+		<>
+			<button type="button" onClick={() => void router.go('/posts')}>
+				Go to posts
+			</button>
+
+			<button type="button" onMouseEnter={() => router.prefetch('/posts')}>
+				Prefetch posts
+			</button>
+
+			<button type="button" onClick={() => void router.refresh()}>
+				Refresh current route
+			</button>
+		</>
+	)
+}
+```
+
+`router.go(...)` accepts route params and query values using the same typed route rules as `Link`:
+
+```tsx
+await router.go('/p/:id', {
+	params: { id: 'post-2' },
+	query: { draft: true },
+})
+```
+
+Those same generated route types can also be reused outside navigation helpers when you want route params to stay typed in page exports:
+
+```tsx
+import type { Route, Solas } from '@jk2908/solas'
+
+export const metadata: Route.Metadata<Solas.Routes['/writing/:slug']> = ({ params }) => {
+	const post = allPosts?.find(p => p.__mdsrc.slug === params?.slug)
+
+	return {
+		title: post?.title ?? 'Post not found',
+	}
+}
+
+export const params: Route.StaticParams<Solas.Routes['/writing/:slug']> = () =>
+	allPosts?.map(p => ({ slug: p.__mdsrc.slug })) ?? []
+```
+
+That keeps your route params aligned across links, imperative navigation, metadata, and static params.
+
+`router.refresh()` clears the cached RSC response for the current path and fetches a fresh payload, so it is most useful for routes that render request-time data. `router.isNavigating` exposes pending client-side navigation state.
+
 ## Config
 
 All Solas options are passed to `solas()` inside `defineConfig`.
@@ -81,14 +182,9 @@ Solas resolves it in this order:
 - the `url` option passed to `solas()`
 - `VITE_APP_URL`
 
-Current behaviour:
+Solas exposes the resolved value as `import.meta.env.VITE_APP_URL`. If `url` is set, prerender also uses it as the request origin for build-time renders.
 
-- Solas reads that value during plugin configuration.
-- Solas exposes the resolved value as `import.meta.env.VITE_APP_URL`.
-- If `url` is set, prerender uses it as the request origin for build-time renders.
-- The runtime router does not otherwise require `config.url` for routing to work.
-
-In practice, you only need `url` if your app code wants to read the public origin from `import.meta.env.VITE_APP_URL`, or if your prerendered output needs a real public origin.
+In practice, you only need `url` if your app reads `import.meta.env.VITE_APP_URL` or your prerendered output needs a real public origin.
 
 If you do want to set it explicitly, this is the shape:
 
@@ -126,9 +222,9 @@ export default defineConfig({
 
 ### `precompress`
 
-Use `precompress` to control whether Solas writes compressed build assets.
+Use `precompress` to control whether Solas writes compressed browser-served build assets (like `.js`, `.css`, etc.).
 
-Default: `true`
+Default: `false`
 
 ```ts
 export default defineConfig({
@@ -208,7 +304,7 @@ export default function Page() {
 }
 
 async function Ts() {
-	dynamic()
+	await dynamic()
 	return <div>{Date.now()}</div>
 }
 ```
@@ -294,12 +390,10 @@ Use `trustedOrigins` to allow specific origins to make cross-origin browser subm
 
 Default: `[]`
 
-Solas protects server actions and `+endpoint` handlers against CSRF.
-
-Server actions are always `POST` requests. `+endpoint` handlers are protected on `POST`, `PUT`, `PATCH`, and `DELETE` requests.
-
 By default, only same-origin browser requests are allowed. Add a trusted origin when a third-party service needs to submit through the user's browser, such as a payment gateway or identity provider.
 
+This setting controls which cross-origin browser sources are allowed for unsafe requests. See Security > CSRF for enforcement details.
+
 Each value must be a complete origin including protocol:
 
 ```ts
@@ -312,7 +406,7 @@ export default defineConfig({
 })
 ```
 
-Only add origins you completely trust. These origins are treated as allowed browser sources for unsafe requests.
+Only add origins you completely trust.
 
 ### `sitemap`
 

package/dist/internal/browser-router/link.js

@@ -16,6 +16,8 @@ function guard(path, prefetcher) {
 export function Link({ children, href, params, prefetch = 'none', query, ...rest }) {
     const { go, prefetch: prefetcher } = useRouter();
     const timer = useRef(null);
+    // track whether the link is meant to be handled by the router, to avoid
+    // unnecessary prefetching and event handling for external links
     const handled = useRef(false);
     const target = BrowserRouter.toTarget(href, params, query);
     // clear any pending hover-prefetch timer on unmount

package/dist/internal/{prefetcher.d.ts → browser-router/response-cache.d.ts}

@@ -1,10 +1,17 @@
-export declare namespace Prefetcher {
+export declare namespace ResponseCache {
     type Entry = {
         promise: Promise<Response>;
         timeoutId: ReturnType<typeof setTimeout>;
     };
 }
-export declare class Prefetcher {
+/**
+ * A simple in-memory cache for RSC response promises used by the BrowserRouter.
+ * It lets a later navigation reuse a prefetched response for the same path,
+ * and helps avoid issuing a second fetch when navigation follows shortly
+ * after prefetch. Entries are stored by normalised path with TTL and
+ * max size eviction
+ */
+export declare class ResponseCache {
     #private;
     ttl: number;
     maxSize: number;
@@ -16,7 +23,7 @@ export declare class Prefetcher {
      * Converts a url path to a cache key by normalising it
      * against a base url
      */
-    static key(path: string, base: string): string | null;
+    static toCacheKey(path: string, base: string): string | null;
     /**
      * Evicts the oldest entry from the cache
      */
@@ -26,8 +33,8 @@ export declare class Prefetcher {
      */
     has(path: string): boolean;
     /**
-     * Retrieves a fresh response promise for the given path if it exists
-     * by cloning the cached response so each consumer gets an unread stream
+     * Retrieves a fresh response promise for the given path if it exists by
+     * cloning the cached response so each consumer gets an unread stream
      */
     get(path: string): Promise<Response> | undefined;
     /**

package/dist/internal/{prefetcher.js → browser-router/response-cache.js}

@@ -1,4 +1,11 @@
-export class Prefetcher {
+/**
+ * A simple in-memory cache for RSC response promises used by the BrowserRouter.
+ * It lets a later navigation reuse a prefetched response for the same path,
+ * and helps avoid issuing a second fetch when navigation follows shortly
+ * after prefetch. Entries are stored by normalised path with TTL and
+ * max size eviction
+ */
+export class ResponseCache {
     #cache = new Map();
     ttl = 60_000;
     maxSize = 32;
@@ -10,7 +17,7 @@ export class Prefetcher {
      * Converts a url path to a cache key by normalising it
      * against a base url
      */
-    static key(path, base) {
+    static toCacheKey(path, base) {
         try {
             const url = new URL(path, base);
             // hash is client-only and never sent to the server, so exclude it
@@ -40,8 +47,8 @@ export class Prefetcher {
         return this.#cache.has(path);
     }
     /**
-     * Retrieves a fresh response promise for the given path if it exists
-     * by cloning the cached response so each consumer gets an unread stream
+     * Retrieves a fresh response promise for the given path if it exists by
+     * cloning the cached response so each consumer gets an unread stream
      */
     get(path) {
         const promise = this.#cache.get(path)?.promise;

package/dist/internal/browser-router/router.d.ts

@@ -4,6 +4,7 @@ export { BrowserRouter } from './shared.js';
 export declare const BrowserRouterContext: import("react").Context<{
     go: BrowserRouter.Go;
     prefetch: (path: string) => void;
+    refresh: () => void;
     isNavigating: boolean;
     url: {
         pathname?: string | undefined;

package/dist/internal/browser-router/router.js

@@ -4,12 +4,13 @@ import { createContext, useCallback, useEffect, useMemo, useRef } from 'react';
 import { createFromFetch } from '@vitejs/plugin-rsc/browser';
 import { Logger } from '../../utils/logger.js';
 import { Solas } from '../../solas.js';
-import { Prefetcher } from '../prefetcher.js';
+import { ResponseCache } from './response-cache.js';
 import { BrowserRouter } from './shared.js';
 export { BrowserRouter } from './shared.js';
 export const BrowserRouterContext = createContext({
     go: async () => '',
     prefetch: () => { },
+    refresh: () => { },
     isNavigating: false,
     url: {},
 });
@@ -17,10 +18,18 @@ const DEFAULT_GO_CONFIG = {
     replace: false,
 };
 const logger = new Logger();
-const prefetcher = new Prefetcher();
+const responseCache = new ResponseCache();
 export function BrowserRouterProvider({ children, setPayload, isNavigating = false, url, }) {
     const id = useRef(0);
     const controller = useRef(null);
+    /**
+     * Navigates to a given path
+     *
+     * @param to - the target path to navigate to, which can be a route pattern with params or an external URL
+     * @param opts - options for navigation, including whether to replace the current history entry and pass query
+     * and route params
+     * @returns the final path navigated to after any redirects, or the original path if navigation failed
+     */
     const go = useCallback(async (to, opts = {}) => {
         id.current += 1;
         const navigationId = id.current;
@@ -36,7 +45,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                 throw new Error('[router.go]: external URLs are not supported. Use <a> instead');
             }
             const url = new URL(target, window.location.origin);
-            const key = Prefetcher.key(url.toString(), window.location.origin);
+            const key = ResponseCache.toCacheKey(url.toString(), window.location.origin);
             if (!key)
                 throw new Error('Invalid navigation url');
             path = key;
@@ -48,7 +57,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                     window.history.pushState(null, '', path);
                 }
             }
-            let promise = prefetcher.get(path);
+            let promise = responseCache.get(path);
             existing = promise !== undefined;
             if (!promise) {
                 const ctrl = new AbortController();
@@ -57,7 +66,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                     headers: { accept: 'text/x-component' },
                     signal: ctrl.signal,
                 });
-                prefetcher.set(path, promise);
+                responseCache.set(path, promise);
             }
             if (navigationId !== id.current)
                 return path;
@@ -65,7 +74,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
                 promise,
                 createFromFetch(promise),
             ]);
-            const resolvedPath = Prefetcher.key(res.url, window.location.origin) ?? path;
+            const resolvedPath = ResponseCache.toCacheKey(res.url, window.location.origin) ?? path;
             if (navigationId !== id.current)
                 return resolvedPath;
             if (resolvedPath !== path) {
@@ -92,20 +101,42 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         finally {
             if (navigationId === id.current)
                 controller.current = null;
-            if (!existing) {
-                prefetcher.remove(path);
-            }
+            if (!existing)
+                responseCache.remove(path);
         }
         return path;
     }, [setPayload]);
+    /**
+     * Prefetches the RSC response for a given path and caches it for later navigation.
+     * Does nothing if a cached response already exists for the path
+     *
+     * @param path - the target path to prefetch
+     * @returns void
+     */
     const prefetch = useCallback((path) => {
-        const key = Prefetcher.key(path, window.location.origin);
+        const key = ResponseCache.toCacheKey(path, window.location.origin);
         if (!key)
             return;
-        if (prefetcher.has(key))
+        if (responseCache.has(key))
             return;
-        prefetcher.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
+        responseCache.set(key, fetch(key, { headers: { Accept: 'text/x-component' } }));
     }, []);
+    /**
+     * Refreshes the current page by re-fetching the RSC response for the current path and updating the
+     * payload. It also clears any cached response for the current path to ensure that the latest
+     * version is fetched
+     */
+    const refresh = useCallback(() => {
+        const currentPath = window.location.pathname + window.location.search;
+        const key = ResponseCache.toCacheKey(currentPath, window.location.origin);
+        if (!key)
+            return;
+        if (responseCache.has(key))
+            responseCache.remove(key);
+        return go(currentPath, {
+            replace: true,
+        });
+    }, [go]);
     useEffect(() => {
         const handler = () => go(BrowserRouter.toTarget(window.location.pathname + window.location.search), {
             replace: true,
@@ -120,11 +151,12 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
     const value = useMemo(() => ({
         go,
         prefetch,
+        refresh,
         isNavigating,
         url: {
             pathname: url?.pathname,
             search: url?.search,
         },
-    }), [go, prefetch, isNavigating, url]);
+    }), [go, prefetch, refresh, isNavigating, url]);
     return _jsx(BrowserRouterContext, { value: value, children: children });
 }

package/dist/internal/browser-router/shared.js

@@ -24,6 +24,7 @@ var BrowserRouter;
      */
     function toTarget(path, params, query) {
         const used = new Set();
+        // first, replace all the :param parts with the corresponding params
         let to = path.replaceAll(/:([A-Za-z0-9_]+)/g, (_, key) => {
             const value = params?.[key];
             if (value == null) {

package/dist/internal/browser-router/use-router.d.ts

@@ -1,6 +1,7 @@
 export declare function useRouter(): {
     go: import("./shared.js").BrowserRouter.Go;
     prefetch: (path: string) => void;
+    refresh: () => void;
     isNavigating: boolean;
     url: {
         pathname?: string | undefined;

package/dist/internal/codegen/maps.js

@@ -37,8 +37,8 @@ export function writeMaps(imports, modules) {
             parts.push(`endpoint: ${toIdentifier(m.endpointId, `endpoint id for ${moduleId}`)}`);
         }
         if (m['401Ids']?.length) {
-            const unauthorized = toIdentifierList(m['401Ids'], `401s for ${moduleId}`);
-            parts.push(`'401s': [${unauthorized}]`);
+            const unauthorised = toIdentifierList(m['401Ids'], `401s for ${moduleId}`);
+            parts.push(`'401s': [${unauthorised}]`);
         }
         if (m['403Ids']?.length) {
             const forbidden = toIdentifierList(m['403Ids'], `403s for ${moduleId}`);
@@ -70,13 +70,15 @@ export function writeMaps(imports, modules) {
 		${AUTOGEN_MSG}
 
 		import type { ImportMap } from '${Solas.Config.PKG_NAME}'
-${importLines
+		
+		${importLines
         ? `
-${importLines}`
+			${importLines}
+		`
         : ''}
 
 		export const importMap = {
-${entries}
+			${entries}
 		} as const satisfies ImportMap
 	`;
 }

package/dist/utils/export-reader.js

@@ -99,7 +99,8 @@ export class ExportReader {
             // capture one supported literal value (string, number, boolean, null)
             '\\s*=\\s*(?<value>(?:"(?:[^"\\\\]|\\\\.)*"|\'(?:[^\'\\\\]|\\\\.)*\'|\\x60(?:[^\\x60\\\\]|\\\\.)*\\x60|true|false|null|-?\\d+(?:\\.\\d+)?))(?=\\s|;|$)';
         // multiline mode lets ^ match the start of each transpiled line, so the
-        // export regex stays anchored to a real statement boundary instead of the file start
+        // export regex stays anchored to a real statement boundary instead of
+        // the file start
         const text = code.match(new RegExp(source, 'm'))?.groups?.value;
         if (!text)
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jk2908/solas",
-	"version": "0.4.2",
+	"version": "0.4.4",
 	"description": "A Vite + React meta-framework exploring streaming, Server Components, and partial prerendering. Designed for simplicity and lightness",
 	"keywords": [
 		"framework",