@cosmicdrift/kumiko-renderer 0.1.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@cosmicdrift/kumiko-renderer",
+  "version": "0.1.0",
+  "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
+  "license": "BUSL-1.1",
+  "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
+  "type": "module",
+  "kumiko": {
+    "runtime": "client"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@cosmicdrift/kumiko-framework": "workspace:*",
+    "@cosmicdrift/kumiko-headless": "workspace:*",
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.2.0",
+    "jsdom": "^29.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cosmicdriftgamestudio/kumiko-framework.git",
+    "directory": "packages/renderer"
+  },
+  "homepage": "https://kumiko.so",
+  "bugs": {
+    "url": "https://github.com/cosmicdriftgamestudio/kumiko-framework/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/__tests__/i18n.test.tsx

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+import type { LocaleResolver } from "@cosmicdrift/kumiko-headless";
+import { act, render, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, test } from "vitest";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  type TranslationsByLocale,
+  useLocale,
+  useTranslation,
+} from "../i18n";
+
+// Stateful resolver fixture: we drive locale changes with setState
+// and the test asserts re-render via subscribe.
+function makeStatefulResolver(initial: string): LocaleResolver {
+  let current = initial;
+  const listeners = new Set<() => void>();
+  return {
+    translate: (key) => key,
+    locale: () => current,
+    timeZone: () => "UTC",
+    subscribe: (l) => {
+      listeners.add(l);
+      return () => {
+        listeners.delete(l);
+      };
+    },
+    setLocale: (next) => {
+      current = next;
+      for (const l of listeners) l();
+    },
+  };
+}
+
+const wrap =
+  (resolver: LocaleResolver, fallbackBundles?: TranslationsByLocale[]) =>
+  ({ children }: { readonly children: ReactNode }): ReactNode => (
+    <LocaleProvider resolver={resolver} {...(fallbackBundles !== undefined && { fallbackBundles })}>
+      {children}
+    </LocaleProvider>
+  );
+
+describe("useTranslation — lookup order", () => {
+  test("App-Resolver wins when it returns a non-key value", () => {
+    const resolver: LocaleResolver = {
+      ...createStaticLocaleResolver({ locale: "de" }),
+      translate: (key) => (key === "hello" ? "Resolved by app" : key),
+    };
+    const { result } = renderHook(() => useTranslation(), { wrapper: wrap(resolver) });
+    expect(result.current("hello")).toBe("Resolved by app");
+  });
+
+  test("falls back to plugin-bundle for current locale", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo" }, en: { greet: "Hello" } }];
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: wrap(resolver, bundles),
+    });
+    expect(result.current("greet")).toBe("Hallo");
+  });
+
+  test("strips region for bundle lookup (de-AT → de)", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de-AT" });
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo" } }];
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: wrap(resolver, bundles),
+    });
+    expect(result.current("greet")).toBe("Hallo");
+  });
+
+  test("falls back to fallbackLocale (en) when current locale missing", () => {
+    const resolver = createStaticLocaleResolver({ locale: "fr" });
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo" }, en: { greet: "Hello" } }];
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: wrap(resolver, bundles),
+    });
+    expect(result.current("greet")).toBe("Hello");
+  });
+
+  test("returns key as-is when nothing resolves", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const { result } = renderHook(() => useTranslation(), { wrapper: wrap(resolver) });
+    expect(result.current("missing.key")).toBe("missing.key");
+  });
+
+  test("interpolates {param}-placeholders from params arg", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo {name}!" } }];
+    const { result } = renderHook(() => useTranslation(), {
+      wrapper: wrap(resolver, bundles),
+    });
+    expect(result.current("greet", { name: "Marc" })).toBe("Hallo Marc!");
+  });
+});
+
+describe("useTranslation — re-render on locale change", () => {
+  test("subscribe fires when setLocale runs, hook returns new value", () => {
+    const resolver = makeStatefulResolver("de");
+    const bundles: TranslationsByLocale[] = [{ de: { greet: "Hallo" }, en: { greet: "Hello" } }];
+
+    function Probe(): ReactNode {
+      const t = useTranslation();
+      return <span data-testid="msg">{t("greet")}</span>;
+    }
+
+    const { getByTestId } = render(
+      <LocaleProvider resolver={resolver} fallbackBundles={bundles}>
+        <Probe />
+      </LocaleProvider>,
+    );
+    expect(getByTestId("msg").textContent).toBe("Hallo");
+
+    act(() => {
+      resolver.setLocale?.("en");
+    });
+    expect(getByTestId("msg").textContent).toBe("Hello");
+  });
+});
+
+describe("useLocale", () => {
+  test("returns the resolver", () => {
+    const resolver = createStaticLocaleResolver({ locale: "de" });
+    const { result } = renderHook(() => useLocale(), { wrapper: wrap(resolver) });
+    expect(result.current.locale()).toBe("de");
+  });
+});

