@netrojs/vono 0.0.1

package/client.ts

@@ -0,0 +1,309 @@
+// ─────────────────────────────────────────────────────────────────────────────
+//  Vono · client.ts
+//  Vue 3 SSR hydration · Vue Router SPA · reactive page data · SEO sync
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {
+  createSSRApp,
+  defineAsyncComponent,
+  defineComponent,
+  h,
+  inject,
+  reactive,
+  readonly,
+  type Component,
+  type InjectionKey,
+} from 'vue'
+import {
+  createRouter,
+  createWebHistory,
+  RouterView,
+} from 'vue-router'
+import {
+  isAsyncLoader,
+  resolveRoutes,
+  toVueRouterPath,
+  compilePath,
+  matchPath,
+  SPA_HEADER,
+  STATE_KEY,
+  PARAMS_KEY,
+  SEO_KEY,
+  DATA_KEY,
+  type AppConfig,
+  type LayoutDef,
+  type SEOMeta,
+  type ClientMiddleware,
+} from './core'
+
+// ── SEO ───────────────────────────────────────────────────────────────────────
+
+function setMeta(selector: string, attr: string, val?: string): void {
+  if (!val) { document.querySelector(selector)?.remove(); return }
+  let el = document.querySelector<HTMLMetaElement>(selector)
+  if (!el) {
+    el = document.createElement('meta')
+    // Destructuring with defaults avoids string|undefined from noUncheckedIndexedAccess
+    const [, attrName = '', attrVal = ''] = /\[([^=]+)="([^"]+)"\]/.exec(selector) ?? []
+    if (attrName) el.setAttribute(attrName, attrVal)
+    document.head.appendChild(el)
+  }
+  el.setAttribute(attr, val)
+}
+
+export function syncSEO(seo: SEOMeta): void {
+  if (seo.title) document.title = seo.title
+  setMeta('[name="description"]',        'content', seo.description)
+  setMeta('[name="keywords"]',           'content', seo.keywords)
+  setMeta('[name="robots"]',             'content', seo.robots)
+  setMeta('[name="theme-color"]',        'content', seo.themeColor)
+  setMeta('[property="og:title"]',       'content', seo.ogTitle)
+  setMeta('[property="og:description"]', 'content', seo.ogDescription)
+  setMeta('[property="og:image"]',       'content', seo.ogImage)
+  setMeta('[property="og:url"]',         'content', seo.ogUrl)
+  setMeta('[property="og:type"]',        'content', seo.ogType)
+  setMeta('[name="twitter:card"]',       'content', seo.twitterCard)
+  setMeta('[name="twitter:title"]',      'content', seo.twitterTitle)
+  setMeta('[name="twitter:description"]','content', seo.twitterDescription)
+  setMeta('[name="twitter:image"]',      'content', seo.twitterImage)
+
+  let link = document.querySelector<HTMLLinkElement>('link[rel="canonical"]')
+  if (seo.canonical) {
+    if (!link) {
+      link = document.createElement('link')
+      link.rel = 'canonical'
+      document.head.appendChild(link)
+    }
+    link.href = seo.canonical
+  } else {
+    link?.remove()
+  }
+}
+
+// ── SPA data fetch + prefetch cache ──────────────────────────────────────────
+
+interface SpaPayload {
+  state:  Record<string, unknown>
+  params: Record<string, string>
+  seo:    SEOMeta
+}
+
+// Module-level cache so repeated visits to the same URL don't re-fetch
+const _fetchCache = new Map<string, Promise<SpaPayload>>()
+
+function fetchSPA(href: string): Promise<SpaPayload> {
+  if (!_fetchCache.has(href)) {
+    _fetchCache.set(
+      href,
+      fetch(href, { headers: { [SPA_HEADER]: '1' } }).then(r => {
+        if (!r.ok) throw new Error(`[vono] ${r.status} ${r.statusText} — ${href}`)
+        return r.json() as Promise<SpaPayload>
+      }),
+    )
+  }
+  return _fetchCache.get(href)!
+}
+
+export function prefetch(url: string): void {
+  try {
+    const u = new URL(url, location.origin)
+    if (u.origin === location.origin) fetchSPA(u.toString())
+  } catch { /* ignore malformed URLs */ }
+}
+
+// ── Client middleware ─────────────────────────────────────────────────────────
+
+const _mw: ClientMiddleware[] = []
+
+/**
+ * Register a client-side navigation middleware.
+ * Must be called **before** `boot()`.
+ *
+ * @example
+ * useClientMiddleware(async (url, next) => {
+ *   if (!isLoggedIn() && url.startsWith('/dashboard')) {
+ *     await navigate('/login')
+ *     return
+ *   }
+ *   await next()
+ * })
+ */
+export function useClientMiddleware(mw: ClientMiddleware): void {
+  _mw.push(mw)
+}
+
+async function runMw(url: string, done: () => Promise<void>): Promise<void> {
+  const chain: ClientMiddleware[] = [
+    ..._mw,
+    async (_: string, next: () => Promise<void>) => { await done(); await next() },
+  ]
+  let i = 0
+  const run = async (): Promise<void> => {
+    const fn = chain[i++]
+    if (fn) await fn(url, run)
+  }
+  await run()
+}
+
+// ── Reactive page data ────────────────────────────────────────────────────────
+//
+// A single module-level reactive object that lives for the app's lifetime.
+// On SPA navigation it is updated in-place so page components re-render
+// reactively without being unmounted.
+//
+// The app provides it as readonly via DATA_KEY so page components cannot
+// mutate it directly.
+
+const _pageData = reactive<Record<string, unknown>>({})
+
+function updatePageData(newData: Record<string, unknown>): void {
+  // Delete keys that are no longer present in the new data
+  for (const k of Object.keys(_pageData)) {
+    if (!(k in newData)) delete _pageData[k]
+  }
+  Object.assign(_pageData, newData)
+}
+
+/**
+ * Access the current page's loader data inside any Vue component.
+ * The returned object is reactive — it updates automatically on navigation.
+ *
+ * @example
+ * const data = usePageData<{ title: string; posts: Post[] }>()
+ * // data.title is typed and reactive
+ */
+export function usePageData<T extends Record<string, unknown> = Record<string, unknown>>(): T {
+  // DATA_KEY is typed as symbol; cast to InjectionKey for strong inference
+  const data = inject(DATA_KEY as InjectionKey<T>)
+  if (data === undefined) {
+    throw new Error('[vono] usePageData() must be called inside a component setup().')
+  }
+  return data
+}
+
+// ── boot() ────────────────────────────────────────────────────────────────────
+
+export interface BootOptions extends AppConfig {
+  /** Warm fetch cache on link hover.  @default true */
+  prefetchOnHover?: boolean
+}
+
+export async function boot(options: BootOptions): Promise<void> {
+  const container = document.getElementById('vono-app')
+  if (!container) {
+    console.error('[vono] #vono-app not found — aborting hydration.')
+    return
+  }
+
+  const { pages } = resolveRoutes(options.routes, {
+    ...(options.layout !== undefined && { layout: options.layout }),
+    middleware: [],
+  })
+
+  // Read server-injected bootstrap data
+  const stateMap  = (window as any)[STATE_KEY]  as Record<string, Record<string, unknown>> ?? {}
+  const seoData   = (window as any)[SEO_KEY]    as SEOMeta                                 ?? {}
+  const pathname  = location.pathname
+
+  // Seed reactive store and sync SEO from server data (no network request)
+  updatePageData(stateMap[pathname] ?? {})
+  syncSEO(seoData)
+
+  // Build Vue Router route table
+  // Async loaders are wrapped with defineAsyncComponent for code splitting.
+  const vueRoutes = pages.map(r => {
+    const layout = r.layout !== undefined ? r.layout : options.layout
+    const comp   = r.page.component
+
+    const PageComp: Component = isAsyncLoader(comp)
+      ? defineAsyncComponent(comp)
+      : comp as Component
+
+    const routeComp: Component = layout
+      ? defineComponent({
+          name:  'VonoRoute',
+          setup: () => () => h((layout as LayoutDef).component as Component, null, {
+            default: () => h(PageComp),
+          }),
+        })
+      : PageComp
+
+    return { path: toVueRouterPath(r.fullPath), component: routeComp }
+  })
+
+  // Pre-load the current route's async chunk BEFORE hydrating to guarantee the
+  // client VDOM matches the SSR HTML (avoids hydration mismatch on first load).
+  const currentRoute = pages.find(r => matchPath(compilePath(r.fullPath), pathname) !== null)
+  if (currentRoute && isAsyncLoader(currentRoute.page.component)) {
+    await currentRoute.page.component()
+  }
+
+  // createSSRApp: tells Vue to hydrate existing DOM instead of re-rendering
+  const app = createSSRApp({ name: 'VonoApp', render: () => h(RouterView) })
+  app.provide(DATA_KEY as InjectionKey<typeof _pageData>, readonly(_pageData))
+
+  const router = createRouter({ history: createWebHistory(), routes: vueRoutes })
+
+  // Track whether this is the initial (server-hydrated) navigation.
+  // We skip data fetching for the first navigation — the server already
+  // injected the data into window.__VONO_STATE__.
+  let isInitialNav = true
+
+  router.beforeEach(async (to, _from, next) => {
+    if (isInitialNav) {
+      isInitialNav = false
+      return next()
+    }
+
+    const href = new URL(to.fullPath, location.origin).toString()
+
+    try {
+      await runMw(to.fullPath, async () => {
+        const payload = await fetchSPA(href)
+        updatePageData(payload.state ?? {})
+        syncSEO(payload.seo ?? {})
+        window.scrollTo(0, 0)
+      })
+      next()
+    } catch (err) {
+      console.error('[vono] Navigation error:', err)
+      // Hard navigate as fallback — the server will handle the request
+      location.href = to.fullPath
+    }
+  })
+
+  app.use(router)
+  await router.isReady()
+  app.mount(container)
+
+  // Hover prefetch — warm the fetch cache before the user clicks
+  if (options.prefetchOnHover !== false) {
+    document.addEventListener('mouseover', (e) => {
+      const a = (e as MouseEvent).composedPath()
+        .find((el): el is HTMLAnchorElement => el instanceof HTMLAnchorElement)
+      if (a?.href) prefetch(a.href)
+    })
+  }
+}
+
+// ── Re-exports ────────────────────────────────────────────────────────────────
+
+export {
+  definePage, defineGroup, defineLayout, defineApiRoute, isAsyncLoader,
+  resolveRoutes, compilePath, matchPath, toVueRouterPath,
+  SPA_HEADER, STATE_KEY, PARAMS_KEY, SEO_KEY, DATA_KEY,
+} from './core'
+
+export type {
+  AppConfig, PageDef, GroupDef, LayoutDef, ApiRouteDef, Route,
+  SEOMeta, HonoMiddleware, LoaderCtx, ResolvedRoute, CompiledPath,
+  ClientMiddleware, AsyncLoader, InferPageData,
+} from './core'
+
+// Vue Router composables re-exported for convenience
+export {
+  useRoute,
+  useRouter,
+  RouterLink,
+  RouterView,
+} from 'vue-router'

