Visio Image Rebuild

Rebuild diagrams from source pixels while preserving separately editable geometry, connectors, and visible text. Never satisfy editability by hiding the source screenshot behind overlays. Report measured similarity and explicit approximations instead of claiming "1:1" from file validity alone.

Public release scope

This free public package supports the strict-native workflow. Native VSDX export requires Windows, an installed and licensed Microsoft Visio desktop application, Python, and pywin32; install the Python dependencies listed in requirements.txt in the chosen environment. This package does not supply Microsoft Visio, MathType, their licenses, a hosted rendering service, or a payment service. Without the required application environment, offer only the validated scene and COM-free PNG/SVG previews, clearly labelled as previews rather than a completed VSDX.

The MathType scene model and Python validation/inspection helpers are retained for import compatibility and COM-free authoring/preview. Native MathType/OLE export is not part of this public release: the original integration requires a separately reviewed, frozen local runtime that is intentionally not distributed. Keep MathType requests at the scene/preview boundary; do not automatically obtain binaries, rebuild the bridge, replace frozen hashes, bypass attestation, or advertise the missing integration as available.

Read references/public-release-scope.md for package contents and the intentionally absent native dependencies. The retained MathType details below and in the other references document conditional integrity/safety requirements, not a promise that this public package can execute that private integration. All application-ownership and fail-closed safety gates remain unchanged.

Modes and current implementation boundary

• strict-native is the default and supports native Visio geometry and live text. It forbids math_type, OLE, embeddings, raster payloads, macros, and arbitrary foreign data.
• visio-mathtype is an explicit opt-in for MathType scene authoring and COM-free preview in this public release. These steps support latex, tex_input, and mathml; preview fallback text is not an editable Equation.DSMT4 OLE equation. The non-distributed native integration accepts only strict ASCII latex or tex_input with no embedded NUL when its separately reviewed runtime is available.

That non-distributed MathType native path uses the frozen vendor-contract-backed MTAPI bridge and the exact reviewed Windows x64 CPython 3.14.3 runtime (cp314-win_amd64). The controller verifies the interpreter ABI, native bridge, source, vendor contract, build report, Python COM runtime, vendor libraries, static capabilities, and scene-bound formula manifest before a worker may start. A missing, changed, or unsupported runtime, source format, or formula manifest fails closed with exit 25, MATHTYPE_INJECTION_UNSUPPORTED, and a blocked preview state before controller COM import, vendor initialization, or worker launch. Never change frozen hashes merely to pass a gate.

Successful preflight permits an isolated export attempt; it is not proof of a finished artifact. Every formula must pass exact source readback after save/reopen, package identity and relationship checks, and a disposable change/save/reopen/restore test. The default proof also opens the editor. When the user requests backend-only work or prohibits desktop UI, explicitly select --mathtype-background-edit-proof: it uses real MTAPI changes on each saved OLE without invoking the editor and records that limitation. Never substitute preview fallback text, a blank OLE, live text, or an image for a requested MathType equation.

Read references/workflow.md for the mode-specific production contract and references/scene-schema.md for exact scene fields.

Application safety gates

Always run the scene-bound, COM-free gate immediately before any export attempt:

python scripts/export_visio.py <scene.json> --preflight-only

• Any existing VISIO.EXE blocks both modes, records PREVIEW_READY_EXPORT_BLOCKED, and exits 20.
• In visio-mathtype only, any existing MathType.exe also blocks export. When Visio is clear, this records the same blocked phase and exits 24. strict-native does not inspect or depend on MathType.
• Never attach to, reuse, activate, focus, hide, close, or terminate an existing Visio or MathType process. Never import Visio COM, start a worker, or activate an OLE server on a blocked path.
• READY is available only after all mode-specific requirements pass. MathType process clearance alone is PROCESS_GATES_CLEAR; under the render lock the controller must repeat both gates and attest the frozen runtime plus the exact formula manifest before reporting READY. Static attestation calls only bridge capabilities(), never MTAPI initialization or COM/OLE activation.
• Visio export may use only DispatchEx plus durable proof that the COM application PID is the sole newly observed VISIO.EXE process. Close only the owned document and proven-owned process.

Read references/visio-safety.md before changing, running, or diagnosing export automation.

MathType scene contract

Every math_type object must:

• appear only in metadata.fidelity_mode: "visio-mathtype";
• have the shared id, bbox, semantic_id, region_id, z, and explicit style fields;
• contain exactly one non-empty source field: latex, tex_input, or mathml;
• contain exactly one non-empty fallback field: fallback_text or the legacy display_text;
• contain canonical identity fields whose values match character-for-character: progid: "Equation.DSMT4" and clsid: "{0002CE03-0000-0000-C000-000000000046}"; aliases, alternate case, and omitted braces are invalid;
• have exactly one text_inventory entry whose object_id points to it, whose literal equals the selected fallback string character-for-character, and whose bbox equals the object bbox.

Preserve the selected source string exactly as authored. The fallback exists only for COM-free layout and visual comparison; it is neither an editable MathType equation nor evidence of OLE creation. For redacted or occluded formulas, draw the occlusion as a top-z native polygon and do not invent hidden source text.

Orthogonal elbow-arrow contract

