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

package/dist/types/page.d.ts

@@ -1,9 +1,36 @@
 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.
@@ -14,8 +41,14 @@ 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 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;
@@ -43,10 +76,33 @@ 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>> = (ctx: PageLoaderContext<P>) => Promise<D> | D;
 //# sourceMappingURL=page.d.ts.map

package/dist/types/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/types/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,GAAG,eAAe,EAAE,CAAA;IAC5D;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,GAAG,CAAC,EAAE,aAAa,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;CACrC;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC1F,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,GAAG,EAAE,eAAe,CAAA;CACrB;AAED,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/types/page.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAElE,qHAAqH;AACrH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,6GAA6G;AAC7G,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,eAAe,EAAE,CAAC,GAAG,eAAe,EAAE,CAAA;IAC5D;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,wGAAwG;IACxG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,GAAG,CAAC,EAAE,aAAa,CAAA;IACnB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,KAAK,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC1F,MAAM,EAAE,CAAC,CAAA;IACT,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC7B,GAAG,EAAE,eAAe,CAAA;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,CACpB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACzD,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IACzB,CAAC,GAAG,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA"}

package/dist/types/plugin.d.ts

@@ -1,10 +1,31 @@
 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>;

package/dist/types/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6CAA6C,CAAA;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7C"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6CAA6C,CAAA;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7C"}

package/docs/authentication.md

@@ -50,6 +50,24 @@ When `auth` is configured, the framework automatically registers:
 | `GET /api/auth/callback/:provider` | Handles the OAuth callback — exchanges the code for tokens, fetches the user profile, writes the auth session cookie, and redirects to `redirectAfterLogin` |
 | `GET /api/auth/logout` | Clears the auth session cookie and redirects to `redirectAfterLogout` |
 
+### OAuth error handling
+
+All network calls in the callback route (token exchange and user-info fetch) are wrapped in try/catch. If a provider is unreachable or returns an unexpected response, the handler responds with HTTP 502 and a plain-text diagnostic message rather than crashing the server:
+
+| Failure | Status | Response body |
+|---|---|---|
+| Token exchange network error | 502 | `[cer-app] OAuth token exchange request failed` |
+| Token exchange non-OK HTTP status | 502 | `[cer-app] OAuth token exchange returned non-OK status` |
+| Token exchange invalid JSON | 502 | `[cer-app] OAuth token exchange returned invalid JSON` |
+| User-info network error | 502 | `[cer-app] OAuth user-info request failed` |
+| User-info non-OK HTTP status | 502 | `[cer-app] OAuth user-info returned non-OK status` |
+| User-info invalid JSON | 502 | `[cer-app] OAuth user-info returned invalid JSON` |
+| Unknown provider | 404 | `[cer-app] Unknown OAuth provider: <name>` |
+| Missing state / code param | 400 | `[cer-app] OAuth callback missing code or state parameter` |
+| State mismatch (CSRF) | 400 | `[cer-app] OAuth state mismatch — possible CSRF attempt` |
+
+These responses are intentionally terse — they are server-to-server error messages, not end-user UI. To show a branded error page when OAuth fails, redirect in a top-level error boundary or handle the 502 at your reverse proxy / CDN layer.
+
 ---
 
 ## `useAuth(sessionKey?)`

package/docs/configuration.md

