@uniweb/semantic-parser 1.9.0 → 1.11.0

package/AGENTS.md

@@ -165,7 +165,7 @@ Key patterns — the staircase rule (each heading relates to the one before it):
 - **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.
+- **Dividers**: a `divider` (`---` in markdown) 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.
 

package/README.md

@@ -280,6 +280,24 @@ or `[#id]{k=v}` references. Two artifacts ship to consumers:
 The two views stay in lockstep — both record every inline inset the
 parser sees, in source order.
 
+### Inline Icons and Pictures
+
+An icon or a picture beside text stays in its paragraph, and it is carried
+the same two ways:
+
+1. **`children` carries an `icon` or an `image` entry** — the icon's library
+   and name, the picture's resolved `url` and its `alt`.
+
+2. **`text` carries a marker at its position** —
+   `<uniweb-icon data-index="N"></uniweb-icon>` or
+   `<uniweb-image data-index="N"></uniweb-image>`, where `N` is its ordinal
+   among the paragraph's icons, or among its pictures
+   (`children.filter(c => c.type === 'image')[N]`).
+
+A renderer that reads `text` as HTML and does not know a marker draws
+nothing for it, as for any empty element it does not know. kit's `<Render>`
+draws an icon with `<Icon>` and a picture with `<Image>`.
+
 ## Use Cases
 
 - **Component-based websites**: Extract structured data for React/Vue components

package/package.json

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

package/src/processors/groups.js

@@ -500,19 +500,10 @@ function processGroupContent(elements, options = {}) {
                     body.media.push({ refId: element.refId, kind: "inset" });
                     break;
 
-                case "form":
-                    // Route a form's 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;
-
+                // ⛔ A `form` element was routed here until 2026-10-18 — the
+                // editor's form node, its data at `data[<schema id>]`, else at
+                // `data.form`. The node is read nowhere now: a form's data is a
+                // tagged data block, which lands at `data[<tag>]` above.
             }
         }
     }

package/src/processors/sequence.js

@@ -22,6 +22,17 @@ function isIconNode(node) {
     return node.type === "image" && node.attrs?.role === "icon";
 }
 
+/**
+ * Is an inline node a picture — an `image` that is not an icon, a video or a
+ * file? These are the nodes processInlineElements() delivers as `image`
+ * children, so the marker's ordinal (getTextContent) counts exactly them.
+ */
+function isInlinePicture(node) {
+    if (node?.type !== "image" || isIconNode(node)) return false;
+    const role = node.attrs?.role;
+    return role !== "video" && role !== "pdf";
+}
+
 /**
  * Process a ProseMirror/TipTap document into a flat sequence
  * @param {Object} doc ProseMirror document
@@ -288,44 +299,26 @@ function createSequenceElement(node, options = {}) {
             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.
+        //
+        // ⭐ The vocabulary's names are the only ones read. ⛔ Until 2026-10-18 the
+        // editor's spellings were read too: `DividerBlock` and `horizontalRule` as
+        // a divider, and its form node — `StructuredContent`, and `FormBlock`, its
+        // name before 2026-07-31 — as a `form` element whose data landed at
+        // `content.data[<schema id>]`. The editor writes `divider` and `dataBlock`
+        // itself now, and no writer produces the others, as none does its
+        // `card-group`, `document-group`, `ImageBlock`, `Video`, `UniwebIcon`,
+        // `Icon` and `button` nodes.
         case "divider":
-        case "DividerBlock":
-        case "horizontalRule":
             return {
                 type: "divider",
                 attrs,
             };
 
-        // The editor's form node. ⛔ Until 2026-10-18 its name before
-        // 2026-07-31, `FormBlock`, was read too — and the editor's `card-group`,
-        // `document-group`, `ImageBlock`, `Video`, `UniwebIcon`, `Icon` and
-        // `button` nodes, which no writer produces now.
-        case "StructuredContent":
-            // Parse form data (can be JSON string or object)
-            let formData = attrs?.data;
-            if (typeof formData === "string") {
-                try {
-                    formData = JSON.parse(formData);
-                } catch (err) {
-                    // Keep as string
-                }
-            }
-
-            return {
-                type: "form",
-                schemaId: attrs?.activeSchemaId || null,
-                data: formData,
-                attrs,
-            };
-
         default:
             return {
                 type: node.type,
@@ -424,16 +417,22 @@ function getTextContent(content, options = {}) {
     // one with `children.filter(c => c.type === 'icon')[index]`. Referencing by
     // ordinal rather than serializing the attrs keeps an inline `svg` blob out
     // of the text stream and leaves `children` the single source of truth.
+    //
+    // A picture beside text is marked the same way, by its ordinal among the
+    // pictures of this array — `children.filter(c => c.type === 'image')[index]`.
     const iconOrdinals = new Map();
+    const pictureOrdinals = new Map();
     let nextIcon = 0;
+    let nextPicture = 0;
     for (const node of content) {
         if (isIconNode(node)) iconOrdinals.set(node, nextIcon++);
+        else if (isInlinePicture(node)) pictureOrdinals.set(node, nextPicture++);
     }
 
     return groups
         .reduce((prev, group) => {
             const inner = group.nodes.reduce(
-                (acc, node) => acc + renderInlineNode(node, iconOrdinals),
+                (acc, node) => acc + renderInlineNode(node, iconOrdinals, pictureOrdinals),
                 "",
             );
             if (!inner && !group.link) return prev;
@@ -446,7 +445,7 @@ function getTextContent(content, options = {}) {
  * Render one inline node to HTML, applying every mark EXCEPT link — the
  * anchor is applied per group by getTextContent, since it may span nodes.
  */
