@jay-framework/production-server 0.25.0 → 0.25.2

package/dist/index.d.ts

@@ -1,9 +1,60 @@
-import { R as RouteManifest, a as RouteEntry } from './serve-index-C2Tfaz1E.js';
-export { A as ActionEntry, b as ArtifactStore, B as BuildMetadata, c as BuildOptions, C as CacheEntry, F as FilesystemArtifactStore, I as InstanceEntry, M as MatchResult, P as PageModule, d as PluginEntry, e as PreImportedPlugin, f as RouteSegment, S as ServerElementModule, g as fetchActionRequest, h as fetchPageRequest, i as fetchStaticFile, j as initializeServices, k as initializeServicesFromModules, l as isActionRequest, m as loadPagePartsFromConfig, n as matchRequest, r as registerActionsFromManifest, o as registerActionsFromModules } from './serve-index-C2Tfaz1E.js';
+import { R as RouteManifest, a as RouteEntry, A as ArtifactStore } from './serve-index-C28bP6tW.js';
+export { b as ActionEntry, B as BuildMetadata, c as BuildOptions, C as CacheEntry, E as ErrorPageEntry, F as FilesystemArtifactStore, I as InstanceEntry, M as MatchResult, P as PageModule, d as PluginEntry, e as PreImportedPlugin, f as RouteSegment, S as ServerElementModule, g as fetchActionRequest, h as fetchPageRequest, i as fetchStaticFile, j as initializeServices, k as initializeServicesFromModules, l as isActionRequest, m as loadPagePartsFromConfig, n as matchRequest, r as registerActionsFromManifest, o as registerActionsFromModules } from './serve-index-C28bP6tW.js';
+import { HeadTag } from '@jay-framework/fullstack-component';
+import { ErrorInfo } from '@jay-framework/stack-server-runtime';
 import '@jay-framework/ssr-runtime';
-import '@jay-framework/stack-server-runtime';
 
 declare function generateSitemap(manifest: RouteManifest, baseUrl: string, outputPath: string): Promise<number>;