@@ -415,7 +415,12 @@ export const loader = async () => {
 }
 ```
 
-> `useRuntimeConfig().private` is `undefined` on the client. Only access it in server-only contexts (loaders, server middleware, API handlers).
+> **Browser enforcement:** Accessing `useRuntimeConfig().private` in a browser context throws a clear runtime error:
+> ```
+> [cer-app] runtimeConfig.private is not available in the browser.
+> Move this access into a server-only loader, middleware, or API handler.
+> ```
+> This prevents accidental secret leaks — the Proxy is applied automatically with no extra configuration required.
 
 **TypeScript:** Import `RuntimePrivateConfig` to type your private config:
 
@@ -425,6 +430,122 @@ import type { RuntimePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/type
 
 ---
 
+## Observability hooks
+
+Three optional hooks in `cer.config.ts` give you visibility into every SSR request without modifying any application code.
+
+> **SSR mode only.** These hooks are invoked by the Node.js SSR request handler. They do **not** fire in SSG or SPA modes:
+> - **SSG** — pages are pre-rendered to static HTML at build time and served directly by the file server. No Node.js handler processes individual page requests at runtime, so no hooks fire.
+> - **SPA** — there is no server-side render pass; the browser loads `index.html` and renders entirely client-side.
+>
+> If you need request logging in SSG/SPA deployments, add it at the reverse-proxy or CDN layer instead.
+
+### `onRequest`
+
+Called at the start of every SSR request, before route matching and the data loader. Use this for request logging or to initialise per-request APM transactions.
+
+**Type:** `(ctx: RequestHookContext) => void | Promise<void>`
+
+| Field | Type | Description |
+|---|---|---|
+| `ctx.path` | `string` | URL pathname (e.g. `/about`) |
+| `ctx.method` | `string` | HTTP method in upper-case (e.g. `'GET'`) |
+| `ctx.req` | `IncomingMessage` | Raw Node.js incoming request |
+
+Errors thrown inside `onRequest` are silently swallowed — the hook cannot crash the request handler.
+
+### `onResponse`
+
+Called after every SSR response is sent, on both success and error paths. `ctx.duration` contains the elapsed milliseconds from the first byte received to `res.end()`. Use this for latency tracking and access logging.
+
+**Type:** `(ctx: ResponseHookContext) => void | Promise<void>`
+
+| Field | Type | Description |
+|---|---|---|
+| `ctx.path` | `string` | URL pathname |
+| `ctx.method` | `string` | HTTP method |
+| `ctx.statusCode` | `number` | Final HTTP status code written to the response |
+| `ctx.duration` | `number` | Request duration in milliseconds |
+| `ctx.req` | `IncomingMessage` | Raw Node.js incoming request |
+
+Errors thrown inside `onResponse` are silently swallowed.
+
+### `onError`
+
+Called when an error is caught by the framework's SSR error boundaries:
+
+- **`'loader'`** — the data loader threw
+- **`'render'`** — an infrastructure-level render error escaped the runtime
+- **`'middleware'`** — a server middleware threw
+
+Use this to forward errors to Sentry, Datadog, or any error-reporting service.
+
+**Type:** `(err: unknown, ctx: ErrorHookContext) => void | Promise<void>`
+
+| Field | Type | Description |
+|---|---|---|
+| `ctx.type` | `'loader' \| 'render' \| 'middleware'` | Which layer the error originated from |
+| `ctx.path` | `string` | URL pathname |
+| `ctx.req` | `IncomingMessage` | Raw Node.js incoming request |
+
+Errors thrown inside `onError` are silently swallowed — the hook cannot crash the request handler.
+
+### Example — Sentry integration
+
+```ts
+// cer.config.ts
+import * as Sentry from '@sentry/node'
+import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+
+Sentry.init({ dsn: process.env.SENTRY_DSN })
+
+export default defineConfig({
+  onError(err, ctx) {
+    Sentry.captureException(err, {
+      tags: { type: ctx.type, path: ctx.path },
+    })
+  },
+
+  onRequest(ctx) {
+    console.log(`→ ${ctx.method} ${ctx.path}`)
+  },
+
+  onResponse(ctx) {
+    console.log(`← ${ctx.statusCode} ${ctx.path} (${ctx.duration}ms)`)
+  },
+})
+```
+
+### Example — console request logger
+
+```ts
+// cer.config.ts
+import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+
+export default defineConfig({
+  onRequest({ method, path }) {
+    console.log(`[${new Date().toISOString()}] ${method} ${path}`)
+  },
+  onResponse({ method, path, statusCode, duration }) {
+    console.log(`[${new Date().toISOString()}] ${statusCode} ${method} ${path} — ${duration}ms`)
+  },
+})
+```
+
+### TypeScript types
+
+All hook context types are exported from `@jasonshimmy/vite-plugin-cer-app/types`:
+
+```ts
+import type {
+  ErrorHookContext,
+  RequestHookContext,
+  ResponseHookContext,
+} from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
 ## Passing config to the Vite plugin directly
 
 When using `vite.config.ts` instead of (or alongside) `cer.config.ts`:
