@cosmicdrift/kumiko-renderer-web 0.46.0 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.40.1",
-    "@cosmicdrift/kumiko-headless": "0.40.1",
-    "@cosmicdrift/kumiko-renderer": "0.40.1",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.45.0",
+    "@cosmicdrift/kumiko-headless": "0.45.0",
+    "@cosmicdrift/kumiko-renderer": "0.45.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/__tests__/create-public-surface.test.tsx

@@ -0,0 +1,147 @@
+import { afterAll, afterEach, describe, expect, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, screen } from "@testing-library/react";
+import { createContext, type ReactNode, useContext } from "react";
+import type { ClientFeatureDefinition } from "../app/client-plugin";
+import { createPublicSurface } from "../app/create-public-surface";
+import { createMockDispatcher } from "./test-utils";
+
+function mountRoot(id = "root"): HTMLDivElement {
+  const existing = document.getElementById(id);
+  if (existing) existing.remove();
+  const root = document.createElement("div");
+  root.id = id;
+  document.body.appendChild(root);
+  return root as HTMLDivElement;
+}
+
+function setPath(path: string): void {
+  window.history.replaceState({}, "", path);
+}
+
+function dispatcher(): Dispatcher {
+  return createMockDispatcher({});
+}
+
+let appRoot: { unmount: () => void } | undefined;
+
+async function mount(options: Parameters<typeof createPublicSurface>[0]): Promise<void> {
+  await act(async () => {
+    appRoot = createPublicSurface(options).root;
+  });
+}
+
+describe("createPublicSurface", () => {
+  afterEach(() => {
+    if (appRoot !== undefined) {
+      act(() => {
+        // biome-ignore lint/style/noNonNullAssertion: TS can't narrow inside act() callback
+        appRoot!.unmount();
+      });
+      appRoot = undefined;
+    }
+    while (document.body.firstChild) document.body.removeChild(document.body.firstChild);
+    delete (window as unknown as { __KUMIKO_SCHEMA__?: unknown }).__KUMIKO_SCHEMA__;
+    setPath("/");
+  });
+
+  afterAll(() => {
+    delete (window as unknown as { __KUMIKO_SCHEMA__?: unknown }).__KUMIKO_SCHEMA__;
+  });
+
+  test("rendert die Route deren path auf den aktuellen Pfad matcht", async () => {
+    setPath("/login");
+    mountRoot();
+    await mount({
+      dispatcher: dispatcher(),
+      routes: [
+        { path: "/login", component: <div data-testid="login">login</div> },
+        { path: "/signup", component: <div data-testid="signup">signup</div> },
+      ],
+    });
+    expect(screen.getByTestId("login")).toBeTruthy();
+    expect(screen.queryByTestId("signup")).toBeNull();
+  });
+
+  test("ohne Match → fallback", async () => {
+    setPath("/nope");
+    mountRoot();
+    await mount({
+      dispatcher: dispatcher(),
+      routes: [{ path: "/login", component: <div data-testid="login">login</div> }],
+      fallback: <div data-testid="fallback">fallback</div>,
+    });
+    expect(screen.getByTestId("fallback")).toBeTruthy();
+    expect(screen.queryByTestId("login")).toBeNull();
+  });
+
+  test("injectSchema:false — ignoriert window.__KUMIKO_SCHEMA__ komplett (kein Topologie-Leak)", async () => {
+    // Ein Admin-Schema im Window darf NICHT zu gerenderter Admin-Nav/
+    // Topologie führen — die Surface liest das Global gar nicht, sie
+    // rendert ausschließlich die deklarierte Route.
+    setPath("/login");
+    (window as unknown as { __KUMIKO_SCHEMA__?: unknown }).__KUMIKO_SCHEMA__ = {
+      features: [
+        {
+          featureName: "secret-admin",
+          entities: {},
+          screens: [{ id: "secret-topology", type: "custom" }],
+        },
+      ],
+    };
+    mountRoot();
+    await mount({
+      dispatcher: dispatcher(),
+      routes: [{ path: "/login", component: <div data-testid="login">login</div> }],
+    });
+    expect(screen.getByTestId("login")).toBeTruthy();
+    expect(document.body.textContent).not.toContain("secret");
+    expect(document.body.textContent).not.toContain("topology");
+  });
+
+  test("clientFeatures: providers werden gestackt, gates aber NICHT (Surface bleibt öffentlich)", async () => {
+    const Ctx = createContext("absent");
+    function MarkerProvider({ children }: { readonly children: ReactNode }): ReactNode {
+      return <Ctx.Provider value="present">{children}</Ctx.Provider>;
+    }
+    function HideEverythingGate(): ReactNode {
+      return <div data-testid="gate-hijack">gate</div>;
+    }
+    function ProbeRoute(): ReactNode {
+      return <div data-testid="probe">{useContext(Ctx)}</div>;
+    }
+    const feature: ClientFeatureDefinition = {
+      name: "auth",
+      providers: [MarkerProvider],
+      gates: [HideEverythingGate],
+    };
+    setPath("/login");
+    mountRoot();
+    await mount({
+      dispatcher: dispatcher(),
+      clientFeatures: [feature],
+      routes: [{ path: "/login", component: <ProbeRoute /> }],
+    });
+    // Provider sichtbar (Context greift), Gate nicht angewandt.
+    expect(screen.getByTestId("probe").textContent).toBe("present");
+    expect(screen.queryByTestId("gate-hijack")).toBeNull();
+  });
+
+  test("shell wrappt den gematchten Content (Page-Chrome)", async () => {
+    setPath("/login");
+    mountRoot();
+    await mount({
+      dispatcher: dispatcher(),
+      routes: [{ path: "/login", component: <div data-testid="login">login</div> }],
+      shell: ({ children }) => <div data-testid="chrome">{children}</div>,
+    });
+    const chrome = screen.getByTestId("chrome");
+    expect(chrome.querySelector("[data-testid=login]")).not.toBeNull();
+  });
+
+  test("fehlendes #root → wirft mit hilfreicher Message", () => {
+    expect(() => createPublicSurface({ dispatcher: dispatcher(), routes: [] })).toThrow(
+      /#root not found/,
+    );
+  });
+});

