@uniweb/semantic-parser 1.1.9 → 1.1.11

package/AGENTS.md

@@ -95,12 +95,15 @@ The `data` object holds all structured content:
 data: {
   "nav-links": [...],     // From ```yaml:nav-links
   "config": {...},        // From ```yaml:config
-  "form": {...},          // From FormBlock editor widget or ```yaml:form
+  "stats": [...],         // From FormBlock (activeSchemaId='stats') or ```yaml:stats
   "person": [...],        // From card-group with cardType="person"
   "event": [...]          // From card-group with cardType="event"
 }
 ```
 
+FormBlock data is routed to `data[activeSchemaId]`. A legacy
+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:
@@ -121,7 +124,7 @@ The sequence processor identifies several special element types by inspecting pa
 
 Editor-specific nodes are mapped to standard entities:
 - `button` node → `links[]` with `role: "button"` and `variant` attribute
-- `FormBlock` → `data.form`
+- `FormBlock` → `data[activeSchemaId]` (fallback: `data.form` when no schemaId)
 - `card-group` → `data[cardType]` arrays (e.g., `data.person`, `data.event`)
 - `document-group` → `links[]` with `role: "document"` and `download: true`
 

package/README.md

@@ -77,13 +77,18 @@ result = {
   icons: [],
   lists: [],
   quotes: [],
+  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
 
   // Additional content groups (from headings after content)
+  // Each item has the SAME flat structure as the top level — title,
+  // pretitle, subtitle, paragraphs, links, images, icons, lists,
+  // snippets, data, etc. Use this for cards, features, FAQ entries.
   items: [
-    { title: "Feature 1", paragraphs: [...], links: [...] },
-    { title: "Feature 2", paragraphs: [...], links: [...] }
+    { title: "Feature 1", paragraphs: [...], links: [...], /* ...full shape */ },
+    { title: "Feature 2", paragraphs: [...], links: [...], /* ...full shape */ }
   ],
 
   // Ordered sequence for document-order rendering
@@ -144,28 +149,53 @@ sequence.forEach(element => {
 
 ## Content Grouping
 
-The parser supports two grouping modes:
+The parser interprets heading levels **relatively**, not absolutely. There is no requirement that a section start with H1 — what matters is the relationship *between* headings (which is more important, which is deeper, which comes after body content). Starting at H1 is natural and recommended, but the same structure works starting at H2 or H3 — every rule below is about relative levels.
 
-### Heading-Based Grouping (Default)
+### How groups are formed
 
-Groups are created based on heading patterns. A new group starts when:
-- A heading follows content
-- Multiple H1s appear (no main content created)
-- The heading level indicates a new section
+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.
 
-**Heading group formation:** Consecutive headings are consumed as a single semantic unit only when each subsequent heading is _exactly one level deeper_ than the previous (e.g., H1→H2→H3). Skipping levels (H1→H3) breaks the group — the deeper heading starts a new group instead of becoming a subtitle. This reflects natural document structure: a large level gap signals items, not a title-subtitle pair.
+When a group begins with one or more headings, the parser consumes a contiguous **heading block** following these rules:
 
-**Pretitle Detection:** Any heading followed by a more important heading is automatically detected as a pretitle:
-- H3 before H1 → pretitle ✅
-- H2 before H1 → pretitle ✅
-- H6 before H5 → pretitle ✅
-- H4 before H2 → pretitle ✅
+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.
 
-No configuration needed - it just works naturally!
+Anything else (going back up after going deeper, or any other gap) breaks the block.
 
-### Divider-Based Grouping
+### Main content vs items
 
-When any horizontal rule (`---`) is present, the entire document uses divider-based grouping. Groups are split explicitly by dividers.
+Once groups are split, the parser decides whether the first group is the section's main content or whether *all* groups should be treated as items. The first group becomes main content when **either**:
+
+- It has no heading at all (body content appearing before the first heading), **or**
+- Its heading level is more important (lower-numbered) than the second group's heading level.
+
+Otherwise, every group becomes an item and the top-level header fields stay empty. For example, a document that starts with `## Card A` followed by `## Card B` produces two items and no main title — because the first group is not more important than the second. The same is true for two H1s in a row, or two H3s; the rule is about *relative* importance, not a specific level.
+
+This is the mechanism that creates repeating content groups (cards, features, FAQ entries) without any extra configuration.
+
+### Pretitle detection
+
+A heading followed by a more important heading at the start of a group is detected as `pretitle`:
+
+- 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).
+
+### Banner image
+
+If a section's very first element is an image (or an image followed immediately by a heading), the parser keeps the image and the following heading in the same group rather than splitting them. This lets a leading image act as a banner for the section's title without becoming an unrelated item.
+
+### Divider-based grouping
+
+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.
+- **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.
 
 ## Text Formatting
 

