@uniweb/semantic-parser 1.1.6 → 1.1.8

package/AGENTS.md

@@ -167,7 +167,7 @@ Key patterns:
 - **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 with increasing levels are consumed together
+- **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
 

package/README.md

@@ -153,6 +153,8 @@ Groups are created based on heading patterns. A new group starts when:
 - Multiple H1s appear (no main content created)
 - The heading level indicates a new section
 
+**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.
+
 **Pretitle Detection:** Any heading followed by a more important heading is automatically detected as a pretitle:
 - H3 before H1 → pretitle ✅
 - H2 before H1 → pretitle ✅

package/package.json

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

package/src/builders/doc.js

@@ -0,0 +1,204 @@
+/**
+ * Reverse conversion: content structure → TipTap document.
+ *
+ * Mirrors the forward parser (processors/sequence.js + processors/groups.js)
+ * so that parseContent(buildDoc(content)) roundtrips cleanly.
+ *
+ * Starter content uses plain strings (no HTML marks), so the conversion
+ * is straightforward — no need to reverse inline HTML formatting.
+ */
+
+// --- TipTap node builders ---
+
+function textNode(text) {
+  return { type: 'text', text }
+}
+
+function heading(level, text) {
+  if (!text) return null
+  // Multi-line title: string[] → multiple headings at same level
+  if (Array.isArray(text)) {
+    return text.map(t => heading(level, t)).filter(Boolean)
+  }
+  return {
+    type: 'heading',
+    attrs: { level },
+    content: [textNode(text)],
+  }
+}
+
+function paragraph(text) {
+  if (!text) return null
+  return {
+    type: 'paragraph',
+    content: [textNode(text)],
+  }
+}
+
+function linkParagraph({ text, href, target }) {
+  if (!text || !href) return null
+  const mark = { type: 'link', attrs: { href } }
+  if (target) mark.attrs.target = target
+  return {
+    type: 'paragraph',
+    content: [{ type: 'text', text, marks: [mark] }],
+  }
+}
+
+function imageBlock({ src, alt = '', caption = '', direction, role, width, height }) {
+  const attrs = { url: src, alt }
+  if (caption) attrs.caption = caption
+  if (direction) attrs.direction = direction
+  if (role) attrs.role = role
+  if (width && height) {
+    attrs.aspect_ratio = { width, height, ratio: (height / width) * 100 }
+  }
+  return { type: 'ImageBlock', attrs }
+}
+
+function iconNode({ src, svg, library, name, size, color }) {
+  // UniwebIcon supports multiple source types
+  const attrs = {}
+  if (svg || src) attrs.svg = svg || src
+  if (library) attrs.library = library
+  if (name) attrs.name = name
+  if (size) attrs.size = size
+  if (color) attrs.color = color
+  return { type: 'UniwebIcon', attrs }
+}
+
+function videoNode({ src, caption, direction, coverImg }) {
+  const attrs = { src }
+  if (caption) attrs.caption = caption
+  if (direction) attrs.direction = direction
+  if (coverImg) attrs.coverImg = coverImg
+  return { type: 'Video', attrs }
+}
+
+function dividerBlock() {
+  return { type: 'DividerBlock' }
+}
+
+function bulletList(items) {
+  if (!items || !items.length) return null
+  return {
+    type: 'bulletList',
+    content: items.map(item => ({
+      type: 'listItem',
+      content: [paragraph(item)].filter(Boolean),
+    })),
+  }
+}
+
+// --- Group builder ---
+
+/**
+ * Build TipTap nodes from a content group (main or item).
+ *
+ * @param {Object} group - Content structure: { pretitle, title, subtitle, paragraphs, images, ... }
+ * @param {number} titleLevel - Heading level for title (1 for main, 2 for items)
+ * @returns {Array} Array of TipTap nodes
+ */
+function buildGroupNodes(group, titleLevel = 1) {
+  const nodes = []
+
+  // 1. Headings: pretitle → title → subtitle
+  // Pretitle uses a higher level number (less important) than title
+  // e.g., H3 before H1 — mirrors isPreTitle() in groups.js
+  if (group.pretitle) {
+    const pre = heading(titleLevel + 2, group.pretitle)
+    if (Array.isArray(pre)) nodes.push(...pre)
+    else if (pre) nodes.push(pre)
+  }
+
+  if (group.title) {
+    const t = heading(titleLevel, group.title)
+    if (Array.isArray(t)) nodes.push(...t)
+    else if (t) nodes.push(t)
+  }
+
+  // Subtitle is one level below title
+  if (group.subtitle) {
+    const sub = heading(titleLevel + 1, group.subtitle)
+    if (Array.isArray(sub)) nodes.push(...sub)
+    else if (sub) nodes.push(sub)
+  }
+
+  // 2. Body fields in document order
+  if (group.paragraphs) {
+    for (const p of group.paragraphs) {
+      const node = paragraph(p)
+      if (node) nodes.push(node)
+    }
+  }
+
+  if (group.images) {
+    for (const img of group.images) {
+      nodes.push(imageBlock(img))
+    }
+  }
+
+  if (group.links) {
+    for (const link of group.links) {
+      const node = linkParagraph(link)
+      if (node) nodes.push(node)
+    }
+  }
+
+  if (group.icons) {
+    for (const icon of group.icons) {
+      nodes.push(iconNode(icon))
+    }
+  }
+
+  if (group.videos) {
+    for (const video of group.videos) {
+      nodes.push(videoNode(video))
+    }
+  }
+
+  if (group.lists) {
+    for (const list of group.lists) {
+      const node = bulletList(list)
+      if (node) nodes.push(node)
+    }
+  }
+
+  return nodes
+}
+
+// --- Main export ---
+
+/**
+ * Build a TipTap document from a content structure.
+ *
+ * This is the reverse of parseContent(): given a flat content object
+ * (title, paragraphs, items, etc.), produce a TipTap document that
+ * roundtrips through parseContent() to yield the same structure.
+ *
+ * @param {Object} content - Content structure (same shape as parseContent output / starter)
+ * @returns {Object|null} TipTap document { type: 'doc', content: [...] }, or null if empty
+ */
+function buildDoc(content) {
+  if (!content) return null
+
+  const nodes = []
+
+  // Main group content (title level 1)
+  nodes.push(...buildGroupNodes(content, 1))
+
+  // Items: separated by DividerBlock (mirrors divider-based grouping in groups.js)
+  if (content.items && content.items.length > 0) {
+    for (const item of content.items) {
+      nodes.push(dividerBlock())
+      // Item headings use level 2 (one below main H1)
+      nodes.push(...buildGroupNodes(item, 2))
+    }
+  }
+
+  if (nodes.length === 0) return null
+
+  return { type: 'doc', content: nodes }
+}
+
+export { buildDoc }

