feat: add alt, description, name, and anchor:page to ImageOptions

Author: GitHubNewbie0

src/odt/content.ts

@@ -1195,11 +1195,18 @@ function buildImageFrame(
   }
 
   const frame = el("draw:frame")
-    .attr("draw:name", `Image${imageCounter}`)
+    .attr("draw:name", image.name ?? `Image${imageCounter}`)
     .attr("text:anchor-type", image.anchor)
     .attr("svg:width", image.width)
     .attr("svg:height", image.height);
 
+  if (image.alt) {
+    frame.appendChild(el("svg:title").text(image.alt));
+  }
+  if (image.description) {
+    frame.appendChild(el("svg:desc").text(image.description));
+  }
+
   const drawImage = el("draw:image")
     .attr("xlink:href", imagePath)
     .attr("xlink:type", "simple")

src/odt/document.ts

@@ -363,6 +363,9 @@ export class OdtDocument {
       height: options.height,
       mimeType: options.mimeType,
       anchor: options.anchor ?? "paragraph",
+      alt: options.alt,
+      description: options.description,
+      name: options.name,
     };
     this.elements.push({
       type: "image",

src/odt/paragraph-builder.ts

@@ -133,6 +133,9 @@ export class ParagraphBuilder {
       height: options.height,
       mimeType: options.mimeType,
       anchor: options.anchor ?? "as-character",
+      alt: options.alt,
+      description: options.description,
+      name: options.name,
     };
     this.runs.push({ text: "", image: imageData });
     return this;

src/odt/types.ts

@@ -253,8 +253,39 @@ export interface ImageOptions {
    * How the image is anchored in the document.
    * - `"as-character"` — inline with text (default for images inside paragraphs)
    * - `"paragraph"` — anchored to the paragraph (default for standalone `addImage()`)
+   * - `"page"` — anchored to the page (positioned relative to the page)
    */
-  anchor?: "as-character" | "paragraph";
+  anchor?: "as-character" | "paragraph" | "page";
+
+  /**
+   * Accessible label for the image. Maps to `<svg:title>` inside the draw frame.
+   * Used by screen readers and accessibility tools.
+   *
+   * @example
+   * { alt: "Company logo" }
+   * { alt: "LaTeX: \\frac{1}{2}" }
+   */
+  alt?: string;
+
+  /**
+   * Detailed description of the image content. Maps to `<svg:desc>` inside
+   * the draw frame. Useful for preserving metadata such as LaTeX source,
+   * formula text, or extended captions for round-trip editing.
+   *
+   * @example
+   * { description: "$\\frac{1}{2}$" }
+   */
+  description?: string;
+
+  /**
+   * Override the auto-generated frame name. Maps to `draw:name` on the
+   * draw frame. Useful when stable, predictable names are needed for
+   * round-trip editing or LibreOffice extension integration.
+   *
+   * @example
+   * { name: "formula-1" }
+   */
+  name?: string;
 }
 
 /**
@@ -274,7 +305,16 @@ export interface ImageData {
   mimeType: string;
 
   /** Anchor type. */
-  anchor: "as-character" | "paragraph";
+  anchor: "as-character" | "paragraph" | "page";
+
+  /** Accessible label — maps to `<svg:title>`. */
+  alt?: string;
+
+  /** Detailed description — maps to `<svg:desc>`. */
+  description?: string;
+
+  /** Override for the draw:name attribute on the frame. */
+  name?: string;
 }
 
 // ─── List Types ──────────────────────────────────────────────────────

tests/odt-document.test.ts

@@ -1461,6 +1461,98 @@ describe("OdtDocument", () => {
       expect(content).toContain('xmlns:draw="urn:oasis:names:tc:opendocument:xmlns:drawing:1.0"');
       expect(content).toContain('xmlns:xlink="http://www.w3.org/1999/xlink"');
     });
+
+    it("should emit svg:title when alt is provided", async () => {
+      const doc = new OdtDocument();
+      doc.addImage(TEST_PNG, {
+        width: "10cm",
+        height: "6cm",
+        mimeType: "image/png",
+        alt: "Company logo",
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain("<svg:title>Company logo</svg:title>");
+      expect(content).not.toContain("svg:desc");
+    });
+
+    it("should emit svg:desc when description is provided", async () => {
+      const doc = new OdtDocument();
+      doc.addImage(TEST_PNG, {
+        width: "10cm",
+        height: "6cm",
+        mimeType: "image/png",
+        description: "A photograph of the office building",
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain("<svg:desc>A photograph of the office building</svg:desc>");
+      expect(content).not.toContain("svg:title");
+    });
+
+    it("should emit both svg:title and svg:desc before draw:image when both are provided", async () => {
+      const doc = new OdtDocument();
+      doc.addImage(TEST_PNG, {
+        width: "2cm",
+        height: "0.5cm",
+        mimeType: "image/png",
+        alt: "LaTeX: \\frac{1}{2}",
+        description: "$\\frac{1}{2}$",
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain("<svg:title>LaTeX: \\frac{1}{2}</svg:title>");
+      expect(content).toContain("<svg:desc>$\\frac{1}{2}$</svg:desc>");
+      const titlePos = content.indexOf("<svg:title>");
+      const descPos = content.indexOf("<svg:desc>");
+      const imagePos = content.indexOf("draw:image");
+      expect(titlePos).toBeLessThan(descPos);
+      expect(descPos).toBeLessThan(imagePos);
+    });
+
+    it("should use caller-supplied name as draw:name", async () => {
+      const doc = new OdtDocument();
+      doc.addImage(TEST_PNG, {
+        width: "2cm",
+        height: "0.5cm",
+        mimeType: "image/png",
+        name: "formula-1",
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain('draw:name="formula-1"');
+      expect(content).not.toContain('draw:name="Image1"');
+    });
+
+    it("should support anchor type page", async () => {
+      const doc = new OdtDocument();
+      doc.addImage(TEST_PNG, {
+        width: "10cm",
+        height: "6cm",
+        mimeType: "image/png",
+        anchor: "page",
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain('text:anchor-type="page"');
+    });
+
+    it("should emit svg:title with alt in inline paragraph image", async () => {
+      const doc = new OdtDocument();
+      doc.addParagraph((p) => {
+        p.addImage(TEST_PNG, {
+          width: "2cm",
+          height: "0.5cm",
+          mimeType: "image/png",
+          alt: "LaTeX: \\frac{1}{2}",
+          description: "$\\frac{1}{2}$",
+        });
+      });
+
+      const content = await getContentXml(doc);
+      expect(content).toContain("<svg:title>LaTeX: \\frac{1}{2}</svg:title>");
+      expect(content).toContain("<svg:desc>$\\frac{1}{2}$</svg:desc>");
+    });
   });
 
   // ─── Repair Plan: Generation Side Fixes ─────────────────────────────