@teyik0/furin 0.1.0-alpha.3

package/dist/internal.d.ts

@@ -0,0 +1,18 @@
+export interface EmbeddedAppData {
+    assets: Record<string, string>;
+    template: string;
+}
+export interface CompileContextRoute {
+    mode: "ssr" | "ssg" | "isr";
+    path: string;
+    pattern: string;
+}
+export interface CompileContext {
+    embedded?: EmbeddedAppData;
+    modules: Record<string, unknown>;
+    rootPath: string;
+    routes: CompileContextRoute[];
+}
+export declare function __setCompileContext(ctx: CompileContext): void;
+export declare function getCompileContext(): CompileContext | null;
+export declare function __resetCompileContext(): void;

package/dist/link.d.ts

@@ -0,0 +1,119 @@
+import type React from "react";
+import type { RuntimeRoute } from "./client";
+/**
+ * Augment this interface via declaration merging in .furin/routes.d.ts
+ * to get type-safe `to` autocompletion and per-route `search` types on <Link>.
+ *
+ * @example
+ * // .furin/routes.d.ts (auto-generated by Furin)
+ * import "@teyik0/furin/link";
+ * declare module "@teyik0/furin/link" {
+ *   interface RouteManifest {
+ *     "/blog": { search?: { page?: number; tag?: string } };
+ *     "/":     { search?: never };
+ *     [key: `/blog/${string}`]: { search?: never };
+ *   }
+ * }
+ */
+export interface RouteManifest {
+}
+/**
+ * The valid `to` pathname union derived from the augmented RouteManifest.
+ * Falls back to `string` when no routes.d.ts has been included in tsconfig.
+ */
+export type RouteTo = keyof RouteManifest extends never ? string : keyof RouteManifest;
+/**
+ * The typed search params for a given `to` pathname.
+ * Falls back to a permissive record when RouteManifest is not augmented.
+ */
+export type RouteSearch<To extends RouteTo> = keyof RouteManifest extends never ? Record<string, string | number | boolean | null | undefined> : To extends keyof RouteManifest ? RouteManifest[To] extends {
+    search?: infer S;
+} ? S : undefined : undefined;
+export type PreloadStrategy = false | "intent" | "viewport" | "render";
+export interface LinkProps<To extends RouteTo = RouteTo> extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+    /** Optional URL fragment (without the #). */
+    hash?: string;
+    /** Preload strategy. Default: "intent" (preload on hover/focus). */
+    preload?: PreloadStrategy;
+    /** Delay in ms before intent preload triggers. Default: 50. */
+    preloadDelay?: number;
+    /** How long a preloaded entry stays fresh (ms). Default: 30_000. */
+    preloadStaleTime?: number;
+    /** Typed search params for this route. Auto-completed from the route's query schema. */
+    search?: RouteSearch<To>;
+    to: To;
+}
+/**
+ * Builds a full href string from a pathname, optional search params, and optional hash.
+ * Null/undefined search values are omitted.
+ *
+ * @internal Exported for unit testing only.
+ */
+export declare function buildHref(to: string, search?: Record<string, unknown> | null, hash?: string): string;
+export interface RouterContextValue {
+    defaultPreload: PreloadStrategy;
+    defaultPreloadDelay: number;
+    defaultPreloadStaleTime: number;
+    isNavigating: boolean;
+    navigate: (href: string, opts?: {
+        replace?: boolean;
+    }) => Promise<void>;
+    prefetch: (href: string, opts?: {
+        staleTime?: number;
+    }) => void;
+}
+export declare const RouterContext: React.Context<RouterContextValue | null>;
+/**
+ * Returns the current router context.
+ * Provides a graceful fallback (full-page navigation) when used outside RouterProvider.
+ */
+export declare function useRouter(): RouterContextValue;
+export interface ClientRoute {
+    component?: React.ComponentType<Record<string, unknown>>;
+    load: () => Promise<{
+        default: {
+            component: React.ComponentType<Record<string, unknown>>;
+            _route: RuntimeRoute;
+        };
+    }>;
+    pageRoute?: RuntimeRoute;
+    pattern: string;
+    regex: RegExp;
+}
+/**
+ * A ClientRoute that has been loaded — component and pageRoute are guaranteed defined.
+ * The initial route is eagerly loaded in the hydrate entry; subsequent routes are loaded
+ * on navigation via fetchPageState.
+ */
+export type LoadedClientRoute = ClientRoute & {
+    component: React.ComponentType<Record<string, unknown>>;
+    pageRoute: RuntimeRoute;
+};
+export interface RouterProviderProps {
+    defaultPreload?: PreloadStrategy;
+    defaultPreloadDelay?: number;
+    defaultPreloadStaleTime?: number;
+    initialData: Record<string, unknown>;
+    initialMatch: LoadedClientRoute;
+    /** Maximum number of prefetch cache entries. Oldest entry is evicted when exceeded. Default: 50. */
+    prefetchCacheSize?: number;
+    root: RuntimeRoute | null;
+    routes: ClientRoute[];
+}
+interface RouterState {
+    data: Record<string, unknown>;
+    match: LoadedClientRoute;
+    title?: string;
+}
+/** @internal */
+export interface CacheEntry {
+    createdAt: number;
+    promise: Promise<RouterState | null>;
+}
+/** @internal Exported for unit testing only. */
+export declare function shouldRefetch(entry: CacheEntry, staleTime: number): boolean;
+/** @internal Exported for unit testing only. */
+export declare function buildPageElement(match: LoadedClientRoute, root: RuntimeRoute | null, data: Record<string, unknown>): React.ReactNode;
+export declare function RouterProvider({ routes, root, initialMatch, initialData, defaultPreload, defaultPreloadDelay, defaultPreloadStaleTime, prefetchCacheSize, }: RouterProviderProps): React.ReactElement;
+export declare function Link<To extends RouteTo>({ to, search, hash, preload, preloadDelay, preloadStaleTime, onClick, onMouseEnter, onMouseLeave, onFocus, children, ...anchorProps }: LinkProps<To>): React.ReactElement;
+export {};

