@jasonshimmy/vite-plugin-cer-app 0.7.0 → 0.9.0

package/dist/runtime/composables/use-runtime-config.js

@@ -1,22 +1,22 @@
 /**
- * Returns the public runtime configuration set in `cer.config.ts` under
- * `runtimeConfig.public`. Available on both server and client.
+ * Returns the runtime configuration set in `cer.config.ts`.
  *
- * Values are baked in at build time from `virtual:cer-app-config`, so only
- * static/env-var values should be placed here. For truly dynamic config,
- * use a loader or API route.
+ * - `public` — available on both server and client.
+ * - `private` — available on the server only (resolved from `process.env` at
+ *   startup). Never present on the client.
  *
  * @example
  * // cer.config.ts
  * export default defineConfig({
  *   runtimeConfig: {
  *     public: { apiBase: process.env.VITE_API_BASE ?? '/api' },
+ *     private: { dbUrl: '', secretKey: '' },
  *   },
  * })
  *
- * // app/pages/index.ts
- * const config = useRuntimeConfig()
- * fetch(config.public.apiBase + '/posts')
+ * // app/pages/index.ts (loader — server-only)
+ * const { private: priv } = useRuntimeConfig()
+ * const rows = await db.query(priv.dbUrl)
  */
 export function useRuntimeConfig() {
     // Dynamic import resolved at runtime — avoids a static circular dependency
@@ -38,4 +38,38 @@ export function initRuntimeConfig(config) {
     ;
     globalThis.__cerRuntimeConfig = config;
 }
+/**
+ * Converts a camelCase or mixed key to UPPER_SNAKE_CASE for env var lookup.
+ * Examples: `dbUrl` → `DB_URL`, `secretKey` → `SECRET_KEY`, `API_KEY` → `API_KEY`.
+ */
+function toUpperSnakeCase(key) {
+    return key
+        .replace(/([a-z])([A-Z])/g, '$1_$2')
+        .toUpperCase();
+}
+/**
+ * Resolves a private config object by looking up each key in the supplied
+ * environment variable map, with the following precedence:
+ *
+ * 1. `env[key]`                   — exact case (e.g. `process.env.dbUrl`)
+ * 2. `env[UPPER_SNAKE_CASE(key)]` — conventional env var form (e.g. `process.env.DB_URL`)
+ * 3. `defaultValue`               — the declared default from `cer.config.ts`
+ *
+ * Accepts an optional `env` parameter so the function is unit-testable
+ * without mutating `process.env`.
+ */
+export function resolvePrivateConfig(defaults, env = process.env) {
+    return Object.fromEntries(Object.entries(defaults).map(([key, defaultValue]) => {
+        const envKey = toUpperSnakeCase(key);
+        const resolved = env[key] ?? env[envKey] ?? defaultValue;
+        // Warn when no env var was found and the declared default is an empty string.
+        // An empty-string default is the conventional way to declare a required secret
+        // (the key exists for typing purposes but has no safe default value).
+        if (resolved === '' && env[key] === undefined && env[envKey] === undefined) {
+            console.warn(`[cer-app] runtimeConfig.private: "${key}" is an empty string — ` +
+                `set ${envKey} in the environment to provide a value.`);
+        }
+        return [key, resolved];
+    }));
+}
 //# sourceMappingURL=use-runtime-config.js.map

package/dist/runtime/composables/use-runtime-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-runtime-config.js","sourceRoot":"","sources":["../../../src/runtime/composables/use-runtime-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,2EAA2E;IAC3E,iDAAiD;IACjD,8DAA8D;IAC9D,MAAM,GAAG,GAAI,UAAkB,CAAC,kBAAkB,CAAA;IAClD,IAAI,GAAG;QAAE,OAAO,GAA0C,CAAA;IAE1D,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA2C;IAC3E,8DAA8D;IAC9D,CAAC;IAAC,UAAkB,CAAC,kBAAkB,GAAG,MAAM,CAAA;AAClD,CAAC"}
+{"version":3,"file":"use-runtime-config.js","sourceRoot":"","sources":["../../../src/runtime/composables/use-runtime-config.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB;IAC9B,2EAA2E;IAC3E,iDAAiD;IACjD,8DAA8D;IAC9D,MAAM,GAAG,GAAI,UAAkB,CAAC,kBAAkB,CAAA;IAClD,IAAI,GAAG;QAAE,OAAO,GAA0B,CAAA;IAE1C,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAA;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAA2B;IAC3D,8DAA8D;IAC9D,CAAC;IAAC,UAAkB,CAAC,kBAAkB,GAAG,MAAM,CAAA;AAClD,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,GAAW;IACnC,OAAO,GAAG;SACP,OAAO,CAAC,iBAAiB,EAAE,OAAO,CAAC;SACnC,WAAW,EAAE,CAAA;AAClB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAgC,EAChC,MAA0C,OAAO,CAAC,GAAyC;IAE3F,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,EAAE,EAAE;QACnD,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;QACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,YAAY,CAAA;QACxD,8EAA8E;QAC9E,+EAA+E;QAC/E,sEAAsE;QACtE,IAAI,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YAC3E,OAAO,CAAC,IAAI,CACV,qCAAqC,GAAG,yBAAyB;gBACjE,OAAO,MAAM,yCAAyC,CACvD,CAAA;QACH,CAAC;QACD,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IACxB,CAAC,CAAC,CACH,CAAA;AACH,CAAC"}

package/dist/runtime/composables/use-seo-meta.d.ts

@@ -0,0 +1,42 @@
+export interface SeoMetaInput {
+    /** Sets the document title. */
+    title?: string;
+    /** Sets the meta description. */
+    description?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogUrl?: string;
+    /** e.g. `'website'`, `'article'`. No tag is emitted when omitted. */
+    ogType?: string;
+    ogSiteName?: string;
+    /** e.g. `'summary'`, `'summary_large_image'`. No tag is emitted when omitted. */
+    twitterCard?: string;
+    twitterTitle?: string;
+    twitterDescription?: string;
+    twitterImage?: string;
+    /** Twitter/X site handle, e.g. '@mysite'. */
+    twitterSite?: string;
+    /** Canonical URL injected as <link rel="canonical">. */
+    canonical?: string;
+}
+/**
+ * Thin wrapper over `useHead()` for common SEO tags.
+ *
+ * Sets the page title, meta description, Open Graph tags, Twitter Card tags,
+ * and a canonical link element. Only tags with a non-undefined value are emitted.
+ *
+ * It is auto-imported, so you don't need to import it manually.
+ *
+ * @example
+ * ```ts
+ * useSeoMeta({
+ *   title: 'My page',
+ *   description: 'A great page.',
+ *   ogImage: 'https://example.com/og.png',
+ *   canonical: 'https://example.com/my-page',
+ * })
+ * ```
+ */
+export declare function useSeoMeta(input: SeoMetaInput): void;
+//# sourceMappingURL=use-seo-meta.d.ts.map

package/dist/runtime/composables/use-seo-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-seo-meta.d.ts","sourceRoot":"","sources":["../../../src/runtime/composables/use-seo-meta.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CA6BpD"}

package/dist/runtime/composables/use-seo-meta.js

@@ -0,0 +1,58 @@
+import { useHead } from './use-head.js';
+/**
+ * Thin wrapper over `useHead()` for common SEO tags.
+ *
+ * Sets the page title, meta description, Open Graph tags, Twitter Card tags,
+ * and a canonical link element. Only tags with a non-undefined value are emitted.
+ *
+ * It is auto-imported, so you don't need to import it manually.
+ *
+ * @example
+ * ```ts
+ * useSeoMeta({
+ *   title: 'My page',
+ *   description: 'A great page.',
+ *   ogImage: 'https://example.com/og.png',
+ *   canonical: 'https://example.com/my-page',
+ * })
+ * ```
+ */
+export function useSeoMeta(input) {
+    const meta = [];
+    const link = [];
+    if (input.description !== undefined)
+        meta.push({ name: 'description', content: input.description });
+    // Open Graph
+    if (input.ogTitle !== undefined)
+        meta.push({ property: 'og:title', content: input.ogTitle });
+    if (input.ogDescription !== undefined)
+        meta.push({ property: 'og:description', content: input.ogDescription });
+    if (input.ogImage !== undefined)
+        meta.push({ property: 'og:image', content: input.ogImage });
+    if (input.ogUrl !== undefined)
+        meta.push({ property: 'og:url', content: input.ogUrl });
+    if (input.ogType !== undefined)
+        meta.push({ property: 'og:type', content: input.ogType });
+    if (input.ogSiteName !== undefined)
+        meta.push({ property: 'og:site_name', content: input.ogSiteName });
+    // Twitter / X
+    if (input.twitterCard !== undefined)
+        meta.push({ name: 'twitter:card', content: input.twitterCard });
+    if (input.twitterTitle !== undefined)
+        meta.push({ name: 'twitter:title', content: input.twitterTitle });
+    if (input.twitterDescription !== undefined)
+        meta.push({ name: 'twitter:description', content: input.twitterDescription });
+    if (input.twitterImage !== undefined)
+        meta.push({ name: 'twitter:image', content: input.twitterImage });
+    if (input.twitterSite !== undefined)
+        meta.push({ name: 'twitter:site', content: input.twitterSite });
+    // Canonical link
+    if (input.canonical !== undefined)
+        link.push({ rel: 'canonical', href: input.canonical });
+    useHead({
+        title: input.title,
+        meta: meta.length > 0 ? meta : undefined,
+        link: link.length > 0 ? link : undefined,
+    });
+}
+//# sourceMappingURL=use-seo-meta.js.map

package/dist/runtime/composables/use-seo-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-seo-meta.js","sourceRoot":"","sources":["../../../src/runtime/composables/use-seo-meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AA2BvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAmB;IAC5C,MAAM,IAAI,GAAkC,EAAE,CAAA;IAC9C,MAAM,IAAI,GAAkC,EAAE,CAAA;IAE9C,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;IAEnG,aAAa;IACb,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IAC5F,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;IAC9G,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;IAC5F,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;IACtF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IACzF,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAA;IAEtG,cAAc;IACd,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;IACpG,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAA;IACvG,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,KAAK,CAAC,kBAAkB,EAAE,CAAC,CAAA;IACzH,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAA;IACvG,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;IAEpG,iBAAiB;IACjB,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAA;IAEzF,OAAO,CAAC;QACN,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACxC,IAAI,EAAE,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;KACzC,CAAC,CAAA;AACJ,CAAC"}

package/dist/runtime/entry-server-template.d.ts

@@ -11,5 +11,5 @@
  * - useHead() support via beginHeadCollection / endHeadCollection
  * - DSD polyfill injected at end of <body> after client-template merge
  */
-export declare const ENTRY_SERVER_TEMPLATE = "// Server-side entry \u2014 AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nimport { readFileSync, existsSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { AsyncLocalStorage } from 'node:async_hooks'\nimport 'virtual:cer-components'\nimport routes from 'virtual:cer-routes'\nimport layouts from 'virtual:cer-layouts'\nimport plugins from 'virtual:cer-plugins'\nimport apiRoutes from 'virtual:cer-server-api'\nimport { runtimeConfig } from 'virtual:cer-app-config'\nimport { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'\nimport { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'\nimport entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'\nimport { initRouter } from '@jasonshimmy/custom-elements-runtime/router'\nimport { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'\nimport { errorTag } from 'virtual:cer-error'\nimport { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'\n\nregisterBuiltinComponents()\ninitRuntimeConfig(runtimeConfig)\n\n// Pre-load the full HTML entity map so named entities like &mdash; decode\n// correctly during SSR. Without this the bundled runtime falls back to a\n// minimal set (&lt;, &gt;, &amp; \u2026) and re-escapes everything else.\nregisterEntityMap(entitiesJson)\n\n// Run plugins once at server startup so their provide() values are available\n// to useInject() during every SSR/SSG render pass. Stored on globalThis so all\n// dynamically-imported page chunks share the same reference.\nconst _pluginProvides = new Map()\n;(globalThis).__cerPluginProvides = _pluginProvides\nconst _pluginsReady = (async () => {\n  const _bootstrapRouter = initRouter({ routes })\n  for (const plugin of plugins) {\n    if (plugin && typeof plugin.setup === 'function') {\n      await plugin.setup({\n        router: _bootstrapRouter,\n        provide: (key, value) => _pluginProvides.set(key, value),\n        config: {},\n      })\n    }\n  }\n})()\n\n// Async-local storage for request-scoped SSR loader data.\n// Using AsyncLocalStorage ensures concurrent SSR renders (e.g. SSG with\n// concurrency > 1) never see each other's data \u2014 each request's async chain\n// carries its own store value, so usePageData() is always race-condition-free.\nconst _cerDataStore = new AsyncLocalStorage()\n// Expose the store so the usePageData() composable can read it server-side.\n;(globalThis).__CER_DATA_STORE__ = _cerDataStore\n\n// Load the Vite-built client index.html (dist/client/index.html) so every SSR\n// response includes the client-side scripts needed for hydration and routing.\n// The server bundle lives at dist/server/server.js, so ../client resolves correctly.\nconst _clientTemplatePath = join(dirname(fileURLToPath(import.meta.url)), '../client/index.html')\nconst _clientTemplate = existsSync(_clientTemplatePath)\n  ? readFileSync(_clientTemplatePath, 'utf-8')\n  : null\n\n// Merge the SSR rendered body with the Vite client shell so the final page\n// contains both pre-rendered DSD content and the client bundle scripts.\nfunction _mergeWithClientTemplate(ssrHtml, clientTemplate) {\n  const headTag = '<head>', headCloseTag = '</head>'\n  const bodyTag = '<body>', bodyCloseTag = '</body>'\n  const headStart = ssrHtml.indexOf(headTag)\n  const headEnd   = ssrHtml.indexOf(headCloseTag)\n  const bodyStart = ssrHtml.indexOf(bodyTag)\n  const bodyEnd   = ssrHtml.lastIndexOf(bodyCloseTag)\n  const ssrHead = headStart >= 0 && headEnd > headStart\n    ? ssrHtml.slice(headStart + headTag.length, headEnd).trim() : ''\n  const ssrBody = bodyStart >= 0 && bodyEnd > bodyStart\n    ? ssrHtml.slice(bodyStart + bodyTag.length, bodyEnd).trim() : ssrHtml\n  // Hoist only top-level <style id=...> elements (cer-ssr-jit, cer-ssr-global)\n  // from the SSR body into the document <head>. Plain <style> blocks without\n  // an id attribute belong to shadow DOM templates and must stay in place \u2014\n  // hoisting them to <head> breaks shadow DOM style encapsulation (document\n  // styles do not pierce shadow roots), which is the root cause of FOUC.\n  const headParts = ssrHead ? [ssrHead] : []\n  let ssrBodyContent = ssrBody\n  let pos = 0\n  while (pos < ssrBodyContent.length) {\n    const styleOpen  = ssrBodyContent.indexOf('<style id=', pos)\n    if (styleOpen < 0) break\n    const styleClose = ssrBodyContent.indexOf('</style>', styleOpen)\n    if (styleClose < 0) break\n    headParts.push(ssrBodyContent.slice(styleOpen, styleClose + 8))\n    ssrBodyContent = ssrBodyContent.slice(0, styleOpen) + ssrBodyContent.slice(styleClose + 8)\n    pos = styleOpen\n  }\n  ssrBodyContent = ssrBodyContent.trim()\n  // Inject the pre-rendered layout+page as light DOM of the app mount element\n  // so it is visible before JS boots, then the client router takes over.\n  let merged = clientTemplate\n  if (merged.includes('<cer-layout-view></cer-layout-view>')) {\n    merged = merged.replace('<cer-layout-view></cer-layout-view>',\n      '<cer-layout-view>' + ssrBodyContent + '</cer-layout-view>')\n  } else if (merged.includes('<div id=\"app\"></div>')) {\n    merged = merged.replace('<div id=\"app\"></div>',\n      '<div id=\"app\">' + ssrBodyContent + '</div>')\n  }\n  const headAdditions = headParts.filter(Boolean).join('\\n')\n  if (headAdditions) {\n    // If SSR provides a <title>, replace the client template's <title> so the\n    // SSR title wins (client template title is the fallback default).\n    if (headAdditions.includes('<title>')) {\n      merged = merged.replace(/<title>[^<]*<\\/title>/, '')\n    }\n    merged = merged.replace('</head>', headAdditions + '\\n</head>')\n  }\n  return merged\n}\n\n// Per-request async setup: initialize a fresh router, resolve the matched\n// route and layout, pre-load the page module, and call the data loader.\n// Loader data is scoped to the current AsyncLocalStorage context via enterWith()\n// so concurrent renders never share state.\nconst _prepareRequest = async (req) => {\n  await _pluginsReady\n  const router = initRouter({ routes, initialUrl: req.url ?? '/' })\n  const current = router.getCurrent()\n  const { route, params } = router.matchRoute(current.path)\n\n  // Pre-load the page module so we can embed the component tag directly.\n  // This avoids the async router-view (which injects content via script tags\n  // and breaks Declarative Shadow DOM on initial parse).\n  let pageVnode = { tag: 'div', props: {}, children: [] }\n  let head\n  if (route?.load) {\n    try {\n      const mod = await route.load()\n      const pageTag = mod.default\n      if (pageTag) {\n        pageVnode = { tag: pageTag, props: { attrs: { ...params } }, children: [] }\n      }\n      if (typeof mod.loader === 'function') {\n        const query = current.query ?? {}\n        const data = await mod.loader({ params, query, req })\n        if (data !== undefined && data !== null) {\n          // enterWith() scopes the value to the current async context so\n          // concurrent renders (SSG concurrency > 1) never share data.\n          _cerDataStore.enterWith(data)\n          head = `<script>window.__CER_DATA__ = ${JSON.stringify(data)}</script>`\n        }\n      }\n    } catch (err) {\n      // Loader threw \u2014 render the error page server-side if app/error.ts exists.\n      const status = (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number')\n        ? err.status : 500\n      const message = (err instanceof Error) ? err.message : String(err)\n      if (!errorTag) {\n        console.error('[cer-app] Loader error (no app/error.ts defined):', err)\n      }\n      const errVnode = errorTag\n        ? { tag: errorTag, props: { attrs: { error: message, status: String(status) } }, children: [] }\n        : { tag: 'div', props: {}, children: [] }\n      return { vnode: errVnode, router, head: undefined, status }\n    }\n  }\n\n  // Resolve layout chain: nested layouts (meta.layoutChain) or single layout.\n  const chain = route?.meta?.layoutChain\n    ? route.meta.layoutChain\n    : [route?.meta?.layout ?? 'default']\n\n  // Wrap pageVnode in the layout chain from innermost to outermost.\n  let vnode = pageVnode\n  for (let i = chain.length - 1; i >= 0; i--) {\n    const tag = layouts[chain[i]]\n    if (tag) vnode = { tag, props: {}, children: [vnode] }\n  }\n\n  return { vnode, router, head, status: null }\n}\n\nexport const handler = async (req, res) => {\n  await _cerDataStore.run(null, async () => {\n    const { vnode, router, head, status } = await _prepareRequest(req)\n    if (status != null) res.statusCode = status\n\n    // Begin collecting useHead() calls made during the synchronous render pass.\n    // IMPORTANT: the stream's start() function runs synchronously on construction,\n    // so ALL useHead() calls happen before the stream object is returned. We must\n    // call endHeadCollection() immediately \u2014 before any await \u2014 to avoid a race\n    // window where a concurrent request (e.g. SSG concurrency > 1) resets the\n    // shared globalThis collector while this handler is suspended at an await.\n    beginHeadCollection()\n\n    // dsdPolyfill: false \u2014 we inject the polyfill manually after merging so it\n    // lands at the end of <body>, not inside <cer-layout-view> light DOM where\n    // scripts may not execute.\n    // The first chunk from the stream is the full synchronous render. Subsequent\n    // chunks are async component swap scripts streamed as they resolve.\n    const stream = renderToStreamWithJITCSSDSD(vnode, { dsdPolyfill: false, router })\n\n    // Collect head tags synchronously \u2014 all useHead() calls have already fired\n    // inside the stream constructor's start() before it returned.\n    const headTags = serializeHeadTags(endHeadCollection())\n\n    const reader = stream.getReader()\n\n    // Read the first (synchronous) chunk.\n    const { value: firstChunk = '' } = await reader.read()\n\n    // Merge loader data script + useHead() tags into the document head.\n    const headContent = [head, headTags].filter(Boolean).join('\\n')\n\n    // Wrap the rendered body in a full HTML document and inject the head additions\n    // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.\n    const ssrHtml = `<!DOCTYPE html><html><head>${headContent}</head><body>${firstChunk}</body></html>`\n\n    const merged = _clientTemplate\n      ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)\n      : ssrHtml\n\n    // Split at </body> so async swap scripts and the DSD polyfill can be streamed\n    // in before the document is closed.\n    const bodyCloseIdx = merged.lastIndexOf('</body>')\n    const beforeBodyClose = bodyCloseIdx >= 0 ? merged.slice(0, bodyCloseIdx) : merged\n    const fromBodyClose  = bodyCloseIdx >= 0 ? merged.slice(bodyCloseIdx) : ''\n\n    res.setHeader('Content-Type', 'text/html; charset=utf-8')\n    res.setHeader('Transfer-Encoding', 'chunked')\n    res.write(beforeBodyClose)\n\n    // Stream async component swap scripts through as-is.\n    while (true) {\n      const { value, done } = await reader.read()\n      if (done) break\n      res.write(value)\n    }\n\n    // Inject DSD polyfill immediately before </body>, then close the document.\n    res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)\n  })\n}\n\n// ISR-wrapped handler for production integrations (Express, Hono, Fastify).\n// Routes with meta.ssg.revalidate are served stale-while-revalidate.\nexport const isrHandler = createIsrHandler(routes, handler)\n\nexport { apiRoutes, plugins, layouts, routes }\nexport default handler\n";
+export declare const ENTRY_SERVER_TEMPLATE = "// Server-side entry \u2014 AUTO-GENERATED by @jasonshimmy/vite-plugin-cer-app\nimport { readFileSync, existsSync } from 'node:fs'\nimport { dirname, join } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { AsyncLocalStorage } from 'node:async_hooks'\nimport 'virtual:cer-components'\nimport routes from 'virtual:cer-routes'\nimport layouts from 'virtual:cer-layouts'\nimport plugins from 'virtual:cer-plugins'\nimport apiRoutes from 'virtual:cer-server-api'\nimport { runtimeConfig, _runtimePrivateDefaults } from 'virtual:cer-app-config'\nimport { registerBuiltinComponents } from '@jasonshimmy/custom-elements-runtime'\nimport { registerEntityMap, renderToStreamWithJITCSSDSD, DSD_POLYFILL_SCRIPT } from '@jasonshimmy/custom-elements-runtime/ssr'\nimport entitiesJson from '@jasonshimmy/custom-elements-runtime/entities.json'\nimport { initRouter } from '@jasonshimmy/custom-elements-runtime/router'\nimport { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig, resolvePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'\nimport { errorTag } from 'virtual:cer-error'\nimport { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'\n\nregisterBuiltinComponents()\n\n// Resolve private config from environment variables at server startup.\n// Each key declared in runtimeConfig.private is looked up in process.env,\n// first as-is, then as ALL_CAPS. The declared default is used as fallback.\ninitRuntimeConfig({ ...runtimeConfig, private: resolvePrivateConfig(_runtimePrivateDefaults ?? {}) })\n\n// Pre-load the full HTML entity map so named entities like &mdash; decode\n// correctly during SSR. Without this the bundled runtime falls back to a\n// minimal set (&lt;, &gt;, &amp; \u2026) and re-escapes everything else.\nregisterEntityMap(entitiesJson)\n\n// Run plugins once at server startup so their provide() values are available\n// to useInject() during every SSR/SSG render pass. Stored on globalThis so all\n// dynamically-imported page chunks share the same reference.\nconst _pluginProvides = new Map()\n;(globalThis).__cerPluginProvides = _pluginProvides\nconst _pluginsReady = (async () => {\n  const _bootstrapRouter = initRouter({ routes })\n  for (const plugin of plugins) {\n    if (plugin && typeof plugin.setup === 'function') {\n      await plugin.setup({\n        router: _bootstrapRouter,\n        provide: (key, value) => _pluginProvides.set(key, value),\n        config: {},\n      })\n    }\n  }\n})()\n\n// Async-local storage for request-scoped SSR loader data.\n// Using AsyncLocalStorage ensures concurrent SSR renders (e.g. SSG with\n// concurrency > 1) never see each other's data \u2014 each request's async chain\n// carries its own store value, so usePageData() is always race-condition-free.\nconst _cerDataStore = new AsyncLocalStorage()\n// Expose the store so the usePageData() composable can read it server-side.\n;(globalThis).__CER_DATA_STORE__ = _cerDataStore\n\n// Async-local storage for request-scoped req/res access.\n// Allows isomorphic composables (e.g. useCookie) to read/write HTTP headers\n// without prop-drilling the request context through the component tree.\nconst _cerReqStore = new AsyncLocalStorage()\n;(globalThis).__CER_REQ_STORE__ = _cerReqStore\n\n// Load the Vite-built client index.html (dist/client/index.html) so every SSR\n// response includes the client-side scripts needed for hydration and routing.\n// The server bundle lives at dist/server/server.js, so ../client resolves correctly.\nconst _clientTemplatePath = join(dirname(fileURLToPath(import.meta.url)), '../client/index.html')\nconst _clientTemplate = existsSync(_clientTemplatePath)\n  ? readFileSync(_clientTemplatePath, 'utf-8')\n  : null\n\n// Merge the SSR rendered body with the Vite client shell so the final page\n// contains both pre-rendered DSD content and the client bundle scripts.\nfunction _mergeWithClientTemplate(ssrHtml, clientTemplate) {\n  const headTag = '<head>', headCloseTag = '</head>'\n  const bodyTag = '<body>', bodyCloseTag = '</body>'\n  const headStart = ssrHtml.indexOf(headTag)\n  const headEnd   = ssrHtml.indexOf(headCloseTag)\n  const bodyStart = ssrHtml.indexOf(bodyTag)\n  const bodyEnd   = ssrHtml.lastIndexOf(bodyCloseTag)\n  const ssrHead = headStart >= 0 && headEnd > headStart\n    ? ssrHtml.slice(headStart + headTag.length, headEnd).trim() : ''\n  const ssrBody = bodyStart >= 0 && bodyEnd > bodyStart\n    ? ssrHtml.slice(bodyStart + bodyTag.length, bodyEnd).trim() : ssrHtml\n  // Hoist only top-level <style id=...> elements (cer-ssr-jit, cer-ssr-global)\n  // from the SSR body into the document <head>. Plain <style> blocks without\n  // an id attribute belong to shadow DOM templates and must stay in place \u2014\n  // hoisting them to <head> breaks shadow DOM style encapsulation (document\n  // styles do not pierce shadow roots), which is the root cause of FOUC.\n  const headParts = ssrHead ? [ssrHead] : []\n  let ssrBodyContent = ssrBody\n  let pos = 0\n  while (pos < ssrBodyContent.length) {\n    const styleOpen  = ssrBodyContent.indexOf('<style id=', pos)\n    if (styleOpen < 0) break\n    const styleClose = ssrBodyContent.indexOf('</style>', styleOpen)\n    if (styleClose < 0) break\n    headParts.push(ssrBodyContent.slice(styleOpen, styleClose + 8))\n    ssrBodyContent = ssrBodyContent.slice(0, styleOpen) + ssrBodyContent.slice(styleClose + 8)\n    pos = styleOpen\n  }\n  ssrBodyContent = ssrBodyContent.trim()\n  // Inject the pre-rendered layout+page as light DOM of the app mount element\n  // so it is visible before JS boots, then the client router takes over.\n  let merged = clientTemplate\n  if (merged.includes('<cer-layout-view></cer-layout-view>')) {\n    merged = merged.replace('<cer-layout-view></cer-layout-view>',\n      '<cer-layout-view>' + ssrBodyContent + '</cer-layout-view>')\n  } else if (merged.includes('<div id=\"app\"></div>')) {\n    merged = merged.replace('<div id=\"app\"></div>',\n      '<div id=\"app\">' + ssrBodyContent + '</div>')\n  }\n  const headAdditions = headParts.filter(Boolean).join('\\n')\n  if (headAdditions) {\n    // If SSR provides a <title>, replace the client template's <title> so the\n    // SSR title wins (client template title is the fallback default).\n    if (headAdditions.includes('<title>')) {\n      merged = merged.replace(/<title>[^<]*<\\/title>/, '')\n    }\n    merged = merged.replace('</head>', headAdditions + '\\n</head>')\n  }\n  return merged\n}\n\n// Per-request async setup: initialize a fresh router, resolve the matched\n// route and layout, pre-load the page module, and call the data loader.\n// Loader data is scoped to the current AsyncLocalStorage context via enterWith()\n// so concurrent renders never share state.\nconst _prepareRequest = async (req) => {\n  await _pluginsReady\n  const router = initRouter({ routes, initialUrl: req.url ?? '/' })\n  const current = router.getCurrent()\n  const { route, params } = router.matchRoute(current.path)\n\n  // Pre-load the page module so we can embed the component tag directly.\n  // This avoids the async router-view (which injects content via script tags\n  // and breaks Declarative Shadow DOM on initial parse).\n  let pageVnode = { tag: 'div', props: {}, children: [] }\n  let head\n  if (route?.load) {\n    try {\n      const mod = await route.load()\n      const pageTag = mod.default\n      if (pageTag) {\n        pageVnode = { tag: pageTag, props: { attrs: { ...params } }, children: [] }\n      }\n      if (typeof mod.loader === 'function') {\n        const query = current.query ?? {}\n        const data = await mod.loader({ params, query, req })\n        if (data !== undefined && data !== null) {\n          // enterWith() scopes the value to the current async context so\n          // concurrent renders (SSG concurrency > 1) never share data.\n          _cerDataStore.enterWith(data)\n          head = `<script>window.__CER_DATA__ = ${JSON.stringify(data)}</script>`\n        }\n      }\n    } catch (err) {\n      // Loader threw \u2014 render the error page server-side if app/error.ts exists.\n      const status = (err && typeof err === 'object' && 'status' in err && typeof err.status === 'number')\n        ? err.status : 500\n      const message = (err instanceof Error) ? err.message : String(err)\n      if (!errorTag) {\n        console.error('[cer-app] Loader error (no app/error.ts defined):', err)\n      }\n      const errVnode = errorTag\n        ? { tag: errorTag, props: { attrs: { error: message, status: String(status) } }, children: [] }\n        : { tag: 'div', props: {}, children: [] }\n      return { vnode: errVnode, router, head: undefined, status }\n    }\n  }\n\n  // Resolve layout chain: nested layouts (meta.layoutChain) or single layout.\n  const chain = route?.meta?.layoutChain\n    ? route.meta.layoutChain\n    : [route?.meta?.layout ?? 'default']\n\n  // Wrap pageVnode in the layout chain from innermost to outermost.\n  let vnode = pageVnode\n  for (let i = chain.length - 1; i >= 0; i--) {\n    const tag = layouts[chain[i]]\n    if (tag) vnode = { tag, props: {}, children: [vnode] }\n  }\n\n  return { vnode, router, head, status: null }\n}\n\nexport const handler = async (req, res) => {\n  await _cerReqStore.run({ req, res }, async () => {\n  await _cerDataStore.run(null, async () => {\n    const { vnode, router, head, status } = await _prepareRequest(req)\n    if (status != null) res.statusCode = status\n\n    // Begin collecting useHead() calls made during the synchronous render pass.\n    // IMPORTANT: the stream's start() function runs synchronously on construction,\n    // so ALL useHead() calls happen before the stream object is returned. We must\n    // call endHeadCollection() immediately \u2014 before any await \u2014 to avoid a race\n    // window where a concurrent request (e.g. SSG concurrency > 1) resets the\n    // shared globalThis collector while this handler is suspended at an await.\n    beginHeadCollection()\n\n    // dsdPolyfill: false \u2014 we inject the polyfill manually after merging so it\n    // lands at the end of <body>, not inside <cer-layout-view> light DOM where\n    // scripts may not execute.\n    // The first chunk from the stream is the full synchronous render. Subsequent\n    // chunks are async component swap scripts streamed as they resolve.\n    const stream = renderToStreamWithJITCSSDSD(vnode, { dsdPolyfill: false, router })\n\n    // Collect head tags synchronously \u2014 all useHead() calls have already fired\n    // inside the stream constructor's start() before it returned.\n    const headTags = serializeHeadTags(endHeadCollection())\n\n    const reader = stream.getReader()\n\n    // Read the first (synchronous) chunk.\n    const { value: firstChunk = '' } = await reader.read()\n\n    // Merge loader data script + useHead() tags into the document head.\n    const headContent = [head, headTags].filter(Boolean).join('\\n')\n\n    // Wrap the rendered body in a full HTML document and inject the head additions\n    // (loader data script, useHead() tags, JIT styles). No polyfill in body yet.\n    const ssrHtml = `<!DOCTYPE html><html><head>${headContent}</head><body>${firstChunk}</body></html>`\n\n    const merged = _clientTemplate\n      ? _mergeWithClientTemplate(ssrHtml, _clientTemplate)\n      : ssrHtml\n\n    // Split at </body> so async swap scripts and the DSD polyfill can be streamed\n    // in before the document is closed.\n    const bodyCloseIdx = merged.lastIndexOf('</body>')\n    const beforeBodyClose = bodyCloseIdx >= 0 ? merged.slice(0, bodyCloseIdx) : merged\n    const fromBodyClose  = bodyCloseIdx >= 0 ? merged.slice(bodyCloseIdx) : ''\n\n    res.setHeader('Content-Type', 'text/html; charset=utf-8')\n    res.setHeader('Transfer-Encoding', 'chunked')\n    res.write(beforeBodyClose)\n\n    // Stream async component swap scripts through as-is.\n    while (true) {\n      const { value, done } = await reader.read()\n      if (done) break\n      res.write(value)\n    }\n\n    // Inject DSD polyfill immediately before </body>, then close the document.\n    res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)\n  })\n  })\n}\n\n// ISR-wrapped handler for production integrations (Express, Hono, Fastify).\n// Routes with meta.ssg.revalidate are served stale-while-revalidate.\nexport const isrHandler = createIsrHandler(routes, handler)\n\nexport { apiRoutes, plugins, layouts, routes }\nexport default handler\n";
 //# sourceMappingURL=entry-server-template.d.ts.map

package/dist/runtime/entry-server-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entry-server-template.d.ts","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,6/WAoPjC,CAAA"}
+{"version":3,"file":"entry-server-template.d.ts","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,osYAgQjC,CAAA"}

package/dist/runtime/entry-server-template.js

@@ -21,17 +21,21 @@ import routes from 'virtual:cer-routes'
 import layouts from 'virtual:cer-layouts'
 import plugins from 'virtual:cer-plugins'
 import apiRoutes from 'virtual:cer-server-api'
-import { runtimeConfig } from 'virtual:cer-app-config'
+import { runtimeConfig, _runtimePrivateDefaults } 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'
 import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
-import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
+import { beginHeadCollection, endHeadCollection, serializeHeadTags, initRuntimeConfig, resolvePrivateConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 import { errorTag } from 'virtual:cer-error'
 import { createIsrHandler } from '@jasonshimmy/vite-plugin-cer-app/isr'
 
 registerBuiltinComponents()
-initRuntimeConfig(runtimeConfig)
+
+// Resolve private config from environment variables at server startup.
+// Each key declared in runtimeConfig.private is looked up in process.env,
+// first as-is, then as ALL_CAPS. The declared default is used as fallback.
+initRuntimeConfig({ ...runtimeConfig, private: resolvePrivateConfig(_runtimePrivateDefaults ?? {}) })
 
 // Pre-load the full HTML entity map so named entities like — decode
 // correctly during SSR. Without this the bundled runtime falls back to a
@@ -64,6 +68,12 @@ const _cerDataStore = new AsyncLocalStorage()
 // Expose the store so the usePageData() composable can read it server-side.
 ;(globalThis).__CER_DATA_STORE__ = _cerDataStore
 
+// Async-local storage for request-scoped req/res access.
+// Allows isomorphic composables (e.g. useCookie) to read/write HTTP headers
+// without prop-drilling the request context through the component tree.
+const _cerReqStore = new AsyncLocalStorage()
+;(globalThis).__CER_REQ_STORE__ = _cerReqStore
+
 // Load the Vite-built client index.html (dist/client/index.html) so every SSR
 // response includes the client-side scripts needed for hydration and routing.
 // The server bundle lives at dist/server/server.js, so ../client resolves correctly.
@@ -188,6 +198,7 @@ const _prepareRequest = async (req) => {
 }
 
 export const handler = async (req, res) => {
+  await _cerReqStore.run({ req, res }, async () => {
   await _cerDataStore.run(null, async () => {
     const { vnode, router, head, status } = await _prepareRequest(req)
     if (status != null) res.statusCode = status
@@ -247,6 +258,7 @@ export const handler = async (req, res) => {
     // Inject DSD polyfill immediately before </body>, then close the document.
     res.end(DSD_POLYFILL_SCRIPT + fromBodyClose)
   })
+  })
 }
 
 // ISR-wrapped handler for production integrations (Express, Hono, Fastify).

package/dist/runtime/entry-server-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry-server-template.js","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoPpC,CAAA"}
+{"version":3,"file":"entry-server-template.js","sourceRoot":"","sources":["../../src/runtime/entry-server-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgQpC,CAAA"}

package/dist/types/config.d.ts

@@ -17,6 +17,9 @@ export interface AutoImportsConfig {
 export interface RuntimePublicConfig {
     [key: string]: unknown;
 }
+export interface RuntimePrivateConfig {
+    [key: string]: string;
+}
 export interface RuntimeConfig {
     /**
      * Public runtime config — available on both server and client via
@@ -31,6 +34,17 @@ export interface RuntimeConfig {
      * }
      */
     public?: RuntimePublicConfig;
+    /**
+     * Server-only secrets — never serialized into the client bundle.
+     * Declare keys with empty-string defaults here; at server startup each key
+     * is resolved from `process.env[KEY]` (case-insensitive, ALL_CAPS preferred).
+     *
+     * @example
+     * runtimeConfig: {
+     *   private: { dbUrl: '', secretKey: '' },
+     * }
+     */
+    private?: RuntimePrivateConfig;
 }
 export interface CerAppConfig {
     mode?: 'spa' | 'ssr' | 'ssg';

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

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAA;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,CAAC,CAAA;IACxD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAE/D"}

package/dist/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAwDA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAuEA,MAAM,UAAU,YAAY,CAAC,MAAoB;IAC/C,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/types/index.d.ts

@@ -1,7 +1,7 @@
-export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig } from './config.js';
+export type { CerAppConfig, SsgConfig, JitCssConfig, AutoImportsConfig, RuntimeConfig, RuntimePublicConfig, RuntimePrivateConfig } 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';
 export type { AppContext, AppPlugin } from './plugin.js';
-export type { NextFunction, RouteMiddleware, ServerMiddleware } from './middleware.js';
+export type { MiddlewareFn, GuardResult, ServerMiddleware } from './middleware.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC/H,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACrJ,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACzH,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC/E,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/types/middleware.d.ts

@@ -1,6 +1,12 @@
 import type { RouteState } from '@jasonshimmy/custom-elements-runtime/router';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-export type NextFunction = (redirectTo?: string) => void;
-export type RouteMiddleware = (to: RouteState, from: RouteState | null, next: NextFunction) => void | Promise<void>;
+/**
+ * Return value from a route middleware function:
+ * - `true`   — allow navigation
+ * - `false`  — block navigation
+ * - `string` — redirect to that path
+ */
+export type GuardResult = boolean | string | Promise<boolean | string>;
+export type MiddlewareFn = (to: RouteState, from: RouteState | null) => GuardResult;
 export type ServerMiddleware = (req: IncomingMessage, res: ServerResponse, next: () => void) => void | Promise<void>;
 //# sourceMappingURL=middleware.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAA;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE,MAAM,MAAM,YAAY,GAAG,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;AAExD,MAAM,MAAM,eAAe,GAAG,CAC5B,EAAE,EAAE,UAAU,EACd,IAAI,EAAE,UAAU,GAAG,IAAI,EACvB,IAAI,EAAE,YAAY,KACf,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/types/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6CAA6C,CAAA;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAA;AAEtE,MAAM,MAAM,YAAY,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,KAAK,WAAW,CAAA;AAEnF,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,IAAI,KACb,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA"}

package/docs/cli.md

@@ -110,6 +110,11 @@ cer-app preview --port 8080
 - Static assets from `dist/client/` are served first; HTML requests fall through to the SSR handler
 - Otherwise, starts a static file server with SPA fallback (serves `index.html` for unknown paths)
 - Returns 404 for paths not found in `dist/` (static mode only)
+- **Path traversal protection:** all file requests are validated against the `dist/` root — requests attempting to escape it (e.g. `GET /../../../../etc/passwd`) receive a `400` response
+- **Security headers:** every response includes `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, and `Referrer-Policy: strict-origin-when-cross-origin`
+- **Smart Cache-Control:** Vite content-hashes assets placed in `/assets/` — these are served with `Cache-Control: public, max-age=31536000, immutable`. All other files (HTML, etc.) use `Cache-Control: no-cache` so browsers always revalidate
+- **Graceful shutdown:** on `SIGTERM` or `SIGINT`, the server stops accepting new connections and waits for in-flight requests to finish before exiting. A 10-second timeout triggers a forced exit if connections do not drain
+- **Request timeouts:** `headersTimeout` (10 s) aborts connections that stall while sending headers; `requestTimeout` (30 s) limits the total time allowed per request/response cycle, protecting against slow-client attacks
 
 ---
 

package/docs/composables.md

@@ -144,7 +144,9 @@ import { useInject } from '@jasonshimmy/vite-plugin-cer-app/composables'
 
 ### `useRuntimeConfig()`
 
-Returns the `public` runtime configuration object set in `cer.config.ts` under `runtimeConfig.public`. Available in all rendering modes (SPA, SSR, SSG) and on both server and client.
+Returns the runtime configuration set in `cer.config.ts`. Returns `{ public, private? }`:
+- `public` — available everywhere (server and client)
+- `private` — server-only secrets resolved from `process.env` at startup; `undefined` on the client
 
 ```ts
 // cer.config.ts
@@ -152,28 +154,184 @@ export default defineConfig({
   runtimeConfig: {
     public: {
       apiBase: process.env.VITE_API_BASE ?? '/api',
-      featureFlags: { darkMode: true },
+    },
+    private: {
+      dbUrl: '',       // resolved from process.env.DB_URL at server startup
     },
   },
 })
 ```
 
 ```ts
-// app/pages/index.ts — auto-imported, no import statement needed
+// app/pages/index.ts — public config, works on client and server
 component('page-index', () => {
   const { public: cfg } = useRuntimeConfig()
-  // cfg.apiBase → '/api'
-
   return html`<p>API base: ${cfg.apiBase}</p>`
 })
 ```
 
-The config is initialized at app boot (both client and server) by calling `initRuntimeConfig(runtimeConfig)` with the value from `virtual:cer-app-config`. You only need `useRuntimeConfig()` to read it.
+```ts
+// app/pages/data.ts — private config, server-only (loader)
+export const loader = async () => {
+  const { private: priv } = useRuntimeConfig()
+  const rows = await db.query(priv!.dbUrl)
+  return { rows }
+}
+```
 
-**Only use `runtimeConfig.public` for values safe to expose to the browser.** Secrets, tokens, and private keys must stay in server-only code (loaders, API handlers, server middleware).
+**Only use `runtimeConfig.public` for values safe to expose to the browser.** Use `runtimeConfig.private` for secrets — they are never sent to the client.
+
+Keys declared in `runtimeConfig.private` with an empty-string default are treated as **required** secrets. If the corresponding environment variable is not set at server startup, a warning is logged:
+
+```
+[cer-app] runtimeConfig.private: "dbUrl" is an empty string — set DB_URL in the environment to provide a value.
+```
+
+If the default is a non-empty string it is used as a genuine fallback — no warning is emitted.
 
 If you need it outside auto-imported directories:
 
 ```ts
 import { useRuntimeConfig } from '@jasonshimmy/vite-plugin-cer-app/composables'
 ```
+
+---
+
+### `useSeoMeta(input)`
+
+Thin wrapper over `useHead()` for the most common SEO tags — Open Graph, Twitter Card, meta description, and canonical URL. Works in SPA, SSR, and SSG modes.
+
+```ts
+// app/pages/about.ts
+component('page-about', () => {
+  useSeoMeta({
+    title: 'About Us',
+    description: 'Learn more about our team.',
+    ogTitle: 'About Us — My Site',
+    ogDescription: 'Learn more about our team.',
+    ogImage: 'https://example.com/og/about.png',
+    ogUrl: 'https://example.com/about',
+    ogType: 'website',
+    ogSiteName: 'My Site',
+    twitterCard: 'summary_large_image',
+    twitterSite: '@mysite',
+    canonical: 'https://example.com/about',
+  })
+  return html`<h1>About Us</h1>`
+})
+```
+
+Only properties you set are emitted — passing `undefined` (or omitting a property entirely) skips that tag.
+
+#### `SeoMetaInput` fields
+
+| Field | Tag emitted |
+|---|---|
+| `title` | `<title>` |
+| `description` | `<meta name="description">` |
+| `ogTitle` | `<meta property="og:title">` |
+| `ogDescription` | `<meta property="og:description">` |
+| `ogImage` | `<meta property="og:image">` |
+| `ogUrl` | `<meta property="og:url">` |
+| `ogType` | `<meta property="og:type">` |
+| `ogSiteName` | `<meta property="og:site_name">` |
+| `twitterCard` | `<meta name="twitter:card">` |
+| `twitterTitle` | `<meta name="twitter:title">` |
+| `twitterDescription` | `<meta name="twitter:description">` |
+| `twitterImage` | `<meta name="twitter:image">` |
+| `twitterSite` | `<meta name="twitter:site">` |
+| `canonical` | `<link rel="canonical">` |
+
+If you need it outside auto-imported directories:
+
+```ts
+import { useSeoMeta } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```
+
+TypeScript types:
+
+```ts
+import type { SeoMetaInput } from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
+### `useCookie(name, options?)`
+
+Isomorphic cookie composable. Reads and writes cookies transparently on both server and client:
+
+- **Server (SSR/SSG):** reads `req.headers.cookie`; writes `Set-Cookie` response headers via `res.setHeader`.
+- **Client:** reads and writes `document.cookie`.
+
+```ts
+// app/pages/profile.ts
+component('page-profile', () => {
+  const session = useCookie('session')
+
+  // Read
+  console.log(session.value)   // 'abc123' | undefined
+
+  // Write
+  session.set('abc123', { httpOnly: true, sameSite: 'Strict' })
+
+  // Remove
+  session.remove()
+
+  return html`<p>Session: ${session.value ?? 'none'}</p>`
+})
+```
+
+#### `CookieRef`
+
+| Member | Type | Description |
+|---|---|---|
+| `value` | `string \| undefined` | Current cookie value (read at call time) |
+| `set(value, options?)` | `void` | Write the cookie |
+| `remove(options?)` | `void` | Delete the cookie (sets `Max-Age=0`) |
+
+#### `CookieOptions`
+
+| Option | Type | Description |
+|---|---|---|
+| `path` | `string` | Cookie path (defaults to `/` when setting/removing) |
+| `domain` | `string` | Cookie domain |
+| `maxAge` | `number` | Max age in seconds |
+| `expires` | `Date` | Expiry date |
+| `httpOnly` | `boolean` | Set `HttpOnly` flag |
+| `secure` | `boolean` | Set `Secure` flag |
+| `sameSite` | `'Strict' \| 'Lax' \| 'None'` | `SameSite` attribute |
+
+Default options can be passed as the second argument to `useCookie` — they are merged with options passed to `set()`/`remove()`:
+
+```ts
+const auth = useCookie('auth', { httpOnly: true, secure: true, sameSite: 'Strict' })
+auth.set('tok')   // inherits httpOnly, secure, sameSite automatically
+```
+
+If you need it outside auto-imported directories:
+
+```ts
+import { useCookie } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```
+
+TypeScript types:
+
+```ts
+import type { CookieOptions, CookieRef } from '@jasonshimmy/vite-plugin-cer-app/types'
+```
+
+---
+
+### `defineMiddleware(fn)`
+
+Identity helper that gives TypeScript the correct `MiddlewareFn` type. Auto-imported — no import needed in `app/middleware/` files.
+
+```ts
+// app/middleware/auth.ts
+export default defineMiddleware(async (to, from) => {
+  const isLoggedIn = !!localStorage.getItem('token')
+  return isLoggedIn ? true : '/login'
+})
+```
+
+See [Middleware](./middleware.md) for full documentation.