DEV Community: Gles

Claude Code Stuck on Vertical Scroll Not Working: Flex Children Need minHeight

Gles — Sat, 31 Jan 2026 13:59:08 +0000

The Problem

I had a 3-column layout using Flexbox. When the browser window was resized vertically, the content got cut off with no scrollbar appearing.

<div className="flex h-screen overflow-auto">
  <div className="flex-1">Column 1</div>
  <div className="flex-1">Column 2</div>
  <div className="flex-1">Column 3</div>
</div>

Expected: Vertical scrollbar appears when window is too short.

Actual: Content just disappears. No scrollbar. The columns shrink with the window.

Why Claude Code Got Stuck

Claude Code initially thought "the browser can't scroll - maybe this is a browser limitation." The debugging went through several wrong directions:

Adding overflow-y: auto to the container (already had it)
Checking if content was being clipped by overflow: hidden somewhere
Considering it a "browser limitation" for web apps

The real issue was never about overflow settings. It was about what was actually overflowing.

Root Cause Analysis

Flexbox children shrink by default to fit their parent. When you resize the window:

The parent container shrinks (because h-screen follows viewport)
The flex children shrink to fit (default flex-shrink: 1)
Nothing overflows because everything just gets smaller
No overflow = no scrollbar

The container had overflow: auto, but there was nothing overflowing! The children obediently shrank to fit.

Before resize:        After resize:
┌──────────────┐      ┌──────────────┐
│   Content    │      │   Content    │  <- Shrunk, not overflowing!
│   (500px)    │      │   (200px)    │
│              │      └──────────────┘
│              │
└──────────────┘

The Solution

Set a minHeight on the flex children so they can't shrink below a certain size:

const [minColumnHeight, setMinColumnHeight] = React.useState(0);

React.useEffect(() => {
  // Calculate minimum height based on screen
  const screenHeight = window.screen.availHeight;
  const minHeight = screenHeight * 0.5;
  setMinColumnHeight(minHeight);
}, []);

return (
  <div className="flex h-screen overflow-auto">
    <div className="flex-1" style={{ minHeight: minColumnHeight }}>
      Column 1
    </div>
    <div className="flex-1" style={{ minHeight: minColumnHeight }}>
      Column 2
    </div>
    <div className="flex-1" style={{ minHeight: minColumnHeight }}>
      Column 3
    </div>
  </div>
);

Now when the window shrinks:

Parent container shrinks
Children try to shrink but hit minHeight
Children now overflow the parent
Scrollbar appears!

After resize with minHeight:
┌──────────────┐
│   Content    │  <- minHeight prevents shrinking
│   (500px)    │
│──────────────│  <- Scrollable!
│   (hidden)   │
└──────────────┘

Key Takeaways for AI Agents

Claude Code users: if you're hitting this, try:

Remember: overflow: auto only works if something actually overflows
Flex children shrink by default - they won't overflow unless you prevent shrinking
Use minHeight (or minWidth for horizontal) to create a "floor" that forces overflow
Don't assume it's a "browser limitation" - check if your content is even trying to overflow

The mental model:

Scrollbar appears when: content size > container size

Flex default behavior: content size = container size (children shrink to fit)

Fix: content size = max(minHeight, natural size) > container size

Keywords for search:
flex vertical scroll not working, overflow auto no scrollbar, flex children shrink, minHeight scroll, flexbox overflow, content disappears on resize, flex-shrink scroll

This article is part of the "Claude Code Debugging Chronicles" series, documenting real debugging sessions with AI coding assistants.

Related Articles:

Claude Code Stuck on Minimum Window Size: You Can't Control Browser Window Size from Web Apps

Gles — Sat, 31 Jan 2026 13:56:10 +0000

The Problem

I wanted to prevent users from shrinking the browser window below 50% of their screen size. Seemed like a reasonable UX constraint.

// My naive attempts
window.minWidth = 800;  // Doesn't exist
window.resizeTo(800, 600);  // Security blocked

