@jasonshimmy/vite-plugin-cer-app 0.23.1 → 0.24.0

package/src/runtime/app-template.ts

@@ -1,380 +0,0 @@
-/**
- * Generates the `.cer/app.ts` framework client entry point.
- *
- * Always written to `.cer/app.ts` on every dev/build so consumers
- * automatically receive the latest bootstrap code on plugin update.
- * This file is gitignored and should never be edited directly.
- *
- * @param customColors - Project-specific color families to register in the JIT
- *   CSS engine at runtime. Serialized as a JSON literal in the generated source.
- */
-export function generateAppEntryTemplate(
-  customColors?: Record<string, Record<string, string>>,
-): string {
-  const enableJITCSSCall =
-    customColors && Object.keys(customColors).length > 0
-      ? `enableJITCSS({ customColors: ${JSON.stringify(customColors)} })`
-      : `enableJITCSS()`
-
-  return `// AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app — do not edit.
-// Regenerated automatically on every dev server start and build.
-
-import '@jasonshimmy/custom-elements-runtime/css'
-import 'virtual:cer-jit-css'
-import 'virtual:cer-content-components'
-import routes from 'virtual:cer-routes'
-import layouts from 'virtual:cer-layouts'
-import plugins from 'virtual:cer-plugins'
-import { hasLoading, loadingTag } from 'virtual:cer-loading'
-import { hasError, errorTag } from 'virtual:cer-error'
-import { runtimeConfig } from 'virtual:cer-app-config'
-import {
-  component,
-  ref,
-  provide,
-  setDevMode,
-  useOnConnected,
-  useOnDisconnected,
-  registerBuiltinComponents,
-} from '@jasonshimmy/custom-elements-runtime'
-import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
-import { initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
-
-const _cerProcess = (globalThis).process
-const _cerNodeEnv = _cerProcess?.env?.NODE_ENV ?? _cerProcess?.env?.MODE
-const _cerRuntimeDev =
-  typeof _cerNodeEnv === 'string'
-    ? _cerNodeEnv !== 'production'
-    : typeof import.meta.env?.DEV === 'boolean'
-      ? import.meta.env.DEV
-      : typeof import.meta.env?.PROD === 'boolean'
-        ? !import.meta.env.PROD
-        : typeof import.meta.env?.MODE === 'string'
-          ? import.meta.env.MODE !== 'production'
-          : false
-;(globalThis).__CE_RUNTIME_DEV__ = _cerRuntimeDev
-
-registerBuiltinComponents()
-setDevMode(_cerRuntimeDev)
-${enableJITCSSCall}
-initRuntimeConfig(runtimeConfig)
-
-const router = initRouter({ routes })
-
-// Expose the router globally so useRoute() and navigateTo() can access it
-// from any composable without circular imports.
-;(globalThis).__cerRouter = router
-
-// ─── Page loader state ───────────────────────────────────────────────────────
-
-// Holds the pre-loaded page tag and loader-derived attrs for the current route.
-// Set by _loadPageForPath before every navigation so cer-layout-view can render
-// the page element directly with the correct attributes (enabling useProps()).
-let _currentPageTag = null
-let _currentPageAttrs = {}
-// The pathname this tag was loaded for — used to detect router-internal
-// redirects (e.g. middleware returning '/login') so cer-layout-view falls
-// back to <router-view> when the current route differs from what was pre-loaded.
-let _currentPagePath = null
-
-function _toLoaderAttrs(data) {
-  if (data === undefined || data === null || typeof data !== 'object') return {}
-  return Object.fromEntries(
-    Object.entries(data).filter(([, v]) => v !== null && v !== undefined && typeof v !== 'object' && typeof v !== 'function')
-  )
-}
-
-// Pre-loads the page module for \`path\`, calls its loader if present, and
-// stores the results so cer-layout-view can pass them as element attributes.
-async function _loadPageForPath(path, options = {}) {
-  try {
-    const url = new URL(path, 'http://x')
-    const query = Object.fromEntries(url.searchParams)
-    const { runLoader = true, initialData } = options ?? {}
-    const matched = router.matchRoute(url.pathname)
-    const route = matched?.route
-    if (!route?.load) {
-      _currentPageTag = null
-      _currentPageAttrs = {}
-      _currentPagePath = url.pathname
-      return
-    }
-    const mod = await route.load()
-    _currentPageTag = mod.default ?? null
-    _currentPagePath = url.pathname
-    const params = matched.params ?? {}
-    let loaderAttrs = { ...params }
-    let loaderData = initialData
-    if (typeof mod.loader === 'function' && runLoader) {
-      try {
-        const data = await mod.loader({ params, query })
-        if (data !== undefined && data !== null) {
-          loaderData = data
-          // Make loader data available via usePageData() for this navigation.
-          ;(globalThis).__CER_DATA__ = data
-        }
-      } catch (err) {
-        // Loader errors are surfaced through currentError so the error boundary
-        // (app/error.ts) can display a meaningful message — consistent with how
-        // the server-side handler behaves when a loader throws.
-        currentError.value = err instanceof Error ? err.message : String(err)
-      }
-    }
-    // For the very first hydration pass in SSR/SSG we already have the server's
-    // loader payload in globalThis.__CER_DATA__ / window.__CER_DATA__. Reuse it
-    // instead of re-running the loader on the client, then derive primitive attrs
-    // from that payload so useProps() stays consistent with usePageData().
-    loaderAttrs = { ...loaderAttrs, ..._toLoaderAttrs(loaderData) }
-    _currentPageAttrs = loaderAttrs
-  } catch {
-    _currentPageTag = null
-    _currentPageAttrs = {}
-    _currentPagePath = null
-  }
-}
-
-// ─── Navigation state ────────────────────────────────────────────────────────
-
-const isNavigating = ref(false)
-const currentError = ref(null)
-
-const resetError = () => {
-  currentError.value = null
-  void router.replace(router.getCurrent().path)
-}
-;(globalThis).resetError = resetError
-
-const _push = router.push.bind(router)
-const _replace = router.replace.bind(router)
-
-router.push = async (path) => {
-  isNavigating.value = true
-  currentError.value = null
-  try {
-    // Clear stale loader data from the previous route before loading the new one.
-    // If the new route has no loader, __CER_DATA__ stays undefined so usePageData()
-    // correctly returns null instead of leaking the previous page's data.
-    delete (globalThis).__CER_DATA__
-    await _loadPageForPath(path)
-    await _push(path)
-  } catch (err) {
-    currentError.value = err instanceof Error ? err.message : String(err)
-  } finally {
-    isNavigating.value = false
-  }
-}
-
-router.replace = async (path) => {
-  isNavigating.value = true
-  currentError.value = null
-  try {
-    // Clear stale loader data from the previous route before loading the new one.
-    delete (globalThis).__CER_DATA__
-    await _loadPageForPath(path)
-    await _replace(path)
-  } catch (err) {
-    currentError.value = err instanceof Error ? err.message : String(err)
-  } finally {
-    isNavigating.value = false
-  }
-}
-
-// ─── Plugins ─────────────────────────────────────────────────────────────────
-
-// Collect plugin-provided values so cer-layout-view can forward them into
-// the component context tree via the real provide() hook (which inject() walks).
-// Declared BEFORE component('cer-layout-view') to avoid a temporal dead zone
-// ReferenceError: customElements.define() upgrades existing DOM elements
-// synchronously, calling the render function immediately.
-const _pluginProvides = new Map()
-// Expose plugin provides globally so page components can read them synchronously
-// regardless of render order.
-;(globalThis).__cerPluginProvides = _pluginProvides
-
-// ─── <cer-layout-view> ───────────────────────────────────────────────────────
-
-// True until the initial page module has loaded and _replace has been called.
-// While true, cer-layout-view renders a <slot> so the SSR/SSG pre-rendered
-// light-DOM content stays visible and no FOUC occurs during the hydration gap.
-// Declared here (before component()) because customElements.define() upgrades
-// existing DOM elements synchronously, so the render function reads this ref
-// on the very first call — before _doHydrate has a chance to run.
-const _cerHydrating = ref(true)
-
-component('cer-layout-view', () => {
-  // Forward plugin-provided values into the component context so inject() in
-  // any descendant component can resolve them by walking up the DOM tree.
-  for (const [key, value] of _pluginProvides) {
-    provide(key, value)
-  }
-
-  const current = ref(router.getCurrent())
-  let unsub
-  let _sawInitialRouteState = false
-
-  useOnConnected(() => {
-    // store.subscribe() synchronously pushes the current route once on
-    // subscription. That initial callback is not a real navigation and must not
-    // tear down the SSR slot before _doHydrate has pre-loaded the page.
-    // Subsequent callbacks are real navigations (including the initial _replace
-    // in _doHydrate), so if they arrive during the hydration gap we drop the
-    // slot immediately and let the live render take over.
-    unsub = router.subscribe((s) => {
-      const _isInitialSubscribePush = !_sawInitialRouteState
-      _sawInitialRouteState = true
-      if (_isInitialSubscribePush) {
-        current.value = s
-        return
-      }
-      if (_cerHydrating.value) _cerHydrating.value = false
-      current.value = s
-    })
-  })
-  useOnDisconnected(() => { unsub?.(); unsub = undefined })
-
-  // While the initial page module is being loaded, keep the SSR/SSG
-  // pre-rendered light-DOM content visible by forwarding it through a <slot>.
-  // This prevents the intermediate blank state that occurs when the shadow DOM
-  // renders layout-default with an empty <router-view> before the page chunk
-  // has arrived. In SPA mode (no pre-rendered content) the slot is empty, which
-  // is no worse than the current router-view behaviour.
-  if (_cerHydrating.value) {
-    return { tag: 'slot', props: {}, children: [] }
-  }
-
-  const matched = router.matchRoute(current.value.path)
-  const routeMeta = matched?.route?.meta
-
-  if (currentError.value !== null) {
-    const routeErrorTag = routeMeta?.errorTag ?? null
-    const effectiveErrorTag = routeErrorTag ?? (hasError ? errorTag : null)
-    if (effectiveErrorTag) {
-      return { tag: effectiveErrorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
-    }
-    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
-  }
-
-  if (isNavigating.value && hasLoading && loadingTag) {
-    return { tag: loadingTag, props: {}, children: [] }
-  }
-
-  // Render the page component directly when a pre-loaded tag is available AND
-  // the loaded path matches the current route.  The path guard detects
-  // router-internal redirects (e.g. middleware returning '/login'): when the
-  // router redirects to a different path, _currentPagePath won't match
-  // current.value.path and we fall back to <router-view> so the correct page
-  // is rendered without stale pre-loaded state.
-  const _useDirectRender = _currentPageTag && _currentPagePath === current.value.path
-  const pageVnode = _useDirectRender
-    ? { tag: _currentPageTag, props: { attrs: _currentPageAttrs }, children: [] }
-    : { tag: 'router-view', props: {}, children: [] }
-
-  // Support nested layout chains: meta.layoutChain = ['default', 'admin']
-  // renders <layout-default><layout-admin><page/></layout-admin></layout-default>
-  const chain = routeMeta?.layoutChain
-    ? routeMeta.layoutChain
-    : [routeMeta?.layout ?? 'default']
-
-  // Build nested vnodes from innermost to outermost.
-  let vnode = pageVnode
-  for (let i = chain.length - 1; i >= 0; i--) {
-    const tag = layouts[chain[i]]
-    if (tag) vnode = { tag, props: {}, children: [vnode] }
-  }
-  return vnode
-})
-
-for (const plugin of plugins) {
-  if (plugin && typeof plugin.setup === 'function') {
-    await plugin.setup({
-      router,
-      provide: (key, value) => { _pluginProvides.set(key, value) },
-      config: {},
-    })
-  }
-}
-
-// ─── Pre-load initial route + hydration strategy ─────────────────────────────
-// Download the current page's route chunk AFTER plugins run so that
-// cer-layout-view's first render (which calls provide()) completes before
-// page components are defined and their renders are scheduled. This ensures
-// inject() in child components can find values stored by provide().
-//
-// meta.hydrate controls WHEN the initial page activates:
-//   'load'    — immediately (default)
-//   'idle'    — deferred until requestIdleCallback (browser idle)
-//   'visible' — deferred until cer-layout-view enters the viewport
-//   'none'    — never: SSR HTML stays as-is, no JS activation
-
-if (typeof window !== 'undefined') {
-  const _initMatch = router.matchRoute(window.location.pathname)
-  const _hydrateStrategy = _initMatch?.route?.meta?.hydrate ?? 'load'
-
-  if (_hydrateStrategy === 'none') {
-    // Static HTML only — leave SSR output untouched, clean up data immediately.
-    delete (globalThis).__CER_DATA__
-  } else {
-    const _doHydrate = async () => {
-      const _initPath = window.location.pathname + window.location.search + window.location.hash
-      const _hasInitialLoaderData = Object.prototype.hasOwnProperty.call(globalThis, '__CER_DATA__')
-      // Pre-load the page module and run the loader so cer-layout-view renders
-      // the page tag directly with loader attrs (enables useProps() on hydration).
-      await _loadPageForPath(
-        _initPath,
-        _hasInitialLoaderData
-          ? { runLoader: false, initialData: (globalThis).__CER_DATA__ }
-          : undefined,
-      )
-      // Only activate the initial route if the URL hasn't changed while we were
-      // loading the module asynchronously (e.g. a test or plugin navigated away
-      // before _doHydrate finished).  Calling _replace with a stale path would
-      // override any navigation that happened during the async gap.
-      const _currentPath = window.location.pathname + window.location.search + window.location.hash
-      // Drop the hydration slot cover unconditionally: the page module is loaded
-      // and cer-layout-view must switch from the <slot> to live rendering whether
-      // or not a redirect changed the path during loading.
-      _cerHydrating.value = false
-      if (_currentPath === _initPath) {
-        // Use the original (unwrapped) replace so isNavigating stays false during
-        // the initial paint — the loading component must not flash over pre-rendered content.
-        await _replace(_initPath)
-      }
-      // The client entry marks the already-rendered entry URL so generated
-      // route middleware can skip the browser router's startup replay once.
-      // Clear any leftover flag after the first hydrated route commits so later
-      // navigations always run middleware normally.
-      queueMicrotask(() => { delete (globalThis).__CER_HYDRATION_ENTRY__ })
-      // Keep the initial route's SSR data available after hydration.
-      // Browser engines do not all upgrade and re-render custom elements with
-      // identical timing, so deleting __CER_DATA__ here can cause a later
-      // hydration render to fall back to the client-only path. The next real
-      // router.push/router.replace clears __CER_DATA__ before loading the new
-      // route, so stale page data still does not leak across navigations.
-    }
-
-    if (_hydrateStrategy === 'idle') {
-      // Defer until the browser has finished higher-priority work.
-      if (typeof requestIdleCallback !== 'undefined') {
-        requestIdleCallback(() => { void _doHydrate() })
-      } else {
-        // Safari / older environments fallback.
-        setTimeout(() => { void _doHydrate() }, 1)
-      }
-    } else if (_hydrateStrategy === 'visible') {
-      // Defer until cer-layout-view (or body as fallback) enters the viewport.
-      const _el = document.querySelector('cer-layout-view') ?? document.body
-      const _io = new IntersectionObserver(([entry]) => {
-        if (entry.isIntersecting) { _io.disconnect(); void _doHydrate() }
-      })
-      _io.observe(_el)
-    } else {
-      // 'load' — hydrate immediately (default behaviour).
-      await _doHydrate()
-    }
-  }
-}
-
-export { router }
-`
-}