package/dist/link.js

@@ -0,0 +1,281 @@
+// @bun
+// src/link.tsx
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState
+} from "react";
+function buildHref(to, search, hash) {
+  let url = to;
+  if (search && Object.keys(search).length > 0) {
+    const params = new URLSearchParams;
+    for (const [k, v] of Object.entries(search)) {
+      if (v != null) {
+        params.set(k, String(v));
+      }
+    }
+    const qs = params.toString();
+    if (qs) {
+      url += `?${qs}`;
+    }
+  }
+  if (hash) {
+    url += `#${hash}`;
+  }
+  return url;
+}
+var RouterContext = createContext(null);
+function useRouter() {
+  return useContext(RouterContext) ?? {
+    navigate: (href) => {
+      window.location.href = href;
+      return Promise.resolve();
+    },
+    prefetch: () => {},
+    isNavigating: false,
+    defaultPreload: "intent",
+    defaultPreloadDelay: 50,
+    defaultPreloadStaleTime: 30000
+  };
+}
+function shouldRefetch(entry, staleTime) {
+  return Date.now() - entry.createdAt > staleTime;
+}
+function buildPageElement(match, root, data) {
+  let element = createElement(match.component, data);
+  const allLayouts = [];
+  let current = match.pageRoute;
+  while (current) {
+    if (current.layout) {
+      allLayouts.unshift(current.layout);
+    }
+    current = current.parent;
+  }
+  const layouts = root ? allLayouts.slice(1) : allLayouts;
+  for (let i = layouts.length - 1;i >= 0; i--) {
+    const Layout = layouts[i];
+    if (Layout) {
+      element = createElement(Layout, { ...data }, element);
+    }
+  }
+  if (root?.layout) {
+    element = createElement(root.layout, { ...data }, element);
+  }
+  return element;
+}
+function RouterProvider({
+  routes,
+  root,
+  initialMatch,
+  initialData,
+  defaultPreload = "intent",
+  defaultPreloadDelay = 50,
+  defaultPreloadStaleTime = 30000,
+  prefetchCacheSize = 50
+}) {
+  const [state, setState] = useState({
+    match: initialMatch,
+    data: initialData
+  });
+  const [isNavigating, setIsNavigating] = useState(false);
+  const prefetchCache = useRef(new Map);
+  const fetchPageState = useCallback(async (href) => {
+    try {
+      const url = new URL(href, window.location.origin);
+      const match = routes.find((r) => r.regex.test(url.pathname));
+      if (!match) {
+        return null;
+      }
+      const [res, loadedMod] = await Promise.all([fetch(href), match.load()]);
+      const html = await res.text();
+      const doc = new DOMParser().parseFromString(html, "text/html");
+      const dataEl = doc.getElementById("__FURIN_DATA__");
+      const data = dataEl ? JSON.parse(dataEl.textContent || "{}") : {};
+      const loadedMatch = {
+        ...match,
+        component: loadedMod.default.component,
+        pageRoute: loadedMod.default._route
+      };
+      return { match: loadedMatch, data, title: doc.title };
+    } catch {
+      return null;
+    }
+  }, [routes]);
+  const prefetch = useCallback((href, opts) => {
+    const staleTime = opts?.staleTime ?? defaultPreloadStaleTime;
+    const existing = prefetchCache.current.get(href);
+    if (existing && !shouldRefetch(existing, staleTime)) {
+      return;
+    }
+    prefetchCache.current.set(href, {
+      promise: fetchPageState(href),
+      createdAt: Date.now()
+    });
+    if (prefetchCache.current.size > prefetchCacheSize) {
+      const oldest = prefetchCache.current.keys().next().value;
+      prefetchCache.current.delete(oldest);
+    }
+  }, [fetchPageState, defaultPreloadStaleTime, prefetchCacheSize]);
+  const navigate = useCallback(async (href, opts) => {
+    prefetch(href);
+    setIsNavigating(true);
+    try {
+      const newState = await prefetchCache.current.get(href)?.promise;
+      if (!newState) {
+        window.location.href = href;
+        return;
+      }
+      setState(newState);
+      if (newState.title) {
+        document.title = newState.title;
+      }
+      if (opts?.replace) {
+        window.history.replaceState(null, "", href);
+      } else {
+        window.history.pushState(null, "", href);
+      }
+      window.scrollTo(0, 0);
+    } finally {
+      setIsNavigating(false);
+    }
+  }, [prefetch]);
+  const handlePopState = useCallback(async () => {
+    const href = window.location.pathname + window.location.search;
+    setIsNavigating(true);
+    try {
+      const newState = await fetchPageState(href);
+      if (!newState) {
+        window.location.reload();
+        return;
+      }
+      setState(newState);
+      if (newState.title) {
+        document.title = newState.title;
+      }
+    } finally {
+      setIsNavigating(false);
+    }
+  }, [fetchPageState]);
+  useEffect(() => {
+    window.addEventListener("popstate", handlePopState);
+    return () => window.removeEventListener("popstate", handlePopState);
+  }, [handlePopState]);
+  return createElement(RouterContext.Provider, {
+    value: {
+      navigate,
+      prefetch,
+      isNavigating,
+      defaultPreload,
+      defaultPreloadDelay,
+      defaultPreloadStaleTime
+    }
+  }, buildPageElement(state.match, root, state.data));
+}
+function Link({
+  to,
+  search,
+  hash,
+  preload,
+  preloadDelay,
+  preloadStaleTime,
+  onClick,
+  onMouseEnter,
+  onMouseLeave,
+  onFocus,
+  children,
+  ...anchorProps
+}) {
+  const router = useRouter();
+  const anchorRef = useRef(null);
+  const intentTimerRef = useRef(null);
+  const href = buildHref(to, search, hash);
+  const effectivePreload = preload ?? router.defaultPreload;
+  const effectiveDelay = preloadDelay ?? router.defaultPreloadDelay;
+  const effectiveStaleTime = preloadStaleTime ?? router.defaultPreloadStaleTime;
+  const triggerPrefetch = useCallback(() => {
+    router.prefetch(href, { staleTime: effectiveStaleTime });
+  }, [router, href, effectiveStaleTime]);
+  useEffect(() => {
+    if (effectivePreload === "render") {
+      triggerPrefetch();
+    }
+  }, [effectivePreload, triggerPrefetch]);
+  useEffect(() => {
+    if (effectivePreload !== "viewport" || !anchorRef.current) {
+      return;
+    }
+    const observer = new IntersectionObserver(([entry]) => {
+      if (entry?.isIntersecting) {
+        triggerPrefetch();
+        observer.disconnect();
+      }
+    }, { rootMargin: "200px" });
+    observer.observe(anchorRef.current);
+    return () => observer.disconnect();
+  }, [effectivePreload, triggerPrefetch]);
+  const isInternal = (url) => {
+    try {
+      return new URL(url, window.location.origin).origin === window.location.origin;
+    } catch {
+      return false;
+    }
+  };
+  const handleClick = (e) => {
+    onClick?.(e);
+    if (e.defaultPrevented) {
+      return;
+    }
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) {
+      return;
+    }
+    if (anchorProps.target && anchorProps.target !== "_self") {
+      return;
+    }
+    if (!isInternal(href)) {
+      return;
+    }
+    e.preventDefault();
+    router.navigate(href);
+  };
+  const handleMouseEnter = (e) => {
+    onMouseEnter?.(e);
+    if (effectivePreload === "intent" && isInternal(href)) {
+      intentTimerRef.current = setTimeout(triggerPrefetch, effectiveDelay);
+    }
+  };
+  const handleMouseLeave = (e) => {
+    onMouseLeave?.(e);
+    if (intentTimerRef.current !== null) {
+      clearTimeout(intentTimerRef.current);
+      intentTimerRef.current = null;
+    }
+  };
+  const handleFocus = (e) => {
+    onFocus?.(e);
+    if (effectivePreload === "intent" && isInternal(href)) {
+      triggerPrefetch();
+    }
+  };
+  return createElement("a", {
+    ref: anchorRef,
+    href,
+    onClick: handleClick,
+    onMouseEnter: handleMouseEnter,
+    onMouseLeave: handleMouseLeave,
+    onFocus: handleFocus,
+    ...anchorProps
+  }, children);
+}
+export {
+  useRouter,
+  shouldRefetch,
+  buildPageElement,
+  buildHref,
+  RouterProvider,
+  RouterContext,
+  Link
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standalone Bun bundler plugin for Furin.
+ *
+ * Register it in your project's bunfig.toml so that Bun's HTML bundler
+ * applies it when building the client bundle:
+ *
+ * ```toml
+ * [serve.static]
+ * plugins = ["@teyik0/furin/strip-plugin"]
+ * ```
+ *
+ * The plugin:
+ *  1. Stubs `elysia` for the browser with a minimal proxy.
+ *  2. Stubs `bun:*` builtins with an empty module (safety net — DCE removes
+ *     loader imports before they reach the browser bundle in practice).
+ *  3. Strips server-only code (loader, query, params) from page files before
+ *     they are bundled into the client entry.
+ */
+declare const plugin: Bun.BunPlugin;
+export default plugin;