feat: add ALTER PAGE SET Layout to switch page layout (#54)

Adds SET Layout = Module.LayoutName [MAP (Old AS New)] to ALTER PAGE.
Rewrites FormCall.Form and Parameter strings without rebuilding the
widget tree. Auto-maps placeholders by name; explicit MAP clause for
layouts with different placeholder names. Not supported for snippets.

Full pipeline: grammar, AST, visitor, executor, plus docs (quick
reference, language guide, reference page, examples, skills, CLAUDE.md)
and doctype-test examples.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ako

.claude/skills/mendix/alter-page.md

@@ -64,6 +64,7 @@ SET Title = 'New Page Title'
 | `Visible` | Any widget | String or Boolean | `SET Visible = false ON txtHidden` |
 | `Name` | Any widget | String | `SET Name = 'newName' ON oldName` |
 | `Title` | Page-level only | String | `SET Title = 'Edit Customer'` |
+| `Layout` | Page-level only | Qualified name | `SET Layout = Atlas_Core.Atlas_Default` |
 | `'quotedProp'` | Pluggable widgets | String, Boolean, Number | `SET 'showLabel' = false ON cbStatus` |
 
 **Pluggable widget properties** use quoted names to set values in the widget's `Object.Properties[]`. Boolean values are stored as `"yes"`/`"no"` in BSON.
@@ -139,6 +140,20 @@ DROP Variables $showStockColumn
 
 Removes a page variable by name.
 
+### SET Layout - Change Page Layout
+
+```sql
+-- Auto-map placeholders by name (most common case)
+SET Layout = Atlas_Core.Atlas_Default
+
+-- Explicit mapping when placeholder names differ
+SET Layout = Atlas_Core.Atlas_SideBar MAP (Main AS Content, Extra AS Sidebar)
+```
+
+Changes the page's layout without rebuilding the widget tree. Only rewrites the `FormCall.Form` and `FormCall.Arguments[].Parameter` BSON fields — all widget content is preserved. Not supported for snippets.
+
+When placeholders have the same names in both layouts (e.g., both have `Main`), auto-mapping works. Use `MAP` when placeholder names differ between the old and new layout.
+
 ## Examples
 
 ### Change button text and style

CLAUDE.md

@@ -345,7 +345,7 @@ Regenerate after modifying `MDLLexer.g4` or `MDLParser.g4`: `make grammar`. See
 **Read the relevant skill files FIRST before writing any MDL, seeding data, or doing database/import work:**
 - `.claude/skills/write-microflows.md` - Microflow syntax, common mistakes, validation checklist
 - `.claude/skills/create-page.md` - Page/widget syntax reference
-- `.claude/skills/alter-page.md` - ALTER PAGE/SNIPPET in-place modifications (SET, INSERT, DROP, REPLACE)
+- `.claude/skills/alter-page.md` - ALTER PAGE/SNIPPET in-place modifications (SET, INSERT, DROP, REPLACE, SET Layout)
 - `.claude/skills/overview-pages.md` - CRUD page patterns
 - `.claude/skills/master-detail-pages.md` - Master-detail page patterns
 - `.claude/skills/generate-domain-model.md` - Entity/Association syntax

docs-site/src/examples/alter-page.md

@@ -63,6 +63,25 @@ ALTER PAGE CRM.ProductOverview {
 };
 ```
 
+## Switch Page Layout
+
+Change a page's layout without losing any widgets:
+
+```sql
+-- Switch from TopBar to Default layout (auto-maps by placeholder name)
+ALTER PAGE CRM.Customer_Edit {
+  SET Layout = Atlas_Core.Atlas_Default
+};
+```
+
+When the new layout has different placeholder names, use `MAP`:
+
+```sql
+ALTER PAGE CRM.Customer_Edit {
+  SET Layout = Atlas_Core.Atlas_SideBar MAP (Main AS Content, Extra AS Sidebar)
+};
+```
+
 ## Works on Snippets Too
 
 ```sql

docs-site/src/language/alter-page.md

@@ -67,6 +67,26 @@ ALTER PAGE Module.EditPage {
 };
 ```
 
+### SET Layout -- Change Page Layout
+
+Switch a page's layout without rebuilding the widget tree. All widget content is preserved -- only the layout reference and placeholder mappings are updated.
+
+```sql
+-- Auto-map placeholders by name (common case)
+ALTER PAGE Module.EditPage {
+  SET Layout = Atlas_Core.Atlas_Default
+};
+
+-- Explicit mapping when placeholder names differ
+ALTER PAGE Module.EditPage {
+  SET Layout = Atlas_Core.Atlas_SideBar MAP (Main AS Content, Extra AS Sidebar)
+};
+```
+
+When both the old and new layouts share the same placeholder names (e.g., both have `Main`), no `MAP` clause is needed -- placeholders are matched automatically. Use `MAP` when the new layout has different placeholder names.
+
+Not supported for snippets (snippets don't have layouts).
+
 ### INSERT -- Add Widgets
 
 Insert new widgets before or after an existing widget:

docs-site/src/reference/page/alter-page.md

@@ -40,6 +40,12 @@ ADD Variables $name : type = 'expression';
 
 -- Drop a page variable
 DROP Variables $name;
+
+-- Change page layout (auto-map placeholders by name)
+SET Layout = module.LayoutName;
+
+-- Change layout with explicit placeholder mapping
+SET Layout = module.LayoutName MAP (OldPlaceholder AS NewPlaceholder);
 ```
 
 ## Description
@@ -70,6 +76,12 @@ Removes one or more widgets by name. The widget and all its children are removed
 
 Replaces a widget (and its entire subtree) with one or more new widgets.
 
+### SET Layout
+
+Changes the page's layout without rebuilding the widget tree. Placeholder names are auto-mapped by default. If the new layout has different placeholder names, use `MAP` to specify the mapping.
+
+Not supported for snippets (snippets don't have layouts).
+
 ### ADD Variables / DROP Variables
 
 Adds or removes page-level variables. Page variables are typed values with default expressions, available for conditional visibility and dynamic behavior.
@@ -148,6 +160,22 @@ ALTER PAGE Sales.Order_Edit {
 };
 ```
 
+Change page layout (preserves all widgets):
+
+```sql
+ALTER PAGE Sales.Order_Edit {
+    SET Layout = Atlas_Core.Atlas_Default;
+};
+```
+
+Change layout with explicit placeholder mapping:
+
+```sql
+ALTER PAGE Sales.Order_Edit {
+    SET Layout = Atlas_Core.Atlas_SideBar MAP (Main AS Content, Extra AS Sidebar);
+};
+```
+
 Modify a snippet:
 
 ```sql

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -445,8 +445,10 @@ Modify an existing page or snippet's widget tree in-place without full `CREATE O
 | Pluggable prop | `SET 'showLabel' = false ON cbStatus` | Quoted name for pluggable widgets |
 | Add variable | `ADD Variables $name: Type = 'expr'` | Add a page variable |
 | Drop variable | `DROP Variables $name` | Remove a page variable |
+| Set layout | `SET Layout = Module.LayoutName` | Change page layout, auto-maps placeholders |
+| Set layout + map | `SET Layout = Module.Layout MAP (Old AS New)` | Explicit placeholder mapping |
 
-**Supported SET properties:** Caption, Label, ButtonStyle, Class, Style, Editable, Visible, Name, Title (page-level), and quoted pluggable widget properties.
+**Supported SET properties:** Caption, Label, ButtonStyle, Class, Style, Editable, Visible, Name, Title (page-level), Layout (page-level), and quoted pluggable widget properties.
 
 **Example:**
 ```sql

mdl-examples/doctype-tests/03-page-examples.mdl

@@ -2238,6 +2238,26 @@ ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
   DROP Variables $showPriceColumn;
 };
 
+-- MARK: ALTER PAGE SET Layout
+
+-- =============================================================================
+-- ALTER PAGE - SET Layout (change page layout without rebuilding widgets)
+-- =============================================================================
+
+/**
+ * Level 8.1: Change page layout (auto-map placeholders)
+ */
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  SET Layout = Atlas_Core.Atlas_Default;
+};
+
+/**
+ * Level 8.2: Change layout back (auto-map)
+ */
+ALTER PAGE PgTest.P033b_DataGrid_ColumnProperties {
+  SET Layout = Atlas_Core.Atlas_TopBar;
+};
+
 -- MARK: Move Examples
 
 -- =============================================================================

mdl/ast/ast_alter_page.go

@@ -66,3 +66,17 @@ type DropVariableOp struct {
 }
 
 func (s *DropVariableOp) isAlterPageOperation() {}
+
+// SetLayoutOp represents: SET Layout = Module.LayoutName [MAP (Old -> New, ...)]
+type SetLayoutOp struct {
+	NewLayout QualifiedName        // New layout qualified name
+	Mappings  map[string]string    // Old placeholder -> New placeholder (nil = auto-map)
+}
+
+func (s *SetLayoutOp) isAlterPageOperation() {}
+
+// LayoutMapping represents a single placeholder mapping: Old -> New
+type LayoutMapping struct {
+	From string
+	To   string
+}

mdl/executor/cmd_alter_page.go

@@ -97,6 +97,13 @@ func (e *Executor) execAlterPage(s *ast.AlterPageStmt) error {
 			if err := applyDropVariable(rawData, o); err != nil {
 				return fmt.Errorf("DROP VARIABLE failed: %w", err)
 			}
+		case *ast.SetLayoutOp:
+			if containerType == "SNIPPET" {
+				return fmt.Errorf("SET Layout is not supported for snippets")
+			}
+			if err := applySetLayout(rawData, o); err != nil {
+				return fmt.Errorf("SET Layout failed: %w", err)
+			}
 		default:
 			return fmt.Errorf("unknown ALTER %s operation type: %T", containerType, op)
 		}
@@ -117,6 +124,139 @@ func (e *Executor) execAlterPage(s *ast.AlterPageStmt) error {
 	return nil
 }
 
+// applySetLayout rewrites the FormCall to reference a new layout.
+// It updates the Form field and remaps Parameter strings in each FormCallArgument.
+func applySetLayout(rawData bson.D, op *ast.SetLayoutOp) error {
+	newLayoutQN := op.NewLayout.Module + "." + op.NewLayout.Name
+
+	// Find FormCall in the page BSON
+	var formCall bson.D
+	for _, elem := range rawData {
+		if elem.Key == "FormCall" {
+			if doc, ok := elem.Value.(bson.D); ok {
+				formCall = doc
+			}
+			break
+		}
+	}
+	if formCall == nil {
+		return fmt.Errorf("page has no FormCall (layout reference)")
+	}
+
+	// Detect the old layout name from existing Parameter values
+	oldLayoutQN := ""
+	for _, elem := range formCall {
+		if elem.Key == "Form" {
+			if s, ok := elem.Value.(string); ok && s != "" {
+				oldLayoutQN = s
+			}
+		}
+		if elem.Key == "Arguments" {
+			if arr, ok := elem.Value.(bson.A); ok {
+				for _, item := range arr {
+					if doc, ok := item.(bson.D); ok {
+						for _, field := range doc {
+							if field.Key == "Parameter" {
+								if s, ok := field.Value.(string); ok && oldLayoutQN == "" {
+									// Extract layout QN from "Atlas_Core.Atlas_TopBar.Main"
+									if lastDot := strings.LastIndex(s, "."); lastDot > 0 {
+										oldLayoutQN = s[:lastDot]
+									}
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+
+	if oldLayoutQN == "" {
+		return fmt.Errorf("cannot determine current layout from FormCall")
+	}
+
+	if oldLayoutQN == newLayoutQN {
+		return nil // Already using the target layout
+	}
+
+	// Update Form field
+	for i, elem := range formCall {
+		if elem.Key == "Form" {
+			formCall[i].Value = newLayoutQN
+		}
+	}
+
+	// If Form field doesn't exist, add it
+	hasForm := false
+	for _, elem := range formCall {
+		if elem.Key == "Form" {
+			hasForm = true
+			break
+		}
+	}
+	if !hasForm {
+		// Insert before Arguments
+		for i, elem := range formCall {
+			if elem.Key == "Arguments" {
+				formCall = append(formCall[:i+1], formCall[i:]...)
+				formCall[i] = bson.E{Key: "Form", Value: newLayoutQN}
+				break
+			}
+		}
+	}
+
+	// Remap Parameter strings in each FormCallArgument
+	for _, elem := range formCall {
+		if elem.Key != "Arguments" {
+			continue
+		}
+		arr, ok := elem.Value.(bson.A)
+		if !ok {
+			continue
+		}
+		for _, item := range arr {
+			doc, ok := item.(bson.D)
+			if !ok {
+				continue
+			}
+			for j, field := range doc {
+				if field.Key != "Parameter" {
+					continue
+				}
+				paramStr, ok := field.Value.(string)
+				if !ok {
+					continue
+				}
+				// Extract placeholder name: "Atlas_Core.Atlas_Default.Main" -> "Main"
+				placeholder := paramStr
+				if strings.HasPrefix(paramStr, oldLayoutQN+".") {
+					placeholder = paramStr[len(oldLayoutQN)+1:]
+				}
+
+				// Apply explicit mapping if provided
+				if op.Mappings != nil {
+					if mapped, ok := op.Mappings[placeholder]; ok {
+						placeholder = mapped
+					}
+				}
+
+				// Write new parameter value
+				doc[j].Value = newLayoutQN + "." + placeholder
+			}
+		}
+	}
+
+	// Write FormCall back into rawData
+	for i, elem := range rawData {
+		if elem.Key == "FormCall" {
+			rawData[i].Value = formCall
+			break
+		}
+	}
+
+	return nil
+}
+
 // ============================================================================
 // bson.D helper functions for ordered document access
 // ============================================================================

mdl/grammar/MDLParser.g4

@@ -190,11 +190,16 @@ alterPageOperation
     ;
 
 alterPageSet
-    : SET alterPageAssignment ON identifierOrKeyword                             // SET Caption = 'Save' ON btnSave
+    : SET LAYOUT EQUALS qualifiedName (MAP LPAREN alterLayoutMapping (COMMA alterLayoutMapping)* RPAREN)?  // SET Layout = Atlas_Core.TopBar MAP (Main -> Main)
+    | SET alterPageAssignment ON identifierOrKeyword                             // SET Caption = 'Save' ON btnSave
     | SET LPAREN alterPageAssignment (COMMA alterPageAssignment)* RPAREN ON identifierOrKeyword  // SET (Caption = 'Save', ButtonStyle = Success) ON btnSave
     | SET alterPageAssignment                                                    // SET Title = 'Edit' (page-level)
     ;
 
+alterLayoutMapping
+    : identifierOrKeyword AS identifierOrKeyword                                // OldPlaceholder AS NewPlaceholder
+    ;
+
 alterPageAssignment
     : identifierOrKeyword EQUALS propertyValueV3       // Caption = 'Save'
     | STRING_LITERAL EQUALS propertyValueV3             // 'showLabel' = false