package/src/runtime/composables/define-middleware.ts

@@ -1,17 +0,0 @@
-import type { MiddlewareFn } from '../../types/middleware.js'
-
-/**
- * Identity helper that gives TypeScript the correct `MiddlewareFn` type
- * without any runtime cost.
- *
- * @example
- * // app/middleware/auth.ts
- * export default defineMiddleware(async (to, from) => {
- *   const isLoggedIn = checkSession()
- *   if (!isLoggedIn) return '/login'   // redirect
- *   return true                         // allow
- * })
- */
-export function defineMiddleware(fn: MiddlewareFn): MiddlewareFn {
-  return fn
-}

package/src/runtime/composables/define-server-middleware.ts

@@ -1,18 +0,0 @@
-import type { ServerMiddleware } from '../../types/middleware.js'
-
-/**
- * Identity helper that gives `ServerMiddleware` functions full TypeScript
- * types without any runtime cost. Usage:
- *
- * ```ts
- * // server/middleware/auth.ts
- * export default defineServerMiddleware(async (req, res, next) => {
- *   const session = await useSession().get()
- *   if (!session) { res.statusCode = 401; res.end('Unauthorized'); return }
- *   next()
- * })
- * ```
- */
-export function defineServerMiddleware(fn: ServerMiddleware): ServerMiddleware {
-  return fn
-}

