@cosmicdrift/kumiko-framework 0.239.0 → 0.241.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.239.0",
+  "version": "0.241.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.239.0",
+    "@cosmicdrift/kumiko-types": "0.241.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.239.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.241.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "ProjectionDetailScreenDefinition gains singleton: boolean for self-service screens bound to a caller-scoped query (fw#2312).",
+    "detail": "A `projectionDetail` screen previously always resolved its row from a path id — the only case `ProjectionDetailBody` handled — so binding one to a `me`-style query (e.g. `user:query:user:me`) rendered nothing but a \"missing id\" error banner. With `singleton: true`, the query is called without the `idParam` key (there is no id to send) and any path id is ignored rather than forwarded into the query or into extension sections' entity-id resolution — a singleton row is server-picked, so no client-supplied id can reach it. The boot validator rejects `idParam` or `detailFor` declared together with `singleton` (both are meaningless once the server owns row selection)."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "DashboardStatPanel gains an optional params field for static query parameters (fw#2312).",
+    "detail": "`DashboardStatPanel.params?: Readonly<Record<string, unknown>>` (`@cosmicdrift/kumiko-types`) is merged under the panel's dynamic `filterParams` by `@cosmicdrift/kumiko-renderer-web`'s dashboard body — lets a panel pin a value (e.g. a status facet) the screen-wide filter doesn't cover, without needing its own query. Additive; existing `dashboard` screens are unaffected."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "EditFieldSpec.renderer gains a json format for pretty-printed structured fields (fw#2312).",
+    "detail": "`FieldFormatRegistry.json: { indent?: number }` (`@cosmicdrift/kumiko-types`, resolved by `@cosmicdrift/kumiko-headless`) — set `renderer: { format: \"json\", indent: 2 }` on an `EditFieldSpec` to pretty-print a JSON-string field instead of showing the raw escaped string. Pairs with the new `JsonView` primitive below when `@cosmicdrift/kumiko-renderer-web` is in use."
+  },
+  {
+    "version": "0.241.0",
+    "type": "improvement",
+    "title": "Optional JsonView primitive for structured, syntax-highlighted JSON display (fw#2312).",
+    "detail": "`CorePrimitives.JsonView` (`@cosmicdrift/kumiko-renderer`, web impl `DefaultJsonView` in `@cosmicdrift/kumiko-renderer-web`) receives the raw value (not a pre-stringified string) and stringifies + tokenizes itself; never throws on circular references, `BigInt`, or other non-serializable input. Optional on `CorePrimitives`, so an existing partial `CorePrimitives` test mock/provider keeps compiling unchanged — every call site (renderer's `format: \"json\"` fields, the jsonb/embedded/files/images fallback banner, `EditorPanel`'s unresolved-target args display) falls back to the prior `<Text>`/`<pre>` rendering when no `JsonView` is registered. A custom `PrimitivesProvider` that wants the improved rendering needs to add a `JsonView` implementation; nothing breaks if it doesn't."
+  },
   {
     "version": "0.235.0",
     "type": "breaking",

package/src/engine/__tests__/projection-detail-singleton.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+// fw#2312: `singleton: true` marks a projectionDetail screen whose query
+// determines the shown row from the caller's context (session), not a row
+// id in the path — a self-service screen like "my profile". idParam names
+// the query-payload key for a path row id, which a singleton screen never
+// sends; detailFor drives the auto-generated "Edit" action's navigation via
+// that same path id (fw#2166). Both combinations are rejected at boot
+// instead of silently winning (idParam ignored / edit button opening a
+// blank create form).
+describe("validateBoot — projectionDetail singleton (fw#2312)", () => {
+  test("singleton + idParam throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        idParam: "userId",
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "profile" \(projectionDetail\) sets both singleton: true and idParam/,
+    );
+  });
+
+  test("singleton + detailFor throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.entity("user", createEntity({ fields: { name: createTextField() } }));
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        detailFor: "user",
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+      r.screen({
+        id: "user-edit",
+        type: "entityEdit",
+        entity: "user",
+        layout: { sections: [{ columns: 1, fields: ["name"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /Screen "profile" \(projectionDetail\) sets both singleton: true and detailFor/,
+    );
+  });
+
+  test("singleton without idParam/detailFor boots cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("me", z.object({}), async () => ({ id: "u1" }), {
+        access: { openToAll: true },
+      });
+      r.screen({
+        id: "profile",
+        type: "projectionDetail",
+        query: "app:query:me",
+        singleton: true,
+        layout: { sections: [{ title: "s", fields: ["id"] }] },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+});

package/src/engine/__tests__/screen.test.ts

@@ -435,6 +435,461 @@ describe("r.screen() — registration", () => {
     );
   });
 
+  test("validateBoot rejects a relatedList rowAction with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [{ id: "sync", label: "actions.sync", handler: "app:write:missing" }],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*rowAction "sync" handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a relatedList rowAction bound to a registered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.writeHandler(
+          "sync",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowActions: [
+                  {
+                    id: "sync",
+                    label: "actions.sync",
+                    handler: "app:write:sync",
+                    payload: { pick: ["name"] },
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a relatedList section with both rowClick and a rowActions rowClick:true entry (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("billing", (r) => {
+        r.entity(
+          "invoice",
+          createEntity({ table: "invoices", fields: { name: createTextField() } }),
+        );
+        r.screen({
+          id: "invoice-detail",
+          type: "custom",
+          renderer: { react: { __component: "stub" } },
+          detailFor: "invoice",
+        });
+      }),
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "relatedList",
+                title: "s",
+                query: "app:query:foo:list",
+                columns: ["name"],
+                rowClick: { entity: "invoice" },
+                rowActions: [
+                  {
+                    kind: "navigate",
+                    id: "open",
+                    label: "actions.open",
+                    entity: "invoice",
+                    entityId: "id",
+                    rowClick: true,
+                  },
+                ],
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /relatedList\).*has both a rowClick and 1 rowActions marked rowClick:true/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an empty fieldDefs map (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: {},
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has an empty fieldDefs map/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with zero fields (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: [],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/\(writeForm\) has zero fields/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm field with no entry in fieldDefs (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["sku"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) field "sku" has no entry in fieldDefs/,
+    );
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section in a wizard layout (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            mode: "wizard",
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(/writeForm.*wizard layout/);
+  });
+
+  test("validateBoot rejects a projectionDetail writeForm section with an unregistered write-handler (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:missing",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(writeForm\) handler "app:write:missing".*not a registered write-handler/,
+    );
+  });
+
+  test("validateBoot accepts a valid projectionDetail writeForm section (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+                submitLabel: "actions.save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  // withBootValidatorFixture auto-fills every key requiredKeysFromFeature
+  // reports, so every other boot test in this file passes regardless of
+  // whether required-surface-keys.ts's writeForm branch names the right key
+  // — it would pass even for a wrong namespace. Bypass the fixture (raw
+  // validateBootRaw, no stubTranslations) to pin the actual key contract.
+  test("validateBoot requires a translation for a writeForm field's own label, namespaced under the write-form pseudo-entity (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        // Screens always require their own "screen:<id>.title" key — supplied
+        // here so the throw below isolates the one key this test is about.
+        r.translations({ keys: { "screen:x.title": { en: "X" } } });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).toThrow(
+      '[i18n] Feature "app": required translation key missing: "app:entity:__write-form-section__:field:name"',
+    );
+  });
+
+  test("translating the writeForm field's pseudo-entity key lets boot pass", () => {
+    const features = [
+      defineFeature("app", (r) => {
+        r.translations({
+          keys: {
+            "screen:x.title": { en: "X" },
+            "app:entity:__write-form-section__:field:name": { en: "Name" },
+          },
+        });
+        r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+          access: { openToAll: true },
+        });
+        r.writeHandler(
+          "save",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "x",
+          type: "projectionDetail",
+          query: "app:query:foo:detail",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "app:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+
+    expect(() => validateBootRaw(features)).not.toThrow();
+  });
+
+  test("validateBoot rejects a writeForm section on entityEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.entity("product", productEntity());
+        r.screen({
+          id: "product-edit",
+          type: "entityEdit",
+          entity: "product",
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(entityEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on configEdit (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.config({
+          keys: { "site-name": createTenantConfig("text", { default: "" }) },
+        });
+        r.screen({
+          id: "settings",
+          type: "configEdit",
+          scope: "tenant",
+          configKeys: { siteName: "shop:config:site-name" },
+          fields: { siteName: { type: "text" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(configEdit\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
+  test("validateBoot rejects a writeForm section on actionForm (fw editable-detail-screens)", () => {
+    const features = [
+      defineFeature("shop", (r) => {
+        r.writeHandler(
+          "restock",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          { access: { roles: ["Admin"] } },
+        );
+        r.screen({
+          id: "restock",
+          type: "actionForm",
+          handler: "shop:write:restock",
+          fields: { qty: { type: "number" } } as never,
+          layout: {
+            sections: [
+              {
+                kind: "writeForm",
+                title: "s",
+                fieldDefs: { name: createTextField() },
+                fields: ["name"],
+                handler: "shop:write:save",
+              },
+            ],
+          },
+        });
+      }),
+    ];
+    expect(() => validateBoot(features)).toThrow(
+      /\(actionForm\) writeForm section "s".*projectionDetail-only/,
+    );
+  });
+
   test("stores an entityEdit screen with sections + conditional fields", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/screens.ts

@@ -9,7 +9,12 @@ import { rowMetaFieldNames } from "../../db/table-builder";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { isKebabSegment, isValidQn, qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
-import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeEditField,
+  normalizeListColumn,
+} from "../screen-helpers";
 import type { EntityDefinition, FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
@@ -617,6 +622,26 @@ export function validateScreens(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has empty or non-string query.`,
         );
       }
+      if (screen.singleton === true && screen.idParam !== undefined) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and idParam — singleton means the server picks the row from the caller's context, so there ` +
+            `is no row id to send under idParam. Remove idParam.`,
+        );
+      }
+      // singleton has no row id in the path, but the auto-generated "Edit"
+      // action (fw#2166, defaultEditAction in kumiko-screen.tsx) navigates
+      // to the detailFor entity's entityEdit screen using that path id —
+      // under singleton it would silently open that screen in CREATE mode
+      // instead of editing the singleton row. Reject rather than let that
+      // win silently, same as the idParam check above.
+      if (screen.singleton === true && screen.detailFor !== undefined) {
+        throw new Error(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and detailFor — the auto-generated "Edit" action navigates using the path's row id, which a ` +
+            `singleton screen never has. Remove detailFor, or declare an explicit "edit" action instead.`,
+        );
+      }
       if (screen.layout.sections.length === 0) {
         throw new Error(
           `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) has an empty sections list — ` +
@@ -732,6 +757,93 @@ export function validateScreens(
               );
             }
           }
+          if (section.rowActions !== undefined) {
+            for (const action of section.rowActions) {
+              if (action.kind === "navigate") {
+                const target = resolveRowActionNavigateTarget(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "rowAction",
+                  action,
+                  allScreenQns,
+                  navTargetShortIds,
+                  screensByShortId,
+                  detailForScreens,
+                );
+                validateRowActionNavigateParams(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  undefined,
+                  action,
+                  target,
+                );
+              } else if (!allWriteHandlerQns.has(action.handler)) {
+                throw new Error(
+                  `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section ` +
+                    `"${section.title}" (relatedList) rowAction "${action.id}" handler "${action.handler}" ` +
+                    `is not a registered write-handler. Check the QN spelling (expected ` +
+                    `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`,
+                );
+              }
+            }
+            // section.rowClick (legacy, navigate-only) and a rowActions entry
+            // marked rowClick:true both claim the row-body click — same
+            // at-most-one constraint as entityList/projectionList's
+            // validateAtMostOneRowClick, just spanning two fields instead of one.
+            const rowClickActionCount = section.rowActions.filter(
+              (a) => a.kind === "navigate" && a.rowClick === true,
+            ).length;
+            const legacyRowClickCount = section.rowClick !== undefined ? 1 : 0;
+            if (rowClickActionCount + legacyRowClickCount > 1) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(relatedList) has both a rowClick and ${rowClickActionCount} rowActions marked ` +
+                  `rowClick:true — at most one may fire on a row-body click.`,
+              );
+            }
+          }
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          if (Object.keys(section.fieldDefs).length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has an empty fieldDefs map — declare at least one field type.`,
+            );
+          }
+          if (section.fields.length === 0) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) has zero fields — drop the section or add fields to it.`,
+            );
+          }
+          for (const f of section.fields) {
+            const fieldName = normalizeEditField(f).field;
+            if (section.fieldDefs[fieldName] === undefined) {
+              throw new Error(
+                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                  `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
+                  `a type declared there.`,
+              );
+            }
+          }
+          if (screen.layout.mode === "wizard") {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `is kind "writeForm" in a wizard layout — a self-persisting form is not supported in a ` +
+                `stepped form. Remove mode: "wizard" or drop the writeForm section.`,
+            );
+          }
+          if (!allWriteHandlerQns.has(section.handler)) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) handler "${section.handler}" is not a registered write-handler. Check the QN ` +
+                `spelling (expected "<feature>:write:<short>") and that the handler is declared via ` +
+                `r.writeHandler(...).`,
+            );
+          }
           continue;
         }
         if (section.fields.length === 0) {
@@ -837,6 +949,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (configEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -952,6 +1070,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (actionForm) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -1308,6 +1432,12 @@ export function validateScreens(
               `primitive (fw#2166).`,
           );
         }
+        if (isWriteFormEditSection(section)) {
+          throw new Error(
+            `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) writeForm section ` +
+              `"${section.title}" is not supported — writeForm is a projectionDetail-only primitive.`,
+          );
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/index.ts

@@ -242,6 +242,7 @@ export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-build
 export {
   isExtensionEditSection,
   isFieldsEditSection,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "./screen-helpers";

package/src/engine/screen-helpers.ts

@@ -3,6 +3,7 @@ import type {
   EditFieldSpec,
   EditFieldsSection,
   EditSectionSpec,
+  EditWriteFormSection,
   FieldCondition,
   FormatSpec,
   ListColumnSpec,
@@ -16,6 +17,10 @@ export function isFieldsEditSection(section: EditSectionSpec): section is EditFi
   return section.kind === undefined || section.kind === "fields";
 }
 
+export function isWriteFormEditSection(section: EditSectionSpec): section is EditWriteFormSection {
+  return section.kind === "writeForm";
+}
+
 // Type guard — narrows FieldRenderer to FormatSpec. Useful for renderer
 // authors who branch on the three FieldRenderer variants without manual
 // "format" in renderer checks.

package/src/engine/types/index.ts

@@ -275,6 +275,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,

package/src/i18n/required-surface-keys.ts

@@ -1,4 +1,8 @@
-import { isExtensionEditSection, normalizeListColumn } from "../engine/screen-helpers";
+import {
+  isExtensionEditSection,
+  isWriteFormEditSection,
+  normalizeListColumn,
+} from "../engine/screen-helpers";
 import type {
   ActionFormScreenDefinition,
   ConfigEditScreenDefinition,
@@ -27,6 +31,11 @@ export const CONFIG_EDIT_ENTITY = "__config-edit__";
 /** Pseudo-entity for projectionDetail field labels (renderer projection-detail-shim). */
 export const PROJECTION_DETAIL_ENTITY = "__projection-detail__";
 
+/** Pseudo-entity for a projectionDetail writeForm section's own fieldDefs
+ *  (distinct from PROJECTION_DETAIL_ENTITY — the section's fields aren't
+ *  drawn from the host record's display entity). */
+export const WRITE_FORM_SECTION_ENTITY = "__write-form-section__";
+
 export function fieldLabelKey(featureName: string, entityName: string, fieldName: string): string {
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
@@ -247,6 +256,16 @@ export function requiredKeysFromScreen(
             const normalized = normalizeListColumn(col);
             if (normalized.label !== undefined) pushKey(out, normalized.label);
           }
+          for (const action of section.rowActions ?? []) pushRowActionKeys(out, action);
+          continue;
+        }
+        if (isWriteFormEditSection(section)) {
+          pushKey(out, section.title);
+          pushKey(out, section.submitLabel);
+          for (const f of section.fields) {
+            const fieldName = editFieldName(f);
+            out.add(fieldLabelKey(featureName, WRITE_FORM_SECTION_ENTITY, fieldName));
+          }
           continue;
         }
         pushKey(out, section.title);

package/src/ui-types/index.ts

@@ -30,6 +30,7 @@ export {
   isExtensionEditSection,
   isFieldsEditSection,
   isFormatSpec,
+  isWriteFormEditSection,
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/screen-helpers";
@@ -74,6 +75,7 @@ export type {
   EditLayout,
   EditRelatedListSection,
   EditSectionSpec,
+  EditWriteFormSection,
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
@@ -100,7 +102,10 @@ export type {
 export type { TargetRef } from "../engine/types/target-ref";
 export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
-export { PROJECTION_DETAIL_ENTITY } from "../i18n/required-surface-keys";
+export {
+  PROJECTION_DETAIL_ENTITY,
+  WRITE_FORM_SECTION_ENTITY,
+} from "../i18n/required-surface-keys";
 export type {
   AppSchema,
   FeatureSchema,