@cosmicdrift/kumiko-renderer 0.220.0 → 0.221.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.220.0",
+  "version": "0.221.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>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.220.0",
-    "@cosmicdrift/kumiko-headless": "0.220.0",
+    "@cosmicdrift/kumiko-framework": "0.221.0",
+    "@cosmicdrift/kumiko-headless": "0.221.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -25,7 +25,7 @@
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
-    "@cosmicdrift/kumiko-locale-de": "0.220.0"
+    "@cosmicdrift/kumiko-locale-de": "0.221.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/merge-search-params-into-initial.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import { mergeSearchParamsIntoInitial } from "../app/kumiko-screen";
 
-type FieldDef = { type?: string; default?: unknown; sensitive?: boolean };
+type FieldDef = {
+  type?: string;
+  default?: unknown;
+  sensitive?: boolean;
+  options?: readonly string[];
+};
 
 describe("mergeSearchParamsIntoInitial", () => {
   test("raw string param merges in as-is for a text field", () => {
@@ -77,4 +82,43 @@ describe("mergeSearchParamsIntoInitial", () => {
     const result = mergeSearchParamsIntoInitial(fields, { ownerId: "user-123" });
     expect(result["ownerId"]).toBe("user-123");
   });
+
+  test("multiSelect coerces comma-separated searchParam to string[]", () => {
+    const fields: Record<string, FieldDef> = { roles: { type: "multiSelect" } };
+    expect(mergeSearchParamsIntoInitial(fields, { roles: "TenantAdmin" })["roles"]).toEqual([
+      "TenantAdmin",
+    ]);
+    expect(mergeSearchParamsIntoInitial(fields, { roles: "Admin,User" })["roles"]).toEqual([
+      "Admin",
+      "User",
+    ]);
+  });
+
+  test("multiSelect coerces JSON-array searchParam to string[]", () => {
+    const fields: Record<string, FieldDef> = { roles: { type: "multiSelect" } };
+    expect(
+      mergeSearchParamsIntoInitial(fields, { roles: JSON.stringify(["Admin", "Editor"]) })["roles"],
+    ).toEqual(["Admin", "Editor"]);
+  });
+
+  test("multiSelect defaults to [] when unset", () => {
+    const fields: Record<string, FieldDef> = { roles: { type: "multiSelect" } };
+    expect(mergeSearchParamsIntoInitial(fields, {})["roles"]).toEqual([]);
+  });
+
+  test("multiSelect prefers JSON parse even without '[' prefix for quoted strings", () => {
+    const fields: Record<string, FieldDef> = { tags: { type: "multiSelect" } };
+    expect(
+      mergeSearchParamsIntoInitial(fields, { tags: JSON.stringify("Berlin, Germany") })["tags"],
+    ).toEqual(["Berlin, Germany"]);
+  });
+
+  test("multiSelect filters unknown option values when options are set", () => {
+    const fields: Record<string, FieldDef> = {
+      roles: { type: "multiSelect", options: ["Admin", "User"] },
+    };
+    expect(
+      mergeSearchParamsIntoInitial(fields, { roles: JSON.stringify(["Admin", "Hacker"]) })["roles"],
+    ).toEqual(["Admin"]);
+  });
 });

package/src/app/__tests__/content-editors.test.tsx

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import type { ContentEditorFormat } from "@cosmicdrift/kumiko-types/nav";
 import { render, screen } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { type CorePrimitives, type InputProps, PrimitivesProvider } from "../../primitives";
@@ -56,7 +57,7 @@ function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
   return <PrimitivesProvider value={testPrimitives}>{children}</PrimitivesProvider>;
 }
 
-function Probe({ contentFormat }: { readonly contentFormat?: string }): ReactNode {
+function Probe({ contentFormat }: { readonly contentFormat?: ContentEditorFormat }): ReactNode {
   const Editor = useContentEditor(contentFormat);
   return (
     <Editor

package/src/app/__tests__/content-preview.test.tsx

@@ -52,6 +52,7 @@ describe("substituteVariables", () => {
 
   test("a name with no example value stays as the literal placeholder", () => {
     expect(substituteVariables("Hi {{customerName}}", {})).toBe("Hi {{customerName}}");
+    expect(substituteVariables("Hi {{constructor}}", {})).toBe("Hi {{constructor}}");
   });
 
   test("no variables in the content → content passes through unchanged", () => {
@@ -62,6 +63,27 @@ describe("substituteVariables", () => {
 });
 
 describe("ContentPreview", () => {
+  test("rich format escapes attribute-breaking quotes in substituted values", () => {
+    function RichEditor({ value }: ContentEditorProps): ReactNode {
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: XSS regression fixture for escapeHtml
+      return <div data-testid="rich" dangerouslySetInnerHTML={{ __html: value }} />;
+    }
+    render(
+      <Wrapper>
+        <ContentEditorsProvider value={{ rich: RichEditor }}>
+          <ContentPreview
+            content={'<a href="{{url}}">x</a>'}
+            variables={{ url: '" onerror="x' }}
+            contentFormat="rich"
+          />
+        </ContentEditorsProvider>
+      </Wrapper>,
+    );
+    const html = screen.getByTestId("rich").innerHTML;
+    expect(html).toContain("&quot;");
+    expect(html).not.toContain('onerror="x');
+  });
+
   test("renders the format's registered editor read-only, with variables substituted", () => {
     function RichEditor({ value, readOnly }: ContentEditorProps): ReactNode {
       return (

package/src/app/__tests__/entity-list-row-action-entity-target.test.tsx

@@ -10,17 +10,22 @@ import { describe, expect, test } from "bun:test";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
+  ProjectionDetailScreenDefinition,
+  ProjectionListScreenDefinition,
+  RowActionNavigate,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
-import { render, waitFor } from "@testing-library/react";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
 import { kumikoDefaultTranslations } from "../../i18n-defaults";
 import {
+  type ButtonProps,
   type CorePrimitives,
   type DataTableProps,
   type DataTableRowAction,
+  type FormProps,
   PrimitivesProvider,
 } from "../../primitives";
 import type { FeatureSchema } from "../feature-schema";
@@ -192,3 +197,205 @@ describe("entityList navigate row-action with an entity-target (fw#2228)", () =>
     expect(navigateCalls).toEqual([{ entity: "customer", id: "cust-7" }]);
   });
 });
+
+// projectionList.runNavigate has NO row["id"] fallback (unlike EntityListBody
+// above) — a projectionList row comes from an arbitrary query without a
+// guaranteed "id" field, so an entity-target there requires an explicit
+// entityId. This proves that path resolves { entity, id } correctly and
+// still forwards `params` via setSearchParams.
+function buildProjectionListSchema(rowAction: RowActionNavigate): FeatureSchema {
+  const listScreen: ProjectionListScreenDefinition = {
+    id: "invoice-projection-list",
+    type: "projectionList",
+    query: "billing:query:invoice:list",
+    columns: [{ field: "status", label: "Status" }],
+    rowActions: [rowAction],
+  };
+  return {
+    featureName: "billing",
+    entities: {},
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+function renderProjectionListScreen(
+  schema: FeatureSchema,
+  navigateSpy: (target: NavTarget) => void,
+  setSearchParamsSpy: (params: Record<string, string | null>) => void,
+): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider
+          value={{
+            route: { screenId: "billing:invoice-projection-list" },
+            navigate: navigateSpy,
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: setSearchParamsSpy,
+          }}
+        >
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={schema} qn="billing:screen:invoice-projection-list" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionList navigate row-action with an entity-target (fw#2228)", () => {
+  test("entity-target with entityId calls nav.navigate with { entity, id } and forwards params via setSearchParams", async () => {
+    capturedRowActions = undefined;
+    const navigateCalls: NavTarget[] = [];
+    const searchParamsCalls: Record<string, string | null>[] = [];
+
+    renderProjectionListScreen(
+      buildProjectionListSchema({
+        kind: "navigate",
+        id: "view",
+        label: "kumiko.actions.view",
+        entity: "invoice",
+        entityId: "invoiceId",
+        params: { pick: ["status"] },
+      }),
+      (target) => navigateCalls.push(target),
+      (params) => searchParamsCalls.push(params),
+    );
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    await requireAction("view").onTrigger({
+      id: "proj-1",
+      values: { id: "proj-1", invoiceId: "invoice-42", status: "open" },
+    });
+
+    expect(navigateCalls).toEqual([{ entity: "invoice", id: "invoice-42" }]);
+    expect(searchParamsCalls).toEqual([{ status: "open" }]);
+  });
+});
+
+// projectionDetail's header actions run through the same entity-target
+// resolution (ProjectionDetailBody, no record["id"] fallback either) as a
+// distinct code path from both entityList and projectionList above — this
+// renders the real KumikoScreen → ProjectionDetailBody → RenderEdit pipeline
+// and clicks the real action button.
+const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) => (
+  <button type="button" data-testid={testId} onClick={() => void onClick?.()}>
+    {children}
+  </button>
+);
+
+const FormWithActions: ComponentType<FormProps> = ({ children, actions }) => (
+  <>
+    <div data-testid="form-body">{children}</div>
+    <div data-testid="form-actions">{actions}</div>
+  </>
+);
+
+const detailTestPrimitives: CorePrimitives = {
+  ...testPrimitives,
+  Button: TestButton,
+  Form: FormWithActions,
+};
+
+function detailStubDispatcher(record: Readonly<Record<string, unknown>>): Dispatcher {
+  return {
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    query: (async () => ({ isSuccess: true, data: record })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function buildProjectionDetailSchema(action: RowActionNavigate): FeatureSchema {
+  const detailScreen: ProjectionDetailScreenDefinition = {
+    id: "invoice-detail",
+    type: "projectionDetail",
+    query: "billing:query:invoice:detail",
+    layout: { sections: [{ title: "s", fields: ["status"] }] },
+    actions: [action],
+  };
+  return {
+    featureName: "billing",
+    entities: {},
+    screens: [detailScreen],
+  } as FeatureSchema;
+}
+
+function renderProjectionDetailScreen(
+  schema: FeatureSchema,
+  record: Readonly<Record<string, unknown>>,
+  navigateSpy: (target: NavTarget) => void,
+  setSearchParamsSpy: (params: Record<string, string | null>) => void,
+): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "en" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={detailStubDispatcher(record)}>
+        <NavProvider
+          value={{
+            route: { screenId: "billing:invoice-detail" },
+            navigate: navigateSpy,
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: setSearchParamsSpy,
+          }}
+        >
+          <PrimitivesProvider value={detailTestPrimitives}>
+            <KumikoScreen
+              schema={schema}
+              qn="billing:screen:invoice-detail"
+              entityId={String(record["id"])}
+            />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionDetail navigate action with an entity-target (fw#2228)", () => {
+  test("entity-target with entityId calls nav.navigate with { entity, id } and forwards params via setSearchParams", async () => {
+    const navigateCalls: NavTarget[] = [];
+    const searchParamsCalls: Record<string, string | null>[] = [];
+
+    renderProjectionDetailScreen(
+      buildProjectionDetailSchema({
+        kind: "navigate",
+        id: "view-customer",
+        label: "kumiko.actions.view",
+        entity: "customer",
+        entityId: "customerId",
+        params: { pick: ["status"] },
+      }),
+      { id: "invoice-42", customerId: "cust-7", status: "open" },
+      (target) => navigateCalls.push(target),
+      (params) => searchParamsCalls.push(params),
+    );
+
+    await waitFor(() => expect(screen.queryByText("Loading…")).toBeNull());
+
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("render-edit-action-view-customer"));
+    });
+
+    expect(navigateCalls).toEqual([{ entity: "customer", id: "cust-7" }]);
+    expect(searchParamsCalls).toEqual([{ status: "open" }]);
+  });
+});

package/src/app/__tests__/entity-list-row-action-refetch.test.tsx

@@ -13,14 +13,16 @@ import { describe, expect, test } from "bun:test";
 import type {
   EntityDefinition,
   EntityListScreenDefinition,
+  ProjectionListScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
-import { act, render, waitFor } from "@testing-library/react";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import type { ComponentType, ReactNode } from "react";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
 import { kumikoDefaultTranslations } from "../../i18n-defaults";
 import {
+  type ButtonProps,
   type CorePrimitives,
   type DataTableProps,
   type DataTableRowAction,
@@ -213,3 +215,187 @@ describe("entityList row-action writeHandler refetches the rows query", () => {
     expect(queryCallCount).toBe(countAfterMount);
   });
 });
+
+// toolbarActions render through RenderList's `toolbarEnd` slot via the real
+// ToolbarActionView primitive, not through the DataTable's `rowActions` prop
+// (that's what captureDataTable above captures) — a stub that ignores
+// `toolbarEnd` never mounts the button, so this needs its own DataTable stub
+// that renders that slot, plus a real Button primitive to click through.
+const TestButton: ComponentType<ButtonProps> = ({ children, onClick, testId }) => (
+  <button type="button" data-testid={testId} onClick={() => void onClick?.()}>
+    {children}
+  </button>
+);
+
+const renderToolbarEnd: ComponentType<DataTableProps> = (props) => <>{props.toolbarEnd}</>;
+
+const toolbarTestPrimitives: CorePrimitives = {
+  ...testPrimitives,
+  Button: TestButton,
+  DataTable: renderToolbarEnd,
+};
+
+function buildToolbarSchema(): FeatureSchema {
+  const entity: EntityDefinition = {
+    fields: {
+      status: {
+        type: "text",
+        maxLength: 50,
+        required: false,
+        searchable: false,
+        sortable: false,
+      },
+    },
+  };
+  const listScreen: EntityListScreenDefinition = {
+    id: "unit-list",
+    type: "entityList",
+    entity: "unit",
+    columns: ["status"],
+    toolbarActions: [
+      {
+        kind: "writeHandler",
+        id: "sync",
+        label: "Sync",
+        handler: "units:write:unit:sync",
+      },
+    ],
+  };
+  return {
+    featureName: "units",
+    entities: { unit: entity },
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+function renderToolbarListScreen(): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider
+          value={{
+            route: { screenId: "units:unit-list" },
+            navigate: () => {},
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: () => {},
+          }}
+        >
+          <PrimitivesProvider value={toolbarTestPrimitives}>
+            <KumikoScreen schema={buildToolbarSchema()} qn="units:screen:unit-list" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("entityList toolbarAction writeHandler refetches the rows query", () => {
+  test("a successful toolbarAction write triggers exactly one refetch", async () => {
+    queryCallCount = 0;
+    writeIsSuccess = true;
+
+    renderToolbarListScreen();
+
+    const button = await waitFor(() => screen.getByTestId("render-list-toolbar-action-sync"));
+    const countAfterMount = queryCallCount;
+    expect(countAfterMount).toBeGreaterThan(0);
+
+    fireEvent.click(button);
+
+    await waitFor(() => {
+      expect(queryCallCount).toBe(countAfterMount + 1);
+    });
+
+    // Give any accidental extra refetch a chance to land before asserting
+    // there wasn't one.
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(queryCallCount).toBe(countAfterMount + 1);
+  });
+});
+
+// projectionList runs its own writeHandler-refetch path (ProjectionListBody,
+// separate from EntityListBody above) — the copy-paste edit that added the
+// refetch call there is untested without this.
+function buildProjectionListSchema(): FeatureSchema {
+  const listScreen: ProjectionListScreenDefinition = {
+    id: "unit-projection-list",
+    type: "projectionList",
+    query: "units:query:unit:list",
+    columns: [{ field: "status", label: "Status" }],
+    rowActions: [
+      {
+        kind: "writeHandler",
+        id: "archive",
+        label: "Archive",
+        handler: "units:write:unit:archive",
+      },
+    ],
+  };
+  return {
+    featureName: "units",
+    entities: {},
+    screens: [listScreen],
+  } as FeatureSchema;
+}
+
+function renderProjectionListScreen(): void {
+  render(
+    <LocaleProvider
+      resolver={createStaticLocaleResolver({ locale: "de-DE" })}
+      fallbackBundles={[kumikoDefaultTranslations]}
+    >
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider
+          value={{
+            route: { screenId: "units:unit-projection-list" },
+            navigate: () => {},
+            replace: () => {},
+            hrefFor: () => "",
+            searchParams: {},
+            setSearchParams: () => {},
+          }}
+        >
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen
+              schema={buildProjectionListSchema()}
+              qn="units:screen:unit-projection-list"
+            />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+describe("projectionList row-action writeHandler refetches the rows query", () => {
+  test("a successful row-action write triggers exactly one refetch", async () => {
+    capturedRowActions = undefined;
+    queryCallCount = 0;
+    writeIsSuccess = true;
+
+    renderProjectionListScreen();
+
+    await waitFor(() => {
+      expect(capturedRowActions).toBeDefined();
+    });
+
+    const countAfterMount = queryCallCount;
+    expect(countAfterMount).toBeGreaterThan(0);
+
+    await act(async () => {
+      await requireArchiveAction().onTrigger({ id: "unit-1", values: { id: "unit-1" } });
+    });
+
+    await waitFor(() => {
+      expect(queryCallCount).toBe(countAfterMount + 1);
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(queryCallCount).toBe(countAfterMount + 1);
+  });
+});

package/src/app/__tests__/form-schema.test.ts

@@ -138,6 +138,15 @@ describe("buildFormSchema", () => {
     expect(buildFormSchema(entity, screen).safeParse({ lines: undefined }).success).toBe(true);
   });
 
+  test("required embedded list field → issue when missing (has EmbeddedListField widget)", () => {
+    const entity = entityWith({
+      lines: { type: "embedded", multiple: true, required: true, schema: {} },
+    });
+    const screen = screenWith(["lines"]);
+    const result = buildFormSchema(entity, screen).safeParse({ lines: undefined });
+    expect(result.success).toBe(false);
+  });
+
   test("required files field → no issue (#1925: no multi-upload widget yet, deliberately deferred)", () => {
     const entity = entityWith({ attachments: { type: "files" } });
     const screen = screenWith([{ field: "attachments", required: true }]);

package/src/app/__tests__/list-filter-facets.test.tsx

@@ -329,9 +329,12 @@ describe("projectionList filter + facets (fw#2224)", () => {
     const props = getCapturedProps();
     if (props === undefined) throw new Error("DataTable was not rendered");
     const facet = props.filterFacets?.[0];
-    expect(facet?.label).not.toBe("kumiko.actions.save");
-    expect(facet?.options?.[0]?.label).not.toBe("kumiko.actions.cancel");
-    expect(typeof facet?.label).toBe("string");
-    expect(facet?.label.length).toBeGreaterThan(0);
+    const de = kumikoDefaultTranslations["de"];
+    const en = kumikoDefaultTranslations["en"];
+    if (en === undefined) throw new Error("missing en default translations");
+    const save = de?.["kumiko.actions.save"] ?? en["kumiko.actions.save"];
+    const cancel = de?.["kumiko.actions.cancel"] ?? en["kumiko.actions.cancel"];
+    expect(facet?.label).toBe(save);
+    expect(facet?.options?.[0]?.label).toBe(cancel);
   });
 });

package/src/app/content-editors.tsx

@@ -8,6 +8,7 @@
 // No entry registered for a format → TextareaContentEditor, so a missing
 // editor is never an empty panel.
 
+import type { ContentEditorFormat } from "@cosmicdrift/kumiko-types/nav";
 import { type ComponentType, createContext, type ReactNode, useContext } from "react";
 import { usePrimitives } from "../primitives";
 
@@ -36,7 +37,7 @@ export type ContentEditorComponent = ComponentType<ContentEditorProps>;
  *  its own id via ContentEditorProps.id. */
 export const CONTENT_EDITOR_ELEMENT_ID = "content-editor-textarea";
 
-export type ContentEditorsMap = Readonly<Record<string, ContentEditorComponent>>;
+export type ContentEditorsMap = Partial<Record<ContentEditorFormat, ContentEditorComponent>>;
 
 const ContentEditorsContext = createContext<ContentEditorsMap>({});
 
@@ -78,7 +79,7 @@ export function TextareaContentEditor({
 /** Resolves the editor for a contentFormat, falling back to the plain
  *  textarea when no clientFeature registered one. `contentFormat`
  *  undefined (collection didn't declare one) behaves like "plain". */
-export function useContentEditor(contentFormat?: string): ContentEditorComponent {
+export function useContentEditor(contentFormat?: ContentEditorFormat): ContentEditorComponent {
   const map = useContext(ContentEditorsContext);
   return map[contentFormat ?? "plain"] ?? TextareaContentEditor;
 }

package/src/app/content-preview.tsx

@@ -4,6 +4,7 @@
 // renders formatted HTML and "plain"/"markdown" render as text through the
 // exact same component, no separate render path per format.
 
+import type { ContentEditorFormat } from "@cosmicdrift/kumiko-types/nav";
 import { type ReactNode, useId } from "react";
 import { useContentEditor } from "./content-editors";
 
@@ -17,17 +18,24 @@ export function substituteVariables(
   content: string,
   variables: Readonly<Record<string, string>>,
 ): string {
-  return content.replace(VARIABLE_PATTERN, (match, name: string) => variables[name] ?? match);
+  return content.replace(VARIABLE_PATTERN, (match, name: string) =>
+    Object.hasOwn(variables, name) ? (variables[name] ?? match) : match,
+  );
 }
 
 function escapeHtml(value: string): string {
-  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
 }
 
 export type ContentPreviewProps = {
   readonly content: string;
   readonly variables: Readonly<Record<string, string>>;
-  readonly contentFormat?: string;
+  readonly contentFormat?: ContentEditorFormat;
 };
 
 export function ContentPreview({