@jk2908/solas 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.5.4 - 2026-06-08
+
+- Add a BrowserRouterHistory API to sync app back/forward navigation with browser navigation.
+- Expose BrowserRouterContext.history for gated use in client components
+
 ## 0.5.3 - 2026-06-06
 
 - Ensured `createRuntime(...)` is exported from `@jk2908/solas/env/rsc` for generated RSC entry compatibility.

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

@@ -0,0 +1,46 @@
+import type { BrowserRouter } from './shared.js';
+/**
+ * A small in-memory mirror of browser history used by BrowserRouter.
+ * It keeps local entries/index in sync with push/replace/go and
+ * popstate updates
+ */
+export declare class BrowserRouterHistory {
+    #private;
+    constructor(url: {
+        pathname: string;
+        search?: string;
+        hash?: string;
+    });
+    /**
+     * Returns a copy of tracked entries
+     */
+    get entries(): BrowserRouter.HistoryEntry[];
+    /**
+     * Returns the tracked history index
+     */
+    get index(): number;
+    /**
+     * Returns the tracked history length
+     */
+    get length(): number;
+    /**
+     * Returns the current tracked entry
+     */
+    get current(): BrowserRouter.HistoryEntry;
+    /**
+     * Pushes a new history entry and advances the index
+     */
+    pushState(path: string): BrowserRouter.HistoryEntry;
+    /**
+     * Replaces the current history entry without changing length
+     */
+    replaceState(path: string): BrowserRouter.HistoryEntry;
+    /**
+     * Applies relative history movement and updates local index
+     */
+    go(delta: number): BrowserRouter.HistoryEntry;
+    /**
+     * Syncs local index and entry from a popstate event
+     */
+    onPopState(): BrowserRouter.HistoryEntry;
+}

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