Every arrow-bearing orthogonal elbow connector must declare elbow_render_mode: "independent_segments". An arrow-bearing route has a non-none start_arrow or end_arrow; this rule intentionally does not auto-classify no-arrow brackets, sampled curves, waveforms, or freeform polylines. This is a hard editability requirement, not a rendering preference. Given N ordered authored points P0 ... P{N-1}, export exactly N - 1 top-level, ungrouped, independently selectable one-dimensional Visio shapes, with segment i created by Page.DrawLine(Pi, P{i+1}) for 0 <= i < N - 1.

• Never export an orthogonal elbow arrow as one DrawPolyline shape, a dynamic connector, a group, or grouped child lines.
• The first segment alone inherits the connector's start_arrow; every later segment has no begin arrow. The last segment alone inherits end_arrow; every earlier segment has no end arrow.
• For a semantically glued elbow, only the first segment's BeginX/BeginY may glue to the source root and only the last segment's EndX/EndY may glue to the target root. Adjacent segment endpoints meet at the exact authored joint coordinates and have no Connect records between them. An explicit_points_only elbow has no glue at any endpoint.
• Each physical segment must retain stable identity and ordered membership in its one logical connector so package inspection can reject missing, extra, duplicated, grouped, or reordered legs.

The final package inspector and a disposable Visio edit test must prove this physical structure. The edit test must select and alter one elbow leg without selecting or changing the other legs, then confirm that save/reopen preserves the independent top-level shapes. A tool version that cannot validate and export this contract must fail closed rather than silently fall back to a single polyline.

Workflow

1. Freeze the source and mode in a new job:

powershell python scripts/prepare_reference.py --input <source-image> --job-dir <job-dir> --mode strict-native

or, only for scene/preview authoring after explicit MathType opt-in in this public release:

powershell python scripts/prepare_reference.py --input <source-image> --job-dir <job-dir> --mode visio-mathtype

A mode change requires a new job directory.

2. Inspect the canonical source and author source_visual_inventory, text_inventory, connector_plan, region_plan, and source-pixel objects. Bind every visible text and math_type object exactly once in text_inventory; bind every connector plan exactly once. Mark every orthogonal elbow connector with elbow_render_mode: "independent_segments" and preserve every ordered bend point needed to derive its independently selectable legs.

3. Validate and create COM-free previews:

powershell python scripts/validate_scene.py <scene.json> --strict --report <validation.json> python scripts/render_preview.py <scene.json> --output <preview.png> --svg <preview.svg> python scripts/qa_compare.py --original <staged-source> --replica <preview.png> --scene <scene.json> --output <qa-preview.json>

4. Run the safety preflight. A blocked result is a valid preview stopping state, not permission to control either application.

5. In this public release, export strict-native only after preflight exits 0 with READY, then inspect the VSDX and complete final visual and editability review. MathType work stops at the validated scene and COM-free previews because the native integration is not distributed. If an explicit diagnostic preflight exits 25 with MATHTYPE_INJECTION_UNSUPPORTED, preserve the blocked result; that job must not advance to VISIO_EXPORTED, QA_REVIEWED, or COMPLETE. The retained MathType worker contract requires repeat attestation, process gates, a proven-owned Visio instance, and every formula's disposable edit proof, but is not an available export promise for this package.

Read references/qa-and-review.md before accepting any final artifact.

Completion requirements

A strict-native job is complete only when the canonical source remains unchanged, strict validation and all inventory bindings pass, the package contains only permitted native Visio content, connector glue and Shape Data match the scene, every orthogonal elbow is the required ordered set of independent top-level 1-D line segments, the disposable segment-edit test passes, Visio-rendered PNG/SVG come from the reopened owned VSDX, every review region is accepted, and the scene/artifact ledger is sealed.

The following visio-mathtype VSDX completion contract applies only to the non-distributed native integration; this public package does not claim that capability. Such a job may satisfy the completion gate only when its actual artifacts prove all of the following fail-closed:

• each scene formula maps one-to-one to a source-bearing Equation.DSMT4 OLE with exact canonical identity;
• its CompObj/MTEF payload and any Visio-generated EMF presentation are relationship-bound to that formula and no other OLE, package, media, macro, ActiveX, or external payload exists;
• save/reopen preserves the exact source/fallback bindings; source readback equals authored TeX, allowing only one vendor-added surrounding $ pair;
• every formula passes a disposable changed-source/save/reopen/restore test; by default this invokes Visio's documented visCmdEditOpenObject command, while the explicit request-bound background option uses MTAPI without editor invocation. Both require changed and restored sources observed after separate save/reopen cycles and an unchanged deliverable VSDX hash. Never claim a performed double-click/editor test for the background method;
• package inspection, final Visio render QA, review acceptance, and completion sealing all pass.

Until that job-specific evidence exists, deliver and label only the source-bound scene, validation report, and COM-free preview. A successful integration pilot or static attestation does not complete another job. Never present fallback rendering as the requested MathType-editable result.

References

• references/public-release-scope.md: public package prerequisites, exclusions, and unavailable native dependencies
• references/workflow.md: production phases and attested MathType export gate
• references/scene-schema.md: exact scene and inventory contract
• references/scene.schema.json: machine-readable schema
• references/qa-and-review.md: preview, package, editability, and visual acceptance
• references/visio-safety.md: Visio/MathType process gates and ownership
• references/method-transfer.md: transferred reconstruction methods and excluded behavior