@uniweb/semantic-parser 1.2.2 → 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.2",
+  "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 } from "./processors/sequence.js";
+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
@@ -46,4 +47,11 @@ function parseContent(doc, options = {}) {
     };
 }
 
-export { parseContent, buildDoc };
+// `resolveAssetUrl` is exported so a consumer that needs an asset URL outside a
+// 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.
+// `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 };

package/src/processors/sequence.js

@@ -106,7 +106,7 @@ function createSequenceElement(node, options = {}) {
     const attrs = node.attrs;
     const content = node.content;
 
-    const linkVal = isLink(node);
+    const linkVal = isLink(node, options);
 
     if (linkVal) {
         return {
@@ -121,7 +121,7 @@ function createSequenceElement(node, options = {}) {
         return multipleLinks; // Returns array of link elements
     }
 
-    const styledLink = isStyledLink(node);
+    const styledLink = isStyledLink(node, options);
 
     if (styledLink) return styledLink;
 
@@ -131,7 +131,7 @@ function createSequenceElement(node, options = {}) {
                 type: "heading",
                 level: node.attrs.level,
                 text: getTextContent(content, options),
-                children: processInlineElements(content),
+                children: processInlineElements(content, options),
                 attrs,
             };
 
@@ -141,16 +141,14 @@ function createSequenceElement(node, options = {}) {
             return {
                 type: "paragraph",
                 text: textContent,
-                children: processInlineElements(content),
+                children: processInlineElements(content, options),
                 attrs,
             };
         }
         case "blockquote":
             return {
                 type: "blockquote",
-                children: processSequence({
-                    content,
-                }),
+                children: processSequence({ content }, options),
                 attrs,
             };
 
@@ -164,7 +162,7 @@ function createSequenceElement(node, options = {}) {
                 type: "inset_block",
                 component,
                 params,
-                children: processSequence({ content }),
+                children: processSequence({ content }, options),
             };
         }
 
@@ -178,9 +176,11 @@ function createSequenceElement(node, options = {}) {
             // put content-reader inside the runtime. The reader already built
             // this node; the job here is only to WALK it.
             //
-            // `options` rides along, unlike the `inset_block` and `blockquote`
-            // cases above, so nested content is sequenced under the same
-            // options as its parent.
+            // `options` rides along so nested content is sequenced under the
+            // same options as its parent. (`inset_block` and `blockquote` used
+            // to drop it and now do the same — harmless while nothing here read
+            // `options`, but an asset inside a blockquote would have lost its
+            // resolution pattern once one did.)
             return {
                 type: "concept_block",
                 tag: attrs?.tag,
@@ -242,7 +242,7 @@ function createSequenceElement(node, options = {}) {
         case "ImageBlock":
             return {
                 type: "image",
-                attrs: parseImgBlock(attrs),
+                attrs: parseImgBlock(attrs, options),
             };
         case "image":
             // `role` decides which content array this lands in — the contract
@@ -260,7 +260,7 @@ function createSequenceElement(node, options = {}) {
             if (attrs?.role === "video") {
                 return {
                     type: "video",
-                    attrs: parseMarkdownVideo(attrs),
+                    attrs: parseMarkdownVideo(attrs, options),
                 };
             }
             // Standard ProseMirror image node - resolve attrs the same way as
@@ -269,12 +269,12 @@ function createSequenceElement(node, options = {}) {
             // wouldn't be populated and components render an empty slot.
             return {
                 type: "image",
-                attrs: parseImgBlock(attrs || {}),
+                attrs: parseImgBlock(attrs || {}, options),
             };
         case "Video":
             return {
                 type: "video",
-                attrs: parseVideoBlock(attrs),
+                attrs: parseVideoBlock(attrs, options),
             };
         case "bulletList":
         case "orderedList": {
@@ -391,7 +391,7 @@ function createSequenceElement(node, options = {}) {
             return {
                 type: "button",
                 text: textContent,
-                children: processInlineElements(content),
+                children: processInlineElements(content, options),
                 attrs,
             };
         }
@@ -628,7 +628,7 @@ function renderInlineNode(curr, iconOrdinals) {
         }, "");
 }
 
-function processInlineElements(content) {
+function processInlineElements(content, options = {}) {
     if (!content) return [];
 
     const items = [];
@@ -654,8 +654,8 @@ function processInlineElements(content) {
             items.push({
                 type: isVideo ? "video" : "image",
                 attrs: isVideo
-                    ? parseMarkdownVideo(item.attrs)
-                    : parseImgBlock(item.attrs || {}),
+                    ? parseMarkdownVideo(item.attrs, options)
+                    : parseImgBlock(item.attrs || {}, options),
             });
         } else if (item.type === "math-inline" || item.type === "math_inline") {
             items.push(item);
@@ -687,6 +687,99 @@ function processInlineElements(content) {
     return items;
 }
 
+/**
+ * Resolve a STORE-HELD asset (`assetId` + `assetExt`) through the host's
+ * URL pattern — the current mechanism, and the one to reach for.
+ *
+ * The host declares `config.assets.url` on the published payload; the runtime
+ * hands it here as `options.assets.url`. We substitute `{id}` and `{ext}` and
+ * do nothing else: the pattern names a host and carries the store's whole path
+ * layout, so a framework package never composes a serve location or guesses an
+ * origin — a host may move its assets without a framework release.
+ *
+ * ⛔ Three ways this returns '' — "unresolved", never a guess:
+ *   - **no pattern** (the host declared none) — absent ⇒ absent
+ *   - **an unknown placeholder** — never emit a half-substituted URL
+ *   - **`{ext}` with no `assetExt`** — `base.` is a broken URL that reads like
+ *     a typo rather than a missing field
+ *
+ * Callers treat '' as "fall through to the next reference form", which is what
+ * makes an id-bearing node safe to write before any deployment emits a pattern.
+ *
+ * @param {string} assetId  - the store's opaque id (backend mints a sha256)
+ * @param {string} assetExt - the extension, minted separately (never derived
+ *                            from the id, which carries no extension)
+ * @param {string} pattern - `config.assets.url`, e.g. `https://cdn/x/{id}/base.{ext}`
+ * @returns {string} the resolved URL, or '' when it cannot be resolved
+ */
+/**
+ * The asset-bearing slots on a media node — the ONE definition, exported so no
+ * consumer keeps its own.
+ *
+ * ⭐ A node carries more than one asset reference. An image has `src`; a video
+ * adds a `poster`; a document embed adds a `preview`. Identity therefore cannot
+ * be a single pair of attrs — it has to name WHICH reference it identifies, or a
+ * producer cannot stamp a poster without inventing vocabulary.
+ *
+ * The identity attrs are **flat and declared**, not a nested `assets: {…}` map,
+ * and that is deliberate: a nested map puts identity inside a value the schema
+ * sweep cannot see, which is exactly the class of defect that makes a reference
+ * buried in an opaque field unenumerable and un-re-pointable. Flat attrs stay
+ * visible to `getBaseSchema()`, to the parity sweep, and to anything generating
+ * an adapter from the declared schema.
+ *
+ * `assetId`/`assetExt` are unprefixed because `src` is the PRIMARY reference —
+ * the one every fallback path already resolves to. The convention is: unprefixed
+ * identifies the primary; a prefix names the attr it belongs to.
+ *
+ * `url` rides in the primary slot because the editor's `ImageBlock` uses it where
+ * markdown's `image` uses `src`; both mean the same reference.
+ */
+export const ASSET_SLOTS = [
+    { urls: ["src", "url"], id: "assetId", ext: "assetExt" },
+    { urls: ["poster"], id: "posterAssetId", ext: "posterAssetExt" },
+    { urls: ["preview"], id: "previewAssetId", ext: "previewAssetExt" },
+];
+
+function resolveAssetUrl(assetId, assetExt, pattern) {
+    if (!assetId || typeof assetId !== "string") return "";
+    if (!pattern || typeof pattern !== "string") return "";
+    let resolvable = true;
+    const url = pattern.replace(/\{(\w+)\}/g, (match, name) => {
+        if (name === "id") return assetId;
+        if (name === "ext" && assetExt) return assetExt;
+        resolvable = false;
+        return match;
+    });
+    return resolvable ? url : "";
+}
+
+/** `resolveAssetUrl` against a node's attrs + the parse options, for one slot. */
+function assetUrlFromAttrs(attrs, options, slot = ASSET_SLOTS[0]) {
+    return resolveAssetUrl(attrs?.[slot.id], attrs?.[slot.ext], options?.assets?.url);
+}
+
+/** The slot whose identity attrs name a given url attr (`poster` → posterAsset*). */
+const slotFor = (urlAttr) => ASSET_SLOTS.find((s) => s.urls.includes(urlAttr));
+
+/**
+ * Resolve a secondary reference (`poster`, `preview`) the same way the primary
+ * one resolves: identity wins when it resolves, else the stored URL stands.
+ * A poster is an asset like any other — it just is not the node's primary.
+ */
+function secondaryAssetUrl(attrs, options, urlAttr) {
+    const slot = slotFor(urlAttr);
+    const resolved = slot ? assetUrlFromAttrs(attrs, options, slot) : "";
+    return resolved || attrs?.[urlAttr] || "";
+}
+
+// ⛔ LEGACY BELOW — the PHP-estate identifier path. Do not extend it.
+//
+// `{version}/{filename}` identifiers have no current producer — the CLI emits
+// `src`, and editors store the URL their host hands them. Only content authored
+// against the original hosted service still carries one, and the hardcoded host
+// below cannot be correct for any other deployment: the CLI can be pointed at
+// any host. New references use `assetId`/`assetExt` above.
 const ASSET_BASE_URL = "https://assets.uniweb.app/";
 
 /**
@@ -695,6 +788,20 @@ const ASSET_BASE_URL = "https://assets.uniweb.app/";
  */
 function resolveAssetIdentifier(identifier) {
     if (!identifier || typeof identifier !== "string") return "";
+    // ⛔ An identifier that is ALREADY a URL or a rooted path is not an
+    // identifier — it is a serve URL sitting in the identifier slot, and it is
+    // usable exactly as it stands. Composing it against the legacy base
+    // destroys it: `split("/")` on `/gateway/asset/dist/{id}/base.png` takes
+    // `""` as the version and `"gateway"` as the filename, yielding
+    // `https://assets.uniweb.app/dist//base.gateway` — not a 404 and not a
+    // validation failure, a URL-shaped string that renders a broken image and
+    // reads like a missing file.
+    //
+    // The legacy grammar is `{version}/{filename}` with no leading slash, so
+    // nothing legitimate is caught here. Passing it through is not constructing
+    // a serve location: it is declining to construct one over a value that is
+    // already an address. (Measured 2026-08-17 against a real producer.)
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|\/)/i.test(identifier)) return identifier;
     const [version, filename] = identifier.split("/");
     if (!filename) return "";
     const ext = filename.substring(filename.lastIndexOf(".") + 1);
@@ -815,7 +922,7 @@ function parseIconBlock(itemAttrs) {
     return icon;
 }
 
-function parseImgBlock(itemAttrs) {
+function parseImgBlock(itemAttrs, options) {
     let {
         info: imgInfo,
         targetId,
@@ -862,12 +969,23 @@ function parseImgBlock(itemAttrs) {
 
     caption = stripTags(caption);
 
-    // Standard ProseMirror `image` nodes use `src`; the custom
-    // `ImageBlock` node uses `url`. Honor either so callers don't have
-    // to pre-normalize. `identifier` (CDN-resolvable asset id) wins
-    // when present so an editor-deployed image with a stale `src`
-    // doesn't shadow the CDN copy.
-    if (identifier) {
+    // Reference precedence. Standard ProseMirror `image` nodes use `src`; the
+    // custom `ImageBlock` node uses `url`. Honor either so callers don't have to
+    // pre-normalize.
+    //
+    // ⭐ A store-held asset (`assetId`) wins WHEN IT RESOLVES — not merely when
+    // it is present. That distinction is the whole reason a producer can write
+    // `assetId` alongside `src` before any deployment declares
+    // `config.assets.url`: until one does, resolution yields '' and the node
+    // renders through `src` exactly as it does today. Content written now stays
+    // correct whichever order the halves arrive in.
+    //
+    // `identifier` is the LEGACY estate path and keeps its old precedence over a
+    // stale `src`.
+    const assetUrl = assetUrlFromAttrs(itemAttrs, options);
+    if (assetUrl) {
+        url = assetUrl;
+    } else if (identifier) {
         url = makeAssetUrl(imgInfo);
     } else if (!url && src) {
         url = src;
@@ -901,7 +1019,11 @@ function parseImgBlock(itemAttrs) {
         ...(loading && { loading }),
         ...(fit && { fit }),
         ...(position && { position }),
-        ...(preview && { preview }),
+        ...((() => {
+            // Same rule for a document's preview image.
+            const p = secondaryAssetUrl(itemAttrs, options, "preview");
+            return p ? { preview: p } : {};
+        })()),
         ...(author && { author }),
         ...(description && { description }),
     };
@@ -915,7 +1037,7 @@ function parseImgBlock(itemAttrs) {
 // attribute set that docs/reference/content-structure.md publishes for the
 // video role, and the shape it documents: `{ src, href, target }` plus the
 // playback flags.
-function parseMarkdownVideo(itemAttrs) {
+function parseMarkdownVideo(itemAttrs, options) {
     const {
         src,
         url,
@@ -933,11 +1055,18 @@ function parseMarkdownVideo(itemAttrs) {
         id, // {#fig-id} cross-reference label, same as parseImgBlock
     } = itemAttrs || {};
 
+    // Reference precedence, now genuinely identical to parseImgBlock: a
+    // resolvable store-held asset, then the legacy identifier, then the authored
+    // src/url.
+    //
+    // ⚠️ The comment here used to claim identifier-precedence "matching
+    // parseImgBlock" while the code did the opposite — it passed `src` INTO
+    // `makeAssetUrl`, which returns a src/url before it ever looks at
+    // `identifier`. So image and video resolved differently for years and the
+    // comment asserted they did not. Aligned to the documented intent (2026-08-17).
+    const assetUrl = assetUrlFromAttrs(itemAttrs, options);
     const video = {
-        // `identifier` (a CDN-resolvable asset id) wins when present, matching
-        // parseImgBlock — an editor-deployed asset with a stale src must not
-        // shadow the CDN copy.
-        src: makeAssetUrl({ src: url || src, ...info }),
+        src: assetUrl || makeAssetUrl(info) || url || src || "",
         alt,
         caption: stripTags(caption),
         role,
@@ -948,7 +1077,10 @@ function parseMarkdownVideo(itemAttrs) {
     // Playback attributes are omitted rather than defaulted: a component can
     // then tell "the author said nothing" from "the author said false", and
     // kit's <Media> supplies its own defaults (controls on, the rest off).
-    if (poster) video.poster = poster;
+    // A poster is an asset like any other — identity resolves it when it can,
+    // and the stored URL stands when it cannot. Same rule as the primary `src`.
+    const posterUrl = secondaryAssetUrl(itemAttrs, options, "poster");
+    if (posterUrl) video.poster = posterUrl;
     if (autoplay !== undefined) video.autoplay = autoplay;
     if (muted !== undefined) video.muted = muted;
     if (loop !== undefined) video.loop = loop;
@@ -958,7 +1090,7 @@ function parseMarkdownVideo(itemAttrs) {
     return video;
 }
 
-function parseVideoBlock(itemAttrs) {
+function parseVideoBlock(itemAttrs, options) {
     let {
         src,
         caption = "",
@@ -970,10 +1102,9 @@ function parseVideoBlock(itemAttrs) {
         target = "",
     } = itemAttrs;
 
-    let video = makeAssetUrl({
-        src,
-        ...info,
-    });
+    // Same precedence as parseImgBlock / parseMarkdownVideo: a resolvable
+    // store-held asset, then the legacy identifier, then the authored src.
+    const video = assetUrlFromAttrs(itemAttrs, options) || makeAssetUrl(info) || src || "";
 
     return {
         src: video,
@@ -1009,7 +1140,7 @@ function stripTags(htmlString) {
         .replace(/&#x([0-9a-fA-F]+);/g, (_, n) => String.fromCharCode(parseInt(n, 16)));
 }
 
-function isLink(item) {
+function isLink(item, options = {}) {
     // Detect paragraphs/headings that are semantically "just a link"
     // (single link text, possibly with decorative icons)
     //
@@ -1067,7 +1198,7 @@ function isLink(item) {
                         iconBefore,
                         iconAfter,
                         // Preserve all inline elements for advanced rendering
-                        children: processInlineElements(originalContent),
+                        children: processInlineElements(originalContent, options),
                     };
                 }
             }
@@ -1132,7 +1263,7 @@ function isOnlyLinks(item) {
 // method to check if given item has multiple content parts and each of them has the same link attrs with different inline style (plain, em, strong, u)
 // if so, it will return the link attrs and all the content parts whose link mark has been removed
 // warning: This method will not work if the any of the content parts are not link marks
-function isStyledLink(item) {
+function isStyledLink(item, options = {}) {
     if (!["paragraph", "heading"].includes(item.type)) return false;
 
     let content = item?.content || [];
@@ -1182,10 +1313,10 @@ function isStyledLink(item) {
 
     return {
         type: "paragraph",
-        children: processInlineElements(item.content),
+        children: processInlineElements(item.content, options),
         text: `<a target="${target}" href="${href}">${textContent}</a>`,
         attrs: item.attrs,
     };
 }
 
-export { processSequence };
+export { processSequence, resolveAssetUrl };