@@ -0,0 +1,131 @@
+/**
+ * A small in-memory mirror of browser history used by BrowserRouter.
+ * It keeps local entries/index in sync with push/replace/go and
+ * popstate updates
+ */
+export class BrowserRouterHistory {
+    #entries;
+    #index;
+    constructor(url) {
+        const entry = {
+            pathname: url.pathname,
+            search: url.search ?? '',
+            hash: url.hash ?? '',
+        };
+        this.#entries = [entry];
+        this.#index = 0;
+    }
+    /**
+     * Returns a copy of tracked entries
+     */
+    get entries() {
+        return [...this.#entries];
+    }
+    /**
+     * Returns the tracked history index
+     */
+    get index() {
+        return this.#index;
+    }
+    /**
+     * Returns the tracked history length
+     */
+    get length() {
+        return this.#entries.length;
+    }
+    /**
+     * Returns the current tracked entry
+     */
+    get current() {
+        return this.#entries[this.#index] ?? null;
+    }
+    /**
+     * Pushes a new history entry and advances the index
+     */
+    pushState(path) {
+        if (this.#index < this.#entries.length - 1) {
+            // drop forward entries when pushing from the middle
+            this.#entries = this.#entries.slice(0, this.#index + 1);
+        }
+        window.history.pushState(null, '', path);
+        const entry = {
+            pathname: window.location.pathname,
+            search: window.location.search,
+            hash: window.location.hash,
+        };
+        this.#entries.push(entry);
+        this.#index++;
+        return entry;
+    }
+    /**
+     * Replaces the current history entry without changing length
+     */
+    replaceState(path) {
+        window.history.replaceState(null, '', path);
+        const entry = {
+            pathname: window.location.pathname,
+            search: window.location.search,
+            hash: window.location.hash,
+        };
+        if (this.#entries.length === 0) {
+            this.#entries = [entry];
+            this.#index = 0;
+            return entry;
+        }
+        this.#entries[this.#index] = entry;
+        return entry;
+    }
+    /**
+     * Applies relative history movement and updates local index
+     */
+    go(delta) {
+        if (!Number.isInteger(delta) || delta === 0) {
+            return this.current;
+        }
+        const nextIndex = Math.max(0, Math.min(this.#index + delta, this.#entries.length - 1));
+        if (nextIndex !== this.#index)
+            this.#index = nextIndex;
+        window.history.go(delta);
+        return this.current;
+    }
+    /**
+     * Syncs local index and entry from a popstate event
+     */
+    onPopState() {
+        const current = {
+            pathname: window.location.pathname,
+            search: window.location.search,
+            hash: window.location.hash,
+        };
+        const prev = this.#entries[this.#index - 1];
+        const next = this.#entries[this.#index + 1];
+        if (prev &&
+            prev.pathname === current.pathname &&
+            prev.search === current.search &&
+            prev.hash === current.hash) {
+            this.#index--;
+            this.#entries[this.#index] = current;
+            return current;
+        }
+        if (next &&
+            next.pathname === current.pathname &&
+            next.search === current.search &&
+            next.hash === current.hash) {
+            this.#index++;
+            this.#entries[this.#index] = current;
+            return current;
+        }
+        // fallback: locate an existing matching entry
+        const index = this.#entries.findIndex(entry => entry.pathname === current.pathname &&
+            entry.search === current.search &&
+            entry.hash === current.hash);
+        if (index >= 0) {
+            this.#index = index;
+            this.#entries[index] = current;
+            return current;
+        }
+        this.#entries.push(current);
+        this.#index = this.#entries.length - 1;
+        return current;
+    }
+}

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

@@ -1,22 +1,14 @@
 import type { RscPayload } from '../env/rsc.js';
 import { BrowserRouter } from './shared.js';
 export { BrowserRouter } from './shared.js';
-export declare const BrowserRouterContext: import("react").Context<{
-    go: BrowserRouter.Go;
-    prefetch: (path: string) => void;
-    refresh: BrowserRouter.Refresh;
-    isNavigating: boolean;
-    url: {
-        pathname?: string | undefined;
-        search?: string | undefined;
-    };
-}>;
+export declare const BrowserRouterContext: import("react").Context<BrowserRouter.Context>;
 export declare function BrowserRouterProvider({ children, setPayload, isNavigating, url }: {
     children: React.ReactNode;
     setPayload?: (payload: RscPayload) => void;
     isNavigating?: boolean;
-    url?: {
-        pathname?: string;
+    url: {
+        pathname: string;
         search?: string;
+        hash?: string;
     };
 }): import("react/jsx-runtime").JSX.Element;

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

@@ -4,6 +4,7 @@ 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 { BrowserRouterHistory } from './history.js';
 import { ResponseCache } from './response-cache.js';
 import { BrowserRouter } from './shared.js';
 export { BrowserRouter } from './shared.js';
@@ -12,7 +13,15 @@ export const BrowserRouterContext = createContext({
     prefetch: () => { },
     refresh: async () => '',
     isNavigating: false,
-    url: {},
+    url: {
+        pathname: '',
+        search: '',
+        hash: '',
+    },
+    history: {
+        entries: [],
+        index: -1,
+    },
 });
 const DEFAULT_GO_CONFIG = {
     replace: false,
@@ -22,6 +31,7 @@ const responseCache = new ResponseCache();
 export function BrowserRouterProvider({ children, setPayload, isNavigating = false, url, }) {
     const id = useRef(0);
     const controller = useRef(null);
+    const history = useRef(new BrowserRouterHistory(url));
     /**
      * Navigates to a given path
      *
@@ -35,6 +45,13 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         const navigationId = id.current;
         const currentPath = window.location.pathname + window.location.search;
         let path = currentPath;
+        // support numeric relative navigation like router.go(-1) to go back,
+        // or router.go(1) to go forward. Will trigger a popstate event which
+        // is intercepted
+        if (typeof to === 'number') {
+            const entry = history.current.go(to);
+            return `${entry.pathname}${entry.search}`;
+        }
         const replace = opts?.replace ?? DEFAULT_GO_CONFIG.replace;
         controller.current?.abort();
         controller.current = null;
@@ -51,10 +68,10 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
             path = key;
             if (path !== currentPath) {
                 if (replace) {
-                    window.history.replaceState(null, '', path);
+                    history.current.replaceState(path);
                 }
                 else {
-                    window.history.pushState(null, '', path);
+                    history.current.pushState(path);
                 }
             }
             let promise = responseCache.get(path);
@@ -78,7 +95,7 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
             if (navigationId !== id.current)
                 return resolvedPath;
             if (resolvedPath !== path) {
-                window.history.replaceState(null, '', resolvedPath);
+                history.current.replaceState(resolvedPath);
             }
             setPayload?.(payload);
             window.dispatchEvent(new CustomEvent(Solas.Events.names.NAVIGATION, {
@@ -138,9 +155,13 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         });
     }, [go]);
     useEffect(() => {
-        const handler = () => go(BrowserRouter.toTarget(window.location.pathname + window.location.search), {
-            replace: true,
-        });
+        const h = history.current;
+        function handler() {
+            h.onPopState();
+            void go(BrowserRouter.toTarget(window.location.pathname + window.location.search), {
+                replace: true,
+            });
+        }
         window.addEventListener('popstate', handler);
         return () => {
             controller.current?.abort();
@@ -154,8 +175,13 @@ export function BrowserRouterProvider({ children, setPayload, isNavigating = fal
         refresh,
         isNavigating,
         url: {
-            pathname: url?.pathname,
+            pathname: url.pathname,
             search: url?.search,
+            hash: url?.hash,
+        },
+        history: {
+            entries: history.current.entries,
+            index: history.current.index,
         },
     }), [go, prefetch, refresh, isNavigating, url]);
     return _jsx(BrowserRouterContext, { value: value, children: children });

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

@@ -11,6 +11,26 @@ export declare namespace BrowserRouter {
         query?: Query;
         params?: Params;
     };
+    export type Context = {
+        go: BrowserRouter.Go;
+        prefetch: (path: string) => void;
+        refresh: BrowserRouter.Refresh;
+        isNavigating: boolean;
+        url: {
+            pathname: string;
+            search?: string;
+            hash?: string;
+        };
+        history: {
+            entries: HistoryEntry[];
+            index: number;
+        };
+    };
+    export type HistoryEntry = {
+        pathname: string;
+        search: string;
+        hash: string;
+    };
     /**
      * These targets are used as-is. They are not matched against the route table,
      * so this covers normal external URLs and hash-only links
@@ -152,6 +172,7 @@ export declare namespace BrowserRouter {
      * ```
      */
     export type Go = {
+        (to: number): Promise<string>;
         <TTo extends Path>(to: TTo, opts?: PatternConfig<TTo> & Replace): Promise<string>;
         <TTo extends Target>(to: TTo, opts?: TargetConfig & Replace): Promise<string>;
         <TTo extends string>(to: string extends TTo ? TTo : never, opts?: GoOptions): Promise<string>;

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

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

package/dist/internal/env/rsc.d.ts

@@ -12,9 +12,10 @@ export type RscPayload = {
     formState?: ReactFormState;
     root: React.ReactNode;
     metadata?: Promise<Metadata.Item>;
-    url?: {
-        pathname?: string;
+    url: {
+        pathname: string;
         search?: string;
+        hash?: string;
     };
 };
 /**

package/dist/internal/env/rsc.js

@@ -65,6 +65,7 @@ async function createPayload(req, manifest, importMap, baseMetadata, returnValue
             url: {
                 pathname: url.pathname,
                 search: url.search,
+                hash: url.hash,
             },
         };
         return {

package/package.json

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

package/dist/runtimes/bun.d.ts

@@ -1,13 +0,0 @@
-import { RuntimeBase } from '../internal/runtimes/runtime.js';
-declare class BunAdapter extends RuntimeBase {
-    readonly name: "bun";
-    readonly module: string;
-    exists(filePath: string): Promise<boolean>;
-    readText(filePath: string): Promise<string>;
-    readBuffer(filePath: string): Promise<ArrayBuffer>;
-    mimeType(filePath: string): string;
-    write(filePath: string, content: string | NodeJS.ArrayBufferView): Promise<void>;
-    hash(value: string): string;
-}
-export default function bunAdapter(): BunAdapter;
-export {};

package/dist/runtimes/bun.js

@@ -1,39 +0,0 @@
-import { RuntimeBase } from '../internal/runtimes/runtime.js';
-import { Solas } from '../solas.js';
-class BunAdapter extends RuntimeBase {
-    name = 'bun';
-    module = `${Solas.Config.PKG_NAME}/runtimes/bun`;
-    async exists(filePath) {
-        return Bun.file(filePath).exists();
-    }
-    readText(filePath) {
-        return Bun.file(filePath).text();
-    }
-    readBuffer(filePath) {
-        return Bun.file(filePath).arrayBuffer();
-    }
-    mimeType(filePath) {
-        return Bun.file(filePath).type || 'application/octet-stream';
-    }
-    async write(filePath, content) {
-        // normalise wider arraybuffer views into a shape Bun.write accepts directly
-        await Bun.write(filePath, typeof content === 'string'
-            ? content
-            : content instanceof Uint8Array
-                ? content
-                : new Uint8Array(content.buffer, content.byteOffset, content.byteLength));
-    }
-    hash(value) {
-        const hash = Bun.hash(value);
-        // Bun.hash returns an integer-like value, so keep it in BigInt space and avoid
-        // precision loss. Clamp it to an unsigned 64-bit value before hex
-        // formatting. Pad to 16 chars to match the Node adapter
-        // output shape
-        return BigInt.asUintN(64, typeof hash === 'bigint' ? hash : BigInt(hash))
-            .toString(16)
-            .padStart(16, '0');
-    }
-}
-export default function bunAdapter() {
-    return new BunAdapter();
-}