@rippling/rippling-sdk 0.2.0-alpha.49 → 0.2.0-alpha.51

package/src/lib/manifest/custom-object-page-layout.ts

@@ -11,6 +11,23 @@ export interface PageLayoutDeletionIdentifier {
   objectRqlName: string;
 }
 
+export type ObjectRqlName = string;
+export type BlueprintKey = string;
+export type LayoutApiName = string;
+export type TabKey = string;
+export type SectionKey = string;
+export type HeaderFieldKey = string;
+export type FieldRqlName = string;
+export type RelatedObjectRqlName = string;
+export type CanvasCompositionId = string;
+export type HeaderButtonKey = string;
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
 // ---------------------------------------------------------------------------
 // header_edits — HeaderEditsDTO
 // ---------------------------------------------------------------------------
@@ -18,7 +35,7 @@ export interface PageLayoutDeletionIdentifier {
 /** Edit to a built-in (system) header field. */
 export interface SystemHeaderFieldEdit {
   /** Replace the system field's RQL field reference. Optional. */
-  newRqlField?: string;
+  newRqlField?: FieldRqlName;
   /** Remove this system field from the header. Optional. */
   deleted?: boolean;
 }
@@ -31,9 +48,9 @@ export interface SystemHeaderFieldEdit {
  */
 export interface NewHeaderField {
   /** RQL field name to display. Required. */
-  rqlName: string;
+  rqlName: FieldRqlName;
   /** Stable key for this field. Required. */
-  key: string;
+  key: HeaderFieldKey;
   /** Whether the user can remove this field. Optional. */
   canBeDeleted?: boolean;
   /** Whether the user can swap this field for another. Optional. */
@@ -53,74 +70,200 @@ export interface NewHeaderField {
  */
 export interface HeaderEdits {
   /** Replace the record title field (pass the field's api_name). Optional. */
-  newTitleField?: string | null;
+  newTitleField?: FieldRqlName;
   /** Remove the title field from the header. Optional. */
   titleFieldDeleted?: boolean;
   /** Replace the record description field. Optional. */
-  newDescriptionField?: string | null;
+  newDescriptionField?: FieldRqlName;
   /** Remove the description field from the header. Optional. */
   descriptionFieldDeleted?: boolean;
   /** Edits to built-in system header fields, keyed by system field key. Optional. */
-  systemFieldEdits?: Record<string, SystemHeaderFieldEdit>;
+  systemFieldEdits?: Record<HeaderFieldKey, SystemHeaderFieldEdit>;
   /** Additional custom fields to add to the header. Optional. */
   newFields?: NewHeaderField[];
   /** Ordered list of header field RQL names. Custom header keys are accepted and converted. Optional. */
-  headerFieldsOrder?: string[];
+  headerFieldsOrder?: FieldRqlName[];
   /** Action button keys to show in the header. Optional. */
-  buttons?: string[];
+  buttons?: HeaderButtonKey[];
+}
+
+interface SerializedSystemHeaderFieldEdit extends Omit<SystemHeaderFieldEdit, 'newRqlField'> {
+  newRqlField?: FieldRqlName | null;
+}
+
+interface SerializedHeaderEdits
+  extends Omit<HeaderEdits, 'newTitleField' | 'newDescriptionField' | 'systemFieldEdits'> {
+  newTitleField?: FieldRqlName | null;
+  newDescriptionField?: FieldRqlName | null;
+  systemFieldEdits?: Record<HeaderFieldKey, SerializedSystemHeaderFieldEdit>;
 }
 
 // ---------------------------------------------------------------------------
 // tab_edits — TabEditsDTO + section/tab DTOs
 // ---------------------------------------------------------------------------
 
+export type SectionFieldsLayout = 'one_column' | 'two_column' | 'three_column' | 'responsive';
+export type TabLayout = 'vertical' | 'horizontal';
+export type SectionMovementOption = 'static' | 'tab' | 'free';
+export type FieldMovementOption = 'tab' | 'free';
+export type CustomObjectCustomSectionComponentKey = 'attachments' | 'comments';
+
+/** Default value wrapper used by `SectionField.defaultValue`. */
+export interface SectionFieldDefaultValue {
+  value: JsonValue;
+}
+
 /** Options for one field entry inside a `fields_section`. */
 export interface SectionFieldOptions {
   /** Hide this field from view. Optional. */
   hidden?: boolean;
   /** Allow inline editing of this field. Optional. */
   editable?: boolean;
+  /** Render this field read-only. Optional. */
+  readOnly?: boolean;
+  /** Default value metadata for the field. Optional. */
+  defaultValue?: SectionFieldDefaultValue;
+  /** Rich-text field height. Optional. */
+  height?: number;
+  /** Whether the layout manager can remove this field. Optional. */
+  canBeDeleted?: boolean;
   /** Controls how the field can be moved in the UI. Optional. */
-  movementOption?: 'tab' | 'free';
+  movementOption?: FieldMovementOption;
 }
 
 /** A typed field entry inside a `fields_section`. */
-export interface SectionFieldRef extends SectionFieldOptions {
+export interface SectionField extends SectionFieldOptions {
   /** Field to display. Required. */
   field: Field;
 }
 
+/** @deprecated Use `SectionField` for object entries or `SectionFieldInput` for field arrays. */
+export type SectionFieldRef = SectionField;
+
 /** One field entry inside a `fields_section`. */
-export type SectionField = Field | SectionFieldRef;
+export type SectionFieldInput = Field | SectionField;
+
+/** Common edit controls for sections. */
+export interface PageLayoutSectionOptions {
+  /** Whether the layout manager can delete this section. Optional. */
+  canBeDeleted?: boolean;
+  /** Whether the layout manager can rename this section. Optional. */
+  canBeRenamed?: boolean;
+  /** Controls how the section can be moved. Optional. */
+  movementOption?: SectionMovementOption;
+  /** Hide the section title. Optional. */
+  hideName?: boolean;
+}
 
 /** A standard field-grid section inside a tab. */
-export interface FieldsSection {
+export interface FieldsSection extends PageLayoutSectionOptions {
   type: 'fields_section';
   /** Field section metadata for the fields displayed in this layout section. Required. */
   section: CustomObjectFieldSection;
-  /** Stable layout section key. Derived from `section.getSectionId()` on the wire. */
-  key?: never;
+  /** Stable layout section key. Optional. Defaults to `section.getSectionId()`. */
+  key?: SectionKey;
   /** Display name of the layout section. Optional. Defaults to the field section name. */
   name?: string;
   /** Fields to display in this section. Required. */
-  fields: SectionField[];
+  fields: SectionFieldInput[];
   /** Column layout for the fields. Optional. @default `'responsive'` (backend default). */
   layout?: SectionFieldsLayout;
 }
 
-/**
- * A section inside a page layout tab.
- *
- * Only `fields_section` is modeled today. Add other section types
- * (`related_object_section`, `custom_section`, …) explicitly as needed.
- */
-export type PageLayoutSection = FieldsSection;
+export interface RelatedObjectSection extends PageLayoutSectionOptions {
+  type: 'related_object_section';
+  /** Stable layout section key. Required. */
+  key: SectionKey;
+  /** Display name of the layout section. Required. */
+  name: string;
+  /** Related object whose records point back to this custom object. Required. */
+  relatedObjectRqlName: RelatedObjectRqlName;
+  /** Field on the related object that points back to this custom object. Required. */
+  relatedFieldRqlName: FieldRqlName;
+  /** Field RQL names to display for related records. Required. */
+  fields: FieldRqlName[];
+}
+
+export interface RelatedFieldSection extends PageLayoutSectionOptions {
+  type: 'related_field_section';
+  /** Stable layout section key. Required. */
+  key: SectionKey;
+  /** Display name of the layout section. Required. */
+  name: string;
+  /** Related object reached from this custom object. Required. */
+  relatedObjectRqlName: RelatedObjectRqlName;
+  /** Field on this custom object that points to the related object. Required. */
+  relatedFieldRqlName: FieldRqlName;
+  /** Field RQL names to display from the related object. Required. */
+  fields: FieldRqlName[];
+  /** Column layout for the fields. Optional. @default `'responsive'` (backend default). */
+  layout?: SectionFieldsLayout;
+}
+
+export interface CustomSection extends PageLayoutSectionOptions {
+  type: 'custom_section';
+  /** Stable layout section key. Required. */
+  key: SectionKey;
+  /** Display name of the layout section. Required. */
+  name: string;
+  /** Custom object section component key. Required. */
+  componentKey: CustomObjectCustomSectionComponentKey;
+}
+
+export interface ResizableLayoutPosition {
+  identifier: string;
+  width: number;
+  height: number;
+  minWidth?: number;
+  minHeight?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+}
+
+export interface ReportsSectionItem {
+  key: string;
+  reportId: string;
+  position: ResizableLayoutPosition;
+  contextualFieldAttrName?: FieldRqlName;
+  visualizationType?: string;
+}
+
+export interface ReportsSection extends PageLayoutSectionOptions {
+  type: 'reports_section';
+  /** Stable layout section key. Required. */
+  key: SectionKey;
+  /** Display name of the layout section. Required. */
+  name: string;
+  /** Reports to display in this section. Required. */
+  reports: ReportsSectionItem[];
+}
+
+export interface CanvasSection extends PageLayoutSectionOptions {
+  type: 'canvas_section';
+  /** Stable layout section key. Required. */
+  key: SectionKey;
+  /** Display name of the layout section. Required. */
+  name: string;
+  /** Canvas composition to render. Required. */
+  canvasCompositionId: CanvasCompositionId;
+  /** Composition input name to field or state path mapping. Optional. */
+  inputMapping?: Record<string, string>;
+}
+
+/** A section inside a page layout tab. */
+export type PageLayoutSection =
+  | FieldsSection
+  | RelatedObjectSection
+  | RelatedFieldSection
+  | CustomSection
+  | ReportsSection
+  | CanvasSection;
 
 /** A tab that contains one or more field-grid sections. */
 export interface TabWithSections {
   type: 'tab_with_sections';
   /** Stable key for this tab. Required. */
-  key: string;
+  key: TabKey;
   /** Display name of the tab. Required. */
   name: string;
   /** Sections inside this tab. Required. */
@@ -131,7 +274,7 @@ export interface TabWithSections {
 export interface CustomTab {
   type: 'custom_tab';
   /** Stable key for this tab. Required. */
-  key: string;
+  key: TabKey;
   /** Display name of the tab. Required. */
   name: string;
   /** Key of the custom component to render. Required. */
@@ -142,8 +285,6 @@ export interface CustomTab {
 export type PageLayoutTab = TabWithSections | CustomTab;
 
 /** Column layout for a `fields_section`. */
-export type SectionFieldsLayout = 'one_column' | 'two_column' | 'three_column' | 'responsive';
-
 /** Edits to a built-in section inside a system tab. */
 export interface SystemSectionEdit {
   /** Rename this section. Optional. */
@@ -153,7 +294,7 @@ export interface SystemSectionEdit {
   /** Change the column layout. Optional. */
   newLayout?: SectionFieldsLayout;
   /** Add fields to this section. Optional. */
-  newFields?: SectionField[];
+  newFields?: SectionFieldInput[];
   /** Hide the section name header. Optional. */
   newHideName?: boolean;
 }
@@ -167,9 +308,9 @@ export interface SystemTabEdit {
   /** Add new sections to this tab. Optional. */
   newSections?: PageLayoutSection[];
   /** Edits to built-in sections inside this tab, keyed by section key. Optional. */
-  systemSectionEdits?: Record<string, SystemSectionEdit>;
+  systemSectionEdits?: Record<SectionKey, SystemSectionEdit>;
   /** Reorder sections by key. Optional. */
-  sectionsOrder?: string[];
+  sectionsOrder?: SectionKey[];
 }
 
 /**
@@ -184,11 +325,11 @@ export interface TabEdits {
   /** New tabs to add to this layout. Each must include a `type` discriminator. Optional. */
   newTabs?: PageLayoutTab[];
   /** Edits to existing system tabs, keyed by tab key. Optional. */
-  systemTabEdits?: Record<string, SystemTabEdit>;
+  systemTabEdits?: Record<TabKey, SystemTabEdit>;
   /** Ordered list of tab `key` values (new + system). Optional. */
-  tabsOrder?: string[];
+  tabsOrder?: TabKey[];
   /** Tab strip orientation. Optional. */
-  newTabLayout?: 'vertical' | 'horizontal';
+  newTabLayout?: TabLayout;
 }
 
 // ---------------------------------------------------------------------------
@@ -205,7 +346,7 @@ export interface VisibilityCondition {
   /** RQL formula that controls visibility. Required. */
   rqlFormula: string;
   /** Layered conditions tree (AST). Required. */
-  layeredConditionsTree: Record<string, any>;
+  layeredConditionsTree: JsonObject;
 }
 
 /**
@@ -215,9 +356,9 @@ export interface VisibilityCondition {
  */
 export interface VisibilityConditions {
   /** Per-section visibility conditions, keyed by section key. Optional. */
-  sections?: Record<string, VisibilityCondition>;
+  sections?: Record<SectionKey, VisibilityCondition>;
   /** Per-tab visibility conditions, keyed by tab key. Optional. */
-  tabs?: Record<string, VisibilityCondition>;
+  tabs?: Record<TabKey, VisibilityCondition>;
 }
 
 // ---------------------------------------------------------------------------
@@ -241,13 +382,13 @@ export interface AddCustomPageLayoutFieldOptions extends AddPageLayoutFieldOptio
    * across the layout.
    */
   tabKey?: string;
-  /** Field section to add the field to. Required for custom layout sections. */
-  section: CustomObjectFieldSection;
-  /** Raw section keys are only accepted for built-in system sections. */
-  sectionKey?: never;
+  /** Field-section metadata used to find typed custom layout sections and assign field metadata. */
+  section?: CustomObjectFieldSection;
+  /** Layout section key. Optional escape hatch for ambiguous custom sections. */
+  sectionKey?: SectionKey;
   /** Deprecated. Use `section`. */
   fieldSection?: never;
-  /** Custom layout sections are selected by `section`; `sectionKey` is only for system sections. */
+  /** Custom layout sections are selected by `section`; `sectionKey` can disambiguate. */
   systemSection?: false;
 }
 
@@ -291,9 +432,9 @@ export interface RemoveCustomPageLayoutFieldOptions extends RemovePageLayoutFiel
   tabKey?: string;
   /** Limit removal to one field section. Optional. */
   section?: CustomObjectFieldSection;
-  /** Raw section keys are only accepted for built-in system sections. */
-  sectionKey?: never;
-  /** Custom layout sections are selected by `section`; `sectionKey` is only for system sections. */
+  /** Limit removal to one layout section key. Optional. */
+  sectionKey?: SectionKey;
+  /** Custom layout sections are selected by `section`; `sectionKey` can disambiguate. */
   systemSection?: false;
 }
 
@@ -339,7 +480,7 @@ export interface RemovePageLayoutSectionOptions {
    * more than once throws. Optional. @default true
    */
   removeAll?: boolean;
-  /** Custom layout sections are selected by `CustomObjectFieldSection`; raw keys are only for system sections. */
+  /** Custom layout sections are selected by layout section key or `CustomObjectFieldSection`. */
   systemSection?: false;
 }
 
@@ -451,11 +592,13 @@ export interface CustomObjectPageLayoutLoadFromExistingOptions extends ExistingM
   customObjectApiName?: string;
 }
 
+type ResolveFieldSectionId = (fieldRqlName: string) => string | undefined;
+
 interface SerializedSectionField extends SectionFieldOptions {
   fieldRqlName: string;
 }
 
-interface SerializedFieldsSection {
+interface SerializedFieldsSection extends PageLayoutSectionOptions {
   key?: string;
   type: 'fields_section';
   name: string;
@@ -463,11 +606,19 @@ interface SerializedFieldsSection {
   layout?: SectionFieldsLayout;
 }
 
+type SerializedPageLayoutSection =
+  | SerializedFieldsSection
+  | RelatedObjectSection
+  | RelatedFieldSection
+  | CustomSection
+  | ReportsSection
+  | CanvasSection;
+
 interface SerializedTabWithSections {
   type: 'tab_with_sections';
   key: string;
   name: string;
-  sections: SerializedFieldsSection[];
+  sections: SerializedPageLayoutSection[];
 }
 
 type SerializedPageLayoutTab = SerializedTabWithSections | CustomTab;
@@ -477,7 +628,7 @@ interface SerializedSystemSectionEdit extends Omit<SystemSectionEdit, 'newFields
 }
 
 interface SerializedSystemTabEdit extends Omit<SystemTabEdit, 'newSections' | 'systemSectionEdits'> {
-  newSections?: SerializedFieldsSection[];
+  newSections?: SerializedPageLayoutSection[];
   systemSectionEdits?: Record<string, SerializedSystemSectionEdit>;
 }
 
@@ -502,46 +653,49 @@ function isField(value: unknown): value is Field {
   );
 }
 
-function isFieldRef(value: SectionField): value is SectionFieldRef {
+function isFieldRef(value: SectionFieldInput): value is SectionField {
   const candidate = value as { field?: unknown } | null;
   return candidate != null && typeof candidate === 'object' && isField(candidate.field);
 }
 
-const FIELD_SECTION_ID = Symbol('CustomObjectPageLayout.fieldSectionId');
+const LAYOUT_SECTION_KEY = Symbol('CustomObjectPageLayout.layoutSectionKey');
 
 function isCustomObjectFieldSection(value: unknown): value is CustomObjectFieldSection {
   return value instanceof CustomObjectFieldSection;
 }
 
-function attachFieldSectionId(section: SerializedFieldsSection, sectionId: string): SerializedFieldsSection {
-  if (section.key != null && section.key !== sectionId) {
-    throw new Error(
-      `CustomObjectPageLayout fields_section key "${section.key}" does not match field section "${sectionId}".`,
-    );
-  }
-  section.key = sectionId;
-  Object.defineProperty(section, FIELD_SECTION_ID, {
-    value: sectionId,
+function explicitLayoutSectionKey(section: { key?: string }): string | undefined {
+  const record = section as unknown as Record<string, unknown>;
+  const key = section.key ?? record['layout_section_key'] ?? record['layoutSectionKey'];
+  return typeof key === 'string' ? key : undefined;
+}
+
+function attachLayoutSectionKey(
+  section: SerializedFieldsSection,
+  sectionKey: string,
+): SerializedFieldsSection {
+  if (explicitLayoutSectionKey(section) == null) section.key = sectionKey;
+  Object.defineProperty(section, LAYOUT_SECTION_KEY, {
+    value: sectionKey,
     enumerable: false,
     configurable: true,
   });
   return section;
 }
 
-function layoutSectionKey(section: SerializedFieldsSection): string | undefined {
+function layoutSectionKey(section: { key?: string }): string | undefined {
   return (
-    section.key ??
-    (section as unknown as Record<typeof FIELD_SECTION_ID, string | undefined>)[FIELD_SECTION_ID]
+    explicitLayoutSectionKey(section) ??
+    (section as unknown as Record<typeof LAYOUT_SECTION_KEY, string | undefined>)[LAYOUT_SECTION_KEY]
   );
 }
 
-function layoutSectionMatches(section: SerializedFieldsSection, sectionKey: string): boolean {
+function layoutSectionMatches(section: { key?: string }, sectionKey: string): boolean {
   return layoutSectionKey(section) === sectionKey;
 }
 
-function inputFieldsSectionHasKey(input: PageLayoutSection): boolean {
-  const record = input as unknown as Record<string, unknown>;
-  return Object.prototype.hasOwnProperty.call(record, 'key') && record['key'] != null;
+function isSerializedFieldsSection(section: SerializedPageLayoutSection): section is SerializedFieldsSection {
+  return section.type === 'fields_section';
 }
 
 function assertSameObject(customObject: CustomObject, field: Field, sectionKey: string): void {
@@ -585,15 +739,30 @@ function toSerializedSectionField(
   const normalized: SerializedSectionField = { fieldRqlName };
   if (options.hidden != null) normalized.hidden = options.hidden;
   if (options.editable != null) normalized.editable = options.editable;
+  if (options.readOnly != null) normalized.readOnly = options.readOnly;
+  if (options.defaultValue != null) normalized.defaultValue = options.defaultValue;
+  if (options.height != null) normalized.height = options.height;
+  if (options.canBeDeleted != null) normalized.canBeDeleted = options.canBeDeleted;
   if (options.movementOption != null) normalized.movementOption = options.movementOption;
   return normalized;
 }
 
+function copySectionOptions<T extends PageLayoutSectionOptions>(
+  target: T,
+  input: PageLayoutSectionOptions,
+): T {
+  if (input.canBeDeleted != null) target.canBeDeleted = input.canBeDeleted;
+  if (input.canBeRenamed != null) target.canBeRenamed = input.canBeRenamed;
+  if (input.movementOption != null) target.movementOption = input.movementOption;
+  if (input.hideName != null) target.hideName = input.hideName;
+  return target;
+}
+
 function normalizeSectionField(
   customObject: CustomObject,
   section: CustomObjectFieldSection | string,
   sectionKey: string,
-  entry: SectionField,
+  entry: SectionFieldInput,
 ): SerializedSectionField {
   if (isField(entry)) {
     assertSameObject(customObject, entry, sectionKey);
@@ -613,30 +782,37 @@ function normalizeSectionField(
   );
 }
 
-function normalizeFieldsSection(
-  customObject: CustomObject,
-  input: PageLayoutSection,
-): SerializedFieldsSection {
+function normalizeFieldsSection(customObject: CustomObject, input: FieldsSection): SerializedFieldsSection {
   assertSectionBelongsTo(customObject, input.section);
-  const sectionId = input.section.getSectionId();
-  if (inputFieldsSectionHasKey(input)) {
-    throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
-  }
+  const sectionKey = input.key ?? input.section.getSectionId();
   const name = input.name ?? input.section.getName();
-  const normalized: SerializedFieldsSection = {
-    name,
-    type: 'fields_section',
-    fields: input.fields.map((field) => normalizeSectionField(customObject, input.section, sectionId, field)),
-  };
+  const normalized = copySectionOptions<SerializedFieldsSection>(
+    {
+      name,
+      type: 'fields_section',
+      fields: input.fields.map((field) =>
+        normalizeSectionField(customObject, input.section, sectionKey, field),
+      ),
+    },
+    input,
+  );
   if (input.layout != null) normalized.layout = input.layout;
-  return attachFieldSectionId(normalized, sectionId);
+  return attachLayoutSectionKey(normalized, sectionKey);
+}
+
+function normalizeSection(
+  customObject: CustomObject,
+  section: PageLayoutSection,
+): SerializedPageLayoutSection {
+  if (section.type === 'fields_section') return normalizeFieldsSection(customObject, section);
+  return { ...section };
 }
 
 function normalizeTab(customObject: CustomObject, tab: PageLayoutTab): SerializedPageLayoutTab {
   if (tab.type === 'custom_tab') return tab;
   return {
     ...tab,
-    sections: tab.sections.map((section) => normalizeFieldsSection(customObject, section)),
+    sections: tab.sections.map((section) => normalizeSection(customObject, section)),
   };
 }
 
@@ -664,7 +840,7 @@ function normalizeSystemTabEdit(
   const { newSections: _newSections, systemSectionEdits: _systemSectionEdits, ...rest } = edit;
   const normalized: SerializedSystemTabEdit = { ...rest };
   if (edit.newSections != null) {
-    normalized.newSections = edit.newSections.map((section) => normalizeFieldsSection(customObject, section));
+    normalized.newSections = edit.newSections.map((section) => normalizeSection(customObject, section));
   }
   if (edit.systemSectionEdits != null) {
     const systemSectionEdits: Record<string, SerializedSystemSectionEdit> = {};
@@ -730,7 +906,7 @@ function assertKnownKeys(
   }
 }
 
-function normalizeHeaderEdits(headerEdits: HeaderEdits): HeaderEdits {
+function normalizeHeaderEdits(headerEdits: HeaderEdits): SerializedHeaderEdits {
   assertKnownKeys(
     headerEdits as unknown as Record<string, unknown>,
     HEADER_EDIT_KEYS,
@@ -756,6 +932,27 @@ function normalizeHeaderEdits(headerEdits: HeaderEdits): HeaderEdits {
     );
   }
 
+  if (headerEdits.newTitleField === '') {
+    throw new Error(
+      'CustomObjectPageLayout headerEdits.newTitleField cannot be empty. Use titleFieldDeleted.',
+    );
+  }
+  if (headerEdits.newDescriptionField === '') {
+    throw new Error(
+      'CustomObjectPageLayout headerEdits.newDescriptionField cannot be empty. Use descriptionFieldDeleted.',
+    );
+  }
+  if (headerEdits.newTitleField != null && headerEdits.titleFieldDeleted === true) {
+    throw new Error(
+      'CustomObjectPageLayout headerEdits cannot both set newTitleField and titleFieldDeleted.',
+    );
+  }
+  if (headerEdits.newDescriptionField != null && headerEdits.descriptionFieldDeleted === true) {
+    throw new Error(
+      'CustomObjectPageLayout headerEdits cannot both set newDescriptionField and descriptionFieldDeleted.',
+    );
+  }
+
   if (headerEdits.headerFieldsOrder == null) return headerEdits;
   return {
     ...headerEdits,
@@ -768,13 +965,13 @@ function addUniqueHeaderOrderField(order: string[], field: unknown): void {
   if (!order.includes(field)) order.push(field);
 }
 
-function normalizeHeaderFieldsOrder(headerEdits: HeaderEdits): string[] {
+function normalizeHeaderFieldsOrder(headerEdits: SerializedHeaderEdits): string[] {
   const customFieldRqlByKey = new Map(
     (headerEdits.newFields ?? []).map((field) => [field.key, field.rqlName]),
   );
   const systemFieldRqlByKey = new Map(
     Object.entries(headerEdits.systemFieldEdits ?? {})
-      .filter((entry): entry is [string, SystemHeaderFieldEdit & { newRqlField: string }] => {
+      .filter((entry): entry is [string, SerializedSystemHeaderFieldEdit & { newRqlField: string }] => {
         const [, edit] = entry;
         return typeof edit.newRqlField === 'string' && edit.newRqlField.length > 0;
       })
@@ -811,6 +1008,11 @@ interface MutableFieldContainer {
   label: string;
 }
 
+interface FieldSectionLayoutSection {
+  tabKey: string;
+  sectionKey: string;
+}
+
 function isTabWithSections(tab: SerializedPageLayoutTab): tab is SerializedTabWithSections {
   return tab.type === 'tab_with_sections';
 }
@@ -841,66 +1043,126 @@ function fieldRqlNameOf(entry: unknown): string | undefined {
   if (typeof entry === 'string') return entry;
   if (entry == null || typeof entry !== 'object') return undefined;
   const record = entry as Record<string, any>;
-  const fieldRqlName = record['fieldRqlName'] ?? record['field_rql_name'];
+  const fieldRqlName =
+    record['fieldRqlName'] ?? record['field_rql_name'] ?? record['apiName'] ?? record['api_name'];
   return typeof fieldRqlName === 'string' ? fieldRqlName : undefined;
 }
 
-function explicitFieldSectionId(entry: unknown): string | undefined {
-  if (entry == null || typeof entry !== 'object') return undefined;
-  const record = entry as Record<string, any>;
-  const fieldSectionId = record['fieldSection'] ?? record['field_section'];
-  return typeof fieldSectionId === 'string' ? fieldSectionId : undefined;
+function addFieldSectionLayoutSection(
+  index: Map<string, FieldSectionLayoutSection[]>,
+  fieldSectionId: string,
+  entry: FieldSectionLayoutSection,
+): void {
+  const entries = index.get(fieldSectionId) ?? [];
+  if (
+    !entries.some((existing) => existing.tabKey === entry.tabKey && existing.sectionKey === entry.sectionKey)
+  ) {
+    entries.push(entry);
+  }
+  index.set(fieldSectionId, entries);
 }
 
-function inferredSectionIdFromFields(
-  section: SerializedFieldsSection,
-  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
-): string | undefined {
-  const sectionIds = new Set<string>();
-  for (const field of section.fields ?? []) {
-    const explicitSectionId = explicitFieldSectionId(field);
-    if (explicitSectionId != null) {
-      sectionIds.add(explicitSectionId);
-      continue;
-    }
+function indexFieldsSectionInput(
+  index: Map<string, FieldSectionLayoutSection[]>,
+  tabKey: string,
+  section: FieldsSection,
+): void {
+  addFieldSectionLayoutSection(index, section.section.getSectionId(), {
+    tabKey,
+    sectionKey: section.key ?? section.section.getSectionId(),
+  });
+}
+
+function indexPageLayoutSectionInput(
+  index: Map<string, FieldSectionLayoutSection[]>,
+  tabKey: string,
+  section: PageLayoutSection,
+): void {
+  if (section.type === 'fields_section') indexFieldsSectionInput(index, tabKey, section);
+}
+
+function buildFieldSectionLayoutIndexFromProps(
+  tabEdits: TabEdits | undefined,
+): Map<string, FieldSectionLayoutSection[]> {
+  const index = new Map<string, FieldSectionLayoutSection[]>();
+  if (tabEdits == null) return index;
+
+  for (const tab of tabEdits.newTabs ?? []) {
+    if (tab.type !== 'tab_with_sections') continue;
+    for (const section of tab.sections) indexPageLayoutSectionInput(index, tab.key, section);
+  }
 
-    const fieldApiName = fieldRqlNameOf(field);
-    if (fieldApiName == null || resolveFieldSectionId == null) continue;
-    const resolvedSectionId = resolveFieldSectionId(fieldApiName);
-    if (resolvedSectionId != null) sectionIds.add(resolvedSectionId);
+  for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits ?? {})) {
+    for (const section of tabEdit.newSections ?? []) {
+      indexPageLayoutSectionInput(index, tabKey, section);
+    }
   }
-  return sectionIds.size === 1 ? [...sectionIds][0] : undefined;
+
+  return index;
 }
 
-function annotateLoadedFieldsSection(
+function indexLoadedFieldsSection(
+  index: Map<string, FieldSectionLayoutSection[]>,
+  tabKey: string,
   section: SerializedFieldsSection,
-  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
-): SerializedFieldsSection {
-  const explicitSectionId = layoutSectionKey(section);
-  const inferredSectionId = inferredSectionIdFromFields(section, resolveFieldSectionId);
-  if (explicitSectionId != null && inferredSectionId != null && explicitSectionId !== inferredSectionId) {
-    throw new Error(
-      `CustomObjectPageLayout fields_section key "${explicitSectionId}" does not match ` +
-        `field section "${inferredSectionId}".`,
-    );
+  resolveFieldSectionId: ResolveFieldSectionId | undefined,
+): void {
+  const sectionKey = layoutSectionKey(section);
+  if (sectionKey == null || resolveFieldSectionId == null) return;
+
+  for (const field of section.fields ?? []) {
+    const fieldRqlName = fieldRqlNameOf(field);
+    if (fieldRqlName == null) continue;
+    const fieldSectionId = resolveFieldSectionId(fieldRqlName);
+    if (fieldSectionId != null) {
+      addFieldSectionLayoutSection(index, fieldSectionId, { tabKey, sectionKey });
+    }
   }
-  const sectionId = explicitSectionId ?? inferredSectionId;
-  return sectionId == null ? section : attachFieldSectionId(section, sectionId);
 }
 
-function annotateLoadedTabEdits(
+function buildFieldSectionLayoutIndexFromLoadedTabEdits(
   tabEdits: SerializedTabEdits,
-  resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
-): SerializedTabEdits {
+  resolveFieldSectionId: ResolveFieldSectionId | undefined,
+): Map<string, FieldSectionLayoutSection[]> {
+  const index = new Map<string, FieldSectionLayoutSection[]>();
+
+  for (const tab of tabEdits.newTabs ?? []) {
+    if (!isTabWithSections(tab)) continue;
+    for (const section of tab.sections) {
+      if (isSerializedFieldsSection(section)) {
+        indexLoadedFieldsSection(index, tab.key, section, resolveFieldSectionId);
+      }
+    }
+  }
+
+  for (const [tabKey, tabEdit] of Object.entries(tabEdits.systemTabEdits ?? {})) {
+    for (const section of tabEdit.newSections ?? []) {
+      if (isSerializedFieldsSection(section)) {
+        indexLoadedFieldsSection(index, tabKey, section, resolveFieldSectionId);
+      }
+    }
+  }
+
+  return index;
+}
+
+function annotateLoadedFieldsSection(section: SerializedFieldsSection): SerializedFieldsSection {
+  const sectionKey = layoutSectionKey(section);
+  return sectionKey == null ? section : attachLayoutSectionKey(section, sectionKey);
+}
+
+function annotateLoadedTabEdits(tabEdits: SerializedTabEdits): SerializedTabEdits {
   for (const tab of tabEdits.newTabs ?? []) {
     if (!isTabWithSections(tab)) continue;
-    tab.sections = tab.sections.map((section) => annotateLoadedFieldsSection(section, resolveFieldSectionId));
+    tab.sections = tab.sections.map((section) =>
+      isSerializedFieldsSection(section) ? annotateLoadedFieldsSection(section) : section,
+    );
   }
 
   for (const tabEdit of Object.values(tabEdits.systemTabEdits ?? {})) {
     if (tabEdit.newSections != null) {
       tabEdit.newSections = tabEdit.newSections.map((section) =>
-        annotateLoadedFieldsSection(section, resolveFieldSectionId),
+        isSerializedFieldsSection(section) ? annotateLoadedFieldsSection(section) : section,
       );
     }
   }
@@ -1020,9 +1282,10 @@ export class CustomObjectPageLayout {
   private readonly _customObjectApiName: string;
   private readonly _name: string;
   private readonly _tabEdits: SerializedTabEdits;
-  private readonly _headerEdits: HeaderEdits;
+  private readonly _headerEdits: SerializedHeaderEdits;
   private readonly _visibilityConditions: VisibilityConditions;
   private readonly _blueprintKey: string | undefined;
+  private readonly _fieldSectionLayoutSections: Map<string, FieldSectionLayoutSection[]>;
 
   /**
    * @param customObject - The custom object this layout belongs to.
@@ -1037,6 +1300,7 @@ export class CustomObjectPageLayout {
     this._customObjectApiName = customObject.getApiName();
     this._name = props.name;
     this._tabEdits = normalizeTabEdits(customObject, props.tabEdits ?? {});
+    this._fieldSectionLayoutSections = buildFieldSectionLayoutIndexFromProps(props.tabEdits);
     this._headerEdits = normalizeHeaderEdits(props.headerEdits ?? {});
     this._visibilityConditions = props.visibilityConditions ?? {};
     this._blueprintKey = props.blueprintKey;
@@ -1061,9 +1325,10 @@ export class CustomObjectPageLayout {
   static _fromExistingComponent(
     customObject: CustomObject,
     component: Record<string, any>,
-    resolveFieldSectionId?: (fieldApiName: string) => string | undefined,
+    resolveFieldSectionId?: ResolveFieldSectionId,
   ): CustomObjectPageLayout {
     const layout = Object.create(CustomObjectPageLayout.prototype) as CustomObjectPageLayout;
+    const tabEdits = annotateLoadedTabEdits(cloneJson(component['tab_edits'] ?? {}));
     Object.assign(layout as Record<string, any>, {
       _layoutId: requireStringComponentField(component, 'layout_id', CustomObjectPageLayout.componentType),
       _apiName: requireStringComponentField(component, 'api_name', CustomObjectPageLayout.componentType),
@@ -1073,10 +1338,14 @@ export class CustomObjectPageLayout {
         CustomObjectPageLayout.componentType,
       ),
       _name: requireStringComponentField(component, 'name', CustomObjectPageLayout.componentType),
-      _tabEdits: annotateLoadedTabEdits(cloneJson(component['tab_edits'] ?? {}), resolveFieldSectionId),
+      _tabEdits: tabEdits,
       _headerEdits: cloneJson(component['header_edits'] ?? {}),
       _visibilityConditions: cloneJson(component['visibility_conditions'] ?? {}),
       _blueprintKey: component['blueprint_key'],
+      _fieldSectionLayoutSections: buildFieldSectionLayoutIndexFromLoadedTabEdits(
+        tabEdits,
+        resolveFieldSectionId,
+      ),
     });
     customObject._register(layout);
     return layout;
@@ -1117,8 +1386,8 @@ export class CustomObjectPageLayout {
    * Adds multiple fields to an existing layout section.
    *
    * Fields are inserted in the order provided. For custom layout sections,
-   * pass `options.section` so TypeScript and runtime validation agree on the
-   * target `CUSTOM_OBJECT_FIELD_SECTION`.
+   * pass `section` to choose the typed field section. Use `sectionKey` only
+   * when a field section maps to multiple layout sections.
    */
   addFields(fields: Field[], options: AddPageLayoutFieldsOptions): this {
     if (fields.length === 0) return this;
@@ -1141,25 +1410,25 @@ export class CustomObjectPageLayout {
           return this.ensureSystemSectionFieldContainer(options.tabKey, options.sectionKey);
         })()
       : (() => {
-          assertOptionAbsent(
-            options,
-            'sectionKey',
-            'CustomObjectPageLayout addField sectionKey is only supported with systemSection: true. ' +
-              'Pass section: CustomObjectFieldSection for custom layout sections.',
-          );
           assertOptionAbsent(
             options,
             'fieldSection',
             'CustomObjectPageLayout addField fieldSection is no longer supported. ' +
               'Pass section: CustomObjectFieldSection instead.',
           );
-          const section = requireFieldSectionOption(
-            options.section,
-            'CustomObjectPageLayout addField section',
-          );
-          this.assertFieldSectionBelongsToLayout(section);
-          fieldSectionForMutation = section;
-          return this.requireOneFieldContainer(options.tabKey, section.getSectionId(), section);
+          const section =
+            options.section == null ?
+              undefined
+            : requireFieldSectionOption(options.section, 'CustomObjectPageLayout addField section');
+          if (section != null) {
+            this.assertFieldSectionBelongsToLayout(section);
+            fieldSectionForMutation = section;
+          }
+          const sectionKey =
+            options.sectionKey ??
+            (section == null ? undefined : this.layoutSectionKeyForFieldSection(options.tabKey, section)) ??
+            section?.getSectionId();
+          return this.requireOneFieldContainer(options.tabKey, sectionKey, section);
         })();
     const entries = fields.map((field) =>
       this.serializeFieldForMutation(
@@ -1208,19 +1477,15 @@ export class CustomObjectPageLayout {
       );
       sectionKey = options.sectionKey;
     } else {
-      assertOptionAbsent(
-        options,
-        'sectionKey',
-        'CustomObjectPageLayout removeField sectionKey is only supported with systemSection: true. ' +
-          'Pass section: CustomObjectFieldSection for custom layout sections.',
-      );
+      sectionKey = options.sectionKey;
       if (options.section != null) {
         const section = requireFieldSectionOption(
           options.section,
           'CustomObjectPageLayout removeField section',
         );
         this.assertFieldSectionBelongsToLayout(section);
-        sectionKey = section.getSectionId();
+        sectionKey ??= this.layoutSectionKeyForFieldSection(options.tabKey, section);
+        sectionKey ??= section.getSectionId();
       }
     }
 
@@ -1280,7 +1545,7 @@ export class CustomObjectPageLayout {
     const normalized = this.normalizeSectionForMutation(section);
     if (options.systemTab === true) {
       const tabEdit = this.ensureSystemTabEdit(options.tabKey);
-      const sections = ensureArrayProperty<SerializedFieldsSection>(
+      const sections = ensureArrayProperty<SerializedPageLayoutSection>(
         tabEdit as Record<string, any>,
         'newSections',
         `systemTabEdits.${options.tabKey}.newSections`,
@@ -1294,6 +1559,9 @@ export class CustomObjectPageLayout {
       const sectionsOrder = this.ensureSystemSectionsOrder(tabEdit);
       insertAt(sections, normalized, options.position);
       insertUniqueAt(sectionsOrder, layoutSectionKey(normalized), options.position);
+      if (section.type === 'fields_section') {
+        this.rememberFieldSectionLayoutSection(section.section, options.tabKey, layoutSectionKey(normalized));
+      }
       return this;
     }
 
@@ -1311,6 +1579,9 @@ export class CustomObjectPageLayout {
       options.allowDuplicate,
     );
     insertAt(tab.sections, normalized, options.position);
+    if (section.type === 'fields_section') {
+      this.rememberFieldSectionLayoutSection(section.section, tab.key, layoutSectionKey(normalized));
+    }
     return this;
   }
 
@@ -1321,6 +1592,7 @@ export class CustomObjectPageLayout {
    * `systemSectionEdits[sectionKey].deleted`.
    */
   removeSection(section: CustomObjectFieldSection, options?: RemovePageLayoutSectionOptions): this;
+  removeSection(sectionKey: string, options?: RemovePageLayoutSectionOptions): this;
   removeSection(sectionKey: string, options: RemoveSystemPageLayoutSectionOptions): this;
   removeSection(
     sectionOrKey: CustomObjectFieldSection | string,
@@ -1342,11 +1614,16 @@ export class CustomObjectPageLayout {
       return this;
     }
 
-    const section = requireFieldSectionOption(sectionOrKey, 'CustomObjectPageLayout removeSection section');
-    this.assertFieldSectionBelongsToLayout(section);
-    const sectionKey = section.getSectionId();
+    let sectionKey: string;
+    if (typeof sectionOrKey === 'string') {
+      sectionKey = sectionOrKey;
+    } else {
+      const section = requireFieldSectionOption(sectionOrKey, 'CustomObjectPageLayout removeSection section');
+      this.assertFieldSectionBelongsToLayout(section);
+      sectionKey = this.layoutSectionKeyForFieldSection(options.tabKey, section) ?? section.getSectionId();
+    }
     const matches: Array<{
-      sections: SerializedFieldsSection[];
+      sections: SerializedPageLayoutSection[];
       section: SerializedFieldsSection;
       index: number;
       tabEdit?: SerializedSystemTabEdit;
@@ -1356,14 +1633,14 @@ export class CustomObjectPageLayout {
       if (!isTabWithSections(tab)) continue;
       if (options.tabKey != null && tab.key !== options.tabKey) continue;
       tab.sections.forEach((section, index) => {
-        if (layoutSectionMatches(section, sectionKey))
+        if (isSerializedFieldsSection(section) && layoutSectionMatches(section, sectionKey))
           matches.push({ sections: tab.sections, section, index, tabKey: tab.key });
       });
     }
     for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
       if (options.tabKey != null && tabKey !== options.tabKey) continue;
       (tabEdit.newSections ?? []).forEach((section, index) => {
-        if (layoutSectionMatches(section, sectionKey))
+        if (isSerializedFieldsSection(section) && layoutSectionMatches(section, sectionKey))
           matches.push({ sections: tabEdit.newSections!, section, index, tabEdit, tabKey });
       });
     }
@@ -1380,7 +1657,7 @@ export class CustomObjectPageLayout {
     }
 
     const removals = removeAll ? matches : matches.slice(0, 1);
-    const byArray = new Map<SerializedFieldsSection[], number[]>();
+    const byArray = new Map<SerializedPageLayoutSection[], number[]>();
     for (const match of removals) {
       const indexes = byArray.get(match.sections) ?? [];
       indexes.push(match.index);
@@ -1404,6 +1681,10 @@ export class CustomObjectPageLayout {
     const tabsOrder = this.ensureTabsOrder();
     insertAt(newTabs, normalized, options.position);
     insertUniqueAt(tabsOrder, normalized.key, options.position);
+    if (tab.type === 'tab_with_sections') {
+      for (const section of tab.sections)
+        indexPageLayoutSectionInput(this._fieldSectionLayoutSections, tab.key, section);
+    }
     return this;
   }
 
@@ -1474,11 +1755,13 @@ export class CustomObjectPageLayout {
   }
 
   /** Sets the record title field in `header_edits`. */
-  setTitleField(field: Field | string | null): this {
+  setTitleField(field: Field): this;
+  setTitleField(fieldApiName: FieldRqlName): this;
+  setTitleField(field: Field | FieldRqlName): this {
     const previousTitleField = this._headerEdits.newTitleField;
     const nextTitleField = this.headerFieldApiName(field);
     this._headerEdits.newTitleField = nextTitleField;
-    if (field != null) this._headerEdits.titleFieldDeleted = false;
+    this._headerEdits.titleFieldDeleted = false;
     insertUniqueAt(this.ensureHeaderFieldsOrder(), nextTitleField, 'end');
     this.removeHeaderOrderFieldIfUnused(previousTitleField);
     return this;
@@ -1494,11 +1777,13 @@ export class CustomObjectPageLayout {
   }
 
   /** Sets the record description field in `header_edits`. */
-  setDescriptionField(field: Field | string | null): this {
+  setDescriptionField(field: Field): this;
+  setDescriptionField(fieldApiName: FieldRqlName): this;
+  setDescriptionField(field: Field | FieldRqlName): this {
     const previousDescriptionField = this._headerEdits.newDescriptionField;
     const nextDescriptionField = this.headerFieldApiName(field);
     this._headerEdits.newDescriptionField = nextDescriptionField;
-    if (field != null) this._headerEdits.descriptionFieldDeleted = false;
+    this._headerEdits.descriptionFieldDeleted = false;
     insertUniqueAt(this.ensureHeaderFieldsOrder(), nextDescriptionField, 'end');
     this.removeHeaderOrderFieldIfUnused(previousDescriptionField);
     return this;
@@ -1571,7 +1856,7 @@ export class CustomObjectPageLayout {
   private normalizeSectionFieldForMutation(
     section: CustomObjectFieldSection | string,
     sectionKey: string,
-    entry: SectionField,
+    entry: SectionFieldInput,
   ): SerializedSectionField {
     if (isField(entry)) {
       this.assertFieldBelongsToLayout(entry);
@@ -1591,23 +1876,25 @@ export class CustomObjectPageLayout {
     );
   }
 
-  private normalizeSectionForMutation(input: PageLayoutSection): SerializedFieldsSection {
+  private normalizeSectionForMutation(input: PageLayoutSection): SerializedPageLayoutSection {
+    if (input.type !== 'fields_section') return { ...input };
+
     this.assertFieldSectionBelongsToLayout(input.section);
 
-    const sectionId = input.section.getSectionId();
-    if (inputFieldsSectionHasKey(input)) {
-      throw new Error('CustomObjectPageLayout fields_section key is not supported. Omit key.');
-    }
+    const sectionKey = input.key ?? input.section.getSectionId();
     const name = input.name ?? input.section.getName();
-    const normalized: SerializedFieldsSection = {
-      name,
-      type: 'fields_section',
-      fields: input.fields.map((field) =>
-        this.normalizeSectionFieldForMutation(input.section, sectionId, field),
-      ),
-    };
+    const normalized = copySectionOptions<SerializedFieldsSection>(
+      {
+        name,
+        type: 'fields_section',
+        fields: input.fields.map((field) =>
+          this.normalizeSectionFieldForMutation(input.section, sectionKey, field),
+        ),
+      },
+      input,
+    );
     if (input.layout != null) normalized.layout = input.layout;
-    return attachFieldSectionId(normalized, sectionId);
+    return attachLayoutSectionKey(normalized, sectionKey);
   }
 
   private normalizeTabForMutation(tab: PageLayoutTab): SerializedPageLayoutTab {
@@ -1670,6 +1957,35 @@ export class CustomObjectPageLayout {
     }
   }
 
+  private rememberFieldSectionLayoutSection(
+    section: CustomObjectFieldSection,
+    tabKey: string,
+    sectionKey: string | undefined,
+  ): void {
+    if (sectionKey == null) return;
+    addFieldSectionLayoutSection(this._fieldSectionLayoutSections, section.getSectionId(), {
+      tabKey,
+      sectionKey,
+    });
+  }
+
+  private layoutSectionKeyForFieldSection(
+    tabKey: string | undefined,
+    section: CustomObjectFieldSection,
+  ): string | undefined {
+    const entries = this._fieldSectionLayoutSections.get(section.getSectionId()) ?? [];
+    const matches = tabKey == null ? entries : entries.filter((entry) => entry.tabKey === tabKey);
+    const sectionKeys = [...new Set(matches.map((entry) => entry.sectionKey))];
+    if (sectionKeys.length === 0) return undefined;
+    if (sectionKeys.length === 1) return sectionKeys[0];
+
+    const scope = tabKey == null ? '' : ` in tab "${tabKey}"`;
+    throw new Error(
+      `CustomObjectPageLayout field section "${section.getSectionId()}" maps to multiple layout sections${scope}: ` +
+        `${sectionKeys.join(', ')}. Pass sectionKey to choose one.`,
+    );
+  }
+
   private requireOneFieldContainer(
     tabKey: string | undefined,
     sectionKey: string | undefined,
@@ -1699,8 +2015,8 @@ export class CustomObjectPageLayout {
           const container = unkeyedContainers[0] as MutableFieldContainer & {
             section: SerializedFieldsSection;
           };
-          attachFieldSectionId(container.section, fallbackFieldSection.getSectionId());
-          container.sectionKey = fallbackFieldSection.getSectionId();
+          attachLayoutSectionKey(container.section, sectionKey);
+          container.sectionKey = sectionKey;
           container.label = `${container.tabKey}.${container.sectionKey}`;
           return container;
         }
@@ -1738,6 +2054,7 @@ export class CustomObjectPageLayout {
         if (!isTabWithSections(tab)) continue;
         if (filter.tabKey != null && tab.key !== filter.tabKey) continue;
         for (const [index, section] of tab.sections.entries()) {
+          if (!isSerializedFieldsSection(section)) continue;
           const sectionKey = layoutSectionKey(section);
           if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey)) continue;
           const label = sectionKey == null ? `${tab.key}.sections[${index}]` : `${tab.key}.${sectionKey}`;
@@ -1758,6 +2075,7 @@ export class CustomObjectPageLayout {
       for (const [tabKey, tabEdit] of Object.entries(this._tabEdits.systemTabEdits ?? {})) {
         if (filter.tabKey != null && tabKey !== filter.tabKey) continue;
         for (const [index, section] of (tabEdit.newSections ?? []).entries()) {
+          if (!isSerializedFieldsSection(section)) continue;
           const sectionKey = layoutSectionKey(section);
           if (filter.sectionKey != null && !layoutSectionMatches(section, filter.sectionKey)) continue;
           const label = sectionKey == null ? `${tabKey}.newSections[${index}]` : `${tabKey}.${sectionKey}`;
@@ -1870,7 +2188,7 @@ export class CustomObjectPageLayout {
   }
 
   private assertSectionKeyAvailable(
-    sections: SerializedFieldsSection[],
+    sections: SerializedPageLayoutSection[],
     sectionKey: string | undefined,
     tabKey: string,
     allowDuplicate: boolean | undefined,
@@ -1903,8 +2221,7 @@ export class CustomObjectPageLayout {
     return normalized;
   }
 
-  private headerFieldApiName(field: Field | string | null): string | null {
-    if (field == null) return null;
+  private headerFieldApiName(field: Field | FieldRqlName): FieldRqlName {
     if (typeof field === 'string') return field;
     this.assertFieldBelongsToLayout(field);
     return field.getApiName();