feat: drop hidden (w:vanish) text by default

Parse the w:vanish ("Hidden") font effect into a new Run::$isHidden
flag and add an ignoreHiddenText option to Converter and
DocumentConverter. When enabled (the default), hidden runs are omitted
from the HTML and Markdown output so the result matches what Word shows
on screen and in print. The parsed Document still keeps the runs
(flagged isHidden) so transformDocument callbacks can inspect them.
This diverges from mammoth.js, which keeps hidden text; pass
ignoreHiddenText: false to restore the previous behaviour.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mattmilesi

CHANGELOG.md

@@ -11,6 +11,27 @@ Tracked in `ROADMAP.md`. Highlights still pending: DSL list
 matchers (`p:unordered-list(N)`); custom `underline` mappers; CLI
 `--style-map FILE`; track-changes deletion concatenation.
 
+## [0.4.0] — 2026-06-28
+
+### Added
+
+- **Hidden-text handling**: runs carrying the `w:vanish` ("Hidden")
+  font effect are now parsed into a new `Run::$isHidden` flag, and a
+  `Converter` / `DocumentConverter` option `ignoreHiddenText` controls
+  whether they are rendered. The `w:vanish` element follows the usual
+  boolean toggle rules (`w:val="false"` / `"0"` disables the effect).
+
+### Changed
+
+- **Hidden text is dropped by default**: with `ignoreHiddenText` on
+  (the default), runs marked `w:vanish` are omitted from the HTML and
+  Markdown output, so it matches what Word shows on screen and in
+  print. The parsed `Document` still keeps the runs (flagged
+  `isHidden`) so `transformDocument` callbacks can inspect them. This
+  diverges from mammoth.js, which keeps hidden text. Pass
+  `ignoreHiddenText: false` to restore the previous behaviour and emit
+  hidden runs as ordinary text.
+
 ## [0.3.1] — 2026-04-28
 
 ### Fixed

README.md

@@ -36,6 +36,7 @@
   (`\n`, `\r`, `\t`, `\\`, `\'`) inside string literals.
 - `Converter` options: `idPrefix` (namespace HTML ids),
   `ignoreEmptyParagraphs`, `prettyPrint` (indented HTML),
