@warpgogol/werkstatt-shared 0.7.0 → 0.8.1

package/src/share/content-reference.ts

@@ -205,6 +205,7 @@ export function resolveReferencesInString(
   lang: string,
   defaultLang: string,
   sourceRef?: SourceRef,
+  onUnresolved?: (ref: string, error: string) => void,
 ): string {
   // RFC-0731: Check for this. as a pure reference (entire text is this.field.path)
   if (
@@ -219,6 +220,7 @@ export function resolveReferencesInString(
       if (result.resolved) {
         return formatValue(result.value);
       }
+      onUnresolved?.(text.trim(), result.error ?? "unresolved this. reference");
     }
   }
   THIS_SCAN_PATTERN.lastIndex = 0;
@@ -228,6 +230,7 @@ export function resolveReferencesInString(
     if (result.resolved) {
       return formatValue(result.value);
     }
+    onUnresolved?.(text, result.error ?? "unresolved reference");
     return text;
   }
 
@@ -310,9 +313,12 @@ export async function resolveReferencesDeep(
   lang: string,
   defaultLang: string,
   sourceRef?: SourceRef,
+  onUnresolved?: (ref: string, error: string) => void,
 ): Promise<unknown> {
   return substituteRefsDeep(data, (value) =>
-    Promise.resolve(resolveReferencesInString(index, value, lang, defaultLang, sourceRef)),
+    Promise.resolve(
+      resolveReferencesInString(index, value, lang, defaultLang, sourceRef, onUnresolved),
+    ),
   );
 }
 

package/src/share/middleware/access-protection.ts

@@ -0,0 +1,174 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0899: Runtime access protection middleware for dev/alt subdomains. Checks Host header and requires Basic Auth with a 4-digit PIN for dev.* and alt.* hosts. Sets X-Robots-Tag headers to prevent indexing.</purpose>
+<keywords>middleware, access-protection, basic-auth, pin, dev, alt, RFC-0899</keywords>
+<responsibilities>
+  <item>Check Host header against dev.* and alt.* patterns — pass through for main domain.</item>
+  <item>Require Basic Auth (username: access, password: ACCESS_PIN env var) for dev/alt hosts.</item>
+  <item>Set X-Robots-Tag: noindex, nofollow, noai, noimageai on ALL dev/alt responses (including 401).</item>
+  <item>Use constant-time string comparison for auth check to prevent timing attacks.</item>
+  <item>Pass through when ACCESS_PIN is unset (allows new sites before protection is configured).</item>
+</responsibilities>
+<non-goals>
+  <item>Do not modify the HTML response body — only headers and access gating.</item>
+  <item>Do not activate for the main/production domain, even if the PIN secret is set on the main Worker.</item>
+  <item>Do not use Node.js-specific APIs (Buffer, crypto.timingSafeEqual) — runs in Cloudflare Workers runtime.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0899: Initial access protection middleware for dev/alt subdomains.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { defineMiddleware } from "astro:middleware";
+
+const NOINDEX_HEADER = "noindex, nofollow, noai, noimageai";
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Returns true if both strings are equal, false otherwise.
+ * Always processes the full length of both strings regardless of match status.
+ */
+function constantTimeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return diff === 0;
+}
+
+/**
+ * Check if a host is a dev or alt subdomain.
+ */
+function isDevOrAltHost(host: string): boolean {
+  return host.startsWith("dev.") || host.startsWith("alt.");
+}
+
+/**
+ * RFC-0899: Check access protection for a request. Called from the Worker entry point
+ * (worker.ts) before passing to the Astro handler. This is necessary because Astro
+ * middleware does not run for prerendered static pages (output: "static") — the
+ * Cloudflare adapter serves them from the ASSETS binding directly.
+ *
+ * Returns a 401 Response if access is denied, or null if the request should pass through.
+ * For dev/alt hosts with no PIN set, returns null (pass through) — caller should add
+ * X-Robots-Tag header to the response.
+ *
+ * @param request - The incoming Request
+ * @param env - The Worker env object (contains ACCESS_PIN)
+ * @returns 401 Response if denied, null if pass through
+ */
+export function checkAccessProtection(
+  request: Request,
+  env: Record<string, unknown>,
+): Response | null {
+  const host = request.headers.get("host") ?? "";
+  if (!isDevOrAltHost(host)) return null;
+
+  const pin = (env.ACCESS_PIN as string | undefined) ?? undefined;
+
+  // No PIN set — allow access (caller should add X-Robots-Tag)
+  if (!pin) return null;
+
+  // Check Basic Auth
+  const auth = request.headers.get("authorization") ?? "";
+  const expected = `Basic ${btoa(`access:${pin}`)}`;
+
+  if (auth && constantTimeEqual(auth, expected)) {
+    return null; // Authenticated — pass through
+  }
+
+  // Not authenticated — challenge
+  return new Response("Authentication required", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": 'Basic realm="Staging Access"',
+      "X-Robots-Tag": NOINDEX_HEADER,
+    },
+  });
+}
+
+/**
+ * RFC-0899: Add X-Robots-Tag header to a response for dev/alt subdomains.
+ * Called after the Astro handler returns a response, if the host is dev/alt.
+ *
+ * @param response - The response to modify
+ * @returns A new response with X-Robots-Tag added (if dev/alt host)
+ */
+export function addNoIndexHeaderIfNeeded(request: Request, response: Response): Response {
+  const host = request.headers.get("host") ?? "";
+  if (!isDevOrAltHost(host)) return response;
+
+  const headers = new Headers(response.headers);
+  headers.set("X-Robots-Tag", NOINDEX_HEADER);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+// cloudflare:workers is only available in the Cloudflare Workers runtime.
+// In Astro build (Node.js) the static import fails — resolve lazily so the
+// middleware still loads; ACCESS_PIN is undefined in build (no runtime binding).
+async function resolveAccessPin(): Promise<string | undefined> {
+  try {
+    const { env } = await import("cloudflare:workers");
+    return (env.ACCESS_PIN as string | undefined) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * RFC-0899: Access protection middleware for dev/alt subdomains.
+ *
+ * At runtime, checks the Host header:
+ * - dev.* or alt.* → require Basic Auth with ACCESS_PIN env var
+ * - main.* or production domain → no protection, pass through
+ * - No PIN configured → pass through but still set X-Robots-Tag
+ *
+ * The auth check happens BEFORE next() to short-circuit unauthorized access.
+ * X-Robots-Tag is set on ALL dev/alt responses including 401 challenges.
+ *
+ * Uses `cloudflare:workers` env import (Astro v6 removed `context.locals.runtime.env`).
+ * Uses `btoa()` (Workers runtime), not Node.js Buffer.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const accessProtectionMiddleware = defineMiddleware(async (context: any, next: any) => {
+  const host = context.request.headers.get("host") ?? "";
+  const isDevOrAlt = host.startsWith("dev.") || host.startsWith("alt.");
+
+  if (!isDevOrAlt) {
+    return next();
+  }
+
+  const pin = await resolveAccessPin();
+
+  // No PIN set — allow access but still set noindex headers
+  if (!pin) {
+    const response = await next();
+    response.headers.set("X-Robots-Tag", NOINDEX_HEADER);
+    return response;
+  }
+
+  // Check Basic Auth BEFORE calling next()
+  const auth = context.request.headers.get("authorization") ?? "";
+  const expected = `Basic ${btoa(`access:${pin}`)}`;
+
+  if (auth && constantTimeEqual(auth, expected)) {
+    const response = await next();
+    response.headers.set("X-Robots-Tag", NOINDEX_HEADER);
+    return response;
+  }
+
+  // Not authenticated — challenge with noindex headers
+  return new Response("Authentication required", {
+    status: 401,
+    headers: {
+      "WWW-Authenticate": 'Basic realm="Staging Access"',
+      "X-Robots-Tag": NOINDEX_HEADER,
+    },
+  });
+});

package/src/share/middleware/tests/access-protection.test.ts

@@ -0,0 +1,123 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>RFC-0899: Unit tests for access protection middleware logic — constant-time comparison, host matching, PIN gating.</purpose>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0899: Initial middleware unit tests.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, expect, it, vi } from "vitest";
+
+const mockEnv: Record<string, unknown> = {};
+vi.mock("cloudflare:workers", () => ({
+  env: mockEnv,
+}));
+vi.mock("astro:middleware", () => ({
+  defineMiddleware: (handler: unknown) => handler,
+}));
+
+describe("RFC-0899: access protection middleware", () => {
+  async function loadMiddleware() {
+    return (await import("../access-protection")).accessProtectionMiddleware as (
+      context: unknown,
+      next: () => Promise<Response>,
+    ) => Promise<Response>;
+  }
+
+  function makeContext(host: string, authHeader?: string) {
+    const headers = new Map<string, string>();
+    headers.set("host", host);
+    if (authHeader) headers.set("authorization", authHeader);
+    return {
+      request: {
+        headers: {
+          get: (name: string) => headers.get(name.toLowerCase()) ?? null,
+        },
+      },
+    };
+  }
+
+  async function runMiddleware(
+    handler: (context: unknown, next: () => Promise<Response>) => Promise<Response>,
+    host: string,
+    authHeader?: string,
+  ): Promise<Response & { _nextCalled: boolean }> {
+    let nextCalled = false;
+    const nextResponse = new Response("page content", { status: 200 });
+    const result = await handler(makeContext(host, authHeader), async () => {
+      nextCalled = true;
+      return nextResponse;
+    });
+    return Object.assign(result, { _nextCalled: nextCalled });
+  }
+
+  it("passes through for main domain (no dev/alt prefix)", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "example.com");
+    expect(res._nextCalled).toBe(true);
+    expect(res.status).toBe(200);
+  });
+
+  it("returns 401 for dev.* without auth header when PIN is set", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "dev.example.com");
+    expect(res._nextCalled).toBe(false);
+    expect(res.status).toBe(401);
+    expect(res.headers.get("WWW-Authenticate")).toBe('Basic realm="Staging Access"');
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow, noai, noimageai");
+  });
+
+  it("returns 401 for alt.* without auth header when PIN is set", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "alt.example.com");
+    expect(res._nextCalled).toBe(false);
+    expect(res.status).toBe(401);
+  });
+
+  it("passes through dev.* with correct Basic Auth", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const expected = `Basic ${btoa("access:1234")}`;
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "dev.example.com", expected);
+    expect(res._nextCalled).toBe(true);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow, noai, noimageai");
+  });
+
+  it("returns 401 for dev.* with wrong PIN", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const wrong = `Basic ${btoa("access:9999")}`;
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "dev.example.com", wrong);
+    expect(res._nextCalled).toBe(false);
+    expect(res.status).toBe(401);
+  });
+
+  it("passes through dev.* when PIN is not set (no env var)", async () => {
+    delete mockEnv.ACCESS_PIN;
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "dev.example.com");
+    expect(res._nextCalled).toBe(true);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow, noai, noimageai");
+  });
+
+  it("passes through alt.* when PIN env is undefined", async () => {
+    mockEnv.ACCESS_PIN = undefined;
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "alt.example.com");
+    expect(res._nextCalled).toBe(true);
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow, noai, noimageai");
+  });
+
+  it("does not set X-Robots-Tag on main domain", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "example.com");
+    expect(res.headers.get("X-Robots-Tag")).toBe(null);
+  });
+});

