@uniweb/semantic-parser 1.2.3 → 1.3.0

package/AGENTS.md

@@ -12,17 +12,14 @@ This is a semantic parser for ProseMirror/TipTap content structures. It transfor
 # Run all tests
 npm test
 
-# Run tests with JSON report output
-npm run test-report
-
 # Run a specific test file
-npx jest tests/parser.test.js
+npx vitest run tests/parser.test.js
 
 # Run tests in watch mode
-npx jest --watch
+npx vitest
 
 # Run a specific test by name
-npx jest -t "handles simple document structure"
+npx vitest run -t "handles simple document structure"
 ```
 
 ## Architecture
@@ -33,9 +30,7 @@ The parser processes content through three distinct stages, each building on the
 
 1. **Sequence Processing** (`src/processors/sequence.js`): Flattens the ProseMirror document tree into a linear sequence of semantic elements (headings, paragraphs, images, lists, etc.)
 
-2. **Groups Processing** (`src/processors/groups.js`): Transforms the sequence into semantic groups with identified main content and items. Supports two grouping modes:
-   - Heading-based grouping (default)
-   - Divider-based grouping (when horizontal rules are present)
+2. **Groups Processing** (`src/processors/groups.js`): Transforms the sequence into semantic groups with identified main content and items. Headings split groups via the staircase headline rule; a horizontal rule explicitly closes the current group — the two compose, there are no separate modes.
 
 3. **ByType Processing** (`src/processors/byType.js`): Organizes elements by type with positional context, enabling type-specific queries
 
@@ -47,8 +42,7 @@ const result = parseContent(doc);
 // {
 //   raw: doc,        // Original ProseMirror document
 //   sequence: [...], // Flat sequence of elements
-//   groups: {...},   // Semantic groups with main/items
-//   byType: {...}    // Elements organized by type
+//   title, pretitle, subtitle, paragraphs, items, ...  // flat content fields
 // }
 ```
 
@@ -59,8 +53,8 @@ The parser returns a flat content structure:
 ```js
 {
   title: '',       // Main heading
-  pretitle: '',    // Heading before main title
-  subtitle: '',    // Heading after main title
+  pretitle: '',    // `#>` label line(s) or smaller headings above the title
+  subtitle: '',    // Line(s) one step below the title (string or array)
   paragraphs: [],
   links: [],       // All link-like entities (including buttons, documents)
   images: [],
@@ -70,7 +64,7 @@ The parser returns a flat content structure:
   quotes: [],
   snippets: [],    // Fenced code — [{ language, code }]
   data: {},        // Structured data (tagged data blocks, forms, cards)
-  headings: [],    // Headings after subtitle, in document order
+  headings: [],    // Only from nested content (quote/list bodies)
   items: [],       // Child content groups (same structure recursively)
 }
 ```
@@ -106,10 +100,10 @@ FormBlock without a `schemaId` still lands at `data.form`.
 
 ### Main Content Identification
 
-The `identifyMainContent()` function (src/processors/groups.js:282) determines if the first group should be treated as main content:
+The `identifyMainContent()` function in `src/processors/groups.js` determines if the first group should be treated as main content:
 - Single group is always main content
-- First group must have lower heading level than second group
-- Divider mode affects main content identification
+- First group must have a more important (lower) heading level than the second group
+- A first group with no heading at all (body before the first heading) is also promoted to main
 
 ### Special Element Detection
 
@@ -165,14 +159,15 @@ Lists maintain hierarchy through nested structure. The `processListItems()` func
 
 ## Content Writing Conventions
 
-Key patterns:
+Key patterns — the staircase rule (each heading relates to the one before it):
 
-- **Pretitle Pattern**: Any heading followed by a more important heading (e.g., H3→H1, H2→H1, H6→H5, etc.)
-- **Banner Pattern**: Image (with banner role or followed by heading) at start of first group
-- **Divider Mode**: Presence of any `horizontalRule` switches entire document to divider-based grouping
-- **Heading Groups**: Consecutive headings are consumed together only when each is exactly one level deeper (H1→H2 yes, H1→H3 no — skipped levels start a new group)
-- **Main Content**: First group is main if it's the only group OR has lower heading level than second group
-- **Body Headings**: Headings after the title and subtitle slots are collected in `body.headings` in document order
+- **Pretitle**: `#>` label lines (headings with `role: "pretitle"`), and smaller headings stacked directly above a more important one (H3→H1, H6→H5, …). String or array.
+- **Subtitle**: one step below the title, directly adjacent — and each further one-step descent (or same-size repeat) is another subtitle line. String or array.
+- **Items**: a heading two or more steps below the previous one, a step back up, or any heading after body content starts a new group.
+- **Banner Pattern**: an image (with banner role or followed by a heading) at the start of the first group stays with the headline.
+- **Dividers**: a `horizontalRule` explicitly closes the current group; it composes with the heading rules rather than replacing them.
+- **Main Content**: the first group is main if it's the only group, has a more important heading level than the second group, or has no heading at all.
+- **Body Headings**: `body.headings` fills only from nested content (blockquote children, list items) — a section's headline never spills there.
 
 ## Testing Structure
 