@@ -459,6 +580,10 @@ import type {
   AutoImportsConfig,
   RuntimeConfig,
   RuntimePublicConfig,
+  RuntimePrivateConfig,
   I18nConfig,
+  ErrorHookContext,
+  RequestHookContext,
+  ResponseHookContext,
 } from '@jasonshimmy/vite-plugin-cer-app/types'
 ```

package/e2e/cypress/e2e/observability.cy.ts

@@ -0,0 +1,77 @@
+/**
+ * Observability hooks e2e tests.
+ *
+ * Log-based tests (onRequest / onResponse firing) only run in SSR mode because
+ * SSG serves pre-built static files — the Node.js SSR handler is never called,
+ * so the hooks never fire. SPA mode also has no server-side render pass.
+ *
+ * The private-config browser enforcement tests run in all modes.
+ */
+
+const LOG_FILE = '/tmp/cer-hooks-test.log'
+const isSSR = () => Cypress.env('mode') === 'ssr'
+
+describe('Observability hooks — log output (SSR only)', () => {
+  before(() => {
+    if (!isSSR()) return
+    // Clear the log file so each run starts clean.
+    cy.writeFile(LOG_FILE, '')
+  })
+
+  it('fires onRequest and onResponse for a successful page request', function () {
+    if (!isSSR()) return this.skip()
+    cy.request('/observability-test').then(() => {
+      cy.readFile(LOG_FILE).then((log: string) => {
+        expect(log).to.match(/REQUEST GET \/observability-test/)
+        expect(log).to.match(/RESPONSE 200 GET \/observability-test \d+ms/)
+      })
+    })
+  })
+
+  it('onResponse includes a non-negative duration in milliseconds', function () {
+    if (!isSSR()) return this.skip()
+    cy.writeFile(LOG_FILE, '')
+    cy.request('/').then(() => {
+      cy.readFile(LOG_FILE).then((log: string) => {
+        const match = log.match(/RESPONSE \d+ GET \/ (\d+)ms/)
+        expect(match).to.not.be.null
+        const duration = parseInt(match![1], 10)
+        expect(duration).to.be.gte(0)
+      })
+    })
+  })
+
+  it('does not write an ERROR entry for a normal request', function () {
+    if (!isSSR()) return this.skip()
+    cy.writeFile(LOG_FILE, '')
+    cy.request('/').then(() => {
+      cy.readFile(LOG_FILE).then((log: string) => {
+        expect(log).not.to.include('ERROR')
+      })
+    })
+  })
+})
+
+describe('Observability hooks — server stability', () => {
+  it('pages render correctly when hooks are defined (hooks do not crash the server)', () => {
+    cy.visit('/observability-test')
+    cy.get('[data-cy=observability-heading]').should('contain', 'Observability Test')
+  })
+})
+
+describe('Private config browser enforcement', () => {
+  it('renders runtimeConfig.public values on the page', () => {
+    cy.visit('/observability-test')
+    cy.get('[data-cy=public-app-name]').should('contain', 'Kitchen Sink')
+  })
+
+  it('throws a Proxy error when .private is accessed in a browser context', () => {
+    cy.visit('/observability-test')
+    // After client-side hydration the component catches the Proxy error and
+    // renders it in [data-cy=private-proxy-error].
+    cy.get('[data-cy=private-proxy-error]').should(
+      'contain',
+      'runtimeConfig.private is not available in the browser',
+    )
+  })
+})

package/e2e/kitchen-sink/app/pages/observability-test.ts

@@ -0,0 +1,25 @@
+component('page-observability-test', () => {
+  const { public: pub } = useRuntimeConfig()
+
+  // Verify that accessing .private in a browser context throws the Proxy error.
+  // The component render function runs client-side (inside the custom element upgrade),
+  // so typeof window !== 'undefined' is true here and the Proxy fires.
+  let privateError = ''
+  if (typeof window !== 'undefined') {
+    try {
+      const cfg = useRuntimeConfig()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      void (cfg as any).private
+    } catch (e) {
+      privateError = (e as Error).message
+    }
+  }
+
+  return html`
+    <div>
+      <h1 data-cy="observability-heading">Observability Test</h1>
+      <div data-cy="public-app-name">${pub.appName as string}</div>
+      <div data-cy="private-proxy-error">${privateError}</div>
+    </div>
+  `
+})

package/e2e/kitchen-sink/cer.config.ts

@@ -1,3 +1,8 @@
+import { appendFileSync } from 'node:fs'
+import type { RequestHookContext, ResponseHookContext, ErrorHookContext } from '@jasonshimmy/vite-plugin-cer-app/types'
+
+const LOG_FILE = '/tmp/cer-hooks-test.log'
+
 // Kitchen sink configuration — mode is overridden by --mode CLI flag
 export default {
   ssg: { routes: 'auto', concurrency: 2 },
@@ -19,4 +24,13 @@ export default {
     defaultLocale: 'en',
     strategy: 'prefix_except_default',
   },
+  onRequest(ctx: RequestHookContext) {
+    try { appendFileSync(LOG_FILE, `REQUEST ${ctx.method} ${ctx.path}\n`) } catch { /* ignore */ }
+  },
+  onResponse(ctx: ResponseHookContext) {
+    try { appendFileSync(LOG_FILE, `RESPONSE ${ctx.statusCode} ${ctx.method} ${ctx.path} ${ctx.duration}ms\n`) } catch { /* ignore */ }
+  },
+  onError(_err: unknown, ctx: ErrorHookContext) {
+    try { appendFileSync(LOG_FILE, `ERROR ${ctx.type} ${ctx.path}\n`) } catch { /* ignore */ }
+  },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.18.2",
+  "version": "0.19.0",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [

package/src/__tests__/plugin/entry-server-template.test.ts

@@ -304,4 +304,54 @@ describe('entry-server-template (ENTRY_SERVER_TEMPLATE content)', () => {
     // Fallback to global errorTag
     expect(src).toContain('?? errorTag')
   })
+
+  // ─── Observability hooks ─────────────────────────────────────────────────────
+
+  it('imports _hooks from virtual:cer-app-config', () => {
+    expect(src).toContain('_hooks')
+    expect(src).toContain('virtual:cer-app-config')
+  })
+
+  it('fires onRequest at the start of the handler with path, method, and req', () => {
+    expect(src).toContain('_hooks?.onRequest')
+    expect(src).toContain('_requestPath')
+    expect(src).toContain('_requestStart')
+  })
+
+  it('fires onError in the middleware catch with type: middleware', () => {
+    expect(src).toContain("type: 'middleware'")
+    // onError fires inside runServerMiddleware catch
+    const mwIdx = src.indexOf('runServerMiddleware')
+    const middlewareErrIdx = src.indexOf("type: 'middleware'", mwIdx)
+    expect(middlewareErrIdx).toBeGreaterThan(mwIdx)
+  })
+
+  it('fires onError in the loader catch with type: loader', () => {
+    expect(src).toContain("type: 'loader'")
+  })
+
+  it('fires onError in the render catch with type: render', () => {
+    expect(src).toContain("type: 'render'")
+    const catchIdx = src.indexOf('} catch (_renderErr) {')
+    const renderErrIdx = src.indexOf("type: 'render'", catchIdx)
+    expect(renderErrIdx).toBeGreaterThan(catchIdx)
+  })
+
+  it('fires onResponse after the success res.end()', () => {
+    expect(src).toContain('_hooks?.onResponse')
+    // onResponse must appear after DSD_POLYFILL_SCRIPT + fromBodyClose
+    const endIdx = src.indexOf('DSD_POLYFILL_SCRIPT + fromBodyClose')
+    const responseIdx = src.indexOf('_hooks?.onResponse', endIdx)
+    expect(responseIdx).toBeGreaterThan(endIdx)
+  })
+
+  it('fires onResponse in the render error catch so it fires on both success and error paths', () => {
+    const catchIdx = src.indexOf('} catch (_renderErr) {')
+    const responseInCatchIdx = src.indexOf('_hooks?.onResponse', catchIdx)
+    expect(responseInCatchIdx).toBeGreaterThan(catchIdx)
+  })
+
+  it('swallows exceptions thrown by onError so hooks cannot crash the handler', () => {
+    expect(src).toContain('/* hooks must not crash the handler */')
+  })
 })

package/src/__tests__/runtime/use-runtime-config.test.ts

@@ -1,9 +1,15 @@
-import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
 import { useRuntimeConfig, initRuntimeConfig, resolvePrivateConfig } from '../../runtime/composables/use-runtime-config.js'
 
 beforeEach(() => {
   // Reset global state between tests
   delete (globalThis as Record<string, unknown>).__cerRuntimeConfig
+  // Ensure window is not set (server context for most tests)
+  delete (globalThis as Record<string, unknown>).window
+})
+
+afterEach(() => {
+  delete (globalThis as Record<string, unknown>).window
 })
 
 describe('initRuntimeConfig', () => {
@@ -75,6 +81,39 @@ describe('useRuntimeConfig', () => {
   })
 })
 
+// ─── Browser Proxy (private config enforcement) ───────────────────────────────
+
+describe('useRuntimeConfig browser Proxy', () => {
+  it('throws a clear error when .private is accessed in a browser context', () => {
+    ;(globalThis as Record<string, unknown>).window = {}
+    initRuntimeConfig({ public: { apiBase: '/api' }, private: { secret: 'shh' } })
+    const config = useRuntimeConfig()
+    expect(() => config.private).toThrow('[cer-app] runtimeConfig.private is not available in the browser')
+  })
+
+  it('allows .public access in a browser context', () => {
+    ;(globalThis as Record<string, unknown>).window = {}
+    initRuntimeConfig({ public: { apiBase: '/api' }, private: { secret: 'shh' } })
+    const config = useRuntimeConfig()
+    expect(config.public).toEqual({ apiBase: '/api' })
+  })
+
+  it('does NOT throw when .private is accessed in a server (non-browser) context', () => {
+    // window is not set — server environment
+    initRuntimeConfig({ public: {}, private: { secret: 'shh' } })
+    const config = useRuntimeConfig()
+    expect(() => config.private).not.toThrow()
+    expect(config.private).toEqual({ secret: 'shh' })
+  })
+
+  it('error message instructs moving access to a loader or middleware', () => {
+    ;(globalThis as Record<string, unknown>).window = {}
+    initRuntimeConfig({ public: {} })
+    const config = useRuntimeConfig()
+    expect(() => config.private).toThrow('loader, middleware, or API handler')
+  })
+})
+
 // ─── resolvePrivateConfig ─────────────────────────────────────────────────────
 
 describe('resolvePrivateConfig', () => {

package/src/cli/create/templates/spa/package.json.tpl

@@ -11,7 +11,7 @@
     "@jasonshimmy/custom-elements-runtime": "^3.7.1"
   },
   "devDependencies": {
-    "@jasonshimmy/vite-plugin-cer-app": "^0.18.1",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.19.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.3"
   }

package/src/cli/create/templates/ssg/package.json.tpl

@@ -12,7 +12,7 @@
     "@jasonshimmy/custom-elements-runtime": "^3.7.1"
   },
   "devDependencies": {
-    "@jasonshimmy/vite-plugin-cer-app": "^0.18.1",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.19.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.3"
   }

package/src/cli/create/templates/ssr/package.json.tpl

@@ -11,7 +11,7 @@
     "@jasonshimmy/custom-elements-runtime": "^3.7.1"
   },
   "devDependencies": {
-    "@jasonshimmy/vite-plugin-cer-app": "^0.18.1",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.19.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.3"
   }

package/src/plugin/index.ts

@@ -190,6 +190,19 @@ function generateAppConfigModule(config: ResolvedCerConfig, ssr = false): string
     // the authenticated user without duplicating config knowledge.
     const authSessionKey = config.auth?.sessionKey ?? (config.auth ? 'auth' : null)
     code += `\nexport const _authSessionKey = ${JSON.stringify(authSessionKey)}\n`
+    // Thread observability hooks by re-importing the user's cer.config.ts.
+    // Functions can't be JSON-serialised, so we import directly and re-export.
+    const configFilePath = join(config.root, 'cer.config.ts')
+    if (existsSync(configFilePath)) {
+      code += `\nimport _cerUserConfig from ${JSON.stringify(configFilePath)}\n`
+      code += `export const _hooks = {\n`
+      code += `  onError: _cerUserConfig.onError ?? null,\n`
+      code += `  onRequest: _cerUserConfig.onRequest ?? null,\n`
+      code += `  onResponse: _cerUserConfig.onResponse ?? null,\n`
+      code += `}\n`
+    } else {
+      code += `\nexport const _hooks = { onError: null, onRequest: null, onResponse: null }\n`
+    }
   }
 
   return code

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

@@ -2,6 +2,11 @@ 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
@@ -11,6 +16,7 @@ export interface AuthUser {
   [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

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

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
+/** Options forwarded to the `Set-Cookie` header when writing a cookie via `useCookie()`. */
 export interface CookieOptions {
   /** Cookie path. Defaults to '/' when setting/removing. */
   path?: string
@@ -12,6 +13,7 @@ export interface CookieOptions {
   sameSite?: 'Strict' | 'Lax' | 'None'
 }
 
+/** Isomorphic cookie accessor returned by `useCookie()`. Reads the current value and provides `set`/`remove` methods. */
 export interface CookieRef {
   /** The current cookie value, or undefined if not set. */
   readonly value: string | undefined

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

@@ -72,6 +72,7 @@ export interface UseFetchReactiveReturn<T = unknown> {
   refresh(): Promise<void>
 }
 
+/** Options for `useFetch()`. Controls caching, SSR behaviour, data transformation, and HTTP request details. */
 export interface UseFetchOptions<T = unknown> {
   /**
    * Unique cache key.  Defaults to the full URL string (including query params).

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

@@ -1,3 +1,7 @@
+/**
+ * Describes the `<head>` tags to inject for a page or component.
+ * Pass to `useHead()`. All fields are optional; only set fields are emitted.
+ */
 export interface HeadInput {
   title?: string
   meta?: Array<Record<string, string>>