+declare function buildUrlFromManifest(pattern: string, params: Record<string, string>): string;
+
+/**
+ * Site-level identity config that drives Organization + WebSite JSON-LD (DL#213).
+ * Mirrors the `site` block of `.jay` config.
+ */
+interface SiteJsonLdConfig {
+    name?: string;
+    baseUrl?: string;
+    logo?: string;
+    description?: string;
+    sameAs?: string[];
+}
+/**
+ * Build the site-level `Organization` + `WebSite` JSON-LD head tags from `.jay` `site` config.
+ *
+ * Returns `[]` when `site.name` is absent — there is no identity to describe, and a validation
+ * warning (DL#213 Part 5) nudges the author. Emitted once at build (next to the sitemap) and
+ * carried on the RouteManifest so every served page gets identical site identity.
+ */
+declare function generateSiteJsonLd(site: SiteJsonLdConfig | undefined): HeadTag[];
+
+/**
+ * Site identity used for the llms.txt header (DL#214). Mirrors the `.jay` `site` config subset
+ * that `generateSiteJsonLd` consumes.
+ */
+interface LlmsTxtSiteConfig {
+    name?: string;
+    description?: string;
+    baseUrl?: string;
+}
+/**
+ * Generate an `llms.txt` (llmstxt.org) index from the build manifest + site config (DL#214).
+ * A curated, markdown map of the site for LLMs: site H1 + summary, then per-page links with
+ * descriptions, grouped into `##` sections by top-level path segment.
+ *
+ * Returns the number of page links written. Requires `site.name` (the H1); callers skip the
+ * emission when it is absent (parallel to the sitemap requiring `baseUrl`).
+ */
+declare function generateLlmsTxt(manifest: RouteManifest, site: LlmsTxtSiteConfig, backendDir: string, outputPath: string): Promise<number>;
+
+/**
+ * Generate a default `robots.txt` (DL#214) — **only when the author has not provided one**
+ * (mirrors the sitemap "don't clobber a static file" convention). Returns true if written,
+ * false if an author file already exists at `outputPath`.
+ *
+ * The `Sitemap:` line is emitted only when `baseUrl` is set; without it, the sitemap URL is
+ * unknown (and the existing `site.baseUrl` validation warning already fires).
+ */
+declare function generateRobotsTxtIfAbsent(outputPath: string, baseUrl: string | undefined): Promise<boolean>;
 
 interface MainServerOptions {
     buildRoot: string;
@@ -50,6 +101,12 @@ interface RebuildOptions {
     minify?: boolean;
     /** Site base URL for sitemap regeneration (e.g. "https://example.com"). */
     siteBaseUrl?: string;
+    /** Full site identity for llms.txt regeneration (DL#214). `name` drives the llms.txt H1. */
+    site?: {
+        name?: string;
+        description?: string;
+        baseUrl?: string;
+    };
 }
 interface RebuildResult {
     affected: number;
@@ -76,4 +133,14 @@ declare function rebuildContract(options: {
 }): Promise<RebuildResult>;
 declare function cleanupOrphanedFiles(buildRoot: string, version: string): Promise<number>;
 
-export { type MainServerOptions, type RebuildOptions, type RebuildResult, type RebuildTarget, type RendererServerOptions, RouteEntry, RouteManifest, cleanupOrphanedFiles, generateSitemap, rebuild, rebuildContract, resolveContractToRoutes, startMainServer, startRendererServer };
+/**
+ * Render a designed error page for a 4xx/5xx outcome (DL#218). Resolves the page by status
+ * (exact → family) from `manifest.errorPages`; when none matches — or when rendering throws —
+ * falls back to the built-in plain-text response. The response always carries `info.status`.
+ *
+ * Error pages are a pass-through: no fast render runs; the framework injects the `error` ViewState
+ * (`buildErrorViewState`). Interactivity (hydration) still works via the compiled client bundle.
+ */
+declare function renderErrorPage(manifest: RouteManifest, artifacts: ArtifactStore, staticBaseUrl: string, info: ErrorInfo): Promise<Response>;
+
+export { ArtifactStore, type LlmsTxtSiteConfig, type MainServerOptions, type RebuildOptions, type RebuildResult, type RebuildTarget, type RendererServerOptions, RouteEntry, RouteManifest, type SiteJsonLdConfig, buildUrlFromManifest, cleanupOrphanedFiles, generateLlmsTxt, generateRobotsTxtIfAbsent, generateSiteJsonLd, generateSitemap, rebuild, rebuildContract, renderErrorPage, resolveContractToRoutes, startMainServer, startRendererServer };

package/dist/index.js

@@ -1,11 +1,11 @@
 import fs from "node:fs/promises";
+import path from "node:path";
+import { headMetaToHeadTags, parseCookies, scanPlugins, DevSlowlyChangingPhase, slowRenderInstances } from "@jay-framework/stack-server-runtime";
 import http from "node:http";
 import { Readable } from "node:stream";
-import path from "node:path";
 import { getLogger } from "@jay-framework/logger";
-import { F as FilesystemArtifactStore, i as initializeServices, r as registerActionsFromManifest, d as isActionRequest, f as fetchActionRequest, b as fetchStaticFile, m as matchRequest, a as fetchPageRequest, l as loadPagePartsFromConfig } from "./init-services-CVQ-U9iX.js";
-import { c, e } from "./init-services-CVQ-U9iX.js";
-import { parseCookies, scanPlugins, DevSlowlyChangingPhase, slowRenderInstances } from "@jay-framework/stack-server-runtime";
+import { F as FilesystemArtifactStore, i as initializeServices, r as registerActionsFromManifest, d as isActionRequest, f as fetchActionRequest, b as fetchStaticFile, m as matchRequest, g as renderErrorPage, a as fetchPageRequest, l as loadPagePartsFromConfig } from "./init-services-CG_wDJmY.js";
+import { c, e } from "./init-services-CG_wDJmY.js";
 import { isJayWebhook } from "@jay-framework/fullstack-component";
 import crypto from "node:crypto";
 async function generateSitemap(manifest, baseUrl, outputPath) {
@@ -49,6 +49,133 @@ function buildUrlFromManifest(pattern, params) {
 function escapeXml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
 }
+function resolveUrl(baseUrl, value) {
+  if (/^https?:\/\//i.test(value)) return value;
+  if (!baseUrl) return value;
+  const base = baseUrl.replace(/\/$/, "");
+  const rel = value.startsWith("/") ? value : `/${value}`;
+  return `${base}${rel}`;
+}
+function generateSiteJsonLd(site) {
+  if (!site?.name) return [];
+  const base = site.baseUrl?.replace(/\/$/, "");
+  const organization = {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: site.name
+  };
+  if (base) organization.url = base;
+  if (site.logo) organization.logo = resolveUrl(site.baseUrl, site.logo);
+  if (site.description) organization.description = site.description;
+  if (site.sameAs && site.sameAs.length > 0) organization.sameAs = site.sameAs;
+  const website = {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: site.name
+  };
+  if (base) website.url = base;
+  return [
+    {
+      tag: "script",
+      attrs: { type: "application/ld+json" },
+      children: JSON.stringify(organization)
+    },
+    {
+      tag: "script",
+      attrs: { type: "application/ld+json" },
+      children: JSON.stringify(website)
+    }
+  ];
+}
+const UNRESOLVED_BINDING = /\{[A-Za-z_$][\w$]*(?:\.[\w$]+)*\}/;
+function hasUnresolved(value) {
+  return !!value && UNRESOLVED_BINDING.test(value);
+}
+async function loadSlowViewState(backendDir, cachePath) {
+  try {
+    const raw = await fs.readFile(path.join(backendDir, cachePath), "utf8");
+    return JSON.parse(raw).slowViewState ?? {};
+  } catch {
+    return {};
+  }
+}
+function resolveTitleAndDescription(route, viewState) {
+  const tags = headMetaToHeadTags(route.headMeta, viewState);
+  const titleTag = tags.find((t) => t.tag.toLowerCase() === "title");
+  const descTag = tags.find(
+    (t) => t.tag.toLowerCase() === "meta" && t.attrs?.name === "description"
+  );
+  const title = hasUnresolved(titleTag?.children) ? void 0 : titleTag?.children;
+  const description = hasUnresolved(descTag?.attrs?.content) ? void 0 : descTag?.attrs?.content;
+  return { title, description };
+}
+async function collectPageLinks(manifest, base, backendDir) {
+  const links = [];
+  for (const route of manifest.routes) {
+    if (route.devOnly || route.noIndex) continue;
+    if (route.instances.length === 0) {
+      const hasDynamic = route.segments.some((s) => s.type !== "static");
+      if (hasDynamic) continue;
+      const urlPath = route.pattern === "/" ? "/" : route.pattern;
+      const { title, description } = resolveTitleAndDescription(route, {});
+      links.push({ title: title ?? urlPath, url: `${base}${urlPath}`, description });
+      continue;
+    }
+    for (const instance of route.instances) {
+      const urlPath = buildUrlFromManifest(route.pattern, instance.params);
+      const viewState = await loadSlowViewState(backendDir, instance.cachePath);
+      const { title, description } = resolveTitleAndDescription(route, viewState);
+      links.push({ title: title ?? urlPath, url: `${base}${urlPath}`, description });
+    }
+  }
+  return links;
+}
+function sectionOf(url, base) {
+  const pathOnly = url.startsWith(base) ? url.slice(base.length) : url;
+  const seg = pathOnly.replace(/^\//, "").split("/")[0];
+  return seg || "Home";
+}
+async function generateLlmsTxt(manifest, site, backendDir, outputPath) {
+  const base = (site.baseUrl ?? "").replace(/\/$/, "");
+  const links = await collectPageLinks(manifest, base, backendDir);
+  const lines = [`# ${site.name}`, ""];
+  if (site.description) {
+    lines.push(`> ${site.description}`, "");
+  }
+  const bySection = /* @__PURE__ */ new Map();
+  for (const link of links) {
+    const section = sectionOf(link.url, base);
+    const bucket = bySection.get(section) ?? [];
+    bucket.push(link);
+    bySection.set(section, bucket);
+  }
+  for (const [section, bucket] of bySection) {
+    lines.push(`## ${section}`, "");
+    for (const link of bucket) {
+      const suffix = link.description ? `: ${link.description}` : "";
+      lines.push(`- [${link.title}](${link.url})${suffix}`);
+    }
+    lines.push("");
+  }
+  const tmpPath = outputPath + ".tmp";
+  await fs.writeFile(tmpPath, lines.join("\n").replace(/\n+$/, "\n"));
+  await fs.rename(tmpPath, outputPath);
+  return links.length;
+}
+async function generateRobotsTxtIfAbsent(outputPath, baseUrl) {
+  try {
+    await fs.access(outputPath);
+    return false;
+  } catch {
+  }
+  const base = baseUrl?.replace(/\/$/, "");
+  const lines = ["User-agent: *", "Allow: /"];
+  if (base) lines.push(`Sitemap: ${base}/sitemap.xml`);
+  const tmpPath = outputPath + ".tmp";
+  await fs.writeFile(tmpPath, lines.join("\n") + "\n");
+  await fs.rename(tmpPath, outputPath);
+  return true;
+}
 function toFetchRequest(req) {
   const url = new URL(req.url || "/", `http://${req.headers.host}`);
   const headers = new Headers();
@@ -137,8 +264,11 @@ async function startMainServer(options) {
       const currentManifest = await artifacts.readManifest();
       const match = matchRequest(currentManifest, url.pathname);
       if (!match) {
-        res.writeHead(404);
-        res.end("Not Found");
+        const response2 = await renderErrorPage(currentManifest, artifacts, staticBaseUrl, {
+          status: 404,
+          url: url.pathname
+        });
+        await pipeFetchResponse(response2, res);
         return;
       }
       const cookies = parseCookies(req.headers.cookie);
@@ -155,8 +285,19 @@ async function startMainServer(options) {
       logger.error(`[Server] Error handling ${url.pathname}: ${err.message}`);
       if (err.stack) logger.error(err.stack);
       if (!res.headersSent) {
-        res.writeHead(500);
-        res.end("Internal Server Error");
+        try {
+          const currentManifest = await artifacts.readManifest();
+          const response = await renderErrorPage(
+            currentManifest,
+            artifacts,
+            staticBaseUrl,
+            { status: 500, url: url.pathname, message: err?.message }
+          );
+          await pipeFetchResponse(response, res);
+        } catch {
+          res.writeHead(500);
+          res.end("Internal Server Error");
+        }
       }
     }
   });
@@ -298,10 +439,11 @@ async function rebuildInstance(route, params, backendDir, rebuildSuffix) {
   } catch (err) {
     return { status: "skipped", reason: `Failed to load page-parts.json: ${err.message}` };
   }
+  const pageUrl = buildUrlFromManifest(route.pattern, params);
   const slowPhase = new DevSlowlyChangingPhase();
   const slowResult = await slowPhase.runSlowlyForPage(
     params,
-    { params },
+    { language: "en", url: pageUrl },
     pageParts.parts,
     pageParts.discoveredInstances,
     pageParts.headlessInstanceComponents
@@ -324,7 +466,7 @@ async function rebuildInstance(route, params, backendDir, rebuildSuffix) {
       {
         pageViewState: slowViewState,
         pageParams: params,
-        pageProps: { language: "en", url: "" }
+        pageProps: { language: "en", url: pageUrl }
       }
     );
     if (instanceSlowResult) {
@@ -464,6 +606,12 @@ async function rebuild(options) {
       const urlCount = await generateSitemap(manifest, options.siteBaseUrl, sitemapPath);
       logger.info(`[Rebuild] Sitemap regenerated: ${urlCount} URLs`);
     }
+    const site = options.site ?? (options.siteBaseUrl ? { baseUrl: options.siteBaseUrl } : {});
+    if (site.name) {
+      const llmsPath = path.join(frontendDir, "llms.txt");
+      const count = await generateLlmsTxt(manifest, site, backendDir, llmsPath);
+      logger.info(`[Rebuild] llms.txt regenerated: ${count} pages`);
+    }
     if (orphanedFiles.length > 0) {
       await appendCleanupManifest(buildDir, orphanedFiles);
       logger.info(`[Rebuild] ${orphanedFiles.length} orphaned file(s) queued for cleanup`);
@@ -689,10 +837,14 @@ function readBody(req) {
 }
 export {
   FilesystemArtifactStore,
+  buildUrlFromManifest,
   cleanupOrphanedFiles,
   fetchActionRequest,
   fetchPageRequest,
   fetchStaticFile,
+  generateLlmsTxt,
+  generateRobotsTxtIfAbsent,
+  generateSiteJsonLd,
   generateSitemap,
   initializeServices,
   c as initializeServicesFromModules,
@@ -703,6 +855,7 @@ export {
   rebuildContract,
   registerActionsFromManifest,
   e as registerActionsFromModules,
+  renderErrorPage,
   resolveContractToRoutes,
   startMainServer,
   startRendererServer

package/dist/{init-services-CVQ-U9iX.js → init-services-CG_wDJmY.js}

@@ -3,11 +3,11 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 import fs from "node:fs/promises";
 import path from "node:path";
-import { makePassthroughInstanceComponent, renderFastChangingData, headMetaToHeadTags, mergeHeadTags, serializeHeadTags, getClientInitData, actionRegistry, setClientInitData } from "@jay-framework/stack-server-runtime";
+import { resolveErrorPageToken, buildErrorViewState, headMetaToHeadTags, mergeHeadTags, serializeHeadTags, serializeScripts, getClientInitData, makePassthroughInstanceComponent, renderFastChangingData, actionRegistry, setClientInitData } from "@jay-framework/stack-server-runtime";
 import { deepMergeViewStates } from "@jay-framework/view-state-merge";
 import { asyncSwapScript } from "@jay-framework/ssr-runtime";
-import { isJayAction, isJayStreamAction } from "@jay-framework/fullstack-component";
 import { getLogger } from "@jay-framework/logger";
+import { isJayAction, isJayStreamAction } from "@jay-framework/fullstack-component";
 class FilesystemArtifactStore {
   constructor(basePath) {
     __publicField(this, "manifestCache");
@@ -137,6 +137,112 @@ function buildImportMap(sharedManifest, publicBasePath, sharedDir = "shared") {
   }
   return imports;
 }
+async function renderErrorPage(manifest, artifacts, staticBaseUrl, info) {
+  const plainText = () => new Response(info.message || info.title || "Error", {
+    status: info.status,
+    headers: { "Content-Type": "text/plain; charset=utf-8" }
+  });
+  const errorPages = manifest.errorPages;
+  if (!errorPages) return plainText();
+  const token = resolveErrorPageToken(Object.keys(errorPages), info.status);
+  if (!token) return plainText();
+  const entry = errorPages[token];
+  try {
+    return await streamErrorPage(entry, manifest, artifacts, staticBaseUrl, info);
+  } catch (err) {
+    getLogger().error(
+      `[Server] Error page "${token}" render failed (${info.status} ${info.url}): ${err?.message}`
+    );
+    return plainText();
+  }
+}
+async function streamErrorPage(entry, manifest, artifacts, staticBaseUrl, info) {
+  const slowViewState = entry.slowCache?.slowViewState ?? {};
+  const fullViewState = buildErrorViewState(info, slowViewState);
+  const headTagSources = [];
+  if (manifest.siteHeadTags && manifest.siteHeadTags.length > 0)
+    headTagSources.push(manifest.siteHeadTags);
+  const templateHeadTags = headMetaToHeadTags(entry.headMeta, fullViewState);
+  const headTags = headTagSources.length > 0 || templateHeadTags.length > 0 ? mergeHeadTags(headTagSources, templateHeadTags) : [];
+  const hasCustomTitle = headTags.some((t) => t.tag?.toLowerCase() === "title");
+  const titleTag = hasCustomTitle ? "" : `    <title>${info.status} Error</title>
+`;
+  const preconnectTags = headTags.filter(
+    (t) => t.tag === "link" && t.attrs?.rel === "preconnect"
+  );
+  const otherHeadTags = headTags.filter(
+    (t) => !(t.tag === "link" && t.attrs?.rel === "preconnect")
+  );
+  const preconnectHtml = preconnectTags.length > 0 ? serializeHeadTags(preconnectTags) + "\n" : "";
+  const headTagsHtml = otherHeadTags.length > 0 ? serializeHeadTags(otherHeadTags) + "\n" : "";
+  const headScriptsHtml = serializeScripts(entry.scripts, "head");
+  const bodyScriptsHtml = serializeScripts(entry.scripts, "body");
+  const serverElement = await artifacts.loadServerElement(entry.serverElementPath);
+  const asyncPromises = [];
+  const importMap = buildImportMap(manifest.sharedManifest, staticBaseUrl);
+  if (entry.routeHydratePath) {
+    importMap["jay-route-hydrate"] = `${staticBaseUrl}${entry.routeHydratePath}`;
+  }
+  const clientBundleUrl = entry.routeClientBundlePath ? `${staticBaseUrl}${entry.routeClientBundlePath}` : "";
+  const sharedPreloads = entry.sharedDeps ? entry.sharedDeps.map((dep) => importMap[dep]).filter(Boolean) : Object.values(importMap);
+  const preloadUrls = clientBundleUrl ? [...sharedPreloads, clientBundleUrl] : [];
+  const modulePreloads = preloadUrls.map((url) => `    <link rel="modulepreload" href="${url}" />`).join("\n");
+  const cssUrl = entry.routeCssPath ? `${staticBaseUrl}${entry.routeCssPath}` : "";
+  const cssPreload = cssUrl ? `    <link rel="preload" href="${cssUrl}" as="style" />` : "";
+  const cssLink = cssUrl ? `    <link rel="stylesheet" href="${cssUrl}" />` : "";
+  const cssImportPreloads = (entry.cssImports ?? []).map((url) => `    <link rel="preload" href="${url}" as="style" />`).join("\n");
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      const write = (s) => controller.enqueue(encoder.encode(s));
+      const headParts = [headTagsHtml, modulePreloads, cssLink, headScriptsHtml].filter(Boolean).join("\n");
+      write(`<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+${titleTag}${[preconnectHtml, cssPreload, cssImportPreloads].filter(Boolean).map((l) => l + "\n").join(
+        ""
+      )}    <script type="importmap">${JSON.stringify({ imports: importMap })}<\/script>
+${headParts}
+  </head>
+  <body>
+    <div id="target">`);
+      serverElement.renderToStream(fullViewState, {
+        write: (chunk) => write(chunk),
+        onAsync: (promise, id, templates) => {
+          asyncPromises.push(
+            promise.then(
+              (val) => asyncSwapScript(id, templates.resolved(val)),
+              (err) => asyncSwapScript(id, templates.rejected(err))
+            )
+          );
+        }
+      });
+      write("</div>");
+      const asyncScripts = (await Promise.all(asyncPromises)).filter((s) => s).join("");
+      if (asyncScripts) write(asyncScripts);
+      if (clientBundleUrl) {
+        const clientInitData = getClientInitData();
+        const initArgs = `${JSON.stringify({})}, ${JSON.stringify(fullViewState)}, ${JSON.stringify({})}, ${JSON.stringify(clientInitData)}`;
+        write(`
+    <script type="module">
+      import { init } from '${clientBundleUrl}';
+      await init(${initArgs});
+    <\/script>`);
+      }
+      if (bodyScriptsHtml) write("\n    " + bodyScriptsHtml);
+      write(`
+  </body>
+</html>`);
+      controller.close();
+    }
+  });
+  return new Response(stream, {
+    status: info.status,
+    headers: { "Content-Type": "text/html; charset=utf-8" }
+  });
+}
 async function loadPagePartsFromConfig(configPath, artifacts) {
   const config = await artifacts.readPagePartsConfig(configPath);
   async function importModule(entry) {
@@ -237,8 +343,13 @@ async function fetchPageRequest(match, manifest, requestUrl, artifacts, staticBa
     });
   }
   if (fastResult.kind === "ServerError" || fastResult.kind === "ClientError") {
-    return new Response(fastResult.message || "Error", {
-      status: fastResult.status
+    return renderErrorPage(manifest, artifacts, staticBaseUrl, {
+      status: fastResult.status,
+      url: requestUrl.pathname,
+      title: fastResult.title,
+      message: fastResult.message,
+      code: fastResult.code,
+      details: fastResult.details
     });
   }
   const fastViewState = fastResult.rendered || {};
@@ -255,12 +366,13 @@ async function fetchPageRequest(match, manifest, requestUrl, artifacts, staticBa
     url: { path: requestUrl.pathname }
   };
   const headTagSources = [];
+  if (manifest.siteHeadTags && manifest.siteHeadTags.length > 0)
+    headTagSources.push(manifest.siteHeadTags);
   const slowHeadTags = cf.__slowHeadTags;
   if (slowHeadTags) headTagSources.push(...slowHeadTags);
   if (fastResult.headTags) headTagSources.push(fastResult.headTags);
   const templateHeadTags = headMetaToHeadTags(route.headMeta, fullViewState);
-  if (templateHeadTags.length > 0) headTagSources.push(templateHeadTags);
-  const headTags = headTagSources.length > 0 ? mergeHeadTags(headTagSources) : [];
+  const headTags = headTagSources.length > 0 || templateHeadTags.length > 0 ? mergeHeadTags(headTagSources, templateHeadTags) : [];
   const hasCustomTitle = headTags.some((t) => t.tag?.toLowerCase() === "title");
   const titleTag = hasCustomTitle ? "" : "    <title>Vite + TS</title>\n";
   const preconnectTags = headTags.filter(
@@ -271,6 +383,8 @@ async function fetchPageRequest(match, manifest, requestUrl, artifacts, staticBa
   );
   const preconnectHtml = preconnectTags.length > 0 ? serializeHeadTags(preconnectTags) + "\n" : "";
   const headTagsHtml = otherHeadTags.length > 0 ? serializeHeadTags(otherHeadTags) + "\n" : "";
+  const headScriptsHtml = serializeScripts(route.scripts, "head");
+  const bodyScriptsHtml = serializeScripts(route.scripts, "body");
   const serverElementPath = route.serverElementPath || instance.serverElementPath;
   const tLoadStart = Date.now();
   const serverElement = await artifacts.loadServerElement(serverElementPath);
@@ -292,7 +406,7 @@ async function fetchPageRequest(match, manifest, requestUrl, artifacts, staticBa
   const stream = new ReadableStream({
     async start(controller) {
       const write = (s) => controller.enqueue(encoder.encode(s));
-      const headParts = [headTagsHtml, modulePreloads, cssLink].filter(Boolean).join("\n");
+      const headParts = [headTagsHtml, modulePreloads, cssLink, headScriptsHtml].filter(Boolean).join("\n");
       write(`<!doctype html>
 <html lang="en">
   <head>
@@ -340,7 +454,7 @@ ${headParts}
       const _t=performance.now();
       await init(${initArgs});
       console.log('[jay] hydrate: '+(performance.now()-_t).toFixed(1)+'ms');
-    <\/script>
+    <\/script>${bodyScriptsHtml ? "\n    " + bodyScriptsHtml : ""}
   </body>
 </html>`);
       controller.close();
@@ -537,7 +651,12 @@ const MIME_TYPES = {
   ".ttf": "font/ttf",
   ".webp": "image/webp",
   ".xml": "application/xml",
-  ".txt": "text/plain"
+  ".txt": "text/plain",
+  // Agent-readiness resources (DL#217): SKILL.md + packaged skill archives.
+  ".md": "text/markdown",
+  ".gz": "application/gzip",
+  // `.tar.gz` resolves via its last extension `.gz`
+  ".tar": "application/x-tar"
 };
 async function fetchStaticFile(pathname, frontendDir) {
   const normalizedBase = path.resolve(frontendDir);
@@ -550,13 +669,15 @@ async function fetchStaticFile(pathname, frontendDir) {
       const contentType = MIME_TYPES[ext] || "application/octet-stream";
       const isHashed = /[-][a-zA-Z0-9_-]{6,}\./.test(path.basename(candidate));
       const cacheControl = isHashed ? "public, max-age=31536000, immutable" : "public, max-age=3600";
-      return new Response(new Uint8Array(content), {
-        headers: {
-          "Content-Type": contentType,
-          "Content-Length": String(content.length),
-          "Cache-Control": cacheControl
-        }
-      });
+      const headers = {
+        "Content-Type": contentType,
+        "Content-Length": String(content.length),
+        "Cache-Control": cacheControl
+      };
+      if (pathname.startsWith("/.well-known/")) {
+        headers["Access-Control-Allow-Origin"] = "*";
+      }
+      return new Response(new Uint8Array(content), { headers });
     } catch {
     }
   }
@@ -632,6 +753,7 @@ export {
   isActionRequest as d,
   registerActionsFromModules as e,
   fetchActionRequest as f,
+  renderErrorPage as g,
   initializeServices as i,
   loadPagePartsFromConfig as l,
   matchRequest as m,

package/dist/{serve-index-C2Tfaz1E.d.ts → serve-index-C28bP6tW.d.ts}

@@ -1,5 +1,6 @@
 import * as _jay_framework_ssr_runtime from '@jay-framework/ssr-runtime';
-import { JayHtmlHeadMeta, DevServerPagePart, HeadlessInstanceComponent, ForEachHeadlessInstance, ActionRegistry } from '@jay-framework/stack-server-runtime';
+import { JayHtmlHeadMeta, JayHtmlScript, DevServerPagePart, HeadlessInstanceComponent, ForEachHeadlessInstance, ActionRegistry } from '@jay-framework/stack-server-runtime';
+import { HeadTag } from '@jay-framework/fullstack-component';
 
 interface RouteManifest {
     version: string;
@@ -8,6 +9,50 @@ interface RouteManifest {
     routes: RouteEntry[];
     actions: ActionEntry[];
     plugins: PluginEntry[];
+    /**
+     * Site-level JSON-LD (Organization + WebSite) head tags, generated once at build from
+     * `.jay` `site` config and injected into every served page's `<head>` (DL#213). Empty/absent
+     * when `site.name` is not configured.
+     */
+    siteHeadTags?: HeadTag[];
+    /**
+     * Compiled error pages keyed by status token (`"404"`, `"502"`, `"5xx"`, …) (DL#218).
+     * Resolved by status (exact → family), never by URL — kept out of `routes[]` so they are
+     * non-navigable and excluded from sitemap/llms.txt/robots/internal-link validation.
+     */
+    errorPages?: Record<string, ErrorPageEntry>;
+}
+/**
+ * A compiled error page (DL#218). Mirrors the per-route compiled refs of a single-instance
+ * route, minus URL/param machinery: an error page is resolved by status, not by matching a URL.
+ */
+interface ErrorPageEntry {
+    /** Status token this page serves — exact (`"404"`, `"502"`) or family (`"4xx"`, `"5xx"`). */
+    token: string;
+    /** Per-page server element path (relative to backend dir). */
+    serverElementPath: string;
+    /** Per-page CSS file path (relative to frontend dir). */
+    routeCssPath?: string;
+    /** Per-page hydrate script path (relative to frontend dir). */
+    routeHydratePath?: string;
+    /** Per-page client bundle path (relative to frontend dir). */
+    routeClientBundlePath?: string;
+    /** External @import URLs extracted from CSS at build time. */
+    cssImports?: string[];
+    /** Head metadata from the error page's jay-html <head>. */
+    headMeta?: JayHtmlHeadMeta;
+    /** Passthrough `<script jay-script="allow">` tags from the template. */
+    scripts?: JayHtmlScript[];
+    /** Shared chunk package names this page's hydrate/client bundle imports (DL#177). */
+    sharedDeps?: string[];
+    /** trackBy map threaded to the client hydration entry. */
+    trackByMap?: Record<string, string>;
+    /**
+     * Optional pre-rendered slow (static chrome) ViewState. Unused in v1 — an error page is a
+     * pass-through of the injected `error` ViewState (DL#218 Q6); its static chrome renders
+     * from the template without slow data. The renderer merges `slowCache?.slowViewState ?? {}`.
+     */
+    slowCache?: CacheEntry;
 }
 interface RouteSegment {
     type: 'static' | 'param' | 'optional' | 'catchAll' | 'optionalCatchAll';
@@ -32,6 +77,8 @@ interface RouteEntry {
     cssImports?: string[];
     /** Head metadata from jay-html <head> (title, meta tags). */
     headMeta?: JayHtmlHeadMeta;
+    /** Passthrough `<script jay-script="allow">` tags from the jay-html template (DL#149 Phase 2). */
+    scripts?: JayHtmlScript[];
     /** True when page has static <meta name="robots" content="noindex"> */
     noIndex?: boolean;
     instances: InstanceEntry[];
@@ -80,6 +127,14 @@ interface BuildOptions {
     minify?: boolean;
     /** Site base URL for sitemap generation (e.g. "https://example.com"). */
     siteBaseUrl?: string;
+    /** Site identity for Organization + WebSite JSON-LD generation (DL#213). */
+    site?: {
+        name?: string;
+        baseUrl?: string;
+        logo?: string;
+        description?: string;
+        sameAs?: string[];
+    };
 }
 interface ServerElementModule {
     renderToStream: (vs: object, ctx: _jay_framework_ssr_runtime.ServerRenderContext) => void;
@@ -202,4 +257,4 @@ interface PreImportedPlugin {
 declare function initializeServicesFromModules(plugins: PreImportedPlugin[], label: string): Promise<void>;
 declare function initializeServices(buildDir: string, projectRoot: string, label: string): Promise<void>;
 
-export { type ActionEntry as A, type BuildMetadata as B, type CacheEntry as C, FilesystemArtifactStore as F, type InstanceEntry as I, type MatchResult as M, type PageModule as P, type RouteManifest as R, type ServerElementModule as S, type RouteEntry as a, type ArtifactStore as b, type BuildOptions as c, type PluginEntry as d, type PreImportedPlugin as e, type RouteSegment as f, fetchActionRequest as g, fetchPageRequest as h, fetchStaticFile as i, initializeServices as j, initializeServicesFromModules as k, isActionRequest as l, loadPagePartsFromConfig as m, matchRequest as n, registerActionsFromModules as o, registerActionsFromManifest as r };
+export { type ArtifactStore as A, type BuildMetadata as B, type CacheEntry as C, type ErrorPageEntry as E, FilesystemArtifactStore as F, type InstanceEntry as I, type MatchResult as M, type PageModule as P, type RouteManifest as R, type ServerElementModule as S, type RouteEntry as a, type ActionEntry as b, type BuildOptions as c, type PluginEntry as d, type PreImportedPlugin as e, type RouteSegment as f, fetchActionRequest as g, fetchPageRequest as h, fetchStaticFile as i, initializeServices as j, initializeServicesFromModules as k, isActionRequest as l, loadPagePartsFromConfig as m, matchRequest as n, registerActionsFromModules as o, registerActionsFromManifest as r };

package/dist/serve-index.d.ts

@@ -1,3 +1,4 @@
-export { b as ArtifactStore, C as CacheEntry, F as FilesystemArtifactStore, I as InstanceEntry, M as MatchResult, e as PreImportedPlugin, a as RouteEntry, R as RouteManifest, S as ServerElementModule, g as fetchActionRequest, h as fetchPageRequest, i as fetchStaticFile, j as initializeServices, k as initializeServicesFromModules, l as isActionRequest, n as matchRequest, r as registerActionsFromManifest, o as registerActionsFromModules } from './serve-index-C2Tfaz1E.js';
+export { A as ArtifactStore, C as CacheEntry, F as FilesystemArtifactStore, I as InstanceEntry, M as MatchResult, e as PreImportedPlugin, a as RouteEntry, R as RouteManifest, S as ServerElementModule, g as fetchActionRequest, h as fetchPageRequest, i as fetchStaticFile, j as initializeServices, k as initializeServicesFromModules, l as isActionRequest, n as matchRequest, r as registerActionsFromManifest, o as registerActionsFromModules } from './serve-index-C28bP6tW.js';
 import '@jay-framework/ssr-runtime';
 import '@jay-framework/stack-server-runtime';
+import '@jay-framework/fullstack-component';

package/dist/serve-index.js

@@ -1,4 +1,4 @@
-import { F, f, a, b, i, c, d, m, r, e } from "./init-services-CVQ-U9iX.js";
+import { F, f, a, b, i, c, d, m, r, e } from "./init-services-CG_wDJmY.js";
 export {
   F as FilesystemArtifactStore,
   f as fetchActionRequest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/production-server",
-  "version": "0.25.0",
+  "version": "0.25.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -30,14 +30,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/fullstack-component": "^0.25.0",
-    "@jay-framework/logger": "^0.25.0",
-    "@jay-framework/ssr-runtime": "^0.25.0",
-    "@jay-framework/stack-server-runtime": "^0.25.0",
-    "@jay-framework/view-state-merge": "^0.25.0"
+    "@jay-framework/fullstack-component": "^0.25.2",
+    "@jay-framework/logger": "^0.25.2",
+    "@jay-framework/ssr-runtime": "^0.25.2",
+    "@jay-framework/stack-server-runtime": "^0.25.2",
+    "@jay-framework/view-state-merge": "^0.25.2"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.25.0",
+    "@jay-framework/dev-environment": "^0.25.2",
     "@types/node": "^22.15.21",
     "rimraf": "^5.0.5",
     "tsup": "^8.0.1",