@blockslides/ai-context 0.1.6 → 0.3.0

package/src/contexts/v1/codeBlock.ts

@@ -1,8 +1,16 @@
 export const codeBlock = `
 <codeBlock>
-Node: codeBlock
-Attrs:
-- language (optional): string | null (e.g., "js", "ts", "python").
+Node: codeBlock (block group)
+Attrs (codeBlock-specific):
+- language (optional): string | null (e.g., "js", "ts", "python")
+
+Attrs (inherited from BaseBlockAttributes):
+- align: "left" | "center" | "right"
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- backgroundColor: string (CSS color)
+- borderRadius: "none" | "sm" | "md" | "lg"
+- (and other base attributes)
 
 Content:
 - Plain text only (no child nodes); used for preformatted code samples.

package/src/contexts/v1/column.ts

@@ -1,21 +1,41 @@
 export const column = `
 <column>
-Node: column
-Attrs:
-- className (optional): string
-- contentMode (optional): "default" (future-friendly)
-- verticalAlign (optional): "top" | "center" | "bottom" (default "top")
-- horizontalAlign (optional): "left" | "center" | "right" | "stretch" (default "left")
-- padding (optional): "none" (future-friendly)
-- backgroundMode (optional): "none" | "color" | "image" | "imageOverlay"
-- backgroundColor (optional): string (CSS color for the column background)
-- backgroundImage (optional): string (URL for column-level background image)
-- backgroundOverlayColor (optional): string (overlay color when using imageOverlay)
-- backgroundOverlayOpacity (optional): number (0–1, overlay opacity)
+Node: column (block group)
+Attrs (inherits from BaseBlockAttributes):
+- align (optional): "left" | "center" | "right" | "stretch" - horizontal alignment
+- justify (optional): "start" | "center" | "end" | "space-between" - vertical distribution of children
+- padding (optional): "none" | "sm" | "md" | "lg" - internal spacing (semantic tokens)
+- margin (optional): "none" | "sm" | "md" | "lg" - external spacing
+- gap (optional): "none" | "sm" | "md" | "lg" - space between child blocks
+- backgroundColor (optional): string - CSS color
+- backgroundImage (optional): string - background image URL
+- borderRadius (optional): "none" | "sm" | "md" | "lg" - corner rounding
+- border (optional): string - CSS border value
+- fill (optional): boolean - whether to fill available space
+- width (optional): string - explicit width (CSS value)
+- height (optional): string - explicit height (CSS value)
+
+Content:
+- Contains one or more blocks (heading, paragraph, imageBlock, bulletList, etc.)
+- Columns cannot nest other columns
+
+Spacing tokens:
+- none: 0
+- sm: 8px
+- md: 16px
+- lg: 32px
+
+Border radius tokens:
+- none: 0
+- sm: 4px
+- md: 8px
+- lg: 16px
 
 Notes:
-- Use className for spacing, colors, typography (e.g., Tailwind).
-- Keep nesting shallow; columns can contain rows or blocks as needed.
+- Use column directly in slide for full-width content
+- Wrap columns in columnGroup to place them side-by-side
+- Use justify to control vertical distribution of child blocks
+- Use gap for spacing between children instead of margins
 </column>
 `.trim();
 

package/src/contexts/v1/columnGroup.ts

@@ -0,0 +1,44 @@
+export const columnGroup = `
+<columnGroup>
+Node: columnGroup (horizontal container)
+Purpose: Groups multiple columns side-by-side horizontally
+
+Attrs:
+- layout (optional): string - Layout ratio for columns (e.g., "1-1" for equal width, "2-1" for 2:1 ratio, "1-2-1" for three columns)
+- fill (optional): boolean - Whether the columnGroup fills available vertical space
+- className (optional): string - CSS classes
+- backgroundMode (optional): "none" | "color" | "image" | "imageOverlay"
+- backgroundColor (optional): string - CSS color for background
+- backgroundImage (optional): string - URL for background image
+- backgroundOverlayColor (optional): string - Color for overlay when using imageOverlay
+- backgroundOverlayOpacity (optional): number (0-1) - Opacity for overlay
+
+Content:
+- Contains one or more column nodes
+- Columns within a columnGroup are displayed side-by-side horizontally
+- Each column shares the horizontal space (equal width by default, or based on layout attribute)
+
+Usage:
+- Use columnGroup when you want columns to appear next to each other horizontally
+- For full-width content, use column directly in the slide (without columnGroup)
+- You can have multiple columnGroups in a slide to create different rows of columns
+
+Examples:
+1. Two equal columns side-by-side:
+   columnGroup { content: [column, column] }
+
+2. Three columns with 2:1:1 ratio:
+   columnGroup { attrs: { layout: "2-1-1" }, content: [column, column, column] }
+
+3. Full-width content above and below a two-column section:
+   slide {
+     content: [
+       column { ... },              // full-width
+       columnGroup {                // side-by-side
+         content: [column, column]
+       },
+       column { ... }               // full-width
+     ]
+   }
+</columnGroup>
+`.trim();

package/src/contexts/v1/core.ts

@@ -4,15 +4,35 @@ You are given a BlockSlides document to CREATE or EDIT.
 
 Document shape:
 - doc: { type: "doc", content: slide[] }
-- slide: { type: "slide", attrs?, content: row[] }
-- row: { type: "row", attrs?, content: column[] | block[] }
-- column: { type: "column", attrs?, content: (block | row)[] }
-- block: includes nodes like paragraph, heading, imageBlock, etc.
+- slide: { type: "slide", attrs?, content: block[] }
+- block: includes heading, paragraph, column, imageBlock, bulletList, codeBlock, blockquote, horizontalRule, youtube, etc.
+- column: { type: "column", attrs?, content: block[] }
+
+Key changes:
+- Slides can contain columns, columnGroups, or any block-level content
+- Use column directly in slide for full-width blocks
+- Use columnGroup to place multiple columns side-by-side
+- All block types inherit common attributes from BaseBlockAttributes
+
+BaseBlockAttributes (available on all blocks):
+- align: "left" | "center" | "right" | "stretch"
+- justify: "start" | "center" | "end" | "space-between" (for containers)
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- gap: "none" | "sm" | "md" | "lg"
+- backgroundColor: string (CSS color)
+- backgroundImage: string (URL)
+- borderRadius: "none" | "sm" | "md" | "lg"
+- border: string (CSS border)
+- fill: boolean (fill available space)
+- width: string (CSS width)
+- height: string (CSS height)
 
 Rules:
 - Use only known node types and valid attrs. Do not invent attributes.
 - Prefer stable references: preserve slide.attrs.id if present.
 - Slides and flyers share the same JSON; flyers are slides sized via attrs and theme.
+- Use semantic spacing tokens (sm/md/lg) instead of raw pixel values
 </core>
 `.trim();
 

package/src/contexts/v1/editingRules.ts

@@ -3,7 +3,7 @@ export const editingRules = `
 - Preserve existing ids and valid attributes. Do not remove or rename known attrs.
 - Use only allowed enum values. Do not invent new enum values.
 - Avoid introducing new attributes that are not documented. If styling is needed, prefer className.
-- Keep the document valid: slide > row > column > blocks.
+- Keep the document valid: slide > (column | columnGroup > column) > blocks.
 </General editing rules>
 
 <Centering content in a column>
@@ -17,17 +17,17 @@ export const editingRules = `
   - After:  column.attrs = { verticalAlign: "center", horizontalAlign: "center", padding: "none" }
 </Centering content in a column>
 
-<Backgrounds (slides, rows, columns)>
+<Backgrounds (slides, columnGroups, columns)>
 - Use structured background attrs instead of raw Tailwind bg-[url(...)] when setting background images.
 - If you use bg-[...], the image will not work because the tailwind classes we need have been tree shaken off - instead use the attributes.
 - For slide-level backgrounds (hero/flyer):
   - Use slide.attrs.backgroundMode = "color" | "image" | "imageOverlay".
   - For images, set slide.attrs.backgroundImage to the image URL.
   - For overlays, set slide.attrs.backgroundOverlayColor (e.g., "rgba(0,0,0,0.8)") and slide.attrs.backgroundOverlayOpacity (0–1).
