feat: release design system engine, studio and component contracts

packages/core/src/control-templates.ts

@@ -4,6 +4,18 @@ import { Buffer } from "node:buffer";
 type Registry = { id: string; definitions: unknown[] };
 const registries = new WeakMap<object, Registry>();
 
+/** Read a control definition owned by the active request for SSR preparation. */
+export function resolveControlTemplate(reference: string): unknown {
+  const ctx = getRequestContext();
+  const registry = ctx && registries.get(ctx);
+  if (!registry) return undefined;
+  const prefix = `@${registry.id}:`;
+  if (!reference.startsWith(prefix)) return undefined;
+  const index = reference.slice(prefix.length);
+  if (!/^(0|[1-9][0-9]*)$/.test(index)) return undefined;
+  return registry.definitions[Number(index)];
+}
+
 /** Hoist nested templates out of each other for linear-size hydration data. */
 export function encodeControlTemplate(value: unknown): string {
   const ctx = getRequestContext();
@@ -17,10 +29,59 @@ export function encodeControlTemplate(value: unknown): string {
   return `@${registry.id}:${index}`;
 }
 
-export function renderControlTemplates(): string {
+/** Nested controls own their rendered content; keep it once in their definition. */
+function compactControlMarkup(markup: string): string {
+  const tokenPattern =
+    /<template\s+(?:data-wrn-(?:if|each)="([^"]+)"|data-wrn-control-end)(?:\s[^>]*)?>\s*<\/template>/g;
+  const stack: Array<{ markerStart: number; marker: string; owned: boolean }> = [];
+  const replacements: Array<{ start: number; end: number; value: string }> = [];
+  for (const match of markup.matchAll(tokenPattern)) {
+    if (match[1]) {
+      stack.push({
+        markerStart: match.index!,
+        marker: match[0],
+        owned: !!resolveControlTemplate(match[1]),
+      });
+      continue;
+    }
+    const open = stack.pop();
+    if (!open || !open.owned || stack.some((entry) => entry.owned)) continue;
+    replacements.push({
+      start: open.markerStart,
+      end: match.index!,
+      value: open.marker.replace(/>\s*<\/template>$/, " data-wrn-control-client></template>"),
+    });
+  }
+  // Do not alter incomplete control ranges.
+  if (stack.length) return markup;
+  for (const replacement of replacements.reverse()) {
+    markup = markup.slice(0, replacement.start) + replacement.value + markup.slice(replacement.end);
+  }
+  return markup;
+}
+
+export function renderControlTemplates(transformMarkup?: (markup: string) => string): string {
   const ctx = getRequestContext();
   const registry = ctx && registries.get(ctx);
   if (!registry) return "";
-  const json = JSON.stringify(registry.definitions).replace(/</g, "\\u003c");
+  const definitions: unknown[] = [];
+  // A markup transform may register shared metadata while visiting a template.
+  // Include those new request-owned entries in this same document.
+  for (let index = 0; index < registry.definitions.length; index++) {
+    const definition = registry.definitions[index];
+    const transform = (entry: unknown) => {
+      if (!entry || typeof entry !== "object") return entry;
+      const copy = { ...entry } as Record<string, unknown>;
+      for (const key of ["body", "empty"]) {
+        if (typeof copy[key] === "string")
+          copy[key] = compactControlMarkup(
+            transformMarkup ? transformMarkup(copy[key]) : copy[key],
+          );
+      }
+      return copy;
+    };
+    definitions.push(Array.isArray(definition) ? definition.map(transform) : transform(definition));
+  }
+  const json = JSON.stringify(definitions).replace(/</g, "\\u003c");
   return `<script type="application/json" data-wrn-controls id="${registry.id}">${json}</script>`;
 }

packages/core/src/headers.ts

@@ -93,6 +93,10 @@ export interface SecurityConfig {
   crossOriginOpenerPolicy?: false | "same-origin" | "same-origin-allow-popups" | "unsafe-none";
   /** Defaults to "SAMEORIGIN". */
   frameOptions?: false | "DENY" | "SAMEORIGIN";
+  /** Allow trusted routes to supply X-WRNexus-Frame-Ancestors (exact HTTPS origins only). */
+  routeFrameAncestors?: boolean;
+  /** Allow a trusted route's explicit CSP to replace the framework default. Opt-in only. */
+  routeContentSecurityPolicy?: boolean;
   /** Defaults to "strict-origin-when-cross-origin". */
   referrerPolicy?: false | string;
   /** Defaults to "same-origin". */
@@ -219,6 +223,9 @@ export function withSecurityHeaders(
   nonce?: string,
 ): Response {
   const headers = new Headers(res.headers);
+  const routeCsp = headers.get("Content-Security-Policy");
+  const routeAncestors = headers.get("X-WRNexus-Frame-Ancestors");
+  headers.delete("X-WRNexus-Frame-Ancestors");
   const cors = normalizeCors(security?.cors);
 
   if (cors.enabled) {
@@ -227,6 +234,46 @@ export function withSecurityHeaders(
 
   if (security?.headers !== false) {
     applyBaseSecurityHeaders(headers, mode, security, nonce);
+    if (security?.routeContentSecurityPolicy && routeCsp?.trim()) {
+      headers.set("Content-Security-Policy", routeCsp);
+      // CSP frame-ancestors is authoritative for explicitly embeddable routes.
+      if (/(?:^|;)\s*frame-ancestors\s+/i.test(routeCsp)) headers.delete("X-Frame-Options");
+    }
+    if (
+      security?.routeFrameAncestors &&
+      routeAncestors !== null &&
+      headers.has("Content-Security-Policy")
+    ) {
+      const sources = routeAncestors.trim().split(/\s+/);
+      const valid =
+        sources.length > 0 &&
+        sources.length <= 21 &&
+        sources.every((source) => {
+          if (source === "'self'" || source === "'none'") return true;
+          try {
+            const url = new URL(source);
+            return (
+              url.protocol === "https:" &&
+              !url.username &&
+              !url.password &&
+              url.origin === source &&
+              !source.includes("*")
+            );
+          } catch {
+            return false;
+          }
+        }) &&
+        (!sources.includes("'none'") || sources.length === 1);
+      const ancestors = valid ? sources.join(" ") : "'none'";
+      const policy = headers
+        .get("Content-Security-Policy")!
+        .split(";")
+        .filter((value) => !/^\s*frame-ancestors(?:\s|$)/i.test(value));
+      headers.set("Content-Security-Policy", policy.join(";") + "; frame-ancestors " + ancestors);
+      if (ancestors === "'none'") headers.set("X-Frame-Options", "DENY");
+      else if (ancestors === "'self'") headers.set("X-Frame-Options", "SAMEORIGIN");
+      else headers.delete("X-Frame-Options");
+    }
   }
 
   if (security?.extraHeaders) {
@@ -261,7 +308,11 @@ function applyBaseSecurityHeaders(
   // A handler can deliberately expose a public image for email embedding.
   // An explicitly configured application policy still takes precedence.
   const responseCorp = headers.get("Cross-Origin-Resource-Policy");
-  if (corp !== false && (security?.crossOriginResourcePolicy !== undefined || !["same-origin", "same-site", "cross-origin"].includes(responseCorp ?? ""))) {
+  if (
+    corp !== false &&
+    (security?.crossOriginResourcePolicy !== undefined ||
+      !["same-origin", "same-site", "cross-origin"].includes(responseCorp ?? ""))
+  ) {
     headers.set("Cross-Origin-Resource-Policy", corp);
   }
   if (security?.originAgentCluster !== false) headers.set("Origin-Agent-Cluster", "?1");

packages/core/src/index.ts

@@ -237,4 +237,8 @@ export type {
   IdempotencyRecord,
   IdempotencyStore,
 } from "./platform.ts";
-export { encodeControlTemplate, renderControlTemplates } from "./control-templates.ts";
+export {
+  encodeControlTemplate,
+  resolveControlTemplate,
+  renderControlTemplates,
+} from "./control-templates.ts";