@formicoidea/labre-core 0.50.0 → 0.51.0

package/dist/_pkgs/affine-block-surface/extensions/drawio-export/writer.d.ts

@@ -0,0 +1,50 @@
+import type { GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
+import type { InterchangeExportContext, InterchangeExportResult } from '../interchange.js';
+/**
+ * The canvas as a draw.io drawing — the GENERIC writer of `canvas:drawio:export`
+ * (`docs/adr/0019`, amendment of 2026-10-14; `docs/adr/0012` P2's visual tier).
+ *
+ * ## What it writes, and what it promises
+ *
+ * One uncompressed `<mxfile>` holding one page: a `<mxGraphModel>` whose cells
+ * are what the canvas PAINTS — a shape as a draw.io shape, a connector as an
+ * edge, a text as a text, a group as a draw.io group, and the canvas blocks a
+ * reader needs (a note, a frame, an edgeless text, an image as a placeholder
+ * naming its blob). A framework artefact is written by its generic rendering —
+ * the shape it extends and the words grouped with it — and carries its `role`
+ * as a `labre-role` attribute, so a reader that knows the vocabulary can
+ * recognise it (`importDrawio`, UML, does for the class and use case
+ * families). That is a courtesy to a reader, not a model: this is the VISUAL
+ * tier, and what a framework means is written by its own semantic exporter
+ * (PlantUML, XMI, `.bpmn`, OWM), never here.
+ *
+ * ## Pure, and deterministic
+ *
+ * No `std`, no DOM, no clock: element records in, text out (`docs/adr/0012`
+ * P3), so labre-mcp can call it and a unit suite can prove it with plain
+ * objects. The same canvas writes the same bytes — cells in z-order (frames
+ * first, then the fractional `index`, the id breaking ties), numbers rounded to
+ * two decimals, no timestamp, no generated id: a cell's id IS the element's id
+ * (`docs/adr/0012` D3), so a re-import can name what it read.
+ *
+ * ## What is never written
+ *
+ * No link, no URL, no script: a label is the element's plain text,
+ * HTML-escaped (draw.io reads `html=1` labels as markup) and then XML-escaped,
+ * so a `<script>` somebody typed arrives as the seven characters they typed.
+ * An image is a placeholder carrying its blob id, never the bytes nor an
+ * address. Nothing here reads `pivotDocId`, tags or `interchange` payloads.
+ *
+ * ## Where it is known to lose
+ *
+ * A freehand stroke, a highlighter and a polygon's outline have no draw.io
+ * shape: the first two are left out, the third is drawn as its bounding box,
+ * and each costs one warning per kind. A curved connector is drawn
+ * `curved=1` through no waypoint (draw.io routes its own curve). A block other
+ * than the four above (an embed, an attachment, a LaTeX block) is left out with
+ * a warning naming its flavour. Colours are printed in their LIGHT variant.
+ */
+export declare const DRAWIO_EXTENSION = ".drawio";
+export declare const DRAWIO_MIME = "application/xml";
+/** The elements (and `context.blocks`) handed over, as one draw.io page. */
+export declare function exportCanvasDrawio(elements: readonly GfxPrimitiveElementModel[], context?: InterchangeExportContext): InterchangeExportResult;