@cosmicdrift/kumiko-renderer 0.290.0 → 0.291.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.290.0",
+  "version": "0.291.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,9 +15,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.290.0",
-    "@cosmicdrift/kumiko-headless": "0.290.0",
-    "@cosmicdrift/kumiko-types": "0.290.0",
+    "@cosmicdrift/kumiko-framework": "0.291.0",
+    "@cosmicdrift/kumiko-headless": "0.291.0",
+    "@cosmicdrift/kumiko-types": "0.291.0",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.290.0"
+    "@cosmicdrift/kumiko-locale-de": "0.291.0"
   },
   "repository": {
     "type": "git",

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

@@ -1,6 +1,10 @@
 import { describe, expect, spyOn, test } from "bun:test";
 import type { EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
-import { mergeSearchParamsIntoInitial } from "../app/kumiko-screen";
+import {
+  buildInitialValues,
+  literalCurrencyOverrides,
+  mergeSearchParamsIntoInitial,
+} from "../app/kumiko-screen";
 import { layoutFieldNames } from "../app/layout-fields";
 
 type FieldDef = {
@@ -472,3 +476,50 @@ describe("mergeSearchParamsIntoInitial — coercion (every field URL-prefillable
     });
   });
 });
+
+// fw#2839: an entity-less form screen passes no `defaultCurrency`, so before
+// this the money branch fell through to a bare `0` the handler's zod schema
+// rejected. `literalCurrencyOverrides` resolves a declared literal source with
+// no query; configEdit's plain-number contract depends on getting neither.
+describe("money currency sources on an entity-less form (fw#2839)", () => {
+  const amountField = (currency?: unknown): Record<string, FieldDef> => ({
+    amount: { type: "money", ...(currency !== undefined && { currency }) } as FieldDef,
+  });
+
+  test("a literal source seeds { amount: 0, currency } without any defaultCurrency", () => {
+    const fields = amountField({ kind: "literal", code: "CHF" });
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: {},
+      urlPrefillFields: [],
+      moneyCurrencyOverrides: literalCurrencyOverrides(fields),
+    });
+    expect(result["amount"]).toEqual({ amount: 0, currency: "CHF" });
+  });
+
+  test("a literal source also carries into a URL-prefilled amount (fw#2763 path)", () => {
+    const fields = amountField({ kind: "literal", code: "CHF" });
+    const result = mergeSearchParamsIntoInitial(fields, {
+      searchParams: { amount: "42.50" },
+      urlPrefillFields: ["amount"],
+      moneyCurrencyOverrides: literalCurrencyOverrides(fields),
+    });
+    expect(result["amount"]).toEqual({ amount: 42.5, currency: "CHF" });
+  });
+
+  test("literalCurrencyOverrides ignores tenant-declared and undeclared money fields", () => {
+    expect(literalCurrencyOverrides(amountField({ kind: "tenant" }))).toEqual({});
+    expect(literalCurrencyOverrides(amountField())).toEqual({});
+  });
+
+  test("configEdit stays on the plain-number contract: no overrides, no currency wrapper", () => {
+    const fields = amountField({ kind: "literal", code: "CHF" });
+    expect(buildInitialValues(fields)["amount"]).toBe(0);
+  });
+
+  test("entityEdit is unchanged: defaultCurrency still wins where no source is declared", () => {
+    expect(buildInitialValues(amountField(), "USD")["amount"]).toEqual({
+      amount: 0,
+      currency: "USD",
+    });
+  });
+});

package/src/app/__tests__/return-to.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { FeatureSchema } from "../feature-schema";
-import { resolveReturnTarget, returnToParams } from "../return-to";
+import { formatReturnTo, resolveReturnTarget, returnToParams, splitReturnTo } from "../return-to";
 
 function schemaWith(featureName: string, screens: readonly ScreenDefinition[]): FeatureSchema {
   return { featureName, entities: {}, screens };
@@ -156,12 +156,37 @@ describe("resolveReturnTarget", () => {
     ).toBeUndefined();
   });
 