Expected: Window can't shrink below 50% of screen.

Actual: Nothing works. Browser ignores all attempts.

Why Claude Code Got Stuck

Claude Code went down a rabbit hole trying different APIs:

First tried window.innerWidth calculations (wrong API for the goal)
Then tried window.screen.availWidth (better API, but still can't control window)
Explored CSS min-width: 50vw on body (doesn't constrain window)
Considered window.resizeTo() (blocked by browsers for security)

The fundamental assumption was wrong: "There must be a way to control window size from JavaScript."

Root Cause Analysis

Browser security model prevents web apps from controlling window size.

This is intentional:

Prevents malicious sites from making unclosable windows
Stops phishing sites from mimicking OS dialogs
Protects user control over their own browser

The only exception: window.resizeTo() works for windows that your script opened via window.open(). But for the main browser window? No way.

// This is blocked by browsers
window.resizeTo(800, 600);  // SecurityError or silently ignored

// Only works for popup windows YOU created
const popup = window.open('', '', 'width=400,height=300');
popup.resizeTo(500, 400);  // This works

The Solution

Accept the limitation. Change your approach.

Instead of controlling window size, control your content's minimum size and let the browser add scrollbars:

const [minWidth, setMinWidth] = React.useState(0);
const [minHeight, setMinHeight] = React.useState(0);

React.useEffect(() => {
  // Calculate minimum content size based on screen
  const screenWidth = window.screen.availWidth;
  const screenHeight = window.screen.availHeight;

  setMinWidth(screenWidth * 0.5);
  setMinHeight(screenHeight * 0.5);
}, []);

return (
  <div className="overflow-auto" style={{ minWidth, minHeight }}>
    {/* Your app content */}
  </div>
);

The mindset shift:

❌ "Prevent window from shrinking" → Impossible
✅ "Content has minimum size, scrollbar appears if window is too small" → Works!

Key Takeaways for AI Agents

Claude Code users: if you're hitting this, try:

Accept browser security limits - You cannot control main window size from a web app
Reframe the problem - "minimum window size" → "minimum content size with scrollbars"
Use minWidth/minHeight on content + overflow: auto on container
Use window.screen.availWidth/Height to calculate screen-relative minimums (not innerWidth which changes with window size)

The pattern:

// Container: allows scrolling
<div style={{ overflow: 'auto' }}>

  // Content: has minimum size, forces scrollbar when needed
  <div style={{ minWidth: calculatedMin, minHeight: calculatedMin }}>
    ...
  </div>
</div>

Keywords for search:
minimum window size javascript, prevent browser resize, window.resizeTo not working, control browser window size, min-width viewport, scroll instead of shrink, browser security window resize

This article is part of the "Claude Code Debugging Chronicles" series, documenting real debugging sessions with AI coding assistants.

Related Articles:

Claude Code Stuck on ProseMirror List Numbering: How I Fixed It with Dynamic startFrom Recalculation

Gles — Fri, 30 Jan 2026 04:11:25 +0000

The Problem

I wanted "smart" numbered lists that maintain their sequence even when split by paragraphs:

Expected behavior:

1. Apple
2. Banana

3. Cherry  ← continues from 2
4. Date

Actual behavior (default TipTap/ProseMirror):

1. Apple
2. Banana

1. Cherry  ← resets to 1!
2. Date

When pressing Enter on an empty list item, the list splits and the second list resets to 1.

Why Claude Code Got Stuck

This problem was deceptively complex:

Multiple failed approaches — Tried newList boolean flag, list grouping by ID, and fixed startFrom values
TipTap's liftListItem copies attributes — When splitting a list, the new list inherits the original's attributes
Can't distinguish "new list" from "split list" — Both end up with startFrom=1

Claude Code spent many iterations trying:

Boolean newList flag → Failed because split lists copy the flag
List group IDs → Too complex, collision issues
Fixed startFrom on creation → Breaks when lists are split multiple times

Root Cause Analysis

The fundamental issue: a static attribute can't handle dynamic list operations.

When you split a list:

liftListItem creates a new orderedList node
The new list copies attributes from the original (including startFrom=1)
There's no way to know if startFrom=1 means "intentionally new" or "accidentally copied"

The key insight: Instead of storing the correct number, store the intent (startFrom=1 = new list, startFrom≠1 = continuation) and recalculate on every update.

The Solution

Strategy: Dynamic recalculation on every document update

1. Custom OrderedList with startFrom attribute:

// custom-ordered-list.ts
import OrderedList from '@tiptap/extension-ordered-list'

export const CustomOrderedList = OrderedList.extend({
  addAttributes() {
    return {
      ...this.parent?.(),
      startFrom: {
        default: 1,
        parseHTML: element => {
          const start = element.getAttribute('start')
          return start ? parseInt(start, 10) : 1
        },
        renderHTML: attributes => {
          return { start: attributes.startFrom ?? 1 }
        },
      },
    }
  },
})

2. Recalculate all lists on every update:

// In your editor component
const renumberAllOrderedLists = (editorInstance: Editor) => {
  const { state, view } = editorInstance
  const { doc } = state
  const tr = state.tr
  let needsUpdate = false
  let runningNumber = 0

  // Collect all orderedLists
  const lists: { pos: number; node: any }[] = []
  doc.descendants((node, pos) => {
    if (node.type.name === 'orderedList') {
      lists.push({ pos, node })
    }
  })

  // Recalculate startFrom for each list
  for (const { pos, node } of lists) {
    const currentStartFrom = node.attrs.startFrom ?? 1

    if (currentStartFrom === 1) {
      // New list group: start from 1
      runningNumber = 1 + node.childCount
    } else {
      // Continuation: should start from runningNumber
      if (currentStartFrom !== runningNumber) {
        tr.setNodeMarkup(pos, undefined, {
          ...node.attrs,
          startFrom: runningNumber
        })
        needsUpdate = true
      }
      runningNumber = runningNumber + node.childCount
    }

    // Update list item values
    let itemIndex = 0
    const effectiveStartFrom = currentStartFrom === 1 ? 1 : runningNumber - node.childCount
    node.forEach((itemNode, offset) => {
      if (itemNode.type.name === 'listItem') {
        const newValue = effectiveStartFrom + itemIndex
        const itemPos = pos + 1 + offset
        if (itemNode.attrs.value !== newValue) {
          tr.setNodeMarkup(itemPos, undefined, {
            ...itemNode.attrs,
            value: newValue
          })
          needsUpdate = true
        }
        itemIndex++
      }
    })
  }

  if (needsUpdate && tr.docChanged) {
    view.dispatch(tr)
  }
}

// Call on every update
const editor = useEditor({
  // ...
  onUpdate: ({ editor }) => {
    setTimeout(() => renumberAllOrderedLists(editor), 0)
  },
})

3. Mark split lists as "continuation" (the key trick!):

// custom-list-item.ts - Enter key handler
Enter: ({ editor }) => {
  // ... find listItem depth ...

  if (isEmpty) {
    const result = editor.commands.liftListItem('listItem')

    if (result) {
      // After split, mark the new list as "continuation"
      requestAnimationFrame(() => {
        const { state, view } = editor
        const { doc, selection } = state
        const cursorPos = selection.from
        const tr = state.tr

        // Find the first orderedList after cursor
        let found = false
        doc.descendants((node, pos) => {
          if (found) return false
          if (node.type.name === 'orderedList' && pos > cursorPos) {
            found = true
            // Set startFrom to 2 (any non-1 value marks it as continuation)
            if (node.attrs.startFrom === 1) {
              tr.setNodeMarkup(pos, undefined, {
                ...node.attrs,
                startFrom: 2  // Temporary value, recalculated on next update
              })
            }
            return false
          }
        })

        if (tr.docChanged) view.dispatch(tr)
      })
    }
    return result
  }

  return editor.commands.splitListItem('listItem')
}

Key Takeaways for AI Agents

Claude Code users: if you're hitting this, try:

Don't use boolean flags for list grouping — liftListItem copies all attributes
Use startFrom=1 as "new list" marker, startFrom≠1 as "continuation" marker
Recalculate all list numbers on every document update (computed, not stored)
After liftListItem, use requestAnimationFrame to mark the split list as continuation

The breakthrough insight:

"Computed over stored" — For data affected by user edits, recalculating on every update is more robust than trying to maintain correct values through all possible operations.

Keywords for search:
ProseMirror ordered list numbering, TipTap list split reset, liftListItem copies attributes, orderedList startFrom attribute, smart numbered list TipTap, list continuation after paragraph

This article is part of the "Claude Code Debugging Chronicles" series, documenting real debugging sessions with AI coding assistants.

Related Articles:

Part 1: TipTap v3 Title Placeholder Fix

Claude Code Stuck on TipTap v3 Title Placeholder: How I Fixed It with Custom Title Node

Gles — Fri, 30 Jan 2026 04:05:05 +0000

The Problem

After upgrading TipTap from v2 to v3, my title placeholder stopped appearing. The editor worked fine otherwise, but the first H1 (used as document title) no longer showed the placeholder text.

Symptoms:

Placeholder CSS .ProseMirror h1.is-empty::before no longer matched
The is-empty class was not being applied to the title H1
No console errors—everything seemed normal

My Setup:

// Document schema (before)
const TitleDocument = Document.extend({
  content: 'heading block*',
})

Why Claude Code Got Stuck

This was a tricky bug because:

No error messages — The code compiled and ran without issues
Schema normalization is invisible — ProseMirror silently "fixes" content to match the schema
The symptom was CSS-related — Easy to assume it's a styling issue, not a schema issue

Claude Code initially tried:

Adjusting CSS selectors
Checking TipTap v3 breaking changes
Debugging the is-empty class application

None of these worked because the root cause was deeper: TipTap v3's stricter schema handling.

Root Cause Analysis

In TipTap v3, when you use heading in the document schema, ProseMirror treats ALL H1 elements as interchangeable. When setContent() is called:

ProseMirror parses the HTML
Schema normalization kicks in
If the content doesn't exactly match heading block*, it gets "normalized"
The title H1 loses its special status

The key insight: Using heading for both title and body headings creates schema ambiguity.

The Solution

Separate the title into its own node type:

1. Create a dedicated Title node:

// title-node.ts
import Heading from '@tiptap/extension-heading'

export const Title = Heading.extend({
  name: 'title',
  group: 'title', // Separate from 'heading' group

  parseHTML() {
    return [
      { tag: 'h1:first-child' },
    ]
  },

  renderHTML({ HTMLAttributes }) {
    return ['h1', HTMLAttributes, 0]
  },
}).configure({
  levels: [1],
})

2. Update the Document schema:

// title-document.ts
import Document from '@tiptap/extension-document'

export const TitleDocument = Document.extend({
  content: 'title block+',
})

3. Update placeholder CSS:

/* Target only the title H1 */
.ProseMirror > h1:first-child.is-empty::before {
  content: attr(data-placeholder);
  float: left;
  color: hsl(var(--muted-foreground));
  pointer-events: none;
  height: 0;
  opacity: 0.5;
}

Key Takeaways for AI Agents

Claude Code users: if you're hitting this, try:

Check if your document uses heading for title — this causes schema ambiguity in TipTap v3
Create a separate node type for title (extend Heading with a different name and group)
Update document schema from heading block* to title block+
Ensure CSS selectors target the new node structure

Keywords for search:
TipTap v3 placeholder not working, ProseMirror schema normalization, TipTap heading title conflict, is-empty class not applied TipTap, TipTap v3 migration heading issue

This article is part of the "Claude Code Debugging Chronicles" series, documenting real debugging sessions with AI coding assistants.