@longsightgroup/qti3-core 0.5.4 → 0.7.0

package/src/types.ts

@@ -139,6 +139,7 @@ export interface QtiTemplateDeclaration extends QtiVariableDeclaration {
 export interface QtiChoice {
   identifier: string;
   text: string;
+  asset?: QtiObjectAsset | undefined;
   role: QtiChoiceRole;
   qtiName: string;
   attributes: Record<string, string>;
@@ -704,3 +705,13 @@ export interface QtiInteractionElementSupport extends QtiElementSupportBase {
 export interface QtiProcessingElementSupport extends QtiElementSupportBase {
   category: "processing";
 }
+
+export interface SharedVocabularyClassSupport {
+  className: string;
+  scope: "interaction" | "content" | "gap";
+  interactions?: QtiInteractionType[] | undefined;
+  level: "full" | "stylesheet" | "pass-through" | "conditional";
+  fixtures?: string[] | undefined;
+  tests?: string[] | undefined;
+  notes?: string | undefined;
+}

package/src/validation.ts

@@ -5,6 +5,7 @@ import type {
   QtiCatalogCardEntry,
   QtiCardinality,
   QtiChoice,
+  QtiElementContent,
   QtiContentNode,
   QtiDiagnostic,
   QtiDocument,
@@ -20,6 +21,11 @@ import type {
   QtiValue,
   QtiValidationResult,
 } from "./types.js";
+import {
+  validateSharedVocabularyExtendedText,
+  validateSharedVocabularyInputWidth,
+  validateSharedVocabularyMediaPlayerControls,
+} from "./shared-vocabulary-validation.js";
 import { validateQtiDataSsmlMetadata } from "./tts.js";
 import { qtiValueToStringList } from "./value-format.js";
 
@@ -32,6 +38,7 @@ export function validateAssessmentItem(document: QtiDocument): QtiValidationResu
   requireIdentifier("qti-assessment-item", item.identifier, diagnostics, item.source);
   validateAssessmentItemRoot(item, diagnostics);
   validateItemBody(item, diagnostics);
+  validateItemBodySharedVocabulary(item, diagnostics);
   validateDeclarationIdentifiers(item, diagnostics);
   validateOutcomeLookupTables(item, diagnostics);
   validateInteractions(item, diagnostics);
@@ -194,6 +201,73 @@ function validateItemBody(item: QtiAssessmentItem, diagnostics: QtiDiagnostic[])
   });
 }
 
+function validateItemBodySharedVocabulary(
+  item: QtiAssessmentItem,
+  diagnostics: QtiDiagnostic[],
+): void {
+  validateContentSharedVocabulary(item.body, diagnostics);
+}
+
+function validateContentSharedVocabulary(
+  nodes: QtiContentNode[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const node of nodes) {
+    if (node.kind !== "element") continue;
+    validateLayoutVocabularyClasses(node, diagnostics);
+    if (sharedClassNames(node.attributes).includes("qti-layout-row")) {
+      validateLayoutRow(node, diagnostics);
+    }
+    validateContentSharedVocabulary(node.children, diagnostics);
+  }
+}
+
+function validateLayoutVocabularyClasses(
+  node: QtiElementContent,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const classNames = sharedClassNames(node.attributes);
+  for (const className of classNames) {
+    if (isLayoutColumnClassName(className) && layoutColumnValue(className) === undefined) {
+      diagnostics.push({
+        code: "item.sharedVocabulary.layoutColumnInvalid",
+        severity: "warning",
+        message: `Shared vocabulary class ${className} is not supported; expected qti-layout-col1 through qti-layout-col12, or dashed qti-layout-col-1 through qti-layout-col-12.`,
+        path: node.source?.path,
+        source: node.source,
+      });
+    }
+    if (isLayoutOffsetClassName(className) && layoutOffsetValue(className) === undefined) {
+      diagnostics.push({
+        code: "item.sharedVocabulary.layoutOffsetInvalid",
+        severity: "warning",
+        message: `Shared vocabulary class ${className} is not supported; expected qti-layout-offset1 through qti-layout-offset11, or dashed qti-layout-offset-1 through qti-layout-offset-11.`,
+        path: node.source?.path,
+        source: node.source,
+      });
+    }
+  }
+}
+
+function validateLayoutRow(node: QtiElementContent, diagnostics: QtiDiagnostic[]): void {
+  let totalColumns = 0;
+  for (const child of node.children) {
+    if (child.kind !== "element") continue;
+    const classNames = sharedClassNames(child.attributes);
+    const column = firstLayoutColumnValue(classNames);
+    if (column === undefined) continue;
+    totalColumns += (firstLayoutOffsetValue(classNames) ?? 0) + column;
+  }
+  if (totalColumns <= 12) return;
+  diagnostics.push({
+    code: "item.sharedVocabulary.layoutRowOverflow",
+    severity: "warning",
+    message: `qti-layout-row column groupings plus offsets total ${totalColumns}; the QTI shared vocabulary grid allows at most twelve columns per row.`,
+    path: node.source?.path,
+    source: node.source,
+  });
+}
+
 function requireIdentifier(
   elementName: string,
   identifier: string | undefined,
@@ -1592,6 +1666,7 @@ function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDiagnosti
   for (const interaction of item.interactions) {
     validateInteractionResponseReference(interaction, responseIdentifiers, diagnostics);
     validateInteractionResponseShape(interaction, diagnostics);
+    validateInteractionSharedVocabulary(interaction, diagnostics);
     validateInteractionChoices(interaction, diagnostics);
     validateInteractionChildren(interaction, diagnostics);
     validateInteractionRequiredAttributes(interaction, diagnostics);
@@ -1615,6 +1690,385 @@ function validateInteractions(item: QtiAssessmentItem, diagnostics: QtiDiagnosti
   }
 }
 
+function validateInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (
+    interaction.type !== "choice" &&
+    interaction.type !== "match" &&
+    interaction.type !== "gapMatch" &&
+    interaction.type !== "graphicGapMatch" &&
+    interaction.type !== "inlineChoice" &&
+    interaction.type !== "textEntry" &&
+    interaction.type !== "extendedText" &&
+    interaction.type !== "media" &&
+    interaction.type !== "order"
+  ) {
+    return;
+  }
+  const classNames = sharedClassNames(interaction.attributes);
+  const classNameSet = new Set(classNames);
+  if (interaction.type === "media") {
+    validateMediaInteractionSharedVocabulary(interaction, diagnostics);
+    return;
+  }
+
+  if (interaction.type === "inlineChoice" || interaction.type === "textEntry") {
+    validateInteractionInputWidthSharedVocabulary(interaction, classNames, diagnostics);
+    return;
+  }
+
+  if (interaction.type === "extendedText") {
+    diagnostics.push(
+      ...validateSharedVocabularyExtendedText({
+        classNames,
+        subjectQtiName: interaction.qtiName,
+        path: interaction.source?.path,
+        source: interaction.source,
+      }),
+    );
+    return;
+  }
+
+  if (interaction.type === "choice" || interaction.type === "order") {
+    validateSharedVocabularyLabelClasses(interaction, classNames, diagnostics);
+  }
+
+  if (
+    interaction.type === "match" ||
+    interaction.type === "gapMatch" ||
+    interaction.type === "graphicGapMatch"
+  ) {
+    if (interaction.type === "match") {
+      validateMatchInteractionSharedVocabulary(interaction, classNames, diagnostics);
+    }
+    validateChoicesPositionSharedVocabulary(interaction, classNames, diagnostics);
+    validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
+    if (interaction.type === "gapMatch") {
+      validateGapInputWidthSharedVocabulary(interaction, diagnostics);
+    }
+    return;
+  }
+
+  if (interaction.type === "order") {
+    validateOrderInteractionSharedVocabulary(interaction, classNames, classNameSet, diagnostics);
+    return;
+  }
+
+  validateOrientationSharedVocabulary(interaction, classNameSet, diagnostics);
+
+  const validStackingClasses = new Set<string>();
+  const invalidStackingClasses = new Set<string>();
+  for (const className of classNames) {
+    const stacking = /^qti-choices-stacking-(\d+)$/.exec(className)?.[1];
+    if (stacking === undefined) continue;
+    const count = Number(stacking);
+    if (count >= 1 && count <= 5) validStackingClasses.add(className);
+    else invalidStackingClasses.add(className);
+  }
+
+  if (validStackingClasses.size > 1) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.stackingConflict",
+      severity: "warning",
+      message: `qti-choice-interaction should not include multiple qti-choices-stacking-* classes: ${[...validStackingClasses].join(", ")}. The first valid stacking class in class attribute order takes precedence at runtime.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+
+  for (const className of invalidStackingClasses) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.stackingInvalid",
+      severity: "warning",
+      message: `qti-choice-interaction shared vocabulary class ${className} is not supported; expected qti-choices-stacking-1 through qti-choices-stacking-5.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}
+
+function validateSharedVocabularyLabelClasses(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  const labelClasses = classNames.filter((className) =>
+    [
+      "qti-labels-decimal",
+      "qti-labels-cjk-ideographic",
+      "qti-labels-lower-alpha",
+      "qti-labels-upper-alpha",
+    ].includes(className),
+  );
+  if (new Set(labelClasses).size > 1) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.labelsConflict",
+      severity: "warning",
+      message: `${interaction.qtiName} should not include multiple qti-labels-* style classes: ${[...new Set(labelClasses)].join(", ")}. qti-labels-decimal takes precedence over qti-labels-cjk-ideographic, then qti-labels-lower-alpha, then qti-labels-upper-alpha at runtime.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+
+  const suffixClasses = classNames.filter((className) =>
+    [
+      "qti-labels-suffix-none",
+      "qti-labels-suffix-period",
+      "qti-labels-suffix-parenthesis",
+    ].includes(className),
+  );
+  if (new Set(suffixClasses).size <= 1) return;
+  diagnostics.push({
+    code: "interaction.sharedVocabulary.labelSuffixConflict",
+    severity: "warning",
+    message: `${interaction.qtiName} should not include multiple qti-labels-suffix-* classes: ${[...new Set(suffixClasses)].join(", ")}. qti-labels-suffix-none takes precedence over qti-labels-suffix-period, then qti-labels-suffix-parenthesis at runtime.`,
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}
+
+function validateOrientationSharedVocabulary(
+  interaction: QtiInteraction,
+  classNameSet: Set<string>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  if (
+    !classNameSet.has("qti-orientation-horizontal") ||
+    !classNameSet.has("qti-orientation-vertical")
+  ) {
+    return;
+  }
+  diagnostics.push({
+    code: "interaction.sharedVocabulary.orientationConflict",
+    severity: "warning",
+    message: `${interaction.qtiName} should not include both qti-orientation-horizontal and qti-orientation-vertical; qti-orientation-horizontal takes precedence at runtime.`,
+    path: interaction.source?.path,
+    source: interaction.source,
+  });
+}
+
+function validateOrderInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  classNameSet: Set<string>,
+  diagnostics: QtiDiagnostic[],
+): void {
+  validateOrientationSharedVocabulary(interaction, classNameSet, diagnostics);
+  validateChoicesPositionSharedVocabulary(interaction, classNames, diagnostics);
+  validateChoicesContainerWidthSharedVocabulary(interaction, diagnostics);
+}
+
+const SHARED_VOCABULARY_CHOICES_POSITION_CLASSES = [
+  "qti-choices-top",
+  "qti-choices-bottom",
+  "qti-choices-left",
+  "qti-choices-right",
+] as const;
+
+function validateMatchInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  const hasTabular = classNames.includes("qti-match-tabular");
+  const hasHeaderHidden = classNames.includes("qti-header-hidden");
+  const firstColumnHeader = interaction.attributes["data-first-column-header"];
+  if (!hasTabular && (hasHeaderHidden || firstColumnHeader !== undefined)) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularContext",
+      severity: "warning",
+      message:
+        "qti-match-interaction shared vocabulary class qti-header-hidden and data-first-column-header are only relevant when qti-match-tabular is specified; they are ignored at runtime.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (hasTabular && hasHeaderHidden && firstColumnHeader !== undefined) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularHeaderHidden",
+      severity: "warning",
+      message:
+        "qti-match-interaction data-first-column-header is ignored when qti-header-hidden suppresses the tabular header row.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (!hasTabular) return;
+
+  const choicesPositionClasses = classNames.filter((className) =>
+    SHARED_VOCABULARY_CHOICES_POSITION_CLASSES.includes(
+      className as (typeof SHARED_VOCABULARY_CHOICES_POSITION_CLASSES)[number],
+    ),
+  );
+  if (
+    choicesPositionClasses.length > 0 ||
+    interaction.attributes["data-choices-container-width"] !== undefined
+  ) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularChoicesConflict",
+      severity: "warning",
+      message:
+        "qti-match-interaction qti-match-tabular uses a matrix layout; qti-choices-* position classes and data-choices-container-width are ignored at runtime.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+  if (!hasHeaderHidden && (firstColumnHeader === undefined || firstColumnHeader === "")) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.matchTabularFirstColumnHeader",
+      severity: "warning",
+      message:
+        "qti-match-interaction with qti-match-tabular should specify data-first-column-header for the top-left table header when the tabular header row is shown.",
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}
+
+function validateChoicesPositionSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  const choicesPositionClasses = classNames.filter((className) =>
+    SHARED_VOCABULARY_CHOICES_POSITION_CLASSES.includes(
+      className as (typeof SHARED_VOCABULARY_CHOICES_POSITION_CLASSES)[number],
+    ),
+  );
+  if (new Set(choicesPositionClasses).size > 1) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.orderChoicesPositionConflict",
+      severity: "warning",
+      message: `${interaction.qtiName} should not include multiple qti-choices-* position classes: ${[...new Set(choicesPositionClasses)].join(", ")}. The first position class in class attribute order takes precedence at runtime.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}
+
+function validateChoicesContainerWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  const width = interaction.attributes["data-choices-container-width"];
+  if (width === undefined) return;
+  const parsed = Number(width);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    diagnostics.push({
+      code: "interaction.sharedVocabulary.orderChoicesContainerWidth",
+      severity: "warning",
+      message: `${interaction.qtiName} data-choices-container-width must be a positive pixel value; the invalid value is ignored at runtime.`,
+      path: interaction.source?.path,
+      source: interaction.source,
+    });
+  }
+}
+
+function validateGapInputWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  for (const gap of interaction.choices.filter((choice) => choice.qtiName === "qti-gap")) {
+    diagnostics.push(
+      ...validateSharedVocabularyInputWidth({
+        classNames: sharedClassNames(gap.attributes),
+        subjectQtiName: "qti-gap",
+        path: gap.source?.path ?? interaction.source?.path,
+        source: gap.source ?? interaction.source,
+        conflictCode: "interaction.sharedVocabulary.gapInputWidthConflict",
+        invalidCode: "interaction.sharedVocabulary.gapInputWidthInvalid",
+      }),
+    );
+  }
+}
+
+function validateInteractionInputWidthSharedVocabulary(
+  interaction: QtiInteraction,
+  classNames: string[],
+  diagnostics: QtiDiagnostic[],
+): void {
+  diagnostics.push(
+    ...validateSharedVocabularyInputWidth({
+      classNames,
+      subjectQtiName: interaction.qtiName,
+      path: interaction.source?.path,
+      source: interaction.source,
+      conflictCode: "interaction.sharedVocabulary.inputWidthConflict",
+      invalidCode: "interaction.sharedVocabulary.inputWidthInvalid",
+    }),
+  );
+}
+
+function validateMediaInteractionSharedVocabulary(
+  interaction: QtiInteraction,
+  diagnostics: QtiDiagnostic[],
+): void {
+  diagnostics.push(
+    ...validateSharedVocabularyMediaPlayerControls({
+      value: interaction.attributes["data-qti-media-player-controls"],
+      subjectQtiName: interaction.qtiName,
+      path: interaction.source?.path,
+      source: interaction.source,
+    }),
+  );
+
+  if (!interaction.object) return;
+  diagnostics.push(
+    ...validateSharedVocabularyMediaPlayerControls({
+      value: interaction.object.attributes["data-qti-media-player-controls"],
+      subjectQtiName: `${interaction.qtiName} media object`,
+      path: interaction.object.source?.path ?? interaction.source?.path,
+      source: interaction.object.source ?? interaction.source,
+    }),
+  );
+}
+
+function sharedClassNames(attributes: Record<string, string>): string[] {
+  return (attributes.class ?? "").split(/\s+/).filter(Boolean);
+}
+
+function isLayoutColumnClassName(className: string): boolean {
+  return /^qti-layout-col-?\w+$/.test(className);
+}
+
+function layoutColumnValue(className: string): number | undefined {
+  const rawValue = /^qti-layout-col-?(\d+)$/.exec(className)?.[1];
+  if (rawValue === undefined) return undefined;
+  const value = Number(rawValue);
+  if (value < 1 || value > 12) return undefined;
+  return value;
+}
+
+function firstLayoutColumnValue(classNames: string[]): number | undefined {
+  for (const className of classNames) {
+    const value = layoutColumnValue(className);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function isLayoutOffsetClassName(className: string): boolean {
+  return /^qti-layout-offset-?\w+$/.test(className);
+}
+
+function layoutOffsetValue(className: string): number | undefined {
+  const rawValue = /^qti-layout-offset-?(\d+)$/.exec(className)?.[1];
+  if (rawValue === undefined) return undefined;
+  const value = Number(rawValue);
+  if (value < 1 || value > 11) return undefined;
+  return value;
+}
+
+function firstLayoutOffsetValue(classNames: string[]): number | undefined {
+  for (const className of classNames) {
+    const value = layoutOffsetValue(className);
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
 function validateInteractionResponseReference(
   interaction: QtiInteraction,
   responseIdentifiers: Set<string>,
@@ -2108,9 +2562,21 @@ function validateChoiceLimitAttributes(choice: QtiChoice, diagnostics: QtiDiagno
   validateChoiceNonNegativeIntegerAttribute(choice, "match-max", diagnostics);
   validateChoiceNonNegativeIntegerAttribute(choice, "match-min", diagnostics);
   validateChoiceMinMaxPair(choice, "match-min", "match-max", diagnostics);
+  validateGapImageAsset(choice, diagnostics);
   validateHotspotGeometry(choice, diagnostics);
 }
 
+function validateGapImageAsset(choice: QtiChoice, diagnostics: QtiDiagnostic[]): void {
+  if (choice.qtiName !== "qti-gap-img" || choice.asset?.data) return;
+  diagnostics.push({
+    code: "choice.gapImg.media.required",
+    severity: "error",
+    message: `qti-gap-img ${choice.identifier} requires an img, object, or picture child with a usable src or data attribute.`,
+    path: choice.source?.path,
+    source: choice.source,
+  });
+}
+
 function requiresMatchMax(choice: QtiChoice): boolean {
   return (
     choice.qtiName === "qti-simple-associable-choice" ||

package/src/xml.ts

@@ -120,9 +120,116 @@ export function parseXmlTree(xml: string): { root: XmlNode | undefined; errors:
     errors.push(new Error(`Unexpected end of document. Missing closing tag for <${node.name}>.`));
   }
 
+  if (root) restoreMixedContentFromSource(xml, root);
+
   return { root, errors };
 }
 
+/**
+ * stax-xml trims boundary whitespace around child elements. Re-slice mixed content from the
+ * original XML so authored spacing around inline markup (for example `<em>`) is preserved.
+ */
+const inlineMixedContentChildNames = new Set([
+  "a",
+  "abbr",
+  "b",
+  "bdi",
+  "bdo",
+  "cite",
+  "code",
+  "dfn",
+  "em",
+  "i",
+  "kbd",
+  "mark",
+  "q",
+  "rp",
+  "rt",
+  "ruby",
+  "s",
+  "samp",
+  "small",
+  "span",
+  "strong",
+  "sub",
+  "sup",
+  "var",
+  "qti-feedback-inline",
+  "qti-gap",
+  "qti-hottext",
+  "qti-inline-choice-interaction",
+  "qti-printed-variable",
+  "qti-template-inline",
+  "qti-text-entry-interaction",
+]);
+
+function shouldRestoreMixedContentWhitespace(node: XmlNode): boolean {
+  return node.content.some(
+    (entry) => typeof entry !== "string" && inlineMixedContentChildNames.has(entry.localName),
+  );
+}
+
+function restoreMixedContentFromSource(xml: string, node: XmlNode): void {
+  for (const entry of node.content) {
+    if (typeof entry !== "string") restoreMixedContentFromSource(xml, entry);
+  }
+
+  if (!shouldRestoreMixedContentWhitespace(node)) return;
+
+  const contentEndOffset = node.endSource?.offset ?? node.sourceRange.endOffset;
+  if (node.sourceRange.startTagEndOffset < 0 || contentEndOffset === undefined) return;
+
+  const restored: Array<string | XmlNode> = [];
+  let cursor = node.sourceRange.startTagEndOffset + 1;
+
+  for (const entry of node.content) {
+    if (typeof entry === "string") continue;
+    const childStart = entry.sourceRange.startOffset;
+    if (childStart < 0) continue;
+    if (childStart > cursor) {
+      appendDecodedTextSegment(restored, xml.slice(cursor, childStart));
+    }
+    restored.push(entry);
+    const childEnd = entry.sourceRange.endOffset;
+    if (childEnd === undefined || childEnd < cursor) continue;
+    cursor = childEnd;
+  }
+
+  if (contentEndOffset > cursor) {
+    appendDecodedTextSegment(restored, xml.slice(cursor, contentEndOffset));
+  }
+
+  node.content = restored;
+  node.text = restored.filter((entry): entry is string => typeof entry === "string").join("");
+}
+
+function appendDecodedTextSegment(content: Array<string | XmlNode>, raw: string): void {
+  const decoded = decodeXmlCharacterData(raw);
+  if (decoded.length > 0) content.push(decoded);
+}
+
+const predefinedXmlEntities: Record<string, string> = {
+  amp: "&",
+  apos: "'",
+  gt: ">",
+  lt: "<",
+  quot: '"',
+};
+
+function decodeXmlCharacterData(value: string): string {
+  return value.replace(/&(#x?[0-9a-fA-F]+|[A-Za-z]+);/g, (entity, body: string) => {
+    if (body.startsWith("#x") || body.startsWith("#X")) {
+      const codePoint = Number.parseInt(body.slice(2), 16);
+      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : entity;
+    }
+    if (body.startsWith("#")) {
+      const codePoint = Number.parseInt(body.slice(1), 10);
+      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : entity;
+    }
+    return predefinedXmlEntities[body] ?? entity;
+  });
+}
+
 export function childElements(node: XmlNode, localName?: string): XmlNode[] {
   return node.children.filter((child) => !localName || child.localName === localName);
 }