@jasonshimmy/vite-plugin-cer-app 0.18.2 → 0.19.0

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

@@ -1,5 +1,6 @@
 import type { IncomingMessage } from 'node:http'
 
+/** Return value of `useLocale()`. Exposes the active locale and helpers for locale-aware navigation. */
 export interface LocaleComposable {
   /** The active locale code for the current request / page. */
   readonly locale: string

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

@@ -1,11 +1,14 @@
+/** Resolved public runtime config values. Available on both server and client. */
 export interface RuntimeConfigPublic {
   [key: string]: unknown
 }
 
+/** Resolved private runtime config values. Available on the server only — never present on the client. */
 export interface RuntimeConfigPrivate {
   [key: string]: string | string[]
 }
 
+/** Return value of `useRuntimeConfig()`. */
 export interface RuntimeConfigResult {
   public: RuntimeConfigPublic
   private?: RuntimeConfigPrivate
@@ -36,10 +39,27 @@ export function useRuntimeConfig(): RuntimeConfigResult {
   // between the composable and the virtual module.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const mod = (globalThis as any).__cerRuntimeConfig
-  if (mod) return mod as RuntimeConfigResult
+  const config: RuntimeConfigResult = mod ? (mod as RuntimeConfigResult) : { public: {} }
 
-  // Fallback: empty config (e.g. in test environments without the virtual module).
-  return { public: {} }
+  // In browser contexts, wrap the result in a Proxy that throws a clear,
+  // actionable error if any code attempts to read `runtimeConfig.private`.
+  // Private values are server-only secrets and are never serialized into the
+  // client bundle — accessing them client-side is always a bug.
+  if (typeof window !== 'undefined') {
+    return new Proxy(config, {
+      get(target, prop) {
+        if (prop === 'private') {
+          throw new Error(
+            '[cer-app] runtimeConfig.private is not available in the browser. ' +
+            'Move this access into a server-only loader, middleware, or API handler.',
+          )
+        }
+        return Reflect.get(target, prop)
+      },
+    })
+  }
+
+  return config
 }
 
 /**

package/src/runtime/composables/use-seo-meta.ts

@@ -1,5 +1,10 @@
 import { useHead } from './use-head.js'
 
+/**
+ * Convenience input for common SEO meta tags.
+ * Pass to `useSeoMeta()` — it maps each field to the correct `<meta>` or `<title>` tag automatically.
+ * All fields are optional.
+ */
 export interface SeoMetaInput {
   /** Sets the document title. */
   title?: string

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

@@ -3,6 +3,7 @@ import { useRuntimeConfig } from './use-runtime-config.js'
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
+/** Options for `useSession()`. Controls the cookie name and expiry. */
 export interface SessionOptions {
   /**
    * Cookie name for the session. Defaults to `'session'`.
@@ -14,6 +15,10 @@ export interface SessionOptions {
   maxAge?: number
 }
 
+/**
+ * HMAC-signed cookie session returned by `useSession()`.
+ * All methods are async because signing and verification use the Web Crypto API.
+ */
 export interface SessionComposable<T extends Record<string, unknown> = Record<string, unknown>> {
   /**
    * Reads and verifies the session cookie. Returns the session data or `null`

package/src/runtime/entry-server-template.ts

@@ -21,7 +21,7 @@ import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
 import serverMiddleware from 'virtual:cer-server-middleware'
-import { runtimeConfig, _runtimePrivateDefaults, _authSessionKey } from 'virtual:cer-app-config'
+import { runtimeConfig, _runtimePrivateDefaults, _authSessionKey, _hooks } from 'virtual:cer-app-config'
 import { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'
 import { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'
 import entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'
@@ -121,6 +121,9 @@ export async function runServerMiddleware(req, res) {
         })).catch(reject)
       })
     } catch (err) {
+      if (_hooks?.onError) {
+        try { await _hooks.onError(err, { type: 'middleware', path: new URL(req.url ?? '/', 'http://x').pathname, req }) } catch { /* hooks must not crash the handler */ }
+      }
       if (!res.writableEnded) {
         const statusCode = (typeof err === 'object' && err !== null && 'status' in err && typeof err.status === 'number')
           ? (isNaN(err.status) ? 500 : err.status)
@@ -277,6 +280,9 @@ const _prepareRequest = async (req) => {
       const status = (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number')
         ? err.status : 500
       const message = (err instanceof Error) ? err.message : String(err)
+      if (_hooks?.onError) {
+        try { await _hooks.onError(err, { type: 'loader', path: new URL(req.url ?? '/', 'http://x').pathname, req }) } catch { /* hooks must not crash the handler */ }
+      }
       // P2-2: Prefer the route-level errorTag over the global one.
       // routeErrorTag is not in scope here; use route?.meta?.errorTag from the matched route.
       const effectiveErrorTag = route?.meta?.errorTag ?? errorTag
@@ -309,6 +315,11 @@ const _prepareRequest = async (req) => {
 }
 
 export const handler = async (req, res) => {
+  const _requestPath = new URL(req.url ?? '/', 'http://x').pathname
+  const _requestStart = Date.now()
+  if (_hooks?.onRequest) {
+    try { await _hooks.onRequest({ path: _requestPath, method: req.method ?? 'GET', req }) } catch { /* hooks must not crash the handler */ }
+  }
   await _cerStateStore.run(new Map(), async () => {
   await _cerReqStore.run({ req, res }, async () => {
   await _cerDataStore.run(null, async () => {
@@ -406,7 +417,13 @@ export const handler = async (req, res) => {
 
       // Inject DSD polyfill immediately before </body>, then close the document.
       res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)
+      if (_hooks?.onResponse) {
+        try { void _hooks.onResponse({ path: _requestPath, method: req.method ?? 'GET', statusCode: res.statusCode, duration: Date.now() - _requestStart, req }) } catch { /* ignore */ }
+      }
     } catch (_renderErr) {
+      if (_hooks?.onError) {
+        try { await _hooks.onError(_renderErr, { type: 'render', path: _requestPath, req }) } catch { /* hooks must not crash the handler */ }
+      }
       // Ensure the head collector is never left open on error.
       if (_headCollectionOpen) { try { endHeadCollection() } catch { /* ignore */ } }
       // If headers have not been flushed yet we can still send a proper 500 page.
@@ -418,6 +435,9 @@ export const handler = async (req, res) => {
       } else {
         res.end()
       }
+      if (_hooks?.onResponse) {
+        try { void _hooks.onResponse({ path: _requestPath, method: req.method ?? 'GET', statusCode: res.statusCode, duration: Date.now() - _requestStart, req }) } catch { /* ignore */ }
+      }
     }
   })  // _cerAuthStore.run
   })  // _cerFetchStore.run

package/src/runtime/isr-handler.ts

@@ -17,6 +17,7 @@
 
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
+/** A single cached SSR response stored by `createIsrHandler`. Includes the full rendered HTML, response headers, status code, and revalidation metadata. */
 export interface IsrCacheEntry {
   html: string
   headers: Record<string, string>
@@ -25,6 +26,7 @@ export interface IsrCacheEntry {
   revalidate: number
 }
 
+/** The SSR request handler signature produced by the server entry bundle (exported as `handler`). Compatible with Express, Hono, and any Node.js HTTP server. */
 export type SsrHandlerFn = (req: IncomingMessage, res: ServerResponse) => unknown
 
 // ─── Internal helpers ─────────────────────────────────────────────────────────

package/src/types/api.ts

@@ -1,18 +1,39 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
+/**
+ * Augmented Node.js `IncomingMessage` passed to API route handlers.
+ * Route params and query string are pre-parsed; `body` is parsed from JSON automatically.
+ */
 export interface ApiRequest extends IncomingMessage {
   params: Record<string, string>
   query: Record<string, string>
   body: unknown
 }
 
+/**
+ * Augmented Node.js `ServerResponse` passed to API route handlers.
+ * Adds convenience methods for JSON responses and fluent status setting.
+ */
 export interface ApiResponse extends ServerResponse {
   json(data: unknown): void
   status(code: number): ApiResponse
 }
 
+/**
+ * Handler function for a file-based API route (`app/api/**\/*.ts`).
+ *
+ * @example
+ * ```ts
+ * // app/api/posts/[id].ts
+ * export const GET: ApiHandler = async (req, res) => {
+ *   const post = await fetchPost(req.params.id)
+ *   res.json(post)
+ * }
+ * ```
+ */
 export type ApiHandler = (req: ApiRequest, res: ApiResponse) => Promise<void> | void
 
+/** Combined request/response context passed to API utility functions and composables inside API handlers. */
 export interface ApiContext {
   req: ApiRequest
   res: ApiResponse

package/src/types/config.ts

@@ -1,7 +1,57 @@
 import type { RouterConfig } from '@jasonshimmy/custom-elements-runtime/router'
+import type { IncomingMessage } from 'node:http'
+
+// ─── Observability hook context types ─────────────────────────────────────────
+
+/**
+ * Context passed to the `onError` hook.
+ * `type` indicates which layer the error originated from so reporters can
+ * tag or route errors appropriately.
+ */
+export interface ErrorHookContext {
+  /** The layer that threw the error. */
+  type: 'loader' | 'render' | 'middleware'
+  /** The request URL pathname (e.g. `/about`). */
+  path: string
+  /** The raw Node.js incoming request. */
+  req: IncomingMessage
+}
+
+/**
+ * Context passed to the `onRequest` hook.
+ * Fires at the start of every SSR request, before the route is matched
+ * or the loader runs.
+ */
+export interface RequestHookContext {
+  /** The request URL pathname (e.g. `/about`). */
+  path: string
+  /** HTTP method in upper-case (e.g. `'GET'`). */
+  method: string
+  /** The raw Node.js incoming request. */
+  req: IncomingMessage
+}
+
+/**
+ * Context passed to the `onResponse` hook.
+ * Fires after the response has been sent (both success and error paths).
+ * Use this for latency tracking and request logging.
+ */
+export interface ResponseHookContext {
+  /** The request URL pathname (e.g. `/about`). */
+  path: string
+  /** HTTP method in upper-case (e.g. `'GET'`). */
+  method: string
+  /** Final HTTP status code written to the response. */
+  statusCode: number
+  /** Request duration in milliseconds from the first byte received to `res.end()`. */
+  duration: number
+  /** The raw Node.js incoming request. */
+  req: IncomingMessage
+}
 
 // ─── OAuth / Auth types ───────────────────────────────────────────────────────
 
+/** Token payload returned by an OAuth provider after a successful authorization code exchange. */
 export interface OAuthTokens {
   accessToken: string
   refreshToken?: string
@@ -9,6 +59,7 @@ export interface OAuthTokens {
   tokenType: string
 }
 
+/** Configuration for a single OAuth 2.0 provider (Google, GitHub, Discord, or a custom provider). */
 export interface OAuthProviderConfig {
   /** OAuth application client ID. */
   clientId: string
@@ -30,6 +81,7 @@ export interface OAuthProviderConfig {
   mapUser?: (profile: Record<string, unknown>, tokens: OAuthTokens) => Record<string, unknown>
 }
 
+/** Authentication configuration. Enables OAuth login flows and auto-generates `/api/auth/*` routes. */
 export interface AuthConfig {
   /**
    * OAuth provider configurations keyed by provider name.
@@ -53,6 +105,7 @@ export interface AuthConfig {
   sessionKey?: string
 }
 
+/** Internationalisation routing configuration. When set, locale-aware URL routes are generated and `useLocale()` is enabled. */
 export interface I18nConfig {
   /**
    * All supported locale codes. e.g. `['en', 'fr', 'de']`.
@@ -71,28 +124,46 @@ export interface I18nConfig {
   strategy?: 'prefix' | 'prefix_except_default' | 'no_prefix'
 }
 
+/** Global Static Site Generation (SSG) configuration. Controls which routes are pre-rendered and at what concurrency. */
 export interface SsgConfig {
+  /**
+   * Routes to pre-render.
+   * - `'auto'` (default) — pre-render every static route discovered in `app/pages/`.
+   * - `string[]` — explicit list of paths (e.g. `['/about', '/contact']`).
+   */
   routes?: 'auto' | string[]
+  /** Maximum number of pages rendered in parallel. Defaults to `1`. Increase for faster SSG builds at the cost of higher memory usage. */
   concurrency?: number
-  fallback?: boolean // fall back to SSR for unenumerated routes
+  /** When `true`, unenumerated routes fall back to SSR at runtime instead of returning 404. */
+  fallback?: boolean
 }
 
+/** JIT (Just-In-Time) CSS configuration for shadow-DOM style injection. */
 export interface JitCssConfig {
+  /** Additional glob patterns for content files scanned by the JIT CSS engine. */
   content?: string[]
+  /** Enable the extended color palette. Defaults to `false`. */
   extendedColors?: boolean
 }
 
+/** Fine-grained control over which auto-import categories are injected into page/layout/component files. All categories are enabled by default. */
 export interface AutoImportsConfig {
+  /** Auto-import components defined in `app/components/`. Defaults to `true`. */
   components?: boolean
+  /** Auto-import framework composables (`useHead`, `useState`, etc.). Defaults to `true`. */
   composables?: boolean
+  /** Auto-import template directives (`when`, `each`, `bind`). Defaults to `true`. */
   directives?: boolean
+  /** Auto-import runtime primitives (`component`, `html`, `ref`, etc.). Defaults to `true`. */
   runtime?: boolean
 }
 
+/** Arbitrary public runtime values serialized into the virtual module at build time. Available on both server and client via `useRuntimeConfig().public`. */
 export interface RuntimePublicConfig {
   [key: string]: unknown
 }
 
+/** Server-only secrets resolved from `process.env` at startup. Never serialized into the client bundle. Available via `useRuntimeConfig().private` in loaders and server middleware only. */
 export interface RuntimePrivateConfig {
   /**
    * HMAC-SHA-256 signing secret(s) for `useSession()`.
@@ -119,6 +190,7 @@ export interface RuntimePrivateConfig {
   [key: string]: string | string[] | undefined
 }
 
+/** Runtime configuration split into `public` (client + server) and `private` (server-only) sections. */
 export interface RuntimeConfig {
   /**
    * Public runtime config — available on both server and client via
@@ -146,6 +218,7 @@ export interface RuntimeConfig {
   private?: RuntimePrivateConfig
 }
 
+/** Root configuration object for `cer.config.ts`. Pass to `defineConfig()` for type-safe configuration. */
 export interface CerAppConfig {
   mode?: 'spa' | 'ssr' | 'ssg'
   srcDir?: string // defaults to 'app'
@@ -218,8 +291,60 @@ export interface CerAppConfig {
    * ```
    */
   auth?: AuthConfig
+  /**
+   * Called when an error is caught by the framework's SSR error boundaries
+   * (loader throws, render crash, or server middleware throws). Use this to
+   * forward errors to Sentry, Datadog, or any other error-reporting service.
+   *
+   * Errors in this hook are silently swallowed so they cannot crash the request handler.
+   *
+   * @example
+   * ```ts
+   * import * as Sentry from '@sentry/node'
+   * export default defineConfig({
+   *   onError(err, ctx) {
+   *     Sentry.captureException(err, { tags: { type: ctx.type, path: ctx.path } })
+   *   },
+   * })
+   * ```
+   */
+  onError?: (err: unknown, ctx: ErrorHookContext) => void | Promise<void>
+  /**
+   * Called at the start of every SSR request, before route matching and the loader.
+   * Use this for request logging or to initialise per-request APM transactions.
+   *
+   * Errors in this hook are silently swallowed.
+   */
+  onRequest?: (ctx: RequestHookContext) => void | Promise<void>
+  /**
+   * Called after every SSR response is sent (both success and error paths).
+   * `ctx.duration` contains the elapsed milliseconds from first byte to `res.end()`.
+   * Use this for latency tracking and access logging.
+   *
+   * Errors in this hook are silently swallowed.
+   */
+  onResponse?: (ctx: ResponseHookContext) => void | Promise<void>
 }
 
+/**
+ * Define the framework configuration with full TypeScript intellisense.
+ * This is a pass-through helper — it returns `config` unchanged and exists
+ * solely to provide type checking and IDE autocompletion in `cer.config.ts`.
+ *
+ * @example
+ * ```ts
+ * // cer.config.ts
+ * import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+ *
+ * export default defineConfig({
+ *   mode: 'ssr',
+ *   runtimeConfig: {
+ *     public: { apiBase: 'https://api.example.com' },
+ *     private: { dbUrl: '' },
+ *   },
+ * })
+ * ```
+ */
 export function defineConfig(config: CerAppConfig): CerAppConfig {
   return config
 }

package/src/types/index.ts

@@ -1,4 +1,4 @@
-export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig, RuntimePrivateConfig, I18nConfig } from './config.js'
+export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig, RuntimePrivateConfig, I18nConfig, ErrorHookContext, RequestHookContext, ResponseHookContext } from './config.js'
 export { defineConfig } from './config.js'
 export type { HydrateStrategy, SsgPathsContext, PageSsgConfig, PageMeta, PageLoaderContext, PageLoader } from './page.js'
 export type { ApiRequest, ApiResponse, ApiHandler, ApiContext } from './api.js'

package/src/types/middleware.ts

@@ -40,6 +40,22 @@ export type MiddlewareFn = (
   next: () => Promise<void>,
 ) => GuardResult | void
 
+/**
+ * Server middleware function. Receives the raw Node.js `req`/`res` pair and a `next`
+ * callback. Call `next()` to pass control to the next middleware in the chain,
+ * or call `next(err)` to signal an error (sets the response status from `err.status`,
+ * defaulting to 500).
+ *
+ * Defined with `defineServerMiddleware()` and placed in `app/middleware/`.
+ *
+ * @example
+ * ```ts
+ * export default defineServerMiddleware((req, res, next) => {
+ *   res.setHeader('X-Request-Id', crypto.randomUUID())
+ *   next()
+ * })
+ * ```
+ */
 export type ServerMiddleware = (
   req: IncomingMessage,
   res: ServerResponse,

package/src/types/page.ts

@@ -1,12 +1,39 @@
 import type { IncomingMessage } from 'node:http'
 
+/**
+ * Controls when the client-side JS activates a pre-rendered page component.
+ *
+ * - `'load'`    — activate immediately on page load (default).
+ * - `'idle'`    — defer until `requestIdleCallback` fires (browser idle time).
+ * - `'visible'` — defer until `cer-layout-view` enters the viewport (IntersectionObserver).
+ * - `'none'`    — never activate; SSR HTML is served as static markup with no JS.
+ */
 export type HydrateStrategy = 'load' | 'idle' | 'visible' | 'none'
 
+/** Context object passed to a page's `ssg.paths()` function. Contains resolved route params for one path variant. */
 export interface SsgPathsContext {
   params: Record<string, string>
 }
 
+/** Per-page SSG / ISR configuration. Export as `export const meta = { ssg: { ... } }` from any page file. */
 export interface PageSsgConfig {
+  /**
+   * Factory that returns the set of param combinations to pre-render for dynamic routes.
+   * Required for dynamic routes (e.g. `/posts/[slug]`) — without it the route is skipped
+   * during the static build.
+   *
+   * @example
+   * ```ts
+   * export const meta = {
+   *   ssg: {
+   *     paths: async () => {
+   *       const slugs = await fetchAllSlugs()
+   *       return slugs.map(slug => ({ params: { slug } }))
+   *     },
+   *   },
+   * }
+   * ```
+   */
   paths?: () => Promise<SsgPathsContext[]> | SsgPathsContext[]
   /**
    * Seconds before a cached SSR response is stale and should be re-rendered.
@@ -18,9 +45,15 @@ export interface PageSsgConfig {
   revalidate?: number
 }
 
+/**
+ * Per-page metadata. Export as `export const meta = { ... }` from any page file.
+ * Values are read at build time and embedded into the route manifest.
+ */
 export interface PageMeta {
-  layout?: string // name of layout in app/layouts/ (default: 'default')
-  middleware?: string[] // named middleware files from app/middleware/
+  /** Layout component to wrap this page. Must match a file in `app/layouts/`. Defaults to `'default'`. */
+  layout?: string
+  /** Named middleware files from `app/middleware/` to run before this route activates. */
+  middleware?: string[]
   hydrate?: HydrateStrategy
   ssg?: PageSsgConfig
   /**
@@ -48,12 +81,35 @@ export interface PageMeta {
   render?: 'static' | 'server' | 'spa'
 }
 
+/**
+ * Context object passed to a page's `loader` function.
+ * Available on the server only — the loader runs before the page component renders.
+ */
 export interface PageLoaderContext<P extends Record<string, string> = Record<string, string>> {
   params: P
   query: Record<string, string>
   req: IncomingMessage
 }
 
+/**
+ * Server-side data loader for a page. Export as `export const loader` (or `export async function loader`)
+ * from any page file. The returned object is:
+ * - Made available via `usePageData()` inside the page component.
+ * - Primitive values are also forwarded as element attributes so `useProps()` works.
+ * - Serialized into `window.__CER_DATA__` for client-side hydration.
+ *
+ * Throwing an error (with an optional `.status` property) renders the page's error component
+ * and sets the HTTP response status code.
+ *
+ * @example
+ * ```ts
+ * export const loader: PageLoader<{ slug: string }, { post: Post }> = async ({ params }) => {
+ *   const post = await fetchPost(params.slug)
+ *   if (!post) throw Object.assign(new Error('Not found'), { status: 404 })
+ *   return { post }
+ * }
+ * ```
+ */
 export type PageLoader<
   P extends Record<string, string> = Record<string, string>,
   D = Record<string, unknown>,

package/src/types/plugin.ts

@@ -1,12 +1,33 @@
 import type { Router } from '@jasonshimmy/custom-elements-runtime/router'
 import type { CerAppConfig } from './config.js'
 
+/**
+ * Application context passed to each plugin's `setup()` function.
+ * Use it to provide values to the component tree, access the router,
+ * or read the resolved config.
+ */
 export interface AppContext {
   provide(key: PropertyKey, value: unknown): void
   router: Router
   config: CerAppConfig
 }
 
+/**
+ * A framework plugin. Plugins run once at app startup (both server and client) before
+ * the first route renders. Use them for global setup: registering provide/inject values,
+ * subscribing to router events, or initialising third-party libraries.
+ *
+ * @example
+ * ```ts
+ * // app/plugins/analytics.ts
+ * export default {
+ *   name: 'analytics',
+ *   async setup({ router }) {
+ *     router.subscribe(({ path }) => trackPageView(path))
+ *   },
+ * } satisfies AppPlugin
+ * ```
+ */
 export interface AppPlugin {
   name: string
   setup(app: AppContext): void | Promise<void>