@uniweb/semantic-parser 1.1.20 → 1.2.0

package/package.json

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

package/src/builders/doc.js

@@ -56,7 +56,7 @@ function imageBlock({ src, alt = '', caption = '', direction, role, width, heigh
   return { type: 'ImageBlock', attrs }
 }
 
-function iconNode({ src, svg, library, name, size, color }) {
+function iconNode({ src, url, svg, library, name, size, color }) {
   // UniwebIcon supports multiple source types.
   //
   // The family rides INSIDE `name` as `family:id`. The editor's node declares
@@ -64,8 +64,17 @@ function iconNode({ src, svg, library, name, size, color }) {
   // and ProseMirror silently drops undeclared attrs on `fromJSON` — so emitting
   // a separate `library` lost the family without a trace, on the path that
   // builds starter content for every new section.
+  //
+  // `svg` is MARKUP and `url` is a URL — on both sides. A file-sourced icon
+  // arrives here as `src` and belongs in `url`, not in the markup slot; putting
+  // a path where a consumer expects `<svg …>` renders nothing. (Fixed
+  // 2026-07-30; `url` is declared on the editor's node, so it crosses intact.)
   const attrs = {}
-  if (svg || src) attrs.svg = svg || src
+  if (svg) attrs.svg = svg
+  // Either spelling in, one spelling out — `parseUniwebIcon` now emits `url`
+  // for a file-sourced icon, and this builder's documented invariant is that
+  // parseContent(buildDoc(x)) round-trips.
+  if (url || src) attrs.url = url || src
   if (name) attrs.name = library ? `${library}:${name}` : name
   if (size) attrs.size = size
   if (color) attrs.color = color

package/src/index.js

@@ -4,9 +4,25 @@ import { buildDoc } from "./builders/doc.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
+ *
+ * This is the PUBLIC entry point for deriving the flat shape, and every
+ * consumer calls it: the runtime derives a block's content this way, and an
+ * editor drawing a surface over the same document derives it the same way. That
+ * both sides run one implementation is what makes their readings agree — so a
+ * derivation rule must be reachable from here rather than applied privately by
+ * whoever produced the ProseMirror.
+ *
+ * Nothing derived is stored. This runs JIT on each side, every time, which is
+ * also why changing a grouping rule re-reads every document that already
+ * exists — see `alwaysItems` below.
+ *
  * @param {Object} doc - ProseMirror document
  * @param {Object} options - Parsing options
  * @param {boolean} options.parseCodeAsJson - Parse code blocks as JSON. Default: false
+ * @param {boolean} options.alwaysItems - Every heading group becomes an item:
+ *   no title promotion, no same-level heading merge. The shape a tagged concept
+ *   block (```md:faq) always takes, fixed by its fence. Default: false, and the
+ *   default path is pinned by tests/grouping-default-path.test.js.
  * @returns {Object} Flat content structure with sequence for ordered access
  */
 function parseContent(doc, options = {}) {

package/src/processors/groups.js

@@ -25,13 +25,33 @@ function flattenGroup(group) {
     // 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;
+    if (group.body.tables && group.body.tables.length) flat.tables = group.body.tables;
     return flat;
 }
 
 /**
  * Transform a sequence into content groups with semantic structure
+ *
+ * `options.alwaysItems` makes every group an ITEM: it turns off the two rules
+ * that otherwise collapse a short document into a titled main block —
+ * title promotion (`identifyMainContent`) and same-level heading merge
+ * (`readHeadingGroup`'s Case 3). Used for a tagged concept block, whose shape is
+ * fixed by its fence rather than by what it happens to contain.
+ *
+ * It names a GROUPING BEHAVIOUR, not a concept. Nothing here knows what `faq` or
+ * `warning` mean, and nothing should: a framework-side registry of concept names
+ * is the failure the whole design avoids.
+ *
+ * DEFAULT OFF, and that matters more than it looks. This parser runs JIT — at
+ * 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.
+ *
  * @param {Array} sequence Flat sequence of elements
  * @param {Object} options Parsing options
+ * @param {boolean} [options.alwaysItems] Every group is an item; no main block
  * @returns {Object} Flat content object with items array
  */
 function processGroups(sequence, options = {}) {
@@ -56,7 +76,7 @@ function processGroups(sequence, options = {}) {
         };
     }
 
-    const groups = splitBySlices(sequence);
+    const groups = splitBySlices(sequence, options);
 
     // Process each group's structure (still nested internally)
     const processedGroups = groups.map((group) => processGroupContent(group));
@@ -65,7 +85,12 @@ function processGroups(sequence, options = {}) {
     let mainGroup = null;
     let itemGroups = [];
 
-    const shouldBeMain = identifyMainContent(processedGroups);
+    // Suppression 1 of 2: title promotion. Without it a lone heading+body pair
+    // is the whole "main" block and yields NO items — the single-question FAQ,
+    // and every callout, would arrive empty.
+    const shouldBeMain = options.alwaysItems
+        ? false
+        : identifyMainContent(processedGroups);
     if (shouldBeMain) {
         mainGroup = processedGroups[0];
         itemGroups = processedGroups.slice(1);
@@ -99,7 +124,7 @@ function processGroups(sequence, options = {}) {
     };
 }
 
-function splitBySlices(sequence) {
+function splitBySlices(sequence, options = {}) {
     const groups = [];
     let currentGroup = [];
 
@@ -132,7 +157,7 @@ function splitBySlices(sequence) {
 
             // Consume the entire semantic heading block (Title + Subtitles)
             // We reuse your smart readHeadingGroup logic here!
-            const headingBlock = readHeadingGroup(sequence, i);
+            const headingBlock = readHeadingGroup(sequence, i, options);
             currentGroup.push(...headingBlock);
 
             // Advance the index by the number of headings consumed
@@ -175,7 +200,7 @@ function isBannerImage(sequence, i) {
     );
 }
 
-function readHeadingGroup(sequence, startIdx) {
+function readHeadingGroup(sequence, startIdx, options = {}) {
     const elements = [sequence[startIdx]];
     let hasGoneDeeper = false;
 
@@ -211,7 +236,18 @@ function readHeadingGroup(sequence, startIdx) {
         // 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)
-        if (element.level === previousElement.level && !hasGoneDeeper) {
+        //
+        // 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;
         }
@@ -366,6 +402,32 @@ function processGroupContent(elements) {
                     body.quotes.push(quoteContent.body);
                     break;
 
+                case "concept_block": {
+                    // A tagged prose fence lands under its tag, sharing the
+                    // namespace tagged DATA blocks use (```yaml:nav also lands
+                    // at data[nav]) — one place a component looks, whichever
+                    // form the author reached for.
+                    //
+                    // Both views, because two consumers need different ones and
+                    // `parseContent` computes them in one pass anyway. `items`
+                    // is what an accordion or a step list renders. `sequence` is
+                    // what anything rendering a concept it does not RECOGNIZE
+                    // has to use: `items` is a bucketed flattening that discards
+                    // ordering, and it collapses to [] exactly where `sequence`
+                    // survives — two bodiless headings give items 0, sequence 2.
+                    //
+                    // `alwaysItems` is hard-coded rather than inherited, and
+                    // that is the scoping: a concept block's shape is fixed by
+                    // its fence no matter how the surrounding document was
+                    // parsed, and the suppressions never reach the default path.
+                    const children = element.children || [];
+                    body.data[element.tag] = {
+                        items: processGroups(children, { alwaysItems: true }).items,
+                        sequence: children,
+                    };
+                    break;
+                }
+
                 case "dataBlock":
                     // Pre-parsed structured data from content-reader
                     body.data[element.tag] = element.data;
@@ -400,6 +462,18 @@ function processGroupContent(elements) {
                     });
                     break;
 
+                case "table":
+                    // Lazily attached, like `math`: most content has no table,
+                    // and a component that cares about ordering should read
+                    // `content.sequence` anyway. Before 2026-07-30 the sequence
+                    // did not carry tables at all, so there was nothing here to
+                    // collect.
+                    (body.tables ||= []).push({
+                        rows: element.rows || [],
+                        attrs: element.attrs || {},
+                    });
+                    break;
+
                 case "inset":
                     body.insets.push({ refId: element.refId });
                     break;
@@ -492,6 +566,11 @@ function processInlineElements(children, body) {
             } else {
                 body.images.push(item.attrs);
             }
+        } else if (item.type === "video") {
+            // Mirrors the top-level `case "video"` partition — an inline
+            // `{role=video}` belongs in videos[] for the same reason a hoisted
+            // one does.
+            body.videos.push(item.attrs);
         } else if (item.type === "link") {
             // Handle inline links extracted from paragraph text nodes
             body.links.push(item.attrs);

package/src/processors/sequence.js

@@ -168,6 +168,26 @@ function createSequenceElement(node, options = {}) {
             };
         }
 
+        case "concept_block": {
+            // A tagged prose fence (```md:faq). Its body is real block content,
+            // recursed like a container's — the default branch would flatten it
+            // to a text string and lose the author's prose.
+            //
+            // No markdown is parsed here and none may ever be: this package
+            // depends on `yaml` alone, and reaching for a markdown parser would
+            // 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.
+            return {
+                type: "concept_block",
+                tag: attrs?.tag,
+                children: processSequence({ content }, options),
+            };
+        }
+
         case "dataBlock":
             // Pre-parsed structured data from content-reader
             return {
@@ -225,6 +245,24 @@ function createSequenceElement(node, options = {}) {
                 attrs: parseImgBlock(attrs),
             };
         case "image":
+            // `role` decides which content array this lands in — the contract
+            // published in docs/reference/content-structure.md ("Media Assets"):
+            // icon → icons, video → videos, everything else → images.
+            //
+            // The video branch was missing until 2026-07-30: every
+            // `{role=video}` node ran parseImgBlock, which does not carry
+            // poster/autoplay/muted/loop/controls, so the author's declaration
+            // was demoted to an image AND its playback attrs were dropped —
+            // while the build had already generated a poster for it
+            // (@uniweb/build site/assets.js). Note this does NOT route to
+            // parseVideoBlock: that reader speaks the editor's dialect
+            // (coverImg, info), not the markdown one.
+            if (attrs?.role === "video") {
+                return {
+                    type: "video",
+                    attrs: parseMarkdownVideo(attrs),
+                };
+            }
             // 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
@@ -258,10 +296,49 @@ function createSequenceElement(node, options = {}) {
             };
         }
 
+        case "table": {
+            // Rows of cells, each cell a nested SEQUENCE — the same recursion a
+            // blockquote or a list item gets, so a cell may hold anything a
+            // block can.
+            //
+            // Added 2026-07-30. Before this a table fell to the `default:`
+            // branch and became `{ type: 'table', content: '' }` — not merely
+            // unrendered but DESTROYED: `getTextContent` walks for text nodes
+            // and a table's children are rows, so even the cell text came back
+            // empty. Every consumer of `content.sequence` therefore lost tables
+            // entirely, which read as "the renderer has no table case" and was
+            // really the vocabulary not carrying one.
+            const rows = (content || [])
+                .filter((row) => row.type === "tableRow")
+                .map((row) => ({
+                    cells: (row.content || [])
+                        .filter((cell) => cell.type === "tableCell")
+                        .map((cell) => ({
+                            children: processSequence({ content: cell.content }, options),
+                            header: cell.attrs?.header === true,
+                            align: cell.attrs?.align || null,
+                            colspan: cell.attrs?.colspan || 1,
+                            rowspan: cell.attrs?.rowspan || 1,
+                        })),
+                }));
+
+            return { type: "table", rows, attrs };
+        }
+
+        // `divider` is what content-reader emits; `horizontalRule` and
+        // `DividerBlock` are the editor's spellings. All three are one element.
+        //
+        // The reader's own name was NOT listed here until 2026-07-30 — markdown
+        // dividers reached consumers only by falling through `default:`, which
+        // happens to produce `{ type: 'divider', content: '' }` and happens to
+        // match what everything downstream keys on. It worked by coincidence,
+        // and the coincidence would have broken the moment `default:` changed.
+        case "divider":
         case "DividerBlock":
         case "horizontalRule":
             return {
                 type: "divider",
+                attrs,
             };
 
         // Custom TipTap elements
@@ -529,6 +606,24 @@ function processInlineElements(content) {
                 type: "icon",
                 attrs: parseUniwebIcon(item.attrs),
             });
+        } else if (item.type === "image" || item.type === "ImageBlock") {
+            // A media node that stayed inside its paragraph — content-reader
+            // hoists a standalone one to the document root, but an image sitting
+            // beside text does not qualify (parser/block.js `isBlockEligible`).
+            //
+            // Without this branch such a node reached NOTHING: getTextContent
+            // skips it, so it was absent from the paragraph's `text`, absent
+            // from `children`, and absent from `body.images` — the author's
+            // image silently deleted. groups.js has carried the receiving
+            // branch (and a comment describing exactly this failure) since it
+            // was written, but nothing ever emitted the item it reads.
+            const isVideo = item.attrs?.role === "video";
+            items.push({
+                type: isVideo ? "video" : "image",
+                attrs: isVideo
+                    ? parseMarkdownVideo(item.attrs)
+                    : parseImgBlock(item.attrs || {}),
+            });
         } else if (item.type === "math-inline" || item.type === "math_inline") {
             items.push(item);
         } else if (item.type === "inset_placeholder") {
@@ -626,14 +721,23 @@ function parseDocumentBlock(itemAttrs) {
 }
 
 function parseUniwebIcon(itemAttrs) {
-    const { svg, url, size, color, preserveColors, href, target, library, name } = itemAttrs || {};
+    const { svg, url, src, size, color, preserveColors, href, target, library, name } = itemAttrs || {};
 
     // Build object with only defined fields — icon source varies:
     // TipTap editor: svg/url (resolved inline)
     // Markdown pipeline: library + name (resolved at runtime via CDN)
+    //                    OR a file, which arrives as `src`
     const icon = {};
     if (svg) icon.svg = svg;
-    if (url) icon.url = url;
+    // Standard ProseMirror `image` nodes use `src`; the editor's `UniwebIcon`
+    // uses `url`. Honor either, exactly as parseImgBlock does below — a
+    // file-sourced icon is authored `![Logo](icon:./logo.svg)` or
+    // `![Logo](./logo.svg){role=icon}` (both documented in AGENTS.md and
+    // docs/reference/content-structure.md), and reaches here as `src` with no
+    // library/name. Until 2026-07-30 this reader dropped it, so every
+    // documented file-sourced icon delivered `{}` and rendered nothing.
+    // `url` is the key kit's <Icon> fetches from.
+    if (url || src) icon.url = url || src;
     if (size) icon.size = size;
     if (color) icon.color = color;
     if (preserveColors) icon.preserveColors = preserveColors;
@@ -655,10 +759,27 @@ function parseUniwebIcon(itemAttrs) {
     return icon;
 }
 
+// The editor's `Icon` node carries an inline SVG blob plus a theme. Return an
+// ATTRS OBJECT, like every other parser in this file — not the bare `svg`
+// string it used to return.
+//
+// The string form was a live bug, not just an inconsistency: kit renders a
+// sequence icon with `<Icon {...element.attrs} />` (styled/Prose/index.jsx),
+// and spreading a string yields indexed character props — `{0:'<', 1:'s', …}`
+// — so the icon rendered as nothing and React saw a wall of unknown props. It
+// failed silently because `attrs.svg` on a string is `undefined`, never an
+// error.
+//
+// Keys are omitted when absent so a consumer can distinguish "not provided"
+// from "empty", matching parseUniwebIcon's shape above.
 function parseIconBlock(itemAttrs) {
-    let { svg } = itemAttrs;
+    const { svg, theme } = itemAttrs || {};
+
+    const icon = {};
+    if (svg) icon.svg = svg;
+    if (theme) icon.theme = theme;
 
-    return svg;
+    return icon;
 }
 
 function parseImgBlock(itemAttrs) {
@@ -678,6 +799,24 @@ function parseImgBlock(itemAttrs) {
         credit = "",
         id, // {#fig-id} cross-reference label — preserved so Press
             // adapters can emit \label{id} (LaTeX) / <id> (Typst).
+        // ── Markdown-authored attributes ────────────────────────────────
+        // This function was written for the EDITOR's `ImageBlock` node and
+        // later reused for the markdown `image` node (see `case "image"`), so
+        // its vocabulary is the editor's: contentType, direction, filter,
+        // theme, credit. Everything markdown declares and the editor does not
+        // was therefore tokenized, declared, and then dropped one layer before
+        // delivery — the published "Image Attributes" table
+        // (docs/reference/content-structure.md) reached no component, and
+        // neither did the `role=pdf` set added 2026-07-29 for the editor's
+        // `document` fold-in. Carried 2026-07-30.
+        width,
+        height,
+        loading,
+        fit,
+        position,
+        preview,     // role=pdf — the preview image
+        author,      // role=pdf — resource metadata, rendered beside the preview
+        description, // role=pdf — describes the RESOURCE, not the image (≠ alt)
     } = itemAttrs;
 
     let { contentType, viewType, contentId, identifier } = imgInfo || {};
@@ -712,6 +851,10 @@ function parseImgBlock(itemAttrs) {
         direction,
         filter,
         imgPos: direction === "left" || direction === "right" ? direction : "",
+        // NOTE: `size` here is the direction-derived LAYOUT size
+        // (basic/lg/full), not the author's `{size=…}` — that attribute is
+        // icon-only and is read by parseUniwebIcon. Do not wire `{size=…}`
+        // through here; the two meanings collide on one key.
         size: sizes[direction] || "basic",
         href,
         target,
@@ -719,7 +862,67 @@ function parseImgBlock(itemAttrs) {
         role,
         credit,
         id: id || undefined,
+        // Omitted when absent, so an existing consumer sees no new empty keys.
+        ...(width !== undefined && width !== null && { width }),
+        ...(height !== undefined && height !== null && { height }),
+        ...(loading && { loading }),
+        ...(fit && { fit }),
+        ...(position && { position }),
+        ...(preview && { preview }),
+        ...(author && { author }),
+        ...(description && { description }),
+    };
+}
+
+// A video authored in markdown: `![alt](./demo.mp4){role=video …}`.
+//
+// Distinct from parseVideoBlock below, which reads the EDITOR's `Video` node
+// (`coverImg`, `info`). The two surfaces name the same concepts differently and
+// collapsing them would drop one side's spelling; this reader carries the
+// 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) {
+    const {
+        src,
+        url,
+        info,
+        poster,
+        alt = "",
+        caption = "",
+        autoplay,
+        muted,
+        loop,
+        controls,
+        href = "",
+        target = "",
+        role,
+        id, // {#fig-id} cross-reference label, same as parseImgBlock
+    } = itemAttrs || {};
+
+    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 }),
+        alt,
+        caption: stripTags(caption),
+        role,
+        href,
+        target,
     };
+
+    // 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;
+    if (autoplay !== undefined) video.autoplay = autoplay;
+    if (muted !== undefined) video.muted = muted;
+    if (loop !== undefined) video.loop = loop;
+    if (controls !== undefined) video.controls = controls;
+    if (id) video.id = id;
+
+    return video;
 }
 
 function parseVideoBlock(itemAttrs) {