@@ -189,4 +184,4 @@ Tests are organized by processor:
 - The parser never modifies the original ProseMirror document
 - Text content can include inline HTML for formatting (bold → `<strong>`, italic → `<em>`, links → `<a>`)
 - Context information in byType includes position, previous/next elements, and nearest heading
-- Group splitting logic differs significantly between heading mode and divider mode
+- Headline slots and group boundaries come from one walk (`readStack`), so the two cannot disagree

package/README.md

@@ -64,10 +64,11 @@ Main content fields are at the top level. The `items` array contains additional
 
 ```js
 result = {
-  // Header fields (from headings)
-  pretitle: "",             // Heading before main title
+  // Header fields (from headings) — each is a string, or an array when the
+  // part spans several lines
+  pretitle: "",             // `#>` label line(s), or smaller headings above the title
   title: "Welcome",         // Main heading
-  subtitle: "",             // Heading after main title
+  subtitle: "",             // Line(s) one step below the title
 
   // Body fields
   paragraphs: ["Get started today."],
@@ -80,7 +81,7 @@ result = {
   insets: [],               // Inline @Component references — { refId }
   snippets: [],             // Fenced code blocks — { language, code }
   data: {},                 // Structured data (tagged data blocks, forms, cards)
-  headings: [],             // Headings after subtitle, in document order
+  headings: [],             // Only from nested content (quote/list bodies)
 
   // Additional content groups (from headings after content)
   // Each item has the SAME flat structure as the top level — title,
@@ -108,7 +109,7 @@ const content = parseContent(doc);
 
 const title = content.title;
 const description = content.paragraphs.join(" ");
-const image = content.banner?.url;
+const image = content.images[0]?.src;
 ```
 
 ### Processing Content Sections
@@ -155,13 +156,13 @@ The parser interprets heading levels **relatively**, not absolutely. There is no
 
 A new group is started whenever a heading appears after non-heading content (paragraphs, images, links, lists, etc.). A horizontal rule (`---`) explicitly closes the current group.
 
-When a group begins with one or more headings, the parser consumes a contiguous **heading block** following these rules:
+When a group begins with headings, the parser reads one **headline stack** with the staircase rule — each heading relates to the one before it:
 
-1. **Adjacent deeper** — the next heading is exactly one level deeper (e.g., H1→H2, H2→H3). It becomes the `subtitle`. Skipping levels (H1→H3) breaks the block; the deeper heading starts a new group as an item.
-2. **Pretitle promotion** — if the very first heading is followed by a *more important* (lower-numbered) heading, the first one becomes `pretitle` and the next becomes `title`. This only applies at the start of the block.
-3. **Same-level continuation** — consecutive headings at the same level merge into an array (multi-line title or subtitle). This stops once a deeper level has been reached: after going deeper, a same-level heading starts a new group instead of merging.
+1. **Same size** — another line of the same part: a split title, or another subtitle line. Merged slots become arrays.
+2. **One step smaller** — the next line of the headline: the subtitle first, then further subtitle lines (`subtitle` is a string for one line, an array for several — a three-line header like name / role / affiliation fits in one headline).
+3. **Two or more steps smaller, or a step back up** — the stack ends; the rest of the run starts a new group (an item), read the same way.
 
-Anything else (going back up after going deeper, or any other gap) breaks the block.
+Before the title, `#>` label lines (headings carrying `role: "pretitle"`) and smaller headings ascending to a more important one all join the `pretitle`. A label line anywhere names the block it sits in; a label with no following heading labels an untitled block.
 
 ### Main content vs items
 
@@ -176,14 +177,10 @@ This is the mechanism that creates repeating content groups (cards, features, FA
 
 ### Pretitle detection
 
-A heading followed by a more important heading at the start of a group is detected as `pretitle`:
+Two spellings fill the `pretitle` slot:
 
-- H3 before H1 → pretitle
-- H2 before H1 → pretitle
-- H6 before H5 → pretitle
-- H4 before H2 → pretitle
-
-Pretitle is detected only between the first two headings of a heading block (before the title is set).
+- **A `#>` label line** — a heading with `role: "pretitle"`. It names the block that starts next, at any depth, with no level arithmetic; the hash count is carried for round-tripping and means nothing.
+- **Position** — headings followed by a more important heading at the start of a group (H3 before H1, H6 before H5, …). Stacked smaller headings all join: `#### / ### / # Title` yields a two-line pretitle.
 
 ### Banner image
 
@@ -193,7 +190,7 @@ If a section's very first element is an image (or an image followed immediately
 
 A horizontal rule (`---`) explicitly closes the current group and starts a new one. Dividers compose with the heading rules above — they don't replace them — and are useful in three situations:
 
-- **Resolving ambiguity.** When the heading rules would group content one way but you want it grouped another way. Most common case: forcing items without a subtitle. Without a divider, `# Our Stats` followed by `## 15,000+` makes `## 15,000+` the subtitle (one level deeper). Adding `---` between them closes the title group so `## 15,000+` becomes `items[0].title` instead.
+- **Resolving ambiguity.** When the heading rules would group content one way but you want it grouped another way. Most common case: forcing items without a subtitle. Without a divider, `# Our Stats` followed by `## 15,000+` makes `## 15,000+` the subtitle (one step down). Adding `---` between them closes the headline so `## 15,000+` becomes `items[0].title` instead — as does writing the entries two steps down (`### 15,000+`), the divider-free spelling.
 - **Forcing splits within same-level runs.** Same-level headings that would otherwise merge into a multi-line title/subtitle become separate groups when separated by a divider.
 - **Personal preference.** Even when the heading rules would already produce the desired structure, authors can use `---` as an explicit visual separator between groups. It never changes a structure that's already correct — it just makes the boundary obvious in the markdown source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/semantic-parser",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Semantic parser for ProseMirror/TipTap content structures",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,6 +1,7 @@
 import { processSequence, resolveAssetUrl, ASSET_SLOTS } from "./processors/sequence.js";
 import { processGroups } from "./processors/groups.js";
 import { buildDoc } from "./builders/doc.js";
+import { lintContent } from "./lint.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
@@ -50,4 +51,7 @@ function parseContent(doc, options = {}) {
 // parse (the editor, a kit component) reaches THIS implementation rather than
 // writing a second one. A duplicated selector is this repo's most-repeated
 // defect; one exported function is the cheapest guard against it.
-export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS };
+// `lintContent` diagnoses grouping near-misses (see src/lint.js). It never
+// affects a parse — parsing stays deterministic; the judgment lives here so
+// the CLI, the dev server, and an editor surface the same findings.
+export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS, lintContent };

package/src/lint.js

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Content lint — diagnose grouping near-misses.
+ *
+ * The grouping rules are deterministic, but a handful of authored shapes are
+ * genuinely ambiguous: the same markdown can mean two things, and whichever
+ * reading the parser takes, an author who meant the other gets a silently
+ * reshaped section. Parsing never guesses; THIS module is where the judgment
+ * lives — it looks at a document the way a reviewer would and names the shapes
+ * that usually indicate a misfire, without ever changing the parse.
+ *
+ * Severities:
+ * - "warning" — the shape almost always means a misfire (measured across the
+ *   intent corpus and real site content; see tests/lint.test.js).
+ * - "hint" — the shape is ambiguous by construction. The message says what the
+ *   parser did and how to spell the other meaning; correct content simply
+ *   ignores it. Hints trade a known false-fire rate for catching the most
+ *   common naive spellings — the corpus records both sides.
+ *
+ * Environment-free on purpose: pure functions over the document, no I/O, so
+ * the CLI, the dev server, and an editor can all surface the same findings.
+ */
+
+import { processSequence } from "./processors/sequence.js";
+import { splitBySlices, readStack } from "./processors/groups.js";
+
+const stripTags = (s) => String(s ?? "").replace(/<[^>]+>/g, "");
+const excerpt = (s) => {
+    const t = stripTags(s).trim();
+    return t.length > 40 ? t.slice(0, 39) + "…" : t;
+};
+
+/**
+ * Lint a ProseMirror document for grouping near-misses.
+ *
+ * @param {Object} doc ProseMirror document
+ * @param {Object} [options] The same options a `parseContent` call would use —
+ *   findings must describe the parse the consumer actually gets.
+ * @returns {Array<{rule: string, severity: "warning"|"hint", message: string}>}
+ */
+export function lintContent(doc, options = {}) {
+    const sequence = processSequence(doc, options);
+    const groups = splitBySlices(sequence, options);
+    const stacks = groups.map((g) =>
+        g[0]?.type === "heading" ? readStack(g, 0, options) : null
+    );
+    const findings = [];
+
+    // ---- label-as-text: a short bare line above the first heading ----------
+    // `**New**` above `# Title` turns the section into an untitled main with
+    // the title demoted to items[0] — the most destructive naive spelling.
+    // Real intro text is left alone: it runs longer and ends like a sentence.
+    if (stacks[0] === null && stacks.length > 1) {
+        const first = groups[0];
+        const laterTitled = stacks.some((s) => s && s.title.length);
+        if (first.length === 1 && first[0].type === "paragraph" && laterTitled) {
+            const text = stripTags(first[0].text).trim();
+            const words = text.split(/\s+/).filter(Boolean);
+            if (words.length > 0 && words.length <= 6 && !/[.!?]$/.test(text)) {
+                findings.push({
+                    rule: "label-as-text",
+                    severity: "warning",
+                    message:
+                        `"${excerpt(text)}" sits above the first heading, so the section became an ` +
+                        `untitled body and the heading below it starts the items. If that line is ` +
+                        `a label for the title, write it as a label line: #> ${text}`,
+                });
+            }
+        }
+    }
+
+    // ---- per-group checks against the groups that follow -------------------
+    for (let i = 0; i < stacks.length; i++) {
+        const stack = stacks[i];
+        if (!stack) continue;
+
+        const laterTitleLevels = new Set(
+            stacks
+                .slice(i + 1)
+                .filter(Boolean)
+                .map((s) => s.title[0]?.level)
+                .filter((l) => l != null)
+        );
+
+        const subLevels = stack.sub.map((el) => el.level);
+
+        // entry-joined-headline: the headline absorbed two or more lines and
+        // at least one sits at the same size as a later block's title. Every
+        // measured real-world instance of this shape was a misfire (the first
+        // stat, feature, testimonial, or job folded into the headline).
+        if (
+            stack.sub.length >= 2 &&
+            subLevels.some((l) => laterTitleLevels.has(l))
+        ) {
+            const absorbed = stack.sub[stack.sub.length - 1];
+            findings.push({
+                rule: "entry-joined-headline",
+                severity: "warning",
+                message:
+                    `The headline under "${excerpt(stack.title[0]?.text)}" absorbed ` +
+                    `${stack.sub.length} lines, ending with "${excerpt(absorbed.text)}", while ` +
+                    `later headings of the same size start items. If those lines are entries, ` +
+                    `step them two sizes below the headline, or put a lead paragraph (or ---) ` +
+                    `after it.`,
+            });
+            continue; // one finding per stack — the hint below would repeat it
+        }
+
+        // first-entry-or-subtitle: a single line one step under the title,
+        // with same-size headings starting items later. Ambiguous by
+        // construction — a platform hero reads exactly like a question list —
+        // so this only states what happened and how to spell the other intent.
+        if (stack.sub.length === 1 && laterTitleLevels.has(subLevels[0])) {
+            findings.push({
+                rule: "first-entry-or-subtitle",
+                severity: "hint",
+                message:
+                    `"${excerpt(stack.sub[0].text)}" joined the headline as the subtitle, while ` +
+                    `later headings of the same size start items. If it is the subtitle, ignore ` +
+                    `this. If it was meant as the first entry, step the entries two sizes below ` +
+                    `the headline or put a lead paragraph before the first one.`,
+            });
+        }
+
+        // merged-title-run: three or more bodiless same-size headings read as
+        // one multi-line title. Two lines is the classic split headline; three
+        // or more usually means a bare list (names, logos, tags).
+        if (stack.title.length >= 3) {
+            findings.push({
+                rule: "merged-title-run",
+                severity: "hint",
+                message:
+                    `${stack.title.length} same-size headings merged into one multi-line title ` +
+                    `starting "${excerpt(stack.title[0]?.text)}". If these are separate items, ` +
+                    `give each one body content, separate them with ---, or write them as a list.`,
+            });
+        }
+    }
+
+    return findings;
+}

package/src/processors/groups.js

@@ -46,8 +46,8 @@ function flattenGroup(group) {
  * render time and at editor time — and nothing derived is ever stored, so a
  * change to a grouping rule retroactively re-reads every document that already
  * exists. Leaking these suppressions into the default path would silently
- * reshape every section body ever authored. `tests/grouping-default-path.test.js`
- * pins the default against that.
+ * reshape every section body ever authored.
+ * `tests/processors/always-items.test.js` pins the default against that.
  *
  * @param {Array} sequence Flat sequence of elements
  * @param {Object} options Parsing options
@@ -79,7 +79,9 @@ function processGroups(sequence, options = {}) {
     const groups = splitBySlices(sequence, options);
 
     // Process each group's structure (still nested internally)
-    const processedGroups = groups.map((group) => processGroupContent(group));
+    const processedGroups = groups.map((group) =>
+        processGroupContent(group, options)
+    );
 
     // Determine main vs items
     let mainGroup = null;
@@ -148,21 +150,23 @@ function splitBySlices(sequence, options = {}) {
             // we do NOT close the group. We let the heading merge with the image.
             const isBannerMerge = i === 1 && isBannerImage(sequence, 0);
 
-            // A new Heading Group starts a new visual block.
+            // A new headline stack starts a new visual block.
             // If we have gathered content in the current group, close it now.
             if (currentGroup.length > 0 && !isBannerMerge) {
                 groups.push(currentGroup);
                 currentGroup = [];
             }
 
-            // Consume the entire semantic heading block (Title + Subtitles)
-            // We reuse your smart readHeadingGroup logic here!
-            const headingBlock = readHeadingGroup(sequence, i, options);
-            currentGroup.push(...headingBlock);
+            // Consume exactly ONE headline stack (pretitle + title + subtitle
+            // lines). A longer contiguous run re-enters here on the next
+            // iteration and opens the next group.
+            const stack = readStack(sequence, i, options);
+            const consumed = Math.max(stack.length, 1);
+            currentGroup.push(...sequence.slice(i, i + consumed));
 
             // Advance the index by the number of headings consumed
-            // (Loop increments i by 1, so we add length - 1)
-            i += headingBlock.length - 1;
+            // (Loop increments i by 1, so we add consumed - 1)
+            i += consumed - 1;
         } else {
             // 3. Handle Content (Body)
             // Paragraphs, images, lists, etc. just append to the current slice.
@@ -179,16 +183,11 @@ function splitBySlices(sequence, options = {}) {
 }
 
 /**
- * Check if this is a pretitle - any heading followed by a more important heading
- * (e.g., H3→H1, H2→H1, H6→H5, etc.)
+ * A `#>` label line — a heading carrying `role: "pretitle"`. It names the
+ * block it opens (or sits in) and never competes for the title slot.
  */
-function isPreTitle(sequence, i) {
-    return (
-        i + 1 < sequence.length &&
-        sequence[i].type === "heading" &&
-        sequence[i + 1].type === "heading" &&
-        sequence[i].level > sequence[i + 1].level // Smaller heading before larger
-    );
+function isLabel(el) {
+    return el?.type === "heading" && el.attrs?.role === "pretitle";
 }
 
 function isBannerImage(sequence, i) {
@@ -200,69 +199,95 @@ function isBannerImage(sequence, i) {
     );
 }
 
-function readHeadingGroup(sequence, startIdx, options = {}) {
-    const elements = [sequence[startIdx]];
-    let hasGoneDeeper = false;
-
-    // Iterate starting from the next element
-    for (let i = startIdx + 1; i < sequence.length; i++) {
-        const element = sequence[i];
-        const previousElement = elements[elements.length - 1];
-
-        if (element.type !== "heading") {
-            break;
-        }
+/**
+ * Read ONE headline stack from a contiguous heading run — the staircase rule:
+ * each heading relates to the one before it. The same size extends the current
+ * part; one step smaller is the next line of the headline (the subtitle, then
+ * further subtitle lines); anything else — two or more steps down, or a step
+ * back up — ends the stack, and the rest of the run starts a new block.
+ *
+ * Before the title: `#>` label lines, and any smaller headings ascending to a
+ * more important one, are the pretitle. A label line anywhere in the stack
+ * also names the block — it never competes for the title.
+ *
+ * `alwaysItems` (a tagged concept block's grouping) suppresses the same-size
+ * continuation: two bodiless same-level headings are two ITEMS, not one
+ * heading split across visual lines. That suppression must happen HERE, at
+ * group formation — no amount of suppressing title promotion downstream can
+ * split a group that was never split. Descents still join: a concept-block
+ * item keeps its subtitle.
+ *
+ * @returns {{ pre: Array, title: Array, sub: Array, length: number }}
+ *   The slot elements and how many sequence elements the stack consumed.
+ */
+function readStack(sequence, startIdx, options = {}) {
+    const pre = [];
+    const title = [];
+    const sub = [];
+    let i = startIdx;
+
+    // Leading `#>` label lines belong to this block's pretitle.
+    while (i < sequence.length && isLabel(sequence[i])) {
+        pre.push(sequence[i]);
+        i++;
+    }
 
-        // Case 1: Adjacent Deeper (Standard Subtitle/Deep Header)
-        // Only group headings that are exactly one level apart.
-        // e.g. H1 -> H2 groups, but H1 -> H3 does not (skipped level
-        // signals a structural tier change, not a title-subtitle pair).
-        if (element.level - previousElement.level === 1) {
-            hasGoneDeeper = true;
-            elements.push(element);
-            continue;
-        }
+    // Ascending positional pretitle: smaller headings stacked directly above
+    // a more important one (e.g. #### / ### / # Title) all join the pretitle.
+    while (
+        i + 1 < sequence.length &&
+        sequence[i].type === "heading" &&
+        sequence[i + 1].type === "heading" &&
+        !isLabel(sequence[i + 1]) &&
+        sequence[i + 1].level < sequence[i].level
+    ) {
+        pre.push(sequence[i]);
+        i++;
+    }
 
-        // Case 2: Pretitle Promotion (Small -> Big)
-        // Only allowed if we haven't gone deep yet (length is 1)
-        // e.g. H2 -> H1
-        if (elements.length === 1 && element.level < previousElement.level) {
-            elements.push(element);
-            continue;
-        }
+    // A label-only stack (labels followed by body, or nothing) is legal: the
+    // block has a pretitle and no title.
+    if (i >= sequence.length || sequence[i].type !== "heading") {
+        return { pre, title, sub, length: i - startIdx };
+    }
 
-        // Case 3: Same Level Continuation (multi-line heading)
-        // Only before going deeper — once a subtitle level is reached,
-        // same-level headings are new sections, not continuations.
-        // e.g. H1 -> H1 → merged into title array
-        // but H1 -> H2 -> H2 → second H2 starts a new group (items)
-        //
-        // Suppression 2 of 2 (`alwaysItems`): in a tagged concept block two
-        // same-level headings are two ITEMS, not one heading split across
-        // visual lines. Merging them is why bodiless headings collapse into a
-        // single group carrying a title ARRAY — and no amount of suppressing
-        // title promotion downstream can split what was never split here, which
-        // is what makes this the second half of a fix that looks like one line.
-        if (
-            element.level === previousElement.level &&
-            !hasGoneDeeper &&
-            !options.alwaysItems
-        ) {
-            elements.push(element);
-            continue;
+    title.push(sequence[i]);
+    let prevLevel = sequence[i].level;
+    let part = title;
+    i++;
+
+    while (i < sequence.length && sequence[i].type === "heading") {
+        const el = sequence[i];
+        if (isLabel(el)) {
+            // A label inside the stack still names this block.
+            pre.push(el);
+            i++;
+        } else if (el.level === prevLevel && !options.alwaysItems) {
+            part.push(el); // another line of the same part
+            i++;
+        } else if (el.level === prevLevel + 1) {
+            sub.push(el); // the next line of the headline, one step down
+            part = sub;
+            prevLevel = el.level;
+            i++;
+        } else {
+            break; // two+ steps down, or back up: a new block starts here
         }
-
-        // Otherwise (New Section — went deeper then back up, or
-        // same-level after going deeper), stop.
-        break;
     }
-    return elements;
+    return { pre, title, sub, length: i - startIdx };
+}
+
+/** Collapse a slot's texts: none → '', one → string, several → array. */
+function flattenSlot(texts) {
+    if (texts.length === 0) return "";
+    if (texts.length === 1) return texts[0];
+    return texts;
 }
 
 /**
  * Process a group's content to identify its structure
  */
-function processGroupContent(elements) {
+function processGroupContent(elements, options = {}) {
     const header = {
         pretitle: "",
         title: "",
@@ -298,46 +323,33 @@ function processGroupContent(elements) {
             metadata,
         };
 
-    // Track last assigned heading slot and level for same-level merging
-    let lastSlot = null;
-    let lastLevel = null;
-
-    for (let i = 0; i < elements.length; i++) {
-        //We shuold only set pretitle once
-        if (isPreTitle(elements, i) && !header.pretitle) {
-            header.pretitle = elements[i].text;
-            i++; // move to known next heading (H1 or h2)
+    // The group's leading heading run is its headline stack: read the slots
+    // with the same staircase rule that decided the group boundary, so the
+    // two walks cannot disagree.
+    let start = 0;
+    if (elements[0]?.type === "heading") {
+        const stack = readStack(elements, 0, options);
+        header.pretitle = flattenSlot(stack.pre.map((el) => el.text));
+        header.title = flattenSlot(stack.title.map((el) => el.text));
+        header.subtitle = flattenSlot(stack.sub.map((el) => el.text));
+        metadata.level = stack.title[0]?.level ?? null;
+        for (const el of [...stack.pre, ...stack.title, ...stack.sub]) {
+            if (el.children && Array.isArray(el.children))
+                processInlineElements(el.children, body);
         }
+        start = Math.max(stack.length, 1);
+    }
 
+    for (let i = start; i < elements.length; i++) {
         const element = elements[i];
 
         if (element.type === "heading") {
+            // Only reachable for nested content (blockquote children, list
+            // items), where headings can follow body inside one element
+            // array — section content is split into groups before this runs.
             if (element.children && Array.isArray(element.children))
                 processInlineElements(element.children, body);
-
-            //We shuold set the group level to the highest one instead of the first one.
-            metadata.level ??= element.level;
-
-            // Same level as last assigned → merge into same slot as array
-            if (lastLevel !== null && element.level === lastLevel && lastSlot) {
-                const current = header[lastSlot];
-                if (Array.isArray(current)) {
-                    current.push(element.text);
-                } else {
-                    header[lastSlot] = [current, element.text];
-                }
-            } else if (!header.title) {
-                header.title = element.text;
-                lastSlot = 'title';
-            } else if (!header.subtitle) {
-                header.subtitle = element.text;
-                lastSlot = 'subtitle';
-            } else {
-                // After subtitle, remaining headings go to body
-                body.headings.push(element.text);
-                lastSlot = null;
-            }
-            lastLevel = element.level;
+            body.headings.push(element.text);
         } else if (element.type === "list") {
             const listItems = element.children;
 
@@ -578,4 +590,8 @@ function processInlineElements(children, body) {
     });
 }
 
-export { processGroups };
+// `splitBySlices` and `readStack` are exported for `lintContent` (src/lint.js),
+// which diagnoses grouping near-misses and must see the SAME walk that decided
+// the groups — a private reimplementation there would drift. They are not part
+// of the package's public API.
+export { processGroups, splitBySlices, readStack };