package/core.ts

@@ -0,0 +1,151 @@
+// ─────────────────────────────────────────────────────────────────────────────
+//  Vono · core.ts
+//  Route builders · path matching · route resolution · async-loader detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+import type { Component } from 'vue'
+import type {
+  PageDef, GroupDef, LayoutDef, ApiRouteDef, Route,
+  ResolvedRoute, CompiledPath, HonoMiddleware, AsyncLoader, LoaderCtx,
+} from './types'
+
+// ── Async-loader detection ────────────────────────────────────────────────────
+//
+// A Vue component (SFC compiled by vite-plugin-vue) always carries one or more
+// of these brand properties.  A plain () => import('./Page.vue') factory has
+// none of them, so checking for their absence is sufficient for real-world use.
+
+const VUE_BRANDS = ['__name', '__file', '__vccOpts', 'setup', 'render', 'data', 'components'] as const
+
+/**
+ * Returns true when `c` is an async factory function (i.e. `() => import(...)`)
+ * rather than a resolved Vue component object.
+ *
+ * Used by both server.ts (to resolve the import before SSR) and client.ts
+ * (to wrap with defineAsyncComponent for lazy hydration).
+ */
+export function isAsyncLoader(c: unknown): c is AsyncLoader {
+  if (typeof c !== 'function') return false
+  const f = c as unknown as Record<string, unknown>
+  for (const brand of VUE_BRANDS) {
+    if (brand in f) return false
+  }
+  return true
+}
+
+// ── Builder functions ─────────────────────────────────────────────────────────
+
+/**
+ * Define a page route with full type inference.
+ *
+ * TypeScript infers `TData` automatically from the `loader` return type, so
+ * you rarely need to supply the generic manually.  Export the page constant and
+ * use `InferPageData<typeof myPage>` in your component for a single source of
+ * truth.
+ *
+ * @example
+ * export const postPage = definePage({
+ *   path:      '/post/[slug]',
+ *   loader:    async (c) => fetchPost(c.req.param('slug')),
+ *   component: () => import('./pages/post.vue'),
+ * })
+ * export type PostData = InferPageData<typeof postPage>
+ */
+export function definePage<TData extends object = Record<string, never>>(
+  def: Omit<PageDef<TData>, '__type'>,
+): PageDef<TData> {
+  return { __type: 'page', ...def }
+}
+
+export function defineGroup(def: Omit<GroupDef, '__type'>): GroupDef {
+  return { __type: 'group', ...def }
+}
+
+/** Wrap a Vue layout component (must render <slot />) as a Vono layout. */
+export function defineLayout(component: Component): LayoutDef {
+  return { __type: 'layout', component }
+}
+
+export function defineApiRoute(
+  path:     string,
+  register: ApiRouteDef['register'],
+): ApiRouteDef {
+  return { __type: 'api', path, register }
+}
+
+// ── Path matching (Vono [param] syntax → RegExp) ────────────────────────────
+
+export function compilePath(path: string): CompiledPath {
+  const keys: string[] = []
+  const src = path
+    .replace(/\[\.\.\.([^\]]+)\]/g, (_, k: string) => { keys.push(k); return '(.*)' })
+    .replace(/\[([^\]]+)\]/g,       (_, k: string) => { keys.push(k); return '([^/]+)' })
+    .replace(/\*/g, '(.*)')
+  return { re: new RegExp(`^${src}$`), keys }
+}
+
+export function matchPath(
+  cp: CompiledPath,
+  pathname: string,
+): Record<string, string> | null {
+  const m = pathname.match(cp.re)
+  if (!m) return null
+  const params: Record<string, string> = {}
+  cp.keys.forEach((k, i) => { params[k] = decodeURIComponent(m[i + 1] ?? '') })
+  return params
+}
+
+/**
+ * Convert Vono `[param]` syntax to Vue Router `:param` syntax.
+ *
+ * `/posts/[slug]`    → `/posts/:slug`
+ * `/files/[...path]` → `/files/:path(.*)*`
+ */
+export function toVueRouterPath(vonoPath: string): string {
+  return vonoPath
+    .replace(/\[\.\.\.([^\]]+)\]/g, ':$1(.*)*')
+    .replace(/\[([^\]]+)\]/g,       ':$1')
+}
+
+// ── Route resolution ──────────────────────────────────────────────────────────
+
+export function resolveRoutes(
+  routes:  Route[],
+  options: {
+    prefix?:     string
+    middleware?: HonoMiddleware[]
+    layout?:     LayoutDef | false
+  } = {},
+): { pages: ResolvedRoute[]; apis: ApiRouteDef[] } {
+  const pages: ResolvedRoute[] = []
+  const apis:  ApiRouteDef[]   = []
+
+  for (const route of routes) {
+    if (route.__type === 'api') {
+      apis.push({ ...route, path: (options.prefix ?? '') + route.path })
+    } else if (route.__type === 'group') {
+      const prefix = (options.prefix ?? '') + route.prefix
+      const mw     = [...(options.middleware ?? []), ...(route.middleware ?? [])]
+      const layout = route.layout !== undefined ? route.layout : options.layout
+      const sub    = resolveRoutes(route.routes, {
+        prefix,
+        middleware: mw,
+        ...(layout !== undefined && { layout }),
+      })
+      pages.push(...sub.pages)
+      apis.push(...sub.apis)
+    } else {
+      pages.push({
+        fullPath:   (options.prefix ?? '') + route.path,
+        page:       route,
+        layout:     route.layout !== undefined ? route.layout : options.layout,
+        middleware: [...(options.middleware ?? []), ...(route.middleware ?? [])],
+      })
+    }
+  }
+
+  return { pages, apis }
+}
+
+// Re-export all types so `import from '@netrojs/vono'` (root export) works
+export * from './types'

