@cosmicdrift/kumiko-renderer 0.261.0 → 0.263.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.261.0",
+  "version": "0.263.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.261.0",
-    "@cosmicdrift/kumiko-headless": "0.261.0",
+    "@cosmicdrift/kumiko-framework": "0.263.0",
+    "@cosmicdrift/kumiko-headless": "0.263.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -27,7 +27,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.261.0"
+    "@cosmicdrift/kumiko-locale-de": "0.263.0"
   },
   "repository": {
     "type": "git",

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

@@ -12,34 +12,133 @@ type FieldDef = {
   maxItems?: number;
 };
 
-describe("mergeSearchParamsIntoInitial", () => {
+function mergeWithAllFieldsUrlPrefillable(
+  fields: Record<string, FieldDef>,
+  searchParams: Record<string, string>,
+  renderableFields?: ReadonlySet<string>,
+  defaultCurrency?: string,
+): Record<string, unknown> {
+  return mergeSearchParamsIntoInitial(fields, {
+    searchParams,
+    urlPrefillFields: Object.keys(fields),
+    ...(renderableFields !== undefined && { renderableFields }),
+    ...(defaultCurrency !== undefined && { defaultCurrency }),
+  });
+}
+
+describe("mergeSearchParamsIntoInitial — urlPrefillFields allowlist", () => {
+  const fields: Record<string, FieldDef> = {
+    leaseId: { type: "text" },
+    iban: { type: "text", default: "DE00" },
+  };
+
+  test("a URL param for a declared field prefills it", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: { leaseId: "l-1" },
+      urlPrefillFields: ["leaseId"],
+    });
+    expect(result["leaseId"]).toBe("l-1");
+  });
+
+  test("a crafted link cannot prefill a field no navigate params declares", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: { leaseId: "l-1", iban: "attacker-iban" },
+      urlPrefillFields: ["leaseId"],
+    });
+    expect(result["leaseId"]).toBe("l-1");
+    expect(result["iban"]).toBe("DE00");
+  });
+
+  test("no urlPrefillFields (screen not from buildAppSchema) prefills nothing from the URL", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: { leaseId: "l-1", iban: "attacker-iban" },
+      urlPrefillFields: undefined,
+    });
+    expect(result["leaseId"]).toBe("");
+    expect(result["iban"]).toBe("DE00");
+  });
+
+  test("sensitive and password fields stay blocked even when allowlisted", () => {
+    const gated: Record<string, FieldDef> = {
+      secret: { type: "text", sensitive: true },
+      apiToken: { type: "text", format: "password", default: "unset" },
+    };
+    const result = mergeSearchParamsIntoInitial(gated, {
+      searchParams: { secret: "s", apiToken: "kpat_leak" },
+      urlPrefillFields: ["secret", "apiToken"],
+    });
+    expect(result["secret"]).toBe("");
+    expect(result["apiToken"]).toBe("unset");
+  });
+});
+
+describe("mergeSearchParamsIntoInitial — handoffValues", () => {
+  const fields: Record<string, FieldDef> = {
+    iban: { type: "text" },
+    amount: { type: "number", default: 0 },
+    secret: { type: "text", sensitive: true },
+    apiToken: { type: "text", format: "password" },
+  };
+
+  test("handed-off values prefill fields outside urlPrefillFields, strings coerced by field type", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: {},
+      urlPrefillFields: [],
+      handoffValues: { iban: "DE12", amount: "42" },
+    });
+    expect(result["iban"]).toBe("DE12");
+    expect(result["amount"]).toBe(42);
+  });
+
+  test("handed-off values never reach sensitive or password fields", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: {},
+      urlPrefillFields: [],
+      handoffValues: { secret: "s", apiToken: "kpat_leak" },
+    });
+    expect(result["secret"]).toBe("");
+    expect(result["apiToken"]).toBe("");
+  });
+
+  test("drawer overrides win over a handoff for the same field", () => {
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: {},
+      urlPrefillFields: [],
+      drawerOverrides: { iban: "from-row" },
+      handoffValues: { iban: "from-handoff" },
+    });
+    expect(result["iban"]).toBe("from-row");
+  });
+});
+
+describe("mergeSearchParamsIntoInitial — coercion (every field URL-prefillable)", () => {
   test("raw string param merges in as-is for a text field", () => {
     const fields: Record<string, FieldDef> = { name: { type: "text" } };
-    const result = mergeSearchParamsIntoInitial(fields, { name: "Alice" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { name: "Alice" });
     expect(result["name"]).toBe("Alice");
   });
 
   test("number-type field coerces a numeric string", () => {
     const fields: Record<string, FieldDef> = { age: { type: "number" } };
-    const result = mergeSearchParamsIntoInitial(fields, { age: "42" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { age: "42" });
     expect(result["age"]).toBe(42);
   });
 
   test("invalid number string falls back to field default", () => {
     const fields: Record<string, FieldDef> = { count: { type: "number", default: 7 } };
-    const result = mergeSearchParamsIntoInitial(fields, { count: "not-a-number" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { count: "not-a-number" });
     expect(result["count"]).toBe(7);
   });
 
   test("boolean field coerces 'true' and 'false'", () => {
     const fields: Record<string, FieldDef> = { active: { type: "boolean" } };
-    expect(mergeSearchParamsIntoInitial(fields, { active: "true" })["active"]).toBe(true);
-    expect(mergeSearchParamsIntoInitial(fields, { active: "false" })["active"]).toBe(false);
+    expect(mergeWithAllFieldsUrlPrefillable(fields, { active: "true" })["active"]).toBe(true);
+    expect(mergeWithAllFieldsUrlPrefillable(fields, { active: "false" })["active"]).toBe(false);
   });
 
   test("sensitive field is skipped even when a matching searchParam exists", () => {
     const fields: Record<string, FieldDef> = { password: { type: "text", sensitive: true } };
-    const result = mergeSearchParamsIntoInitial(fields, { password: "secret" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { password: "secret" });
     expect(result["password"]).toBe("");
   });
 
@@ -47,31 +146,31 @@ describe("mergeSearchParamsIntoInitial", () => {
     const fields: Record<string, FieldDef> = {
       apiToken: { type: "text", format: "password", default: "unset" },
     };
-    const result = mergeSearchParamsIntoInitial(fields, { apiToken: "kpat_leak" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { apiToken: "kpat_leak" });
     expect(result["apiToken"]).toBe("unset");
   });
 
   test("field with no matching searchParam keeps its buildInitialValues default", () => {
     const fields: Record<string, FieldDef> = { total: { type: "number", default: 100 } };
-    const result = mergeSearchParamsIntoInitial(fields, {});
+    const result = mergeWithAllFieldsUrlPrefillable(fields, {});
     expect(result["total"]).toBe(100);
   });
 
   test("money-type field without a defaultCurrency coerces a bare numeric string (legacy callers, e.g. config-edit/action-form)", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
-    const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" });
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { price: "19.99" });
     expect(result["price"]).toBe(19.99);
   });
 
   test("money-type field WITH a defaultCurrency merges the entityEdit payload shape (#1923)", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
-    const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" }, undefined, "USD");
+    const result = mergeWithAllFieldsUrlPrefillable(fields, { price: "19.99" }, undefined, "USD");
     expect(result["price"]).toEqual({ amount: 19.99, currency: "USD" });
   });
 
   test("money-type field WITH a defaultCurrency but no matching searchParam still defaults to the object shape", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
-    const result = mergeSearchParamsIntoInitial(fields, {}, undefined, "USD");
+    const result = mergeWithAllFieldsUrlPrefillable(fields, {}, undefined, "USD");
     expect(result["price"]).toEqual({ amount: 0, currency: "USD" });
   });
 
@@ -80,7 +179,7 @@ describe("mergeSearchParamsIntoInitial", () => {
       status: { type: "text", default: "draft" },
       ownerId: { type: "text" },
     };
-    const result = mergeSearchParamsIntoInitial(
+    const result = mergeWithAllFieldsUrlPrefillable(
       fields,
       { status: "approved", ownerId: "user-123" },
       new Set(["status"]),
@@ -91,16 +190,16 @@ describe("mergeSearchParamsIntoInitial", () => {
 
   test("no renderableFields set given (undefined): behaves as before, all fields eligible", () => {
     const fields: Record<string, FieldDef> = { ownerId: { type: "text" } };
-    const result = mergeSearchParamsIntoInitial(fields, { ownerId: "user-123" });
+    const result = mergeWithAllFieldsUrlPrefillable(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([
+    expect(mergeWithAllFieldsUrlPrefillable(fields, { roles: "TenantAdmin" })["roles"]).toEqual([
       "TenantAdmin",
     ]);
-    expect(mergeSearchParamsIntoInitial(fields, { roles: "Admin,User" })["roles"]).toEqual([
+    expect(mergeWithAllFieldsUrlPrefillable(fields, { roles: "Admin,User" })["roles"]).toEqual([
       "Admin",
       "User",
     ]);
@@ -109,19 +208,21 @@ describe("mergeSearchParamsIntoInitial", () => {
   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"],
+      mergeWithAllFieldsUrlPrefillable(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([]);
+    expect(mergeWithAllFieldsUrlPrefillable(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"],
+      mergeWithAllFieldsUrlPrefillable(fields, { tags: JSON.stringify("Berlin, Germany") })["tags"],
     ).toEqual(["Berlin, Germany"]);
   });
 
@@ -130,13 +231,15 @@ describe("mergeSearchParamsIntoInitial", () => {
       roles: { type: "multiSelect", options: ["Admin", "User"] },
     };
     expect(
-      mergeSearchParamsIntoInitial(fields, { roles: JSON.stringify(["Admin", "Hacker"]) })["roles"],
+      mergeWithAllFieldsUrlPrefillable(fields, { roles: JSON.stringify(["Admin", "Hacker"]) })[
+        "roles"
+      ],
     ).toEqual(["Admin"]);
   });
 
   test("money-type field parses a JSON {amount, currency} param without a defaultCurrency (fw#2763)", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
-    const result = mergeSearchParamsIntoInitial(fields, {
+    const result = mergeWithAllFieldsUrlPrefillable(fields, {
       price: JSON.stringify({ amount: 19.99, currency: "CHF" }),
     });
     expect(result["price"]).toEqual({ amount: 19.99, currency: "CHF" });
@@ -144,7 +247,7 @@ describe("mergeSearchParamsIntoInitial", () => {
 
   test("money-type field: explicit JSON currency wins over defaultCurrency", () => {
     const fields: Record<string, FieldDef> = { price: { type: "money" } };
-    const result = mergeSearchParamsIntoInitial(
+    const result = mergeWithAllFieldsUrlPrefillable(
       fields,
       { price: JSON.stringify({ amount: 19.99, currency: "CHF" }) },
       undefined,
@@ -157,7 +260,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
     try {
       const fields: Record<string, FieldDef> = { price: { type: "money" } };
-      const result = mergeSearchParamsIntoInitial(fields, { price: "19.99" });
+      const result = mergeWithAllFieldsUrlPrefillable(fields, { price: "19.99" });
       expect(result["price"]).toBe(19.99);
       expect(warnSpy).toHaveBeenCalled();
       expect(warnSpy.mock.calls[0]?.[0]).toContain("price");
@@ -172,7 +275,9 @@ describe("mergeSearchParamsIntoInitial", () => {
       const fields: Record<string, FieldDef> = {
         price: { type: "money", default: { amount: 0, currency: "EUR" } },
       };
-      const result = mergeSearchParamsIntoInitial(fields, { price: JSON.stringify({ amount: 5 }) });
+      const result = mergeWithAllFieldsUrlPrefillable(fields, {
+        price: JSON.stringify({ amount: 5 }),
+      });
       expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
       expect(warnSpy).toHaveBeenCalled();
     } finally {
@@ -186,7 +291,7 @@ describe("mergeSearchParamsIntoInitial", () => {
       const fields: Record<string, FieldDef> = {
         price: { type: "money", default: { amount: 0, currency: "EUR" } },
       };
-      const result = mergeSearchParamsIntoInitial(fields, {
+      const result = mergeWithAllFieldsUrlPrefillable(fields, {
         price: JSON.stringify({ amount: 5, currency: "<script>" }),
       });
       expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
@@ -202,7 +307,7 @@ describe("mergeSearchParamsIntoInitial", () => {
       const fields: Record<string, FieldDef> = {
         price: { type: "money", default: { amount: 0, currency: "EUR" } },
       };
-      const result = mergeSearchParamsIntoInitial(fields, { price: "1e999" });
+      const result = mergeWithAllFieldsUrlPrefillable(fields, { price: "1e999" });
       expect(result["price"]).toEqual({ amount: 0, currency: "EUR" });
     } finally {
       warnSpy.mockRestore();
@@ -230,12 +335,14 @@ describe("mergeSearchParamsIntoInitial", () => {
         { accountId: "bank", amount: 1299, qty: 2, posted: true, kind: "debit" },
         { accountId: "cash", amount: -1299, qty: 1, posted: false, kind: "credit" },
       ];
-      const result = mergeSearchParamsIntoInitial(linesField(), { lines: JSON.stringify(rows) });
+      const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
+        lines: JSON.stringify(rows),
+      });
       expect(result["lines"]).toEqual(rows);
     });
 
     test("money cells stay signed minor-unit integers", () => {
-      const result = mergeSearchParamsIntoInitial(linesField(), {
+      const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
         lines: JSON.stringify([{ accountId: "bank", amount: -4200 }]),
       });
       expect(result["lines"]).toEqual([{ accountId: "bank", amount: -4200 }]);
@@ -244,7 +351,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("a fractional money cell rejects the whole prefill and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField(), {
+        const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
           lines: JSON.stringify([{ accountId: "bank", amount: 12.99 }]),
         });
         expect(result["lines"]).toEqual([]);
@@ -258,7 +365,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("a non-JSON param leaves the field empty and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField(), { lines: "not-json-at-all" });
+        const result = mergeWithAllFieldsUrlPrefillable(linesField(), { lines: "not-json-at-all" });
         expect(result["lines"]).toEqual([]);
         expect(warnSpy).toHaveBeenCalled();
       } finally {
@@ -269,7 +376,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("a JSON object instead of an array leaves the field empty and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField(), {
+        const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
           lines: JSON.stringify({ accountId: "bank" }),
         });
         expect(result["lines"]).toEqual([]);
@@ -282,7 +389,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("a row that is not an object leaves the field empty and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField(), {
+        const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
           lines: JSON.stringify([1, 2]),
         });
         expect(result["lines"]).toEqual([]);
@@ -295,7 +402,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("a select cell outside the declared options rejects the prefill and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField(), {
+        const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
           lines: JSON.stringify([{ accountId: "bank", kind: "sudo" }]),
         });
         expect(result["lines"]).toEqual([]);
@@ -306,14 +413,14 @@ describe("mergeSearchParamsIntoInitial", () => {
     });
 
     test("undeclared row keys are dropped instead of reaching the form", () => {
-      const result = mergeSearchParamsIntoInitial(linesField(), {
+      const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
         lines: JSON.stringify([{ accountId: "bank", secretFlag: "yes" }]),
       });
       expect(result["lines"]).toEqual([{ accountId: "bank" }]);
     });
 
     test("a __proto__ key in a row pollutes nothing", () => {
-      const result = mergeSearchParamsIntoInitial(linesField(), {
+      const result = mergeWithAllFieldsUrlPrefillable(linesField(), {
         lines: '[{"accountId":"bank","__proto__":{"polluted":true}}]',
       });
       expect(result["lines"]).toEqual([{ accountId: "bank" }]);
@@ -324,7 +431,7 @@ describe("mergeSearchParamsIntoInitial", () => {
     test("more rows than maxItems leaves the field empty and warns", () => {
       const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
       try {
-        const result = mergeSearchParamsIntoInitial(linesField({ maxItems: 2 }), {
+        const result = mergeWithAllFieldsUrlPrefillable(linesField({ maxItems: 2 }), {
           lines: JSON.stringify([{ accountId: "a" }, { accountId: "b" }, { accountId: "c" }]),
         });
         expect(result["lines"]).toEqual([]);
@@ -335,12 +442,12 @@ describe("mergeSearchParamsIntoInitial", () => {
     });
 
     test("an embedded list without a matching param defaults to an empty array", () => {
-      const result = mergeSearchParamsIntoInitial(linesField(), {});
+      const result = mergeWithAllFieldsUrlPrefillable(linesField(), {});
       expect(result["lines"]).toEqual([]);
     });
 
     test("a sensitive embedded list ignores the param", () => {
-      const result = mergeSearchParamsIntoInitial(linesField({ sensitive: true }), {
+      const result = mergeWithAllFieldsUrlPrefillable(linesField({ sensitive: true }), {
         lines: JSON.stringify([{ accountId: "bank" }]),
       });
       expect(result["lines"]).toEqual([]);

package/src/app/__tests__/entity-edit-create-search-params.test.tsx

@@ -12,14 +12,14 @@ import type {
   EntityEditScreenDefinition,
 } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
-import { render } from "@testing-library/react";
-import type { ComponentType, ReactNode } from "react";
+import { act, render } from "@testing-library/react";
+import { type ComponentType, type ReactNode, useState } from "react";
 import { DispatcherProvider } from "../../context/dispatcher-context";
 import { createStaticLocaleResolver, LocaleProvider } from "../../i18n";
 import { type CorePrimitives, type InputProps, PrimitivesProvider } from "../../primitives";
 import type { FeatureSchema } from "../feature-schema";
 import { KumikoScreen } from "../kumiko-screen";
-import { NavProvider } from "../nav";
+import { type NavApi, NavProvider, type NavTarget, useNavigateWithInitialValues } from "../nav";
 
 const captured: Record<string, InputProps | undefined> = {};
 const captureInput: ComponentType<InputProps> = (props) => {
@@ -65,18 +65,29 @@ function stubDispatcher(): Dispatcher {
   };
 }
 
-function buildSchema(): FeatureSchema {
+function buildSchema(urlPrefillFields: readonly string[] | undefined): FeatureSchema {
   const entity: EntityDefinition = {
     fields: {
       name: { type: "text", maxLength: 200, required: false, searchable: false, sortable: false },
       floorCount: { type: "number", required: false, sortable: false },
+      ownerEmail: { type: "text", maxLength: 200, required: false, searchable: false },
+      accessCode: {
+        type: "text",
+        maxLength: 200,
+        required: false,
+        searchable: false,
+        sensitive: true,
+      },
     },
   };
   const screen: EntityEditScreenDefinition = {
     id: "unit-edit",
     type: "entityEdit",
     entity: "unit",
-    layout: { sections: [{ columns: 1, fields: ["name", "floorCount"] }] },
+    layout: {
+      sections: [{ columns: 1, fields: ["name", "floorCount", "ownerEmail", "accessCode"] }],
+    },
+    ...(urlPrefillFields !== undefined && { urlPrefillFields }),
   };
   return {
     featureName: "housing",
@@ -85,29 +96,41 @@ function buildSchema(): FeatureSchema {
   } as FeatureSchema;
 }
 
+function staticNav(searchParams: Record<string, string>): NavApi {
+  return {
+    route: { screenId: "housing:unit-edit" },
+    navigate: () => {},
+    replace: () => {},
+    hrefFor: () => "",
+    searchParams,
+    setSearchParams: () => {},
+  };
+}
+
+function renderWithNav(nav: NavApi, schema: FeatureSchema): void {
+  render(
+    <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
+      <DispatcherProvider dispatcher={stubDispatcher()}>
+        <NavProvider value={nav}>
+          <PrimitivesProvider value={testPrimitives}>
+            <KumikoScreen schema={schema} qn="housing:screen:unit-edit" />
+          </PrimitivesProvider>
+        </NavProvider>
+      </DispatcherProvider>
+    </LocaleProvider>,
+  );
+}
+
+function resetCaptured(): void {
+  for (const key of Object.keys(captured)) delete captured[key];
+}
+
 describe("EntityEditCreateBody — navigate params as initial values (#1680)", () => {
   test("URL searchParams from rowAction navigate prefill the create form", () => {
-    delete captured["name"];
-    delete captured["floorCount"];
-    render(
-      <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
-        <DispatcherProvider dispatcher={stubDispatcher()}>
-          <NavProvider
-            value={{
-              route: { screenId: "housing:unit-edit" },
-              navigate: () => {},
-              replace: () => {},
-              hrefFor: () => "",
-              searchParams: { name: "Erdgeschoss", floorCount: "3" },
-              setSearchParams: () => {},
-            }}
-          >
-            <PrimitivesProvider value={testPrimitives}>
-              <KumikoScreen schema={buildSchema()} qn="housing:screen:unit-edit" />
-            </PrimitivesProvider>
-          </NavProvider>
-        </DispatcherProvider>
-      </LocaleProvider>,
+    resetCaptured();
+    renderWithNav(
+      staticNav({ name: "Erdgeschoss", floorCount: "3" }),
+      buildSchema(["name", "floorCount"]),
     );
 
     expect(captured["name"]?.value).toBe("Erdgeschoss");
@@ -115,28 +138,99 @@ describe("EntityEditCreateBody — navigate params as initial values (#1680)", (
   });
 
   test("without a matching searchParam the field keeps its default (empty)", () => {
-    delete captured["name"];
-    render(
+    resetCaptured();
+    renderWithNav(staticNav({}), buildSchema(["name"]));
+
+    expect(captured["name"]?.value).toBe("");
+  });
+
+  test("a crafted link cannot prefill a field outside urlPrefillFields", () => {
+    resetCaptured();
+    renderWithNav(
+      staticNav({ name: "Erdgeschoss", ownerEmail: "attacker@example.com" }),
+      buildSchema(["name"]),
+    );
+
+    expect(captured["name"]?.value).toBe("Erdgeschoss");
+    expect(captured["ownerEmail"]?.value).toBe("");
+  });
+
+  test("a screen without urlPrefillFields takes nothing from the URL", () => {
+    resetCaptured();
+    renderWithNav(staticNav({ name: "Erdgeschoss" }), buildSchema(undefined));
+
+    expect(captured["name"]?.value).toBe("");
+  });
+
+  test("a sensitive field stays empty even when urlPrefillFields names it", () => {
+    resetCaptured();
+    renderWithNav(staticNav({ accessCode: "1234" }), buildSchema(["accessCode"]));
+
+    expect(captured["accessCode"]?.value).toBe("");
+  });
+});
+
+describe("EntityEditCreateBody — useNavigateWithInitialValues", () => {
+  function HandoffApp({
+    schema,
+    initialValues,
+  }: {
+    readonly schema: FeatureSchema;
+    readonly initialValues: Readonly<Record<string, unknown>>;
+  }): ReactNode {
+    const [screenId, setScreenId] = useState("home");
+    const nav: NavApi = {
+      route: { screenId },
+      navigate: (target: NavTarget) => {
+        if ("screenId" in target) setScreenId(target.screenId);
+      },
+      replace: () => {},
+      hrefFor: () => "",
+      searchParams: {},
+      setSearchParams: () => {
+        throw new Error("the handoff must not write the query string");
+      },
+    };
+    return (
       <LocaleProvider resolver={createStaticLocaleResolver({ locale: "de-DE" })}>
         <DispatcherProvider dispatcher={stubDispatcher()}>
-          <NavProvider
-            value={{
-              route: { screenId: "housing:unit-edit" },
-              navigate: () => {},
-              replace: () => {},
-              hrefFor: () => "",
-              searchParams: {},
-              setSearchParams: () => {},
-            }}
-          >
+          <NavProvider value={nav}>
             <PrimitivesProvider value={testPrimitives}>
-              <KumikoScreen schema={buildSchema()} qn="housing:screen:unit-edit" />
+              {screenId === "unit-edit" ? (
+                <KumikoScreen schema={schema} qn="housing:screen:unit-edit" />
+              ) : (
+                <Opener initialValues={initialValues} />
+              )}
             </PrimitivesProvider>
           </NavProvider>
         </DispatcherProvider>
-      </LocaleProvider>,
+      </LocaleProvider>
     );
+  }
 
-    expect(captured["name"]?.value).toBe("");
+  let openForm: (() => void) | undefined;
+  function Opener({
+    initialValues,
+  }: {
+    readonly initialValues: Readonly<Record<string, unknown>>;
+  }): ReactNode {
+    const navigateWithInitialValues = useNavigateWithInitialValues();
+    openForm = () => navigateWithInitialValues({ screenId: "unit-edit" }, initialValues);
+    return null;
+  }
+
+  test("handed-off values prefill fields outside urlPrefillFields, but never a sensitive one", () => {
+    resetCaptured();
+    render(
+      <HandoffApp
+        schema={buildSchema([])}
+        initialValues={{ ownerEmail: "owner@example.com", floorCount: "2", accessCode: "1234" }}
+      />,
+    );
+    act(() => openForm?.());
+
+    expect(captured["ownerEmail"]?.value).toBe("owner@example.com");
+    expect(captured["floorCount"]?.value).toBe(2);
+    expect(captured["accessCode"]?.value).toBe("");
   });
 });

package/src/app/kumiko-screen.tsx

@@ -33,7 +33,11 @@ import type {
 import { fieldLabelKey, fieldOptionLabelKey, isSafeHref } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { extractCreatedId, extractIdField } from "../components/reference-create-dialog";
-import { RenderEdit, type RenderEditAction } from "../components/render-edit";
+import {
+  RenderEdit,
+  type RenderEditAction,
+  type RenderEditControls,
+} from "../components/render-edit";
 import {
   needsActionConfirm,
   RenderEditActionButton,
@@ -65,7 +69,7 @@ import {
   type ResolvedFacetSpec,
   resolveProjectionFacetSpecs,
 } from "./list-facets";
-import { type NavApi, useNav } from "./nav";
+import { type NavApi, useInitialValuesHandoff, useNav } from "./nav";
 import {
   synthesizeProjectionDetailEntity,
   synthesizeProjectionDetailScreen,
@@ -522,87 +526,116 @@ function coerceEmbeddedListRows(
   return rows;
 }
 
+type PrefillFieldShape = {
+  readonly type?: string;
+  readonly sensitive?: boolean;
+  readonly format?: string;
+  readonly options?: readonly (string | { readonly value: string })[];
+  readonly multiple?: boolean;
+  readonly schema?: Readonly<Record<string, EmbeddedCellShape>>;
+  readonly maxItems?: number;
+};
+
+export type InitialValueSources = {
+  readonly searchParams: Readonly<Record<string, string>>;
+  // Only these URL query keys may prefill — the target screen's
+  // `urlPrefillFields` from buildAppSchema. Absent means none: a crafted link
+  // must not seed fields no declared navigate `params` names.
+  readonly urlPrefillFields: readonly string[] | undefined;
+  readonly renderableFields?: ReadonlySet<string>;
+  readonly defaultCurrency?: string;
+  // Drawer-kind row actions (fw#2710) prefill from the clicked row's
+  // already-typed values; wins over every other source.
+  readonly drawerOverrides?: Readonly<Record<string, unknown>>;
+  // useNavigateWithInitialValues — in-app only, never in the URL, so it
+  // bypasses urlPrefillFields; string values get the URL coercion.
+  readonly handoffValues?: Readonly<Record<string, unknown>>;
+};
+
+function coercePrefillString(
+  raw: string,
+  name: string,
+  shape: PrefillFieldShape,
+  fallback: unknown,
+  defaultCurrency: string | undefined,
+): unknown {
+  if (shape.type === "number") {
+    const parsed = Number(raw);
+    return Number.isNaN(parsed) ? fallback : parsed;
+  }
+  if (shape.type === "money") {
+    const coerced = coerceMoneyValue(raw, name, defaultCurrency);
+    return coerced === undefined ? fallback : coerced;
+  }
+  if (shape.type === "boolean") return raw === "true";
+  if (shape.type === "multiSelect") {
+    // Row-action navigate stringifies arrays via String(arr) → "a,b" (or
+    // JSON when the navigate helper JSON.stringifies). Try JSON first
+    // (even without a "[" prefix), then comma-split; filter against
+    // field.options when present so unknown values never reach the form.
+    const optionValues = multiSelectOptionValues(shape);
+    const splitComma = (): string[] =>
+      raw === ""
+        ? []
+        : raw
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+    let values: string[];
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        values = parsed.map((v) => String(v));
+      } else if (typeof parsed === "string") {
+        values = [parsed];
+      } else {
+        values = splitComma();
+      }
+    } catch {
+      values = splitComma();
+    }
+    return optionValues !== undefined ? values.filter((v) => optionValues.has(v)) : values;
+  }
+  if (shape.type === "embedded" && shape.multiple === true) {
+    return coerceEmbeddedListRows(raw, name, shape.schema ?? {}, shape.maxItems) ?? fallback;
+  }
+  return raw;
+}
+
 export function mergeSearchParamsIntoInitial(
   fields: Readonly<Record<string, unknown>>,
-  searchParams: Readonly<Record<string, string>>,
-  renderableFields?: ReadonlySet<string>,
-  defaultCurrency?: string,
-  // Drawer-kind row actions (fw#2710) prefill directly from the clicked
-  // row's already-typed values — no URL round-trip, so no string coercion.
-  // Goes through the same renderableFields/sensitive gates as searchParams
-  // (a `params` extractor could still name a hidden or sensitive field) and
-  // wins over searchParams for a name present in both.
-  overrides?: Readonly<Record<string, unknown>>,
+  sources: InitialValueSources,
 ): Record<string, unknown> {
+  const { searchParams, renderableFields, defaultCurrency, drawerOverrides, handoffValues } =
+    sources;
+  const urlPrefillFields = new Set(sources.urlPrefillFields ?? []);
   const defaults = buildInitialValues(fields, defaultCurrency) as Record<string, unknown>;
   const merged: Record<string, unknown> = { ...defaults };
   for (const [name, fieldDef] of Object.entries(fields)) {
     if (renderableFields !== undefined && !renderableFields.has(name)) continue;
-    const shape = fieldDef as {
-      type?: string;
-      sensitive?: boolean;
-      format?: string;
-      options?: readonly (string | { readonly value: string })[];
-      multiple?: boolean;
-      schema?: Readonly<Record<string, EmbeddedCellShape>>;
-      maxItems?: number;
-    };
+    const shape = fieldDef as PrefillFieldShape;
+    // Neither gate is lifted by an allowlist entry or a handoff.
     if (shape.sensitive === true) continue;
-    // A password field must never be prefilled from the URL, same as sensitive.
     if (shape.format === "password") continue;
-    if (overrides !== undefined && name in overrides) {
-      merged[name] = overrides[name];
+    if (drawerOverrides !== undefined && name in drawerOverrides) {
+      merged[name] = drawerOverrides[name];
       continue;
     }
-    const raw = searchParams[name];
-    if (raw === undefined) continue;
-    if (shape.type === "number") {
-      const parsed = Number(raw);
-      merged[name] = Number.isNaN(parsed) ? defaults[name] : parsed;
-    } else if (shape.type === "money") {
-      const coerced = coerceMoneyValue(raw, name, defaultCurrency);
-      merged[name] = coerced === undefined ? defaults[name] : coerced;
-    } else if (shape.type === "boolean") {
-      merged[name] = raw === "true";
-    } else if (shape.type === "multiSelect") {
-      // Row-action navigate stringifies arrays via String(arr) → "a,b" (or
-      // JSON when the navigate helper JSON.stringifies). Try JSON first
-      // (even without a "[" prefix), then comma-split; filter against
-      // field.options when present so unknown values never reach the form.
-      const optionValues = multiSelectOptionValues(shape);
-      let values: string[];
-      try {
-        const parsed: unknown = JSON.parse(raw);
-        if (Array.isArray(parsed)) {
-          values = parsed.map((v) => String(v));
-        } else if (typeof parsed === "string") {
-          values = [parsed];
-        } else {
-          values =
-            raw === ""
-              ? []
-              : raw
-                  .split(",")
-                  .map((s) => s.trim())
-                  .filter(Boolean);
-        }
-      } catch {
-        values =
-          raw === ""
-            ? []
-            : raw
-                .split(",")
-                .map((s) => s.trim())
-                .filter(Boolean);
-      }
+    const handedOff =
+      handoffValues !== undefined && Object.hasOwn(handoffValues, name)
+        ? handoffValues[name]
+        : undefined;
+    if (handedOff !== undefined) {
       merged[name] =
-        optionValues !== undefined ? values.filter((v) => optionValues.has(v)) : values;
-    } else if (shape.type === "embedded" && shape.multiple === true) {
-      const rows = coerceEmbeddedListRows(raw, name, shape.schema ?? {}, shape.maxItems);
-      merged[name] = rows ?? defaults[name];
-    } else {
-      merged[name] = raw;
+        typeof handedOff === "string"
+          ? coercePrefillString(handedOff, name, shape, defaults[name], defaultCurrency)
+          : handedOff;
+      continue;
     }
+    if (!urlPrefillFields.has(name)) continue;
+    const raw = searchParams[name];
+    if (raw === undefined) continue;
+    merged[name] = coercePrefillString(raw, name, shape, defaults[name], defaultCurrency);
   }
   return merged;
 }
@@ -687,20 +720,29 @@ function EntityEditCreateBody({
   readonly onSaved?: () => void;
 }): ReactNode {
   const nav = useNav();
+  const handoffValues = useInitialValuesHandoff(screen.id);
   const appFeatures = useAppFeatures();
   const initial = useMemo(
     () =>
-      mergeSearchParamsIntoInitial(
-        entity.fields,
-        nav.searchParams,
-        layoutFieldNames(screen),
-        entity.defaultCurrency ?? "EUR",
-      ) as FormValues,
-    [entity.fields, nav.searchParams, screen, entity.defaultCurrency],
+      mergeSearchParamsIntoInitial(entity.fields, {
+        searchParams: nav.searchParams,
+        urlPrefillFields: screen.urlPrefillFields,
+        renderableFields: layoutFieldNames(screen),
+        defaultCurrency: entity.defaultCurrency ?? "EUR",
+        ...(handoffValues !== undefined && { handoffValues }),
+      }) as FormValues,
+    [entity.fields, nav.searchParams, screen, entity.defaultCurrency, handoffValues],
   );
   const formSchema = useMemo(() => buildFormSchema(entity, screen), [entity, screen]);
   const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
+  // Create's write-handler success payload doesn't flatly expose a parent FK
+  // (`{ kind, id, data, … }`), so an object-form redirect's `idFrom` falls
+  // back to the values just submitted to the handler.
+  const controlsRef = useRef<RenderEditControls<FormValues> | null>(null);
+  const handleControlsReady = useCallback((controls: RenderEditControls<FormValues>) => {
+    controlsRef.current = controls;
+  }, []);
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {
       if (!result.isSuccess) return;
@@ -722,6 +764,7 @@ function EntityEditCreateBody({
           result.data,
           schema,
           appFeatures,
+          controlsRef.current?.getValues(),
         );
         nav.navigate({ screenId, ...(entityId !== undefined && { entityId }) });
         return;
@@ -744,6 +787,7 @@ function EntityEditCreateBody({
       schema={formSchema}
       writeCommand={writeCommand}
       onSubmit={handleSubmitted}
+      onControlsReady={handleControlsReady}
       onCancel={navigateToList}
       {...(screen.submitLabel !== undefined && { submitLabel: screen.submitLabel })}
       {...(translate !== undefined && { translate })}
@@ -2959,8 +3003,9 @@ function redirectScreenTarget(
 // list screen never gets an id attached, matching actionForm's original
 // behavior. The id itself prefers the write-handler's success payload
 // (`submittedData`) and falls back to `fallbackRecord` — the entityEdit
-// update path's already-loaded record, which has fields (e.g. a parent FK)
-// the CRUD write executor's success payload doesn't flatly expose.
+// update path's already-loaded record, or the create path's just-submitted
+// form values — both of which carry fields (e.g. a parent FK) the CRUD
+// write executor's success payload doesn't flatly expose.
 function resolveRedirectTarget(
   redirect: string | ActionFormRedirect,
   submittedData: unknown,
@@ -3024,16 +3069,26 @@ function ActionFormBody({
   const appFeatures = useAppFeatures();
   const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
   const synthScreen = useMemo(() => synthesizeActionFormScreen(screen), [screen]);
+  const pendingHandoff = useInitialValuesHandoff(screen.id);
+  // A drawer-hosted form is not a navigation target, so it never takes a handoff.
+  const handoffValues = onSuccess === undefined ? pendingHandoff : undefined;
   const initial = useMemo(
     () =>
-      mergeSearchParamsIntoInitial(
-        screen.fields,
-        nav.searchParams,
-        layoutFieldNames(synthScreen),
-        undefined,
-        initialOverrides,
-      ) as FormValues,
-    [screen.fields, nav.searchParams, synthScreen, initialOverrides],
+      mergeSearchParamsIntoInitial(screen.fields, {
+        searchParams: nav.searchParams,
+        urlPrefillFields: screen.urlPrefillFields,
+        renderableFields: layoutFieldNames(synthScreen),
+        ...(initialOverrides !== undefined && { drawerOverrides: initialOverrides }),
+        ...(handoffValues !== undefined && { handoffValues }),
+      }) as FormValues,
+    [
+      screen.fields,
+      screen.urlPrefillFields,
+      nav.searchParams,
+      synthScreen,
+      initialOverrides,
+      handoffValues,
+    ],
   );
   const handleSubmitted = useCallback(
     (result: SubmitResult<unknown>) => {

package/src/app/nav.tsx

@@ -1,5 +1,6 @@
-import { createContext, type ReactNode, useContext } from "react";
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useState } from "react";
 import type { FeatureSchema } from "./feature-schema";
+import { lastSegment } from "./qn";
 
 // Navigation-Contract, plattform-neutral. Types + Context + Hook leben
 // hier; die konkrete Implementation (window.history im Web,
@@ -173,8 +174,77 @@ export type NavProviderProps = {
   readonly value: NavApi;
 };
 
+type InitialValuesHandoff = {
+  readonly screenId: string;
+  readonly values: Readonly<Record<string, unknown>>;
+};
+
+// A mutable slot instead of state: offering must not re-render the app, and
+// the target form reads it once on mount.
+type InitialValuesHandoffSlot = { current: InitialValuesHandoff | undefined };
+
+const InitialValuesHandoffContext = createContext<InitialValuesHandoffSlot | undefined>(undefined);
+
 export function NavProvider({ children, value }: NavProviderProps): ReactNode {
-  return <NavContext.Provider value={value}>{children}</NavContext.Provider>;
+  const [handoffSlot] = useState<InitialValuesHandoffSlot>(() => ({ current: undefined }));
+  const routeScreenId = value.route?.screenId;
+  // An offer whose form never mounted (e.g. already on that screen) must not
+  // resurface on a later, unrelated visit — drop it once the route moves elsewhere.
+  useEffect(() => {
+    const pending = handoffSlot.current;
+    if (pending === undefined || routeScreenId === undefined) return;
+    if (lastSegment(routeScreenId) !== pending.screenId) handoffSlot.current = undefined;
+  }, [handoffSlot, routeScreenId]);
+  return (
+    <NavContext.Provider value={value}>
+      <InitialValuesHandoffContext.Provider value={handoffSlot}>
+        {children}
+      </InitialValuesHandoffContext.Provider>
+    </NavContext.Provider>
+  );
+}
+
+// Navigates to a form screen (actionForm, secretMint, entityEdit-create) with
+// initial values carried in memory — never in the URL, so a link cannot
+// forge them and they are not limited to the screen's urlPrefillFields.
+// sensitive and password fields are still never prefilled.
+export function useNavigateWithInitialValues(): (
+  target: ScreenTarget,
+  initialValues: Readonly<Record<string, unknown>>,
+) => void {
+  const nav = useNav();
+  const handoffSlot = useContext(InitialValuesHandoffContext);
+  return useCallback(
+    (target, initialValues) => {
+      if (handoffSlot !== undefined) {
+        handoffSlot.current = { screenId: lastSegment(target.screenId), values: initialValues };
+      }
+      nav.navigate(target);
+    },
+    [nav, handoffSlot],
+  );
+}
+
+export function useInitialValuesHandoff(
+  screenId: string,
+): Readonly<Record<string, unknown>> | undefined {
+  const handoffSlot = useContext(InitialValuesHandoffContext);
+  const [values] = useState(() => {
+    const pending = handoffSlot?.current;
+    return pending !== undefined && pending.screenId === lastSegment(screenId)
+      ? pending.values
+      : undefined;
+  });
+  useEffect(() => {
+    if (
+      handoffSlot !== undefined &&
+      values !== undefined &&
+      handoffSlot.current?.values === values
+    ) {
+      handoffSlot.current = undefined;
+    }
+  }, [handoffSlot, values]);
+  return values;
 }
 
 export function useNav(): NavApi {

package/src/app/secret-mint-body.tsx

@@ -12,7 +12,7 @@ import {
 import type { FeatureSchema } from "./feature-schema";
 import { buildInitialValues, mergeSearchParamsIntoInitial } from "./kumiko-screen";
 import { layoutFieldNames } from "./layout-fields";
-import { useNav } from "./nav";
+import { useInitialValuesHandoff, useNav } from "./nav";
 import { lastSegment } from "./qn";
 
 export type SecretMintBodyProps = {
@@ -62,14 +62,16 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
   const effectiveTranslate = translate ?? t;
   const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
   const synthScreen = useMemo(() => synthesizeActionFormScreen(screen), [screen]);
+  const handoffValues = useInitialValuesHandoff(screen.id);
   const initial = useMemo(
     () =>
-      mergeSearchParamsIntoInitial(
-        screen.fields,
-        nav.searchParams,
-        layoutFieldNames(synthScreen),
-      ) as FormValues,
-    [screen.fields, nav.searchParams, synthScreen],
+      mergeSearchParamsIntoInitial(screen.fields, {
+        searchParams: nav.searchParams,
+        urlPrefillFields: screen.urlPrefillFields,
+        renderableFields: layoutFieldNames(synthScreen),
+        ...(handoffValues !== undefined && { handoffValues }),
+      }) as FormValues,
+    [screen.fields, screen.urlPrefillFields, nav.searchParams, synthScreen, handoffValues],
   );
   const [revealed, setRevealed] = useState<Readonly<Record<string, unknown>> | null>(null);
   const [done, setDone] = useState(false);

package/src/components/__tests__/render-field-number-unit.test.tsx

@@ -5,6 +5,11 @@
 // never a value conversion.
 
 import { describe, expect, test } from "bun:test";
+import {
+  buildAppSchema,
+  createRegistry,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 import type {
   EntityDefinition,
   EntityEditScreenDefinition,
@@ -189,3 +194,34 @@ describe("RenderField — editable number unit suffix", () => {
     expect(field.unit).toBeUndefined();
   });
 });
+
+describe("RenderField — number unit through the shipped client schema", () => {
+  function projectedVehicleEntity(
+    mileageUnit: string | { readonly field: string },
+  ): EntityDefinition {
+    const feature = defineFeature("fleet", (r) => {
+      r.entity("vehicle", buildEntity(mileageUnit));
+    });
+    const app = buildAppSchema(createRegistry([feature]));
+    const entity = app.features[0]?.entities["vehicle"];
+    if (entity === undefined) throw new Error("expected the projected vehicle entity");
+    // Mirrors the browser-injection pipeline, which ships the schema as JSON.
+    return JSON.parse(JSON.stringify(entity)) as EntityDefinition;
+  }
+
+  test("static unit survives buildAppSchema and reaches Input.unit", () => {
+    const field = renderMileageField(projectedVehicleEntity("mi"), { mileage: 58 });
+    if (field.kind !== "number") throw new Error("expected a number Input");
+    expect(field.unit).toBe("mi");
+  });
+
+  test("sibling-field unit survives buildAppSchema and resolves from the row", () => {
+    const field = renderMileageField(
+      projectedVehicleEntity({ field: "mileageUnit" }),
+      { mileage: 58, mileageUnit: "km" },
+      { mileage: 58, mileageUnit: "km" },
+    );
+    if (field.kind !== "number") throw new Error("expected a number Input");
+    expect(field.unit).toBe("km");
+  });
+});

package/src/index.ts

@@ -79,6 +79,7 @@ export {
   parsePath,
   resolveTarget,
   useNav,
+  useNavigateWithInitialValues,
 } from "./app/nav";
 export { lastSegment } from "./app/qn";
 export type { EmbeddedScreenTarget } from "./app/use-embedded-screen";

package/src/primitives.tsx

@@ -51,6 +51,7 @@ import {
   type ComponentType,
   createContext,
   type FormEvent,
+  type KeyboardEvent,
   type ReactNode,
   type Ref,
   useContext,
@@ -60,6 +61,11 @@ export type { RuntimeRenderer };
 
 // ---- Prop-Types (die Primitive-Contract-Oberfläche) ----
 
+/** Escape hatch for `data-*` test hooks (e.g. an E2E selector) that don't
+ *  warrant a dedicated typed prop. Web merges these onto the rendered
+ *  element; native impls ignore it (precedent: `className`). */
+export type DataAttributes = Readonly<Record<`data-${string}`, string>>;
+
 /** Standard-Button. `loading` zeigt einen Spinner statt der Children
  *  und sollte mit `disabled` kombiniert werden, wenn die Action wirklich
  *  blockiert bis das Loading durch ist (z.B. async submit). Native-
@@ -105,6 +111,7 @@ export type ButtonProps = {
   readonly icon?: NavIconKey;
   /** Icon after the label (e.g. "Continue →"). */
   readonly iconEnd?: NavIconKey;
+  readonly dataAttributes?: DataAttributes;
 };
 
 /** Navigations-Link. `variant="button"` rendert die Button-Optik auf einem
@@ -121,6 +128,7 @@ export type LinkProps = {
   readonly className?: string;
   readonly children: ReactNode;
   readonly testId?: string;
+  readonly dataAttributes?: DataAttributes;
 };
 
 /** Banner für inline-Message ODER Page-State (z.B. "Loading…",
@@ -197,6 +205,11 @@ export type InputProps =
       readonly readOnly?: boolean;
       /** Closed FieldIconKey vocabulary (FIELD_ICONS registry, renderer-web). */
       readonly icon?: FieldIconKey;
+      readonly dataAttributes?: DataAttributes;
+      /** Raw keydown access (e.g. Enter-to-submit at the field instead of
+       *  the surrounding Form). Web forwards it, native impls ignore it
+       *  (precedent: `ButtonProps.ref`). */
+      readonly onKeyDown?: (event: KeyboardEvent<HTMLInputElement>) => void;
     }
   | {
       readonly kind: "email";
@@ -479,6 +492,12 @@ export type InputProps =
       /** Ctrl/Cmd+Enter submits instead of inserting a newline. Plain
        *  Enter still inserts a newline. */
       readonly onSubmitShortcut?: () => void;
+      readonly dataAttributes?: DataAttributes;
+      /** Raw keydown access (e.g. plain-Enter-submits/Shift+Enter-newline at
+       *  the field instead of the surrounding Form). Composes with
+       *  `onSubmitShortcut` — both fire on the same keystroke when set. Web
+       *  forwards it, native impls ignore it (precedent: `ButtonProps.ref`). */
+      readonly onKeyDown?: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
     };
 
 // Sort-Wire-Format. `null`-State unterscheidet "User hat noch nichts
@@ -1033,6 +1052,7 @@ export type CardProps = {
   readonly children?: ReactNode;
   readonly className?: string;
   readonly testId?: string;
+  readonly dataAttributes?: DataAttributes;
 };
 
 /** Determinate progress bar (e.g. wizard step progress). `value` is a