@cosmicdrift/kumiko-headless 0.287.0 → 0.289.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "0.287.0",
+  "version": "0.289.0",
   "description": "Headless UI logic for Kumiko — Dispatcher contract, Form-Controller, View-Model, Nav-Resolver. Plattform- und React-frei; jeder Renderer (renderer, renderer-web, renderer-native, …) komponiert darauf.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.287.0",
+    "@cosmicdrift/kumiko-framework": "0.289.0",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },

package/src/apex/__tests__/page-head.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { injectPageHead, resolveAndInjectPageHead } from "../index";
+
+describe("injectPageHead", () => {
+  const TAGS = '<title>New Title</title>\n<meta name="description" content="d">';
+
+  test("replaces an existing <title> instead of duplicating it", () => {
+    const html = "<html><head><title>Old</title></head><body></body></html>";
+    const out = injectPageHead(html, TAGS);
+    expect(out).not.toContain("<title>Old</title>");
+    expect((out.match(/<title>/g) ?? []).length).toBe(1);
+    expect(out).toContain("<title>New Title</title>");
+  });
+
+  test("applying twice does not duplicate the head-tags block", () => {
+    const html = "<html><head><title>Old</title></head><body></body></html>";
+    const once = injectPageHead(html, TAGS);
+    const twice = injectPageHead(once, TAGS);
+    expect(twice).toBe(once);
+    expect((twice.match(/kumiko-page-head/g) ?? []).length).toBe(1);
+  });
+
+  test("HTML without </head> is returned unchanged", () => {
+    const html = "<html><body><title>Old</title></body></html>";
+    expect(injectPageHead(html, TAGS)).toBe(html);
+  });
+});
+
+describe("resolveAndInjectPageHead", () => {
+  const HTML = "<!doctype html><html><head><title>Shell</title></head><body>shell</body></html>";
+  const input = { path: "/", host: "t", systemQuery: async () => ({}) };
+
+  test("resolved meta is injected as head tags", async () => {
+    const out = await resolveAndInjectPageHead(
+      HTML,
+      async () => ({ title: "Vehicle X", description: "A car", ogImage: "https://x/i.png" }),
+      input,
+    );
+    expect(out).toContain("<title>Vehicle X</title>");
+    expect(out).toContain('<meta property="og:image" content="https://x/i.png" />');
+  });
+
+  test("resolver throws → unchanged html, not a rejection", async () => {
+    const out = await resolveAndInjectPageHead(
+      HTML,
+      async () => {
+        throw new Error("boom");
+      },
+      input,
+    );
+    expect(out).toBe(HTML);
+  });
+
+  test("resolver returns null → unchanged html", async () => {
+    const out = await resolveAndInjectPageHead(HTML, async () => null, input);
+    expect(out).toBe(HTML);
+  });
+
+  test("resolver never resolves → unchanged html after the shared timeout", async () => {
+    const out = await resolveAndInjectPageHead(HTML, () => new Promise(() => {}), input);
+    expect(out).toBe(HTML);
+  }, 2000);
+});

package/src/apex/index.ts

@@ -4,6 +4,7 @@
 // brand tokens (brand.tokensCss) and content. Server-side, zero React, one
 // cacheable HTTP response. See APEX_STRUCTURAL_CSS for the CSS contract.
 
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { escapeHtml } from "../format";
 import { APEX_STRUCTURAL_CSS } from "./css";
 import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox";
