fix(html): improve validation guidance

codegen/codegen.go

@@ -209,6 +209,8 @@ type slotEntry struct {
 
 var canonicalSlotOrder = []string{"H", "L", "C", "R", "F"}
 
+const validSlotKeys = "H, L, C, R, F"
+
 func validateSlotKeys(slots map[string]string) error {
 	if len(slots) == 0 {
 		return nil
@@ -238,7 +240,7 @@ func validateSlotKeys(slots map[string]string) error {
 	for _, slot := range invalid {
 		quoted = append(quoted, strconv.Quote(slot))
 	}
-	return log.E("codegen", "invalid slot key(s): "+strings.Join(quoted, ", "), nil)
+	return log.E("codegen", "invalid slot key(s): "+strings.Join(quoted, ", ")+"; valid keys: "+validSlotKeys, nil)
 }
 
 func orderedSlotEntries(slots map[string]string) []slotEntry {

codegen/codegen_test.go

@@ -97,6 +97,7 @@ func TestGenerateBundle_Bad_InvalidSlotKey(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "invalid slot key")
 	assert.Contains(t, err.Error(), `"X"`)
+	assert.Contains(t, err.Error(), "valid keys: H, L, C, R, F")
 }
 
 func TestGenerateBundle_Bad_ReservedTag(t *testing.T) {

layout.go

@@ -15,6 +15,8 @@ var _ Node = (*Layout)(nil)
 // Example: errors.Is(ValidateLayoutVariant("HXC"), ErrInvalidLayoutVariant).
 var ErrInvalidLayoutVariant = errors.New("html: invalid layout variant")
 
+const validLayoutSlots = "H, L, C, R, F"
+
 // slotMeta holds the semantic HTML mapping for each HLCRF slot.
 type slotMeta struct {
 	tag  string
@@ -284,6 +286,8 @@ func (e *LayoutVariantError) Error() string {
 			b.WriteString(strconv.Itoa(e.invalidPositions[i] + 1))
 		}
 	}
+	b.WriteString("; valid slots: ")
+	b.WriteString(validLayoutSlots)
 	b.WriteByte(')')
 	return b.String()
 }

layout_test.go

@@ -207,7 +207,7 @@ func TestLayout_VariantError(t *testing.T) {
 			name:          "mixed invalid variant",
 			variant:       "HXC",
 			wantErr:       true,
-			wantErrString: "html: invalid layout variant HXC (invalid slot: 'X' at position 2)",
+			wantErrString: "html: invalid layout variant HXC (invalid slot: 'X' at position 2; valid slots: H, L, C, R, F)",
 			wantRender: `<header role="banner" data-block="H-0">header</header>` +
 				`<main role="main" data-block="C-0">main</main>`,
 		},
@@ -215,7 +215,7 @@ func TestLayout_VariantError(t *testing.T) {
 			name:          "multiple invalid slots",
 			variant:       "H1X?",
 			wantErr:       true,
-			wantErrString: "html: invalid layout variant H1X? (invalid slots: '1' at position 2, 'X' at position 3, '?' at position 4)",
+			wantErrString: "html: invalid layout variant H1X? (invalid slots: '1' at position 2, 'X' at position 3, '?' at position 4; valid slots: H, L, C, R, F)",
 			wantRender:    `<header role="banner" data-block="H-0">header</header>`,
 		},
 	}