package/src/__tests__/qn.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "vitest";
+import { lastSegment } from "../app/qn";
+
+describe("lastSegment", () => {
+  test("strips feature-prefix from screen-QN", () => {
+    expect(lastSegment("publicstatus:screen:component-edit")).toBe("component-edit");
+  });
+
+  test("strips feature-prefix from nav-QN", () => {
+    expect(lastSegment("shop:nav:catalog")).toBe("catalog");
+  });
+
+  test("strips feature-prefix from workspace-QN", () => {
+    expect(lastSegment("admin:workspace:disposition")).toBe("disposition");
+  });
+
+  test("returns short-form input unchanged", () => {
+    // Defensive default — an Author who already passes a short id
+    // shouldn't get a misformatted result.
+    expect(lastSegment("component-edit")).toBe("component-edit");
+  });
+
+  test("strips only the LAST segment, not the first", () => {
+    // The QN convention is `<feature>:<kind>:<short-id>`. lastIndexOf
+    // ensures kebab-ids that themselves contain colons (defensive —
+    // kebab spec rejects them, but the helper shouldn't break).
+    expect(lastSegment("a:b:c:d")).toBe("d");
+  });
+
+  test("handles empty string", () => {
+    expect(lastSegment("")).toBe("");
+  });
+
+  test("handles trailing colon as empty segment", () => {
+    // E.g. when registry stamping is buggy and writes `feature:screen:`
+    // — the helper returns "" rather than throwing, the caller's
+    // navigate-then-not-found banner makes the bug visible.
+    expect(lastSegment("publicstatus:screen:")).toBe("");
+  });
+});

