@uniweb/semantic-parser 1.2.1 → 1.2.3

package/package.json

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

package/src/index.js

@@ -1,4 +1,4 @@
-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";
 
@@ -46,4 +46,8 @@ 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.
+export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS };

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,
             };
         }
@@ -470,10 +470,23 @@ function getTextContent(content, options = {}) {
         }
     }
 
+    // Icons are emitted as positional markers that a renderer swaps for a real
+    // component (see renderInlineNode). The marker carries the icon's ordinal
+    // among the icons of THIS content array, which is the same order
+    // processInlineElements() puts them in `children` — so a consumer resolves
+    // 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.
+    const iconOrdinals = new Map();
+    let nextIcon = 0;
+    for (const node of content) {
+        if (isIconNode(node)) iconOrdinals.set(node, nextIcon++);
+    }
+
     return groups
         .reduce((prev, group) => {
             const inner = group.nodes.reduce(
-                (acc, node) => acc + renderInlineNode(node),
+                (acc, node) => acc + renderInlineNode(node, iconOrdinals),
                 "",
             );
             if (!inner && !group.link) return prev;
@@ -486,7 +499,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) {
+function renderInlineNode(curr, iconOrdinals) {
     return [curr]
         .reduce((prev, curr) => {
             const { type, marks = [], text } = curr;
@@ -593,6 +606,21 @@ function renderInlineNode(curr) {
                 return prev + `<uniweb-inset data-ref-id="${refId}"></uniweb-inset>`;
             } else if (type === "hardBreak") {
                 return prev + "<br>";
+            } else if (isIconNode(curr)) {
+                // An icon sitting IN the prose — `Click the ![](lu-save) button`.
+                // It rides as a positional marker for the same reason an inline
+                // inset does: the paragraph's text is an HTML string, and an
+                // icon needs a component (kit's <Icon>, which resolves the
+                // library+name against the icon CDN at render time).
+                //
+                // Until 2026-08-12 this fell through to the catch-all below and
+                // the icon vanished — the text kept a gap where it had been, the
+                // entry stayed in `children` and in `content.icons`, and nothing
+                // put it back. Every other inline atom (math, insets) already
+                // had a marker; this was the one that did not.
+                const index = iconOrdinals?.get(curr);
+                if (index === undefined) return prev;
+                return prev + `<uniweb-icon data-index="${index}"></uniweb-icon>`;
             } else {
                 // console.warn(`unhandled text content type: ${type}`, curr);
                 return prev;
@@ -600,7 +628,7 @@ function renderInlineNode(curr) {
         }, "");
 }
 
-function processInlineElements(content) {
+function processInlineElements(content, options = {}) {
     if (!content) return [];
 
     const items = [];
@@ -626,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);
@@ -659,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/";
 
 /**
@@ -667,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);
@@ -787,7 +922,7 @@ function parseIconBlock(itemAttrs) {
     return icon;
 }
 
-function parseImgBlock(itemAttrs) {
+function parseImgBlock(itemAttrs, options) {
     let {
         info: imgInfo,
         targetId,
@@ -834,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;
@@ -873,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 }),
     };
@@ -887,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,
@@ -905,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,
@@ -920,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;
@@ -930,7 +1090,7 @@ function parseMarkdownVideo(itemAttrs) {
     return video;
 }
 
-function parseVideoBlock(itemAttrs) {
+function parseVideoBlock(itemAttrs, options) {
     let {
         src,
         caption = "",
@@ -942,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,
@@ -981,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)
     //
@@ -1039,7 +1198,7 @@ function isLink(item) {
                         iconBefore,
                         iconAfter,
                         // Preserve all inline elements for advanced rendering
-                        children: processInlineElements(originalContent),
+                        children: processInlineElements(originalContent, options),
                     };
                 }
             }
@@ -1104,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 || [];
@@ -1154,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 };