package/src/share/page.ts

@@ -44,7 +44,7 @@ export interface PageEntry {
 }
 
 export interface BlockEntry {
-  id?: string;
+  id: string;
   type?: string; // CMS-facing archetype slug — validated by page.block.validate
   use?: string; // PlanetName or MoonName — normalized from type for internal resolution
   props: Record<string, unknown>;
@@ -75,7 +75,7 @@ export interface ShellConfig {
  * All blocks in ResolvedPage.blocks passed visibility — invisible blocks are dropped.
  */
 export interface ResolvedBlock {
-  /** Stable kebab-case block id from the content entry (null if not declared). */
+  /** Stable kebab-case block id from the content entry. Mandatory for content blocks (RFC-0914); null only for shell blocks injected by the pipeline. */
   readonly id: string | null;
   /** The PlanetName or MoonName identifying this block's archetype. */
   readonly planetName: string;
@@ -121,6 +121,8 @@ export interface SectionProps {
   defaultLanguageCode: string;
   /** Zero-padded section index (01, 02, ...) for anchors and styling */
   sectionNumber: string;
+  /** RFC-0914: Stable kebab-case block id from content entry, used as HTML id */
+  blockId: string;
   /** Optional link registry for CTA/link resolution */
   linkRegistry?: Record<string, string | null>;
   /** Complete block.props as declared in page frontmatter */

package/src/share/routes/template-filter.ts

@@ -0,0 +1,36 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0917 canonical placeholder route template filter. Detects Astro dynamic
+route templates (e.g. `[slug]`, `[version]`) that are expanded by dedicated
+route generators, not actual pages. All system.md consumers MUST import this
+utility instead of reimplementing the bracket-detection check inline.
+</purpose>
+<non-goals>
+  <item>Do not expand or resolve placeholder templates — only detect them.</item>
+  <item>Do not validate route syntax — bracket presence is the only signal.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0917: Initial creation — centralize placeholder route template filtering.</item>
+</CHANGE_SUMMARY>
+*/
+
+/**
+ * Returns `true` if any route value in the given routes map contains
+ * `[` or `]` characters, indicating an Astro dynamic route template
+ * (e.g. `nachweis/[slug]`, `verify/[version]`).
+ *
+ * Returns `false` for `undefined`, `null`, or empty routes — safe default
+ * that avoids false positives when routes are missing or not yet resolved.
+ *
+ * Canonical utility (RFC-0917). All `system.md` consumers
+ * MUST import from `@warpgogol/werkstatt-shared/share/routes/template-filter`.
+ * Enforcement: `utility.provenance.validate` (RFC-0916).
+ */
+export function hasPlaceholderRoutes(routes?: Record<string, string> | null): boolean {
+  if (!routes) return false;
+  return Object.values(routes).some(
+    (slug) => typeof slug === "string" && (slug.includes("[") || slug.includes("]")),
+  );
+}

package/src/share/routes/tests/template-filter.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { hasPlaceholderRoutes } from "../template-filter.ts";
+
+describe("hasPlaceholderRoutes", () => {
+  it("returns true for routes containing [slug]", () => {
+    expect(hasPlaceholderRoutes({ de: "nachweis/[slug]" })).toBe(true);
+  });
+
+  it("returns true for routes containing [version]", () => {
+    expect(hasPlaceholderRoutes({ de: "verify/[version]" })).toBe(true);
+  });
+
+  it("returns true for routes containing [...path] (rest params)", () => {
+    expect(hasPlaceholderRoutes({ de: "docs/[...path]" })).toBe(true);
+  });
+
+  it("returns true for mixed routes (some plain, some placeholder)", () => {
+    expect(hasPlaceholderRoutes({ de: "home", en: "blog/[slug]" })).toBe(true);
+  });
+
+  it("returns false for plain routes without brackets", () => {
+    expect(hasPlaceholderRoutes({ de: "home", en: "about" })).toBe(false);
+  });
+
+  it("returns false for undefined routes", () => {
+    expect(hasPlaceholderRoutes(undefined)).toBe(false);
+  });
+
+  it("returns false for null routes", () => {
+    expect(hasPlaceholderRoutes(null)).toBe(false);
+  });
+
+  it("returns false for empty routes object", () => {
+    expect(hasPlaceholderRoutes({})).toBe(false);
+  });
+
+  it("returns false when route values are non-string", () => {
+    expect(hasPlaceholderRoutes({ de: 123 as unknown as string })).toBe(false);
+  });
+});

package/src/share/scripts/lenis.ts

@@ -79,6 +79,7 @@ export async function initLenis(
             offset: -headerOffset,
             immediate: prefersReducedMotion,
           });
+          history.replaceState(null, "", href);
         }
       }
     }

