void-plugin-hono-jsx 0.1.0-alpha.3 → 0.1.0-alpha.4

package/src/runtime/client.tsx

@@ -1,12 +1,14 @@
-import { render } from 'hono/jsx/dom';
+import { ErrorBoundary, render } from 'hono/jsx/dom';
 import { jsx } from 'hono/jsx/dom/jsx-runtime';
 import { useLayoutEffect, useState } from 'hono/jsx';
-import { createVoidRouter, type VoidRouterConfig } from 'void/pages-client';
-import { parseCacheFor } from 'void/pages-prefetch';
-import { PageContext, RouterContext } from './pages.tsx';
+import { idleNavigationState, type NavigationState, type VoidRouterConfig } from 'void/pages-client';
+import { PageContext, RouterContext, NavigationContext, setActionRouter } from './pages.tsx';
+import { createHonoRouter } from './navigation.ts';
 import { createDocumentHead } from './document-head.ts';
 import { createDeferred, resolveDeferred, rejectDeferred, isLoading, bufferInitialDeferred } from './deferred.ts';
 
+type NavigationOptions = Pick<VoidRouterConfig, 'viewTransitions' | 'prefetchHoverDelay' | 'prefetchDefaultCacheFor'>;
+
 type Manifest = Pick<VoidRouterConfig, 'components' | 'layoutTree' | 'routeMeta' | 'matchRoute' | 'staticPageData' | 'staticPageDataFastPath'>;
 
 function pageComponent(component: unknown) {
@@ -14,16 +16,22 @@ function pageComponent(component: unknown) {
   return component;
 }
 
-export async function startHonoPages(manifest: Manifest) {
+export async function startHonoPages(manifest: Manifest, options: NavigationOptions) {
   const root = document.getElementById('app');
   if (!root) throw new Error('Hono Pages: app root is missing.');
-  type Frame = { page: Awaited<ReturnType<typeof createVoidRouter>>['initialPageData']; component: unknown; layouts: unknown[]; revision: number };
+  type Frame = { page: Awaited<ReturnType<typeof createHonoRouter>>['initialPageData']; sourceProps: Record<string, unknown>; component: unknown; layouts: unknown[]; revision: number; commit: number };
   let update: ((frame: Frame) => void) | undefined;
   let revision = 0;
+  let commit = 0;
+  const pendingCommits = new Map<number, { resolve(): void; reject(error: unknown): void }>();
+  let committedFrame: Frame | undefined;
+  const failedFrames = new Set<number>();
+  let navigationState = idleNavigationState();
+  let updateNavigation: ((state: NavigationState) => void) | undefined;
   let applyDocumentHead: ReturnType<typeof createDocumentHead> | undefined;
   let renderedProps: Record<string, unknown> | undefined;
   let updateDeferred: ((props: Record<string, unknown>) => void) | undefined;
-  const initialization = createVoidRouter({
+  const initialization = createHonoRouter({
     ...manifest,
     adapter: {
       createDeferred, resolveDeferred, rejectDeferred, isLoading,
@@ -36,42 +44,76 @@ export async function startHonoPages(manifest: Manifest) {
         if (!update) throw new Error('Hono Pages: page rendering has not started.');
         if (!options.preserveState) revision++;
         renderedProps = page.props;
-        update({ page: { ...page, props: { ...page.props } }, component, layouts, revision });
-        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
-        applyDocumentHead?.(page.head);
+        const nextCommit = ++commit;
+        const committed = new Promise<void>((resolve, reject) => pendingCommits.set(nextCommit, { resolve, reject }));
+        update({ page: { ...page, props: { ...page.props } }, sourceProps: page.props, component, layouts, revision, commit: nextCommit });
+        await committed;
       },
     },
-    viewTransitions: false,
-    prefetchHoverDelay: 75,
-    prefetchDefaultCacheFor: parseCacheFor('30s'),
+    ...options,
     cacheVisitedPageData: false,
-    onNavigationChange(state) { root.dataset.navigation = state.state; },
+    onNavigationChange(state) { navigationState = state; updateNavigation?.(state); root.dataset.navigation = state.state; },
   });
   const releaseBuffer = bufferInitialDeferred();
   const navigation = await initialization.finally(releaseBuffer);
+  setActionRouter(navigation.router);
   renderedProps = navigation.initialPageData.props;
   applyDocumentHead = createDocumentHead(navigation.initialPageData.head);
 
+  const initialFrame: Frame = { page: { ...navigation.initialPageData, props: { ...navigation.initialPageData.props } }, sourceProps: navigation.initialPageData.props, component: navigation.initialComponent, layouts: navigation.initialLayouts, revision, commit };
+  function PageFrame({ frame }: { frame: Frame }) {
+    useLayoutEffect(() => {
+      if (failedFrames.has(frame.commit)) return;
+      if (frame.commit > 0) applyDocumentHead?.(frame.page.head);
+      committedFrame = frame;
+      for (const id of failedFrames) if (id < frame.commit) failedFrames.delete(id);
+      for (const [id, pending] of pendingCommits) if (id <= frame.commit) { pendingCommits.delete(id); pending.resolve(); }
+    }, [frame]);
+    let content = jsx(pageComponent(frame.component), frame.page.props, String(frame.revision));
+    const ids = manifest.layoutTree[frame.page.component] ?? [];
+    for (let index = frame.layouts.length - 1; index >= 0; index--) {
+      content = jsx(pageComponent(frame.layouts[index]), { children: content }, ids[index]);
+    }
+    return <PageContext.Provider value={frame.page}>{content}</PageContext.Provider>;
+  }
+
   function App() {
-    const [frame, setFrame] = useState<Frame>({ page: { ...navigation.initialPageData, props: { ...navigation.initialPageData.props } }, component: navigation.initialComponent, layouts: navigation.initialLayouts, revision });
+    const [frame, setFrame] = useState<Frame>(initialFrame);
+    const [pendingNavigation, setNavigation] = useState(navigationState);
     const [failed, setFailed] = useState(false);
+    const [recovery, setRecovery] = useState(0);
     useLayoutEffect(() => {
+      updateNavigation = setNavigation;
+      setNavigation(navigationState);
       updateDeferred = (props) => setFrame((frame) => ({ ...frame, page: { ...frame.page, props } }));
       update = (next) => { setFailed(false); setFrame(next); };
       const onError = () => setFailed(true);
       window.addEventListener('hono-pages:navigation-error', onError);
-      return () => { update = undefined; updateDeferred = undefined; window.removeEventListener('hono-pages:navigation-error', onError); };
+      return () => { for (const pending of pendingCommits.values()) pending.reject(new DOMException('Hono Pages: renderer unmounted.', 'AbortError')); pendingCommits.clear(); updateNavigation = undefined; update = undefined; updateDeferred = undefined; window.removeEventListener('hono-pages:navigation-error', onError); };
     }, []);
-    let content = jsx(pageComponent(frame.component), frame.page.props, String(frame.revision));
-    const ids = manifest.layoutTree[frame.page.component] ?? [];
-    for (let index = frame.layouts.length - 1; index >= 0; index--) {
-      content = jsx(pageComponent(frame.layouts[index]), { children: content }, ids[index]);
-    }
+    const renderFailed = (error: unknown) => {
+      if (failedFrames.has(frame.commit)) return;
+      failedFrames.add(frame.commit);
+      queueMicrotask(() => {
+      // A rejected child never reaches PageFrame's commit effect. Roll back
+      // outside the render traversal, then reject every coalesced waiter.
+      if (commit === frame.commit) {
+        if (committedFrame) { renderedProps = committedFrame.sourceProps; setFrame(committedFrame); }
+        // Discard the partially built Hono tree only after a render failure.
+        // Successful navigations keep the same boundary and layout state.
+        setRecovery(value => value + 1);
+        setFailed(true);
+      }
+      for (const [id, pending] of pendingCommits) if (id <= frame.commit) { pendingCommits.delete(id); pending.reject(error); }
+      });
+    };
     return <RouterContext.Provider value={navigation.router}>
-      <PageContext.Provider value={frame.page}>
+      <NavigationContext.Provider value={pendingNavigation}>
         {failed && <p role="alert">The page could not be loaded. Please try again.</p>}
-        {content}
-      </PageContext.Provider>
+        <ErrorBoundary key={recovery} onError={renderFailed} fallback={<></>}>
+          <PageFrame frame={frame} />
+        </ErrorBoundary>
+      </NavigationContext.Provider>
     </RouterContext.Provider>;
   }
 

package/src/runtime/document-head.ts

@@ -11,7 +11,11 @@ function scriptElements(head: HeadDescriptor | undefined) {
   return Array.from(template.content.querySelectorAll('script'));
 }
 
-/** Complements Void's title/meta/link updates without executing navigation scripts. */
+function metadataSignature(element: Element) {
+  return JSON.stringify([element.tagName, Array.from(element.attributes, ({ name, value }) => [name, value]).filter(([name]) => name !== 'data-void-head').sort()]);
+}
+
+/** Synchronizes the snapshot before Void's idempotent post-render head commit. */
 export function createDocumentHead(initial: HeadDescriptor | undefined) {
   let htmlKeys = Object.keys(initial?.htmlAttrs ?? {});
   let bodyKeys = Object.keys(initial?.bodyAttrs ?? {});
@@ -29,6 +33,21 @@ export function createDocumentHead(initial: HeadDescriptor | undefined) {
   }
 
   return (head: HeadDescriptor | undefined) => {
+    if (head?.title !== undefined) document.title = head.title;
+    // Use Void's serializer and managed-tag marker so the router's subsequent
+    // commit reuses these nodes instead of inserting duplicate meta/link tags.
+    const template = document.createElement('template');
+    template.innerHTML = renderHeadToString({ meta: head?.meta, link: head?.link });
+    const metadata = Array.from(document.head.querySelectorAll('meta[data-void-head],link[data-void-head]'));
+    let cursor = document.head.querySelector('meta[data-void-head],link[data-void-head]') as Node | null;
+    for (const desired of Array.from(template.content.querySelectorAll('meta,link'))) {
+      const index = metadata.findIndex(element => metadataSignature(element) === metadataSignature(desired));
+      const element = index >= 0 ? metadata.splice(index, 1)[0] : desired;
+      element.setAttribute('data-void-head', '');
+      if (element !== cursor) document.head.insertBefore(element, cursor);
+      cursor = element.nextSibling;
+    }
+    for (const previous of metadata) previous.remove();
     htmlKeys = attributes(document.documentElement, htmlKeys, head?.htmlAttrs);
     bodyKeys = attributes(document.body, bodyKeys, head?.bodyAttrs);
     const remaining = [...scripts];

package/src/runtime/form-view.tsx

@@ -0,0 +1,23 @@
+import { useEffect, useState, type JSX, type Child } from 'hono/jsx';
+import { formErrorMessage, formRetryMessage, formSubmissionBlocked, scheduleFormRetry, type FormMethod, type FormModel, type VoidActionError } from 'void/pages-client';
+
+export type FormProps = Omit<JSX.IntrinsicElements['form'], 'action' | 'method' | 'onSubmit' | 'onError'> & {
+  form: FormModel<[string | FormData | undefined]>;
+  method?: FormMethod;
+  url?: string;
+  renderError?: (error: VoidActionError) => Child;
+};
+export function Form({ form, method = 'post', url, renderError, children, ...props }: FormProps) {
+  const [now, setNow] = useState(Date.now());
+  useEffect(() => scheduleFormRetry(form.error, () => setNow(Date.now())), [form.error]);
+  const message = formErrorMessage(form);
+  const retry = formRetryMessage(form.error);
+  const blocked = formSubmissionBlocked(form, now);
+  return <form {...props} aria-busy={form.pending} onSubmit={(event: Event) => {
+    event.preventDefault();
+    if (!blocked) void form[method](url ?? new FormData(event.currentTarget as HTMLFormElement));
+  }}>
+    {message && <div role="alert" data-void-form-error>{form.error && renderError ? renderError(form.error) : message}{retry && <p>{retry}</p>}</div>}
+    {children}
+  </form>;
+}

package/src/runtime/form.ts

@@ -1,6 +1,27 @@
-import { useContext, useRef, useState } from 'hono/jsx';
-import { isAbortError, submitAction, VoidActionError, type FormMethod } from 'void/pages-client';
-import { RouterContext, useErrors, useRouter } from './pages.tsx';
+import { useContext, useEffect, useRef, useState } from 'hono/jsx';
+import { isAbortError, isEqualFormValue, interpolateRouteParams, submitAction, VoidActionError, type ActionResult, type FormMethod } from 'void/pages-client';
+import type { ActionFormOptions, ActionUrl, ResolveActionBody } from 'void/routes';
+import { RouterContext, useErrors, useRouter, action } from './pages.tsx';
+export { Form, type FormProps } from './form-view.tsx';
+export { action };
+
+type Fields = Record<string, unknown>;
+type Body<U extends string> = ResolveActionBody<U> extends Fields ? ResolveActionBody<U> : Fields;
+type SetData<T> = { (next: T | ((current: T) => T)): void; <K extends keyof T & string>(field: K, value: T[K]): void };
+export type HonoForm<T extends Fields> = {
+  data: T; setData: SetData<T>; errors: Record<string, string>; pending: boolean;
+  error: VoidActionError | null; hasChanges: boolean; wasSuccessful: boolean; recentlySuccessful: boolean;
+  submit(method: FormMethod, target?: string | FormData): Promise<void>; cancel(): void;
+  reset: { (): void; (...fields: Array<keyof T & string>): void }; clearErrors(...fields: Array<keyof T & string>): void; clearError(): void;
+} & Record<FormMethod, (target?: string | FormData) => Promise<void>>;
+
+function toFormError(failure: unknown, url: string): VoidActionError {
+  if (failure instanceof VoidActionError) return failure;
+  const message = failure instanceof Error ? failure.message : String(failure);
+  const error = new VoidActionError({ body: { message }, status: 0, statusText: 'Network Error', url });
+  error.message = message;
+  return error;
+}
 
 function fieldErrors(error: VoidActionError): Record<string, string> {
   const body = error.body;
@@ -8,64 +29,84 @@ function fieldErrors(error: VoidActionError): Record<string, string> {
   return Object.fromEntries(Object.entries(body.errors).filter((entry): entry is [string, string] => typeof entry[1] === 'string'));
 }
 
-export function useForm<T extends Record<string, unknown>>(initialData: T) {
-  if (!useContext(RouterContext)) throw new Error('Hono Pages: useForm requires the full Pages renderer; island form helpers are unsupported.');
+export function useForm<T extends Fields>(initialData: T): HonoForm<T>;
+export function useForm<U extends ActionUrl & string>(url: U, defaults: Body<U>, options?: ActionFormOptions<U>): HonoForm<Body<U>>;
+export function useForm(initial: string | Fields, values?: Fields, options?: { params?: Record<string, string> }): HonoForm<Fields> {
+  if (!useContext(RouterContext)) throw new Error('Hono Pages: useForm requires the full Pages renderer; use useIslandForm for islands.');
   const router = useRouter();
-  const initialErrors = useErrors();
-  const [data, updateData] = useState(initialData);
+  const bound = typeof initial === 'string' ? initial : undefined;
+  return useFormModel(typeof initial === 'string' ? values ?? {} : initial, useErrors(), async (method, url, data) => submitAction(router, interpolateRouteParams(url, options?.params), { method: method.toUpperCase(), data, preserveScroll: true }), () => router.refresh(), bound);
+}
+
+export function useIslandForm<T extends Fields>(defaults: T): HonoForm<T> {
+  const controller = useRef<AbortController | null>(null);
+  useEffect(() => () => controller.current?.abort(), []);
+  return useFormModel(defaults, {}, async (method, url, data) => {
+    const target = new URL(url, window.location.href);
+    if (target.origin !== window.location.origin || !['http:', 'https:'].includes(target.protocol)) throw new Error('Hono island form: actions must target the current origin.');
+    controller.current = new AbortController();
+    const response = await fetch(target, { method: method.toUpperCase(), headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: controller.current.signal });
+    if (response.redirected && response.ok) { window.location.assign(response.url); return { ok: true, pageData: undefined }; }
+    if (response.ok) { window.location.reload(); return { ok: true, pageData: undefined }; }
+    let body: unknown;
+    try { body = response.headers.get('content-type')?.includes('application/json') ? await response.json() : await response.text(); } catch { body = null; }
+    return { ok: false, error: new VoidActionError({ body, status: response.status, statusText: response.statusText, url: target.href }) };
+  }, () => controller.current?.abort());
+}
+
+type FormTransport = (method: FormMethod, url: string, data: Fields) => Promise<ActionResult>;
+function useFormModel<T extends Fields>(initial: T, initialErrors: Record<string, string>, send: FormTransport, abort: () => void | Promise<unknown>, bound?: string): HonoForm<T> {
+  const defaults = useRef({ ...initial });
+  const current = useRef({ ...defaults.current });
+  const [data, updateData] = useState(current.current);
   const [errors, setErrors] = useState(initialErrors);
   const [pending, setPending] = useState(false);
   const [wasSuccessful, setSuccessful] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
+  const [recentlySuccessful, setRecent] = useState(false);
+  const [error, setError] = useState<VoidActionError | null>(null);
   const active = useRef(false);
   const generation = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => () => { ++generation.current; active.current = false; clearTimeout(timer.current); }, []);
 
-  const setData: typeof updateData = (next) => {
-    updateData(next);
-    setSuccessful(false);
-    setErrors({});
-    setError(null);
+  const setData: SetData<T> = (next: T | ((current: T) => T) | string, value?: unknown) => {
+    current.current = typeof next === 'string' ? { ...current.current, [next]: value } as T : typeof next === 'function' ? next(current.current) : { ...next };
+    updateData(current.current); setSuccessful(false); setErrors({}); setError(null); setRecent(false); clearTimeout(timer.current);
   };
-
-  async function submit(method: FormMethod, url: string) {
+  async function submit(method: FormMethod, target?: string | FormData) {
+    const url = typeof target === 'string' ? target : bound;
+    if (!url) throw new Error('Hono Form: supply an action URL to useForm or submit.');
     if (active.current) return;
-    active.current = true;
-    const id = ++generation.current;
-    setPending(true);
-    setSuccessful(false);
-    setError(null);
-    setErrors({});
+    active.current = true; const id = ++generation.current;
+    setPending(true); setSuccessful(false); setRecent(false); clearTimeout(timer.current); setError(null); setErrors({});
+    const submitted = { ...current.current };
     try {
-      const result = await submitAction(router, url, { method: method.toUpperCase(), data, preserveScroll: true });
+      const result = await send(method, url, submitted);
       if (id !== generation.current) return;
-      if (result.ok) setSuccessful(true);
-      else { setError(result.error); setErrors(fieldErrors(result.error)); }
+      if (result.ok) {
+        if (bound) defaults.current = submitted;
+        setSuccessful(true); setRecent(true);
+        timer.current = setTimeout(() => { if (id === generation.current) setRecent(false); }, 2000);
+      } else { setError(result.error); setErrors(fieldErrors(result.error)); }
     } catch (failure) {
-      if (id === generation.current && !isAbortError(failure)) {
-        setError(failure instanceof Error ? failure : new Error(String(failure)));
-      }
+      if (id === generation.current && !isAbortError(failure)) setError(toFormError(failure, url));
     } finally {
       if (id === generation.current) { active.current = false; setPending(false); }
     }
   }
-
   function cancel() {
     if (!active.current) return;
-    const id = ++generation.current;
-    active.current = false;
-    setPending(false);
-    setSuccessful(false);
-    void router.refresh().catch((failure: unknown) => {
-      if (id === generation.current) setError(failure instanceof Error ? failure : new Error(String(failure)));
+    const id = ++generation.current; active.current = false; setPending(false); setSuccessful(false); setRecent(false); clearTimeout(timer.current);
+    void Promise.resolve(abort()).catch((failure: unknown) => {
+      if (id === generation.current) setError(toFormError(failure, bound ?? 'island'));
     });
   }
-
   return {
-    data, setData, errors, pending, wasSuccessful, error, submit, cancel,
-    reset() { setData(initialData); },
-    post: (url: string) => submit('post', url),
-    put: (url: string) => submit('put', url),
-    patch: (url: string) => submit('patch', url),
-    delete: (url: string) => submit('delete', url),
+    data, setData, errors, pending, wasSuccessful, recentlySuccessful, error, submit, cancel,
+    hasChanges: Object.keys({ ...defaults.current, ...data }).some((key) => !isEqualFormValue(defaults.current[key], data[key])),
+    reset(...fields: Array<string | MouseEvent>) { const keys = fields.filter((field): field is string => typeof field === 'string'); setData(keys.length ? { ...current.current, ...Object.fromEntries(keys.map((key) => [key, defaults.current[key]])) } as T : { ...defaults.current }); },
+    clearErrors(...fields) { setErrors((previous) => fields.length ? Object.fromEntries(Object.entries(previous).filter(([field]) => !fields.includes(field))) : {}); },
+    clearError() { setError(null); },
+    post: (target) => submit('post', target), put: (target) => submit('put', target), patch: (target) => submit('patch', target), delete: (target) => submit('delete', target),
   };
 }

package/src/runtime/markdown.ts

@@ -0,0 +1,7 @@
+import { createContext, useContext } from 'hono/jsx';
+export type MarkdownHeading = { depth: number; slug: string; text: string };
+export type MarkdownContextValue = { frontmatter: Record<string, unknown>; headings: MarkdownHeading[]; props: Record<string, unknown> };
+export const MarkdownContext = createContext<MarkdownContextValue>({ frontmatter: {}, headings: [], props: {} });
+export function useFrontmatter<T = Record<string, unknown>>(): T { return useContext(MarkdownContext).frontmatter as T; }
+export function useMarkdownHeadings(): MarkdownHeading[] { return useContext(MarkdownContext).headings; }
+export function useMarkdownProps<T = Record<string, unknown>>(): T { return useContext(MarkdownContext).props as T; }

package/src/runtime/navigation.ts

@@ -0,0 +1,72 @@
+import { createPageNavigationEngine, createRouterFacade, idleNavigationState, isAbortError, type PageNavigationResource, type VoidRouter, type VoidRouterConfig, type NavigationMethod } from 'void/pages-client';
+
+/** DOM updates still complete when a native animation is skipped or replaced. */
+export async function applyWithTransition(enabled: boolean, update: () => Promise<void>) {
+  if (!enabled || !document.startViewTransition) return update();
+  const transition = document.startViewTransition(update);
+  // ready rejects for expected animation skips; updateCallbackDone separately
+  // propagates rendering failures. Never patch the browser's native method.
+  void transition.ready.catch(() => {});
+  void transition.finished?.catch(() => {});
+  await transition.updateCallbackDone;
+}
+
+/** Hono render integration over Void's public navigation engine and facade. */
+export async function createHonoRouter(config: VoidRouterConfig) {
+  const engine = await createPageNavigationEngine(config);
+  const currentUrl = () => window.location.pathname + window.location.search + window.location.hash;
+  const toUrl = (value: string | URL) => new URL(value, window.location.href);
+  const normalize = (value: string | URL) => {
+    const url = toUrl(value);
+    // Preserve foreign origins and schemes for the shared engine's guards.
+    return url.origin === window.location.origin && ['http:', 'https:'].includes(url.protocol)
+      ? url.pathname + url.search + url.hash : url.href;
+  };
+  let routeUrl = currentUrl();
+  let routeParams = engine.initialPageData.params ?? {};
+  let active: number | null = null;
+  const setRoute = (url: string, params = routeParams) => { routeUrl = url; routeParams = params; config.onRouteChange?.(url); };
+  const assertCurrent = (resource: PageNavigationResource) => {
+    if (active !== resource.id) throw new DOMException('Hono Pages: stale navigation callback discarded.', 'AbortError');
+  };
+  async function apply(resource: PageNavigationResource) {
+    active = resource.id;
+    const previousParams = routeParams;
+    config.onNavigationChange?.({ state: resource.method === 'GET' ? 'loading' : 'submitting', location: toUrl(resource.fetchUrl + resource.hash), method: resource.method.toUpperCase() as NavigationMethod });
+    try {
+      const result = await resource.shell;
+      if (!result) return;
+      assertCurrent(resource);
+      setRoute(result.pageData.url || resource.fetchUrl + resource.hash, result.pageData.params ?? {});
+      await applyWithTransition(resource.options.viewTransition ?? config.viewTransitions, async () => {
+        assertCurrent(resource);
+        await config.adapter.applyUpdate(result.pageData, result.component, result.layouts, { preserveState: resource.options.preserveState ?? resource.method !== 'GET' });
+      });
+      assertCurrent(resource);
+      await resource.commit();
+      if (active === resource.id) setRoute(currentUrl(), result.pageData.params ?? {});
+      return result.pageData;
+    } catch (error) {
+      if (active === resource.id) routeParams = previousParams;
+      if (resource.method === 'GET' && !resource.options._resolveOnShell && isAbortError(error)) return;
+      throw error;
+    } finally {
+      if (active === resource.id) { active = null; setRoute(currentUrl()); config.onNavigationChange?.(idleNavigationState()); }
+    }
+  }
+  const raw: VoidRouter = {
+    _hoverDelay: engine._hoverDelay,
+    get url() { return toUrl(routeUrl); },
+    get path() { return this.url.pathname; },
+    get query() { return this.url.searchParams; },
+    get params() { return routeParams; },
+    visit(url, options = {}) { return apply(engine.prepareVisit(normalize(url), options)); },
+    refresh(options = {}) { return raw.visit(window.location.pathname + window.location.search, { preserveState: true, preserveScroll: true, ...options }); },
+    prefetch(url, options = {}) { return engine.prefetch(normalize(url), options); },
+    flush(url, method = 'GET') { engine.flush(normalize(url), method); },
+    flushAll() { engine.flushAll(); },
+  };
+  const router = createRouterFacade(raw, () => routeUrl, () => routeParams);
+  engine.setPopStateHandler((url, options) => { void router.visit(url, options).catch(error => window.dispatchEvent(new CustomEvent('hono-pages:navigation-error', { detail: error }))); });
+  return { router, initialPageData: engine.initialPageData, initialComponent: engine.initialComponent, initialLayouts: engine.initialLayouts, start: engine.start, commitInitialRender: engine.commitInitialRender };
+}

package/src/runtime/pages.tsx

@@ -1,9 +1,15 @@
-import { createContext, useContext, type JSX } from 'hono/jsx';
-import type { VoidRouter } from 'void/pages-client';
+import { createContext, useContext, useEffect, useRef, type JSX } from 'hono/jsx';
+import { createActionClient, mergeDataIntoHref, type NavigationState, type NavigationMethod, type VoidRouter } from 'void/pages-client';
+import type { CacheForInput } from 'void/pages-prefetch';
 import type { PageObject } from 'void/pages-protocol';
 export type { DeferredState as Deferred } from 'void';
 
+const actionClient = createActionClient();
+export const action = actionClient.action;
+export const setActionRouter = actionClient.setActionRouter;
+
 export const RouterContext = createContext<VoidRouter | null>(null);
+export const NavigationContext = createContext<NavigationState | null>(null);
 export const PageContext = createContext<PageObject | null>(null);
 
 function usePage() {
@@ -12,6 +18,12 @@ function usePage() {
   return page;
 }
 
+export function useNavigation(): NavigationState {
+  const navigation = useContext(NavigationContext);
+  if (!navigation) throw new Error('Hono Pages: useNavigation requires a page provider.');
+  return navigation;
+}
+
 export function useShared() { return usePage().shared; }
 export function useParams() { return usePage().params; }
 export function useErrors() { return usePage().errors ?? {}; }
@@ -22,24 +34,74 @@ export function useRouter(): VoidRouter {
   return router;
 }
 
-type LinkProps = Omit<JSX.IntrinsicElements['a'], 'href' | 'onClick'> & {
+export type PrefetchStrategy = 'hover' | 'click' | 'mount' | 'visible';
+export type LinkProps = Omit<JSX.IntrinsicElements['a'], 'href' | 'onClick'> & {
   href: string;
+  method?: NavigationMethod | Lowercase<NavigationMethod>;
+  data?: Record<string, unknown>;
+  preserveScroll?: boolean;
+  preserveState?: boolean;
   reloadDocument?: boolean;
   replace?: boolean;
+  viewTransition?: boolean;
+  prefetch?: boolean | PrefetchStrategy | ReadonlyArray<PrefetchStrategy>;
+  cacheFor?: CacheForInput;
+  onNavigate?: (event: { preventDefault(): void }) => void;
   onClick?: (event: MouseEvent) => void;
 };
 
-export function Link({ href, reloadDocument, replace, onClick, ...attributes }: LinkProps) {
+export function Link({ href, method = 'GET', data, preserveScroll, preserveState, reloadDocument, replace, viewTransition,
+  prefetch = false, cacheFor, onNavigate, onClick, onMouseEnter, onMouseLeave, onFocus, onMouseDown, onTouchStart,
+  ...attributes }: LinkProps) {
   const router = useRouter();
-  return <a {...attributes} href={href} onClick={(event: MouseEvent) => {
-    onClick?.(event);
-    if (event.defaultPrevented || reloadDocument || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
-    if (attributes.download !== undefined || (attributes.target && attributes.target !== '_self') || attributes.rel?.split(/\s+/).includes('external')) return;
-    const url = new URL(href, window.location.href);
-    if (url.origin !== window.location.origin || !['http:', 'https:'].includes(url.protocol)) return;
-    event.preventDefault();
-    void router.visit(url, { replace }).catch((error: unknown) => {
-      window.dispatchEvent(new CustomEvent('hono-pages:navigation-error', { detail: error }));
-    });
-  }} />;
+  const element = useRef<HTMLAnchorElement | HTMLButtonElement | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const normalized = method.toUpperCase();
+  const get = normalized === 'GET';
+  if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(normalized)) throw new Error('Hono Link: unsupported method.');
+  if (!get && (prefetch !== false || reloadDocument)) throw new Error('Hono Link: prefetch and reloadDocument only support GET links.');
+  const destination = get ? mergeDataIntoHref(href, data) : href;
+  const strategies = reloadDocument || prefetch === false ? [] : prefetch === true ? ['hover'] : typeof prefetch === 'string' ? [prefetch] : prefetch;
+  if (strategies.some((strategy) => !['hover', 'click', 'mount', 'visible'].includes(strategy))) throw new Error('Hono Link: unsupported prefetch strategy.');
+  const clear = () => { clearTimeout(timer.current); timer.current = undefined; };
+  const canHandle = () => {
+    const url = new URL(destination, window.location.href);
+    return !reloadDocument && attributes.download === undefined && (!attributes.target || attributes.target === '_self') &&
+      !attributes.rel?.split(/\s+/).includes('external') && url.origin === window.location.origin && ['http:', 'https:'].includes(url.protocol);
+  };
+  const report = (error: unknown) => window.dispatchEvent(new CustomEvent('hono-pages:navigation-error', { detail: error }));
+  const fetchAhead = () => {
+    if (canHandle()) void router.prefetch(destination, { cacheFor }).catch(report);
+  };
+  useEffect(() => {
+    if (strategies.includes('mount')) fetchAhead();
+    let observer: IntersectionObserver | undefined;
+    if (strategies.includes('visible') && element.current) {
+      observer = new IntersectionObserver((entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) { observer?.disconnect(); fetchAhead(); }
+      });
+      observer.observe(element.current);
+    }
+    return () => { clear(); observer?.disconnect(); };
+  }, [destination, prefetch, cacheFor, reloadDocument, router]);
+  const events = {
+    onClick(event: MouseEvent) {
+      onClick?.(event);
+      if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || !canHandle()) return;
+      let cancelled = false;
+      onNavigate?.({ preventDefault() { cancelled = true; } });
+      event.preventDefault();
+      if (!cancelled) void router.visit(new URL(destination, window.location.href), { method: normalized, data: get ? undefined : data, preserveScroll, preserveState, replace, viewTransition }).catch(report);
+    },
+    onMouseEnter(event: MouseEvent) {
+      onMouseEnter?.(event); clear();
+      if (!event.defaultPrevented && strategies.includes('hover')) timer.current = setTimeout(fetchAhead, router._hoverDelay);
+    },
+    onMouseLeave(event: MouseEvent) { onMouseLeave?.(event); clear(); },
+    onFocus(event: FocusEvent) { onFocus?.(event); if (!event.defaultPrevented && strategies.includes('hover')) fetchAhead(); },
+    onMouseDown(event: MouseEvent) { onMouseDown?.(event); if (!event.defaultPrevented && strategies.includes('click')) fetchAhead(); },
+    onTouchStart(event: TouchEvent) { onTouchStart?.(event); if (!event.defaultPrevented && strategies.includes('click')) fetchAhead(); },
+  };
+  if (get) return <a {...attributes} {...events} ref={element} href={destination} />;
+  return <button {...attributes} {...events} ref={element} type="button" />;
 }