vibe.workbench.docx_service

DOCX Service for Workbench.

Handles the core technical challenge of creating robust, unbreakable links between the visual HTML editor and the underlying DOCX XML structure.

Key features: - Stable data-vibe-id generation using SHA-256 hashes - DOCX to HTML conversion with preserved IDs - Jinja tag parsing and mapping to element IDs - XML modification for publishing templates

JinjaMapping

Represents a Jinja tag found in the document mapped to a stable element ID.

DOCXConversionResult

Result of DOCX to HTML conversion with stable IDs.

DOCXService

Production-grade DOCX processing service for the workbench.

Provides robust, unbreakable linking between HTML editor and DOCX XML through stable ID generation and careful XML manipulation.

__init__ 

__init__() -> None

Initialize the DOCX service.

convert_docx_to_html_with_ids 

convert_docx_to_html_with_ids(docx_path: Path) -> DOCXConversionResult

Convert DOCX to HTML with stable data-vibe-id attributes.

Parameters:
  • docx_path (Path) –

    Path to the DOCX file
Returns:
Raises:
  • ValueError –

    If DOCX file is malformed

  • FileNotFoundError –

    If DOCX file doesn't exist

convert_docx_to_html 

convert_docx_to_html(docx_bytes: bytes) -> str

Convert DOCX bytes to HTML with stable data-vibe-id attributes.

Parameters:
  • docx_bytes (bytes) –

    DOCX file content as bytes
Returns:
  • str –

    HTML string with data-vibe-id attributes
Raises:
  • ValueError –

    If DOCX file is malformed

parse_jinja_from_docx 

parse_jinja_from_docx(docx_bytes: bytes) -> dict[str, Any]

Parse Jinja tags from DOCX and create markup overlay structure.

Parameters:
  • docx_bytes (bytes) –

    DOCX file content as bytes
Returns:
  • dict[str, Any] –

    Dictionary representing markup overlay structure

parse_jinja_from_docx_path 

parse_jinja_from_docx_path(docx_path: Path) -> list[JinjaMapping]

Parse Jinja tags from DOCX path and map them to stable element IDs.

Parameters:
  • docx_path (Path) –

    Path to the DOCX file
Returns:

publish_draft 

publish_draft(docx_bytes: bytes, markup_overlay: dict[str, Any]) -> bytes

Publish a draft by applying markup overlay to the DOCX bytes.

Parameters:
  • docx_bytes (bytes) –

    Original DOCX file content as bytes

  • markup_overlay (dict[str, Any]) –

    Markup overlay data
Returns:
  • bytes –

    Modified DOCX file as bytes
Raises:
  • ValueError –

    If markup overlay is invalid or DOCX is malformed

publish 

publish(draft_path: Path, markup_overlay: dict[str, Any], output_path: Path) -> None

Publish a draft by applying markup overlay to the original DOCX.

Uses stable data-vibe-id locators from markup_overlay.json to find exact XML nodes and modify them via XPath.

Parameters:
  • draft_path (Path) –

    Path to the draft directory

  • markup_overlay (dict[str, Any]) –

    Markup overlay data from JSON

  • output_path (Path) –

    Path where to save the published template.docx
Raises:
  • ValueError –

    If markup overlay is invalid

  • FileNotFoundError –

    If source files are missing