npm - @cosmicdrift/kumiko-headless - Versions diffs - 1.0.0 → 2.0.0 - Mend

@cosmicdrift/kumiko-headless 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/package.json +7 -2
package/src/apex/__tests__/lightbox.test.ts +20 -0
package/src/apex/__tests__/render.test.ts +54 -1
package/src/apex/css.ts +11 -1
package/src/apex/index.ts +69 -39
package/src/apex/lightbox.ts +50 -0
package/src/dispatcher/__tests__/contract.test.ts +3 -0
package/src/dispatcher/index.ts +2 -0
package/src/dispatcher/types.ts +27 -0
package/src/form/__tests__/submit.test.ts +3 -0
package/src/form/form-controller.ts +6 -3
package/src/format/__tests__/format.test.ts +21 -0
package/src/format/__tests__/html-template.test.ts +47 -0
package/src/format/escape.ts +55 -0
package/src/format/html-template.ts +49 -0
package/src/format/index.ts +40 -6
package/src/index.ts +15 -1
package/src/locale-routing/__tests__/locale-routing.test.ts +118 -0
package/src/locale-routing/index.ts +144 -0
package/src/store/create-store.ts +1 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-headless",
-  "version": "1.0.0",
+  "version": "2.0.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>",
@@ -29,10 +29,15 @@
     "./apex": {
       "types": "./src/apex/index.ts",
       "default": "./src/apex/index.ts"
+    },
+    "./locale-routing": {
+      "types": "./src/locale-routing/index.ts",
+      "default": "./src/locale-routing/index.ts"
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "1.0.0",
+    "@cosmicdrift/kumiko-framework": "2.0.0",
+    "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/src/apex/__tests__/lightbox.test.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { APEX_LIGHTBOX_SCRIPT, APEX_LIGHTBOX_SCRIPT_CSP_HASH } from "../index";
+function scriptBody(html: string): string {
+  const match = html.match(/^<script>(?<body>[\s\S]*)<\/script>$/);
+  const body = match?.groups?.["body"];
+  if (body === undefined) {
+    throw new Error("APEX_LIGHTBOX_SCRIPT isn't a single <script>...</script> string");
+  }
+  return body;
+}
+describe("APEX_LIGHTBOX_SCRIPT_CSP_HASH", () => {
+  test("matches the actual script content byte-for-byte", () => {
+    const body = scriptBody(APEX_LIGHTBOX_SCRIPT);
+    const hash = `sha256-${createHash("sha256").update(body).digest("base64")}`;
+    expect(hash).toBe(APEX_LIGHTBOX_SCRIPT_CSP_HASH);
+  });
+});

package/src/apex/__tests__/render.test.ts CHANGED Viewed

@@ -122,6 +122,8 @@ describe("renderApexPage", () => {
     expect(html.indexOf("price-cap")).toBeLessThan(html.indexOf("b1"));
     // featured tier without explicit cta variant → primary button
     expect(html).toContain('class="btn btn-primary" href="/s"');
+    expect(html).not.toContain("btn-link");
   });
   test("cta variant link renders a plain anchor, default renders a button", () => {
@@ -140,6 +142,29 @@ describe("renderApexPage", () => {
     expect(html).toContain('<a class="btn btn-primary" href="/signup">Start</a>');
   });
+  test("pricing-tier cta variant link renders a plain anchor via renderCta, not a btn-link class", () => {
+    const html = renderApexPage(
+      page({
+        sections: [
+          {
+            kind: "pricing-grid",
+            heading: "Preise",
+            tiers: [
+              {
+                name: "Free",
+                amount: "0 €",
+                benefits: ["b1"],
+                cta: { label: "Los", href: "/free", variant: "link" },
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    expect(html).toContain('<a href="/free">Los</a>');
+    expect(html).not.toContain("btn-link");
+  });
   test("footer --footer-cols reflects column count and survives without columns", () => {
     const twoCols = renderApexPage(
       page({
@@ -153,7 +178,11 @@ describe("renderApexPage", () => {
       }),
     );
     expect(twoCols).toContain("--footer-cols:2");
-    expect(renderApexPage(page())).toContain("--footer-cols:0");
+    // 502/2: --footer-cols:0 makes grid-template-columns's repeat(0, 1fr)
+    // invalid CSS — the browser drops the whole declaration. Clamped to a
+    // minimum of 1 so a footer with no columns still gets a valid grid.
+    expect(renderApexPage(page())).toContain("--footer-cols:1");
+    expect(renderApexPage(page())).not.toContain("--footer-cols:0");
   });
   test("renders every section kind without throwing or leaking undefined", () => {
@@ -189,6 +218,11 @@ describe("renderApexPage", () => {
     );
     expect(withRobots).toContain('<meta name="robots" content="noindex, nofollow" />');
   });
+  test("omits both description meta tags when description is empty", () => {
+    const html = renderApexPage(page({ head: { lang: "de", title: "T", description: "" } }));
+    expect(html).not.toContain('<meta name="description"');
+    expect(html).not.toContain('<meta property="og:description"');
+  });
   test("renders og:site_name and og:locale", () => {
     const html = renderApexPage(
@@ -247,6 +281,25 @@ describe("renderApexPage", () => {
     expect(html).toContain('<link rel="preconnect" href="https://api.example.com" />');
   });
+  test("hero screenshot includes apex lightbox chrome", () => {
+    const html = renderApexPage(
+      page({
+        sections: [
+          {
+            kind: "hero",
+            title: "h",
+            tagline: "t",
+            screenshot: { src: "/shots/demo.png", alt: "Dashboard" },
+          },
+        ],
+      }),
+    );
+    expect(html).toContain('class="shot-frame"');
+    expect(html).toContain('<dialog id="apex-lightbox"');
+    expect(html).toContain("apex-lightbox");
+    expect(html).toContain(".shot-frame img");
+  });
   test("renders schemaJson as json-ld script tag", () => {
     const html = renderApexPage(
       page({

package/src/apex/css.ts CHANGED Viewed

@@ -59,10 +59,20 @@ const HERO = `
   .hero-meta { margin-top: 1.5rem; font-size: 0.875rem; color: var(--fg-subtle); }
   .hero-meta strong { color: var(--fg-muted); font-weight: 600; }
   .shot-frame { border-radius: 0.75rem; border: 1px solid var(--border); background: var(--bg-card);
-    box-shadow: var(--shadow); overflow: hidden; }
+    box-shadow: var(--shadow); overflow: hidden; cursor: zoom-in; }
   .shot-bar { display: flex; gap: 0.4rem; padding: 0.6rem 0.85rem; border-bottom: 1px solid var(--border); background: var(--bg-muted); }
   .shot-bar span { width: 0.65rem; height: 0.65rem; border-radius: 50%; background: var(--border); }
   .shot-frame img { display: block; width: 100%; height: auto; }
+  .apex-lightbox { border: none; padding: 0; margin: auto; max-width: 95vw; max-height: 90vh;
+    background: transparent; overflow: visible; }
+  .apex-lightbox::backdrop { background: rgba(15, 23, 42, 0.72); }
+  .apex-lightbox__img { display: block; max-width: 90vw; max-height: 85vh; width: auto; height: auto;
+    border-radius: 0.75rem; border: 1px solid var(--border); box-shadow: var(--shadow); }
+  .apex-lightbox__close { position: fixed; top: 1rem; right: 1rem; z-index: 1; width: 2.5rem; height: 2.5rem;
+    border: 1px solid var(--border); border-radius: 0.5rem; background: var(--bg-card); color: var(--fg);
+    font-size: 1.5rem; line-height: 1; cursor: pointer; }
+  .apex-lightbox__close:hover { background: var(--bg-muted); }
+  .apex-dark .apex-lightbox__close { background: var(--on-dark); color: var(--primary); border-color: var(--on-dark-border); }
 `;
 const FEATURES = `

package/src/apex/index.ts CHANGED Viewed

@@ -6,8 +6,14 @@
 import { escapeHtml } from "../format";
 import { APEX_STRUCTURAL_CSS } from "./css";
+import { APEX_LIGHTBOX_HTML, APEX_LIGHTBOX_SCRIPT } from "./lightbox";
 export { APEX_NAV_MENU_CSS, APEX_STRUCTURAL_CSS } from "./css";
+export {
+  APEX_LIGHTBOX_HTML,
+  APEX_LIGHTBOX_SCRIPT,
+  APEX_LIGHTBOX_SCRIPT_CSP_HASH,
+} from "./lightbox";
 export type ApexTheme = "light" | "dark";
@@ -203,12 +209,18 @@ export type ApexPage = {
   readonly footer: ApexFooter;
 };
+// JSON in <script>-Kontext: `<` als < serialisieren, damit weder
+// `</script>` noch `<!--` aus dem Block ausbrechen kann (JSON bleibt valide).
+function scriptSafeJsonHtml(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
 function dim(img: ApexImage): string {
   return `${img.width !== undefined ? ` width="${img.width}"` : ""}${img.height !== undefined ? ` height="${img.height}"` : ""}`;
 }
-function svgIcon(inner: string): string {
-  return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${inner}</svg>`;
+function svgIcon(innerHtml: string): string {
+  return `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${innerHtml}</svg>`;
 }
 function renderCta(cta: ApexCta): string {
@@ -241,7 +253,7 @@ function renderHero(s: ApexHeroSection): string {
     s.logo !== undefined
       ? `<img class="hero-pony" src="${escapeHtml(s.logo.src)}" alt="${escapeHtml(s.logo.alt)}"${dim(s.logo)} />`
       : "";
-  const ctas = (s.ctas ?? []).map(renderCta).join("\n            ");
+  const ctasHtml = (s.ctas ?? []).map(renderCta).join("\n            ");
   const meta = s.metaHtml !== undefined ? `<p class="hero-meta">${s.metaHtml}</p>` : "";
   const visual =
     s.screenshot !== undefined
@@ -252,7 +264,7 @@ function renderHero(s: ApexHeroSection): string {
         <div class="hero-copy">
           ${logo}<h1>${escapeHtml(s.title)}</h1>
           <p class="tagline">${escapeHtml(s.tagline)}</p>
-          ${ctas !== "" ? `<div class="hero-cta">${ctas}</div>` : ""}
+          ${ctasHtml !== "" ? `<div class="hero-cta">${ctasHtml}</div>` : ""}
           ${meta}
         </div>
         ${visual}
@@ -261,7 +273,7 @@ function renderHero(s: ApexHeroSection): string {
 }
 function renderFeatureGrid(s: ApexFeatureGridSection): string {
-  const cards = s.items
+  const cardsHtml = s.items
     .map(
       (f) => `<article class="feature">
             ${f.icon !== undefined ? `<div class="feature-icon">${svgIcon(f.icon)}</div>` : ""}<h3>${escapeHtml(f.title)}</h3>
@@ -273,7 +285,7 @@ function renderFeatureGrid(s: ApexFeatureGridSection): string {
       <div class="container">
         ${renderSectionHead(s)}
         <div class="feature-grid">
-          ${cards}
+          ${cardsHtml}
         </div>
       </div>
     </section>`;
@@ -286,41 +298,43 @@ function renderPricingCard(t: ApexPricingTier): string {
   const cap =
     t.capLine !== undefined ? [`<li class="price-cap">${escapeHtml(t.capLine)}</li>`] : [];
   const benefits = t.benefits.map((b) => `<li>${escapeHtml(b)}</li>`);
-  const items = [...cap, ...benefits].join("\n            ");
+  const itemsHtml = [...cap, ...benefits].join("\n            ");
   const per = t.priceSuffix !== undefined ? `<span>${escapeHtml(t.priceSuffix)}</span>` : "";
-  const cls =
-    t.cta.variant !== undefined
-      ? `btn btn-${t.cta.variant}`
-      : featured
-        ? "btn btn-primary"
-        : "btn btn-secondary";
   const tagline =
     t.tagline !== undefined ? `<p class="price-tagline">${escapeHtml(t.tagline)}</p>` : "";
+  // Delegates to renderCta so a `variant: "link"` tier CTA gets the same
+  // class-free anchor as everywhere else instead of re-deriving the class
+  // string here (a prior inline duplicate had no "link" case, always
+  // emitting `.btn-link`, which the structural CSS never defines).
+  const cta =
+    t.cta.variant === undefined
+      ? renderCta({ ...t.cta, variant: featured ? "primary" : "secondary" })
+      : renderCta(t.cta);
   return `<article class="price-card${featured ? " price-card--featured" : ""}">
           ${badge}<h3>${escapeHtml(t.name)}</h3>
           ${tagline}<div class="price-amount">${escapeHtml(t.amount)}${per}</div>
           <ul class="price-list">
-            ${items}
+            ${itemsHtml}
           </ul>
-          <a class="${cls}" href="${escapeHtml(t.cta.href)}">${escapeHtml(t.cta.label)}</a>
+          ${cta}
         </article>`;
 }
 function renderPricingGrid(s: ApexPricingGridSection): string {
-  const cards = s.tiers.map(renderPricingCard).join("\n          ");
+  const cardsHtml = s.tiers.map(renderPricingCard).join("\n          ");
   const idAttr = s.id !== undefined ? ` id="${escapeHtml(s.id)}"` : "";
   return `<section${idAttr}>
       <div class="container">
         ${renderSectionHead(s)}
         <div class="price-grid">
-          ${cards}
+          ${cardsHtml}
         </div>
       </div>
     </section>`;
 }
 function renderInfoGrid(s: ApexInfoGridSection): string {
-  const items = s.items
+  const itemsHtml = s.items
     .map(
       (i) => `<div class="trust-item">
             <h3>${escapeHtml(i.title)}</h3>
@@ -332,7 +346,7 @@ function renderInfoGrid(s: ApexInfoGridSection): string {
       <div class="container">
         ${renderSectionHead(s)}
         <div class="trust-grid">
-          ${items}
+          ${itemsHtml}
         </div>
       </div>
     </section>`;
@@ -370,7 +384,7 @@ function renderSection(s: ApexSection): string {
 }
 function renderNavMenu(m: ApexNavMenu): string {
-  const items = m.items
+  const itemsHtml = m.items
     .map(
       (it) =>
         `<a class="nav-menu__item" href="${escapeHtml(it.href)}">${
@@ -384,7 +398,7 @@ function renderNavMenu(m: ApexNavMenu): string {
     m.footer !== undefined
       ? `<div class="nav-menu__sep"></div><a class="nav-menu__more" href="${escapeHtml(m.footer.href)}">${escapeHtml(m.footer.label)}</a>`
       : "";
-  return `<div class="nav-menu"><button type="button" class="nav-menu__trigger" aria-haspopup="true">${escapeHtml(m.label)}<span class="nav-menu__chev" aria-hidden="true">${svgIcon('<path d="m6 9 6 6 6-6"/>')}</span></button><div class="nav-menu__panel">${items}${footer}</div></div>`;
+  return `<div class="nav-menu"><button type="button" class="nav-menu__trigger" aria-haspopup="true">${escapeHtml(m.label)}<span class="nav-menu__chev">${svgIcon('<path d="m6 9 6 6 6-6"/>')}</span></button><div class="nav-menu__panel">${itemsHtml}${footer}</div></div>`;
 }
 function renderNavEntry(entry: ApexNavEntry): string {
@@ -399,13 +413,13 @@ function renderNavEntry(entry: ApexNavEntry): string {
 export function renderApexHeader(h: ApexHeader): string {
   const logo =
     h.brand.logoSrc !== undefined ? `<img src="${escapeHtml(h.brand.logoSrc)}" alt="" /> ` : "";
-  const navLinks = (h.navLinks ?? []).map(renderNavEntry).join("\n      ");
-  const actions = (h.actions ?? []).map(renderCta);
+  const navLinksHtml = (h.navLinks ?? []).map(renderNavEntry).join("\n      ");
+  const actionsHtml = (h.actions ?? []).map(renderCta).join("\n      ");
   return `<header>
     <div class="container nav">
       <div class="brand"><a href="${escapeHtml(h.brand.href)}">${logo}${escapeHtml(h.brand.label)}</a></div>
-      ${navLinks !== "" ? `<nav class="nav-links">${navLinks}</nav>` : ""}
-      ${actions.length > 0 ? `<div class="nav-actions">${actions.join("\n      ")}</div>` : ""}
+      ${navLinksHtml !== "" ? `<nav class="nav-links">${navLinksHtml}</nav>` : ""}
+      ${actionsHtml !== "" ? `<div class="nav-actions">${actionsHtml}</div>` : ""}
     </div>
   </header>`;
 }
@@ -431,7 +445,7 @@ function renderFooter(f: ApexFooter): string {
       : "";
   return `<footer>
     <div class="container">
-      <div class="footer-grid" style="--footer-cols:${cols.length}">
+      <div class="footer-grid" style="--footer-cols:${Math.max(1, cols.length)}">
         <div>
           <div class="footer-brand">${logo}${escapeHtml(f.brand.label)}</div>
           ${f.tagline !== undefined ? `<p class="footer-tagline">${escapeHtml(f.tagline)}</p>` : ""}
@@ -443,11 +457,11 @@ function renderFooter(f: ApexFooter): string {
   </footer>`;
 }
-export function renderApexPage(page: ApexPage): string {
-  const { head, brand } = page;
-  const theme = page.theme ?? "light";
-  const css = (brand.fontFaceCss ?? "") + brand.tokensCss + APEX_STRUCTURAL_CSS;
-  const sections = page.sections.map(renderSection).join("\n\n    ");
+// All <title>/meta/link/script tags for an ApexHead — the single source both
+// renderApexPage and any other head (e.g. page-render's wrapInLayout) splice
+// into their own <head>. Extracted verbatim from renderApexPage so existing
+// output stays byte-identical (see render.test.ts regression coverage).
+export function renderApexHeadTags(head: ApexHead): string {
   const ogUrl =
     head.canonicalUrl !== undefined
       ? `\n    <meta property="og:url" content="${escapeHtml(head.canonicalUrl)}" />`
@@ -495,26 +509,42 @@ export function renderApexPage(page: ApexPage): string {
     .join("");
   const schema =
     head.schemaJson !== undefined
-      ? `\n    <script type="application/ld+json">${JSON.stringify(head.schemaJson)}</script>`
+      ? `\n    <script type="application/ld+json">${scriptSafeJsonHtml(head.schemaJson)}</script>`
       : "";
+  const metaDescription = head.description
+    ? `\n    <meta name="description" content="${escapeHtml(head.description)}" />`
+    : "";
+  const ogDescription = head.description
+    ? `\n    <meta property="og:description" content="${escapeHtml(head.description)}" />`
+    : "";
+  return `<title>${escapeHtml(head.title)}</title>${metaDescription}
+    <meta property="og:title" content="${escapeHtml(head.title)}" />${ogDescription}
+    <meta property="og:type" content="website" />${ogUrl}${ogImage}${siteName}${locale}${twitterCard}${twitterSite}${favicon}${canonical}${alternates}${robots}${preconnects}${schema}`;
+}
+export function renderApexPage(page: ApexPage): string {
+  const { head, brand } = page;
+  const theme = page.theme ?? "light";
+  // Brand-CSS ist app-authored (Trust-Boundary siehe Datei-Header), kein Tenant-Input.
+  const cssHtml = (brand.fontFaceCss ?? "") + brand.tokensCss + APEX_STRUCTURAL_CSS;
+  const sectionsHtml = page.sections.map(renderSection).join("\n\n    ");
   return `<!doctype html>
 <html lang="${escapeHtml(head.lang)}">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
-    <title>${escapeHtml(head.title)}</title>
-    <meta name="description" content="${escapeHtml(head.description)}" />
-    <meta property="og:title" content="${escapeHtml(head.title)}" />
-    <meta property="og:description" content="${escapeHtml(head.description)}" />
-    <meta property="og:type" content="website" />${ogUrl}${ogImage}${siteName}${locale}${twitterCard}${twitterSite}${favicon}${canonical}${alternates}${robots}${preconnects}${schema}
-    <style>${css}</style>
+    ${renderApexHeadTags(head)}
+    <style>${cssHtml}</style>
   </head>
   <body${theme === "dark" ? ` class="apex-dark"` : ""}>
     ${renderApexHeader(page.header)}
-    ${sections}
+    ${sectionsHtml}
     ${renderFooter(page.footer)}
+    ${APEX_LIGHTBOX_HTML}
+    ${APEX_LIGHTBOX_SCRIPT}
   </body>
 </html>`;
 }

package/src/apex/lightbox.ts ADDED Viewed

@@ -0,0 +1,50 @@
+// Vanilla lightbox for Apex marketing pages — click .shot-frame img to enlarge.
+// Injected by renderApexPage; no React, no per-app wiring.
+export const APEX_LIGHTBOX_HTML = `<dialog id="apex-lightbox" class="apex-lightbox" aria-label="Screenshot preview">
+  <button type="button" class="apex-lightbox__close" aria-label="Close">&times;</button>
+  <img class="apex-lightbox__img" alt="" />
+</dialog>`;
+// Split from APEX_LIGHTBOX_SCRIPT so APEX_LIGHTBOX_SCRIPT_CSP_HASH hashes
+// exactly the bytes the browser executes — CSP's script-src hash-source
+// covers the content between <script> and </script>, nothing more/less.
+const APEX_LIGHTBOX_SCRIPT_BODY = `
+(function () {
+  var dlg = document.getElementById("apex-lightbox");
+  if (!dlg) return;
+  var img = dlg.querySelector(".apex-lightbox__img");
+  var closeBtn = dlg.querySelector(".apex-lightbox__close");
+  if (!img || !closeBtn) return;
+  function open(src, alt) {
+    img.src = src;
+    img.alt = alt || "";
+    if (typeof dlg.showModal === "function") dlg.showModal();
+  }
+  function close() {
+    if (dlg.open) dlg.close();
+  }
+  document.addEventListener("click", function (e) {
+    var t = e.target;
+    if (!(t instanceof HTMLImageElement)) return;
+    if (!t.closest(".shot-frame")) return;
+    e.preventDefault();
+    open(t.currentSrc || t.src, t.alt);
+  });
+  closeBtn.addEventListener("click", close);
+  dlg.addEventListener("click", function (e) {
+    if (e.target === dlg) close();
+  });
+  dlg.addEventListener("cancel", function (e) {
+    e.preventDefault();
+    close();
+  });
+})();
+`;
+/** ponytail: one delegated listener; no-op when no .shot-frame on the page. */
+export const APEX_LIGHTBOX_SCRIPT = `<script>${APEX_LIGHTBOX_SCRIPT_BODY}</script>`;
+// CSP hash-source for the inline script above; apex output is often
+// pre-rendered, so a per-request nonce can't work. Guarded by lightbox.test.ts.
+export const APEX_LIGHTBOX_SCRIPT_CSP_HASH = "sha256-f+hHLpDuQsjmtFZCjdM13D9NaMTCyOKaawAhfLf/X9o=";

package/src/dispatcher/__tests__/contract.test.ts CHANGED Viewed

@@ -60,6 +60,9 @@ function createFakeDispatcher(options?: {
       return result;
     },
     statusStore,
+    async *stream() {
+      // streams unsupported in the sync fake — empty generator
+    },
     pendingWrites: () => pendingWritesStore,
     pendingFiles: () => pendingFilesStore,
     setStatus(next) {

package/src/dispatcher/index.ts CHANGED Viewed

@@ -9,6 +9,8 @@ export type {
   PendingWrite,
   QueryOpts,
   QueryResult,
+  StreamOpts,
   WriteOpts,
   WriteResult,
 } from "./types";
+export { StreamFrame, type StreamFrameEvent } from "./types";

package/src/dispatcher/types.ts CHANGED Viewed

@@ -149,6 +149,22 @@ export type QueryOpts = {
   readonly signal?: AbortSignal;
 };
+export type StreamOpts = {
+  readonly signal?: AbortSignal;
+};
+// SSE frame event names for POST /api/stream — shared across the server route,
+// the live-dispatcher wire parser, and their tests so a typo on one side
+// fails the type-checker instead of the integration test.
+export const StreamFrame = {
+  chunk: "chunk",
+  ping: "ping",
+  done: "done",
+  error: "error",
+} as const;
+export type StreamFrameEvent = (typeof StreamFrame)[keyof typeof StreamFrame];
 // ---------------------------------------------------------------------------
 // The contract
 // ---------------------------------------------------------------------------
@@ -173,6 +189,17 @@ export type Dispatcher = {
   batch(commands: readonly Command[], opts?: WriteOpts): Promise<BatchResult>;
+  // Dispatcher-driven SSE (`POST /api/stream`, #1380/#1382). Yields one
+  // value per `chunk` frame. Terminal `done` ends the generator; terminal
+  // `error` rejects with a DispatcherError (thrown). Heartbeat `ping`
+  // frames are swallowed. Abort via opts.signal cancels the fetch and
+  // rejects with code `aborted`.
+  stream<TChunk = unknown>(
+    type: string,
+    payload: unknown,
+    opts?: StreamOpts,
+  ): AsyncGenerator<TChunk, void, undefined>;
   // --- Status ---
   // Subscribe/Emit-Store für Online/Offline/Syncing-Transitions. Konsumenten

package/src/form/__tests__/submit.test.ts CHANGED Viewed

@@ -21,6 +21,7 @@ function makeDispatcher(response?: WriteResult): Dispatcher & {
     async batch() {
       return { isSuccess: true, results: [] };
     },
+    async *stream() {},
     statusStore: createStore("online"),
     pendingWrites: () => [],
     pendingFiles: () => [],
@@ -166,6 +167,7 @@ describe("createFormController — submit()", () => {
         return { isSuccess: true as const, results: [] };
       },
       statusStore: createStore("online"),
+      async *stream() {},
       pendingWrites: () => [],
       pendingFiles: () => [],
     };
@@ -269,6 +271,7 @@ describe("createFormController — submit()", () => {
         return { isSuccess: true as const, results: [] };
       },
       statusStore: createStore("online"),
+      async *stream() {},
       pendingWrites: () => [],
       pendingFiles: () => [],
     };

package/src/form/form-controller.ts CHANGED Viewed

@@ -197,7 +197,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     getSnapshot: snapshotStore.getSnapshot,
     subscribe: snapshotStore.subscribe,
     setField(key, value) {
-      // Skip work when the new value is identical to the current one —
+      // skip: value unchanged, avoid notify/re-render on identical set
       // avoids a notify + re-render for "setField with same value" which
       // happens a lot in controlled inputs on every keystroke of an
       // untouched field.
@@ -206,7 +206,7 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
       invalidate();
     },
     setValues(partial) {
-      // Detect any effective change before rebuilding — setValues with a
+      // skip: partial matches current values, avoid no-op notify
       // partial that matches current values shouldn't fire listeners.
       let changed = false;
       const v = values as Record<string, unknown>; // @cast-boundary form-values
@@ -217,15 +217,18 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
           break;
         }
       }
+      // skip: no key in partial actually changed, avoid no-op notify
       if (!changed) return;
       values = { ...values, ...partial };
       invalidate();
     },
     clearErrors(path) {
       if (path === undefined) {
+        // skip: no errors present, avoid no-op notify
         if (Object.keys(errors).length === 0) return;
         errors = Object.freeze({});
       } else {
+        // skip: path has no error entry, avoid no-op notify
         if (!(path in errors)) return;
         const next: Record<string, readonly FieldIssue[]> = { ...errors };
         delete next[path];
@@ -239,8 +242,8 @@ export function createFormController<TValues extends FormValues, TCtx = unknown>
     },
     validate: runValidate,
     reset() {
-      // Cheap no-op when already at baseline and no errors to clear.
       const alreadyClean = !snapshotStore.getSnapshot().isDirty && Object.keys(errors).length === 0;
+      // skip: already at baseline with no errors, no-op reset
       if (alreadyClean) return;
       values = { ...initial };
       errors = Object.freeze({});

package/src/format/__tests__/format.test.ts CHANGED Viewed

@@ -68,4 +68,25 @@ describe("applyFormatSpec — timestamp/date (formatDateCell-Pfad)", () => {
     expect(applyFormatSpec({ format: "timestamp" }, "kein-datum")).toBe("kein-datum");
     expect(applyFormatSpec({ format: "date" }, "kein-datum")).toBe("kein-datum");
   });
+  test("offset-lose Timestamps (kein Z/Offset) fallen NICHT auf den Rohstring zurück", () => {
+    // Temporal.Instant.from is stricter than the old `new Date(raw)` —
+    // without a UTC designator/offset it throws. Both forms must still
+    // format instead of passing through raw (see toInstant fallback in
+    // index.ts).
+    const withoutOffset = "2026-01-15T12:00:00";
+    const withoutTime = "2026-01-15 12:00:00";
+    for (const raw of [withoutOffset, withoutTime]) {
+      const out = applyFormatSpec({ format: "timestamp", locale: "en-US" }, raw);
+      expect(out).not.toBe(raw);
+      expect(out).toContain("2026");
+    }
+  });
+  test("offset-loser Timestamp im date-Format fällt NICHT auf den Rohstring zurück", () => {
+    const withoutOffset = "2026-01-15T12:00:00";
+    const out = applyFormatSpec({ format: "date", locale: "en-US" }, withoutOffset);
+    expect(out).not.toBe(withoutOffset);
+    expect(out).toContain("2026");
+  });
 });

package/src/format/__tests__/html-template.test.ts ADDED Viewed

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { html, RawHtml, raw } from "../html-template";
+const XSS = `<script>alert("1")</script>`;
+describe("html tagged template", () => {
+  test("escapes string interpolations", () => {
+    expect(html`<p>${XSS}</p>`.toString()).toBe(
+      "<p>&lt;script&gt;alert(&quot;1&quot;)&lt;/script&gt;</p>",
+    );
+  });
+  test("escapes attribute breakouts (double quotes)", () => {
+    const href = `"><img src=x onerror=alert(1)>`;
+    const out = html`<a href="${href}">x</a>`.toString();
+    expect(out).not.toContain('"><img');
+    expect(out).toContain("&quot;&gt;&lt;img");
+  });
+  test("raw() passes prerendered markup through unchanged", () => {
+    expect(html`<div>${raw("<b>ok</b>")}</div>`.toString()).toBe("<div><b>ok</b></div>");
+  });
+  test("nested html`...` fragments are not double-escaped", () => {
+    const item = html`<li>${"a & b"}</li>`;
+    expect(html`<ul>${item}</ul>`.toString()).toBe("<ul><li>a &amp; b</li></ul>");
+  });
+  test("arrays are joined with each element escaped", () => {
+    const items = ["<x>", "y"].map((v) => html`<li>${v}</li>`);
+    expect(html`<ul>${items}</ul>`.toString()).toBe("<ul><li>&lt;x&gt;</li><li>y</li></ul>");
+  });
+  test("null and undefined render as empty string", () => {
+    expect(html`<p>${null}${undefined}</p>`.toString()).toBe("<p></p>");
+  });
+  test("numbers and booleans render via String()", () => {
+    expect(html`<td>${42}${false}</td>`.toString()).toBe("<td>42false</td>");
+  });
+  test("toString() makes fragments usable in plain string contexts", () => {
+    const fragment = html`<p>${"<i>"}</p>`;
+    expect(`${fragment}`).toBe("<p>&lt;i&gt;</p>");
+    expect(fragment).toBeInstanceOf(RawHtml);
+  });
+});

package/src/format/escape.ts CHANGED Viewed

@@ -22,3 +22,58 @@ export function escapeXml(s: string): string {
     .replace(/"/g, "&quot;")
     .replace(/'/g, "&apos;");
 }
+// Strips ASCII control chars + space (codepoints 0x00-0x20 and 0x7f) — the
+// same characters browsers strip before scheme detection. `.trim()` alone
+// only removes leading/trailing whitespace, so a scheme like
+// "java\tscript:" (tab embedded mid-scheme) survives to isSafeHref's regex
+// check below, breaks its character class before the ":", falls through to
+// `return true`, and the browser then normalizes it back to "javascript:"
+// and executes it. Written as a char-code filter rather than a regex range
+// to avoid embedding literal control characters in source.
+export function stripControlChars(value: string): string {
+  let result = "";
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code > 0x20 && code !== 0x7f) result += ch;
+  }
+  return result;
+}
+// http(s)/mailto or scheme-less (relative/anchor) allowed; javascript:,
+// data:, vbscript:, etc. rejected. Shared between renderer-web's Link
+// primitive and page-render's server-side markdown renderer (both take
+// untrusted tenant-authored hrefs) — no sanitizer dependency needed for a
+// four-line regex check.
+// Browsers decode HTML character references (&colon;, &#58;, &#x3a;, &Tab;,
+// &#9;, ...) while parsing the href attribute, before the URL parser ever
+// sees the value — so "javascript&colon;alert(1)" and "java&Tab;script:"
+// both normalize to an executable javascript: URL at click time even though
+// neither contains a literal ":" for the regex below to catch. Decode
+// (not delete) so the scheme check sees what the browser will execute —
+// deleting "&colon;" would leave no colon at all, which reads as a safe
+// scheme-less href, exactly backwards.
+const NAMED_HTML_ENTITY_CHARS: Record<string, string> = {
+  colon: ":",
+  tab: "\t",
+  newline: "\n",
+  semi: ";",
+  amp: "&",
+};
+function decodeHtmlEntities(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z][a-z0-9]*);/gi, (match, entity: string) => {
+    if (entity[0] === "#") {
+      const isHex = entity[1]?.toLowerCase() === "x";
+      const code = Number.parseInt(isHex ? entity.slice(2) : entity.slice(1), isHex ? 16 : 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+    }
+    return NAMED_HTML_ENTITY_CHARS[entity.toLowerCase()] ?? match;
+  });
+}
+export function isSafeHref(href: string): boolean {
+  const trimmed = stripControlChars(decodeHtmlEntities(href)).toLowerCase();
+  if (!/^[a-z][a-z0-9+.-]*:/.test(trimmed)) return true;
+  return /^(?:https?|mailto):/.test(trimmed);
+}

package/src/format/html-template.ts ADDED Viewed

@@ -0,0 +1,49 @@
+// html`...` — Tagged-Template, das jede Interpolation automatisch HTML-escaped.
+// Macht Escaping strukturell statt per-Callsite-Konvention: vergessen ist
+// unmöglich, bewusst rohes HTML braucht ein explizites raw(). Der
+// HTML-Escape-Guard (kumiko-guards) akzeptiert html`...` als safe.
+import { escapeHtml } from "./escape";
+export class RawHtml {
+  readonly html: string;
+  constructor(html: string) {
+    this.html = html;
+  }
+  toString(): string {
+    return this.html;
+  }
+}
+/** Markiert bereits escaptes/vertrauenswürdiges Markup für html`...`. */
+export function raw(html: string): RawHtml {
+  return new RawHtml(html);
+}
+export type HtmlValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | RawHtml
+  | ReadonlyArray<HtmlValue>;
+function renderValue(value: HtmlValue): string {
+  if (value === null || value === undefined) return "";
+  if (value instanceof RawHtml) return value.html;
+  if (Array.isArray(value)) return value.map(renderValue).join("");
+  if (typeof value === "string") return escapeHtml(value);
+  return String(value);
+}
+// Rückgabe ist RawHtml, damit Fragmente verschachtelbar sind ohne doppelt zu
+// escapen: `html`<div>${item}</div>`` innerhalb eines äußeren html`...`
+// passiert unverändert durch. toString() liefert das fertige Markup.
+export function html(strings: TemplateStringsArray, ...values: ReadonlyArray<HtmlValue>): RawHtml {
+  let out = strings[0] ?? "";
+  values.forEach((value, i) => {
+    out += renderValue(value) + (strings[i + 1] ?? "");
+  });
+  return new RawHtml(out);
+}

package/src/format/index.ts CHANGED Viewed

@@ -1,6 +1,31 @@
 // Pure format utilities — no web or platform dependencies.
 // Shared between renderer-web, renderer-native, and server-side tests.
+import { Temporal } from "temporal-polyfill";
+function toPlainDate(raw: string): Temporal.PlainDate {
+  try {
+    return Temporal.PlainDate.from(raw);
+  } catch {
+    // "date"-typed field stored as a full instant (day-boundary timestamp) —
+    // take the calendar date in the local zone rather than fail.
+    return toInstant(raw).toZonedDateTimeISO(Temporal.Now.timeZoneId()).toPlainDate();
+  }
+}
+// Temporal.Instant.from is stricter than the `new Date(raw)` this replaced:
+// it requires a UTC designator/offset (Z/+hh:mm). Timestamps without one
+// (e.g. "2026-07-18T12:00:00", still valid input to `new Date`) throw here
+// instead of parsing — fall back to reading them as a local wall-clock time,
+// same posture as toPlainDate's own fallback above.
+export function toInstant(raw: string): Temporal.Instant {
+  try {
+    return Temporal.Instant.from(raw);
+  } catch {
+    return Temporal.PlainDateTime.from(raw).toZonedDateTime(Temporal.Now.timeZoneId()).toInstant();
+  }
+}
 function formatDateCell(
   value: unknown,
   type: string,
@@ -12,17 +37,25 @@ function formatDateCell(
 ): string {
   try {
     const raw = typeof value === "string" ? value : String(value);
-    const date = new Date(raw);
-    if (Number.isNaN(date.getTime())) return raw;
     const locale = opts?.locale;
     if (opts?.dateStyle || opts?.timeStyle) {
-      return date.toLocaleString(locale, {
+      if (type === "date") {
+        // ponytail: timeStyle is ignored here on purpose — a PlainDate has no
+        // time component to format, so a timeStyle-only "date" field falls
+        // back to PlainDate's default dateStyle instead of rendering a time.
+        return toPlainDate(raw).toLocaleString(locale, {
+          dateStyle: opts.dateStyle,
+        });
+      }
+      return toInstant(raw).toLocaleString(locale, {
         dateStyle: opts.dateStyle,
         timeStyle: opts.timeStyle,
       });
     }
-    if (type === "date") return date.toLocaleDateString(locale);
-    return date.toLocaleString(locale, {
+    if (type === "date") {
+      return toPlainDate(raw).toLocaleString(locale);
+    }
+    return toInstant(raw).toLocaleString(locale, {
       year: "numeric",
       month: "short",
       day: "numeric",
@@ -34,7 +67,8 @@ function formatDateCell(
   }
 }
-export { escapeHtml, escapeHtmlAttr, escapeXml } from "./escape";
+export { escapeHtml, escapeHtmlAttr, escapeXml, isSafeHref, stripControlChars } from "./escape";
+export { type HtmlValue, html, RawHtml, raw } from "./html-template";
 export function applyFormatSpec(
   spec: { format: string } & Record<string, unknown>,
   value: unknown,

package/src/index.ts CHANGED Viewed

@@ -34,9 +34,11 @@ export type {
   PendingWrite,
   QueryOpts,
   QueryResult,
+  StreamOpts,
   WriteOpts,
   WriteResult,
 } from "./dispatcher";
+export { StreamFrame, type StreamFrameEvent } from "./dispatcher";
 export type {
   FieldConditionPredicate,
   FieldConditions,
@@ -51,7 +53,19 @@ export type {
   SubmitResult,
 } from "./form";
 export { createFormController } from "./form";
-export { applyFormatSpec, escapeHtml, escapeHtmlAttr, escapeXml } from "./format";
+export {
+  applyFormatSpec,
+  escapeHtml,
+  escapeHtmlAttr,
+  escapeXml,
+  type HtmlValue,
+  html,
+  isSafeHref,
+  RawHtml,
+  raw,
+  stripControlChars,
+  toInstant,
+} from "./format";
 export type {
   NavDefinition,
   NavNode,

package/src/locale-routing/__tests__/locale-routing.test.ts ADDED Viewed

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+import { createLocaleRouter } from "../index";
+type MoneyHorsePage = "home" | "features" | "rechner" | "budget" | "ltv";
+const moneyHorseRouter = createLocaleRouter<MoneyHorsePage>({
+  defaultLocale: "de",
+  prefixedLocales: ["en"],
+  routes: {
+    home: { de: "/", en: "/en" },
+    features: { de: "/funktionen", en: "/en/features" },
+    rechner: { de: "/rechner", en: "/en/rechner" },
+    budget: { de: "/budget-rechner", en: "/en/budget-rechner" },
+    ltv: { de: "/beleihungsauslauf", en: "/en/beleihungsauslauf" },
+  },
+  localeHints: { en: ["/features"] },
+});
+describe("createLocaleRouter money-horse config", () => {
+  test("detectLang: prefixed, default, legacy hint", () => {
+    expect(moneyHorseRouter.detectLang("/")).toBe("de");
+    expect(moneyHorseRouter.detectLang("/en")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/en/rechner")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/rechner")).toBe("de");
+    expect(moneyHorseRouter.detectLang("/features")).toBe("en");
+    expect(moneyHorseRouter.detectLang("/features/")).toBe("en");
+  });
+  test("publicPath returns canonical paths per locale", () => {
+    expect(moneyHorseRouter.publicPath("features", "de")).toBe("/funktionen");
+    expect(moneyHorseRouter.publicPath("features", "en")).toBe("/en/features");
+    expect(moneyHorseRouter.publicPath("rechner", "en")).toBe("/en/rechner");
+  });
+  test("resolvePage maps canonical and legacy paths", () => {
+    expect(moneyHorseRouter.resolvePage("/funktionen")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/en/features")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/features")).toBe("features");
+    expect(moneyHorseRouter.resolvePage("/en/rechner")).toBe("rechner");
+    expect(moneyHorseRouter.resolvePage("/login")).toBeUndefined();
+  });
+  test("altLocalePath keeps logical page across locales", () => {
+    expect(moneyHorseRouter.altLocalePath("/en")).toBe("/");
+    expect(moneyHorseRouter.altLocalePath("/")).toBe("/en");
+    expect(moneyHorseRouter.altLocalePath("/en/features")).toBe("/funktionen");
+    expect(moneyHorseRouter.altLocalePath("/funktionen")).toBe("/en/features");
+    expect(moneyHorseRouter.altLocalePath("/features")).toBe("/funktionen");
+    expect(moneyHorseRouter.altLocalePath("/en/rechner")).toBe("/rechner");
+    expect(moneyHorseRouter.altLocalePath("/rechner")).toBe("/en/rechner");
+    expect(moneyHorseRouter.altLocalePath("/unknown")).toBe("/en");
+  });
+  test("sectionAnchor attaches fragment to page path", () => {
+    expect(moneyHorseRouter.sectionAnchor("home", "de", "pricing")).toBe("/#pricing");
+    expect(moneyHorseRouter.sectionAnchor("home", "en", "pricing")).toBe("/en#pricing");
+  });
+});
+type PublicStatusPage = "home" | "developers";
+const publicStatusRouter = createLocaleRouter<PublicStatusPage>({
+  defaultLocale: "de",
+  prefixedLocales: ["en"],
+  routes: {
+    home: { de: "/", en: "/en" },
+    developers: { de: "/developers", en: "/en/developers" },
+  },
+});
+describe("createLocaleRouter publicstatus config", () => {
+  test("altLocalePath for developers", () => {
+    expect(publicStatusRouter.altLocalePath("/en/developers")).toBe("/developers");
+    expect(publicStatusRouter.altLocalePath("/developers")).toBe("/en/developers");
+  });
+});
+describe("createLocaleRouter inverted default (website-style)", () => {
+  const router = createLocaleRouter({
+    defaultLocale: "en",
+    prefixedLocales: ["de"],
+    prefixFor: () => "/de",
+    routes: {
+      home: { en: "/", de: "/de" },
+    },
+  });
+  test("detectLang with non-default prefix locale", () => {
+    expect(router.detectLang("/")).toBe("en");
+    expect(router.detectLang("/de")).toBe("de");
+    expect(router.altLocalePath("/")).toBe("/de");
+    expect(router.altLocalePath("/de")).toBe("/");
+  });
+});
+describe("createLocaleRouter homePage validation", () => {
+  test("throws at construction when homePage has no routes entry", () => {
+    expect(() =>
+      createLocaleRouter({
+        defaultLocale: "de",
+        prefixedLocales: ["en"],
+        routes: { features: { de: "/funktionen", en: "/en/features" } },
+      }),
+    ).toThrow(/homePage/);
+  });
+  test("publicPath throws instead of crashing when page is missing from routes", () => {
+    const router = createLocaleRouter<"home" | "features">({
+      defaultLocale: "de",
+      prefixedLocales: ["en"],
+      routes: { home: { de: "/", en: "/en" } } as unknown as Record<
+        "home" | "features",
+        Record<string, string>
+      >,
+    });
+    expect(() => router.publicPath("features", "de")).toThrow(/no path for page/);
+  });
+});

package/src/locale-routing/index.ts ADDED Viewed

@@ -0,0 +1,144 @@
+export type LocaleRouterConfig<TPage extends string> = {
+  /** Canonical default, usually "de". No URL prefix. */
+  readonly defaultLocale: string;
+  /** Locales that get a URL prefix, e.g. ["en"] → /en/... */
+  readonly prefixedLocales: readonly string[];
+  /** Prefix segment per locale, default: locale code ("en" → "/en"). */
+  readonly prefixFor?: (locale: string) => string;
+  /** Logical page → path per locale. Every page must define defaultLocale path. */
+  readonly routes: Record<TPage, Record<string, string>>;
+  /** Legacy slug-only paths for detectLang/resolvePage, e.g. { en: ["/features"] }. */
+  readonly localeHints?: Readonly<Record<string, readonly string[]>>;
+  /** Fallback page when altLocalePath cannot resolve pathname. Default: "home". */
+  readonly homePage?: TPage;
+};
+export type LocaleRouter<TPage extends string> = {
+  detectLang(pathname: string): string;
+  publicPath(page: TPage, locale: string): string;
+  resolvePage(pathname: string): TPage | undefined;
+  altLocalePath(pathname: string): string;
+  sectionAnchor(page: TPage, locale: string, fragment: string): string;
+};
+function normalizePath(pathname: string): string {
+  if (pathname === "" || pathname === "/") return "/";
+  return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
+function defaultPrefixFor(locale: string): string {
+  return `/${locale}`;
+}
+function stripLocalePrefix(
+  path: string,
+  locale: string,
+  prefixFor: (locale: string) => string,
+): string {
+  const prefix = prefixFor(locale);
+  if (path === prefix) return "/";
+  if (path.startsWith(`${prefix}/`)) return path.slice(prefix.length);
+  return path;
+}
+export function createLocaleRouter<TPage extends string>(
+  config: LocaleRouterConfig<TPage>,
+): LocaleRouter<TPage> {
+  const {
+    defaultLocale,
+    prefixedLocales,
+    routes,
+    localeHints = {},
+    prefixFor = defaultPrefixFor,
+    homePage = "home" as TPage,
+  } = config;
+  if (routes[homePage] === undefined) {
+    throw new Error(
+      `locale-routing: homePage "${String(homePage)}" has no entry in routes — altLocalePath's fallback would throw at request time`,
+    );
+  }
+  const pathIndex = new Map<string, { page: TPage; locale: string }>();
+  for (const [page, localePaths] of Object.entries(routes) as [TPage, Record<string, string>][]) {
+    for (const [locale, routePath] of Object.entries(localePaths)) {
+      pathIndex.set(normalizePath(routePath), { page, locale });
+    }
+  }
+  for (const [hintLocale, hints] of Object.entries(localeHints)) {
+    for (const hint of hints) {
+      const normalizedHint = normalizePath(hint);
+      if (pathIndex.has(normalizedHint)) continue;
+      for (const [page, localePaths] of Object.entries(routes) as [
+        TPage,
+        Record<string, string>,
+      ][]) {
+        const canonical = localePaths[hintLocale];
+        if (canonical === undefined) continue;
+        const canonicalNorm = normalizePath(canonical);
+        const hintSlug = stripLocalePrefix(normalizedHint, hintLocale, prefixFor);
+        const canonicalSlug = stripLocalePrefix(canonicalNorm, hintLocale, prefixFor);
+        if (hintSlug === canonicalSlug) {
+          pathIndex.set(normalizedHint, { page, locale: hintLocale });
+          break;
+        }
+      }
+    }
+  }
+  function detectLang(pathname: string): string {
+    const path = normalizePath(pathname);
+    for (const locale of prefixedLocales) {
+      const prefix = prefixFor(locale);
+      if (path === prefix || path.startsWith(`${prefix}/`)) return locale;
+    }
+    const resolved = pathIndex.get(path);
+    if (resolved !== undefined) return resolved.locale;
+    for (const [locale, hints] of Object.entries(localeHints)) {
+      if (hints.some((hint) => normalizePath(hint) === path)) return locale;
+    }
+    return defaultLocale;
+  }
+  function resolvePage(pathname: string): TPage | undefined {
+    return pathIndex.get(normalizePath(pathname))?.page;
+  }
+  function publicPath(page: TPage, locale: string): string {
+    const localePaths = routes[page];
+    const routePath = localePaths?.[locale];
+    if (routePath === undefined) {
+      throw new Error(`locale-routing: no path for page "${String(page)}" locale "${locale}"`);
+    }
+    return routePath;
+  }
+  // Binary toggle (defaultLocale <-> prefixedLocales[0]) — altLocalePath has
+  // no way to target a specific alt locale beyond the first prefixed one.
+  // Fine for the current bilingual (de/en) setup; a third prefixed locale
+  // needs altLocalePath to take an explicit targetLocale param instead.
+  function otherLocale(currentLocale: string): string {
+    if (currentLocale === defaultLocale) {
+      return prefixedLocales[0] ?? defaultLocale;
+    }
+    return defaultLocale;
+  }
+  function altLocalePath(pathname: string): string {
+    const path = normalizePath(pathname);
+    const resolved = pathIndex.get(path);
+    const targetLocale = otherLocale(detectLang(pathname));
+    if (resolved !== undefined) {
+      return publicPath(resolved.page, targetLocale);
+    }
+    return publicPath(homePage, targetLocale);
+  }
+  function sectionAnchor(page: TPage, locale: string, fragment: string): string {
+    return `${publicPath(page, locale)}#${fragment}`;
+  }
+  return { detectLang, publicPath, resolvePage, altLocalePath, sectionAnchor };
+}

package/src/store/create-store.ts CHANGED Viewed

@@ -36,6 +36,7 @@ export function createStore<T>(initial: T): WritableStore<T> {
     },
     setState: (next) => {
       const nextValue = typeof next === "function" ? (next as (prev: T) => T)(snapshot) : next;
+      // skip: next value identical to snapshot, avoid notifying listeners
       if (Object.is(nextValue, snapshot)) return;
       snapshot = nextValue;
       for (const listener of listeners) listener();