🥮 mooncakes.io

    This version of the module is deprecated: Use moonbitlang/docx2html instead

    bobzhang/docx2html/docx does not have a README file

    AnnotationAnchor

    source
    pub struct AnnotationAnchor {
      // private fields
    }

    One anchor of a comment: a paired range (start+end), a dangling half-range, or a point (references only). Paths are full agent paths ("/body/p[2]"); references are the comment-reference positions attached to this anchor, in document order.

    AnnotationAnchor::end

    source
    fn AnnotationAnchor::end(self : AnnotationAnchor) -> String?

    The range end's containing projection path, when present.

    AnnotationAnchor::end_boundary

    source

    The end marker's boundary relative to end, when present.

    AnnotationAnchor::references

    source
    fn AnnotationAnchor::references(self : AnnotationAnchor) -> Array[String]

    Comment-reference positions attached to this anchor, in document order.

    AnnotationAnchor::start

    source
    fn AnnotationAnchor::start(self : AnnotationAnchor) -> String?

    The range start's containing projection path, when present.

    AnnotationAnchor::start_boundary

    source

    The start marker's boundary relative to start, when present.

    AnnotationAnchor::story

    source
    fn AnnotationAnchor::story(self : AnnotationAnchor) -> String

    The story this anchor lives in ("/body", "/header[1]", ...).

    AnnotationBoundary

    source
    pub enum AnnotationBoundary {
      Before
      InsideStart
      InsideEnd
      After
    } derive(Eq)

    Where a marker sits relative to its rendered projection node — the plan's boundary distinction, preserved so "before p[3]" and "after p[2]" do not collapse into the same position.

    AnnotationBoundary::equal

    source

    AnnotationBoundary::not_equal

    source

    AnnotationBoundary::output

    source
    fn AnnotationBoundary::output(self : AnnotationBoundary, logger : &Logger) -> Unit

    AnnotationBoundary::to_string

    source
    fn AnnotationBoundary::to_string(self : AnnotationBoundary) -> String

    AnnotationIndex

    source
    pub struct AnnotationIndex {
      // private fields
    }

    The annotation index. Opaque: fields stay private so the surface can evolve additively.

    AnnotationIndex::comments

    source

    Comments: one entry per definition (comments.xml order), then marker-only ids.

    AnnotationIndex::covering_comment_ids

    source
    fn AnnotationIndex::covering_comment_ids(self : AnnotationIndex, path : String) -> Array[String]

    The ids of comments whose anchors INTERSECT the projection element at path ("/body/p[2]" style), in definition order — the reverse link J2's comment_ids exposes. Point anchors cover their reference's paragraph.

    AnnotationIndex::endnotes

    source

    Endnotes with their reference positions.

    AnnotationIndex::footnotes

    source
    fn AnnotationIndex::footnotes(self : AnnotationIndex) -> Array[NoteInfo]

    Footnotes with their reference positions.

    AnnotationIndex::revisions

    source

    Tracked changes across every publicly addressable story, in document order (story order, then position within the story).

    AnnotationIndex::warnings

    source
    fn AnnotationIndex::warnings(self : AnnotationIndex) -> Array[String]

    Non-fatal diagnostics gathered while building the index.

    CommentInfo

    source
    pub struct CommentInfo {
      // private fields
    }

    One comment: identity and metadata from comments.xml (defined is false for a dangling id that only appears in markers), threading from commentsExtended when present, and anchors from the story scans in the total order the plan fixes (story rank, then position).

    CommentInfo::anchors

    source

    Anchors in the plan's total order (story rank, then position).

    CommentInfo::author

    source
    fn CommentInfo::author(self : CommentInfo) -> String?

    The w:author attribute, when present.

    CommentInfo::body_paragraphs

    source
    fn CommentInfo::body_paragraphs(self : CommentInfo) -> Int

    Number of body paragraphs in the comment definition.

    CommentInfo::date

    source
    fn CommentInfo::date(self : CommentInfo) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    CommentInfo::defined

    source
    fn CommentInfo::defined(self : CommentInfo) -> Bool

    False when the id appears only in markers (no definition).

    CommentInfo::done

    source
    fn CommentInfo::done(self : CommentInfo) -> Bool?

    w15 resolution state; None when commentsExtended is absent.

    CommentInfo::id

    source
    fn CommentInfo::id(self : CommentInfo) -> String

    The comment id, as spelled in comments.xml.

    CommentInfo::initials

    source
    fn CommentInfo::initials(self : CommentInfo) -> String?

    The w:initials attribute, when present.

    CommentInfo::last_para_id

    source
    fn CommentInfo::last_para_id(self : CommentInfo) -> String?

    The definition's LAST body paragraph w14:paraId (the commentsExtended key), or None when the paragraph is unstamped.

    CommentInfo::parent_id

    source
    fn CommentInfo::parent_id(self : CommentInfo) -> String?

    The parent comment id for replies (w15 paraIdParent, last-paragraph rule).

    CommentSpec

    source
    pub struct CommentSpec {
      // private fields
    }

    One comment to attach to the written body: WHO (author, optional initials and xsd:dateTime date), WHERE (an inclusive range of top-level body block indexes with both endpoints paragraphs — or, for a reply, the earlier comment it answers), optionally a done resolution flag, and WHAT (paragraph-only body content). Construct with comment_spec (anchored) or comment_reply (anchorless), which fail-close on everything a spec can get wrong in isolation.

    DocxAnnotatedResult

    source
    pub struct DocxAnnotatedResult {
      // private fields
    }

    The package read plus its annotation index. Opaque. Carries the annotation BODIES as (id, body) pairs in reader order — exactly the shape @paths.resolve_annotation_path consumes (J2's read surface).

    The retained source bytes, story scans, and mutation-planning topology of a returned result form a source-pinned IMMUTABLE snapshot: in mutation-safe mode its index scans ARE the retained reader-projection scans (one scan per story part, shared by every consumer). Applying surgery never patches a retained scan in place — the plan writes a new archive, and reading that archive is the only way to observe the mutation.

    DocxAnnotatedResult::annotation_sidecars

    source
    fn DocxAnnotatedResult::annotation_sidecars(self : DocxAnnotatedResult) -> Array[String]

    Relationship types of annotation SIDECARS this tooling cannot keep consistent when mutating comments (Word's modern comment identity and people parts). Per the L0 matrix rule these are detected by RELATIONSHIP TYPE from the main part — their presence makes mutating commands fail closed. commentsExtended is NOT here: the add operation never touches it (matrix row), and L2 owns it.

    DocxAnnotatedResult::annotations

    source

    The annotation index built from the same bytes.

    DocxAnnotatedResult::body_paragraph_span

    source
    fn DocxAnnotatedResult::body_paragraph_span(self : DocxAnnotatedResult, relative_path : String) -> NodeSpan?

    The span of the body-story paragraph at relative_path — the story-relative ORDINAL path exactly as the index emits it ("p[3]", "tbl[1]/tr[2]/tc[1]/p[1]") — or None when no such paragraph was projected. Offsets index into main_story_part's original bytes.

    DocxAnnotatedResult::body_run_span

    source
    fn DocxAnnotatedResult::body_run_span(self : DocxAnnotatedResult, relative_path : String) -> NodeSpan?

    The span of the body-story RUN at relative_path ("p[3]/r[2]", the index's ordinal form), or None. Runs carry the same offsets as paragraphs (content_start past a leading rPr) so L1 can rewrite a self-closing <w:r/> by its own extent too.

    DocxAnnotatedResult::comment_bodies

    source

    Comment (id, body) pairs in comments.xml order.

    DocxAnnotatedResult::comments_extended_part

    source
    fn DocxAnnotatedResult::comments_extended_part(self : DocxAnnotatedResult) -> String?

    The zip entry holding the commentsExtended part (resolved by RELATIONSHIP TYPE), or None when the package has none — L2 then creates it.

    DocxAnnotatedResult::comments_part

    source
    fn DocxAnnotatedResult::comments_part(self : DocxAnnotatedResult) -> String?

    The zip entry holding the comments part (resolved by RELATIONSHIP TYPE from the main part, never by filename), or None when the package has no comments part yet — L1 then creates it.

    DocxAnnotatedResult::comments_story_source

    source
    fn DocxAnnotatedResult::comments_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the comments story, when one was read.

    DocxAnnotatedResult::endnote_bodies

    source

    Endnote (id, body) pairs in reader order.

    DocxAnnotatedResult::endnotes_story_source

    source
    fn DocxAnnotatedResult::endnotes_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the endnotes story, when one was read.

    DocxAnnotatedResult::footer_story_sources

    source

    Physical sources for rendered footer stories in package-result order.

    DocxAnnotatedResult::footnote_bodies

    source

    Footnote (id, body) pairs in reader order.

    DocxAnnotatedResult::footnotes_story_source

    source
    fn DocxAnnotatedResult::footnotes_story_source(self : DocxAnnotatedResult) -> DocxStoryPartSource?

    Physical source for the footnotes story, when one was read.

    DocxAnnotatedResult::header_story_sources

    source

    Physical sources for rendered header stories in package-result order.

    DocxAnnotatedResult::main_story_part

    source
    fn DocxAnnotatedResult::main_story_part(self : DocxAnnotatedResult) -> String

    The zip entry name of the MAIN document part the body-story spans index into (resolved through the officeDocument relationship, never hardcoded).

    DocxAnnotatedResult::main_story_source

    source

    Physical source and authority for the body story.

    DocxAnnotatedResult::paragraph_style_ids

    source
    fn DocxAnnotatedResult::paragraph_style_ids(self : DocxAnnotatedResult) -> Array[String]

    The PARAGRAPH style ids the styles part declares — a COPY, for insertion's style-reference verification.

    DocxAnnotatedResult::result

    source

    The package-level read (identical to read_docx_package).

    DocxAnnotatedResult::revision_spans

    source

    Every tracked-change element across every scanned story, in story order then document order. Offsets index into the part that backs each story.

    The list is complete BY CONSTRUCTION: the scanner records a site for every tracked-change element it walks, without the suppression and projection gates the reading index applies, and retraction never removes one. A resolver can therefore treat an empty result as proof that the package carries no tracked changes at all.

    DocxAnnotatedResult::story_paragraph_span

    source
    fn DocxAnnotatedResult::story_paragraph_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of a paragraph in ANY scanned story ("/comments" included), by its story-relative ordinal path ("comment[2]/p[1]") — offsets index into that story's part bytes. L2's paraId retrofit edits the parent comment's LAST body paragraph through this.

    DocxAnnotatedResult::story_root_span

    source
    fn DocxAnnotatedResult::story_root_span(self : DocxAnnotatedResult, story : String) -> NodeSpan?

    The ROOT element's span for a scanned story ("/body", "/comments", "/footnotes", "/endnotes"), or None when the story was not scanned. L1 splices a new comment definition just before the comments story's close_tag_start; a self-closing root reports no interior and must be rewritten by its own extent first.

    DocxAnnotatedResult::story_row_span

    source
    fn DocxAnnotatedResult::story_row_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of one table ROW in any scanned story, addressed by the story key ("/body", "/header[1]", ...) and the story-relative ordinal path ("tbl[1]/tr[2]"). The scanner already records tr nodes with full spans; template repetition replaces a row's byte region with filled clones through this.

    DocxAnnotatedResult::story_run_span

    source
    fn DocxAnnotatedResult::story_run_span(self : DocxAnnotatedResult, story : String, relative_path : String) -> NodeSpan?

    The span of one text RUN in any scanned story, addressed by the story key ("/body", "/header[1]", ...) and the story-relative ordinal path ("p[3]/r[2]", "p[1]/hyperlink[1]/r[1]"). The scanner already records run nodes with full spans in every story; this generalizes the body-only lookup so template merging can rewrite header and footer runs through the same byte-span contract.

    DocxInsertContent

    source
    pub(all) struct DocxInsertContent {
      style : String?
      runs : Array[DocxInsertRun]
    } derive(Eq, 
    Debug    )

    The dedicated docx.paragraph/1 content payload: an optional paragraph style reference (verified against the TARGET's styles part) and resource-free runs.

    DocxInsertReceipt

    source
    pub struct DocxInsertReceipt {
      // private fields
    }

    What one planned insertion did: the minted id (canonical uppercase, allocated fresh against the whole document's inventory) and the ordinal path the new paragraph will answer to after publication.

    DocxInsertReceipt::para_id

    source
    fn DocxInsertReceipt::para_id(self : DocxInsertReceipt) -> String

    DocxInsertReceipt::planned_path

    source
    fn DocxInsertReceipt::planned_path(self : DocxInsertReceipt) -> String

    DocxInsertRun

    source
    pub(all) struct DocxInsertRun {
      text : String
      bold : Bool
      italic : Bool
      underline : Bool
    } derive(Eq, 
    Debug    )

    One resource-free run of insertion content: text with direct formatting only. Hyperlinks, images, notes, and list bullets are v1 refusals — they need relationship, media, or numbering surgery.

    DocxMatch

    source
    pub struct DocxMatch {
      ordinal : Int
      story : String
      path : String
      start : Int
      end : Int
      text : String
      context_before : String
      context_after : String
      runs : Array[String]
      run_kinds : Array[String]
      actionable : Bool
      reason : String
      para_id : String?
      anchor_status : String
      physical_para_ids : Array[String]
    }

    One candidate the literal matcher found in a story.

    actionable is not a second opinion about editability. It is the PLANNER's own answer: each candidate is offered to plan_paragraph_text_edits as an identity replacement, which runs every structural check and plans no bytes. So a candidate reported actionable here is one the mutation surface accepts, by construction rather than by a parallel classifier that could drift out of step.

    DocxMatch::actionable

    source
    fn DocxMatch::actionable(self : DocxMatch) -> Bool

    Whether the RANGE is structurally editable.

    Precisely: whether the mutation surface accepts an edit over these coordinates, judged by everything it can know from the document alone — regions, ancestry, boundaries, carriers.

    It is NOT a promise that a particular replacement will be accepted. Validity of the new TEXT belongs to the write and is checked there: a replacement carrying a control character is refused over a range this reports actionable, and correctly so, because that refusal is about the caller's string rather than the document.

    DocxMatch::anchor_status

    source
    fn DocxMatch::anchor_status(self : DocxMatch) -> String

    unique, missing, invalid, duplicate, or multi_physical.

    DocxMatch::context_after

    source
    fn DocxMatch::context_after(self : DocxMatch) -> String

    Bounded projection text immediately after the match.

    DocxMatch::context_before

    source
    fn DocxMatch::context_before(self : DocxMatch) -> String

    Bounded projection text immediately before the match.

    DocxMatch::end

    source
    fn DocxMatch::end(self : DocxMatch) -> Int

    Paragraph-relative UTF-16 end, exclusive.

    DocxMatch::ordinal

    source
    fn DocxMatch::ordinal(self : DocxMatch) -> Int

    Position among all candidates in document order, from 1.

    DocxMatch::para_id

    source
    fn DocxMatch::para_id(self : DocxMatch) -> String?

    The canonical w14:paraId, present for unique and duplicate anchor statuses.

    DocxMatch::path

    source
    fn DocxMatch::path(self : DocxMatch) -> String

    The candidate's paragraph, as a body-relative scanner path.

    DocxMatch::physical_para_ids

    source
    fn DocxMatch::physical_para_ids(self : DocxMatch) -> Array[String]

    For multi_physical anchors: the participating physical ids, bounded — joined from several w:p, or sharing one.

    DocxMatch::reason

    source
    fn DocxMatch::reason(self : DocxMatch) -> String

    Why the candidate is not actionable; empty when it is.

    The vocabulary names the construct rather than the mechanism, since what an agent needs is what to do instead: field-region, hyperlink-boundary, tracked-region, sdt-content, alternate-content, textbox, cdata, visible-barrier, suppressed-region, multi-physical-paragraph, non-scalar-boundary, ambiguous-boundary, unsupported-source, checkbox-control, duplicate-source, cross-paragraph-reuse, no-synthesis-carrier, refused-field, malformed-field, field-instruction, internal.

    DocxMatch::run_kinds

    source
    fn DocxMatch::run_kinds(self : DocxMatch) -> Array[String]

    The source kinds the match draws from, deduplicated and in document order: text, tab, no-break-hyphen, soft-hyphen, symbol. A match reading as ordinary prose can still be carried by an atom, and an agent that assumes otherwise will address the wrong thing.

    DocxMatch::runs

    source
    fn DocxMatch::runs(self : DocxMatch) -> Array[String]

    The runs the match draws from, as body-relative paths, in document order. A match crossing run boundaries names each one.

    DocxMatch::start

    source
    fn DocxMatch::start(self : DocxMatch) -> Int

    Paragraph-relative UTF-16 start of the match, over the PROJECTION -- the text a reader sees, not the bytes.

    DocxMatch::story

    source
    fn DocxMatch::story(self : DocxMatch) -> String

    The story the candidate sits in. "body" in v1; the field is reserved so header, footer and note stories can join without a schema break.

    DocxMatch::text

    source
    fn DocxMatch::text(self : DocxMatch) -> String

    The matched projection text.

    DocxMatchList

    source
    pub struct DocxMatchList {
      matches : Array[DocxMatch]
      total : Int
    }

    What a search found: the examined candidates, and how many exist.

    The two are separated because they cost differently. Counting a candidate is a scan step; EXAMINING one runs the planner. So a search counts everything and examines at most limit, and the caller is told both numbers rather than being left to infer the total from a list that was deliberately cut short.

    DocxMatchList::matches

    source
    fn DocxMatchList::matches(self : DocxMatchList) -> Array[DocxMatch]

    The examined candidates, in document order, at most limit of them.

    DocxMatchList::total

    source
    fn DocxMatchList::total(self : DocxMatchList) -> Int

    How many candidates EXIST, which may exceed the examined list.

    DocxMatchList::truncated

    source
    fn DocxMatchList::truncated(self : DocxMatchList) -> Bool

    Whether candidates exist that were counted but not examined.

    DocxPackageResult

    source

    Everything read_docx_with_messages returns, plus sections and header/footer stories.

    DocxPackageResult::equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::equal(DocxPackageResult, DocxPackageResult) -> Bool

    DocxPackageResult::not_equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::not_equal(x : DocxPackageResult, y : DocxPackageResult) -> Bool

    DocxPackageResult::to_repr

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxPackageResult::to_repr(DocxPackageResult) -> 
    Repr

    DocxParaIdCarrierResolution

    source
    pub enum DocxParaIdCarrierResolution {
      ResolvedCarrier(Int)
      CarrierInvalid
      CarrierNotFound
      CarrierAmbiguous(Array[Int])
      CarrierInMultiPhysical
    }

    A carrier-level resolution: the identity judgment WITHOUT the tree step. Its own type, so no consumer can mistake a carrier answer for a tree occurrence.

    DocxParaIdResolution

    source
    pub enum DocxParaIdResolution {
      ResolvedOccurrence(Int, Int)
      ParaIdInvalid
      ParaIdNotFound
      ParaIdAmbiguous(Array[Int])
      ParaIdInMultiPhysical
      ParaIdUnjoined(Int)
    }

    One stable-selector resolution outcome. p[id="…"] resolves to a TREE OCCURRENCE only through the whole chain — validated id, exactly one addressable carrier, sound tree join — and every other state is its own typed refusal. There is no first-wins and no ordinal fallback anywhere in this enum.

    DocxParagraphAnchor

    source
    pub struct DocxParagraphAnchor {
      // private fields
    }

    One logical paragraph's stable-anchor judgment.

    path is where the paragraph is in THIS snapshot; the anchor is what the paragraph IS across structural edits. The two are deliberately separate dimensions — and both are separate from planner editability (actionable), which this layer never touches.

    DocxParagraphAnchor::para_id

    source
    fn DocxParagraphAnchor::para_id(self : DocxParagraphAnchor) -> String?

    The canonical (uppercase) paraId when the spelling is valid and the anchor is a carrier (unique or duplicate); None otherwise.

    DocxParagraphAnchor::physical_para_ids

    source
    fn DocxParagraphAnchor::physical_para_ids(self : DocxParagraphAnchor) -> Array[String]

    For multi_physical anchors only: the valid canonical ids of the participating physical paragraphs, in document order, bounded.

    DocxParagraphAnchor::status

    source
    fn DocxParagraphAnchor::status(self : DocxParagraphAnchor) -> String

    The anchor status: unique, missing, invalid, duplicate, or multi_physical.

    DocxParagraphAnchorIndex

    source
    pub struct DocxParagraphAnchorIndex {
      // private fields
    }

    Per-story anchor index. The AUTHORITATIVE key is the logical paragraph's projection index — paths are NOT unique (a tolerated nested paragraph makes two logical paragraphs share one physical head, hence one path), so a path-keyed lookup refuses collided paths rather than answering for either claimant.

    DocxParagraphAnchorIndex::anchor_at

    source

    Path-keyed lookup for callers that only hold a path. A path claimed by MORE than one logical paragraph returns None: an ambiguous name must not resolve to either claimant's judgment.

    DocxParagraphAnchorIndex::anchor_of_paragraph

    source
    fn DocxParagraphAnchorIndex::anchor_of_paragraph(self : DocxParagraphAnchorIndex, paragraph_index : Int) -> DocxParagraphAnchor?

    The judgment for one projected logical paragraph, by its index in the projection — the join find and the planners already hold.

    DocxParagraphAnchorIndex::paragraphs_with_para_id

    source
    fn DocxParagraphAnchorIndex::paragraphs_with_para_id(self : DocxParagraphAnchorIndex, canonical : String) -> Array[Int]

    Projection indices of the ADDRESSABLE carriers of a canonical id.

    DocxParagraphAnchorIndex::resolve_para_id_carrier

    source
    fn DocxParagraphAnchorIndex::resolve_para_id_carrier(self : DocxParagraphAnchorIndex, raw : String) -> DocxParaIdCarrierResolution

    The identity judgment WITHOUT the tree step: resolve an as-spelled paraId to its single addressable carrier's projection index, or the typed reason it never resolves. Scan-path consumers (find scopes, the write verbs) build on this; tree surfaces add the join step.

    DocxParagraphAnchorIndex::scan_path_of_paragraph

    source
    fn DocxParagraphAnchorIndex::scan_path_of_paragraph(self : DocxParagraphAnchorIndex, paragraph_index : Int) -> String?

    The scanner paragraph path a projection paragraph answers to in THIS snapshot.

    DocxParagraphAnchorJoinIndex

    source
    pub struct DocxParagraphAnchorJoinIndex {
      // private fields
    }

    The tree/projection join for one story (paraId R1b): tree paragraph occurrences in erase order, each mapped to at most one projection paragraph by source-vector bijection.

    DocxParagraphAnchorJoinIndex::anchor_index

    source

    The anchor index this join was judged against, for callers that need scan paths or per-paragraph anchors beside the resolution.

    DocxParagraphAnchorJoinIndex::join_of_occurrence

    source
    fn DocxParagraphAnchorJoinIndex::join_of_occurrence(self : DocxParagraphAnchorJoinIndex, occurrence : Int) -> DocxParagraphJoin?

    The join for the Nth tree Paragraph occurrence, in the depth-first order the erased tree presents them. None when the occurrence is out of range — a caller whose own enumeration disagrees with the provenance channel must treat EVERY paragraph as unjoined.

    DocxParagraphAnchorJoinIndex::occurrence_count

    source

    Number of paragraph occurrences represented by this story join.

    DocxParagraphAnchorJoinIndex::occurrence_of_paragraph

    source
    fn DocxParagraphAnchorJoinIndex::occurrence_of_paragraph(self : DocxParagraphAnchorJoinIndex, paragraph_index : Int) -> Int?

    The R2a seam: the unique tree occurrence a projection paragraph joined to, if the bijection held in both directions.

    DocxParagraphAnchorJoinIndex::resolve_para_id

    source

    Resolve one as-spelled paraId to a tree occurrence.

    DocxParagraphJoin

    source
    pub enum DocxParagraphJoin {
      Joined(Int, DocxParagraphAnchor)
      Unjoined(String)
    }

    One tree paragraph occurrence's relationship to the projection: the judgment travels ONLY across a proven bijection. Unjoined is a JOIN outcome, not a sixth anchor status — the engine vocabulary is unchanged, and a tree surface reporting it says "no sound correspondence", never a borrowed judgment.

    DocxReadResult

    source

    Document tree plus diagnostics produced while reading a DOCX package.

    DocxReadResult::equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::equal(DocxReadResult, DocxReadResult) -> Bool

    DocxReadResult::not_equal

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::not_equal(x : DocxReadResult, y : DocxReadResult) -> Bool

    DocxReadResult::to_repr

    source
    #deprecated("implicit trait-method promotion is being removed; call via the trait")
    fn DocxReadResult::to_repr(DocxReadResult) -> 
    Repr

    DocxReplaceAffected

    source
    pub struct DocxReplaceAffected {
      path : String
      expected : String
      para_id : String?
      anchor_status : String
    }

    One affected paragraph: its path, and the full projection text it must carry after the splice.

    The expectation is the WHOLE paragraph projection, precomputed at plan time — never a substring probe, because the replacement text may pre-exist elsewhere in the same paragraph and a substring check would pass on a splice that landed in the wrong place.

    DocxReplaceAffected::anchor_status

    source
    fn DocxReplaceAffected::anchor_status(self : DocxReplaceAffected) -> String

    The paragraph's anchor status (unique, missing, invalid, duplicate), copied from its selected matches. Never multi_physical: the planner refuses those.

    DocxReplaceAffected::expected

    source
    fn DocxReplaceAffected::expected(self : DocxReplaceAffected) -> String

    The full projection text the paragraph must read after the edit.

    DocxReplaceAffected::para_id

    source
    fn DocxReplaceAffected::para_id(self : DocxReplaceAffected) -> String?

    The paragraph's canonical anchor paraId, when the source carries one (the anchor judgment copied from its selected matches).

    DocxReplaceAffected::path

    source
    fn DocxReplaceAffected::path(self : DocxReplaceAffected) -> String

    The paragraph's body-relative path.

    DocxReplaceReceipt

    source
    pub struct DocxReplaceReceipt {
      selected : Array[Int]
      replaced : Int
      affected : Array[DocxReplaceAffected]
      matches : Array[DocxMatch]
    }

    What a planned replacement will do, and what the document must read afterwards.

    DocxReplaceReceipt::affected

    source

    The affected paragraphs with their expected post-edit projections.

    DocxReplaceReceipt::matches

    source

    The selected candidates themselves — the same entries find would report, so a dry-run can print the matches payload the roadmap promises rather than a summary that hides ranges and runs.

    DocxReplaceReceipt::replaced

    source
    fn DocxReplaceReceipt::replaced(self : DocxReplaceReceipt) -> Int

    How many replacements the plan performs.

    DocxReplaceReceipt::selected

    source
    fn DocxReplaceReceipt::selected(self : DocxReplaceReceipt) -> Array[Int]

    The candidate ordinals this plan replaces, in document order.

    DocxStoryPartAuthority

    source
    pub enum DocxStoryPartAuthority {
      RelationshipBacked
      LegacyFilenameFallback
    }

    How the reader selected a physical story part.

    DocxStoryPartAuthority::name

    source

    Stable protocol spelling for story-part authority.

    DocxStoryPartSource

    source
    pub struct DocxStoryPartSource {
      // private fields
    }

    The physical ZIP entry used for one logical DOCX story and how it was selected. The type is opaque so more provenance can be added later without exposing mutable reader internals.

    DocxStoryPartSource::authority

    source

    Whether this part was relationship-backed or a legacy filename fallback.

    DocxStoryPartSource::part

    source
    fn DocxStoryPartSource::part(self : DocxStoryPartSource) -> String

    The exact physical ZIP entry read for this story.

    HeaderFooterSpec

    source
    pub struct HeaderFooterSpec {
      // private fields
    }

    One header or footer story attached to the written document's section. Construct with header_footer_spec, which fail-closes on everything the story can get wrong in isolation.

    NodeSpan

    source
    pub struct NodeSpan {
      // private fields
    }

    The byte extent of one BODY-story projection node (paragraph or run) in the original word-processing part, plus the two insertion offsets annotation surgery uses: content_start (just past the open tag AND past a leading pPr/rPr — the property container leads its sequence, so content and markers must land after it) and close_tag_start (the '<' of the close tag). Both are None for a self-closing form, which has no interior — the splice layer must first rewrite it to the open form (a byte edit of this node's own span).

    NodeSpan::byte_end

    source
    fn NodeSpan::byte_end(self : NodeSpan) -> Int

    Offset just past the '>' of the paragraph's close tag (exclusive).

    NodeSpan::byte_start

    source
    fn NodeSpan::byte_start(self : NodeSpan) -> Int

    Offset of the '<' of the paragraph's open tag.

    NodeSpan::close_tag_start

    source
    fn NodeSpan::close_tag_start(self : NodeSpan) -> Int?

    Offset of the '<' of the close tag, or None for a self-closing paragraph.

    NodeSpan::content_start

    source
    fn NodeSpan::content_start(self : NodeSpan) -> Int?

    Earliest interior insertion offset (past the open tag and any leading pPr), or None for a self-closing paragraph.

    NodeSpan::self_closing

    source
    fn NodeSpan::self_closing(self : NodeSpan) -> Bool

    True when the paragraph is the self-closing <w:p/> form.

    NoteInfo

    source
    pub struct NoteInfo {
      // private fields
    }

    One footnote/endnote: its id and every body position referencing it (multi-reference notes are representable per the plan).

    NoteInfo::id

    source
    fn NoteInfo::id(self : NoteInfo) -> String

    The note id, as spelled.

    NoteInfo::references

    source
    fn NoteInfo::references(self : NoteInfo) -> Array[String]

    Every body position referencing this note, in document order.

    NoteSpec

    source
    pub struct NoteSpec {
      // private fields
    }

    One footnote or endnote body: plain-content, paragraph-only, and no note references of its own (notes do not nest). Construct with note_spec.

    RevisionInfo

    source
    pub struct RevisionInfo {
      // private fields
    }

    One tracked change: what kind of revision it is, who made it, when they said they made it, and the projection path of the paragraph that contains it.

    The reader flattens w:ins into the accepted text and drops w:del entirely, so a revision has no representation in the parsed document at all. This record is the only place the identity survives, and it is read-only: text still returns the accepted view, unchanged.

    id, author and date are the attributes AS SPELLED and stay absent when the source omits them. All three are optional in CT_TrackChange; a defaulted author or date would make the index assert authorship the document never recorded.

    RevisionInfo::author

    source
    fn RevisionInfo::author(self : RevisionInfo) -> String?

    The w:author attribute, when present.

    RevisionInfo::date

    source
    fn RevisionInfo::date(self : RevisionInfo) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    RevisionInfo::id

    source
    fn RevisionInfo::id(self : RevisionInfo) -> String?

    The w:id attribute, as spelled, when present.

    RevisionInfo::kind

    source
    fn RevisionInfo::kind(self : RevisionInfo) -> String

    "ins" for an insertion, "del" for a deletion.

    RevisionInfo::path

    source
    fn RevisionInfo::path(self : RevisionInfo) -> String

    The story-qualified projection path of the containing paragraph ("/body/p[2]"), degrading to the nearest verifiable ancestor.

    RevisionNameEdit

    source
    pub struct RevisionNameEdit {
      // private fields
    }

    One element-name rewrite: the byte range of an element's LOCAL NAME in the original part, and the name it becomes. Rejecting a deletion turns every w:delText back into w:t through these ranges, which leaves the namespace prefix, xml:space, and every other byte of the tag untouched.

    RevisionNameEdit::end

    source
    fn RevisionNameEdit::end(self : RevisionNameEdit) -> Int

    Offset just past the last byte of the local name (exclusive).

    RevisionNameEdit::replacement

    source
    fn RevisionNameEdit::replacement(self : RevisionNameEdit) -> String

    The local name that replaces the range ("t" or "instrText").

    RevisionNameEdit::start

    source
    fn RevisionNameEdit::start(self : RevisionNameEdit) -> Int

    Offset of the first byte of the local name.

    RevisionSpan

    source
    pub struct RevisionSpan {
      // private fields
    }

    One tracked-change ELEMENT in the original bytes: what it is, who recorded it, and the byte extent a resolver needs to unwrap or remove it.

    This is the MUTATION view of a revision and is deliberately wider than AnnotationIndex::revisions, which is the READING view. Reading reports the content insertions and deletions the reader's projection retains; resolving must additionally see every construct it cannot act on, because a construct it cannot see is a construct it would silently leave behind. supported separates the two: it is true only for content w:ins and w:del, false for property revisions, moves, and every *PrChange.

    RevisionSpan::author

    source
    fn RevisionSpan::author(self : RevisionSpan) -> String?

    The w:author attribute, as spelled, when present.

    RevisionSpan::byte_end

    source
    fn RevisionSpan::byte_end(self : RevisionSpan) -> Int

    Offset just past the '>' that ends the element (exclusive).

    RevisionSpan::byte_start

    source
    fn RevisionSpan::byte_start(self : RevisionSpan) -> Int

    Offset of the '<' of the element's open tag.

    RevisionSpan::close_tag_start

    source
    fn RevisionSpan::close_tag_start(self : RevisionSpan) -> Int?

    Offset of the '<' of the close tag, or None for the self-closing form.

    RevisionSpan::container_path

    source
    fn RevisionSpan::container_path(self : RevisionSpan) -> String?

    The story-relative projection path of the innermost containing node ("p[2]", "tbl[1]/tr[1]/tc[1]/p[1]"), or None at story level.

    RevisionSpan::content_start

    source
    fn RevisionSpan::content_start(self : RevisionSpan) -> Int?

    Offset just past the '>' of the open tag, or None for the self-closing form — which has no content to keep, so all four resolutions of it collapse to removing the element.

    RevisionSpan::date

    source
    fn RevisionSpan::date(self : RevisionSpan) -> String?

    The w:date attribute, LEXICAL (never converted), when present.

    RevisionSpan::declares_namespaces

    source
    fn RevisionSpan::declares_namespaces(self : RevisionSpan) -> Bool

    True when the element's own start tag binds a namespace prefix. Unwrapping it would drop the binding while its former children still use it, so an unwrap resolution must refuse; removing the whole element stays safe.

    RevisionSpan::id

    source
    fn RevisionSpan::id(self : RevisionSpan) -> String?

    The w:id attribute, as spelled, when present.

    RevisionSpan::kind

    source
    fn RevisionSpan::kind(self : RevisionSpan) -> String

    The WML local name of the element ("ins", "del", "moveFrom", "rPrChange").

    RevisionSpan::name_edits

    source
    fn RevisionSpan::name_edits(self : RevisionSpan) -> Array[RevisionNameEdit]

    The w:delText/w:delInstrText names inside this deletion, in document order; empty for an insertion. Rejecting the deletion applies all of them.

    RevisionSpan::story

    source
    fn RevisionSpan::story(self : RevisionSpan) -> String

    The story key the span's offsets index into ("/body", "/header[1]").

    RevisionSpan::supported

    source
    fn RevisionSpan::supported(self : RevisionSpan) -> Bool

    True only for a content w:ins/w:del a resolver can accept or reject.

    RunTextReceipt

    source
    pub struct RunTextReceipt {
      // private fields
    }

    What an addressed run replacement planned: the story part, the address that named the run, the reader-visible text the caller expected (and the plan replaces), and how many byte edits carry it.

    RunTextReceipt::at_relative

    source
    fn RunTextReceipt::at_relative(self : RunTextReceipt) -> String

    The story-relative ordinal run path that named the run (for example p[1]/r[2]), echoed back once it has resolved to exactly one run in this story -- unique among the scan's run nodes AND among the projected runs. Against this same snapshot it stays valid, so a caller may re-plan with expect=replaced_text(). Once the plan is APPLIED the address is only meaningful again after a fresh mutation-safe read, since ordinals are snapshot-relative.

    RunTextReceipt::edit_count

    source
    fn RunTextReceipt::edit_count(self : RunTextReceipt) -> Int

    How many byte edits the plan carries. It is a size, not a count of runs or characters -- one addressed run can need several edits. Zero means the replacement was the run's own text: the address, the expectation and the run's writability were all still checked, and the plan edits nothing rather than re-encoding bytes that already say it.

    RunTextReceipt::replaced_text

    source
    fn RunTextReceipt::replaced_text(self : RunTextReceipt) -> String

    The expect string the caller passed, returned only after it was checked equal to the run's reader-visible text. So this is both what the caller asserted and what the run actually held: a receipt exists only when those agree.

    RunTextReceipt::result_text

    source
    fn RunTextReceipt::result_text(self : RunTextReceipt) -> String

    The text the addressed run holds once this plan is applied to the package it was built from: reading that result back through the reader reproduces exactly this for that run. The plan pins only the story part, so applying it to a different archive that happens to carry the same story bytes is not covered by that claim. When result_text equals replaced_text the run already holds it and the plan is empty.

    RunTextReceipt::story_part

    source
    fn RunTextReceipt::story_part(self : RunTextReceipt) -> String

    The story part the addressed run lives in, spelled exactly as the annotated read exposed it (for example word/document.xml). It is the only part the returned plan targets: the plan pins it, and any edit the plan carries is an edit to it. A self-replacement carries none.

    MAX_AUTHORED_MEDIA_BYTES

    source
    let MAX_AUTHORED_MEDIA_BYTES : Int64

    Maximum aggregate emitted-media bytes, summed over image occurrences rather than unique assets.

    MAX_AUTHORED_MEDIA_PARTS

    source
    let MAX_AUTHORED_MEDIA_PARTS : Int

    Maximum distinct media parts a fresh-authoring script may emit (one per image OCCURRENCE, not per unique asset), and the aggregate emitted-media byte ceiling summed over occurrences. Enforced BEFORE the writer graph is built, so a script that references one asset thousands of times is refused as a typed media limit rather than after materializing every part.

    author_docx_bytes

    source

    Builds a fresh DOCX from an already-parsed docx.batch/2 script and the image bytes its image_paths() referenced. Body/comment/note construction errors surface as Unsupported carrying the script op address; a bounded serialization or emitted-media ceiling breach surfaces as WriteResourceLimit. Nothing is written — the caller publishes the returned bytes through its own transaction/atomic-write boundary.

    comment_anchor_fragments

    source
    fn comment_anchor_fragments(id~ : String, wordprocessing_namespace? : String) -> (String, String)

    The two anchor fragments for comment id: the range start (spliced at the from-paragraph's content_start) and the range end plus the reference run (spliced at the to-paragraph's close_tag_start) — the same canonical shape the K1 writer emits, in self-contained form.

    comment_definition_fragment

    source
    fn comment_definition_fragment(spec : CommentSpec, id~ : String, para_ids? : Array[String], max_output_bytes? : Int, wordprocessing_namespace? : String) -> String raise 
    DocxError

    The w:comment definition fragment for spec (whose anchored range is ignored here — the splice layer owns placement). The body is re-validated (the arrays stay caller-mutable) and serialized through the same body writers as the packaging path, under the same fail-closed guard against relationship-bearing content.

    comment_reply

    source
    fn comment_reply(author~ : String, initials? : String, date? : String, reply_to~ : Int, done? : Bool, body : Array[
    DocumentElement    ]) -> CommentSpec raise 
    DocxError

    Validates and builds an anchorless REPLY: reply_to is the 0-based index of an EARLIER spec in the array passed to write_docx_with_comments (checked against the array there; chains are allowed — a reply may answer another reply). Per the locked policy a reply emits NO range or reference markers: its parent's anchor is logically its own, and the thread linkage lives in word/commentsExtended.xml (w15:paraIdParent). Everything else — author/initials/date rules, the plain-content paragraph-only body — matches comment_spec.

    comment_spec

    source
    fn comment_spec(author~ : String, initials? : String, date? : String, from~ : Int, to~ : Int, done? : Bool, body : Array[
    DocumentElement    ]) -> CommentSpec raise 
    DocxError

    Validates and builds a CommentSpec. from/to are 0-based indexes into the body array later passed to write_docx_with_comments (the inclusive anchored range); bounds against that body are checked at write time, everything spec-local is checked here so callers can attribute the failure to the exact comment: non-empty attribute-safe author, non-empty attribute-safe initials (when given), a lexically valid xsd:dateTime date (when given), an ordered non-negative range, and a non-empty paragraph-only body. Bodies are PLAIN CONTENT by the roadmap's locked rule — hyperlinks (even relationship-free anchor-only ones) and images are rejected here, and again at write time because the arrays stay caller-mutable.

    convert

    source
    fn convert(docx : BytesView, output_format? : 
    OutputFormat    , style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, pretty_print? : Bool, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes using the requested output format.

    convert_to_html

    source
    fn convert_to_html(docx : BytesView, style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, pretty_print? : Bool, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes to HTML.

    convert_to_markdown

    source
    fn convert_to_markdown(docx : BytesView, style_map? : Array[String], include_default_style_map? : Bool, include_embedded_style_map? : Bool, ignore_empty_paragraphs? : Bool, id_prefix? : String, convert_image? : (
    Image    ) -> 
    ImageConversion    , transform_document? : (
    DocumentElement    ) -> 
    DocumentElement    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Converts DOCX bytes to Markdown.

    docx_paragraph_anchor_index

    source

    Build the anchor index for one story.

    Duplicate detection is PART-SCOPED over every WML w:p the scan retained (the reader-selected view of the part) — not merely the projected logical paragraphs — because Word's uniqueness rule is per part, and a collision hiding in suppressed content still makes the id unaddressable. Only VALID spellings can collide: an invalid value is not an identity, so it neither claims nor contests one.

    docx_paragraph_anchor_join_index

    source

    Build the story's tree/projection join.

    A tree occurrence joins a projection paragraph only when ALL hold: the source vectors are exactly equal; exactly one occurrence and one projection paragraph claim that vector; and every physical source in the vector participates in exactly one projection paragraph. The last condition kills the false match the nested-paragraph shape offers (the outer tree paragraph's [host] superficially equals the post-half projection paragraph's [host], but the host also participates in the joined head) — refusing beats first-wins.

    docx_paragraph_projection

    source
    fn docx_paragraph_projection(annotated : DocxAnnotatedResult, story : DocxStoryPartSource, path~ : String) -> String?

    One paragraph's full projection text, by its body-relative path.

    This is the readback half of the replace contract: after a splice is applied, the transaction re-reads the candidate and compares each affected paragraph's projection — through THIS accessor — against the receipt's precomputed expectation. None means the path names no paragraph in the story, which a readback must treat as a mismatch rather than a pass.

    embed_style_map

    source
    fn embed_style_map(docx : BytesView, style_map : String) -> Bytes raise 
    DocxError

    Embeds or replaces the DOCX style map part.

    extract_raw_text

    source
    fn extract_raw_text(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    ConversionResult     raise 
    DocxError

    Extracts raw text from DOCX bytes.

    find_docx_matches

    source
    fn find_docx_matches(annotated : DocxAnnotatedResult, story : DocxStoryPartSource, needle~ : String, within? : String, context? : Int, limit? : Int) -> DocxMatchList raise 
    DocxError

    List every literal candidate for needle, in document order.

    This is a READ. Zero matches is an empty list and not a refusal -- only a mutation fails closed on finding nothing. What can still refuse is the request itself: an empty needle names every position, and a story with no retained projection cannot be searched.

    within restricts to a subtree by body-relative path prefix, so p[3] takes one paragraph and tbl[1] takes a whole table.

    At most limit candidates are EXAMINED. Every examined candidate costs a planner run, so the bound is on work rather than only on output; candidates past it are counted through ordinal but carry no verdict, and the caller sees fewer entries than the last ordinal.

    Validates and builds one header/footer story. variant is the OOXML reference type (default, first or even); the body is non-empty and block-level (paragraphs and tables), plain content all the way down.

    mint_para_id

    source
    fn mint_para_id(used : Array[String]) -> String raise 
    DocxError

    Mint a fresh paraId: the smallest canonical value not in used. Deterministic by design — tests assert validity and freshness, never an allocator sequence — and conservative: used should carry every id seen anywhere in the package, buried and invalid spellings included, so a mint can never collide with anything a future repair might surface.

    new_blank_docx

    source
    fn new_blank_docx() -> Bytes

    Builds a minimal, schema-valid blank docx: one empty paragraph, a body-final section (Letter, one-inch margins), and a Normal style. All inputs are compile-time constants, so builder failures are programming errors — hence the abort rather than a raise.

    new_blank_docx_limited

    source

    Like new_blank_docx, but serialized under limits so a fresh-creation transaction can bound the candidate BEFORE allocation (the blank package is a small constant, so this never actually breaches — it keeps the create path on the same bounded-writer contract as authored documents). An over- limit ceiling surfaces as the typed WriteResourceLimit.

    note_spec

    source

    Validates and builds a NoteSpec. The body rules match comment bodies (non-empty, paragraph-only, plain content) plus the no-nesting rule; they are re-checked at write time because the arrays stay caller-mutable. Which KIND the note is (footnote or endnote) is decided by which array it is passed in, so one spec type serves both.

    para_id_inventory_archive_limited

    source
    fn para_id_inventory_archive_limited(annotated : DocxAnnotatedResult, archive : 
    Archive    , xml_budget : 
    XmlReadBudget    ) -> Map[String, Array[String]] raise 
    DocxError

    The document's per-part w14:paraId inventory: every reachable story part mapped to its raw attribute values in document order. No judgment is applied — invalid spellings and duplicates are listed as they stand, because the caller's question is "what did the operation CHANGE about the identity state", not "is the identity state clean". The delta judgment lives in para_id_state_delta_violation.

    para_id_state_delta_violation

    source
    fn para_id_state_delta_violation(source : Map[String, Array[String]], candidate : Map[String, Array[String]]) -> String?

    The identity DELTA judgment for a mutation's candidate against its source, part-scoped per Word's uniqueness rule. Existing dirt may SURVIVE — real documents carry duplicate and invalid ids, and a text edit must not be hostage to them — and removals are always fine (consumed content takes its ids with it). What a write may never do:

    • introduce an invalid spelling the part did not already carry (per raw spelling, count-bounded by the source), or
    • increase a valid id's per-part occupancy beyond one — creating a NEW collision or deepening an existing one. Case-insensitive: 1a… and 1A… are the same identity.

    Returns the first violation's description, or None when the delta is acceptable. Cross-part equality is NOT a violation — identity scope is the part.

    plan_comment_addition

    source
    fn plan_comment_addition(annotated : DocxAnnotatedResult, original : BytesView, at_relative~ : String, to_relative~ : String, spec : CommentSpec, max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Builds the splice plan that adds one comment to the ORIGINAL package: anchor markers into the main part at scanner offsets (self-closing paragraphs rewritten by their own extent), the definition into the existing comments part (self-closing roots rewritten too) or a fresh part derived from the MAIN part's directory, wired with a parsed-not-guessed relationship id and a content-type Override located at the BYTE level. Returns the plan and the allocated comment id.

    plan_comment_addition_archive

    source
    fn plan_comment_addition_archive(annotated : DocxAnnotatedResult, archive : 
    Archive    , at_relative~ : String, to_relative~ : String, spec : CommentSpec, xml_budget? : 
    XmlReadBudget    , max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Archive-backed form used by preservation-safe edit sessions. It reuses the caller's already bounded, materialized package and never inflates the DOCX a second time.

    plan_comment_reply

    source
    fn plan_comment_reply(annotated : DocxAnnotatedResult, original : BytesView, parent_id~ : String, spec : CommentSpec, max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Builds the splice plan for docx annotate reply: the reply's definition (paraId-stamped) into comments.xml plus the whole-part commentsExtended update (parent retrofit included). Returns the plan and the reply's new comment id.

    plan_comment_reply_archive

    source
    fn plan_comment_reply_archive(annotated : DocxAnnotatedResult, archive : 
    Archive    , parent_id~ : String, spec : CommentSpec, xml_budget? : 
    XmlReadBudget    , max_fragment_bytes? : Int) -> (
    SplicePlan    , String) raise 
    DocxError

    Archive-backed reply planner for bounded preservation sessions.

    plan_comment_resolution

    source
    fn plan_comment_resolution(annotated : DocxAnnotatedResult, original : BytesView, comment_id~ : String, done~ : Bool) -> 
    SplicePlan     raise 
    DocxError

    Builds the splice plan for docx annotate resolve|unresolve: the comment's commentsExtended entry flips (or gains) its w15:done flag, with the same paraId retrofit as replies when the definition is unstamped.

    plan_comment_resolution_archive

    source

    Archive-backed resolution planner for bounded preservation sessions.

    plan_docx_paragraph_insertion

    source
    fn plan_docx_paragraph_insertion(annotated : DocxAnnotatedResult, at~ : String, before~ : Bool, content~ : DocxInsertContent, used_para_ids~ : Array[String]) -> (
    SplicePlan    , DocxInsertReceipt) raise 
    DocxError

    Plan one paragraph insertion beside a DIRECT body paragraph.

    at is the direct body ordinal path ("p[3]" — nested paragraphs are not insertion anchors); before picks which side of it the new paragraph lands on. used_para_ids is the caller's complete inventory (the transaction already holds it for the delta gate). The returned plan splices ONLY the insertion; the receipt carries the minted id and the path the paragraph will answer to.

    plan_docx_replacements

    source
    fn plan_docx_replacements(annotated : DocxAnnotatedResult, story : DocxStoryPartSource, needle~ : String, replacement~ : String, within? : String, nth? : Int) -> (
    SplicePlan    , DocxReplaceReceipt) raise 
    DocxError

    Plan replacing needle with replacement in the body story.

    The locked selection semantics, verbatim from the roadmap:

    • Ordinals run over ALL candidates in document order, including restricted ones — the same ordinals find reports.
    • nth selects ONE candidate by that ordinal, BEFORE actionability is considered; selecting a restricted candidate is a refusal that names its reason, not a skip.
    • Without nth, every candidate is selected, and ANY restricted candidate in scope refuses — replace never silently skips what find reports.

    Zero candidates plans nothing and returns an empty receipt; whether that is an error belongs to the caller (--allow-zero is CLI policy, not engine fact).

    The returned plan is pinned to the annotated read's retained bytes, so applying it to any other snapshot refuses as stale.

    plan_run_text_replacement

    source
    fn plan_run_text_replacement(annotated : DocxAnnotatedResult, story : DocxStoryPartSource, at_relative~ : String, expect~ : String, text~ : String) -> (
    SplicePlan    , RunTextReceipt) raise 
    DocxError

    Plans the replacement of one addressed run's whole text with text.

    story must be a story part source the annotated result itself exposed, and the result must come from a MUTATION-SAFE read: only those retain the classified projection this planner consumes. at_relative is the story-relative ordinal run path (p[3]/r[2]), resolved against the projection's own physical scan. expect is REQUIRED and must equal the run's reader-visible text: addresses are snapshot-relative, and a stale expectation refuses rather than editing whatever now sits at the path.

    Every failure is a typed refusal; nothing falls back. The planner takes NO archive: it plans against the exact source bytes the annotated read retained beside the projection, so a mismatched archive cannot be smuggled in -- and the returned plan is pinned to those same bytes, so applying it to anything else refuses as stale.

    read_docx

    source
    fn read_docx(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> 
    DocumentElement     raise 
    DocxError

    Reads DOCX bytes into a document tree.

    read_docx_annotated

    source
    fn read_docx_annotated(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxAnnotatedResult raise 
    DocxError

    Reads DOCX bytes into the package representation PLUS the annotation index. The package half is identical to read_docx_package.

    read_docx_annotated_archive

    source
    fn read_docx_annotated_archive(archive : 
    Archive    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxAnnotatedResult raise 
    DocxError

    Builds the same package and annotation indexes from a caller-owned archive snapshot. Payload buffers are shared; the DOCX reader does not inflate the package a second time. Duplicate entry names fail before the map-backed view is constructed.

    read_docx_annotated_archive_joined_projection_limited

    source
    fn read_docx_annotated_archive_joined_projection_limited(archive : 
    Archive    , xml_budget : 
    XmlReadBudget    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?, max_diagnostics? : Int, max_diagnostic_chars? : Int, expected_main_document_path? : String) -> DocxAnnotatedResult raise 
    DocxError

    Builds a read-only projection with the joined story reader while retaining tolerant annotation identities. This is the projection command's single read path: strict story correspondence is available for paragraph anchors, but mutation-only identity gates remain disabled.

    read_docx_annotated_archive_limited

    source
    fn read_docx_annotated_archive_limited(archive : 
    Archive    , xml_budget : 
    XmlReadBudget    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?, max_diagnostics? : Int, max_diagnostic_chars? : Int, expected_main_document_path? : String) -> DocxAnnotatedResult raise 
    DocxError

    Builds package and annotation indexes from an existing archive while every XML part shares one cumulative parser budget. Source bytes are charged before UTF-8 decoding and parser tokens before DOM allocation. Reader diagnostics are deduplicated in first-seen order and bounded during production by max_diagnostics and max_diagnostic_chars.

    read_docx_annotated_archive_tolerant_limited

    source
    fn read_docx_annotated_archive_tolerant_limited(archive : 
    Archive    , xml_budget : 
    XmlReadBudget    , external_file_access? : Bool, read_external_file? : (String) -> Bytes?, max_diagnostics? : Int, max_diagnostic_chars? : Int, expected_main_document_path? : String) -> DocxAnnotatedResult raise 
    DocxError

    Builds the bounded annotation-aware projection used by tolerant read-only commands. Broken section header/footer references are already warned and omitted by DocxPackageResult; they do not activate mutation-only identity gates. Edit transactions continue to use read_docx_annotated_archive_limited and fail closed on the same input.

    read_docx_package

    source
    fn read_docx_package(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxPackageResult raise 
    DocxError

    Reads DOCX bytes into the package-level representation: the body document tree (identical to read_docx_with_messages), header/footer parts (each a block-level story, deduplicated by part path in first-reference order), and the sections that reference them.

    read_docx_with_messages

    source
    fn read_docx_with_messages(docx : BytesView, external_file_access? : Bool, read_external_file? : (String) -> Bytes?) -> DocxReadResult raise 
    DocxError

    Reads DOCX bytes into a document tree and diagnostics.

    read_embedded_style_map

    source
    fn read_embedded_style_map(docx : BytesView) -> String? raise 
    DocxError

    Reads the embedded style map from DOCX bytes, if present.

    sweep_archive_para_id_values

    source

    A PACKAGE-GLOBAL paraId value sweep for the mint's used set: every archive part that parses as strict XML contributes its decoded w14:paraId values — quote style, attribute whitespace, and entity encodings all normalized by the parser, any prefix bound to the w14 URI normalized by the namespace map. FAIL-CLOSED where the sweep cannot judge: each part gets a FRESH budget (earlier parts can never starve later ones), a part that exhausts its own budget refuses the caller's operation, and a UTF-16 part — which the strict reader cannot decode and a byte belt cannot match — refuses too. Only parts that are not XML at all are skipped, and the caller keeps a lexical belt for those.

    validate_annotation_identity_state

    source
    fn validate_annotation_identity_state(annotated : DocxAnnotatedResult) -> Unit raise 
    DocxError

    Rejects annotation state that cannot safely serve as the result of a comment mutation. This is the candidate-side counterpart to the planners' source gate and catches duplicate or ambiguous identities introduced by a caller-supplied generic splice plan.

    validate_global_para_id_state_archive_limited

    source
    fn validate_global_para_id_state_archive_limited(annotated : DocxAnnotatedResult, archive : 
    Archive    , xml_budget : 
    XmlReadBudget    ) -> Unit raise 
    DocxError

    Validates every reachable story's w14:paraId values under one cumulative XML budget. This is the candidate-side gate for generic splice plans; the reply/resolution planners use the same traversal before allocating IDs.

    validated_para_id

    source
    fn validated_para_id(raw : String) -> String?

    Validate one as-spelled paraId and return its canonical uppercase form: exactly eight ASCII hex digits (either case), nonzero, and below 0x80000000 (MS-DOCX: greater than zero, high bit clear). Anything else is not an identity.

    Distinct from the comments layer's canonical_para_id, which only case-normalizes conforming spellings for comparison and passes everything else through verbatim — this is the ADDRESSING judgment, and it rejects what it cannot vouch for.

    write_docx

    source

    Serializes body content into a complete docx package. Supported today: paragraphs (style id, alignment, list numbering) containing runs (bold, italic, underline, strikethrough, caps, super/subscript, font, size, highlight), text, tabs, line breaks; and tables with spans. Headings use the Heading1..Heading6 style ids, emitted into the styles part so Word's outline and this repo's own outline command both recognize them; list paragraphs reference the fixed bullet/decimal definitions in the numbering part.

    write_docx_with_annotations

    source

    The full annotation writer: write_docx plus comments (see write_docx_with_comments) plus footnotes and endnotes. Notes are referenced from body runs by note_reference(kind, index) where index is the 0-based position in the matching array here — each supplied note must be referenced EXACTLY ONCE (the canonical shape; unreferenced notes would be invisible orphans, duplicate references are not what Word produces). Note bodies are plain-content paragraph-only, may not carry note references themselves, and land in word/footnotes.xml / word/endnotes.xml as MAIN-part relationships, complete with the separator/continuationSeparator plumbing notes and the in-note footnoteRef/endnoteRef mark run.

    write_docx_with_comments

    source

    write_docx plus comments. The body serializes exactly as write_docx would (an empty comments array is byte-identical); each comment then decorates its anchored paragraphs — range start markers right after pPr in the from paragraph, range end plus the id's reference run appended to the to paragraph — and its definition is written to word/comments.xml. Both anchor endpoints must be top-level paragraphs (tables cannot carry the canonical intra-paragraph shape). REPLIES (comment_reply) must answer an EARLIER spec in this array and emit no markers at all. Comment BODIES reuse the body writers, with a fail-closed guard: content that allocates relationships or media (hyperlinks, images) raises instead of emitting references that would dangle in the comments part. Threading or resolution anywhere adds w14:paraId stamps and word/commentsExtended.xml; otherwise output is byte-identical to the threading-free writer.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io