| Aspect | Grid (Phase 1) | Columns (Phase 2) | | ----------------- | --------------------------------- | --------------------------------------------- | | Nesting depth | 1 level (container -> items) | 2 levels (container -> column wrappers -> content) | | Column count | Attribute (columnCount) | Number of direct children | | Item overflow | Wraps to next row | No overflow, each column is independent | | Content per column| Single block per cell | Multiple blocks per column | | Width control | Equal width, CSS grid | Per-column via columnWidths attribute |

frontend/packages/shared/src/hm-types.ts

Add 'Columns' to HMBlockChildrenTypeSchema (Grid already present from Phase 1):

z.union([
  z.literal('Group'),
  z.literal('Ordered'),
  z.literal('Unordered'),
  z.literal('Blockquote'),
  z.literal('Grid'),
  z.literal('Columns'),
])

frontend/packages/editor/src/blocknote/core/extensions/Blocks/api/defaultBlocks.ts

childrenType: {
  default: 'Group',
  values: ['Group', 'Unordered', 'Ordered', 'Blockquote', 'Grid', 'Columns'],
}

frontend/packages/shared/src/client/hmblock-to-editorblock.ts

• Accept 'Columns' as valid childrenType (same pattern as Grid from Phase 1)

frontend/packages/shared/src/client/editorblock-to-hmblock.ts

• Pass through 'Columns' childrenType

• Preserve columnWidths attribute in conversion

frontend/packages/editor/src/blocknote/core/extensions/Blocks/nodes/BlockChildren.ts

• listNode(): Add case for 'Columns' — render as <div> with display: flex; flex-direction: row; gap styles

• Each child blockNode inside a Columns container renders as a flex item

• addInputRules(): Phase 1 Grid guard already exists — extend to also cover Columns

frontend/packages/editor/src/blocknote/core/extensions/KeyboardShortcuts/KeyboardShortcutsExtension.ts

Rename Phase 1's isInGridContainer() -> isInLayoutContainer() covering both Grid and Columns.

Additional guards needed beyond what Grid already has:

| Handler | Guard | | ------------------------ | -------------------------------------------------------------------- | | handleBackspace (~26) | Prevent merging across column boundaries (col-1 block can't merge with col-2 block) | | handleDelete (~315) | Same — prevent cross-column merging | | handleEnter (~423) | On empty block inside column: stay in column, don't unnest to parent | | handleTab (~541) | Prevent indent of column wrappers — already guarded by Phase 1 | | Shift-Tab (~621) | Prevent outdent of column wrappers — already guarded by Phase 1 |

frontend/packages/editor/src/blocknote/core/api/blockManipulation/commands/nestBlock.ts

Phase 1 already prevents nesting in Grid. Extend to:

• Prevent nesting column wrapper blocks (direct children of Columns container)

• Content blocks INSIDE a column CAN still be nested normally (they're inside a regular Group)

frontend/packages/editor/src/blocknote/core/api/blockManipulation/commands/mergeBlocks.ts

• canMerge(): Add guard — blocks in different columns cannot merge

• getPrevBlockInfo(): Stop traversal at column wrapper boundaries

frontend/packages/editor/src/slash-menu-items.tsx

{
  name: 'Columns',
  aliases: ['cols', 'side-by-side', 'split'],
  group: 'Layout',
  icon: ColumnsIcon,
  execute: (editor) => {
    // 1. Replace current block with empty block, set childrenType: 'Columns'
    // 2. Create 2 child blocks (column wrappers), each with childrenType: 'Group'
    // 3. Each column wrapper gets 1 empty paragraph child
    // 4. Place cursor in first column's paragraph
  }
}

Floating toolbar on the Columns container (on hover/selection):

• "Add Column" button — creates a new column wrapper child

• "Remove Column" button — removes the last column (min 2 enforced)

• Column count display (e.g., "2 columns")

• "Convert to normal blocks" — flattens: removes column wrappers, moves all content blocks to parent level

Column width resize handles:

• Draggable divider between columns

• Updates columnWidths attribute on the container block

• Visual feedback during drag

frontend/packages/ui/src/blocks-content.tsx — BlockNodeList (line 464):

if (childrenType === 'Columns') {
  return (
    <div
      className="flex flex-row gap-4 w-full"
      data-node-type="blockGroup"
      data-list-type="Columns"
    >
      {children}
    </div>
  )
}

BlockNodeContent: When parent is Columns:

• Each child renders as a flex item with flex: 1 (or proportional width from columnWidths)

• Hide the empty container paragraph block (invisible wrapper)

• Column content renders normally via recursive BlockNodeList

frontend/packages/editor/src/blocknote/core/extensions/SideMenu/SideMenuPlugin.ts

• blockPositionsFromSelection(): Prevent selection spanning multiple columns

• onDrop(): Calculate drop target with column awareness — blocks dropped on a column land inside it

• Future follow-up: side-drop indicators (like BlockNote's multiColumnDropCursor) for dragging blocks into new columns

CSS media queries:

• Below tablet breakpoint: flex-direction: column — columns stack vertically

• Column widths reset to 100% on mobile

frontend/packages/shared/src/client/__tests__/hmblock-to-editorblock.test.ts

Add to existing describe('childrenType'):

test('Columns', () => {
  const hmBlock: HMBlock = {
    id: 'foo',
    type: 'Paragraph',
    text: '',
    annotations: [],
    attributes: {childrenType: 'Columns'},
    revision: 'revision123',
  }
  const val = hmBlockToEditorBlock(hmBlock)
  expect(val.props.childrenType).toBe('Columns')
})

test('Columns with columnWidths attribute', () => {
  const hmBlock: HMBlock = {
    id: 'foo',
    type: 'Paragraph',
    text: '',
    annotations: [],
    attributes: {childrenType: 'Columns', columnWidths: [60, 40]},
    revision: 'revision123',
  }
  const val = hmBlockToEditorBlock(hmBlock)
  expect(val.props.childrenType).toBe('Columns')
})

test('Columns with nested children structure', () => {
  const blocks: HMBlockNode[] = [
    {
      block: {
        id: 'cols-1',
        type: 'Paragraph',
        text: '',
        annotations: [],
        attributes: {childrenType: 'Columns'},
      },
      children: [
        {
          block: {
            id: 'col-1',
            type: 'Paragraph',
            text: '',
            annotations: [],
            attributes: {childrenType: 'Group'},
          },
          children: [
            {
              block: {
                id: 'p1',
                type: 'Paragraph',
                text: 'Left',
                annotations: [],
                attributes: {},
              },
              children: [],
            },
          ],
        },
        {
          block: {
            id: 'col-2',
            type: 'Paragraph',
            text: '',
            annotations: [],
            attributes: {childrenType: 'Group'},
          },
          children: [
            {
              block: {
                id: 'p2',
                type: 'Paragraph',
                text: 'Right',
                annotations: [],
                attributes: {},
              },
              children: [],
            },
          ],
        },
      ],
    },
  ]
  const result = hmBlocksToEditorContent(blocks)
  expect(result[0].props.childrenType).toBe('Columns')
  expect(result[0].children).toHaveLength(2)
  expect(result[0].children[0].children).toHaveLength(1)
  expect(result[0].children[1].children).toHaveLength(1)
})

frontend/packages/shared/src/client/__tests__/editorblock-to-hmblock.test.ts

Add to existing describe('childrenType'):

test('Columns', () => {
  const editorBlock: EditorBlock = {
    id: 'foo',
    type: 'paragraph',
    children: [],
    props: {childrenType: 'Columns'},
    content: [],
  }
  const val = editorBlockToHMBlock(editorBlock)
  expect(val.attributes.childrenType).toBe('Columns')
})

frontend/packages/editor/src/blocknote/core/api/blockManipulation/__tests__/nestBlock.test.ts

describe('Columns container', () => {
  it('prevents nesting column wrapper blocks', () => {
    // Column wrapper (direct child of Columns) cannot be indented
    const doc = buildDoc(schema, [
      {
        id: 'cols-container',
        text: '',
        children: {
          listType: 'Columns',
          blocks: [
            {
              id: 'col-1',
              text: '',
              children: {blocks: [{id: 'p1', text: 'Left'}]},
            },
            {
              id: 'col-2',
              text: '',
              children: {blocks: [{id: 'p2', text: 'Right'}]},
            },
          ],
        },
      },
    ])
    const state = EditorState.create({doc, schema})
    const editor = createMockEditor(state)
    const pos = findPosInBlock(doc, 'col-2')
    const result = nestBlock(editor, pos)
    expect(result).toBe(false)
  })

  it('allows nesting content blocks inside a column', () => {
    // Content inside a column (regular Group) CAN be nested normally
    const doc = buildDoc(schema, [
      {
        id: 'cols-container',
        text: '',
        children: {
          listType: 'Columns',
          blocks: [
            {
              id: 'col-1',
              text: '',
              children: {
                blocks: [
                  {id: 'p1', text: 'First'},
                  {id: 'p2', text: 'Second'},
                ],
              },
            },
          ],
        },
      },
    ])
    const state = EditorState.create({doc, schema})
    const editor = createMockEditor(state)
    const pos = findPosInBlock(doc, 'p2')
    const result = nestBlock(editor, pos)
    expect(result).toBe(true)
  })
})

frontend/packages/editor/src/blocknote/core/api/blockManipulation/__tests__/mergeBlocks.test.ts

describe('Columns container', () => {
  it('prevents merging blocks across column boundaries', () => {
    // Block at end of col-1 + Backspace should NOT merge with start of col-2
    const doc = buildDoc(schema, [
      {
        id: 'cols-container',
        text: '',
        children: {
          listType: 'Columns',
          blocks: [
            {
              id: 'col-1',
              text: '',
              children: {blocks: [{id: 'p1', text: 'Left'}]},
            },
            {
              id: 'col-2',
              text: '',
              children: {blocks: [{id: 'p2', text: 'Right'}]},
            },
          ],
        },
      },
    ])
    const state = EditorState.create({doc, schema})
    const editor = createMockEditor(state)
    // Place cursor at start of p2 and try to merge backwards
    const pos = findPosInBlock(doc, 'p2')
    const result = mergeBlocks(editor, pos)
    expect(result).toBe(false)
  })
})

frontend/packages/shared/src/__tests__/hm-types.test.ts

test('HMBlockChildrenType accepts Columns', () => {
  expect(HMBlockChildrenTypeSchema.parse('Columns')).toBe('Columns')
})