beffroi-tools/docs/interfaces/midra-extra-parameters.md

8.0 KiB

Extra Midra parameters in geometry exports

This optional extension is selected by Export layers → Include extra Midra parameters (experimental). It defaults off. Plain exports retain their existing representation. Native Save project already saves the full project and needs no additional switch.

Use Project → Restore parameters from export… to recover the original snapshot into a new, unsaved project. The existing replacement review applies. The source artwork never becomes the project-save/autosave path. Geometry import and clipboard paste continue to import the artwork's current geometry; they do not silently restore old positions, links or crop settings from metadata. This matters when an external editor moves/resizes a shape without updating the embedded snapshot.

Format audit and implemented carriers

Format Carrier / result Compatibility limits
SVG <metadata><parameters xmlns="urn:beffroi:midra:parameters:1">BASE64</parameters></metadata> inside the SVG root Non-rendered foreign-namespace metadata. SVG geometry exchange remains v2. Tested with librsvg rendering. Optimizers may remove metadata.
draw.io Global root-cell custom property: <object id="0" beffroi_midra_parameters="BASE64"><mxCell/></object> Graph model/geometry version stays 1. Installed draw.io Desktop opened and exported this to SVG; parameters also recovered from the SVG's embedded diagram. Compressed single-page draw.io models are supported through the existing bounded decoder.
Geometry JSON Version 2, required root string beffroi_midra_parameters All v1 geometry fields unchanged. Versions 1 and 2 import; v1 exporters remain byte-compatible when the option is off. Older strict readers reject v2 rather than misread it.
Geometry CSV Version 2 in every row; added beffroi_midra_parameters column The first data row holds BASE64; remaining rows contain empty cells. Header/row widths remain equal and ordinary CSV quoting is used. No nonstandard comment lines. Versions 1 and 2 import; older schema-aware readers reject v2.
ASCII DXF Group 999 comments after the existing geometry marker, each beffroi-midra-parameters:CHUNK Ordered base64 chunks of at most 200 characters (comment lines under 255). Craft still reads the same rectangles. Comments may be stripped on CAD resave; binary DXF does not use group 999.
HTML <meta name="beffroi_midra_parameters" content="BASE64"/> in <head> Inert document metadata, no scripts or hidden visible objects. HTML geometry version stays 1.
PPTX docProps/custom.xml, string property beffroi_midra_parameters Standard custom-properties content type and package-root relationship; vt:lpwstr, pid 2, fmtid {D5CDD505-2E9C-101B-9397-08002B2CF9AE}. Existing ZIP parts are preserved; native DeckCraft import checks unchanged geometry. Microsoft PowerPoint resave not tested here.
DWG Not enabled DXF comments do not provide a reliable binary-DWG carrier. XRECORD/XData are potential future paths, but the current Craft conversion bridge has no verified application-payload round trip. No bytes are appended to the binary file.
FigCraft FIGCRAFT Not enabled Native geometry and image exchange only; no Midra snapshot field is emitted or restored.
Figma FIG Not enabled Figma has plugin data, but the installed FigCraft 0.5.1 native exporter explicitly warns plugin data was left out. Its model field is not evidence of native preservation.
Illustrator AI Not enabled PDF-compatible AI can have document metadata, but the current VectorCraft SVG↔AI conversion path has no verified application-payload preservation. No unverified PDF/AI trailer changes are made.
Midra project JSON Already complete Project v13 remains the authoritative full-fidelity save. This task does not change its schema.

Unsupported codecs disable the option with an explanation. Programmatic attempts to request the extension on those codecs fail explicitly, never silently discard it. Vendor availability and the no_proprietary build flag still apply.

Payload contract (extension version 1)

BASE64 is standard padded RFC 4648 base64 of UTF-8, pretty-printed project JSON, currently version 13. It is inert data, not an executable instruction, URL or file path. Project format/version and validation remain authoritative. Future incompatible carrier/payload meanings require a new extension version and explicit migration or rejection.

The snapshot includes only exported layer IDs, in document stack order, with full-precision bounds, names, folders, visibility, locks, pivots, Midra links, source/input crop and advanced crop. Only referenced input slots are included; source IDs are remapped consecutively, preserving shared source relationships. Selection, explicit folders and collapsed folders are filtered to retained layers; unrelated empty folders are omitted. Output resolution, positioning, camera, guide and workspace settings remain available. Pixel-rounded artwork and full-precision stored coordinates are intentionally distinct.

All reference-image objects and preview assignments/images/device-address bindings are omitted. Artwork background/placeholder options operate independently; they do not embed capture settings. Application preferences, connection history, active connections, pending device edits/jobs and undo history are never included.

The decoded metadata JSON is limited to 1 MiB, and the complete exchange file still must fit within 16 MiB after embedding. PPTX custom-properties XML reads are bounded to 2 MiB. No archive members are extracted onto the filesystem. Invalid base64 or project data rejects explicit snapshot restoration. For geometry JSON and CSV, the known v2 extension is removed before strict v1 geometry validation; invalid optional payload contents do not prevent importing otherwise valid artwork. Unknown versions and unknown geometry fields remain errors. More than one nonempty CSV snapshot is rejected on restoration.

The JSON v2 example is a tested example; its decoded snapshot is also validated as a project. Plain v1 fixtures remain unchanged. Other carriers use the same payload bytes and are round-trip tested with background on/off and optional placeholders. The regression suite also checks that edited artwork is imported as edited, unsupported codecs refuse the option, and recovered exports are never reused as project-save paths.

Standards and codec evidence

  • W3C SVG extensibility explicitly allows application metadata for round trips; SVG 2 structure describes metadata containers.
  • draw.io global custom properties documents root-cell custom data.
  • Autodesk DXF group codes documents group 999 comments. Binary DXF does not use that comment group.
  • WHATWG document metadata describes name/content metadata. RFC 4180 describes CSV fields and quoting; this extension adds a regular column.
  • Microsoft custom properties describes the shared Open XML custom-property representation; its package relationship applies to presentations too.
  • Figma plugin data exists in the platform. The local figcraft-format 0.5.1/src/fig/export.rs exporter nevertheless rejects preservation in plugin_data; support stays off.
  • Craft DWG source inspected at revision 79e97b6febcb62de406e5bcf5a724bd3f7333065; current native adapter conversion boundaries are in crates/canvas-pilot/src/vendor_formats.rs.