+  `ignoreHiddenText` (drop `w:vanish` "Hidden" runs, on by default),
   `transformDocument` (callback to rewrite the parsed tree before
   rendering), plus `Transforms` helpers
   (`paragraph`, `run`, `elementsOfType`, `elements`, `getDescendants`,

src/Converter.php

@@ -88,6 +88,11 @@ public function __construct(
         // for block elements. Affects only `convertToHtml`; ignored by
         // Markdown and raw-text conversion.
         private readonly bool $prettyPrint = false,
+        // When true (the default), runs carrying the `w:vanish`
+        // ("Hidden") font effect are dropped so the output matches what
+        // Word shows on screen. This diverges from mammoth.js, which
+        // keeps hidden text. Set to false to emit hidden runs as text.
+        private readonly bool $ignoreHiddenText = true,
         // Optional callback that receives the parsed `Document` and
         // returns a (typically modified) `Document` to convert in its
         // place. Mirrors mammoth's `transformDocument` hook -- useful
@@ -275,6 +280,7 @@ private function convert(string $path, callable $write): Result
             idPrefix: $this->idPrefix,
             ignoreEmptyParagraphs: $this->ignoreEmptyParagraphs,
             prettyPrint: $this->prettyPrint,
+            ignoreHiddenText: $this->ignoreHiddenText,
         );
         $htmlResult = $write($converter, $document);
 

src/Document/DocumentConverter.php

@@ -65,6 +65,12 @@ public function __construct(
         // identical because browsers collapse the added whitespace
         // outside of `<pre>`.
         private readonly bool $prettyPrint = false,
+        // When true (the default), runs marked with the `w:vanish`
+        // ("Hidden") font effect are dropped, matching how Word renders
+        // them on screen and in print. This diverges from mammoth.js,
+        // which keeps hidden text. Set to false to emit hidden runs as
+        // ordinary text.
+        private readonly bool $ignoreHiddenText = true,
     ) {
         $this->styleMap = $styleMap ?? StyleMap::default();
         $this->comments = new Comments();
@@ -669,6 +675,10 @@ private static function wrapAsListItem(NumberingLevel $numbering, array $childre
      */
     private function convertRun(Run $run, array &$messages): array
     {
+        if ($this->ignoreHiddenText && $run->isHidden) {
+            return [];
+        }
+
         $nodes = $this->convertNodes($run->children, $messages);
 
         // Inline styling wrappers, innermost first to outermost, matching

src/Document/Run.php

@@ -21,6 +21,7 @@ public function __construct(
         public bool $isStrikethrough = false,
         public bool $isAllCaps = false,
         public bool $isSmallCaps = false,
+        public bool $isHidden = false,
         public VerticalAlignment $verticalAlignment = VerticalAlignment::Baseline,
         public ?string $highlight = null,
         public ?string $font = null,
@@ -45,6 +46,7 @@ public function withChildren(array $children): self
             isStrikethrough: $this->isStrikethrough,
             isAllCaps: $this->isAllCaps,
             isSmallCaps: $this->isSmallCaps,
+            isHidden: $this->isHidden,
             verticalAlignment: $this->verticalAlignment,
             highlight: $this->highlight,
             font: $this->font,

src/Reader/BodyReader.php

@@ -332,6 +332,7 @@ private function readRun(Element $element): Result
                 isStrikethrough: self::readBoolean($properties->first('w:strike')),
                 isAllCaps: self::readBoolean($properties->first('w:caps')),
                 isSmallCaps: self::readBoolean($properties->first('w:smallCaps')),
+                isHidden: self::readBoolean($properties->first('w:vanish')),
                 verticalAlignment: self::readVerticalAlignment($properties->first('w:vertAlign')),
                 highlight: self::readHighlight($properties->first('w:highlight')),
                 font: $properties->first('w:rFonts')?->attribute('w:ascii'),

tests/Unit/Document/DocumentConverterHiddenTextTest.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+use EndlessCreativity\ElephantPhp\Document\Document;
+use EndlessCreativity\ElephantPhp\Document\DocumentConverter;
+use EndlessCreativity\ElephantPhp\Document\Paragraph;
+use EndlessCreativity\ElephantPhp\Document\Run;
+use EndlessCreativity\ElephantPhp\Document\Text;
+
+function htmlOfDocument(Document $document, bool $ignoreHiddenText = true): string
+{
+    return (new DocumentConverter(ignoreHiddenText: $ignoreHiddenText))
+        ->convertToHtml($document)
+        ->value;
+}
+
+/**
+ * @param  list<Run>  $runs
+ */
+function paragraphWithRuns(array $runs): Document
+{
+    return new Document(children: [new Paragraph(children: $runs)]);
+}
+
+it('drops a hidden run by default, keeping surrounding visible text', function (): void {
+    $document = paragraphWithRuns([
+        new Run(children: [new Text(value: 'before')]),
+        new Run(isHidden: true, children: [new Text(value: 'SECRET')]),
+        new Run(children: [new Text(value: 'after')]),
+    ]);
+
+    expect(htmlOfDocument($document))->toBe('<p>beforeafter</p>');
+});
+
+it('emits a hidden run as ordinary text when ignoreHiddenText is false', function (): void {
+    $document = paragraphWithRuns([
+        new Run(children: [new Text(value: 'before')]),
+        new Run(isHidden: true, children: [new Text(value: 'SECRET')]),
+        new Run(children: [new Text(value: 'after')]),
+    ]);
+
+    expect(htmlOfDocument($document, ignoreHiddenText: false))
+        ->toBe('<p>beforeSECRETafter</p>');
+});
+
+it('drops a paragraph whose only content is a hidden run', function (): void {
+    $document = paragraphWithRuns([
+        new Run(isHidden: true, children: [new Text(value: 'entirely hidden')]),
+    ]);
+
+    expect(htmlOfDocument($document))->toBe('');
+});
+
+it('leaves a visible run untouched', function (): void {
+    $document = paragraphWithRuns([
+        new Run(children: [new Text(value: 'visible')]),
+    ]);
+
+    expect(htmlOfDocument($document))->toBe('<p>visible</p>');
+});

tests/Unit/Reader/BodyReaderRunPropertiesTest.php

@@ -39,6 +39,7 @@ function readRun(Element $runXml): Run
     expect($run->isStrikethrough)->toBeFalse();
     expect($run->isAllCaps)->toBeFalse();
     expect($run->isSmallCaps)->toBeFalse();
+    expect($run->isHidden)->toBeFalse();
     expect($run->verticalAlignment)->toBe(VerticalAlignment::Baseline);
 });
 
@@ -49,6 +50,7 @@ function readRun(Element $runXml): Run
     'isStrikethrough' => ['isStrikethrough', 'w:strike'],
     'isAllCaps' => ['isAllCaps', 'w:caps'],
     'isSmallCaps' => ['isSmallCaps', 'w:smallCaps'],
+    'isHidden' => ['isHidden', 'w:vanish'],
 ]);
 
 it('treats a bare property element as enabling the flag (except w:u which needs a value)', function (string $property, string $tagName): void {