package/dist/client.d.ts

@@ -0,0 +1,199 @@
+import { Component } from 'vue';
+import { Hono, MiddlewareHandler, Context } from 'hono';
+export { RouterLink, RouterView, useRoute, useRouter } from 'vue-router';
+
+type HonoMiddleware = MiddlewareHandler;
+type LoaderCtx = Context;
+interface SEOMeta {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    author?: string;
+    robots?: string;
+    canonical?: string;
+    themeColor?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogImageAlt?: string;
+    ogUrl?: string;
+    ogType?: string;
+    ogSiteName?: string;
+    twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    twitterSite?: string;
+    twitterTitle?: string;
+    twitterDescription?: string;
+    twitterImage?: string;
+    /** Structured data injected as <script type="application/ld+json">. */
+    jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+}
+type AsyncLoader = () => Promise<{
+    default: Component;
+} | Component>;
+interface PageDef<TData extends object = Record<string, never>> {
+    readonly __type: 'page';
+    path: string;
+    middleware?: HonoMiddleware[];
+    loader?: (c: LoaderCtx) => TData | Promise<TData>;
+    seo?: SEOMeta | ((data: TData, params: Record<string, string>) => SEOMeta);
+    /** Override or disable the app-level layout for this route. */
+    layout?: LayoutDef | false;
+    /**
+     * The Vue component to render for this route.
+     * Use () => import('./Page.vue') for automatic code splitting.
+     */
+    component: Component | AsyncLoader;
+}
+interface GroupDef {
+    readonly __type: 'group';
+    prefix: string;
+    layout?: LayoutDef | false;
+    middleware?: HonoMiddleware[];
+    routes: Route[];
+}
+interface LayoutDef {
+    readonly __type: 'layout';
+    /** Vue layout component — must contain <slot /> for page content. */
+    component: Component;
+}
+interface ApiRouteDef {
+    readonly __type: 'api';
+    path: string;
+    register: (app: Hono, globalMiddleware: HonoMiddleware[]) => void;
+}
+type Route = PageDef<any> | GroupDef | ApiRouteDef;
+interface AppConfig {
+    layout?: LayoutDef;
+    seo?: SEOMeta;
+    middleware?: HonoMiddleware[];
+    routes: Route[];
+    notFound?: Component;
+    htmlAttrs?: Record<string, string>;
+    /** Extra HTML injected into <head> (e.g. font preloads). */
+    head?: string;
+}
+interface ResolvedRoute {
+    fullPath: string;
+    page: PageDef<any>;
+    layout: LayoutDef | false | undefined;
+    middleware: HonoMiddleware[];
+}
+interface CompiledPath {
+    re: RegExp;
+    keys: string[];
+}
+type ClientMiddleware = (url: string, next: () => Promise<void>) => Promise<void>;
+/** Custom request header that identifies an SPA navigation (JSON payload). */
+declare const SPA_HEADER = "x-vono-spa";
+/** window key for SSR-injected per-page loader data. */
+declare const STATE_KEY = "__VONO_STATE__";
+/** window key for SSR-injected URL params. */
+declare const PARAMS_KEY = "__VONO_PARAMS__";
+/** window key for SSR-injected SEO meta. */
+declare const SEO_KEY = "__VONO_SEO__";
+/**
+ * Vue provide/inject key for the reactive page-data object.
+ * Symbol.for() ensures the same reference across module instances (SSR safe).
+ */
+declare const DATA_KEY: unique symbol;
+/**
+ * Extract the loader data type from a `PageDef` returned by `definePage()`.
+ *
+ * This enables you to define the data type exactly once — inferred from the
+ * loader — and import it into page components for `usePageData<T>()`.
+ *
+ * @example
+ * // app/routes.ts
+ * export const homePage = definePage({
+ *   path: '/',
+ *   loader: async () => ({ title: 'Hello', count: 42 }),
+ *   component: () => import('./pages/home.vue'),
+ * })
+ * export type HomeData = InferPageData<typeof homePage>
+ * // HomeData = { title: string; count: number }
+ *
+ * // app/pages/home.vue
+ * import type { HomeData } from '../routes'
+ * const data = usePageData<HomeData>()
+ */
+type InferPageData<T> = T extends PageDef<infer D> ? D : never;
+
+/**
+ * Returns true when `c` is an async factory function (i.e. `() => import(...)`)
+ * rather than a resolved Vue component object.
+ *
+ * Used by both server.ts (to resolve the import before SSR) and client.ts
+ * (to wrap with defineAsyncComponent for lazy hydration).
+ */
+declare function isAsyncLoader(c: unknown): c is AsyncLoader;
+/**
+ * Define a page route with full type inference.
+ *
+ * TypeScript infers `TData` automatically from the `loader` return type, so
+ * you rarely need to supply the generic manually.  Export the page constant and
+ * use `InferPageData<typeof myPage>` in your component for a single source of
+ * truth.
+ *
+ * @example
+ * export const postPage = definePage({
+ *   path:      '/post/[slug]',
+ *   loader:    async (c) => fetchPost(c.req.param('slug')),
+ *   component: () => import('./pages/post.vue'),
+ * })
+ * export type PostData = InferPageData<typeof postPage>
+ */
+declare function definePage<TData extends object = Record<string, never>>(def: Omit<PageDef<TData>, '__type'>): PageDef<TData>;
+declare function defineGroup(def: Omit<GroupDef, '__type'>): GroupDef;
+/** Wrap a Vue layout component (must render <slot />) as a Vono layout. */
+declare function defineLayout(component: Component): LayoutDef;
+declare function defineApiRoute(path: string, register: ApiRouteDef['register']): ApiRouteDef;
+declare function compilePath(path: string): CompiledPath;
+declare function matchPath(cp: CompiledPath, pathname: string): Record<string, string> | null;
+/**
+ * Convert Vono `[param]` syntax to Vue Router `:param` syntax.
+ *
+ * `/posts/[slug]`    → `/posts/:slug`
+ * `/files/[...path]` → `/files/:path(.*)*`
+ */
+declare function toVueRouterPath(vonoPath: string): string;
+declare function resolveRoutes(routes: Route[], options?: {
+    prefix?: string;
+    middleware?: HonoMiddleware[];
+    layout?: LayoutDef | false;
+}): {
+    pages: ResolvedRoute[];
+    apis: ApiRouteDef[];
+};
+
+declare function syncSEO(seo: SEOMeta): void;
+declare function prefetch(url: string): void;
+/**
+ * Register a client-side navigation middleware.
+ * Must be called **before** `boot()`.
+ *
+ * @example
+ * useClientMiddleware(async (url, next) => {
+ *   if (!isLoggedIn() && url.startsWith('/dashboard')) {
+ *     await navigate('/login')
+ *     return
+ *   }
+ *   await next()
+ * })
+ */
+declare function useClientMiddleware(mw: ClientMiddleware): void;
+/**
+ * Access the current page's loader data inside any Vue component.
+ * The returned object is reactive — it updates automatically on navigation.
+ *
+ * @example
+ * const data = usePageData<{ title: string; posts: Post[] }>()
+ * // data.title is typed and reactive
+ */
+declare function usePageData<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+interface BootOptions extends AppConfig {
+    /** Warm fetch cache on link hover.  @default true */
+    prefetchOnHover?: boolean;
+}
+declare function boot(options: BootOptions): Promise<void>;
+
+export { type ApiRouteDef, type AppConfig, type AsyncLoader, type BootOptions, type ClientMiddleware, type CompiledPath, DATA_KEY, type GroupDef, type HonoMiddleware, type InferPageData, type LayoutDef, type LoaderCtx, PARAMS_KEY, type PageDef, type ResolvedRoute, type Route, type SEOMeta, SEO_KEY, SPA_HEADER, STATE_KEY, boot, compilePath, defineApiRoute, defineGroup, defineLayout, definePage, isAsyncLoader, matchPath, prefetch, resolveRoutes, syncSEO, toVueRouterPath, useClientMiddleware, usePageData };