package/src/runtime/composables/index.ts

@@ -1,27 +0,0 @@
-export { useHead, beginHeadCollection, endHeadCollection, serializeHeadTags } from './use-head.js'
-export type { HeadInput } from './use-head.js'
-export { usePageData } from './use-page-data.js'
-export { useInject } from './use-inject.js'
-export { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from './use-runtime-config.js'
-export type { RuntimeConfigResult, RuntimeConfigPublic, RuntimeConfigPrivate } from './use-runtime-config.js'
-export { defineMiddleware } from './define-middleware.js'
-export { defineServerMiddleware } from './define-server-middleware.js'
-export { useSeoMeta } from './use-seo-meta.js'
-export type { SeoMetaInput } from './use-seo-meta.js'
-export { useCookie } from './use-cookie.js'
-export type { CookieOptions, CookieRef } from './use-cookie.js'
-export { useSession } from './use-session.js'
-export type { SessionOptions, SessionComposable } from './use-session.js'
-export { useAuth } from './use-auth.js'
-export type { AuthUser, AuthComposable } from './use-auth.js'
-export { useFetch } from './use-fetch.js'
-export type { UseFetchOptions, UseFetchReturn, UseFetchResult, UseFetchReactiveReturn } from './use-fetch.js'
-export { useRoute } from './use-route.js'
-export type { RouteInfo } from './use-route.js'
-export { navigateTo } from './use-navigate.js'
-export { useState } from './use-state.js'
-export { useLocale } from './use-locale.js'
-export type { LocaleComposable } from './use-locale.js'
-export { queryContent, QueryBuilder } from './use-content.js'
-export { useContentSearch } from './use-content-search.js'
-export type { UseContentSearchReturn } from './use-content-search.js'

package/src/runtime/composables/use-auth.ts

@@ -1,125 +0,0 @@
-import { useSession } from './use-session.js'
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * Normalised user profile stored in the auth session after a successful OAuth login.
- * The `provider`, `id`, and at least one of `name`/`email` fields are populated by the built-in
- * provider normalisers. Additional fields from `mapUser()` are merged in.
- */
-export interface AuthUser {
-  provider: string
-  id: string
-  name?: string
-  email?: string
-  avatar?: string
-  [key: string]: unknown
-}
-
-/** Return value of `useAuth()`. Exposes the current user and helpers for login/logout. */
-export interface AuthComposable {
-  /** The currently authenticated user, or `null` if not logged in. */
-  readonly user: AuthUser | null
-  /** `true` when a user is authenticated. */
-  readonly loggedIn: boolean
-  /**
-   * Initiates an OAuth login flow by redirecting to `/api/auth/:provider`.
-   * Only meaningful on the client — calling this on the server is a no-op.
-   */
-  login(provider: string): void
-  /**
-   * Logs out the current user.
-   *
-   * - **Server context** (inside a loader / middleware): clears the auth
-   *   session cookie immediately via `useSession().clear()`.
-   * - **Client context**: redirects to `/api/auth/logout` which clears the
-   *   cookie server-side and redirects to `redirectAfterLogout`.
-   */
-  logout(): Promise<void>
-}
-
-// ─── Composable ───────────────────────────────────────────────────────────────
-
-/**
- * Returns the currently authenticated user and helpers for login/logout.
- *
- * Works isomorphically:
- * - **Server render pass** — reads from `globalThis.__CER_AUTH_STORE__`
- *   (AsyncLocalStorage populated by the entry-server handler before rendering).
- * - **Client hydration** — reads from `globalThis.__CER_AUTH_USER__` (injected
- *   as `window.__CER_AUTH_USER__` by the entry-server and captured by the
- *   client entry before the app boots).
- *
- * @param sessionKey - Session cookie name; must match `auth.sessionKey` in
- *   `cer.config.ts` (defaults to `'auth'`).
- *
- * @example
- * ```ts
- * // app/pages/profile.ts
- * component('page-profile', () => {
- *   const { user, loggedIn, logout } = useAuth()
- *
- *   if (!loggedIn) {
- *     // Redirect to login
- *     useHead({ title: 'Login required' })
- *   }
- * })
- * ```
- *
- * @example
- * ```ts
- * // app/middleware/require-auth.ts
- * export default defineMiddleware((to) => {
- *   const { loggedIn } = useAuth()
- *   if (!loggedIn) return '/login'
- *   return true
- * })
- * ```
- */
-export function useAuth(sessionKey = 'auth'): AuthComposable {
-  const g = globalThis as Record<string, unknown>
-
-  // Server: read from the per-request AsyncLocalStorage context.
-  // __CER_AUTH_STORE__ is only present in Node.js (tree-shaken on client).
-  const authStore = g['__CER_AUTH_STORE__'] as { getStore(): unknown } | undefined
-  let user: AuthUser | null = null
-
-  if (authStore) {
-    user = (authStore.getStore() as AuthUser | null) ?? null
-  } else {
-    // Client: read from the global hydrated by the client entry.
-    user = (g['__CER_AUTH_USER__'] as AuthUser | null) ?? null
-  }
-
-  return {
-    get user() {
-      return user
-    },
-
-    get loggedIn() {
-      return user !== null
-    },
-
-    login(provider: string) {
-      if (typeof window !== 'undefined') {
-        window.location.href = `/api/auth/${provider}`
-      }
-    },
-
-    async logout() {
-      if (typeof window !== 'undefined') {
-        // Client: let the server clear the cookie via the logout route.
-        window.location.href = '/api/auth/logout'
-      } else {
-        // Server context: clear the session cookie directly.
-        const session = useSession({ name: sessionKey })
-        await session.clear()
-        // Also clear the local user reference so the current render sees null.
-        user = null
-        // Clear the ALS store value so concurrent requests are unaffected.
-        const store = (g['__CER_AUTH_STORE__'] as { enterWith(v: unknown): void } | undefined)
-        if (store) store.enterWith(null)
-      }
-    },
-  }
-}