package/src/share/semantic/block-extractors/index.ts

@@ -500,3 +500,27 @@ for (const blockType of PASSPORT_NOOP_TYPES) {
     },
   });
 }
+
+// ---------------------------------------------------------------------------
+// Site-specific block types that have no semantic text to extract but must be
+// registered so page.blocks.extract.validate does not fail.
+// ---------------------------------------------------------------------------
+const SITE_NOOP_TYPES = [
+  "nachweis-list",
+  "nachweis-detail",
+  "nachweis-verify",
+  "gratitude",
+  "open-source-registry",
+  "mountain-journey",
+  "dynamic-status-block",
+  "service-metadata-block",
+] as const;
+
+for (const blockType of SITE_NOOP_TYPES) {
+  BLOCK_EXTRACTORS.register<Record<string, unknown>>({
+    blockType,
+    extract() {
+      return { heading: "" };
+    },
+  });
+}

package/src/share/semantic/build-page.ts

@@ -10,6 +10,7 @@
 <CHANGE_SUMMARY>
   <item>RFC-0144: initial extraction of the shared per-page builder from the two duplicated paths.</item>
   <item>RFC-0372: unified all page types through extractContentBlocks + extractPageHeading; removed home-specific branch and extractMarkdownProps; extractContentBlocks returns SemanticBlock[].</item>