package/src/app/create-public-surface.tsx

@@ -0,0 +1,108 @@
+import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import type { Dispatcher, LocaleResolver } from "@cosmicdrift/kumiko-headless";
+import {
+  DispatcherProvider,
+  kumikoDefaultTranslations,
+  LocaleProvider,
+  PrimitivesProvider,
+  type PrimitivesRegistry,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { defaultPrimitives } from "../primitives";
+import { ToastProvider } from "../primitives/toast";
+import { createBrowserLocaleResolver } from "./browser-locale";
+import { type ClientFeatureDefinition, stackWrappers } from "./client-plugin";
+
+// Apex-Surface — der öffentliche Gegenpart zu createKumikoApp. Mountet eine
+// schlanke, schema-LOSE Provider-Chain (Locale + Primitives + Dispatcher +
+// feature-providers) und rendert genau einen anhand des URL-Pfads gewählten
+// Content. Bewusst KEIN Schema, KEINE Nav, KEIN KumikoScreen: die Surface ist
+// anonym erreichbar, ein __KUMIKO_SCHEMA__-Inject würde Admin-Nav/Topologie an
+// Besucher leaken (injectSchema:false ist hier struktureller Default, kein Flag).
+//
+// `routes` sind app-authored React-Elemente — Auth-Screens et al. tragen
+// Callback-Props (loggedInHref usw.), die durch keine serialisierbare
+// ScreenDefinition passen würden; deshalb laufen sie über diesen Mount und
+// nicht über die Registry. Späterer Registry-Content (CMS/Landing) konvergiert
+// auf denselben Mount.
+//
+//   createPublicSurface({
+//     routes: [{ path: "/login", component: <LoginScreen ... /> }],
+//     fallback: <LoginScreen ... />,
+//     clientFeatures: [emailPasswordClient()],
+//     shell: ({ children }) => <MarketingChrome>{children}</MarketingChrome>,
+//   });
+
+export type PublicRoute = {
+  /** Exakter window.location.pathname-Match (match-once beim Mount; alle
+   *  Apex-Pages sind Full-Page-Reloads, kein SPA-Router). */
+  readonly path: string;
+  readonly component: ReactNode;
+};
+
+export type CreatePublicSurfaceOptions = {
+  readonly routes: readonly PublicRoute[];
+  /** Gerendert wenn kein route.path auf den aktuellen Pfad matcht. */
+  readonly fallback?: ReactNode;
+  readonly rootId?: string;
+  readonly locale?: LocaleResolver;
+  readonly primitives?: Partial<PrimitivesRegistry>;
+  /** Dispatcher für Handler-Calls (z.B. anonymer Deletion-Request). Auth-
+   *  Screens brauchen ihn nicht (fetch via auth-client), aber er steht für
+   *  dispatchende Public-Flows bereit. Default: createLiveDispatcher(). */
+  readonly dispatcher?: Dispatcher;
+  /** Feature-Client-Extensions — NUR `providers` + `translations` werden
+   *  gestackt. `gates` werden bewusst ignoriert: ein AuthGate würde die
+   *  öffentliche Surface hinter Login sperren. */
+  readonly clientFeatures?: readonly ClientFeatureDefinition[];
+  /** Page-Chrome um den gematchten Content (Apex-/Marketing-Layout). */
+  readonly shell?: (props: { readonly children: ReactNode }) => ReactNode;
+};
+
+function matchRoute(options: CreatePublicSurfaceOptions, pathname: string): ReactNode {
+  for (const route of options.routes) {
+    if (route.path === pathname) return route.component;
+  }
+  return options.fallback ?? null;
+}
+
+export function createPublicSurface(options: CreatePublicSurfaceOptions): { readonly root: Root } {
+  const rootId = options.rootId ?? "root";
+  const container = document.getElementById(rootId);
+  if (!container) {
+    throw new Error(
+      `createPublicSurface: DOM element #${rootId} not found. Make sure your HTML has a matching <div id="${rootId}"></div> before the bundle loads.`,
+    );
+  }
+
+  const dispatcher = options.dispatcher ?? createLiveDispatcher();
+  const primitives: PrimitivesRegistry = { ...defaultPrimitives, ...(options.primitives ?? {}) };
+  const localeResolver = options.locale ?? createBrowserLocaleResolver();
+
+  const clientFeatures = options.clientFeatures ?? [];
+  const providers = clientFeatures.flatMap((f) => f.providers ?? []);
+  const fallbackBundles = [
+    ...clientFeatures.flatMap((f) => (f.translations !== undefined ? [f.translations] : [])),
+    kumikoDefaultTranslations,
+  ];
+
+  const pathname = typeof window !== "undefined" ? window.location.pathname : "";
+  const matched = matchRoute(options, pathname);
+  const Shell = options.shell;
+  const content = Shell !== undefined ? <Shell>{matched}</Shell> : matched;
+
+  const tree = (
+    <LocaleProvider resolver={localeResolver} fallbackBundles={fallbackBundles}>
+      <PrimitivesProvider value={primitives}>
+        <DispatcherProvider dispatcher={dispatcher}>
+          <ToastProvider>{stackWrappers(providers, content)}</ToastProvider>
+        </DispatcherProvider>
+      </PrimitivesProvider>
+    </LocaleProvider>
+  );
+
+  const root = createRoot(container);
+  root.render(tree);
+  return { root };
+}

package/src/index.ts

@@ -87,6 +87,8 @@ export { createBrowserLocaleResolver } from "./app/browser-locale";
 export type { ClientFeatureDefinition } from "./app/client-plugin";
 export type { CreateKumikoAppOptions } from "./app/create-app";
 export { createKumikoApp } from "./app/create-app";
+export type { CreatePublicSurfaceOptions, PublicRoute } from "./app/create-public-surface";
+export { createPublicSurface } from "./app/create-public-surface";
 export type { KumikoLinkProps } from "./app/nav";
 export { KumikoLink, useBrowserNavApi } from "./app/nav";
 export type { AppLayoutProps } from "./layout/app-layout";