package/src/index.js

@@ -1,5 +1,6 @@
 import { processSequence } from "./processors/sequence.js";
 import { processGroups } from "./processors/groups.js";
+import { buildDoc } from "./builders/doc.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
@@ -29,4 +30,4 @@ function parseContent(doc, options = {}) {
     };
 }
 
-export { parseContent };
+export { parseContent, buildDoc };

package/src/processors/groups.js

@@ -183,9 +183,11 @@ function readHeadingGroup(sequence, startIdx) {
             break;
         }
 
-        // Case 1: Strictly Deeper (Standard Subtitle/Deep Header)
-        // e.g. H1 -> H2
-        if (element.level > previousElement.level) {
+        // 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;

package/src/processors/sequence.js

@@ -412,21 +412,25 @@ function processInlineElements(content) {
     return items;
 }
 
-function makeAssetUrl(info) {
-    let url = "";
-
-    let src = info?.src || info?.url || "";
+const ASSET_BASE_URL = "https://assets.uniweb.app/";
 
-    if (src) {
-        url = src;
-    } else if (info?.identifier) {
-        url =
-            new uniweb.Profile(`docufolio/profile`, "_template").getAssetInfo(
-                info.identifier
-            )?.src || "";
-    }
+/**
+ * Resolve an asset identifier ({version}/{filename}) to a direct URL.
+ * Assets are hosted at assets.uniweb.app under dist/{version}/base.{ext}.
+ */
+function resolveAssetIdentifier(identifier) {
+    if (!identifier || typeof identifier !== "string") return "";
+    const [version, filename] = identifier.split("/");
+    if (!filename) return "";
+    const ext = filename.substring(filename.lastIndexOf(".") + 1);
+    return `${ASSET_BASE_URL}dist/${version}/base.${ext}`;
+}
 
-    return url;
+function makeAssetUrl(info) {
+    const src = info?.src || info?.url || "";
+    if (src) return src;
+    if (info?.identifier) return resolveAssetIdentifier(info.identifier);
+    return "";
 }
 
 function parseCardBlock(itemAttrs) {
@@ -467,10 +471,7 @@ function parseDocumentBlock(itemAttrs) {
         const { identifier = "" } = info;
 
         if (identifier) {
-            ele.downloadUrl = new uniweb.Profile(
-                `docufolio/profile`,
-                "_template"
-            ).getAssetInfo(identifier)?.href;
+            ele.downloadUrl = resolveAssetIdentifier(identifier);
         }
     }