-- For horizontal bands, use row-level backgrounds (row.attrs.background*).
+- For horizontal bands, use columnGroup-level backgrounds (columnGroup.attrs.background*).
 - For panel-style sections, use column-level backgrounds (column.attrs.background*).
-- Do not mix multiple background images on the same node; prefer one backgroundMode per slide/row/column and layer additional visuals as imageBlock nodes.
-</Backgrounds (slides, rows, columns)>
+- Do not mix multiple background images on the same node; prefer one backgroundMode per slide/columnGroup/column and layer additional visuals as imageBlock nodes.
+</Backgrounds (slides, columnGroups, columns)>
 
 <Text editing (headings and paragraphs)>
 - Preserve semantic types: do not turn headings into paragraphs or vice versa unless explicitly asked.

package/src/contexts/v1/heading.ts

@@ -1,8 +1,16 @@
 export const heading = `
 <heading>
-Node: heading
-Attrs:
-- level (required): 1 | 2 | 3 | 4 | 5 | 6.
+Node: heading (block group)
+Attrs (heading-specific):
+- level (required): 1 | 2 | 3 | 4 | 5 | 6
+
+Attrs (inherited from BaseBlockAttributes):
+- align: "left" | "center" | "right"
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- backgroundColor: string (CSS color)
+- borderRadius: "none" | "sm" | "md" | "lg"
+- (and other base attributes)
 
 Content:
 - Inline content (text, marks, inline nodes).
@@ -10,7 +18,6 @@ Content:
 Semantics:
 - Renders as <h1>…<h6> depending on level.
 - Use level 1–2 for main slide titles, 3–4 for section headings, 5–6 for subtle labels.
-- Do not invent other attrs; typography/styling should come from className on columns/slides.
 </heading>
 `.trim();
 

package/src/contexts/v1/horizontalRule.ts

@@ -1,15 +1,20 @@
 export const horizontalRule = `
 <horizontalRule>
-Node: horizontalRule
-Attrs:
-- HTML-only; no JSON attrs beyond optional styling via surrounding layout.
+Node: horizontalRule (block group)
+Attrs (inherited from BaseBlockAttributes):
+- align: "left" | "center" | "right" | "stretch"
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- backgroundColor: string (CSS color)
+- (and other base attributes)
 
 Content:
 - No children; this is a self-contained separator.
 
 Semantics:
 - Renders as <hr>.
-- Use to visually separate sections within a slide (for example, between rows of text).
+- Use to visually separate sections within a slide.
+- Can control spacing around the rule with padding/margin.
 </horizontalRule>
 `.trim();
 

package/src/contexts/v1/imageBlock.ts

@@ -1,28 +1,37 @@
 export const imageBlock = `
 <imageBlock>
-Node: imageBlock
-Attrs:
-- src (required): string (URL)
-- alt (optional): string
-- caption (optional): string
-- credit (optional): string
-- layout (optional): "cover" | "contain" | "fill" | "focus" | "pattern"
-- align (optional): "left" | "center" | "right" | "stretch" (default "center")
-- width (optional): number (px) or string ("%"/"px")
-- height (optional): number (px) or string ("%"/"px")
-- fullBleed (optional): boolean (removes radius; stretches width)
-- assetId (optional): string
-- focalX, focalY (optional): 0–100; spotlight position (when relevant)
+Node: imageBlock (block group)
+Attrs (required):
+- src (required): string (image URL)
 
-Behavior:
-- Numbers for width/height are interpreted as pixels.
-- layout:
-  - cover: Fill container; crop edges as needed.
-  - contain: Fit entirely; may letterbox.
-  - fill: Stretch to container (may distort).
-  - focus: Cover + radial spotlight at focalX/focalY.
-  - pattern: Hide <img>; use tiled background (from src).
-- Do not set unknown attributes. Preserve existing valid attrs.
+Attrs (optional - image-specific):
+- alt (optional): string - alt text for accessibility
+- caption (optional): string - image caption
+- credit (optional): string - image credit/attribution
+- assetId (optional): string - asset reference
+- size (optional): "fill" | "fit" | "natural" - how image fills container
+  - fill: Cover entire container (width:100%, height:100%, object-fit:cover)
+  - fit: Fit inside container with letterboxing (object-fit:contain)
+  - natural: Use image's natural dimensions
+- crop (optional): "center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right"
+  - Focal point for fill/fit modes (default: "center")
+
+Attrs (inherited from BaseBlockAttributes):
+- align (optional): "left" | "center" | "right" | "stretch" - block alignment
+- padding (optional): "none" | "sm" | "md" | "lg" - internal padding
+- margin (optional): "none" | "sm" | "md" | "lg" - external margin
+- backgroundColor (optional): string - background color
+- borderRadius (optional): "none" | "sm" | "md" | "lg" - corner rounding
+- width (optional): string - explicit width override (CSS value)
+- height (optional): string - explicit height override (CSS value)
+
+Deprecated attributes (kept for backwards compatibility, do not use):
+- layout, fullBleed, focalX, focalY
+
+Notes:
+- Default size is "fill" if not specified
+- Use crop to control which part of the image is visible when cropped
+- width/height overrides apply on top of size mode
 </imageBlock>
 `.trim();
 