package/src/__tests__/use-list-url-state.test.tsx

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+//
+// useListUrlState pinnt den URL-State-Vertrag pro Screen-ID-Namespace:
+// `?<screenId>.sort=…&<screenId>.dir=…&<screenId>.q=…&<screenId>.page=…`.
+// Zwei Listen auf der Route teilen sich die URL ohne Param-Konflikt.
+// Page wird bei Sort/Filter-Wechsel reseted; Sort bleibt bei Search.
+
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, test, vi } from "vitest";
+import type { NavApi } from "../app/nav";
+import { NavProvider } from "../app/nav";
+import { useListUrlState } from "../hooks/use-list-url-state";
+
+function makeNav(initial: Record<string, string> = {}): NavApi & {
+  readonly current: { params: Record<string, string> };
+  readonly captures: Array<Record<string, string | null>>;
+} {
+  const params: Record<string, string> = { ...initial };
+  const captures: Array<Record<string, string | null>> = [];
+  const api: NavApi & {
+    current: { params: Record<string, string> };
+    captures: Array<Record<string, string | null>>;
+  } = {
+    route: undefined,
+    navigate: vi.fn(),
+    replace: vi.fn(),
+    hrefFor: () => "",
+    get searchParams() {
+      return params;
+    },
+    setSearchParams: (updates) => {
+      captures.push(updates);
+      for (const [k, v] of Object.entries(updates)) {
+        if (v === null) delete params[k];
+        else params[k] = v;
+      }
+    },
+    current: { params },
+    captures,
+  };
+  return api;
+}
+
+function wrapper(nav: NavApi): (props: { children: ReactNode }) => ReactNode {
+  return ({ children }) => <NavProvider value={nav}>{children}</NavProvider>;
+}
+
+describe("useListUrlState", () => {
+  test("Default-State: kein URL-Param → sort=null, q='', page=1", () => {
+    const nav = makeNav();
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.sort).toBeNull();
+    expect(result.current.q).toBe("");
+    expect(result.current.page).toBe(1);
+  });
+
+  test("liest sort+dir aus URL-Params (mit screenId-Prefix)", () => {
+    const nav = makeNav({ "orders.sort": "createdAt", "orders.dir": "desc" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.sort).toEqual({ field: "createdAt", dir: "desc" });
+  });
+
+  test("ignoriert sort einer ANDEREN Liste (Namespacing)", () => {
+    const nav = makeNav({ "incidents.sort": "severity", "incidents.dir": "asc" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.sort).toBeNull();
+  });
+
+  test("invalid dir (z.B. 'foo') → sort=null (defensive parse)", () => {
+    const nav = makeNav({ "orders.sort": "name", "orders.dir": "foo" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.sort).toBeNull();
+  });
+
+  test("setSort schreibt sort+dir, resettet page (atomic update)", () => {
+    const nav = makeNav({ "orders.page": "5" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setSort({ field: "name", dir: "asc" });
+    });
+    expect(nav.captures).toHaveLength(1);
+    expect(nav.captures[0]).toEqual({
+      "orders.sort": "name",
+      "orders.dir": "asc",
+      "orders.page": null, // page-reset bei sort-change
+    });
+  });
+
+  test("setSort(null) löscht sort+dir+page", () => {
+    const nav = makeNav({
+      "orders.sort": "name",
+      "orders.dir": "asc",
+      "orders.page": "3",
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setSort(null);
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.sort": null,
+      "orders.dir": null,
+      "orders.page": null,
+    });
+  });
+
+  test("setQ schreibt q + resettet page (Sort bleibt unangetastet)", () => {
+    const nav = makeNav({
+      "orders.sort": "name",
+      "orders.dir": "asc",
+      "orders.page": "3",
+    });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setQ("acme");
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.q": "acme",
+      "orders.page": null,
+    });
+    // Sort darf NICHT in den captures sein — search-change zerlegt
+    // die Sortierung nicht.
+    expect(nav.captures[0]).not.toHaveProperty("orders.sort");
+  });
+
+  test("setQ('') löscht den q-Key", () => {
+    const nav = makeNav({ "orders.q": "acme" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setQ("");
+    });
+    expect(nav.captures[0]).toEqual({
+      "orders.q": null,
+      "orders.page": null,
+    });
+  });
+
+  test("setPage(1) löscht den Key (Default-Page = unprefixed URL)", () => {
+    const nav = makeNav({ "orders.page": "5" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setPage(1);
+    });
+    expect(nav.captures[0]).toEqual({ "orders.page": null });
+  });
+
+  test("setPage(N>1) speichert die Page als String", () => {
+    const nav = makeNav();
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    act(() => {
+      result.current.setPage(7);
+    });
+    expect(nav.captures[0]).toEqual({ "orders.page": "7" });
+  });
+
+  test("invalid page (negativ, NaN, 0) → fallback auf 1", () => {
+    const nav = makeNav({ "orders.page": "-3" });
+    const { result } = renderHook(() => useListUrlState("orders"), { wrapper: wrapper(nav) });
+    expect(result.current.page).toBe(1);
+  });
+});

package/src/app/action-form-shim.ts