-function renderInlineNode(curr, iconOrdinals) {
+function renderInlineNode(curr, iconOrdinals, pictureOrdinals) {
     return [curr]
         .reduce((prev, curr) => {
             const { type, marks = [], text } = curr;
@@ -454,24 +453,13 @@ function renderInlineNode(curr, iconOrdinals) {
             if (type === "text") {
                 let styledText = escapeText(text || "");
 
-                // Apply marks in order: textStyle, highlight, bold, italic, link
-                // This ensures proper nesting
-
-                // textStyle (color)
-                if (marks.some((mark) => mark.type === "textStyle")) {
-                    const color = marks.find(
-                        (mark) => mark.type === "textStyle"
-                    )?.attrs?.color;
-                    // A theme token's name, or nothing — it lands inside `var(--…)`.
-                    if (typeof color === "string" && /^[a-zA-Z0-9-]+$/.test(color)) {
-                        styledText = `<span style="color: var(--${color})">${styledText}</span>`;
-                    }
-                }
-
-                // highlight
-                if (marks.some((mark) => mark.type === "highlight")) {
-                    styledText = `<span style="background-color: var(--highlight)">${styledText}</span>`;
-                }
+                // Apply marks in order: span, code, bold, italic — the link is
+                // applied per group by getTextContent. This ensures proper nesting.
+                //
+                // ⛔ Until 2026-10-18 the editor's `textStyle` (a theme color) and
+                // `highlight` marks were applied first. The editor saves both as
+                // the vocabulary's `span` — `[x]{accent}`, `[x]{highlight}` — so
+                // neither is read now.
 
                 // span (bracketed spans with class/id/attributes)
                 if (marks.some((mark) => mark.type === "span")) {
@@ -574,6 +562,18 @@ function renderInlineNode(curr, iconOrdinals) {
                 const index = iconOrdinals?.get(curr);
                 if (index === undefined) return prev;
                 return prev + `<uniweb-icon data-index="${index}"></uniweb-icon>`;
+            } else if (isInlinePicture(curr)) {
+                // A picture sitting IN the prose — `as the figure ![](./cells.jpg)
+                // shows` — marked for the icon's reason: a renderer draws it with a
+                // component (kit's <Image>), from the entry processInlineElements()
+                // puts in `children`, its address resolved there.
+                //
+                // ⛔ Until 2026-10-18 it fell through to the catch-all below, as an
+                // icon did before 2026-08-12: the text kept a gap, the picture stayed
+                // in `children` and `content.images`, and a walker drew nothing.
+                const index = pictureOrdinals?.get(curr);
+                if (index === undefined) return prev;
+                return prev + `<uniweb-image data-index="${index}"></uniweb-image>`;
             } else {
                 // console.warn(`unhandled text content type: ${type}`, curr);
                 return prev;

package/src/sanitize.js

@@ -347,9 +347,16 @@ function rebuild(input, policy) {
 
 /**
  * What a rebuild would leave out of `input`, item by item — the same walk as
- * `rebuild`, reporting instead of writing. Empty when the markup is within the
- * policy, which is when a rebuild changes nothing but spelling (quotes,
- * escapes, a style's spacing).
+ * `rebuild`, reporting instead of writing — and, when it leaves nothing out but
+ * writes the markup differently, one `spelling` item at the first difference.
+ * Empty when a rebuild writes `input` back exactly as given.
+ *
+ * ⭐ Exactly, not "up to spelling" (since 2026-10-18): every text run and
+ * attribute value a rebuild writes is escaped, so markup in that form reads the
+ * same to any reader. Markup spelled otherwise — a `<` left in text, a CDATA
+ * section, a reference the rebuild would write as its character — can read one
+ * way here and another way to a reader that parses it as written, which a store
+ * holding it for every reader cannot allow.
  */
 function inspect(input, policy) {
     const outside = [];
@@ -394,6 +401,14 @@ function inspect(input, policy) {
             }
         }
     }
+    if (!outside.length) {
+        const rebuilt = rebuild(input, policy);
+        if (rebuilt !== input) {
+            let at = 0;
+            while (input[at] === rebuilt[at]) at++;
+            outside.push({ reason: "spelling", value: input.slice(at, at + 40) });
+        }
+    }
     return outside;
 }
 
@@ -412,14 +427,16 @@ export function sanitizeMathML(mathml) {
 /**
  * What in a MathML string falls outside the allowlist `sanitizeMathML` rebuilds
  * from: each element and attribute a rebuild drops, each style declaration it
- * drops, and any comment, doctype or processing instruction. Empty when the
- * markup is within it.
+ * drops, and any comment, doctype or processing instruction — or, when it drops
+ * nothing, a `spelling` item if the rebuild writes the markup differently. Empty
+ * when `sanitizeMathML` writes the markup back exactly as given, so a writer
+ * that stores what `sanitizeMathML` returns stores markup within it.
  *
  * This is how content is checked rather than cleaned — a writer refused with
  * what it sent can fix it, where a cleaned value changes without a word.
  *
  * @param {string} mathml
- * @returns {Array<{reason: 'element'|'attribute'|'style'|'markup', element?: string, attribute?: string, value?: string}>}
+ * @returns {Array<{reason: 'element'|'attribute'|'style'|'markup'|'spelling', element?: string, attribute?: string, value?: string}>}
  */
 export function inspectMathML(mathml) {
     if (typeof mathml !== "string" || !mathml) return [];
@@ -443,11 +460,11 @@ export function sanitizeSVG(svg) {
 
 /**
  * What in an SVG string falls outside the allowlist `sanitizeSVG` rebuilds
- * from, reported as `inspectMathML` reports MathML. Empty when the markup is
- * within it.
+ * from, reported as `inspectMathML` reports MathML. Empty when `sanitizeSVG`
+ * writes the markup back exactly as given.
  *
  * @param {string} svg
- * @returns {Array<{reason: 'element'|'attribute'|'style'|'markup', element?: string, attribute?: string, value?: string}>}
+ * @returns {Array<{reason: 'element'|'attribute'|'style'|'markup'|'spelling', element?: string, attribute?: string, value?: string}>}
  */
 export function inspectSVG(svg) {
     if (typeof svg !== "string" || !svg) return [];
@@ -480,8 +497,8 @@ export function isImageSource(url) {
 
 /**
  * Whether a `data:` URL holds an image a page may show: a PNG, JPEG, GIF, WebP
- * or AVIF in base64, or SVG — percent-encoded or base64 — whose markup is within
- * the allowlist `sanitizeSVG` rebuilds from. ⭐ Admitted [Diego, 2026-10-16]: a
+ * or AVIF in base64, or SVG — percent-encoded or base64 — whose markup is
+ * exactly what `sanitizeSVG` writes of it (`inspectSVG`). ⭐ Admitted [Diego, 2026-10-16]: a
  * picture an `<img>` loads runs no script, and a built-in starter image is one.
  * The URL is read as a browser reads it: tab and newline removed, leading and
  * trailing spaces and controls trimmed.
@@ -598,6 +615,14 @@ export function isCssColor(value) {
     return typeof value === "string" && CSS_COLOR.test(value) && !NOT_A_COLOR.test(value);
 }
 
+/** How a rebuild writes markup — what `inspect` compares the input with. */
+const WRITTEN =
+    "exactly as a rebuild writes it: a text run with `&`, `<` and `>` written `&amp;`, `&lt;` and `&gt;`, and every other character as itself; " +
+    "a start tag `<name>` or `<name/>` and an end tag `</name>`, the name as `elements` spells it, with no space before `>` or `/>`; " +
+    "each attribute once, as one space then `name=\"value\"` — the name as `attributes` spells it, or a common one in lower case — " +
+    "with `&`, `<`, `>` and `\"` in the value written `&amp;`, `&lt;`, `&gt;` and `&quot;`; " +
+    "a `style` value as its declarations, each `property:value;` with the property in lower case and the value trimmed";
+
 /**
  * The same rules, as data — for a reader that implements them in another
  * language, such as a backend checking content when it is written. Every list
@@ -632,7 +657,8 @@ export function allowlists() {
             unsafeValue: UNSAFE_VALUE.source,
             urlInAValue: "only url(#id), a reference within the document",
             style: "declaration by declaration: a property of letters and -, a value with none of \\ < > { } /* and no unsafe value",
-            markup: "no comment, doctype or processing instruction; CDATA is text",
+            markup: "no comment, doctype, processing instruction or CDATA section",
+            written: WRITTEN,
         },
         imageData: {
             raster: RASTER_DATA.source,
@@ -649,7 +675,8 @@ export function allowlists() {
                 unsafeValue: UNSAFE_VALUE.source,
                 urlInAValue: "only url(#id), a reference within the document",
                 style: "declaration by declaration: a property of letters and -, a value with none of \\ < > { } /* and no unsafe value",
-                markup: "no comment, doctype or processing instruction; CDATA is text",
+                markup: "no comment, doctype, processing instruction or CDATA section",
+                written: `${WRITTEN}; an \`href\` or \`xlink:href\` value trimmed`,
             },
         },
     };