@warpgogol/werkstatt-shared 0.2.0 → 0.3.0

package/src/content/index.ts

@@ -0,0 +1,22 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Public entrypoint for @warpgogol/werkstatt-shared/content — exports
+markdown frontmatter utilities and system manifest loading (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not import from app-specific packages or stack plugins.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/content/index.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+export { parseMarkdownFrontmatter, stringifyMarkdownFrontmatter } from "./markdown-frontmatter.ts";
+export type { ParsedFrontmatter } from "./markdown-frontmatter.ts";
+export {
+  loadSystemManifest,
+  loadSystemManifestSync,
+  isUsingSystemMd,
+  isUsingSystemMdSync,
+} from "./system-manifest.ts";
+export type { SystemManifest, SystemManifestLoadResult } from "./system-manifest.ts";

package/src/content/markdown-frontmatter.ts

@@ -0,0 +1,46 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Parse and stringify Markdown frontmatter using YAML. Extracts frontmatter
+data and content from --- delimited blocks. Stack-agnostic utility used by both
+engine and site plugin (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not handle raw Markdown parsing beyond frontmatter extraction.</item>
+  <item>Do not manage file I/O or transport mechanisms for Markdown files.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/content/markdown-frontmatter.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import YAML from "yaml";
+
+export type ParsedFrontmatter = {
+  content: string;
+  data: Record<string, unknown>;
+};
+
+export function parseMarkdownFrontmatter(source: string): ParsedFrontmatter {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+
+  if (!match) {
+    return {
+      content: source,
+      data: {},
+    };
+  }
+
+  return {
+    content: match[2] ?? "",
+    data: (YAML.parse(match[1]) ?? {}) as Record<string, unknown>,
+  };
+}
+
+export function stringifyMarkdownFrontmatter(
+  content: string,
+  data: Record<string, unknown>,
+): string {
+  const normalizedContent = content.replace(/^\s+/, "").replace(/\s+$/, "");
+  const frontmatter = YAML.stringify(data).trimEnd();
+  return `---\n${frontmatter}\n---\n\n${normalizedContent}\n`;
+}

package/src/content/system-manifest.ts

@@ -0,0 +1,182 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Facilitates loading and parsing of the canonical system.md manifest per RFC-0047.
+Stack-agnostic utility used by both engine and site plugin (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not validate system manifest content (handled by validators).</item>
+  <item>Do not handle system manifest generation or modification.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/content/system-manifest.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile, access } from "node:fs/promises";
+import { readFileSync, accessSync } from "node:fs";
+import { join } from "node:path";
+import { parseMarkdownFrontmatter } from "./markdown-frontmatter.ts";
+
+export interface SystemManifest {
+  app: string;
+  version: string;
+  identity: {
+    systemStar: string;
+    biome: string;
+    tagline: string;
+    domain?: string;
+    /** RFC-0087: Per-app default CTA pageId for shared header and final-cta. */
+    ctaTarget?: string;
+    /** RFC-0096: Operator details consumed by legal.scaffold to fill Impressum / Datenschutz stubs. */
+    legal?: {
+      responsibleName?: string;
+      address?: string;
+      email?: string;
+    };
+  };
+  i18n?: {
+    default: string;
+    supported: Record<string, unknown>;
+  };
+  constellations: string[];
+  clientEditable: string[];
+  sharedContext?: {
+    requiredPageIds: string[];
+  };
+  pages: Array<{
+    pageId: string;
+    routes?: Record<string, string>;
+    route?: string;
+    /** RFC-0097: explicit locale opt-in; the page exists only in these locales. */
+    locales?: string[];
+    cosmicStar: string;
+    planets: Array<{
+      cosmicPlanet: string;
+      pin: string;
+    }>;
+  }>;
+  growth: {
+    vendor: {
+      adapter: string;
+      options: Record<string, unknown>;
+    };
+    funnels: unknown[];
+    experiments: unknown[];
+  };
+  release: {
+    passport: {
+      enabled: boolean;
+      indexable: boolean;
+      keyVersion: string;
+      heartbeatUrl: string;
+    };
+  };
+  /**
+   * RFC-0211 Content Knowledge Lifecycle policy. Mirrors the `knowledge` block in
+   * the ontology systemManifestSchema; declared here so the CKL kernel commands
+   * (content.freshness.validate RFC-0213, content.plan.build RFC-0216) read it
+   * with real types instead of structural casts.
+   */
+  knowledge?: {
+    freshness?: {
+      soonWindowDays?: number;
+      critical?: Array<{ match: string; criticality: "advisory" | "important" | "blocking" }>;
+    };
+    derivation?: {
+      critical?: Array<{ match: string; criticality: "advisory" | "important" | "blocking" }>;
+    };
+    plan?: {
+      leadTimeDays?: number;
+      defaultOwner?: string;
+      criticalityMap?: Array<{ match: string; criticality: "advisory" | "important" | "blocking" }>;
+    };
+  };
+  /** RFC-0487: Business model declaration. Closed enum — currently only "b2b-only". */
+  businessModel?: "b2b-only";
+  /** RFC-0487/RFC-0509: Retired page routes — 410 Gone tombstones or 301 redirects. */
+  retiredRoutes?: Array<{ slug: string; status: 410 } | { slug: string; status: 301; to: string }>;
+  /** UI-level rendering toggles for split-list column order. */
+  ui?: {
+    responsibilityBlock?: {
+      swapOrder?: boolean;
+    };
+  };
+}
+
+export interface SystemManifestLoadResult {
+  manifest: SystemManifest;
+  source: "system.md";
+  filePath: string;
+}
+
+/**
+ * Loads and parses the canonical system.md manifest from src/content/system.md.
+ *
+ * @param contentDirectory The src/content directory path
+ * @returns Parsed system manifest with source information
+ */
+export async function loadSystemManifest(
+  contentDirectory: string,
+): Promise<SystemManifestLoadResult> {
+  const systemMdPath = join(contentDirectory, "system.md");
+  await access(systemMdPath);
+  const content = await readFile(systemMdPath, "utf8");
+  const parsed = parseMarkdownFrontmatter(content);
+
+  return {
+    manifest: parsed.data as unknown as SystemManifest,
+    source: "system.md",
+    filePath: systemMdPath,
+  };
+}
+
+/**
+ * Synchronous version of loadSystemManifest for contexts where async is not available.
+ *
+ * @param contentDirectory The src/content directory path
+ * @returns Parsed system manifest with source information
+ */
+export function loadSystemManifestSync(contentDirectory: string): SystemManifestLoadResult {
+  const systemMdPath = join(contentDirectory, "system.md");
+  accessSync(systemMdPath);
+  const content = readFileSync(systemMdPath, "utf8");
+  const parsed = parseMarkdownFrontmatter(content);
+
+  return {
+    manifest: parsed.data as unknown as SystemManifest,
+    source: "system.md",
+    filePath: systemMdPath,
+  };
+}
+
+/**
+ * Checks if the canonical system.md manifest exists.
+ *
+ * @param contentDirectory The src/content directory path
+ * @returns true if src/content/system.md exists
+ */
+export async function isUsingSystemMd(contentDirectory: string): Promise<boolean> {
+  const systemMdPath = join(contentDirectory, "system.md");
+  try {
+    await access(systemMdPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Synchronous version of isUsingSystemMd.
+ *
+ * @param contentDirectory The src/content directory path
+ * @returns true if src/content/system.md exists
+ */
+export function isUsingSystemMdSync(contentDirectory: string): boolean {
+  const systemMdPath = join(contentDirectory, "system.md");
+  try {
+    accessSync(systemMdPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/onboarding/brief.ts

@@ -0,0 +1,51 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Defines and validates the RFC-0070 onboarding brief contract from
+onboarding/<system-id>/.input/00-brief.md (RFC-0532). Stack-agnostic utility
+used by both engine and site plugin (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not scaffold apps or infer derived ecosystem choices like biome or constellation.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/onboarding/brief.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import matter from "gray-matter";
+import { z } from "zod";
+import YAML from "yaml";
+
+export const BriefFrontmatter = z
+  .object({
+    client: z.object({
+      id: z.string().regex(/^[a-z][a-z0-9-]{2,48}$/),
+      domain: z.string().regex(/^([a-z0-9-]+\.)+[a-z]{2,}$/),
+    }),
+    i18n: z
+      .object({
+        default: z.string().regex(/^[a-z]{2}$/),
+        supported: z.array(z.string().regex(/^[a-z]{2}$/)).min(1),
+      })
+      .refine((value) => value.supported.includes(value.default), {
+        message: "i18n.supported must contain i18n.default",
+        path: ["supported"],
+      }),
+    legalJurisdiction: z.string().regex(/^[A-Z]{2}$/),
+  })
+  .strict();
+
+export type Brief = z.infer<typeof BriefFrontmatter>;
+
+export function parseBriefFrontmatter(source: string): Brief {
+  const parsed = matter(source);
+  return BriefFrontmatter.parse(parsed.data);
+}
+
+export function parseSystemFrontmatter(source: string): Record<string, unknown> {
+  return matter(source).data as Record<string, unknown>;
+}
+
+export function parseMarkdownAsYaml(source: string): Record<string, unknown> {
+  return YAML.parse(source) as Record<string, unknown>;
+}

package/src/onboarding/index.ts

@@ -0,0 +1,20 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Public entrypoint for @warpgogol/werkstatt-shared/onboarding — exports
+brief parsing utilities (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not import from app-specific packages or stack plugins.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/onboarding/brief.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+export {
+  BriefFrontmatter,
+  parseBriefFrontmatter,
+  parseSystemFrontmatter,
+  parseMarkdownAsYaml,
+} from "./brief.ts";
+export type { Brief } from "./brief.ts";

package/src/share/legal/index.ts

@@ -0,0 +1 @@
+export * from "./translation-policy.ts";

package/src/share/scripts/orchestrator.ts

@@ -57,9 +57,13 @@ export async function runStandardLayoutOrchestration(
     }
   }
 
-  // 2. LordIcon hydration (mandatory on demand)
+  // 2. LordIcon hydration (deferred to load event to avoid blocking LCP)
   if (has("lord-icon")) {
-    initLordIconOnDemand();
+    if (document.readyState === "complete") {
+      initLordIconOnDemand();
+    } else {
+      window.addEventListener("load", () => initLordIconOnDemand(), { once: true });
+    }
   }
 
   // 3. Lenis smooth scroll (opt-in via smoothScroll: true)

package/src/share/semantic/models.ts

@@ -331,6 +331,14 @@ export type SemanticPageModel = {
    * Image Provider Port run in the render layer), so it ships the raw token.
    */
   leadImageToken?: { src: string; alt: string };
+  /**
+   * Unresolved token for the page's actual LCP element, carried from the
+   * framework-free page handler to the asset-aware render layer. Set to the
+   * hero block's `backgroundImage` when present (full-viewport, fetchpriority
+   * high), falling back to `leadImage` when visible. Used for `<link
+   * rel="preload" as="image">` in `<head>`.
+   */
+  lcpImageToken?: { src: string; alt: string };
   /** RFC-0162: Open Graph type. Defaults to "website" when unset. */
   ogType?: OgType;
   /** RFC-0162: Open Graph locale in `xx_XX` form (from system.md i18n hreflang). */