@@ -550,3 +551,117 @@ export function renderApexPage(page: ApexPage): string {
   </body>
 </html>`;
 }
+
+/** Per-request head metadata (Open-Graph/title/description) for a
+ *  server-rendered HTML shell. Only `title` is required; everything else
+ *  falls back to no tag rather than a placeholder. */
+export type PageHeadMeta = {
+  readonly title: string;
+  readonly description?: string;
+  readonly ogImage?: string;
+  readonly canonicalUrl?: string;
+  readonly siteName?: string;
+  readonly locale?: string;
+};
+
+// Matches bundled-features' shared/system-query.ts SystemQueryFn shape
+// (non-generic, Promise<unknown>) rather than a generic <T> signature —
+// that's the convention every other systemQuery caller in the framework
+// already follows (r.httpRoute handlers, seo/managed-pages features).
+export type PageHeadSystemQuery = (
+  type: string,
+  payload: unknown,
+  tenantId: TenantId,
+) => Promise<unknown>;
+
+export type PageHeadResolver = (input: {
+  readonly path: string;
+  readonly host: string;
+  readonly systemQuery: PageHeadSystemQuery;
+}) => Promise<PageHeadMeta | null>;
+
+const HEAD_TAGS_MARKER = "<!-- kumiko-page-head -->";
+const TITLE_TAG_RE = /<title\b[^>]*>[\s\S]*?<\/title>/i;
+
+// Idempotent by marker (repeated calls, e.g. hostDispatch + default path
+// both hitting the same request, never double-inject) and safe on a
+// head-less document (nothing to splice into). `tagsHtml` is pre-rendered
+// HTML from a caller (renderApexHeadTags) — this function only owns
+// placement + the original <title> removal, not escaping.
+export function injectPageHead(html: string, tagsHtml: string): string {
+  if (html.includes(HEAD_TAGS_MARKER)) return html;
+  if (!html.includes("</head>")) return html;
+  const withoutTitle = html.replace(TITLE_TAG_RE, "");
+  return withoutTitle.replace("</head>", () => `${HEAD_TAGS_MARKER}\n${tagsHtml}\n</head>`);
+}
+
+// Resolver runs alongside the request, never gates it: a slow, throwing, or
+// null-returning resolver must never turn a 200 shell into a 500 or a
+// stall. One constant shared by runProdApp and runDevApp so both time out
+// on the same value (kumiko-framework#3026).
+const PAGE_HEAD_TIMEOUT_MS = 300;
+
+async function resolvePageHeadWithTimeout(
+  resolvePageHead: PageHeadResolver,
+  input: {
+    readonly path: string;
+    readonly host: string;
+    readonly systemQuery: PageHeadSystemQuery;
+  },
+): Promise<PageHeadMeta | null> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const timedOut = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), PAGE_HEAD_TIMEOUT_MS);
+    });
+    // .catch on the resolver's own promise (not just the outer try/catch)
+    // so a rejection arriving AFTER the timeout already won the race
+    // doesn't surface as an unhandled rejection.
+    const resolved = resolvePageHead(input).catch(() => null);
+    return await Promise.race([resolved, timedOut]);
+  } catch {
+    return null;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+// ApexHead.lang is required (html lang="..."); PageHeadMeta only carries
+// og:locale-shaped strings ("de_DE", "en-US") since that's all og:locale
+// needs. Take the language subtag before the region separator; default to
+// "en" when there's no locale to derive one from.
+function apexLangFromLocale(locale: string | undefined): string {
+  return locale?.split(/[_-]/)[0]?.toLowerCase() || "en";
+}
+
+function toApexHead(meta: PageHeadMeta): ApexHead {
+  return {
+    lang: apexLangFromLocale(meta.locale),
+    title: meta.title,
+    description: meta.description ?? "",
+    ...(meta.canonicalUrl !== undefined ? { canonicalUrl: meta.canonicalUrl } : {}),
+    ...(meta.ogImage !== undefined ? { ogImage: meta.ogImage } : {}),
+    ...(meta.siteName !== undefined ? { siteName: meta.siteName } : {}),
+    ...(meta.locale !== undefined ? { locale: meta.locale } : {}),
+  };
+}
+
+/** Resolves per-request head metadata and splices it into `html`, capped at
+ *  the shared timeout. Never throws and never changes `html` on a resolver
+ *  error, a `null` resolve, or a timeout — the caller's shell always ships
+ *  unchanged. runProdApp and runDevApp both call this single function, so a
+ *  future change to timeout or fallback semantics has one place to land
+ *  (kumiko-framework#3026). */
+export async function resolveAndInjectPageHead(
+  html: string,
+  resolvePageHead: PageHeadResolver,
+  input: {
+    readonly path: string;
+    readonly host: string;
+    readonly systemQuery: PageHeadSystemQuery;
+  },
+): Promise<string> {
+  const meta = await resolvePageHeadWithTimeout(resolvePageHead, input);
+  if (!meta) return html;
+  return injectPageHead(html, renderApexHeadTags(toApexHead(meta)));
+}

package/src/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.289.0",
+    "type": "improvement",
+    "title": "headless gains resolveAndInjectPageHead/injectPageHead for per-request head injection",
+    "detail": "New apex exports: PageHeadMeta/PageHeadResolver/PageHeadSystemQuery types, injectPageHead (idempotent marker-based </head> splice), and resolveAndInjectPageHead (resolves a PageHeadResolver with a shared 300ms timeout, converts to ApexHead, renders via renderApexHeadTags, injects). Moved out of @cosmicdrift/kumiko-server-runtime (kumiko-framework#3026) so runDevApp and runProdApp share one resolve+inject call instead of two copies of the timeout/fallback logic; server-runtime re-exports the three types unchanged for existing consumers."
+  }
+]