package/src/contexts/v1/index.ts

@@ -1,8 +1,8 @@
 export { core } from "./core";
 export { fullDocument } from "./output.fullDocument";
 export { imageBlock } from "./imageBlock";
-export { row } from "./row";
 export { column } from "./column";
+export { columnGroup } from "./columnGroup";
 export { slide } from "./slide";
 export { style } from "./style";
 export { editingRules } from "./editingRules";

package/src/contexts/v1/paragraph.ts

@@ -1,15 +1,21 @@
 export const paragraph = `
 <paragraph>
-Node: paragraph
-Attrs:
-- HTML-only; no structured JSON attrs beyond optional styling such as className.
+Node: paragraph (block group)
+Attrs (inherited from BaseBlockAttributes):
+- align: "left" | "center" | "right"
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- backgroundColor: string (CSS color)
+- borderRadius: "none" | "sm" | "md" | "lg"
+- (and other base attributes)
 
 Content:
 - Inline content (text with marks, inline nodes such as image or hardBreak).
 
 Semantics:
-- Default text block inside columns and rows.
-- Multiple paragraphs can be stacked within the same column to create vertical rhythm.
+- Default text block inside columns and slides.
+- Multiple paragraphs can be stacked to create vertical rhythm.
+- Use gap on parent column instead of margin on individual paragraphs for consistent spacing.
 </paragraph>
 `.trim();
 

package/src/contexts/v1/slide.ts

@@ -12,12 +12,16 @@ Attrs:
 - backgroundOverlayOpacity (optional): number (0–1, opacity for the overlay)
 
 Content:
-- slide contains one or more rows.
+- slide can contain columns, columnGroups, or any block-level content (heading, paragraph, imageBlock, bulletList, codeBlock, etc.)
+- Use column directly for full-width content
+- Use columnGroup to place multiple columns side-by-side
+- You can mix columns, columnGroups, and other blocks in any order
 
 Notes:
 - Flyers are slides sized for paper (e.g., size: "a4-portrait").
 - Set size to control canvas dimensions; theme applies the exact width/height.
 - For background images, prefer backgroundMode/backgroundImage over Tailwind bg-[url(...)]; the extension will inject the correct CSS.
+- To create multi-column layouts, wrap columns in a columnGroup
 </slide>
 `.trim();
 

package/src/contexts/v1/youtube.ts

@@ -1,18 +1,25 @@
 export const youtube = `
 <youtube>
-Node: youtube
-Attrs:
-- src (required): string (public YouTube URL).
-- start (optional): number (start time in seconds).
-- width (optional): number (frame width in px).
-- height (optional): number (frame height in px).
+Node: youtube (block group)
+Attrs (youtube-specific):
+- src (required): string (public YouTube URL)
+- start (optional): number (start time in seconds)
+- width (optional): number (frame width in px)
+- height (optional): number (frame height in px)
+
+Attrs (inherited from BaseBlockAttributes):
+- align: "left" | "center" | "right" | "stretch"
+- padding: "none" | "sm" | "md" | "lg"
+- margin: "none" | "sm" | "md" | "lg"
+- borderRadius: "none" | "sm" | "md" | "lg"
+- (and other base attributes)
 
 Content:
 - No children; this is an atomic embed node.
 
 Semantics:
 - Renders as an embedded YouTube iframe wrapped in a container <div>.
