@gmb/bitmark-parser-generator 5.24.0 → 5.26.0

package/dist/index.js

@@ -230,6 +230,7 @@ var BitType = {
   dangerAlt: "danger-alt",
   dangerCollapsible: "danger-collapsible",
   definitionList: "definition-list",
+  definitionListCollapsible: "definition-list-collapsible",
   definitionTerm: "definition-term",
   deleted: "deleted",
   details: "details",
@@ -510,6 +511,8 @@ var BitType = {
   smartStandardArticleNonNormativeCollapsible: "smart-standard-article-non-normative-collapsible",
   smartStandardArticleNormative: "smart-standard-article-normative",
   smartStandardArticleNormativeCollapsible: "smart-standard-article-normative-collapsible",
+  smartStandardDefinitionListNonNormative: "smart-standard-definition-list-non-normative",
+  smartStandardDefinitionListNormative: "smart-standard-definition-list-normative",
   smartStandardExampleNonNormative: "smart-standard-example-non-normative",
   smartStandardExampleNonNormativeCollapsible: "smart-standard-example-non-normative-collapsible",
   smartStandardExampleNormative: "smart-standard-example-normative",
@@ -560,6 +563,8 @@ var BitType = {
   smartStandardTableNormativeCollapsible: "smart-standard-table-normative-collapsible",
   standardArticleNonNormative: "standard-article-non-normative",
   standardArticleNormative: "standard-article-normative",
+  standardDefinitionListNonNormative: "standard-definition-list-non-normative",
+  standardDefinitionListNormative: "standard-definition-list-normative",
   standardExampleNonNormative: "standard-example-non-normative",
   standardExampleNormative: "standard-example-normative",
   standardImageFigureNonNormative: "standard-image-figure-non-normative",
@@ -731,6 +736,7 @@ var CardSetConfigKey = {
   flashcard: "flashcard",
   flashcard1: "flashcard1",
   definitionList: "definitionList",
+  definitionListPlain: "definitionListPlain",
   elements: "elements",
   statements: "statements",
   quiz: "quiz",
@@ -1344,6 +1350,7 @@ var propertyKeys = {
   property_enforceUpdateOverUserInput: "@enforceUpdateOverUserInput",
   property_extractorExtractionTimestamp: "@extractorExtractionTimestamp",
   property_isCaseSensitive: "@isCaseSensitive",
+  property_isCollapsible: "@isCollapsible",
   property_isInfoOnly: "@isInfoOnly",
   property_isPublic: "@isPublic",
   property_isTemplate: "@isTemplate",
@@ -2548,6 +2555,126 @@ var CARDSETS = {
     ]
   },
   //
+  // definition-list-plain
+  //
+  // Same shape as `definitionList`, but every variant body is rendered as
+  // plain text (string), not bitmark+ AST. Used by
+  // `meta-search-default-terms` / `meta-search-default-topics`, which need
+  // term/definition text emitted verbatim instead of as a ProseMirror tree.
+  //
+  [CardSetConfigKey.definitionListPlain]: {
+    jsonKey: "definitions",
+    exportJsonKey: { definitions: "$" },
+    sides: [
+      {
+        name: "term",
+        variants: [
+          {
+            jsonKey: "term.text",
+            exportJsonKey: [{ "@absent": { term: {} } }, { term: { text: "$" } }],
+            format: TextFormat.plainText,
+            tags: [
+              {
+                key: ConfigKey.group_standardTags,
+                description: "Standard tags for the definition."
+              },
+              {
+                key: ConfigKey.tag_title,
+                description: "Title of the definition.",
+                format: TagFormat.plainText,
+                jsonKey: "^heading.forKeys",
+                exportJsonKey: { "@bit": { heading: { forKeys: "$" } } }
+              },
+              {
+                key: ConfigKey.group_resourceIcon,
+                description: "Icon resource for the definition.",
+                format: TagFormat.plainText,
+                jsonKey: "term.icon|resource(type=image, key=image)",
+                exportJsonKey: { term: { icon: { type: "image", image: { src: "$" } } } }
+              },
+              {
+                key: ConfigKey.property_example,
+                exportJsonKey: [
+                  { "@keyonly": { isExample: true, example: true, "@bit": { isExample: true } } },
+                  { "@absent": { isExample: true, example: true, "@bit": { isExample: true } } },
+                  { isExample: true, example: "$", "@bit": { isExample: true } }
+                ],
+                description: "Example marker for the definition term.",
+                format: TagFormat.bitmarkText,
+                nullable: true
+              }
+            ]
+          }
+        ]
+      },
+      {
+        name: "definition",
+        variants: [
+          {
+            jsonKey: "definition.text",
+            exportJsonKey: [{ "@absent": { definition: {} } }, { definition: { text: "$" } }],
+            format: TextFormat.plainText,
+            tags: [
+              {
+                key: ConfigKey.group_standardTags,
+                description: "Standard tags for the definition."
+              },
+              {
+                key: ConfigKey.tag_title,
+                description: "Title of the definition.",
+                format: TagFormat.plainText,
+                jsonKey: "^heading.forValues",
+                exportJsonKey: { "@bit": { heading: { forValues: "$" } } }
+              },
+              {
+                key: ConfigKey.group_resourceIcon,
+                description: "Icon resource for the definition.",
+                jsonKey: "definition.icon|resource(type=image, key=image)",
+                exportJsonKey: { definition: { icon: { type: "image", image: { src: "$" } } } }
+              },
+              {
+                key: ConfigKey.property_example,
+                exportJsonKey: [
+                  { "@keyonly": { isExample: true, example: true, "@bit": { isExample: true } } },
+                  { "@absent": { isExample: true, example: true, "@bit": { isExample: true } } },
+                  { isExample: true, example: "$", "@bit": { isExample: true } }
+                ],
+                description: "Example marker for the definition.",
+                format: TagFormat.bitmarkText,
+                nullable: true
+              }
+            ]
+          },
+          {
+            jsonKey: "alternativeDefinitions[].text",
+            exportJsonKey: { alternativeDefinitions: [{ text: "$" }] },
+            format: TextFormat.plainText,
+            tags: [
+              {
+                key: ConfigKey.group_standardTags,
+                description: "Standard tags for the definition."
+              },
+              {
+                exportJsonKey: { title: "$" },
+                key: ConfigKey.tag_title,
+                description: "Title of the definition."
+              },
+              {
+                key: ConfigKey.group_resourceIcon,
+                description: "Icon resource for the definition.",
+                jsonKey: "alternativeDefinitions[].icon|resource(type=image, key=image)",
+                exportJsonKey: {
+                  alternativeDefinitions: [{ icon: { type: "image", image: { src: "$" } } }]
+                }
+              }
+            ],
+            repeatCount: Count.infinity
+          }
+        ]
+      }
+    ]
+  },
+  //
   // match-pairs
   //
   [CardSetConfigKey.matchPairs]: {
@@ -3485,12 +3612,29 @@ var CARDSETS = {
                 // ALIGN-EXAMPLE-CASCADE §3.10: `questions` is NOT in BPG's
                 // `pushExampleDownTree` dispatch — bit-header `[@example]`
                 // does not propagate `example`/`isExample` onto question
-                // entries. Only entry-local `[@example]` fires (handled by
-                // `@keyonly` and the unconditional fallback). No `@absent`
-                // rule.
+                // entries. Only entry-local `[@example]` fires.
+                //
+                // BPG's `BaseBuilder.toExample` for interview questions
+                // (Builder.ts:2575,2588) uses `data.__sampleSolutionAst`
+                // as `defaultExample` — bare `[@example]` (which sets
+                // `__isDefaultExample=true, example=undefined`) emits the
+                // parsed sample-solution AST in the `example` slot. The
+                // `@keyonly` rule mirrors that runtime behaviour via
+                // `$parent.sampleSolution` — the chain-walker's post-walk
+                // retry resolves this once the sibling `[@sampleSolution]`
+                // chain has merged into the shared scope (interview's
+                // `[@example]` typically precedes `[@sampleSolution]` in
+                // source). Format coercion turns the resolved string
+                // value into a PM tree.
                 key: ConfigKey.property_example,
                 exportJsonKey: [
-                  { "@keyonly": { isExample: true, example: true, "@bit": { isExample: true } } },
+                  {
+                    "@keyonly": {
+                      isExample: true,
+                      example: "$parent.sampleSolution",
+                      "@bit": { isExample: true }
+                    }
+                  },
                   { isExample: true, example: "$", "@bit": { isExample: true } }
                 ],
                 description: "Example marker for the question (entry-local only; no bit-header cascade).",
@@ -5313,7 +5457,11 @@ var GROUPS = {
       {
         key: ConfigKey.property_mark,
         jsonKey: "marks.mark",
-        exportJsonKey: { marks: [{ mark: "$" }] },
+        // `emphasis: 'underline'` is the per-entry default for mark
+        // configs — mirrors the hardcoded default in BPG
+        // `MarkConfigChainContentProcessor.ts:55-58`. Chained
+        // `[@emphasis:…]` overrides via deep-merge into `marks[-1]`.
+        exportJsonKey: { marks: [{ mark: "$", emphasis: "underline" }] },
         description: "The mark configuration",
         format: TagFormat.plainText,
         maxCount: Count.infinity,
@@ -5355,13 +5503,22 @@ var GROUPS = {
           {
             key: ConfigKey.property_example,
             jsonKey: "example",
-            exportJsonKey: [
-              { "@keyonly": { isExample: true, example: true, "@bit": { isExample: true } } },
-              { "@absent": { isExample: true, example: true, "@bit": { isExample: true } } },
-              { isExample: true, example: "$", "@bit": { isExample: true } }
-            ],
+            // Per-mark `@example` is a boolean toggle. BPG's runtime
+            // `ExampleTagContentProcessor.handleDefaultOnlyExample`
+            // (lines 147-161) normalises ANY `[@example]` or
+            // `[@example:V]` on a mark body-bit to
+            // `__isDefaultExample=true, example=undefined`; the
+            // downstream `toExample(_, _, defaultExample=true)` in
+            // `BaseBuilder.ts:80-87` then emits `example: true`
+            // regardless of source. Declare a single unconditional
+            // boolean-shape rule so the exported schema matches that
+            // runtime semantic instead of the misleading `example: $`
+            // shape (which would only fire if `handleDefaultOnlyExample`
+            // were removed). `@bit: {isExample: true}` cascades the
+            // marker — but NOT the `example` value — to bit root.
+            exportJsonKey: { isExample: true, example: true, "@bit": { isExample: true } },
             description: "An example for the marked content",
-            format: TagFormat.bitmarkText,
+            format: TagFormat.boolean,
             nullable: true
           }
         ]
@@ -8137,6 +8294,12 @@ var BITS = {
         description: "The progress of the chapter, used for tracking reading progress",
         format: TagFormat.boolean,
         defaultValue: "true"
+      },
+      {
+        key: ConfigKey.property_isCollapsible,
+        description: "If true, the chapter is collapsible",
+        format: TagFormat.boolean,
+        defaultValue: "false"
       }
     ]
   },
@@ -8911,7 +9074,12 @@ var BITS = {
         maxCount: Count.infinity
       },
       {
-        // Override inherited @example from group_standardTags: string root example.
+        // Override inherited @example from group_standardTags: emits both
+        // `isExample` (bool) AND `example` (paragraph array). Declared as
+        // bitmarkText because BPG `JsonGenerator.toExample` renders the
+        // root-example value through the bit's textFormat (not this tag's
+        // declared format) — `TagFormat.plainText` here would be ignored
+        // at runtime and is misleading.
         key: ConfigKey.property_example,
         exportJsonKey: [
           { "@keyonly": { isExample: true, example: "true" } },
@@ -8919,7 +9087,7 @@ var BITS = {
           { isExample: true, example: "$" }
         ],
         description: "The example text for the essay bit",
-        format: TagFormat.plainText,
+        format: TagFormat.bitmarkText,
         nullable: true
       }
     ],
@@ -9965,6 +10133,11 @@ var BITS = {
     baseBitType: BitType._standard,
     description: "Extractor rule bit, used to define extraction rules with reference images and instructions",
     tags: [
+      {
+        exportJsonKey: { title: "$" },
+        key: ConfigKey.tag_title,
+        description: "The name of the extraction rule"
+      },
       {
         key: ConfigKey.group_resourceBitTags,
         description: "Resource bit tags for extraction rule images"
@@ -10281,11 +10454,36 @@ var BITS = {
     ],
     cardSet: CardSetConfigKey.definitionList
   },
+  [BitType.definitionListCollapsible]: {
+    since: "5.25.0",
+    baseBitType: BitType.definitionList,
+    description: "Collapsible definition list bit, used to create collapsible lists of definitions in articles or books"
+  },
+  [BitType.standardDefinitionListNormative]: {
+    since: "5.24.0",
+    baseBitType: BitType.definitionList,
+    description: "Standard normative definition list bit, used to create normative standard definition lists in articles or books"
+  },
+  [BitType.standardDefinitionListNonNormative]: {
+    since: "5.24.0",
+    baseBitType: BitType.definitionList,
+    description: "Standard non-normative definition list bit, used to create non-normative standard definition lists in articles or books"
+  },
+  [BitType.smartStandardDefinitionListNormative]: {
+    since: "5.24.0",
+    baseBitType: BitType.standardDefinitionListNormative,
+    description: "Smart standard normative definition list bit, used to create normative smart standard definition lists in articles or books"
+  },
+  [BitType.smartStandardDefinitionListNonNormative]: {
+    since: "5.24.0",
+    baseBitType: BitType.standardDefinitionListNonNormative,
+    description: "Smart standard non-normative definition list bit, used to create non-normative smart standard definition lists in articles or books"
+  },
   [BitType.metaSearchDefaultTerms]: {
     since: "3.12.0",
     baseBitType: BitType._standard,
     description: "Meta search default terms bit, used to define default search terms in articles",
-    cardSet: CardSetConfigKey.definitionList
+    cardSet: CardSetConfigKey.definitionListPlain
   },
   [BitType.metaSearchDefaultTopics]: {
     since: "3.12.0",
@@ -10329,7 +10527,11 @@ var BITS = {
   [BitType.qAndACard]: {
     since: "3.25.0",
     baseBitType: BitType.flashcard1,
-    description: "Q&A card bit, used to create question and answer cards in articles or books"
+    description: "Q&A card bit, used to create question and answer cards in articles or books",
+    // PLAN-085: q-and-a-card permits multiple cards (some fixtures carry
+    // two). Override the inherited `flashcard1` (max=1) cardset back to
+    // the unbounded `flashcard` cardset.
+    cardSet: CardSetConfigKey.flashcard
   },
   [BitType.focusImage]: {
     since: "1.3.0",
@@ -13415,7 +13617,7 @@ var instance2 = new Config();
 // src/generated/package_info.ts
 var PACKAGE_INFO = {
   "name": "@gmb/bitmark-parser-generator",
-  "version": "5.24.0",
+  "version": "5.26.0",
   "author": "Get More Brain Ltd",
   "license": "ISC",
   "description": "A bitmark parser and generator using Peggy.js"
@@ -14061,6 +14263,8 @@ var NodeType = {
   internalPrintPdf: "internalPrintPdf",
   internalPrintPdfValue: "internalPrintPdfValue",
   isCaseSensitive: "isCaseSensitive",
+  isCollapsible: "isCollapsible",
+  isCollapsibleValue: "isCollapsibleValue",
   isCommented: "isCommented",
   isCorrect: "isCorrect",
   isEditable: "isEditable",
@@ -28299,6 +28503,12 @@ var Builder = class extends BaseBuilder {
       level: instance6.asNumber(data.level),
       toc: this.toAstProperty(bitType, ConfigKey.property_toc, data.toc, options),
       progress: this.toAstProperty(bitType, ConfigKey.property_progress, data.progress, options),
+      isCollapsible: this.toAstProperty(
+        bitType,
+        ConfigKey.property_isCollapsible,
+        data.isCollapsible,
+        options
+      ),
       anchor: data.anchor,
       reference: data.reference,
       referenceEnd: data.referenceEnd,
@@ -33845,6 +34055,7 @@ var JsonGenerator = class extends AstWalkerGenerator {
       if (instance2.isOfBitType(bitType, BitType.chapter)) {
         if (bitJson.toc == null) bitJson.toc = true;
         if (bitJson.progress == null) bitJson.progress = true;
+        if (bitJson.isCollapsible == null) bitJson.isCollapsible = false;
         if (bitJson.level == null) bitJson.level = 1;
         if (bitJson.body == null) bitJson.body = this.bodyDefault;
       }
@@ -36060,6 +36271,7 @@ function buildCards(context, bitType, textFormat, parsedCardSet, statementV1, st
     case CardSetConfigKey.flashcard:
     case CardSetConfigKey.flashcard1:
     case CardSetConfigKey.definitionList:
+    case CardSetConfigKey.definitionListPlain:
       result = parseFlashcardOrDefinitionList(context, bitType, processedCardSet);
       break;
     case CardSetConfigKey.elements:
@@ -42396,6 +42608,235 @@ var BitmarkFileGenerator = class {
   }
 };
 
+// src/generator/html/HtmlTableGenerator.ts
+var MARK_TO_TAG = {
+  bold: "b",
+  italic: "i",
+  superscript: "sup",
+  subscript: "sub",
+  strike: "s",
+  del: "del",
+  ins: "ins",
+  underline: "u",
+  highlight: "mark",
+  code: "code"
+};
+var HtmlTableGenerator = class {
+  constructor() {
+    __publicField(this, "indentUnit", "  ");
+  }
+  /**
+   * Generate HTML table fragments from a string or JSON value.
+   * @returns the concatenated `<table>` fragments, blank-line separated (empty string if none).
+   */
+  generate(input) {
+    let data = input;
+    if (typeof data === "string") {
+      try {
+        data = JSON.parse(data);
+      } catch {
+        return "";
+      }
+    }
+    const bits = this.collectBits(data);
+    const fragments = [];
+    for (const bit of bits) {
+      const html = this.renderTableBit(bit);
+      if (html) fragments.push(html);
+    }
+    return fragments.join("\n\n");
+  }
+  // --- bit collection -------------------------------------------------------
+  collectBits(data) {
+    const out = [];
+    const visit = (value) => {
+      if (value == null || typeof value !== "object") return;
+      if (Array.isArray(value)) {
+        value.forEach(visit);
+        return;
+      }
+      const obj = value;
+      if ("bit" in obj && obj.bit && typeof obj.bit === "object") {
+        out.push(obj.bit);
+      } else if ("type" in obj) {
+        out.push(obj);
+      }
+    };
+    visit(data);
+    return out;
+  }
+  // --- table rendering ------------------------------------------------------
+  renderTableBit(bit) {
+    const table = bit.table;
+    if (!table) return "";
+    if (bit.type !== "table" && bit.type !== "table-extended") return "";
+    const extended = this.toExtended(table);
+    const lines = [];
+    lines.push("<table>");
+    if (bit.caption != null) {
+      const caption = this.cellContentToHtml(this.asTextAst(bit.caption));
+      if (caption) lines.push(`${this.indentUnit}<caption>${caption}</caption>`);
+    }
+    this.renderSection(lines, "thead", extended.header, "header");
+    this.renderSection(lines, "tbody", extended.body, "body");
+    this.renderSection(lines, "tfoot", extended.footer, "footer");
+    lines.push("</table>");
+    return lines.join("\n");
+  }
+  toExtended(table) {
+    const t = table;
+    if (t.header || t.body || t.footer) return table;
+    return convertBasicToExtendedTableFormat(table);
+  }
+  renderSection(lines, tag, section, key) {
+    if (!section || !section.rows || section.rows.length === 0) return;
+    lines.push(`${this.indentUnit}<${tag}>`);
+    for (const row of section.rows) {
+      lines.push(`${this.indentUnit.repeat(2)}<tr>`);
+      for (const cell of row.cells ?? []) {
+        lines.push(`${this.indentUnit.repeat(3)}${this.renderCell(cell, key)}`);
+      }
+      lines.push(`${this.indentUnit.repeat(2)}</tr>`);
+    }
+    lines.push(`${this.indentUnit}</${tag}>`);
+  }
+  renderCell(cell, _key) {
+    const tag = cell.title === true ? "th" : "td";
+    const attrs = [];
+    if (cell.rowspan && cell.rowspan > 1) attrs.push(`rowspan="${cell.rowspan}"`);
+    if (cell.colspan && cell.colspan > 1) attrs.push(`colspan="${cell.colspan}"`);
+    if (cell.scope) attrs.push(`scope="${cell.scope}"`);
+    if (cell.colwidth && cell.colwidth > 0) attrs.push(`width="${cell.colwidth}"`);
+    const open = attrs.length > 0 ? `<${tag} ${attrs.join(" ")}>` : `<${tag}>`;
+    return `${open}${this.cellContentToHtml(this.asTextAst(cell.content))}</${tag}>`;
+  }
+  // --- cell content (TextAst -> HTML) ---------------------------------------
+  asTextAst(content) {
+    if (content == null) return [];
+    if (typeof content === "string") return [{ type: "text", text: content }];
+    return content;
+  }
+  cellContentToHtml(blocks) {
+    if (blocks.length === 0) return "";
+    if (blocks.length === 1 && blocks[0].type === "paragraph") {
+      return this.inlineToHtml(blocks[0].content ?? []);
+    }
+    return blocks.map((b) => this.blockToHtml(b)).join("");
+  }
+  blockToHtml(node) {
+    switch (node.type) {
+      case "paragraph":
+        return `<p>${this.inlineToHtml(node.content ?? [])}</p>`;
+      case "bulletList":
+      case "noBulletList":
+      case "orderedList":
+      case "orderedListRoman":
+      case "orderedListRomanLower":
+      case "letteredList":
+      case "letteredListLower":
+      case "taskList":
+        return this.listToHtml(node);
+      case "image":
+      case "imageInline":
+        return this.imageToHtml(node);
+      default:
+        return this.inlineToHtml([node]);
+    }
+  }
+  inlineToHtml(nodes) {
+    return nodes.map((n) => this.inlineNodeToHtml(n)).join("");
+  }
+  inlineNodeToHtml(node) {
+    if (node.type === "hardBreak") return "<br>";
+    if (node.type === "image" || node.type === "imageInline") return this.imageToHtml(node);
+    if (node.type === "text") {
+      return this.wrapMarks(this.escapeText(node.text ?? ""), node.marks);
+    }
+    if (node.content) return this.inlineToHtml(node.content);
+    return this.escapeText(node.text ?? "");
+  }
+  wrapMarks(text, marks) {
+    if (!marks || marks.length === 0) return text;
+    let open = "";
+    let close = "";
+    for (const mark of marks) {
+      if (mark.type === "link") {
+        const href = mark.attrs?.href ?? "";
+        open += `<a href="${this.escapeAttr(href)}">`;
+        close = `</a>${close}`;
+      } else {
+        const tag = MARK_TO_TAG[mark.type];
+        if (tag) {
+          open += `<${tag}>`;
+          close = `</${tag}>${close}`;
+        }
+      }
+    }
+    return `${open}${text}${close}`;
+  }
+  // --- lists ----------------------------------------------------------------
+  listToHtml(node) {
+    const { tag, attrs } = this.listTag(node);
+    const items = (node.content ?? []).map((item) => this.listItemToHtml(item, node.type === "taskList")).join("");
+    return `<${tag}${attrs}>${items}</${tag}>`;
+  }
+  listTag(node) {
+    const start = node.attrs?.start;
+    const startAttr = typeof start === "number" && start !== 1 ? ` start="${start}"` : "";
+    switch (node.type) {
+      case "orderedList":
+        return { tag: "ol", attrs: startAttr };
+      case "orderedListRoman":
+        return { tag: "ol", attrs: ` type="I"${startAttr}` };
+      case "orderedListRomanLower":
+        return { tag: "ol", attrs: ` type="i"${startAttr}` };
+      case "letteredList":
+        return { tag: "ol", attrs: ` type="A"${startAttr}` };
+      case "letteredListLower":
+        return { tag: "ol", attrs: ` type="a"${startAttr}` };
+      case "noBulletList":
+        return { tag: "ul", attrs: ' style="list-style:none"' };
+      case "taskList":
+      case "bulletList":
+      default:
+        return { tag: "ul", attrs: "" };
+    }
+  }
+  listItemToHtml(item, task) {
+    const inner = (item.content ?? []).map((b) => {
+      if (b.type === "paragraph") return this.inlineToHtml(b.content ?? []);
+      return this.blockToHtml(b);
+    }).join("");
+    if (task) {
+      const checked = item.attrs?.checked ? " checked" : "";
+      return `<li><input type="checkbox"${checked}>${inner}</li>`;
+    }
+    return `<li>${inner}</li>`;
+  }
+  // --- images ---------------------------------------------------------------
+  imageToHtml(node) {
+    const attrs = node.attrs ?? {};
+    const parts = [];
+    const src = attrs.src;
+    parts.push(`src="${this.escapeAttr(typeof src === "string" ? src : "")}"`);
+    if (typeof attrs.alt === "string") parts.push(`alt="${this.escapeAttr(attrs.alt)}"`);
+    if (typeof attrs.title === "string") parts.push(`title="${this.escapeAttr(attrs.title)}"`);
+    if (attrs.width != null) parts.push(`width="${attrs.width}"`);
+    if (attrs.height != null) parts.push(`height="${attrs.height}"`);
+    if (typeof attrs.class === "string" && attrs.class) {
+      parts.push(`class="${this.escapeAttr(attrs.class)}"`);
+    }
+    return `<img ${parts.join(" ")}>`;
+  }
+  // --- escaping -------------------------------------------------------------
+  escapeText(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  }
+  escapeAttr(text) {
+    return this.escapeText(text).replace(/"/g, "&quot;");
+  }
+};
+
 // src/generator/json/JsonFileGenerator.ts
 import "fs";
 var JsonFileGenerator = class {
@@ -43372,6 +43813,499 @@ var ConfigBuilder = class {
   }
 };
 
+// src/parser/html/HtmlDom.ts
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+var IMPLIED_CLOSE = {
+  li: /* @__PURE__ */ new Set(["li"]),
+  td: /* @__PURE__ */ new Set(["td", "th"]),
+  th: /* @__PURE__ */ new Set(["td", "th"]),
+  tr: /* @__PURE__ */ new Set(["td", "th", "tr"]),
+  thead: /* @__PURE__ */ new Set(["td", "th", "tr", "thead", "tbody", "tfoot"]),
+  tbody: /* @__PURE__ */ new Set(["td", "th", "tr", "thead", "tbody", "tfoot"]),
+  tfoot: /* @__PURE__ */ new Set(["td", "th", "tr", "thead", "tbody", "tfoot"]),
+  p: /* @__PURE__ */ new Set(["p"]),
+  option: /* @__PURE__ */ new Set(["option"])
+};
+var TAG_RE = /<(\/)?([a-zA-Z][a-zA-Z0-9-]*)((?:\s+(?:"[^"]*"|'[^']*'|[^<>"'])*)?)(\/)?>/g;
+var ATTR_RE = /([a-zA-Z_:][a-zA-Z0-9:._-]*)(?:\s*=\s*("[^"]*"|'[^']*'|[^\s"'>]+))?/g;
+function parseAttrs(raw) {
+  const attrs = {};
+  if (!raw) return attrs;
+  ATTR_RE.lastIndex = 0;
+  let m;
+  while ((m = ATTR_RE.exec(raw)) !== null) {
+    const name = m[1].toLowerCase();
+    let value = m[2] ?? "";
+    if (value.length >= 2 && (value[0] === '"' || value[0] === "'")) {
+      value = value.slice(1, -1);
+    }
+    attrs[name] = value;
+  }
+  return attrs;
+}
+function stripNonContent(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, "").replace(/<!\[CDATA\[[\s\S]*?\]\]>/g, "").replace(/<!doctype[^>]*>/gi, "").replace(/<script\b[\s\S]*?<\/script>/gi, "").replace(/<style\b[\s\S]*?<\/style>/gi, "");
+}
+function tokenize(html) {
+  const tokens = [];
+  const clean = stripNonContent(html);
+  TAG_RE.lastIndex = 0;
+  let lastIndex = 0;
+  let m;
+  while ((m = TAG_RE.exec(clean)) !== null) {
+    if (m.index > lastIndex) {
+      tokens.push({ kind: "text", text: clean.slice(lastIndex, m.index) });
+    }
+    lastIndex = TAG_RE.lastIndex;
+    const isClose = m[1] === "/";
+    const name = m[2].toLowerCase();
+    if (isClose) {
+      tokens.push({ kind: "close", name });
+    } else {
+      tokens.push({
+        kind: "open",
+        name,
+        attrs: parseAttrs(m[3]),
+        selfClose: m[4] === "/"
+      });
+    }
+  }
+  if (lastIndex < clean.length) {
+    tokens.push({ kind: "text", text: clean.slice(lastIndex) });
+  }
+  return tokens;
+}
+function parseHtml(html) {
+  const root = { type: "element", name: "#root", attrs: {}, children: [] };
+  const stack = [root];
+  const top = () => stack[stack.length - 1];
+  for (const token of tokenize(html)) {
+    if (token.kind === "text") {
+      if (token.text) top().children.push({ type: "text", value: token.text });
+      continue;
+    }
+    if (token.kind === "open") {
+      const name = token.name;
+      const closes = IMPLIED_CLOSE[name];
+      if (closes) {
+        while (stack.length > 1 && closes.has(top().name)) stack.pop();
+      }
+      const el = {
+        type: "element",
+        name,
+        attrs: token.attrs ?? {},
+        children: []
+      };
+      top().children.push(el);
+      if (!token.selfClose && !VOID_ELEMENTS.has(name)) {
+        stack.push(el);
+      }
+      continue;
+    }
+    for (let i = stack.length - 1; i > 0; i--) {
+      if (stack[i].name === token.name) {
+        stack.length = i;
+        break;
+      }
+    }
+  }
+  return root.children;
+}
+function childElements(el, names) {
+  return el.children.filter((c) => c.type === "element" && names.has(c.name));
+}
+
+// src/parser/html/HtmlTableParser.ts
+var MARK_TAGS = {
+  b: "bold",
+  strong: "bold",
+  i: "italic",
+  em: "italic",
+  sup: "superscript",
+  sub: "subscript",
+  s: "strike",
+  strike: "strike",
+  del: "del",
+  ins: "ins",
+  u: "underline",
+  mark: "highlight",
+  code: "code"
+};
+var SECTION_TAGS = /* @__PURE__ */ new Set(["thead", "tbody", "tfoot"]);
+var ROW_TAGS = /* @__PURE__ */ new Set(["tr"]);
+var CELL_TAGS = /* @__PURE__ */ new Set(["td", "th"]);
+var LI_TAGS = /* @__PURE__ */ new Set(["li"]);
+var VALID_SCOPES = /* @__PURE__ */ new Set(["row", "col", "rowgroup", "colgroup"]);
+var NAMED_ENTITIES = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: "\xA0"
+};
+function decodeEntities(text) {
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (whole, body) => {
+    if (body[0] === "#") {
+      const code = body[1] === "x" || body[1] === "X" ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+      if (Number.isFinite(code) && code >= 0 && code <= 1114111) {
+        try {
+          return String.fromCodePoint(code);
+        } catch {
+          return whole;
+        }
+      }
+      return whole;
+    }
+    return NAMED_ENTITIES[body] ?? whole;
+  });
+}
+function intAttr(value) {
+  if (value == null) return void 0;
+  const n = Number.parseInt(value, 10);
+  return Number.isInteger(n) ? n : void 0;
+}
+function isElement(node) {
+  return node.type === "element";
+}
+var HtmlTableParser = class {
+  constructor() {
+    __publicField(this, "keepUnknownTags", false);
+  }
+  /**
+   * Parse an HTML string and return one table bit per top-level `<table>`.
+   */
+  parse(html, options) {
+    this.keepUnknownTags = options?.keepUnknownTags ?? false;
+    const tableFormat = options?.tableFormat ?? "table-extended";
+    const onWarning = options?.onWarning;
+    const tables = this.collectTopLevelTables(parseHtml(html));
+    const bits = [];
+    for (const table of tables) {
+      const bit = this.tableToBit(table, tableFormat, onWarning);
+      if (bit) bits.push(bit);
+    }
+    return bits;
+  }
+  // --- table extraction -----------------------------------------------------
+  /** Collect every `<table>` element, NOT descending into nested tables. */
+  collectTopLevelTables(nodes) {
+    const tables = [];
+    const visit = (node) => {
+      if (!isElement(node)) return;
+      if (node.name === "table") {
+        tables.push(node);
+        return;
+      }
+      node.children.forEach(visit);
+    };
+    nodes.forEach(visit);
+    return tables;
+  }
+  tableToBit(table, tableFormat, onWarning) {
+    const header = [];
+    const body = [];
+    const footer = [];
+    let caption;
+    for (const child of table.children) {
+      if (!isElement(child)) continue;
+      if (child.name === "caption") {
+        const capContent = this.inlineNodes(child.children, []);
+        const trimmed = this.trimInline(capContent);
+        if (trimmed.length > 0) caption = trimmed;
+      } else if (SECTION_TAGS.has(child.name)) {
+        const target = child.name === "thead" ? header : child.name === "tfoot" ? footer : body;
+        for (const tr of childElements(child, ROW_TAGS)) {
+          target.push(this.rowToCells(tr));
+        }
+      } else if (ROW_TAGS.has(child.name)) {
+        body.push(this.rowToCells(child));
+      }
+    }
+    if (header.length === 0 && body.length === 0 && footer.length === 0) {
+      return void 0;
+    }
+    const tableExtended = {};
+    if (header.length > 0) tableExtended.header = { rows: header };
+    if (body.length > 0) tableExtended.body = { rows: body };
+    if (footer.length > 0) tableExtended.footer = { rows: footer };
+    let tableData = tableExtended;
+    if (tableFormat === "table") {
+      if (this.isLossyAsBasic(tableExtended)) {
+        onWarning?.(
+          "Converting an HTML table to [.table] loses rowspan/colspan/scope and multi-section structure; use --tableFormat table-extended to preserve them."
+        );
+      }
+      tableData = convertExtendedToBasicTableFormat(tableExtended);
+    }
+    const bit = {
+      type: tableFormat,
+      format: "bitmark++",
+      table: tableData
+    };
+    if (caption) bit.caption = caption;
+    return bit;
+  }
+  rowToCells(tr) {
+    const cells = [];
+    for (const cell of childElements(tr, CELL_TAGS)) {
+      cells.push(this.cellToJson(cell));
+    }
+    return { cells };
+  }
+  cellToJson(cell) {
+    const json = {
+      content: this.blockNodes(cell.children)
+    };
+    if (cell.name === "th") json.title = true;
+    const rowspan = intAttr(cell.attrs.rowspan);
+    if (rowspan != null && rowspan >= 2) json.rowspan = rowspan;
+    const colspan = intAttr(cell.attrs.colspan);
+    if (colspan != null && colspan >= 2) json.colspan = colspan;
+    const scope = cell.attrs.scope?.toLowerCase();
+    if (scope && VALID_SCOPES.has(scope)) {
+      json.scope = scope;
+    }
+    const width = this.widthFromCell(cell);
+    if (width != null) json.colwidth = width;
+    return json;
+  }
+  widthFromCell(cell) {
+    const attrWidth = intAttr(cell.attrs.width);
+    if (attrWidth != null && attrWidth > 0) return attrWidth;
+    const style = cell.attrs.style;
+    if (style) {
+      const m = style.match(/width\s*:\s*(\d+)\s*px/i);
+      if (m) {
+        const n = Number.parseInt(m[1], 10);
+        if (Number.isInteger(n) && n > 0) return n;
+      }
+    }
+    return void 0;
+  }
+  isLossyAsBasic(table) {
+    if (table.footer) return true;
+    if (table.header && table.header.rows.length > 1) return true;
+    const sections = [table.header, table.body, table.footer];
+    for (const section of sections) {
+      if (!section) continue;
+      for (const row of section.rows) {
+        for (const cell of row.cells) {
+          if (cell.rowspan || cell.colspan || cell.scope) return true;
+        }
+      }
+    }
+    return false;
+  }
+  // --- content conversion (HTML -> TextAst) ---------------------------------
+  /**
+   * Convert a cell/li's child nodes into block-level TextAst nodes (paragraphs, lists, images).
+   */
+  blockNodes(nodes) {
+    const blocks = [];
+    let inline = [];
+    const flush = () => {
+      const trimmed = this.trimInline(inline);
+      inline = [];
+      if (trimmed.length === 0) return;
+      if (trimmed.length === 1 && trimmed[0].type === "imageInline") {
+        blocks.push({ ...trimmed[0], type: "image" });
+      } else {
+        blocks.push({ type: "paragraph", content: trimmed, attrs: {} });
+      }
+    };
+    for (const node of nodes) {
+      if (!isElement(node)) {
+        inline.push(...this.inlineText(node.value, []));
+        continue;
+      }
+      const name = node.name;
+      if (name === "p") {
+        flush();
+        const content = this.trimInline(this.inlineNodes(node.children, []));
+        if (content.length > 0) {
+          blocks.push({ type: "paragraph", content, attrs: {} });
+        }
+      } else if (this.isListTag(name)) {
+        flush();
+        const list = this.listNode(node);
+        if (list) blocks.push(list);
+      } else {
+        inline.push(...this.inlineFromElement(node, []));
+      }
+    }
+    flush();
+    return blocks;
+  }
+  /** Convert child nodes to a flat list of inline TextNodes, applying the given marks. */
+  inlineNodes(nodes, marks) {
+    const out = [];
+    for (const node of nodes) {
+      if (!isElement(node)) {
+        out.push(...this.inlineText(node.value, marks));
+      } else {
+        out.push(...this.inlineFromElement(node, marks));
+      }
+    }
+    return out;
+  }
+  inlineFromElement(el, marks) {
+    const name = el.name;
+    if (name === "br") {
+      return [{ type: "hardBreak" }];
+    }
+    if (name === "img") {
+      return [this.imageNode(el, true)];
+    }
+    const markType = MARK_TAGS[name];
+    if (markType) {
+      return this.inlineNodes(el.children, [...marks, { type: markType }]);
+    }
+    if (name === "a") {
+      const linkMark = {
+        type: "link",
+        attrs: {
+          href: el.attrs.href ?? "",
+          ...el.attrs.target ? { target: el.attrs.target } : {}
+        }
+      };
+      return this.inlineNodes(el.children, [...marks, linkMark]);
+    }
+    if (this.keepUnknownTags) {
+      const open = this.serializeOpenTag(el);
+      const close = `</${name}>`;
+      return [
+        ...this.inlineText(open, marks),
+        ...this.inlineNodes(el.children, marks),
+        ...this.inlineText(close, marks)
+      ];
+    }
+    return this.inlineNodes(el.children, marks);
+  }
+  inlineText(raw, marks) {
+    const text = decodeEntities(raw).replace(/\s+/g, " ");
+    if (text === "") return [];
+    const node = { text, type: "text" };
+    if (marks.length > 0) node.marks = marks.map((m) => ({ ...m }));
+    return [node];
+  }
+  serializeOpenTag(el) {
+    const attrs = Object.entries(el.attrs).map(([k, v]) => v === "" ? ` ${k}` : ` ${k}="${v}"`).join("");
+    return `<${el.name}${attrs}>`;
+  }
+  // --- lists ----------------------------------------------------------------
+  isListTag(name) {
+    return name === "ul" || name === "ol";
+  }
+  listNode(el) {
+    const items = childElements(el, LI_TAGS);
+    if (items.length === 0) return void 0;
+    const isTask = el.name === "ul" && items.some((li) => {
+      const firstEl = li.children.find(isElement);
+      return firstEl?.name === "input" && firstEl.attrs.type?.toLowerCase() === "checkbox";
+    });
+    if (isTask) {
+      return {
+        type: "taskList",
+        content: items.map((li) => this.taskItemNode(li))
+      };
+    }
+    const type = this.listType(el);
+    const node = {
+      type,
+      content: items.map((li) => this.listItemNode(li))
+    };
+    if (el.name === "ol") {
+      const start = intAttr(el.attrs.start);
+      if (start != null) {
+        node.attrs = { start };
+      }
+    }
+    return node;
+  }
+  listType(el) {
+    if (el.name === "ol") {
+      switch (el.attrs.type) {
+        case "i":
+          return "orderedListRomanLower";
+        case "I":
+          return "orderedListRoman";
+        case "a":
+          return "letteredListLower";
+        case "A":
+          return "letteredList";
+        default:
+          return "orderedList";
+      }
+    }
+    const style = el.attrs.style ?? "";
+    if (/list-style(-type)?\s*:\s*none/i.test(style)) return "noBulletList";
+    return "bulletList";
+  }
+  listItemNode(li) {
+    let content = this.blockNodes(li.children);
+    if (content.length === 0) {
+      content = [{ type: "paragraph", content: [], attrs: {} }];
+    }
+    return { type: "listItem", content };
+  }
+  taskItemNode(li) {
+    const checkbox = li.children.find(
+      (c) => isElement(c) && c.name === "input" && c.attrs.type?.toLowerCase() === "checkbox"
+    );
+    const checked = checkbox ? "checked" in checkbox.attrs : false;
+    const rest = li.children.filter((c) => c !== checkbox);
+    let content = this.blockNodes(rest);
+    if (content.length === 0) {
+      content = [{ type: "paragraph", content: [], attrs: {} }];
+    }
+    return { type: "taskItem", attrs: { checked }, content };
+  }
+  // --- images ---------------------------------------------------------------
+  imageNode(el, inline) {
+    const attrs = { src: el.attrs.src ?? "" };
+    attrs.alt = el.attrs.alt ?? null;
+    attrs.title = el.attrs.title ?? null;
+    const width = intAttr(el.attrs.width);
+    if (width != null) attrs.width = width;
+    const height = intAttr(el.attrs.height);
+    if (height != null) attrs.height = height;
+    if (el.attrs.class) attrs.class = el.attrs.class;
+    return { type: inline ? "imageInline" : "image", attrs };
+  }
+  // --- whitespace -----------------------------------------------------------
+  /** Trim leading/trailing whitespace from inline content (edges only). */
+  trimInline(nodes) {
+    const out = nodes.slice();
+    const isWs = (n) => n.type === "text" && /^\s*$/.test(n.text ?? "");
+    while (out.length > 0 && isWs(out[0])) out.shift();
+    if (out.length > 0 && out[0].type === "text") {
+      out[0] = { ...out[0], text: (out[0].text ?? "").replace(/^\s+/, "") };
+    }
+    while (out.length > 0 && isWs(out[out.length - 1])) out.pop();
+    if (out.length > 0 && out[out.length - 1].type === "text") {
+      const last = out.length - 1;
+      out[last] = { ...out[last], text: (out[last].text ?? "").replace(/\s+$/, "") };
+    }
+    return out.filter((n) => !(n.type === "text" && n.text === ""));
+  }
+};
+
 // src/BitmarkParserGenerator.ts
 var Input = {
   /**
@@ -43413,7 +44347,11 @@ var InputFormat = {
   /**
    * Input is plain text
    */
-  plainText: "plainText"
+  plainText: "plainText",
+  /**
+   * Input is HTML (used by convertHtmlTable)
+   */
+  html: "html"
 };
 var BitmarkParserGenerator = class {
   constructor() {
@@ -43948,6 +44886,87 @@ var BitmarkParserGenerator = class {
     const res = generator.generate(data);
     return res;
   }
+  /**
+   * Convert between HTML tables and bitmark tables.
+   *
+   * Direction is auto-detected (override with `options.inputFormat`):
+   * - HTML input: every `<table>` is extracted and emitted as a `[.table-extended]` (or `[.table]`)
+   *   bit; output as bitmark (default), JSON, AST, or HTML (re-emit).
+   * - bitmark / JSON / AST input: each `table` / `table-extended` bit is rendered as an HTML
+   *   `<table>` fragment.
+   *
+   * Cell content is reproduced verbatim except inline conversion to bitmark marks (bold, italic,
+   * superscript, etc.), with lists and images mapped to their bitmark equivalents.
+   *
+   * @param input - HTML, bitmark, JSON or AST string; or a parsed JSON/AST value; or a file path.
+   * @param options - the conversion options
+   * @returns the converted output as a string (or object for JSON/AST), or void when writing a file
+   * @throws Error if any error occurs
+   */
+  convertHtmlTable(input, options) {
+    const opts = Object.assign({}, options);
+    if (env.isBrowser && opts.outputFile) {
+      throw new Error("Cannot write to file in browser environment");
+    }
+    let inStr = input;
+    const inputIsString = typeof input === "string";
+    if (env.isNode && inputIsString && fs4.existsSync(inStr)) {
+      inStr = fs4.readFileSync(inStr, { encoding: "utf8" });
+    }
+    const isHtmlString = (s) => {
+      const t = s.replace(/^\s+/, "");
+      return t.startsWith("<") && /<table/i.test(t);
+    };
+    let htmlInput;
+    if (opts.inputFormat === InputFormat.html) {
+      htmlInput = true;
+    } else if (opts.inputFormat != null) {
+      htmlInput = false;
+    } else {
+      htmlInput = inputIsString && isHtmlString(inStr);
+    }
+    if (htmlInput) {
+      const parser2 = new HtmlTableParser();
+      const bits = parser2.parse(inStr, {
+        tableFormat: opts.tableFormat ?? "table-extended",
+        keepUnknownTags: opts.keepUnknownTags,
+        onWarning: (m) => console.warn(m)
+      });
+      const outputFormat2 = opts.outputFormat ?? Output.bitmark;
+      if (outputFormat2 === "html") {
+        const json2 = this.convert(bits, { outputFormat: Output.json });
+        return this.outputHtml(new HtmlTableGenerator().generate(json2), opts);
+      }
+      return this.convert(bits, {
+        outputFormat: Enum23(Output).fromValue(outputFormat2),
+        outputFile: opts.outputFile,
+        fileOptions: opts.fileOptions,
+        jsonOptions: opts.jsonOptions,
+        bitmarkOptions: opts.bitmarkOptions
+      });
+    }
+    const outputFormat = opts.outputFormat ?? "html";
+    if (outputFormat !== "html") {
+      throw new Error(
+        "convertHtmlTable: non-HTML input can only be converted to HTML. Use convert() for bitmark/JSON/AST conversions."
+      );
+    }
+    const json = this.convert(inputIsString ? inStr : input, { outputFormat: Output.json });
+    return this.outputHtml(new HtmlTableGenerator().generate(json), opts);
+  }
+  /**
+   * Write an HTML string to the configured output file, or return it.
+   */
+  outputHtml(html, opts) {
+    if (opts.outputFile) {
+      const output = opts.outputFile.toString();
+      const flag = opts.fileOptions?.append ? "a" : "w";
+      fs4.ensureDirSync(path4.dirname(output));
+      fs4.writeFileSync(output, html, { flag });
+      return;
+    }
+    return html;
+  }
   /**
    * Breakscape bitmark text.
    *
@@ -44243,6 +45262,8 @@ export {
   Builder,
   CardSetVersion,
   FileWriter,
+  HtmlTableGenerator,
+  HtmlTableParser,
   InfoFormat,
   InfoType,
   Input,