@@ -0,0 +1,50 @@
+// Shim für ActionForm-Renderer (Tier 2.7d).
+//
+// RenderEdit verlangt heute eine `entity: EntityDefinition` + ein
+// `screen: EntityEditScreenDefinition` Pair, nutzt aber intern nur
+// `entity.fields` und `screen.layout`. ActionForm-Screens haben weder
+// eine Entity-Reference noch sind sie type: "entityEdit" — die zwei
+// Helper hier shapen den Daten-Input ad-hoc um, damit RenderEdit
+// reused werden kann ohne den Stack zu duplizieren.
+//
+// Schulden-Flag: Sobald RenderEdit auf entity.transitions / idType /
+// defaultCurrency / softDelete zugreift, oder ein zukünftiger Boot-
+// Validator die schema.entities-Map cross-referenziert, brechen die
+// Type-Lies hier silent. Dann ist es Zeit für eine echte
+// RenderActionForm-Komponente, die `fields` direkt als Input nimmt.
+// Der Boot-Validator kennt actionForm bereits eigenständig (kein
+// entity-Lookup), also ist der Server-Pfad davon nicht betroffen.
+
+import type {
+  ActionFormScreenDefinition,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+const ACTION_FORM_PSEUDO_ENTITY = "__action-form__";
+
+/** Baut eine minimale EntityDefinition aus den Inline-Fields des
+ *  ActionForm-Screens. RenderEdit + computeEditViewModel iterieren
+ *  über entity.fields zur Render-Zeit; alle weiteren EntityDefinition-
+ *  Felder bleiben undefined. */
+export function synthesizeActionFormEntity(
+  fields: ActionFormScreenDefinition["fields"],
+): EntityDefinition {
+  return { fields } as EntityDefinition;
+}
+
+/** Wandelt ein ActionFormScreenDefinition in die EntityEditScreen-
+ *  Shape die RenderEdit erwartet. type wird auf "entityEdit" gesetzt
+ *  damit der Type-Constraint hält; entity wird auf den Pseudo-Namen
+ *  gepinnt — RenderEdit liest das Feld nicht. */
+export function synthesizeActionFormScreen(
+  screen: ActionFormScreenDefinition,
+): EntityEditScreenDefinition {
+  return {
+    id: screen.id,
+    type: "entityEdit",
+    entity: ACTION_FORM_PSEUDO_ENTITY,
+    layout: screen.layout,
+    ...(screen.access !== undefined && { access: screen.access }),
+  };
+}

package/src/app/column-renderers.tsx

@@ -0,0 +1,64 @@
+// Column-Renderer-Map: client-side Lookup für ListColumn-Spalten die im
+// Schema einen PlatformComponent-Renderer (`{ react: { __component: "Name" } }`)
+// statt einer String-Funktion angeben. createKumikoApp im renderer-web sammelt
+// alle clientFeatures.columnRenderers und mountet den Provider; der DataTable-
+// Cell-Renderer schlägt den Component über `useColumnRenderer(name)` nach.
+//
+// Analog zu CustomScreensProvider — der Renderer-Web-Bootstrap mounted beide
+// Provider an derselben Stelle. Schemas selbst bleiben serializable: der
+// Component wird nur per String-Key referenziert, die Map liegt allein
+// client-seitig.
+
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+// Props die ein Column-Renderer-Component bekommt. `value` ist der
+// Cell-Value für die Spalte (rohes Field-Value aus der Row), `row` ist
+// die ganze Row als plain object — nice-to-have für Renderer die auf
+// andere Spalten zugreifen wollen (z.B. Status-Badge der den
+// Erstellungs-Zeitpunkt aus der Row mitnimmt). `column.field` ist der
+// Field-Name; hilfreich für generische Renderer (JSON-Pretty-Printer
+// oder Debug-Renderer die den Feldnamen anzeigen).
+export type ColumnRendererProps = {
+  readonly value: unknown;
+  readonly row: Readonly<Record<string, unknown>>;
+  readonly column: {
+    readonly field: string;
+  };
+};
+
+export type ColumnRendererComponent = ComponentType<ColumnRendererProps>;
+
+export type ColumnRenderersMap = Readonly<Record<string, ColumnRendererComponent>>;
+
+const ColumnRenderersContext = createContext<ColumnRenderersMap | undefined>(undefined);
+
+export type ColumnRenderersProviderProps = {
+  readonly children: ReactNode;
+  readonly value: ColumnRenderersMap;
+};
+
+export function ColumnRenderersProvider({
+  children,
+  value,
+}: ColumnRenderersProviderProps): ReactNode {
+  return (
+    <ColumnRenderersContext.Provider value={value}>{children}</ColumnRenderersContext.Provider>
+  );
+}
+
+/** Schaut die Component für einen Renderer-Key nach. Returnt undefined
+ *  wenn `name` leer/undefined ist (Caller hat keinen __component-Renderer)
+ *  oder weder Provider gemounted noch der Key in der Map ist. Der Caller
+ *  (DataTable.renderCell) loggt dann eine Warnung und fällt auf den
+ *  Default-Type-Renderer zurück.
+ *
+ *  `name` ist optional damit Caller den Hook unkonditional aufrufen
+ *  können — Rules-of-Hooks verbieten einen Function-Branch der den Hook
+ *  überspringt. So bleibt der Aufruf eine einzige Zeile, ohne dass der
+ *  Caller einen Stub-Key wie `""` reichen muss. */
+export function useColumnRenderer(name?: string): ColumnRendererComponent | undefined {
+  const map = useContext(ColumnRenderersContext);
+  if (name === undefined || name === "") return undefined;
+  if (map === undefined) return undefined;
+  return map[name];
+}

package/src/app/config-edit-shim.ts

@@ -0,0 +1,48 @@
+// Shim für ConfigEdit-Renderer (analog zu action-form-shim.ts).
+//
+// RenderEdit verlangt eine `entity: EntityDefinition` + ein
+// `screen: EntityEditScreenDefinition` Pair, nutzt aber intern nur
+// `entity.fields` und `screen.layout` für das Rendern. ConfigEdit-
+// Screens haben weder eine Entity-Reference noch sind sie
+// type: "entityEdit" — die zwei Helper hier shapen den Daten-Input
+// ad-hoc um, damit RenderEdit reused werden kann.
+//
+// Selbe Schulden-Reservation wie bei action-form-shim: sobald RenderEdit
+// auf entity.transitions / idType / softDelete zugreift, oder ein
+// zukünftiger Boot-Validator die schema.entities-Map cross-referenziert,
+// brechen die Type-Lies hier silent. Dann ist Zeit für eine echte
+// RenderConfigEdit-Komponente die direkt fields nimmt.
+
+import type {
+  ConfigEditScreenDefinition,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+const CONFIG_EDIT_PSEUDO_ENTITY = "__config-edit__";
+
+/** Baut eine minimale EntityDefinition aus den Inline-Fields des
+ *  ConfigEdit-Screens. RenderEdit + computeEditViewModel iterieren
+ *  über entity.fields zur Render-Zeit; alle weiteren EntityDefinition-
+ *  Felder bleiben undefined. */
+export function synthesizeConfigEditEntity(
+  fields: ConfigEditScreenDefinition["fields"],
+): EntityDefinition {
+  return { fields } as EntityDefinition;
+}
+
+/** Wandelt ein ConfigEditScreenDefinition in die EntityEditScreen-
+ *  Shape die RenderEdit erwartet. type wird auf "entityEdit" gesetzt
+ *  damit der Type-Constraint hält; entity wird auf den Pseudo-Namen
+ *  gepinnt — RenderEdit liest das Feld nicht. */
+export function synthesizeConfigEditScreen(
+  screen: ConfigEditScreenDefinition,
+): EntityEditScreenDefinition {
+  return {
+    id: screen.id,
+    type: "entityEdit",
+    entity: CONFIG_EDIT_PSEUDO_ENTITY,
+    layout: screen.layout,
+    ...(screen.access !== undefined && { access: screen.access }),
+  };
+}

package/src/app/custom-screens.tsx

@@ -0,0 +1,29 @@
+// Custom-Screen-Components-Map: client-side Lookup für Screens vom Typ
+// `custom`. KumikoScreen schaut hier nach `screen.id` (oder qn) und
+// rendert die passende Component. createKumikoApp im renderer-web sammelt
+// alle clientFeatures.components und mountet den Provider; Tests die
+// einzelne Custom-Screens prüfen wollen, mounten den Provider direkt.
+
+import { type ComponentType, createContext, type ReactNode, useContext } from "react";
+
+export type CustomScreensMap = Readonly<Record<string, ComponentType>>;
+
+const CustomScreensContext = createContext<CustomScreensMap | undefined>(undefined);
+
+export type CustomScreensProviderProps = {
+  readonly children: ReactNode;
+  readonly value: CustomScreensMap;
+};
+
+export function CustomScreensProvider({ children, value }: CustomScreensProviderProps): ReactNode {
+  return <CustomScreensContext.Provider value={value}>{children}</CustomScreensContext.Provider>;
+}
+
+/** Schaut die Component für ein Custom-Screen nach. Returnt undefined
+ *  wenn weder Provider gemounted noch screenId in der Map ist — der
+ *  Caller (KumikoScreen) zeigt dann seinen Placeholder-Banner. */
+export function useCustomScreenComponent(screenId: string): ComponentType | undefined {
+  const map = useContext(CustomScreensContext);
+  if (map === undefined) return undefined;
+  return map[screenId];
+}

package/src/app/feature-schema.ts

@@ -0,0 +1,59 @@
+// Client-safe view of a feature: the subset the renderer needs to
+// mount screens. Intentionally narrower than the server-side
+// FeatureDefinition (no handlers, no hooks, no projections) so the
+// file that exports a schema can be imported from the browser bundle
+// without dragging in Node-only framework internals.
+//
+// Types wohnen in `framework/ui-types/app-schema.ts` damit der Server
+// (buildAppSchema, dev-server) sie produzieren kann ohne renderer als
+// Dependency zu ziehen. Hier nur Re-Export + Runtime-Helpers
+// (toAppSchema, isAppSchema) die Client-Code zur Laufzeit braucht.
+//
+// Typical layout on the feature author's side:
+//
+//   // feature-schema.ts  (imported by client AND server)
+//   export const taskEntity = createEntity({ ... });
+//   export const editScreen: EntityEditScreenDefinition = { ... };
+//   export const clientSchema: FeatureSchema = {
+//     featureName: "tasks",
+//     entities: { task: taskEntity },
+//     screens: [editScreen, ...],
+//   };
+//
+//   // feature.ts  (server-only — imports defineFeature)
+//   import { taskEntity, editScreen, ... } from "./feature-schema";
+//   export const taskFeature = defineFeature("tasks", (r) => {
+//     r.entity("task", taskEntity);
+//     r.writeHandler(...);
+//     r.screen(editScreen);
+//     ...
+//   });
+
+import type {
+  AppSchema,
+  FeatureSchema,
+  WorkspaceSchema,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+export type { AppSchema, FeatureSchema, WorkspaceSchema };
+
+// Normalisiert FeatureSchema → AppSchema. Idempotent für AppSchema.
+// Hebt eine Feature-lokal deklarierte `workspaces`-Liste (Legacy) auf
+// App-Ebene hoch, damit alle Layouts mit der neuen Form arbeiten können
+// ohne dass alte clientSchemas migriert werden müssen.
+export function toAppSchema(input: FeatureSchema | AppSchema): AppSchema {
+  if ("features" in input) return input;
+  // Old single-feature shape — wrap.
+  const { workspaces, ...feature } = input;
+  return {
+    features: [feature],
+    ...(workspaces !== undefined && { workspaces }),
+  };
+}
+
+// TypeGuard — Caller die schon zur Laufzeit unterscheiden müssen
+// (selten; meist reicht toAppSchema). Nicht via `"features" in x` inline
+// machen — narrow'd TS dann auf den join-Typ statt die echte Differenz.
+export function isAppSchema(input: FeatureSchema | AppSchema): input is AppSchema {
+  return "features" in input;
+}