-  test("rejects entityId with '?'", () => {
+  test("rejects an entityId whose decoded form carries '?'", () => {
     expect(
-      resolveReturnTarget("token-edit/abc?x=1", "token-create", features, undefined),
+      resolveReturnTarget("token-edit/abc%3Fx=1", "token-create", features, undefined),
     ).toBeUndefined();
   });
 
+  test("a trailing host-state query resolves to the bare target", () => {
+    expect(
+      resolveReturnTarget("token-edit/abc?tab=keys", "token-create", features, undefined),
+    ).toEqual({ screenId: "token-edit", entityId: "abc" });
+  });
+
+  test("a host-state query does not loosen validation", () => {
+    expect(
+      resolveReturnTarget("https://evil.com?tab=keys", "token-create", features, undefined),
+    ).toBeUndefined();
+    expect(
+      resolveReturnTarget("//evil.com?tab=keys", "token-create", features, undefined),
+    ).toBeUndefined();
+    expect(
+      resolveReturnTarget("token-edit/..?tab=keys", "token-create", features, undefined),
+    ).toBeUndefined();
+    expect(
+      resolveReturnTarget("unknown-screen?tab=keys", "token-create", features, undefined),
+    ).toBeUndefined();
+    expect(
+      resolveReturnTarget("admin-only?tab=keys", "token-create", features, undefined),
+    ).toBeUndefined();
+    expect(resolveReturnTarget("?tab=keys", "token-create", features, undefined)).toBeUndefined();
+  });
+
   test("rejects entityId with '#'", () => {
     expect(
       resolveReturnTarget("token-edit/abc#frag", "token-create", features, undefined),
@@ -253,3 +278,61 @@ describe("returnToParams", () => {
     ).toEqual({ returnTo: "token-edit/abc" });
   });
 });
+
+describe("formatReturnTo / splitReturnTo", () => {
+  test("no host params formats exactly like before the snapshot existed", () => {
+    expect(formatReturnTo({ screenId: "token-list" })).toBe("token-list");
+    expect(formatReturnTo({ screenId: "token-list" }, {})).toBe("token-list");
+    expect(formatReturnTo({ screenId: "token-edit", entityId: "abc" })).toBe("token-edit/abc");
+  });
+
+  test("host params round-trip through the value", () => {
+    const raw = formatReturnTo(
+      { screenId: "token-detail", entityId: "abc" },
+      { tab: "keys", "orders.sort": "name", "orders.dir": "asc" },
+    );
+    expect(splitReturnTo(raw)).toEqual({
+      path: "token-detail/abc",
+      state: { tab: "keys", "orders.sort": "name", "orders.dir": "asc" },
+    });
+  });
+
+  test("empty param values are left out of the snapshot", () => {
+    expect(formatReturnTo({ screenId: "token-list" }, { q: "", tab: "keys" })).toBe(
+      "token-list?tab=keys",
+    );
+  });
+
+  test("two nesting levels round-trip one level per split", () => {
+    const inner = formatReturnTo({ screenId: "token-list" }, { returnTo: "settings" });
+    const outer = formatReturnTo({ screenId: "token-edit", entityId: "abc" }, { returnTo: inner });
+
+    const first = splitReturnTo(outer);
+    expect(first.path).toBe("token-edit/abc");
+    expect(first.state["returnTo"]).toBe("token-list?returnTo=settings");
+
+    const second = splitReturnTo(first.state["returnTo"] as string);
+    expect(second.path).toBe("token-list");
+    expect(second.state).toEqual({ returnTo: "settings" });
+  });
+
+  test("a fourth level is dropped, the rest of the snapshot survives", () => {
+    const level3 = formatReturnTo(
+      { screenId: "token-list" },
+      { returnTo: formatReturnTo({ screenId: "token-detail" }, { returnTo: "settings" }) },
+    );
+    const level4 = formatReturnTo({ screenId: "token-edit" }, { returnTo: level3, tab: "keys" });
+
+    expect(splitReturnTo(level4)).toEqual({ path: "token-edit", state: { tab: "keys" } });
+  });
+
+  test("an over-long snapshot degrades to the bare target", () => {
+    expect(formatReturnTo({ screenId: "token-list" }, { q: "x".repeat(600) })).toBe("token-list");
+  });
+
+  test("returnToParams carries the host snapshot", () => {
+    expect(
+      returnToParams({ screenId: "token-list" }, { screenId: "token-create" }, { tab: "keys" }),
+    ).toEqual({ returnTo: "token-list?tab=keys" });
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -82,6 +82,8 @@ import { lastSegment, toKebab } from "./qn";
 import { featureNameFromQualifiedScreenId, qualifyScreenId } from "./qualify-screen-id";
 import { ReferenceFacetBridges, type ReferenceFacetOption } from "./reference-facet-bridge";
 import {
+  navigateToReturn,
+  navigateToReturnOr,
   navigateWithReturnTo,
   type ReturnHost,
   ReturnHostProvider,
@@ -487,6 +489,63 @@ function resolveTenantCurrency(
   return { status: "ready", currency: typeof raw === "string" && raw !== "" ? raw : fallback };
 }
 
+// An entity-less form screen has no `entity.defaultCurrency` to fall back on,
+// so a tenant-declared field whose config query errors or returns no value
+// lands here — same last resort as the entityEdit path's `?? "EUR"`.
+const ACTION_FORM_CURRENCY_FALLBACK = "EUR";
+
+// A money field naming a fixed ISO code (`currency: { kind: "literal", code }`,
+// fw#2839) resolves with no query at all. Read structurally, same idiom as
+// tenantCurrencyMoneyFieldNames above.
+export function literalCurrencyOverrides(
+  fields: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  for (const [name, def] of Object.entries(fields)) {
+    const shape = def as {
+      readonly type?: string;
+      readonly currency?: { readonly kind?: string; readonly code?: string };
+    };
+    const code = shape.currency?.code;
+    if (shape.type === "money" && shape.currency?.kind === "literal" && code !== undefined) {
+      out[name] = code;
+    }
+  }
+  return out;
+}
+
+// Per-field currency for the money fields that declare their own source: a
+// literal code resolves synchronously (fw#2839), a `{ kind: "tenant" }` field
+// needs the tenant-settings config query and makes the caller hold the form
+// until it lands (fw#2933) — seeding the fallback meanwhile would render, and
+// on a fast click submit, the wrong currency. Callers pass the tenant field
+// names themselves because an edit form only needs the fetch for fields the
+// record has no stored value for.
+function useMoneyCurrencyOverrides(
+  fields: Readonly<Record<string, unknown>>,
+  tenantFieldNames: readonly string[],
+  fallback: string,
+): {
+  readonly overrides: Readonly<Record<string, string>> | undefined;
+  readonly loading: boolean;
+} {
+  const query = useQuery<TenantConfigValuesResponse>(
+    "config:query:values",
+    {},
+    { enabled: tenantFieldNames.length > 0 },
+  );
+  const resolution = resolveTenantCurrency(tenantFieldNames, query, fallback);
+  const resolvedTenantCurrency = resolution.status === "ready" ? resolution.currency : undefined;
+  const overrides = useMemo(() => {
+    const out: Record<string, string> = { ...literalCurrencyOverrides(fields) };
+    if (resolvedTenantCurrency !== undefined) {
+      for (const name of tenantFieldNames) out[name] = resolvedTenantCurrency;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }, [fields, tenantFieldNames, resolvedTenantCurrency]);
+  return { overrides, loading: resolution.status === "loading" };
+}
+
 function multiSelectOptionValues(shape: {
   readonly options?: readonly (string | { readonly value: string })[];
 }): ReadonlySet<string> | undefined {
@@ -857,26 +916,11 @@ function EntityEditCreateBody({
     () => tenantCurrencyMoneyFieldNames(entity.fields),
     [entity.fields],
   );
-  const needsTenantCurrency = tenantCurrencyFieldNames.length > 0;
-  const tenantCurrencyQuery = useQuery<TenantConfigValuesResponse>(
-    "config:query:values",
-    {},
-    { enabled: needsTenantCurrency },
-  );
-  const tenantCurrencyResolution = resolveTenantCurrency(
+  const { overrides: moneyCurrencyOverrides, loading: currencyLoading } = useMoneyCurrencyOverrides(
+    entity.fields,
     tenantCurrencyFieldNames,
-    tenantCurrencyQuery,
     entityDefaultCurrency,
   );
-  const resolvedTenantCurrency =
-    tenantCurrencyResolution.status === "ready" ? tenantCurrencyResolution.currency : undefined;
-  const moneyCurrencyOverrides = useMemo(
-    () =>
-      resolvedTenantCurrency !== undefined
-        ? Object.fromEntries(tenantCurrencyFieldNames.map((name) => [name, resolvedTenantCurrency]))
-        : undefined,
-    [tenantCurrencyFieldNames, resolvedTenantCurrency],
-  );
   const initial = useMemo(
     () =>
       mergeSearchParamsIntoInitial(entity.fields, {
@@ -900,7 +944,7 @@ function EntityEditCreateBody({
   const writeCommand = entityWriteCommand(schema.featureName, screen.entity, "create");
   const navigateToList = useNavigateToListAfter(schema, screen.entity);
   const handleCancel = useCallback(
-    () => navigateToReturnTargetOr(nav, returnTarget, navigateToList),
+    () => navigateToReturnOr(nav, returnTarget, navigateToList),
     [nav, returnTarget, navigateToList],
   );
   // Create's write-handler success payload doesn't flatly expose a parent FK
@@ -916,7 +960,7 @@ function EntityEditCreateBody({
       const redirect = screen.redirect;
       if (redirect !== undefined) {
         if (returnToWinsOverRedirect(returnTarget, redirect, schema, appFeatures)) {
-          nav.navigate(returnTarget);
+          navigateToReturn(nav, returnTarget);
         } else if (typeof redirect === "string") {
           // String form unchanged: always carries the newly created
           // record's own id, regardless of the target screen's type. The
@@ -938,7 +982,7 @@ function EntityEditCreateBody({
           nav.navigate({ screenId, ...(entityId !== undefined && { entityId }) });
         }
       } else {
-        navigateToReturnTargetOr(nav, returnTarget, navigateToList);
+        navigateToReturnOr(nav, returnTarget, navigateToList);
         onSaved?.();
       }
     },
@@ -946,7 +990,7 @@ function EntityEditCreateBody({
   );
   // Never seed a tenant-declared money field with entityDefaultCurrency while
   // its real tenant currency is still in flight (fw#2933) — wait instead.
-  if (needsTenantCurrency && tenantCurrencyResolution.status === "loading") {
+  if (currencyLoading) {
     return (
       <Banner padded variant="loading" testId="kumiko-screen-loading">
         Loading…
@@ -1109,26 +1153,11 @@ function EntityEditUpdateForm({
       ),
     [entity.fields, record],
   );
-  const needsTenantCurrency = tenantCurrencyFieldNames.length > 0;
-  const tenantCurrencyQuery = useQuery<TenantConfigValuesResponse>(
-    "config:query:values",
-    {},
-    { enabled: needsTenantCurrency },
-  );
-  const tenantCurrencyResolution = resolveTenantCurrency(
+  const { overrides: moneyCurrencyOverrides, loading: currencyLoading } = useMoneyCurrencyOverrides(
+    entity.fields,
     tenantCurrencyFieldNames,
-    tenantCurrencyQuery,
     entityDefaultCurrency,
   );
-  const resolvedTenantCurrency =
-    tenantCurrencyResolution.status === "ready" ? tenantCurrencyResolution.currency : undefined;
-  const moneyCurrencyOverrides = useMemo(
-    () =>
-      resolvedTenantCurrency !== undefined
-        ? Object.fromEntries(tenantCurrencyFieldNames.map((name) => [name, resolvedTenantCurrency]))
-        : undefined,
-    [tenantCurrencyFieldNames, resolvedTenantCurrency],
-  );
   const initial = useMemo(() => {
     const out: Record<string, unknown> = {};
     for (const name of Object.keys(entity.fields)) {
@@ -1311,7 +1340,7 @@ function EntityEditUpdateForm({
       const redirect = screen.redirect;
       if (redirect !== undefined) {
         if (returnToWinsOverRedirect(returnTarget, redirect, schema, appFeatures)) {
-          nav.navigate(returnTarget);
+          navigateToReturn(nav, returnTarget);
         } else if (typeof redirect === "string") {
           // String form unchanged: navigates without an entityId, same as
           // before the object form existed. The object form resolves like
@@ -1334,14 +1363,14 @@ function EntityEditUpdateForm({
           });
         }
       } else {
-        navigateToReturnTargetOr(nav, returnTarget, navigateToList);
+        navigateToReturnOr(nav, returnTarget, navigateToList);
         onSaved?.();
       }
     },
     [nav, screen.redirect, schema, appFeatures, record, navigateToList, onSaved, returnTarget],
   );
   const handleCancel = useCallback(
-    () => navigateToReturnTargetOr(nav, returnTarget, navigateToList),
+    () => navigateToReturnOr(nav, returnTarget, navigateToList),
     [nav, returnTarget, navigateToList],
   );
   const handleDelete = useCallback(async () => {
@@ -1349,7 +1378,7 @@ function EntityEditUpdateForm({
     if (res.isSuccess) {
       // Never return onto the just-deleted record.
       const target = returnTarget?.entityId !== entityId ? returnTarget : undefined;
-      navigateToReturnTargetOr(nav, target, navigateToList);
+      navigateToReturnOr(nav, target, navigateToList);
       onDeleted?.();
     }
   }, [dispatcher, deleteCommand, entityId, navigateToList, onDeleted, returnTarget, nav]);
@@ -1358,7 +1387,7 @@ function EntityEditUpdateForm({
   // its real tenant currency is still in flight (fw#2933) — wait instead. A
   // stored (non-empty) value is unaffected — it never reaches this branch's
   // fallback because `initial` above already prefers `record[name]`.
-  if (needsTenantCurrency && tenantCurrencyResolution.status === "loading") {
+  if (currencyLoading) {
     return (
       <Banner padded variant="loading" testId="kumiko-screen-loading">
         Loading…
@@ -3281,7 +3310,7 @@ function redirectTargetsRecord(
 }
 
 // Type-guard form narrows `returnTarget` for the caller's subsequent
-// nav.navigate(returnTarget) call.
+// navigateToReturn(nav, returnTarget) call.
 function returnToWinsOverRedirect(
   returnTarget: ScreenTarget | undefined,
   redirect: string | ActionFormRedirect,
@@ -3291,18 +3320,6 @@ function returnToWinsOverRedirect(
   return returnTarget !== undefined && !redirectTargetsRecord(redirect, schema, appFeatures);
 }
 
-function navigateToReturnTargetOr(
-  nav: NavApi,
-  returnTarget: ScreenTarget | undefined,
-  fallback: () => void,
-): void {
-  if (returnTarget !== undefined) {
-    nav.navigate(returnTarget);
-  } else {
-    fallback();
-  }
-}
-
 // Resolves an object-form redirect to a nav target — shared by
 // actionForm and entityEdit (create + update) so the id
 // carries over identically regardless of which screen type triggered it.
@@ -3367,6 +3384,7 @@ function ActionFormBody({
 }): ReactNode {
   const nav = useNav();
   const appFeatures = useAppFeatures();
+  const { Banner } = usePrimitives();
   // Unused when drawer-hosted — onSuccess/onCancelOverride win below first.
   const returnTarget = useReturnTarget(screen.id);
   const synthEntity = useMemo(() => synthesizeActionFormEntity(screen.fields), [screen.fields]);
@@ -3374,12 +3392,27 @@ function ActionFormBody({
   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;
+  // This screen has no entity, so a money field here declares its own currency
+  // source (fw#2839, boot-enforced) — without one the form would seed a bare
+  // `0` the handler's schema rejects. ACTION_FORM_CURRENCY_FALLBACK only
+  // applies when a tenant-declared field's config query errors or holds no
+  // value, matching the entityEdit path's behaviour (fw#2937).
+  const tenantCurrencyFieldNames = useMemo(
+    () => tenantCurrencyMoneyFieldNames(screen.fields),
+    [screen.fields],
+  );
+  const { overrides: moneyCurrencyOverrides, loading: currencyLoading } = useMoneyCurrencyOverrides(
+    screen.fields,
+    tenantCurrencyFieldNames,
+    ACTION_FORM_CURRENCY_FALLBACK,
+  );
   const initial = useMemo(
     () =>
       mergeSearchParamsIntoInitial(screen.fields, {
         searchParams: nav.searchParams,
         urlPrefillFields: screen.urlPrefillFields,
         renderableFields: layoutFieldNames(synthScreen),
+        ...(moneyCurrencyOverrides !== undefined && { moneyCurrencyOverrides }),
         ...(initialOverrides !== undefined && { drawerOverrides: initialOverrides }),
         ...(handoffValues !== undefined && { handoffValues }),
       }) as FormValues,
@@ -3388,6 +3421,7 @@ function ActionFormBody({
       screen.urlPrefillFields,
       nav.searchParams,
       synthScreen,
+      moneyCurrencyOverrides,
       initialOverrides,
       handoffValues,
     ],
@@ -3403,7 +3437,7 @@ function ActionFormBody({
       // navigation, and never one to a record screen (see redirectTargetsRecord).
       if (screen.redirect !== undefined) {
         if (returnToWinsOverRedirect(returnTarget, screen.redirect, schema, appFeatures)) {
-          nav.navigate(returnTarget);
+          navigateToReturn(nav, returnTarget);
         } else {
           const { screenId, entityId } = resolveRedirectTarget(
             screen.redirect,
@@ -3428,8 +3462,18 @@ function ActionFormBody({
       screen.cancelTarget ??
       (screen.redirect !== undefined ? redirectScreenTarget(screen.redirect) : undefined);
     if (target === undefined || target === false) return undefined;
-    return () => nav.navigate(returnTarget ?? { screenId: lastSegment(target) });
+    return () =>
+      navigateToReturnOr(nav, returnTarget, () => nav.navigate({ screenId: lastSegment(target) }));
   }, [nav, screen.redirect, screen.cancelTarget, onCancelOverride, returnTarget]);
+  // Rendering the form before a tenant-declared currency lands would show the
+  // fallback and, on a fast click, submit it (fw#2933) — hold instead.
+  if (currencyLoading) {
+    return (
+      <Banner padded variant="loading" testId="kumiko-screen-loading">
+        Loading…
+      </Banner>
+    );
+  }
   return (
     <RenderEdit
       screen={synthScreen}

package/src/app/projection-detail-shim.ts

@@ -60,6 +60,7 @@ export function synthesizeProjectionDetailScreen(
     if (!isFieldsEditSection(section)) return section;
     return {
       ...section,
+      // kumiko-lint-ignore section-fields-raw rewrites both sources in place — the groups branch below does the same for groups[].fields
       fields: section.fields.map(forceReadOnly),
       ...(section.groups !== undefined && {
         groups: section.groups.map((group) => ({

package/src/app/return-to.tsx

@@ -11,13 +11,72 @@ import { screenAccessAllows } from "./screen-access";
 // and a copied/shared URL.
 export const RETURN_TO_PARAM = "returnTo";
 
+// Screen levels one returnTo value may carry: the host itself plus its own
+// nested chain. Beyond that the host's returnTo is left out of the snapshot.
+const MAX_RETURN_DEPTH = 3;
+// Serialized host snapshot longer than this is dropped whole — the bare
+// target still resolves, only the restored state is lost.
+const MAX_RETURN_STATE_LENGTH = 512;
+
+const NO_RETURN_STATE: Readonly<Record<string, string>> = Object.freeze({});
+
 export type ReturnHost = {
   readonly screenId: string;
   readonly entityId?: string;
 };
 
-export function formatReturnTo(host: ReturnHost): string {
-  return host.entityId !== undefined ? `${host.screenId}/${host.entityId}` : host.screenId;
+export type ReturnTo = {
+  readonly path: string;
+  readonly state: Readonly<Record<string, string>>;
+};
+
+/** Splits `<screenId>[/<entityId>][?<host-params>]`. One `URLSearchParams`
+ *  pass per nesting level — a deeper level stays encoded inside a value and
+ *  is only decoded when that level is reached. */
+export function splitReturnTo(raw: string): ReturnTo {
+  const queryStart = raw.indexOf("?");
+  if (queryStart === -1) return { path: raw, state: NO_RETURN_STATE };
+  return {
+    path: raw.slice(0, queryStart),
+    state: Object.fromEntries(new URLSearchParams(raw.slice(queryStart + 1))),
+  };
+}
+
+// Saturates at MAX_RETURN_DEPTH — callers only ask whether the cap is
+// reached, and an unbounded walk would follow attacker-sized nesting.
+function returnToDepth(raw: string): number {
+  let depth = 1;
+  let current = raw;
+  while (depth < MAX_RETURN_DEPTH) {
+    const nested = splitReturnTo(current).state[RETURN_TO_PARAM];
+    if (nested === undefined) return depth;
+    depth += 1;
+    current = nested;
+  }
+  return depth;
+}
+
+// Both caps degrade to the pre-snapshot value instead of failing, so a value
+// that hits one still navigates.
+function returnStateSnapshot(hostParams: Readonly<Record<string, string>> | undefined): string {
+  if (hostParams === undefined) return "";
+  const snapshot = new URLSearchParams();
+  for (const [key, value] of Object.entries(hostParams)) {
+    if (value === "") continue;
+    if (key === RETURN_TO_PARAM && returnToDepth(value) >= MAX_RETURN_DEPTH) continue;
+    snapshot.set(key, value);
+  }
+  const serialized = snapshot.toString();
+  return serialized.length > MAX_RETURN_STATE_LENGTH ? "" : serialized;
+}
+
+export function formatReturnTo(
+  host: ReturnHost,
+  hostParams?: Readonly<Record<string, string>>,
+): string {
+  const path = host.entityId !== undefined ? `${host.screenId}/${host.entityId}` : host.screenId;
+  const state = returnStateSnapshot(hostParams);
+  return state === "" ? path : `${path}?${state}`;
 }
 
 // {} when target IS host — pushPath no-ops on the same path, so the param
@@ -25,12 +84,13 @@ export function formatReturnTo(host: ReturnHost): string {
 export function returnToParams(
   host: ReturnHost | undefined,
   target: ScreenTarget,
+  hostParams?: Readonly<Record<string, string>>,
 ): Readonly<Record<string, string>> {
   if (host === undefined) return {};
   if (lastSegment(target.screenId) === host.screenId && target.entityId === host.entityId) {
     return {};
   }
-  return { [RETURN_TO_PARAM]: formatReturnTo(host) };
+  return { [RETURN_TO_PARAM]: formatReturnTo(host, hostParams) };
 }
 
 export function navigateWithReturnTo(
@@ -39,16 +99,42 @@ export function navigateWithReturnTo(
   host: ReturnHost | undefined,
   params?: Readonly<Record<string, string | null>>,
 ): void {
+  // Snapshot before navigating — nav.searchParams still describes the host.
+  const returnParams = returnToParams(host, target, nav.searchParams);
   nav.navigate(target);
   const merged: Record<string, string | null> = {
     ...(params ?? {}),
-    ...returnToParams(host, target),
+    ...returnParams,
   };
   if (Object.keys(merged).length > 0) {
     nav.setSearchParams(merged);
   }
 }
 
+/** Jumps back to an already-validated returnTo target and restores the host
+ *  search params carried in the same value. The host's own returnTo travels
+ *  with them, so a chain unwinds one level per jump. */
+export function navigateToReturn(nav: NavApi, target: ScreenTarget): void {
+  const raw = nav.searchParams[RETURN_TO_PARAM];
+  const state = raw === undefined ? NO_RETURN_STATE : splitReturnTo(raw).state;
+  nav.navigate(target);
+  // The explicit null drops this screen's own returnTo on nav impls whose
+  // navigate keeps the query.
+  nav.setSearchParams({ ...state, [RETURN_TO_PARAM]: state[RETURN_TO_PARAM] ?? null });
+}
+
+export function navigateToReturnOr(
+  nav: NavApi,
+  target: ScreenTarget | undefined,
+  fallback: () => void,
+): void {
+  if (target === undefined) {
+    fallback();
+    return;
+  }
+  navigateToReturn(nav, target);
+}
+
 // "%" is left alone — route entityIds come raw from the path and can carry it.
 const UNSAFE_ENTITY_ID_PATTERN = /[\\?#\s]/;
 
@@ -61,7 +147,7 @@ export function resolveReturnTarget(
   userRoles: readonly string[] | undefined,
 ): ScreenTarget | undefined {
   if (raw === undefined || raw === "") return undefined;
-  const segments = raw.split("/");
+  const segments = splitReturnTo(raw).path.split("/");
   if (segments.length !== 1 && segments.length !== 2) return undefined;
   if (segments.some((segment) => segment === "")) return undefined;
   const [screenId, entityId] = segments;

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

@@ -10,11 +10,15 @@ import {
   synthesizeSecretMintConfirmScreen,
 } from "./action-form-shim";
 import type { FeatureSchema } from "./feature-schema";
-import { buildInitialValues, mergeSearchParamsIntoInitial } from "./kumiko-screen";
+import {
+  buildInitialValues,
+  literalCurrencyOverrides,
+  mergeSearchParamsIntoInitial,
+} from "./kumiko-screen";
 import { layoutFieldNames } from "./layout-fields";
 import { useInitialValuesHandoff, useNav } from "./nav";
 import { lastSegment } from "./qn";
-import { useReturnTarget } from "./return-to";
+import { navigateToReturnOr, useReturnTarget } from "./return-to";
 
 export type SecretMintBodyProps = {
   readonly schema: FeatureSchema;
@@ -71,6 +75,11 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
         searchParams: nav.searchParams,
         urlPrefillFields: screen.urlPrefillFields,
         renderableFields: layoutFieldNames(synthScreen),
+        // A mint form has no entity either, so its money fields name their own
+        // currency source (fw#2839). Only the literal form is resolved here:
+        // `{ kind: "tenant" }` would need the config query this screen never
+        // runs, and a one-time secret mint has no money use case to justify it.
+        moneyCurrencyOverrides: literalCurrencyOverrides(screen.fields),
         ...(handoffValues !== undefined && { handoffValues }),
       }) as FormValues,
     [screen.fields, screen.urlPrefillFields, nav.searchParams, synthScreen, handoffValues],
@@ -91,7 +100,14 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
     [screen, confirm],
   );
   const confirmInitial = useMemo(
-    () => (confirm !== undefined ? (buildInitialValues(confirm.fields) as FormValues) : undefined),
+    () =>
+      confirm !== undefined
+        ? (buildInitialValues(
+            confirm.fields,
+            undefined,
+            literalCurrencyOverrides(confirm.fields),
+          ) as FormValues)
+        : undefined,
     [confirm],
   );
 
@@ -114,7 +130,8 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
   const handleCancel = useMemo<(() => void) | undefined>(() => {
     const target = screen.cancelTarget ?? screen.redirect;
     if (target === undefined || target === false) return undefined;
-    return () => nav.navigate(returnTarget ?? { screenId: lastSegment(target) });
+    return () =>
+      navigateToReturnOr(nav, returnTarget, () => nav.navigate({ screenId: lastSegment(target) }));
   }, [nav, screen.redirect, screen.cancelTarget, returnTarget]);
 
   // Ends the reveal phase for both paths (the bare acknowledge button, and a
@@ -125,8 +142,11 @@ export function SecretMintBody({ schema, screen, translate }: SecretMintBodyProp
   const finishMint = useCallback(() => {
     setRevealed(null);
     carriedRef.current = {};
-    if (screen.redirect !== undefined) {
-      nav.navigate(returnTarget ?? { screenId: lastSegment(screen.redirect) });
+    const redirect = screen.redirect;
+    if (redirect !== undefined) {
+      navigateToReturnOr(nav, returnTarget, () =>
+        nav.navigate({ screenId: lastSegment(redirect) }),
+      );
     } else {
       setDone(true);
     }

package/src/app/secrets-edit-body.tsx

@@ -118,6 +118,7 @@ export function SecretsEditBody({ screen, translate }: SecretsEditBodyProps): Re
           key={section.title ?? `section-${index}`}
           {...(section.title !== undefined && { title: effectiveTranslate(section.title) })}
         >
+          {/* kumiko-lint-ignore section-fields-raw secretsEdit section fields are field-id strings, not EditFieldSpec */}
           {section.fields.map((fieldId) => {
             const qualified = screen.secretKeys[fieldId];
             if (qualified === undefined) return null;

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.291.0",
+    "type": "improvement",
+    "title": "returnTo restores the host screen's search params and nests return chains",
+    "detail": "A `returnTo` value may now carry the host's search params as a nested query (`token-detail/abc?tab=keys&orders.sort=name`), so jumping back lands on the tab, filter and sort the user left — `use-list-url-state` keys and `layout.mode: \"tabs\"` included, with no per-key allowlist to keep in sync. The host's own `returnTo` travels inside that snapshot, so a chain (list → edit → action form → back → save) unwinds one level per jump instead of losing its tail. Two syntactic caps bound the URL: at most three screen levels per value, and a snapshot over 512 characters is dropped whole. Both degrade to the previous bare value rather than failing, and a value without a snapshot is byte-identical to before, so existing links keep working. Target validation is unchanged: `resolveReturnTarget` sees only the path part and still rejects anything that is not an accessible in-app screen."
+  },
   {
     "version": "0.290.0",
     "type": "fix",

package/src/components/embedded-list-field.tsx

@@ -151,7 +151,7 @@ export function EmbeddedListField({
   const referenceQueries = referenceCells.map((cell) => {
     const refFeature = cell.refFeature ?? featureName;
     const refEntity = cell.refEntity ?? "";
-    const qn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+    const qn = cell.refOptionsQuery ?? `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
     // biome-ignore lint/correctness/useHookAtTopLevel: referenceCells comes from the entity-schema definition — fixed for the screen's lifetime, not a real conditional-hook risk.
     return useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(qn, {
       limit: REFERENCE_COMBOBOX_LIMIT,
@@ -165,10 +165,10 @@ export function EmbeddedListField({
     if (cell.type === "reference") {
       const idx = referenceCells.indexOf(cell);
       const query = referenceQueries[idx];
-      const labelField = cell.refLabelField ?? "id";
+      const labelKey = cell.refOptionsQuery !== undefined ? "label" : (cell.refLabelField ?? "id");
       const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
         value: String(row["id"] ?? ""),
-        label: String(row[labelField] ?? row["id"] ?? ""),
+        label: String(row[labelKey] ?? row["id"] ?? ""),
       }));
       return {
         field: cell.field,

package/src/components/render-field.tsx

@@ -167,6 +167,24 @@ export function RenderField({
   );
 }
 
+// Where a reference field's option rows come from, and which of their keys
+// holds the display text — the entity's own list handler plus `refLabelField`
+// by default, or an author-supplied handler whose rows carry `label`
+// (fw#2780), for targets with no readable column of their own.
+function referenceOptionSource(
+  field: Pick<EditFieldViewModel, "refLabelField" | "refOptionsQuery">,
+  refFeature: string,
+  refEntity: string,
+): { readonly queryQn: string; readonly labelKey: string } {
+  if (field.refOptionsQuery !== undefined) {
+    return { queryQn: field.refOptionsQuery, labelKey: "label" };
+  }
+  return {
+    queryQn: `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`,
+    labelKey: field.refLabelField ?? "id",
+  };
+}
+
 // Tier 2.7e-3 + 2.1c: Reference-Input rendert eine Searchable Combobox
 // gefüllt aus einer Live-Query auf die referenced Entity. Default-
 // Limit: 200 — bei größeren Datasets fehlt der Tail im Dropdown
@@ -200,12 +218,13 @@ function ReferenceInput({
   const { Banner } = usePrimitives();
   const refEntity = field.refEntity ?? "";
   const refFeature = field.refFeature ?? featureName;
-  const labelField = field.refLabelField ?? "id";
   const isMultiple = field.refMultiple === true;
   // Tier 2.7e Cross-Feature: refFeature kann ≠ featureName sein
   // (z.B. items.assignee → users:query:user:list). Default ist
   // same-feature, kommt aus dem ViewModel (parseRefTarget).
-  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  // fw#2780: refOptionsQuery replaces that source with an author-supplied
+  // handler whose rows already carry a composed `label`.
+  const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
   // Issue #1681: "+ Neu" in der Combobox öffnet den Create-Screen der
   // referenced entity als Dialog, statt die aktuelle Form zu verlassen.
   // refFeature kann ein anderes Feature als das aktuell gerenderte sein
@@ -276,10 +295,10 @@ function ReferenceInput({
     const rows = queryResult.data?.rows ?? [];
     return rows.map((row) => {
       const idVal = String(row["id"] ?? "");
-      const label = String(row[labelField] ?? idVal);
+      const label = String(row[labelKey] ?? idVal);
       return { value: idVal, label };
     });
-  }, [queryResult.data, labelField]);
+  }, [queryResult.data, labelKey]);
   // Single: value ist String/null; Multi: Array. Coerce auf das was
   // der Combobox-Mode erwartet, damit Storage-Drift (Server liefert
   // alten String wo jetzt Array erwartet wird) keine Crash auslöst.
@@ -431,9 +450,8 @@ function ReadOnlyReferenceValue({
   const t = useTranslation();
   const refEntity = field.refEntity ?? "";
   const refFeature = field.refFeature ?? featureName;
-  const labelField = field.refLabelField ?? "id";
   const isMultiple = field.refMultiple === true;
-  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
+  const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
   const queryResult = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
     limit: REFERENCE_COMBOBOX_LIMIT,
   });
@@ -454,7 +472,7 @@ function ReadOnlyReferenceValue({
   const labels = ids.map((id) => {
     if (systemLabel !== undefined && id === systemLabel.id) return t(systemLabel.labelKey);
     const row = rows.find((r) => String(r["id"] ?? "") === id);
-    return row !== undefined ? String(row[labelField] ?? id) : id;
+    return row !== undefined ? String(row[labelKey] ?? id) : id;
   });
   return <Text testId={`field-value-${field.field}`}>{labels.join(", ")}</Text>;
 }

package/src/index.ts

@@ -82,12 +82,15 @@ export {
   useNavigateWithInitialValues,
 } from "./app/nav";
 export { lastSegment } from "./app/qn";
-export type { ReturnHost } from "./app/return-to";
+export type { ReturnHost, ReturnTo } from "./app/return-to";
 export {
+  navigateToReturn,
+  navigateToReturnOr,
   navigateWithReturnTo,
   RETURN_TO_PARAM,
   ReturnHostProvider,
   resolveReturnTarget,
+  splitReturnTo,
   useReturnHost,
   useReturnTarget,
 } from "./app/return-to";