-- Use for video embeds inside a column or row; keep other text in separate paragraphs/columns.
+- Use for video embeds inside a column or slide.
 - Do not embed raw <iframe> HTML directly; always use the youtube node with attrs.
 </youtube>
 `.trim();

package/src/index.ts

@@ -1,7 +1,5 @@
 export * as contextsV1 from "./contexts/v1";
-export * as examplesV1 from "./examples/v1";
 export * as bundlesV1 from "./bundles/v1";
-export * as recipesV1 from "./recipes/v1";
 export * as schemasV1 from "./schemas/v1";
+export * as templatesV1 from "./templates/v1";
 export * from "./types/v1";
-

package/src/schemas/v1/blockquote.schema.json

@@ -1,16 +1,27 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "blockquote",
+  "description": "A blockquote. Inherits common block attributes.",
   "type": "object",
   "properties": {
     "type": { "const": "blockquote" },
     "attrs": {
       "type": "object",
+      "properties": {
+        "align": { "enum": ["left", "center", "right", null], "description": "Text alignment" },
+        "padding": { "enum": ["none", "sm", "md", "lg", null], "description": "Internal padding" },
+        "margin": { "enum": ["none", "sm", "md", "lg", null], "description": "External margin" },
+        "backgroundColor": { "type": ["string", "null"], "description": "Background color" },
+        "borderRadius": { "enum": ["none", "sm", "md", "lg", null], "description": "Corner rounding" }
+      },
       "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Block content"
     }
   },
   "required": ["type"],
   "additionalProperties": false
 }
-
-

package/src/schemas/v1/bulletList.schema.json

@@ -1,16 +1,27 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "bulletList",
+  "description": "A bullet list block. Inherits common block attributes.",
   "type": "object",
   "properties": {
     "type": { "const": "bulletList" },
     "attrs": {
       "type": "object",
+      "properties": {
+        "align": { "enum": ["left", "center", "right", null], "description": "Text alignment" },
+        "padding": { "enum": ["none", "sm", "md", "lg", null], "description": "Internal padding" },
+        "margin": { "enum": ["none", "sm", "md", "lg", null], "description": "External margin" },
+        "backgroundColor": { "type": ["string", "null"], "description": "Background color" },
+        "borderRadius": { "enum": ["none", "sm", "md", "lg", null], "description": "Corner rounding" }
+      },
       "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "List items"
     }
   },
   "required": ["type"],
   "additionalProperties": false
 }
-
-

package/src/schemas/v1/codeBlock.schema.json

@@ -1,19 +1,28 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "codeBlock",
+  "description": "A code block. Inherits common block attributes.",
   "type": "object",
   "properties": {
     "type": { "const": "codeBlock" },
     "attrs": {
       "type": "object",
       "properties": {
-        "language": { "type": ["string", "null"] }
+        "language": { "type": ["string", "null"], "description": "Programming language for syntax highlighting" },
+        "align": { "enum": ["left", "center", "right", null], "description": "Block alignment" },
+        "padding": { "enum": ["none", "sm", "md", "lg", null], "description": "Internal padding" },
+        "margin": { "enum": ["none", "sm", "md", "lg", null], "description": "External margin" },
+        "backgroundColor": { "type": ["string", "null"], "description": "Background color" },
+        "borderRadius": { "enum": ["none", "sm", "md", "lg", null], "description": "Corner rounding" }
       },
       "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Code text content"
     }
   },
   "required": ["type"],
   "additionalProperties": false
 }
-
-

package/src/schemas/v1/column.schema.json

@@ -1,30 +1,34 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "column",
+  "description": "A container block that holds other blocks. Common attributes (align, padding, gap, backgroundColor, etc.) are shared with all block types.",
   "type": "object",
   "properties": {
     "type": { "const": "column" },
     "attrs": {
       "type": "object",
       "properties": {
-        "className": { "type": ["string", "null"] },
-        "contentMode": { "enum": ["default", null] },
-        "verticalAlign": { "enum": ["top", "center", "bottom", null] },
-        "horizontalAlign": { "enum": ["left", "center", "right", "stretch", null] },
-        "padding": { "enum": ["none", null] },
-        "backgroundMode": {
-          "enum": ["none", "color", "image", "imageOverlay", null]
-        },
-        "backgroundColor": { "type": ["string", "null"] },
-        "backgroundImage": { "type": ["string", "null"] },
-        "backgroundOverlayColor": { "type": ["string", "null"] },
-        "backgroundOverlayOpacity": { "type": ["number", "null"] }
+        "align": { "enum": ["left", "center", "right", "stretch", null], "description": "Horizontal alignment of content" },
+        "justify": { "enum": ["start", "center", "end", "space-between", null], "description": "Vertical distribution of children" },
+        "padding": { "enum": ["none", "sm", "md", "lg", null], "description": "Internal padding" },
+        "margin": { "enum": ["none", "sm", "md", "lg", null], "description": "External margin" },
+        "gap": { "enum": ["none", "sm", "md", "lg", null], "description": "Gap between child blocks" },
+        "backgroundColor": { "type": ["string", "null"], "description": "Background color" },
+        "backgroundImage": { "type": ["string", "null"], "description": "Background image URL" },
+        "borderRadius": { "enum": ["none", "sm", "md", "lg", null], "description": "Corner rounding" },
+        "border": { "type": ["string", "null"], "description": "CSS border value" },
+        "fill": { "type": ["boolean", "null"], "description": "Whether to fill available space" },
+        "width": { "type": ["string", "null"], "description": "Explicit width" },
+        "height": { "type": ["string", "null"], "description": "Explicit height" }
       },
       "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Child blocks"
     }
   },
   "required": ["type"],
   "additionalProperties": false
 }
-
-

package/src/schemas/v1/columnGroup.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "columnGroup",
+  "description": "A horizontal container that groups multiple columns side-by-side. Use columnGroup when you want columns to be placed next to each other horizontally. For full-width content, use column directly in the slide.",
+  "type": "object",
+  "properties": {
+    "type": { "const": "columnGroup" },
+    "attrs": {
+      "type": "object",
+      "properties": {
+        "layout": {
+          "type": ["string", "null"],
+          "description": "Layout ratio for columns (e.g., '1-1' for equal, '2-1' for 2:1 ratio)"
+        },
+        "fill": {
+          "type": ["boolean", "null"],
+          "description": "Whether the columnGroup should fill available vertical space"
+        },
+        "className": { "type": ["string", "null"] },
+        "backgroundMode": {
+          "enum": ["none", "color", "image", "imageOverlay", null]
+        },
+        "backgroundColor": { "type": ["string", "null"] },
+        "backgroundImage": { "type": ["string", "null"] },
+        "backgroundOverlayColor": { "type": ["string", "null"] },
+        "backgroundOverlayOpacity": { "type": ["number", "null"] }
+      },
+      "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "type": { "const": "column" }
+        },
+        "required": ["type"]
+      },
+      "minItems": 1,
+      "description": "Array of column nodes"
+    }
+  },
+  "required": ["type", "content"],
+  "additionalProperties": false
+}

package/src/schemas/v1/heading.schema.json

@@ -1,23 +1,28 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "heading",
+  "description": "A heading block (h1-h6). Inherits common block attributes.",
   "type": "object",
   "properties": {
     "type": { "const": "heading" },
     "attrs": {
       "type": "object",
       "properties": {
-        "level": {
-          "type": "integer",
-          "minimum": 1,
-          "maximum": 6
-        }
+        "level": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Heading level (1-6)" },
+        "align": { "enum": ["left", "center", "right", null], "description": "Text alignment" },
+        "padding": { "enum": ["none", "sm", "md", "lg", null], "description": "Internal padding" },
+        "margin": { "enum": ["none", "sm", "md", "lg", null], "description": "External margin" },
+        "backgroundColor": { "type": ["string", "null"], "description": "Background color" },
+        "borderRadius": { "enum": ["none", "sm", "md", "lg", null], "description": "Corner rounding" }
       },
       "additionalProperties": true
+    },
+    "content": {
+      "type": "array",
+      "items": { "type": "object" },
+      "description": "Inline content (text, marks)"
     }
   },
   "required": ["type"],
   "additionalProperties": false
 }
-
-