+  <item>RFC-0912: extract seo.videoObject opt-in from block props and attach VideoSeoData to SemanticBlock.video.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -22,6 +23,7 @@ import type {
   SemanticPageModel,
   SemanticPageType,
   SemanticPerson,
+  VideoSeoData,
 } from "./models.ts";
 import { BLOCK_EXTRACTORS } from "./block-extraction.ts";
 import "./block-extractors/index.ts";
@@ -132,6 +134,31 @@ async function resolveFaqEntries(
   return faqEntries;
 }
 
+/** RFC-0912: extract video SEO data from block props when seo.videoObject opt-in is present. */
+function extractVideoSeoData(props: Record<string, unknown>): VideoSeoData | undefined {
+  const seo = props["seo"];
+  if (!seo || typeof seo !== "object") return undefined;
+  const seoRecord = seo as Record<string, unknown>;
+  if (seoRecord["videoObject"] !== true) return undefined;
+  const name = seoRecord["name"];
+  const description = seoRecord["description"];
+  const uploadDate = seoRecord["uploadDate"];
+  if (
+    typeof name !== "string" ||
+    typeof description !== "string" ||
+    typeof uploadDate !== "string"
+  ) {
+    return undefined;
+  }
+  // The manifest data (posterUrl, durationSec, contentUrl) is populated by the
+  // render layer when the variant manifest is available. At build-page time we
+  // carry the seo fields; the render layer fills in the manifest data.
+  return {
+    seo: { name, description, uploadDate },
+    manifest: { posterUrl: "", contentUrl: "" },
+  };
+}
+
 /** RFC-0372: extract semantic text from declared blocks into SemanticBlock[]. */
 function extractContentBlocks(
   blocks: Array<Record<string, unknown>>,
@@ -140,7 +167,12 @@ function extractContentBlocks(
   const result: SemanticBlock[] = [];
   for (const block of blocks) {
     const blockType = String(block["type"] ?? "");
-    const blockId = String(block["id"] ?? `block-${result.length}`);
+    const blockId = block["id"];
+    if (typeof blockId !== "string" || !blockId) {
+      throw new Error(
+        `[extractContentBlocks] Block #${result.length} in page ${ctx.pageId} (${ctx.lang}) is missing required \`id\` field. Run \`block.id.generate\` to backfill.`,
+      );
+    }
     if (!blockType) continue;
     const extractor = BLOCK_EXTRACTORS.get(blockType);
     if (!extractor) continue;
@@ -156,6 +188,12 @@ function extractContentBlocks(
       items: extracted.items,
       extractedAt: new Date().toISOString(),
       extractorVersion: "1.0.0",
+      // RFC-0912: attach video SEO data when the block has seo.videoObject opt-in.
+      ...((block["props"] ?? block) &&
+      typeof (block["props"] ?? block) === "object" &&
+      extractVideoSeoData((block["props"] ?? block) as Record<string, unknown>)
+        ? { video: extractVideoSeoData((block["props"] ?? block) as Record<string, unknown>) }
+        : {}),
     });
   }
   return result;

package/src/share/semantic/extract.ts

@@ -7,6 +7,7 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0133: backfilled MODULE_MAP and CHANGE_SUMMARY markers for compass.validate compliance.</item>
+  <item>RFC-0915: removed custom slugify() — replaced by slugId from @warpgogol/werkstatt-shared/share/slug.</item>
 </CHANGE_SUMMARY>
 */
 
@@ -16,17 +17,6 @@ export function normalizeWhitespace(value: string): string {
   return value.replace(/\s+/g, " ").trim();
 }
 
-export function slugify(value: string): string {
-  return (
-    value
-      .toLowerCase()
-      .normalize("NFKD")
-      .replace(/[\u0300-\u036f]/g, "")
-      .replace(/[^a-z0-9]+/g, "-")
-      .replace(/^-+|-+$/g, "") || "entity"
-  );
-}
-
 export type MarkdownSection = {
   heading: string;
   body: string;
@@ -62,6 +52,90 @@ export function extractParagraphs(markdown: string): string[] {
     .filter(Boolean);
 }
 
+const SENTENCE_ABBREVIATIONS: Record<string, string[]> = {
+  de: [
+    "z.B.",
+    "z. B.",
+    "z.",
+    "etc.",
+    "Nr.",
+    "Abs.",
+    "§",
+    "S.",
+    "ca.",
+    "u.a.",
+    "u. a.",
+    "u.",
+    "vgl.",
+    "bspw.",
+  ],
+  uk: ["т.д.", "т.п.", "п.", "ст.", "див.", "пор.", "напр.", "ім.", "о."],
+  en: ["e.g.", "i.e.", "etc.", "vs.", "Mr.", "Mrs.", "Dr.", "Inc.", "Ltd."],
+};
+
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function buildAbbreviationPattern(abbreviations: string[]): RegExp | undefined {
+  if (abbreviations.length === 0) return undefined;
+  const sorted = [...abbreviations].sort((a, b) => b.length - a.length);
+  return new RegExp(`(?:^|[^a-zA-Zа-яА-ЯёЁїЇіІєЄäöüÄÖÜß])(${sorted.map(escapeRegex).join("|")})$`);
+}
+
+export function splitSentences(text: string, locale: string = "en"): string[] {
+  const normalized = text.trim();
+  if (!normalized) return [];
+
+  const abbreviations = SENTENCE_ABBREVIATIONS[locale] ?? SENTENCE_ABBREVIATIONS.en;
+  const abbrevPattern = buildAbbreviationPattern(abbreviations);
+
+  const sentences: string[] = [];
+  let current = "";
+
+  const chars = [...normalized];
+  for (let i = 0; i < chars.length; i++) {
+    const char = chars[i];
+    current += char;
+
+    if (char !== "." && char !== "!" && char !== "?") continue;
+
+    const nextChar = chars[i + 1];
+    if (nextChar === undefined) {
+      sentences.push(current.trim());
+      current = "";
+      continue;
+    }
+
+    if (nextChar !== " " && nextChar !== "\n" && nextChar !== "\t") continue;
+
+    const beforeAbbrCheck = current.trimEnd();
+
+    if (abbrevPattern && abbrevPattern.test(beforeAbbrCheck)) continue;
+
+    // Skip numbered list markers (e.g., "1. ", "2. ") — a period after
+    // digits is a list marker, not a sentence boundary. After normalizeWhitespace
+    // newlines are spaces, so we check the token before the period.
+    const beforePeriod = current.slice(0, -1);
+    const lastSpaceIdx = Math.max(beforePeriod.lastIndexOf(" "), beforePeriod.lastIndexOf("\n"));
+    const tokenBeforePeriod = beforePeriod.slice(lastSpaceIdx + 1).trim();
+    if (/^\d+$/.test(tokenBeforePeriod)) continue;
+
+    const afterWhitespace = chars
+      .slice(i + 1)
+      .join("")
+      .match(/^\s*([A-ZÄÖÜА-ЯЁЇІЄ])/);
+    if (!afterWhitespace) continue;
+
+    sentences.push(current.trim());
+    current = "";
+  }
+
+  if (current.trim()) sentences.push(current.trim());
+
+  return sentences.filter(Boolean);
+}
+
 export function extractListFacts(markdown: string): string[] {
   return markdown
     .split("\n")