package/package.json

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

package/src/processors/groups.js

@@ -5,7 +5,7 @@
  */
 function flattenGroup(group) {
     if (!group) return null;
-    return {
+    const flat = {
         title: group.header.title || '',
         pretitle: group.header.pretitle || '',
         subtitle: group.header.subtitle || '',
@@ -21,6 +21,11 @@ function flattenGroup(group) {
         quotes: group.body.quotes || [],
         headings: group.body.headings || [],
     };
+    // Only attach rare collections when present so we don't pay the cost
+    // on every page (math is <1% of content in practice; authors who need
+    // ordering should use content.sequence anyway).
+    if (group.body.math && group.body.math.length) flat.math = group.body.math;
+    return flat;
 }
 
 /**
@@ -240,6 +245,9 @@ function processGroupContent(elements) {
         data: {},
         quotes: [],
         headings: [],
+        // `math` is lazily added in the math_display case when encountered —
+        // avoids allocating an empty array on every group (math is rare; most
+        // consumers that care about ordering should use content.sequence).
     };
 
     const metadata = {
@@ -370,13 +378,38 @@ function processGroupContent(elements) {
                     });
                     break;
 
+                case "math_display":
+                    // Block-level math from $$...$$ on its own line or ```math
+                    // fence. The mathml string is pre-compiled at parse time;
+                    // foundations render it by setting dangerouslySetInnerHTML
+                    // on the mathml field. The optional id enables numbered
+                    // cross-references (see @uniweb/scholar/math).
+                    // For ordered rendering alongside paragraphs, prefer
+                    // `content.sequence` — this flat collection is convenience
+                    // sugar when order doesn't matter. Allocate lazily so
+                    // pages without math pay nothing.
+                    (body.math ||= []).push({
+                        id: element.id || null,
+                        latex: element.latex || '',
+                        mathml: element.mathml || '',
+                    });
+                    break;
+
                 case "inset":
                     body.insets.push({ refId: element.refId });
                     break;
 
                 case "form":
-                    // Map FormBlock to data.form
-                    body.data.form = element.data || element.attrs;
+                    // Route FormBlock data by the schema id it targets, so it
+                    // shares a namespace with tagged markdown data blocks
+                    // (```yaml:<id>``` also lands at data[<id>]). When no
+                    // schemaId is present (legacy content), fall back to the
+                    // literal key "form" — eventual deprecation.
+                    {
+                        const payload = element.data || element.attrs;
+                        const key = element.schemaId || "form";
+                        body.data[key] = payload;
+                    }
                     break;
 
                 case "card-group":

package/src/processors/sequence.js

@@ -167,16 +167,33 @@ function createSequenceElement(node, options = {}) {
                 type: "inset",
                 refId: attrs.refId,
             };
+
+        case "math_display":
+            // Block-level math. The mathml string is pre-compiled at parse
+            // time (content-reader) and renders natively via kit's HTML
+            // renderers. Foundations can read el.mathml from content.sequence.
+            // The optional id enables numbered cross-references via
+            // @uniweb/scholar/math's <EquationRef>.
+            return {
+                type: "math_display",
+                id: node.attrs?.id || null,
+                latex: node.attrs?.latex || "",
+                mathml: node.attrs?.mathml || "",
+                attrs,
+            };
         case "ImageBlock":
             return {
                 type: "image",
                 attrs: parseImgBlock(attrs),
             };
         case "image":
-            // Standard ProseMirror image node - wrap attrs like ImageBlock
+            // Standard ProseMirror image node - resolve attrs the same way as
+            // ImageBlock so info.identifier lands as a CDN URL. CLI-deployed
+            // content uses this node type; without parseImgBlock the url
+            // wouldn't be populated and components render an empty slot.
             return {
                 type: "image",
-                attrs: attrs || {},
+                attrs: parseImgBlock(attrs || {}),
             };
         case "Video":
             return {
@@ -241,6 +258,7 @@ function createSequenceElement(node, options = {}) {
 
             return {
                 type: "form",
+                schemaId: attrs?.activeSchemaId || null,
                 data: formData,
                 attrs,
             };
@@ -380,6 +398,12 @@ function getTextContent(content, options = {}) {
                 }
 
                 return prev + styledText;
+            } else if (type === "math_inline") {
+                // Pre-compiled MathML string rides straight into the
+                // paragraph's HTML and reaches kit's Text via
+                // dangerouslySetInnerHTML. The HTML5 parser handles <math>
+                // as MathML natively — zero runtime math library needed.
+                return prev + (curr.attrs?.mathml || "");
             } else if (type === "hardBreak") {
                 return prev + "<br>";
             } else {