@uniweb/semantic-parser 1.5.0 → 1.6.0

package/README.md

@@ -73,16 +73,22 @@ result = {
 
   // Body fields
   paragraphs: ["Get started today."],
-  links: [],                // All links (including buttons, documents)
+  links: [],                // All links (including buttons)
   images: [],
   videos: [],
+  documents: [],            // Files marked {role=pdf} — { url, name, mime, size?, alt,
+                            //   caption, preview?, … }
   icons: [],
   lists: [],
   quotes: [],
   insets: [],               // Inline @Component references — { refId }
+  media: [],                // Images, videos and insets on their own line, in the
+                            //   order written — each with its `kind`
   snippets: [],             // Fenced code blocks — { language, code }
   data: {},                 // Structured data (tagged data blocks, forms, cards)
   headings: [],             // Only from nested content (quote/list bodies)
+  // tables: [],            // Only when the content has one — { rows, attrs }
+  // math: [],              // Only when the content has one — { id, latex, mathml }
 
   // Additional content groups (from headings after content)
   // Each item has the SAME flat structure as the top level — title,
@@ -197,7 +203,8 @@ A horizontal rule (`---`) explicitly closes the current group and starts a new o
 
 ## Text Formatting
 
-Inline formatting is preserved as HTML tags:
+A text node holds text, and its characters are escaped in the HTML strings the
+parser builds — a `<` someone typed shows as `<`. Marks become tags:
 
 ```js
 // Input: Text with bold mark
@@ -207,33 +214,55 @@ Inline formatting is preserved as HTML tags:
 // Output: "Text with <em>emphasis</em>"
 
 // Input: Link mark
-// Output: "Click <a href=\"/docs\">here</a>"
+// Output: "Click <a href=\"/docs\" target=\"_self\">here</a>"
 
-// Input: Span mark (bracketed spans)
-// Output: "This is <span class=\"highlight\">highlighted</span> text"
+// Input: Span mark (a named style, `[text]{highlight}`)
+// Output: "This is <span highlight=\"true\">highlighted</span> text"
 ```
 
+A link is drawn only when its URL may be followed — relative, or `http:`,
+`https:`, `mailto:`, `tel:`, `page:` or `topic:`. Any other, such as
+`javascript:`, leaves its text unlinked. A `button` mark is a link whose `role`
+is `button`.
+
 ### Span Marks
 
-Bracketed spans (`[text]{.class}`) are converted to `<span>` elements with their attributes:
+Bracketed spans are converted to `<span>` elements. A span's style names become
+attributes, which a theme styles by name:
 
 ```js
 // Input mark
-{ type: "span", attrs: { class: "highlight", id: "note-1" } }
+{ type: "span", attrs: { highlight: true, id: "note-1" } }
 
 // Output HTML
-'<span class="highlight" id="note-1">text</span>'
+'<span id="note-1" highlight="true">text</span>'
 ```
 
-Spans can have classes, IDs, and custom attributes. They combine with other marks—a span with bold becomes `<strong><span class="...">text</span></strong>`.
+A span keeps `class`, `id`, `color` and `bg` (CSS colours, as an inline style),
+and style names — a letter, then letters, digits, `_` or `-`, never starting with
+`on`. Anything else is dropped. Spans combine with other marks — a span with bold
+becomes `<strong><span …>text</span></strong>`.
+
+### Safety — `@uniweb/semantic-parser/sanitize`
+
+The rules above, exported for anything that builds or checks content:
+
+| export | what it does |
+|---|---|
+| `escapeText`, `escapeAttribute` | escape a string for a text position or a double-quoted attribute |
+| `isSafeLink(url)` | whether a link may be followed |
+| `isLinkTarget(target)` | one of `_self`, `_blank`, `_parent`, `_top` |
+| `isStyleName(name)`, `isCssColor(value)` | what a span may carry |
+| `sanitizeMathML(mathml)`, `sanitizeSVG(svg)` | rebuild markup content carries by design — a formula, an icon — from an allowlist |
+| `inspectMathML(mathml)` | what `sanitizeMathML` would leave out, reported instead of removed |
+| `allowlists()` | the same rules as data, for an implementation in another language |
 
 ### Inline Insets and Cross-references
 
 The parser handles inline `inset_placeholder` nodes — generated by
-`@uniweb/build`'s content collector when it pulls
+`@uniweb/core` when it builds a block from content holding
 `![alt](@Component){k=v}`, `[text](@Component){k=v}`, `[@key]{k=v}`,
-or `[#id]{k=v}` references out of paragraph content. Two artifacts
-ship to consumers:
+or `[#id]{k=v}` references. Two artifacts ship to consumers:
 
 1. **`children` carries an `inset` entry per placeholder** — each
    carrying the `refId` and `embedKind` (`'text'` for textual sugars

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uniweb/semantic-parser",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Semantic parser for ProseMirror/TipTap content structures",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./sanitize": "./src/sanitize.js"
   },
   "keywords": [
     "prosemirror",

package/src/index.js

@@ -2,6 +2,7 @@ import { processSequence, resolveAssetUrl, ASSET_SLOTS } from "./processors/sequ
 import { processGroups } from "./processors/groups.js";
 import { buildDoc } from "./builders/doc.js";
 import { lintContent } from "./lint.js";
+import { MIME_TYPES, mimeFor } from "./utils/mime.js";
 
 /**
  * Parse ProseMirror/TipTap content into semantic structure
@@ -54,4 +55,6 @@ function parseContent(doc, options = {}) {
 // `lintContent` diagnoses grouping near-misses (see src/lint.js). It never
 // affects a parse — parsing stays deterministic; the judgment lives here so
 // the CLI, the dev server, and an editor surface the same findings.
-export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS, lintContent };
+// `MIME_TYPES` / `mimeFor` are the one extension → media-type table: a document's
+// `mime` here, a file's in the build (src/utils/mime.js).
+export { parseContent, buildDoc, resolveAssetUrl, ASSET_SLOTS, lintContent, MIME_TYPES, mimeFor };

package/src/processors/groups.js

@@ -17,6 +17,7 @@ function flattenGroup(group) {
         videos: group.body.videos || [],
         documents: group.body.documents || [],
         insets: group.body.insets || [],
+        media: group.body.media || [],
         snippets: group.body.snippets || [],
         data: group.body.data || {},
         quotes: group.body.quotes || [],
@@ -69,6 +70,7 @@ function processGroups(sequence, options = {}) {
             lists: [],
             videos: [],
             insets: [],
+            media: [],
             snippets: [],
             data: {},
             quotes: [],
@@ -113,6 +115,7 @@ function processGroups(sequence, options = {}) {
         lists: [],
         videos: [],
         insets: [],
+        media: [],
         data: {},
         quotes: [],
         headings: [],
@@ -306,6 +309,13 @@ function processGroupContent(elements, options = {}) {
         videos: [],
         documents: [],
         insets: [],
+        // ⭐ The group's visual media — each block-level image, video and inset, in the
+        // order written, tagged with its `kind`: what a media slot holds. `images`,
+        // `videos` and `insets` keep what they hold, and keep the author's order only
+        // within one kind; across kinds only this does (and `sequence`). An image
+        // inside a sentence belongs to the text, so it is not here — nor is a
+        // document, which is not visual media.
+        media: [],
         snippets: [],
         paragraphs: [],
         links: [],
@@ -382,11 +392,13 @@ function processGroupContent(elements, options = {}) {
                         body.icons.push(element.attrs);
                     } else {
                         body.images.push(preserveProps);
+                        body.media.push({ ...preserveProps, kind: "image" });
                     }
                     break;
 
                 case "video":
                     body.videos.push(preserveProps);
+                    body.media.push({ ...preserveProps, kind: "video" });
                     break;
 
                 case "document":
@@ -499,6 +511,7 @@ function processGroupContent(elements, options = {}) {
 
                 case "inset":
                     body.insets.push({ refId: element.refId });
+                    body.media.push({ refId: element.refId, kind: "inset" });
                     break;
 
                 case "form":

package/src/processors/sequence.js

@@ -1,19 +1,22 @@
-/**
- * HTML-attribute encoding for values placed inside double-quoted
- * attributes. Backslashes and braces (common in LaTeX) pass through
- * unchanged; only the four characters that are unsafe in this context
- * need replacing.
- *
- * @param {string} s
- * @returns {string}
- */
-function escapeAttr(s) {
-    return String(s)
-        .replace(/&/g, "&")
-        .replace(/"/g, """)
-        .replace(/</g, "&lt;")
-        .replace(/>/g, "&gt;");
-}
+import { mimeFor, fileNameOf } from "../utils/mime.js";
+import {
+    escapeText,
+    escapeAttribute as escapeAttr,
+    sanitizeMathML,
+    sanitizeSVG,
+    isSafeLink,
+    isLinkTarget,
+    isStyleName,
+    isCssColor,
+} from "../sanitize.js";
+
+// ⭐ A text node holds TEXT. Every string this file builds for kit's HTML
+// renderers escapes it, and every attribute value, so content cannot carry a
+// tag, a handler or a script URL into a page. The only markup that passes is
+// rebuilt from an allowlist: a math node's MathML and an icon's SVG
+// (`../sanitize.js`). ⛔ Until 2026-10-14 text was pasted in as stored, on the
+// rule that a text node held HTML — so `<img src=x onerror=…>` written in
+// content ran on the published page, and `if a<b then` showed as `if a`.
 
 /**
  * Check if an inline node is an icon.
@@ -57,9 +60,11 @@ function createSequenceElement(node, options = {}) {
     const attrs = node.attrs;
     const content = node.content;
 
+    // A link whose URL may not be followed is not a link: the paragraph falls
+    // through to ordinary text, where `anchor` leaves its label unlinked.
     const linkVal = isLink(node, options);
 
-    if (linkVal) {
+    if (linkVal && isSafeLink(linkVal.href)) {
         return {
             type: "link",
             attrs: linkVal, //label, href
@@ -68,7 +73,7 @@ function createSequenceElement(node, options = {}) {
 
     // Check for paragraph containing only multiple links (no other text)
     const multipleLinks = isOnlyLinks(node);
-    if (multipleLinks) {
+    if (multipleLinks && multipleLinks.every((l) => isSafeLink(l.attrs?.href))) {
         return multipleLinks; // Returns array of link elements
     }
 
@@ -199,7 +204,7 @@ function createSequenceElement(node, options = {}) {
                 display: true,
                 id: node.attrs?.id || null,
                 latex: node.attrs?.latex || "",
-                mathml: node.attrs?.mathml || "",
+                mathml: sanitizeMathML(node.attrs?.mathml || ""),
                 attrs,
             };
         case "ImageBlock":
@@ -399,11 +404,29 @@ const FILE_LINK_EXTENSIONS = [
     "mp4", "mp3", "wav", "mov", "zip",
 ];
 
+/**
+ * A text's link, if it carries one: its `link` mark, or its `button` mark read
+ * as a link whose `role` is `button` — a button is a link, with a hint for how
+ * a component may draw it (`[Go](/x){button}`, documented in
+ * docs/reference/content-structure.md). ⛔ Until 2026-10-14 nothing here read
+ * the `button` mark: its label reached the page as plain text and the link was
+ * lost, wherever it sat.
+ */
+function linkMarkOf(marks) {
+    for (const mark of marks || []) {
+        if (mark?.type === "link") return mark;
+        if (mark?.type === "button") {
+            return { type: "link", attrs: { ...mark.attrs, role: mark.attrs?.role ?? "button" } };
+        }
+    }
+    return null;
+}
+
 /**
  * Find a node's link mark, if it carries one.
  */
 function getLinkMark(node) {
-    return (node?.marks || []).find((mark) => mark.type === "link") || null;
+    return linkMarkOf(node?.marks);
 }
 
 /**
@@ -422,12 +445,21 @@ function sameLink(a, b) {
  * Wrap already-styled inline content in an anchor.
  */
 function wrapLink(inner, linkMark) {
-    const href = linkMark.attrs.href;
-    const target = linkMark.attrs.target || "_self";
+    return anchor(linkMark.attrs.href, linkMark.attrs.target, inner);
+}
+
+/**
+ * An anchor around already-escaped inner HTML. A link whose URL may not be
+ * followed (`javascript:`, `data:`, any scheme `isSafeLink` refuses) is not
+ * drawn as a link: its label stays, as text.
+ */
+function anchor(href, target, inner) {
+    if (typeof href !== "string" || !isSafeLink(href)) return inner;
+    const t = isLinkTarget(target) ? target : "_self";
     const extension = href.split(".").pop()?.toLowerCase();
     const isFileLink = FILE_LINK_EXTENSIONS.includes(extension);
 
-    return `<a href="${href}" target="${target}"${isFileLink ? " download" : ""}>${inner}</a>`;
+    return `<a href="${escapeAttr(href)}" target="${t}"${isFileLink ? " download" : ""}>${inner}</a>`;
 }
 
 function getTextContent(content, options = {}) {
@@ -483,7 +515,7 @@ function renderInlineNode(curr, iconOrdinals) {
             const { type, marks = [], text } = curr;
 
             if (type === "text") {
-                let styledText = text || "";
+                let styledText = escapeText(text || "");
 
                 // Apply marks in order: textStyle, highlight, bold, italic, link
                 // This ensures proper nesting
@@ -493,7 +525,8 @@ function renderInlineNode(curr, iconOrdinals) {
                     const color = marks.find(
                         (mark) => mark.type === "textStyle"
                     )?.attrs?.color;
-                    if (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>`;
                     }
                 }
@@ -510,18 +543,23 @@ function renderInlineNode(curr, iconOrdinals) {
                     const attrParts = [];
                     const styleParts = [];
 
-                    if (attrs.class) attrParts.push(`class="${attrs.class}"`);
-                    if (attrs.id) attrParts.push(`id="${attrs.id}"`);
+                    if (attrs.class) attrParts.push(`class="${escapeAttr(attrs.class)}"`);
+                    if (attrs.id) attrParts.push(`id="${escapeAttr(attrs.id)}"`);
 
                     for (const [key, value] of Object.entries(attrs)) {
                         if (key === 'class' || key === 'id') continue;
                         // Convert color/bg to inline styles
-                        if (key === 'color') {
-                            styleParts.push(`color: ${value}`);
-                        } else if (key === 'bg') {
-                            styleParts.push(`background: ${value}`);
-                        } else {
-                            attrParts.push(`${key}="${value}"`);
+                        if (key === 'color' || key === 'bg') {
+                            if (isCssColor(value)) {
+                                styleParts.push(`${key === 'color' ? 'color' : 'background'}: ${value}`);
+                            }
+                        } else if (isStyleName(key)) {
+                            // A named inline style becomes an attribute of its
+                            // span — `[text]{accent}` is `<span accent="true">`
+                            // — so the name is held to a style name: never a
+                            // handler, a URL or a style attribute, nothing a
+                            // pasted value can turn into one.
+                            attrParts.push(`${key}="${escapeAttr(value)}"`);
                         }
                     }
 
@@ -566,7 +604,7 @@ function renderInlineNode(curr, iconOrdinals) {
                 // The wrapper is visually invisible; the inner <math>
                 // still renders as MathML in the browser.
                 const latex = escapeAttr(curr.attrs?.latex || "");
-                const mathml = curr.attrs?.mathml || "";
+                const mathml = sanitizeMathML(curr.attrs?.mathml || "");
                 return (
                     prev +
                     `<span data-type="math" data-latex="${latex}" data-display="false">${mathml}</span>`
@@ -581,7 +619,7 @@ function renderInlineNode(curr, iconOrdinals) {
                 // have an alternative path.
                 const refId = curr.attrs?.refId;
                 if (!refId) return prev;
-                return prev + `<uniweb-inset data-ref-id="${refId}"></uniweb-inset>`;
+                return prev + `<uniweb-inset data-ref-id="${escapeAttr(refId)}"></uniweb-inset>`;
             } else if (type === "hardBreak") {
                 return prev + "<br>";
             } else if (isIconNode(curr)) {
@@ -651,8 +689,8 @@ function processInlineElements(content, options = {}) {
             });
         } else if (item.type === "text" && item.marks) {
             // Extract links from text nodes with link marks
-            const linkMark = item.marks.find((m) => m.type === "link");
-            if (linkMark) {
+            const linkMark = linkMarkOf(item.marks);
+            if (linkMark && isSafeLink(linkMark.attrs?.href)) {
                 items.push({
                     type: "link",
                     attrs: {
@@ -830,6 +868,7 @@ function parseMarkdownDocument(itemAttrs, options) {
         parseImgBlock(itemAttrs || {}, options);
     return {
         url,
+        ...fileFacts(url, itemAttrs),
         alt,
         caption,
         role,
@@ -842,6 +881,25 @@ function parseMarkdownDocument(itemAttrs, options) {
     };
 }
 
+/**
+ * A document's file, as a file record's value names it: `name` (the file's name) and
+ * `mime` from its address, and `size` — known only where the file is — when a
+ * producer stamped one. A stamped `name` or `mime` wins over the address: the build
+ * copies a local file under a hashed name, so it stamps the one the author gave it.
+ * ✅ The field names are a file record's [Diego, 2026-09-29], so one component can
+ * render a downloads list from either.
+ */
+function fileFacts(url, attrs = {}) {
+    const name = typeof attrs?.name === "string" && attrs.name ? attrs.name : fileNameOf(url);
+    const mime = typeof attrs?.mime === "string" && attrs.mime ? attrs.mime : name ? mimeFor(name) : "";
+    const size = Number.isFinite(attrs?.size) ? attrs.size : null;
+    return {
+        ...(name && { name }),
+        ...(mime && { mime }),
+        ...(size !== null && { size }),
+    };
+}
+
 // The editor's older `document` node — its `title`, `coverImg` and `src` (or
 // asset identifier) — read into the same shape a markdown document has.
 function documentFromEditorNode(itemAttrs) {
@@ -855,8 +913,10 @@ function documentFromEditorNode(itemAttrs) {
         description,
         fileType,
     } = parseDocumentBlock(itemAttrs || {});
+    const url = href || downloadUrl || "";
     return {
-        url: href || downloadUrl || "",
+        url,
+        ...fileFacts(url, itemAttrs),
         alt: alt || title,
         caption: title,
         role: "pdf",
@@ -896,7 +956,8 @@ function parseUniwebIcon(itemAttrs) {
     // Markdown pipeline: library + name (resolved at runtime via CDN)
     //                    OR a file, which arrives as `src`
     const icon = {};
-    if (svg) icon.svg = svg;
+    // Markup from content, so rebuilt from the SVG allowlist (`../sanitize.js`).
+    if (svg) icon.svg = sanitizeSVG(svg);
     // 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
@@ -944,7 +1005,7 @@ function parseIconBlock(itemAttrs) {
     const { svg, theme } = itemAttrs || {};
 
     const icon = {};
-    if (svg) icon.svg = svg;
+    if (svg) icon.svg = sanitizeSVG(svg);
     if (theme) icon.theme = theme;
 
     return icon;
@@ -1192,43 +1253,39 @@ function isLink(item, options = {}) {
 
         if (textContent.length === 1) {
             let contentItem = textContent[0];
-            let marks = contentItem?.marks || [];
-
-            for (let l = 0; l < marks.length; l++) {
-                let mark = marks[l];
-
-                if (mark?.type === "link") {
-                    // Find the position of the link text in the original content
-                    const linkIndex = originalContent.findIndex(
-                        (c) => c.type === "text" && c.text === contentItem.text
-                    );
-
-                    // Collect icons before and after the link text
-                    let iconBefore = null;
-                    let iconAfter = null;
-
-                    for (let i = 0; i < originalContent.length; i++) {
-                        if (isIconNode(originalContent[i])) {
-                            const iconAttrs = parseUniwebIcon(originalContent[i].attrs);
-                            if (i < linkIndex) {
-                                // Take the last icon before the link
-                                iconBefore = iconAttrs;
-                            } else if (i > linkIndex) {
-                                // Take the first icon after the link
-                                if (!iconAfter) iconAfter = iconAttrs;
-                            }
+            const mark = linkMarkOf(contentItem?.marks);
+
+            if (mark) {
+                // Find the position of the link text in the original content
+                const linkIndex = originalContent.findIndex(
+                    (c) => c.type === "text" && c.text === contentItem.text
+                );
+
+                // Collect icons before and after the link text
+                let iconBefore = null;
+                let iconAfter = null;
+
+                for (let i = 0; i < originalContent.length; i++) {
+                    if (isIconNode(originalContent[i])) {
+                        const iconAttrs = parseUniwebIcon(originalContent[i].attrs);
+                        if (i < linkIndex) {
+                            // Take the last icon before the link
+                            iconBefore = iconAttrs;
+                        } else if (i > linkIndex) {
+                            // Take the first icon after the link
+                            if (!iconAfter) iconAfter = iconAttrs;
                         }
                     }
-
-                    return {
-                        ...mark?.attrs,  // Preserve all link attributes (role, target, etc.)
-                        label: contentItem?.text || "",
-                        iconBefore,
-                        iconAfter,
-                        // Preserve all inline elements for advanced rendering
-                        children: processInlineElements(originalContent, options),
-                    };
                 }
+
+                return {
+                    ...mark?.attrs,  // Preserve all link attributes (role, target, etc.)
+                    label: contentItem?.text || "",
+                    iconBefore,
+                    iconAfter,
+                    // Preserve all inline elements for advanced rendering
+                    children: processInlineElements(originalContent, options),
+                };
             }
         }
     }
@@ -1268,8 +1325,7 @@ function isOnlyLinks(item) {
     // Check if ALL remaining content items are text nodes with link marks
     const allLinks = textContent.every((c) => {
         if (c.type !== "text") return false;
-        const hasLinkMark = c.marks?.some((m) => m.type === "link");
-        return hasLinkMark;
+        return Boolean(linkMarkOf(c.marks));
     });
 
     if (!allLinks) return false;
@@ -1277,7 +1333,7 @@ function isOnlyLinks(item) {
     // Extract links with all their attributes
     // Icons in this paragraph go to body.icons separately (no association)
     return textContent.map((c) => {
-        const linkMark = c.marks.find((m) => m.type === "link");
+        const linkMark = linkMarkOf(c.marks);
         return {
             type: "link",
             attrs: {
@@ -1307,18 +1363,11 @@ function isStyledLink(item, options = {}) {
     });
 
     // check if all content items have the same link mark
-    let firstLinkMark = content[0]?.marks?.find(
-        (mark) => mark.type === "link" && mark.attrs
-    );
-    if (!firstLinkMark) return false;
+    let firstLinkMark = linkMarkOf(content[0]?.marks);
+    if (!firstLinkMark?.attrs) return false;
     if (
         !content.every(
-            (c) =>
-                c?.marks?.some(
-                    (mark) =>
-                        mark.type === "link" &&
-                        mark.attrs?.href === firstLinkMark.attrs?.href
-                ) || false
+            (c) => linkMarkOf(c?.marks)?.attrs?.href === firstLinkMark.attrs?.href
         )
     )
         return false;
@@ -1328,7 +1377,7 @@ function isStyledLink(item, options = {}) {
     const cleanedContent = content.map((c) => {
         // remove link marks from content items
         const cleanedMarks =
-            c.marks?.filter((mark) => mark.type !== "link") || [];
+            c.marks?.filter((mark) => mark.type !== "link" && mark.type !== "button") || [];
         return {
             ...c,
             marks: cleanedMarks,
@@ -1342,7 +1391,7 @@ function isStyledLink(item, options = {}) {
     return {
         type: "paragraph",
         children: processInlineElements(item.content, options),
-        text: `<a target="${target}" href="${href}">${textContent}</a>`,
+        text: anchor(href, target, textContent),
         attrs: item.attrs,
     };
 }

package/src/sanitize.js

@@ -0,0 +1,556 @@
+/**
+ * Markup that content may carry, rebuilt from an allowlist.
+ *
+ * Content never carries HTML: a text node holds text, and the parser escapes it
+ * when it builds a string. Two kinds of markup still ride in content, because
+ * they are formats rather than formatting — a math node's MathML, compiled from
+ * the author's LaTeX, and an SVG icon. Neither can be escaped, since the markup
+ * is the point, so each is rebuilt instead: the input is read as tokens, and
+ * only allowed elements and attributes are written back out, with every text
+ * run and attribute value escaped.
+ *
+ * Nothing from the input reaches the output unparsed. A construct this reader
+ * understands differently from a browser can lose content; it cannot carry a
+ * tag through, because every tag in the output was written here.
+ *
+ * @module @uniweb/semantic-parser/sanitize
+ */
+
+// ─── Escaping ────────────────────────────────────────────────────────────────
+
+/**
+ * Escape a string for an HTML text position.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeText(s) {
+    return String(s)
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+
+/**
+ * Escape a string for a double-quoted HTML attribute value.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function escapeAttribute(s) {
+    return escapeText(s).replace(/"/g, "&quot;");
+}
+
+const NAMED = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+/**
+ * Decode the character references a serializer emits: numeric references and
+ * the five XML entities (plus `&nbsp;`). Anything else is left as written, and
+ * is then escaped on the way out — it shows as text, never as markup.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function decodeReferences(s) {
+    if (!s.includes("&")) return s;
+    return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/g, (match, ref) => {
+        if (ref[0] !== "#") return NAMED[ref] ?? match;
+        const code = ref[1] === "x" || ref[1] === "X"
+            ? parseInt(ref.slice(2), 16)
+            : parseInt(ref.slice(1), 10);
+        const valid = code > 0 && code <= 0x10ffff && !(code >= 0xd800 && code <= 0xdfff);
+        return valid ? String.fromCodePoint(code) : "�";
+    });
+}
+
+// ─── Reading tokens ──────────────────────────────────────────────────────────
+
+const TAG = /<(\/?)([A-Za-z][A-Za-z0-9:_.-]*)((?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*(\/?)>/y;
+const ATTRIBUTE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+function readAttributes(source) {
+    const attributes = [];
+    for (const m of source.matchAll(ATTRIBUTE)) {
+        attributes.push([m[1], m[2] ?? m[3] ?? m[4] ?? ""]);
+    }
+    return attributes;
+}
+
+/**
+ * Split markup into text runs, start tags and end tags. Comments, doctypes and
+ * processing instructions come out as `skipped` tokens, which a rebuild leaves
+ * out; CDATA is text; a `<` that opens none of these is text.
+ */
+function* readTokens(input) {
+    let i = 0;
+    while (i < input.length) {
+        const lt = input.indexOf("<", i);
+        if (lt === -1) {
+            yield { type: "text", value: input.slice(i) };
+            return;
+        }
+        if (lt > i) yield { type: "text", value: input.slice(i, lt) };
+
+        if (input.startsWith("<!--", lt)) {
+            const end = input.indexOf("-->", lt + 4);
+            i = end === -1 ? input.length : end + 3;
+            yield { type: "skipped", value: input.slice(lt, i) };
+            continue;
+        }
+        // CDATA is character data: its content is text, escaped like any other.
+        if (input.startsWith("<![CDATA[", lt)) {
+            const end = input.indexOf("]]>", lt + 9);
+            yield { type: "text", value: input.slice(lt + 9, end === -1 ? input.length : end), cdata: true };
+            i = end === -1 ? input.length : end + 3;
+            continue;
+        }
+        if (input[lt + 1] === "!" || input[lt + 1] === "?") {
+            const end = input.indexOf(">", lt);
+            i = end === -1 ? input.length : end + 1;
+            yield { type: "skipped", value: input.slice(lt, i) };
+            continue;
+        }
+
+        TAG.lastIndex = lt;
+        const m = TAG.exec(input);
+        if (!m) {
+            yield { type: "text", value: "<" };
+            i = lt + 1;
+            continue;
+        }
+        yield {
+            type: m[1] ? "end" : "start",
+            name: m[2],
+            attributes: m[1] ? [] : readAttributes(m[3]),
+            selfClosing: Boolean(m[4]),
+        };
+        i = TAG.lastIndex;
+    }
+}
+
+// ─── Values ──────────────────────────────────────────────────────────────────
+
+const UNSAFE_VALUE = /javascript:|vbscript:|data:text|expression\s*\(|@import|behavior\s*:|-moz-binding/i;
+
+/** `url(…)` is allowed only as a reference within the same document. */
+function onlyLocalUrls(value) {
+    const urls = value.match(/url\s*\(/gi);
+    if (!urls) return true;
+    const local = value.match(/url\s*\(\s*['"]?#[A-Za-z][\w.:-]*['"]?\s*\)/gi) || [];
+    return local.length === urls.length;
+}
+
+/**
+ * A `style` attribute, declaration by declaration: a property name and a value
+ * with no URL other than a local reference, and nothing that can open another
+ * construct. Blank declarations (`a:b;;`, a trailing `;`) are neither.
+ */
+function readStyle(value) {
+    const kept = [];
+    const dropped = [];
+    for (const declaration of value.split(";")) {
+        if (!declaration.trim()) continue;
+        const colon = declaration.indexOf(":");
+        const property = colon === -1 ? "" : declaration.slice(0, colon).trim().toLowerCase();
+        const v = colon === -1 ? "" : declaration.slice(colon + 1).trim();
+        if (
+            !/^-?[a-z][a-z-]*$/.test(property) || !v ||
+            /[\\<>{}]|\/\*/.test(v) || UNSAFE_VALUE.test(v) || !onlyLocalUrls(v)
+        ) {
+            dropped.push(declaration.trim());
+            continue;
+        }
+        kept.push(`${property}:${v}`);
+    }
+    return { kept, dropped };
+}
+
+function cleanStyle(value) {
+    const { kept } = readStyle(value);
+    return kept.length ? kept.join(";") + ";" : null;
+}
+
+/**
+ * The schemes a link may use: the web, mail and phone, and the framework's own
+ * references to a page (`page:`, and the older `topic:`), which kit resolves to
+ * a route at render.
+ */
+const LINK_SCHEMES = new Set(["http", "https", "mailto", "tel", "page", "topic"]);
+
+/** A link a document may follow: relative, or one of LINK_SCHEMES. */
+function isSafeUrl(value) {
+    const v = value.replace(/[\u0000- \u007f]/g, "");
+    const scheme = v.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+    if (!scheme) return true;
+    return LINK_SCHEMES.has(scheme[1].toLowerCase());
+}
+
+const RASTER_DATA = /^data:image\/(?:png|jpeg|gif|webp|avif);base64,[A-Za-z0-9+/=\s]+$/i;
+
+// ─── Policies ────────────────────────────────────────────────────────────────
+
+/** Elements whose content is dropped along with them. */
+const DROP_WITH_CONTENT = new Set([
+    "script", "style", "foreignobject", "iframe", "object", "embed", "noscript",
+    "template", "textarea", "xmp", "noembed", "noframes", "annotation-xml",
+    "animate", "set", "animatemotion", "animatetransform", "mglyph", "maction",
+]);
+
+/** Attributes either policy accepts on any allowed element. */
+function isCommonAttribute(name) {
+    return name === "class" || name === "id" || name === "role" || name === "dir" ||
+        /^aria-[a-z]+$/.test(name) || /^data-[a-z0-9-]+$/.test(name);
+}
+
+function byLowercase(names) {
+    return new Map(names.map((n) => [n.toLowerCase(), n]));
+}
+
+const MATHML_ELEMENTS = byLowercase([
+    "math", "semantics", "annotation", "mrow", "mi", "mn", "mo", "ms", "mtext",
+    "mspace", "mfrac", "msqrt", "mroot", "mstyle", "merror", "mpadded", "mphantom",
+    "menclose", "msub", "msup", "msubsup", "munder", "mover", "munderover",
+    "mmultiscripts", "mprescripts", "none", "mtable", "mtr", "mtd", "mlabeledtr",
+    // temml wraps LaTeX it cannot compile in a span carrying the source.
+    "span",
+]);
+
+const MATHML_ATTRIBUTES = byLowercase([
+    "xmlns", "display", "displaystyle", "scriptlevel", "mathvariant", "mathcolor",
+    "mathbackground", "mathsize", "stretchy", "fence", "separator", "form",
+    "lspace", "rspace", "largeop", "movablelimits", "accent", "accentunder",
+    "symmetric", "minsize", "maxsize", "width", "height", "depth", "voffset",
+    "linethickness", "numalign", "denomalign", "bevelled", "notation",
+    "columnalign", "rowalign", "columnspacing", "rowspacing", "columnlines",
+    "rowlines", "columnwidth", "frame", "framespacing", "equalrows",
+    "equalcolumns", "rowspan", "columnspan", "side", "encoding", "intent", "arg",
+    "style",
+]);
+
+const SVG_ELEMENTS = byLowercase([
+    "svg", "g", "path", "circle", "ellipse", "line", "polyline", "polygon", "rect",
+    "defs", "linearGradient", "radialGradient", "stop", "clipPath", "mask",
+    "pattern", "symbol", "use", "title", "desc", "text", "tspan", "image",
+    "marker", "filter", "feGaussianBlur", "feOffset", "feBlend", "feColorMatrix",
+    "feComposite", "feFlood", "feMerge", "feMergeNode", "feDropShadow",
+    "feMorphology",
+]);
+
+const SVG_ATTRIBUTES = byLowercase([
+    "xmlns", "xmlns:xlink", "xml:space", "version", "viewBox",
+    "preserveAspectRatio", "width", "height", "x", "y", "x1", "y1", "x2", "y2",
+    "cx", "cy", "r", "rx", "ry", "fx", "fy", "d", "points", "pathLength",
+    "transform", "fill", "fill-opacity", "fill-rule", "stroke", "stroke-width",
+    "stroke-linecap", "stroke-linejoin", "stroke-miterlimit", "stroke-dasharray",
+    "stroke-dashoffset", "stroke-opacity", "opacity", "clip-path", "clip-rule",
+    "mask", "color", "display", "visibility", "overflow", "vector-effect",
+    "shape-rendering", "text-rendering", "font-family", "font-size",
+    "font-weight", "font-style", "text-anchor", "dominant-baseline",
+    "alignment-baseline", "letter-spacing", "word-spacing", "dx", "dy", "rotate",
+    "textLength", "lengthAdjust", "offset", "stop-color", "stop-opacity",
+    "gradientUnits", "gradientTransform", "spreadMethod", "patternUnits",
+    "patternContentUnits", "patternTransform", "clipPathUnits", "maskUnits",
+    "maskContentUnits", "markerWidth", "markerHeight", "markerUnits", "refX",
+    "refY", "orient", "marker-start", "marker-mid", "marker-end", "filter",
+    "filterUnits", "primitiveUnits", "in", "in2", "result", "stdDeviation",
+    "mode", "operator", "k1", "k2", "k3", "k4", "values", "type", "flood-color",
+    "flood-opacity", "radius", "color-interpolation-filters", "focusable",
+    "style", "href", "xlink:href",
+]);
+
+/** Where an SVG element may point: a fragment, or for an image a safe URL. */
+function svgReference(element, value) {
+    const v = value.trim();
+    if (v.startsWith("#")) return /^#[A-Za-z][\w.:-]*$/.test(v) ? v : null;
+    if (element === "image") return RASTER_DATA.test(v) || (isSafeUrl(v) && !/^data:/i.test(v)) ? v : null;
+    return null;
+}
+
+function makePolicy(elements, attributes, reference) {
+    return {
+        element(name) {
+            return elements.get(name.toLowerCase()) ?? null;
+        },
+        attribute(element, name, value) {
+            const lower = name.toLowerCase();
+            if (lower.startsWith("on")) return null;
+            if (lower === "href" || lower === "xlink:href" || lower === "src") {
+                if (!attributes.has(lower)) return null;
+                const target = reference ? reference(element, value) : null;
+                return target === null ? null : [attributes.get(lower), target];
+            }
+            if (lower === "style") {
+                const style = cleanStyle(value);
+                return style === null ? null : ["style", style];
+            }
+            const canonical = attributes.get(lower) ?? (isCommonAttribute(lower) ? lower : null);
+            if (!canonical) return null;
+            if (UNSAFE_VALUE.test(value) || !onlyLocalUrls(value)) return null;
+            return [canonical, value];
+        },
+    };
+}
+
+const MATHML = makePolicy(MATHML_ELEMENTS, MATHML_ATTRIBUTES, null);
+const SVG = makePolicy(SVG_ELEMENTS, SVG_ATTRIBUTES, svgReference);
+
+// ─── Rebuilding ──────────────────────────────────────────────────────────────
+
+function rebuild(input, policy) {
+    if (typeof input !== "string" || !input) return "";
+    let out = "";
+    let dropping = null;
+    let depth = 0;
+
+    for (const token of readTokens(input)) {
+        if (dropping) {
+            const name = token.name?.toLowerCase();
+            if (token.type === "start" && name === dropping && !token.selfClosing) depth++;
+            if (token.type === "end" && name === dropping && --depth === 0) dropping = null;
+            continue;
+        }
+        if (token.type === "skipped") continue;
+        if (token.type === "text") {
+            out += escapeText(token.cdata ? token.value : decodeReferences(token.value));
+            continue;
+        }
+
+        const lower = token.name.toLowerCase();
+        if (DROP_WITH_CONTENT.has(lower)) {
+            if (token.type === "start" && !token.selfClosing) {
+                dropping = lower;
+                depth = 1;
+            }
+            continue;
+        }
+
+        const element = policy.element(token.name);
+        if (!element) continue; // the tag goes; what it held stays
+
+        if (token.type === "end") {
+            out += `</${element}>`;
+            continue;
+        }
+
+        let attributes = "";
+        const seen = new Set();
+        for (const [name, raw] of token.attributes) {
+            const kept = policy.attribute(element, name, decodeReferences(raw));
+            if (!kept || seen.has(kept[0])) continue;
+            seen.add(kept[0]);
+            attributes += ` ${kept[0]}="${escapeAttribute(kept[1])}"`;
+        }
+        out += token.selfClosing ? `<${element}${attributes}/>` : `<${element}${attributes}>`;
+    }
+    return out;
+}
+
+/**
+ * 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).
+ */
+function inspect(input, policy) {
+    const outside = [];
+    let dropping = null;
+    let depth = 0;
+
+    for (const token of readTokens(input)) {
+        if (dropping) {
+            const name = token.name?.toLowerCase();
+            if (token.type === "start" && name === dropping && !token.selfClosing) depth++;
+            if (token.type === "end" && name === dropping && --depth === 0) dropping = null;
+            continue;
+        }
+        if (token.type === "text") continue;
+        if (token.type === "skipped") {
+            outside.push({ reason: "markup", value: token.value.slice(0, 40) });
+            continue;
+        }
+        if (token.type === "end") continue; // a start tag already answered for it
+
+        const lower = token.name.toLowerCase();
+        const element = DROP_WITH_CONTENT.has(lower) ? null : policy.element(token.name);
+        if (!element) {
+            outside.push({ reason: "element", element: token.name });
+            if (DROP_WITH_CONTENT.has(lower) && !token.selfClosing) {
+                dropping = lower;
+                depth = 1;
+            }
+            continue;
+        }
+        for (const [name, raw] of token.attributes) {
+            const value = decodeReferences(raw);
+            if (name.toLowerCase() === "style") {
+                const { dropped } = readStyle(value);
+                if (dropped.length) {
+                    outside.push({ reason: "style", element, attribute: name, value: dropped.join("; ") });
+                }
+                continue;
+            }
+            if (!policy.attribute(element, name, value)) {
+                outside.push({ reason: "attribute", element, attribute: name });
+            }
+        }
+    }
+    return outside;
+}
+
+/**
+ * Rebuild MathML from its allowlist — MathML Core, the presentation elements a
+ * LaTeX compiler emits, and temml's error span. No element can link, load or
+ * run anything.
+ *
+ * @param {string} mathml
+ * @returns {string} the rebuilt markup; empty when nothing survives
+ */
+export function sanitizeMathML(mathml) {
+    return rebuild(mathml, 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.
+ *
+ * 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}>}
+ */
+export function inspectMathML(mathml) {
+    if (typeof mathml !== "string" || !mathml) return [];
+    return inspect(mathml, MATHML);
+}
+
+/**
+ * Rebuild SVG from its allowlist — shapes, gradients, masks, text and simple
+ * filters. A reference may only point inside the document, and an `image` only
+ * at a raster image. Scripts, event handlers, `foreignObject` and animations,
+ * which can rewrite an attribute after the fact, are dropped.
+ *
+ * Accepts a whole `<svg>` or a fragment of its content.
+ *
+ * @param {string} svg
+ * @returns {string} the rebuilt markup; empty when nothing survives
+ */
+export function sanitizeSVG(svg) {
+    return rebuild(svg, SVG);
+}
+
+/**
+ * Whether a link may be followed: a relative URL, or `http:`, `https:`,
+ * `mailto:`, `tel:`, or the framework's `page:` / `topic:` references. Control
+ * characters and spaces are ignored when reading the scheme, as a browser
+ * ignores them, so `java\tscript:` is read as `javascript:`.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+export function isSafeLink(url) {
+    return typeof url === "string" && isSafeUrl(url);
+}
+
+// ─── Values content may hold ─────────────────────────────────────────────────
+//
+// The rules below decide what a text's marks may put into the markup the parser
+// builds. The parser applies them at render, and a writer of content can check
+// against the same functions (`@uniweb/content-reader/vocabulary`), so the two
+// never disagree about what a value may be.
+
+const LINK_TARGETS = ["_self", "_blank", "_parent", "_top"];
+const LINK_TARGET_SET = new Set(LINK_TARGETS);
+
+/**
+ * Whether a link may open in this target: the four keywords a browser defines.
+ * A frame name is not one — content does not know the page's frames.
+ *
+ * @param {string} target
+ * @returns {boolean}
+ */
+export function isLinkTarget(target) {
+    return LINK_TARGET_SET.has(target);
+}
+
+const STYLE_NAME = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+/** Attribute names a browser reads as a URL, a style or an element's identity. */
+const NOT_A_STYLE_NAME = [
+    "href", "src", "srcset", "srcdoc", "action", "formaction", "style",
+    "background", "poster", "xmlns", "is", "slot",
+];
+const NOT_A_STYLE_NAME_SET = new Set(NOT_A_STYLE_NAME);
+
+/**
+ * Whether a name may be a style name — the attribute NAME a bracketed span
+ * carries (`[text]{accent}` is `<span accent="true">`), which a theme binds by
+ * name (`span[accent]`, from theme.yml's `inline:`). A letter, then letters,
+ * digits, `_` and `-`. Never a name a browser would read as an event handler —
+ * anything starting with `on`, in any case, since HTML lowercases attribute
+ * names — nor one it reads as a URL, a style or an element's identity.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isStyleName(name) {
+    if (typeof name !== "string" || !STYLE_NAME.test(name)) return false;
+    const lower = name.toLowerCase();
+    return !lower.startsWith("on") && !NOT_A_STYLE_NAME_SET.has(lower);
+}
+
+const CSS_COLOR = /^[#a-zA-Z0-9(),.%\s+-]+$/;
+const NOT_A_COLOR = /url\s*\(|expression\s*\(/i;
+
+/**
+ * Whether a value is a CSS colour — a name, a hex, a colour function, or
+ * `var(--token)` — what a span's `color` and `bg` may set. No `;`, quote or
+ * URL, so it cannot end the declaration it sits in or load anything.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isCssColor(value) {
+    return typeof value === "string" && CSS_COLOR.test(value) && !NOT_A_COLOR.test(value);
+}
+
+/**
+ * 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
+ * here is the one the functions above use.
+ *
+ * @returns {Object}
+ */
+export function allowlists() {
+    return {
+        link: {
+            schemes: [...LINK_SCHEMES],
+            relative: "a URL with no scheme",
+            readingTheScheme: "ASCII control characters, space and DEL are ignored, as a browser ignores them",
+            targets: [...LINK_TARGETS],
+        },
+        styleName: {
+            pattern: STYLE_NAME.source,
+            notStartingWith: "on, in any case",
+            not: [...NOT_A_STYLE_NAME],
+        },
+        color: {
+            pattern: CSS_COLOR.source,
+            notMatching: NOT_A_COLOR.source,
+            flags: "i",
+        },
+        mathml: {
+            elements: [...MATHML_ELEMENTS.values()],
+            attributes: [...MATHML_ATTRIBUTES.values()],
+            commonAttributes: "class, id, role, dir, aria-<letters>, data-<letters, digits and ->",
+            droppedWithContent: [...DROP_WITH_CONTENT],
+            neverAttributes: "on…, in any case; href, xlink:href and src",
+            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",
+        },
+    };
+}

package/src/utils/mime.js

@@ -0,0 +1,90 @@
+/**
+ * What a file is, by its extension — the one extension → media-type table.
+ *
+ * ⭐ ONE TABLE, HERE, because two producers need it and this is the package both can
+ * reach: the parser gives a document its `mime` from its address, and the build gives
+ * a file record — and a document file it copies — theirs (`@uniweb/build`'s
+ * `site/file-records.js` imports `mimeFor` from here, as it imports `ASSET_SLOTS`).
+ * The parser has no dependencies, so the table cannot live in the build and be
+ * reached from here. ⛔ Do not write a second.
+ *
+ * Anything not here is `application/octet-stream`.
+ */
+export const MIME_TYPES = {
+    pdf: "application/pdf",
+    doc: "application/msword",
+    docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    xls: "application/vnd.ms-excel",
+    xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ppt: "application/vnd.ms-powerpoint",
+    pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    odt: "application/vnd.oasis.opendocument.text",
+    ods: "application/vnd.oasis.opendocument.spreadsheet",
+    odp: "application/vnd.oasis.opendocument.presentation",
+    rtf: "application/rtf",
+    epub: "application/epub+zip",
+    zip: "application/zip",
+    gz: "application/gzip",
+    tar: "application/x-tar",
+    csv: "text/csv",
+    tsv: "text/tab-separated-values",
+    txt: "text/plain",
+    md: "text/markdown",
+    json: "application/json",
+    xml: "application/xml",
+    yml: "application/yaml",
+    yaml: "application/yaml",
+    html: "text/html",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    svg: "image/svg+xml",
+    webp: "image/webp",
+    avif: "image/avif",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    m4a: "audio/mp4",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mov: "video/quicktime",
+};
+
+/**
+ * The extension of a file name or path, lower-cased, without its dot — `''` for none,
+ * and for a dotfile (`.env`), as Node's `extname` reads them.
+ */
+function extensionOf(name) {
+    const base = String(name || "").split(/[\\/]/).pop();
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+
+/**
+ * The media type of a file, by its extension.
+ *
+ * @param {string} name - a file name or path
+ * @returns {string}
+ */
+export function mimeFor(name) {
+    return MIME_TYPES[extensionOf(name)] || "application/octet-stream";
+}
+
+/**
+ * The file name an address ends in — `/files/Annual%20report.pdf?v=2` →
+ * `Annual report.pdf` — or `''` when it names none.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function fileNameOf(url) {
+    const text = String(url || "");
+    if (/^data:/i.test(text)) return "";
+    const segment = text.split(/[?#]/)[0].split("/").pop() || "";
+    try {
+        return decodeURIComponent(segment);
+    } catch {
+        return segment;
+    }
+}