cascadeMessage docs explain a nested message with the cascade-level selection rule

[dqnykamp]

Summary

packages/docs-nextra/pages/reference/cascadeMessage.mdx explains a <cascadeMessage> nested inside a section with a rule that only governs messages written as direct children of the <cascade>:

A <cascadeMessage> placed inside a still-hidden section serves as the prompt shown in place of that section's body. The cascade chooses the first <cascadeMessage> that follows the last completed child, so authoring one per section lets each section carry its own prompt.

The first sentence is right. The second describes the selection the cascade performs among its own message children (Cascade.js, the search for the next <cascadeMessage> after the last shown child). A message inside a section is not selected that way at all: the section hides its own children, and a <cascadeMessage> is the one child whose rule is inverted, so it shows exactly while its section is held back — independently of every other section.

The difference is visible in the page's own Example 2, which has three boxed sections each carrying a message. As written, the text implies only "Finish Part 1 to unlock Part 2." is shown until Part 1 is done. In fact both "Finish Part 1…" and "Finish Part 2…" are shown from the start, each inside its own box.

That is asserted today by cascade.test.ts's "continuation messages inside sections", which holds a three-section cascade and checks each section's message against numCompleted:

expect(stateVariables[section2cmIdx].stateValues.hidden).eq(numCompleted >= 1);
expect(stateVariables[section3cmIdx].stateValues.hidden).eq(numCompleted >= 2);

At numCompleted === 0 both are false — both messages are on screen. Confirmed on screen as well as in the state.

Suggested change

Keep the first sentence and replace the mechanism in the second: a nested message is shown by its own section for as long as that section is held back, so every held-back section shows its message at once, and each reads as the prompt for its own box. The "first message after the last completed child" rule belongs with the cascade-level messages the page documents elsewhere, where it is correct.

The conclusion the page draws — "authoring one per section lets each section carry its own prompt" — is true and worth keeping; only the reason given for it is wrong.

Notes

Pre-existing and documentation-only. Found while reviewing #1681, which fixes where a held-back step's message is drawn (#1680); deliberately left out of that PR, since it is a docs change unrelated to the two-line layout fix.

🤖 Generated with Claude Code

[dqnykamp]

Traced the history, because the natural reading is that this used to work as the page describes and regressed. It did not: for a <cascadeMessage> nested in a section, showing one per held-back section is the behavior it shipped with, and the page's sentence describes a rule that was written for a different form of the same tag.

Both forms arrived together in #711 (b2dda14d0, "updates to <cascade> component"), which is also where the tag itself arrived, as <continuationMessage>; #691 (a525d3b8e), the original <cascade>, had no message concept at all. #711 added two separate rules:

• A message that is a direct child of the <cascade> — Cascade.js finds the next <cascadeMessage> after the last shown child and hides all the others. One message on screen at a time. This is the rule the page's sentence states.
• A message nested inside a section — SectioningComponent's childrenToHide inverts for this one component type: it is hidden exactly when the section's content is shown. Every held-back section therefore shows its own, independently of the others. No selection among them is performed anywhere.

The nested behavior was pinned by a test in that same PR, cascade.test.ts "continuation messages inside sections", whose assertions are unchanged since:

expect(stateVariables[section2cmIdx].stateValues.hidden).eq(numCompleted >= 1);
expect(stateVariables[section3cmIdx].stateValues.hidden).eq(numCompleted >= 2);

At numCompleted === 0 both are false, i.e. both messages on screen. So there is no commit that changed this; the two rules have differed since the day nested messages existed.

That means this issue is a choice rather than a defect report, and it is worth deciding before editing the page:

1. The page is wrong. Restate the nested rule as "each held-back section shows its own message", keeping the conclusion the page already draws (one per section lets each carry its own prompt), and leave the "next message after the last completed child" rule where it belongs, with the cascade's own message children.
2. The behavior is wrong. Make a nested message show only while its section is the next one — matching the cascade-level rule, so the two forms read alike and only ever one prompt is on screen. Cascade.childrenToHide already builds the held-back sections in order, so the first of them is the "next" one; exposing that and gating the inversion on it is a small change, but it reverses an asserted behavior, so the test above changes with it.

🤖 Generated with Claude Code