@formicoidea/labre-core 0.40.0 → 0.42.0

package/dist/_pkgs/affine-block-surface/extensions/export-svg/svg-context.d.ts

@@ -0,0 +1,49 @@
+/**
+ * A 2D context that records an SVG document instead of pixels, shaped so the
+ * existing canvas renderers can paint into it unchanged.
+ */
+export interface SvgContext {
+    /** What the element renderers draw into. */
+    ctx: CanvasRenderingContext2D;
+    /** What `new RoughCanvas(...)` takes: `getContext('2d')` returns {@link ctx}. */
+    canvas: HTMLCanvasElement;
+    /** The finished document, with `viewBox`, `width`/`height` in px and `xmlns`. */
+    serialize(): string;
+}
+/** Marks a {@link RecordingPath2D} and carries what it recorded. */
+declare const RECORDED_D: unique symbol;
+interface RecordedPath {
+    [RECORDED_D]: string;
+}
+/** A `Path2D` that also remembers itself as an SVG `d`, in the caller's space. */
+export type RecordingPath2D = Path2D & RecordedPath & {
+    readonly d: string;
+};
+/**
+ * Runs `render` with `globalThis.Path2D` swapped for the recording subclass, so
+ * the `new Path2D(d)` a renderer builds can be replayed into the SVG document.
+ *
+ * Swapping a global is safe here because the swap and the restore bracket a
+ * SYNCHRONOUS call on a single-threaded runtime: no other code can run — let
+ * alone observe `Path2D` — between the two, and the `finally` restores the
+ * original even when a renderer throws.
+ */
+export declare function runWithRecordingPath2D<T>(render: () => T): T;
+/**
+ * The dash pattern svgcanvas holds, as the `number[]` Canvas2D's `getLineDash`
+ * returns.
+ *
+ * svgcanvas 2.6.0 implements `setLineDash` but not `getLineDash`, and a
+ * renderer that reads the pattern back (to put it back after a dashed stroke)
+ * would throw and abort the whole export. Its `setLineDash` stores the pattern
+ * in the `lineDash` style — a comma-joined string, `null` once cleared, the
+ * default `[]` before any call — and that style is saved and restored with the
+ * rest of the drawing state, so reading it is exact.
+ */
+export declare function readLineDash(lineDash: unknown): number[];
+/**
+ * An SVG-emitting 2D context of `width` × `height` user units, ready to be
+ * handed to {@link CanvasRenderer.renderBoundTo}.
+ */
+export declare function createSvgContext(width: number, height: number): SvgContext;
+export {};

package/dist/_pkgs/affine-block-surface/extensions/export-svg/svg-context.js

@@ -0,0 +1,257 @@
+import { Context } from 'svgcanvas/dist/svgcanvas.esm.js';
+const PATH_OPS = ['fill', 'stroke', 'clip'];
+/** Marks a {@link RecordingPath2D} and carries what it recorded. */
+const RECORDED_D = Symbol('labre.export-svg.recorded-d');
+function isRecordingPath(value) {
+    return (typeof value?.[RECORDED_D] === 'string');
+}
+/**
+ * The SVG `d` of a path argument, or `undefined` when it cannot be read.
+ *
+ * Duck-typed on a string `d` so it covers both paths this module recorded and
+ * the native ones `taggedPath2D` tagged — a renderer is free to memoise those,
+ * and a memo built during an ordinary canvas paint must still be readable here.
+ */
+function readablePathD(value) {
+    const d = value?.d;
+    return typeof d === 'string' ? d : undefined;
+}
+/** A path argument whose geometry is unreadable: a bare native `Path2D`. */
+function isOpaquePath(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        readablePathD(value) === undefined);
+}
+function isEvenOdd(value) {
+    return value === 'evenodd';
+}
+function unsupported(method) {
+    return new Error(`SVG export: Path2D.${method}() is not recorded. Add it to RecordingPath2D ` +
+        `in extensions/export-svg/svg-context.ts, or draw it on the context directly.`);
+}
+let recordingPath2D;
+/**
+ * Built on first use rather than at import time: it extends the platform
+ * `Path2D`, which does not exist under Node, and merely importing this module
+ * must not throw there (same arrangement as `gfx/cynefin-estuarine`'s lazy
+ * curves).
+ *
+ * It EXTENDS `Path2D` on purpose. A renderer is free to memoise the paths it
+ * builds (`gfx/cynefin-estuarine` does), so an instance created while the shim
+ * is installed can outlive the export and be handed to a real canvas context
+ * later — which only works if it is a genuine `Path2D` as well.
+ */
+function getRecordingPath2D() {
+    var _a;
+    if (recordingPath2D)
+        return recordingPath2D;
+    const Base = globalThis.Path2D;
+    if (!Base) {
+        throw new Error('SVG export: Path2D is unavailable in this environment.');
+    }
+    class RecordingPath2DImpl extends Base {
+        static { _a = RECORDED_D; }
+        get d() {
+            return this[RECORDED_D];
+        }
+        constructor(source) {
+            super(source);
+            this[_a] = '';
+            if (typeof source === 'string') {
+                this[RECORDED_D] = source;
+            }
+            else if (isRecordingPath(source)) {
+                this[RECORDED_D] = source[RECORDED_D];
+            }
+            else if (source) {
+                throw unsupported('constructor(Path2D)');
+            }
+        }
+        _push(command) {
+            this[RECORDED_D] += this[RECORDED_D] ? ` ${command}` : command;
+        }
+        addPath(path, transform) {
+            if (transform)
+                throw unsupported('addPath(path, transform)');
+            if (!isRecordingPath(path))
+                throw unsupported('addPath(Path2D)');
+            super.addPath(path);
+            this._push(path[RECORDED_D]);
+        }
+        arc() {
+            throw unsupported('arc');
+        }
+        arcTo() {
+            throw unsupported('arcTo');
+        }
+        bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y) {
+            super.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y);
+            this._push(`C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${x} ${y}`);
+        }
+        closePath() {
+            super.closePath();
+            this._push('Z');
+        }
+        ellipse() {
+            throw unsupported('ellipse');
+        }
+        lineTo(x, y) {
+            super.lineTo(x, y);
+            this._push(`L ${x} ${y}`);
+        }
+        moveTo(x, y) {
+            super.moveTo(x, y);
+            this._push(`M ${x} ${y}`);
+        }
+        quadraticCurveTo(cpx, cpy, x, y) {
+            super.quadraticCurveTo(cpx, cpy, x, y);
+            this._push(`Q ${cpx} ${cpy} ${x} ${y}`);
+        }
+        rect(x, y, w, h) {
+            super.rect(x, y, w, h);
+            this._push(`M ${x} ${y} L ${x + w} ${y} L ${x + w} ${y + h} L ${x} ${y + h} Z`);
+        }
+        roundRect() {
+            throw unsupported('roundRect');
+        }
+    }
+    recordingPath2D =
+        RecordingPath2DImpl;
+    return recordingPath2D;
+}
+/**
+ * Runs `render` with `globalThis.Path2D` swapped for the recording subclass, so
+ * the `new Path2D(d)` a renderer builds can be replayed into the SVG document.
+ *
+ * Swapping a global is safe here because the swap and the restore bracket a
+ * SYNCHRONOUS call on a single-threaded runtime: no other code can run — let
+ * alone observe `Path2D` — between the two, and the `finally` restores the
+ * original even when a renderer throws.
+ */
+export function runWithRecordingPath2D(render) {
+    const original = globalThis.Path2D;
+    globalThis.Path2D = getRecordingPath2D();
+    try {
+        return render();
+    }
+    finally {
+        globalThis.Path2D = original;
+    }
+}
+/**
+ * Teaches `fill`/`stroke`/`clip` the two things svgcanvas drops on the floor:
+ * the `Path2D` argument, and the fill rule.
+ */
+function installPathOps(ctx) {
+    for (const op of PATH_OPS) {
+        const original = ctx[op];
+        ctx[op] = (...args) => {
+            const d = args.map(readablePathD).find(value => value !== undefined);
+            const hasPath = d !== undefined;
+            const evenOdd = args.some(isEvenOdd);
+            if (hasPath) {
+                // svgcanvas ignores Path2D arguments and always paints its "current
+                // default path", so the path's `d` becomes exactly that.
+                ctx.beginPath();
+                ctx.__currentDefaultPath = d;
+            }
+            else if (args.some(isOpaquePath)) {
+                // An untagged native Path2D. Nothing can read its geometry back, so
+                // drop it loudly rather than let svgcanvas paint whatever path happened
+                // to be current. `taggedPath2D` is the fix at the call site.
+                ctx.beginPath();
+                ctx.__currentDefaultPath = '';
+                console.warn('SVG export: an untagged Path2D cannot be read back; that shape is ' +
+                    'missing from the SVG. Build it with `taggedPath2D`.');
+            }
+            // `clip()` moves this node into a <clipPath>, so grab it beforehand.
+            const element = ctx.__currentElement;
+            const lineWidth = ctx.lineWidth;
+            original.call(ctx);
+            if (hasPath) {
+                // svgcanvas BAKES the current matrix into every coordinate it emits;
+                // an injected `d` never went through that, so the matrix rides along
+                // as a `transform` attribute instead…
+                ctx.__applyTransformation(element);
+                // …and the stroke width, which svgcanvas pre-multiplied by the matrix
+                // scale, goes back to its raw value or the transform scales it twice.
+                if (op === 'stroke') {
+                    element.setAttribute('stroke-width', `${lineWidth}`);
+                }
+            }
+            if (evenOdd) {
+                element.setAttribute(op === 'clip' ? 'clip-rule' : 'fill-rule', 'evenodd');
+            }
+        };
+    }
+}
+/**
+ * The dash pattern svgcanvas holds, as the `number[]` Canvas2D's `getLineDash`
+ * returns.
+ *
+ * svgcanvas 2.6.0 implements `setLineDash` but not `getLineDash`, and a
+ * renderer that reads the pattern back (to put it back after a dashed stroke)
+ * would throw and abort the whole export. Its `setLineDash` stores the pattern
+ * in the `lineDash` style — a comma-joined string, `null` once cleared, the
+ * default `[]` before any call — and that style is saved and restored with the
+ * rest of the drawing state, so reading it is exact.
+ */
+export function readLineDash(lineDash) {
+    if (Array.isArray(lineDash))
+        return lineDash.map(Number);
+    if (typeof lineDash !== 'string' || lineDash === '')
+        return [];
+    return lineDash.split(',').map(Number);
+}
+/** Adds `viewBox` / `xmlns` / px units to the root `<svg>` if they are missing. */
+function finishSvg(svg, width, height) {
+    return (svg
+        // Models store fonts under the loader's own face name
+        // (`blocksuite:surface:Inter`); outside the editor only `Inter` exists.
+        .replace(/blocksuite:surface:/g, '')
+        // svgcanvas writes the (unset) text decoration out literally.
+        .replace(/ text-decoration="undefined"/g, '')
+        .replace(/<svg\b[^>]*>/, tag => {
+        let out = tag;
+        if (!/\sviewBox=/.test(out)) {
+            out = out.replace(/^<svg/, `<svg viewBox="0 0 ${width} ${height}"`);
+        }
+        if (!/\sxmlns=/.test(out)) {
+            out = out.replace(/^<svg/, `<svg xmlns="http://www.w3.org/2000/svg"`);
+        }
+        out = /\swidth=/.test(out)
+            ? out.replace(/\swidth="[^"]*"/, ` width="${width}px"`)
+            : out.replace(/^<svg/, `<svg width="${width}px"`);
+        out = /\sheight=/.test(out)
+            ? out.replace(/\sheight="[^"]*"/, ` height="${height}px"`)
+            : out.replace(/^<svg/, `<svg height="${height}px"`);
+        return out;
+    }));
+}
+/**
+ * An SVG-emitting 2D context of `width` × `height` user units, ready to be
+ * handed to {@link CanvasRenderer.renderBoundTo}.
+ */
+export function createSvgContext(width, height) {
+    const context = new Context({ width, height });
+    const ctx = context;
+    // `RoughCanvas` takes the CANVAS and calls `getContext('2d')` on it.
+    // svgcanvas already points `canvas` back at the context, so one method
+    // closes the loop.
+    context.getContext = () => ctx;
+    // Text renderers temporarily attach a detached canvas to <body> to measure
+    // RTL runs. This context is not a DOM node, so claim it is already attached.
+    context.isConnected = true;
+    // …and they set `dir` on the canvas before every text run; a no-op keeps
+    // that call from reaching an object that is not an element.
+    context.setAttribute = () => { };
+    // The one Canvas2D method a renderer calls that svgcanvas lacks — see
+    // `readLineDash`. Without it a single `getLineDash()` aborts the export.
+    context.getLineDash = () => readLineDash(context.lineDash);
+    installPathOps(context);
+    return {
+        ctx,
+        canvas: ctx.canvas,
+        serialize: () => finishSvg(context.getSerializedSvg(true), width, height),
+    };
+}

package/dist/_pkgs/affine-block-surface/extensions/export-svg/tagged-path.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A `Path2D` that carries the `d` it was built from.
+ *
+ * The SVG export replays the element renderers into an SVG-emitting context,
+ * and a native `Path2D` is a black box: nothing can read its geometry back, so
+ * a shape drawn through one would be missing from the export. The tag is what
+ * the export reads — see `svg-context.ts`.
+ *
+ * Use it anywhere a renderer builds a `Path2D` FROM A STRING. A path built by
+ * calling methods (`new Path2D()` then `rect(...)`) needs no tag: the export
+ * records those calls itself.
+ *
+ * It is a plain function, not a constant: `Path2D` does not exist under Node,
+ * so this must only ever run on a paint, never at module load.
+ */
+export declare function taggedPath2D(d: string): Path2D;

package/dist/_pkgs/affine-block-surface/extensions/export-svg/tagged-path.js

@@ -0,0 +1,24 @@
+/**
+ * A `Path2D` that carries the `d` it was built from.
+ *
+ * The SVG export replays the element renderers into an SVG-emitting context,
+ * and a native `Path2D` is a black box: nothing can read its geometry back, so
+ * a shape drawn through one would be missing from the export. The tag is what
+ * the export reads — see `svg-context.ts`.
+ *
+ * Use it anywhere a renderer builds a `Path2D` FROM A STRING. A path built by
+ * calling methods (`new Path2D()` then `rect(...)`) needs no tag: the export
+ * records those calls itself.
+ *
+ * It is a plain function, not a constant: `Path2D` does not exist under Node,
+ * so this must only ever run on a paint, never at module load.
+ */
+export function taggedPath2D(d) {
+    const path = new Path2D(d);
+    // While the export's recording `Path2D` is installed, the instance already
+    // exposes `d` through a getter; writing it again would throw.
+    if (typeof path.d !== 'string') {
+        Object.defineProperty(path, 'd', { value: d, enumerable: true });
+    }
+    return path;
+}

package/dist/_pkgs/affine-block-surface/extensions/export-svg/toolbar.d.ts

@@ -0,0 +1,24 @@
+import { type ToolbarContext } from '../../../affine-shared/services/index.js';
+export declare const exportSvgToolbarConfig: {
+    readonly actions: [import("../../../affine-shared/services/index.js").ToolbarActionGenerator];
+    readonly when: (ctx: ToolbarContext) => boolean;
+};
+/**
+ * "Export SVG" in the "⋮" of EVERY framework board (ADR 0025).
+ *
+ * ## Where it is registered
+ *
+ * `custom:affine:surface:*` — the wildcard slot merged into the toolbar of every
+ * canvas element — with an OWNER suffix. The bare key is already taken by
+ * `validation-toolbar.ts` (and `affine:surface:*` by the root's built-in misc
+ * module), so a second module on either would be a
+ * `DuplicateServiceDefinitionError` at setup rather than a menu entry;
+ * {@link toolbarModuleKey} is what gives a second contributor a distinct DI
+ * variant while `modulesFor` still hands it to the row drawn for that flavour.
+ *
+ * One registration therefore covers all eleven board kinds and every one that
+ * follows, which is the whole claim of the ADR: the export is generic, so it is
+ * registered once, generically, and a new framework inherits it by extending
+ * `FrameworkBackgroundElementModel` and doing nothing else.
+ */
+export declare const exportSvgToolbarExtension: import("../../../store/index.js").ExtensionType;

package/dist/_pkgs/affine-block-surface/extensions/export-svg/toolbar.js

@@ -0,0 +1,66 @@
+import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { commandMoreAction, ToolbarModuleExtension, toolbarModuleKey, } from '../../../affine-shared/services/index.js';
+import { BlockFlavourIdentifier } from '../../../std/index.js';
+import { html } from 'lit';
+/**
+ * A sheet with an arrow leaving it: the board, on its way out of the editor.
+ *
+ * Drawn inline like its neighbours in this package (`reading-toolbar.ts`,
+ * `tags-toolbar.ts`, `validation-toolbar.ts`): the surface block does not
+ * depend on `@blocksuite/icons`, and one glyph is not worth a new dependency.
+ */
+const ExportSvgIcon = html `<svg
+  width="20"
+  height="20"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 3v12" />
+  <path d="M8 11l4 4 4-4" />
+  <path d="M4 17v2a2 2 0 002 2h12a2 2 0 002-2v-2" />
+</svg>`;
+/** The keys the command declares; spelled once, read here and nowhere else. */
+const EXPORT_SVG_COMMAND_ID = 'export.svg';
+const EXPORT_SVG_LABEL_KEY = 'com.labre.command.export.svg';
+const EXPORT_SVG_LABEL_FALLBACK = 'Export SVG';
+export const exportSvgToolbarConfig = {
+    actions: [
+        commandMoreAction(
+        // `z.z-` and not `z.`: a framework's own export (`z.export-owm`,
+        // `z.export-xml`, `z.export-mermaid`) is the format that says what the
+        // board MEANS, and it reads first. The picture reads last, under
+        // everything, which is also where a reader looks for it.
+        'z.z-export-svg', EXPORT_SVG_COMMAND_ID, EXPORT_SVG_LABEL_KEY, EXPORT_SVG_LABEL_FALLBACK, ExportSvgIcon),
+    ],
+    // The module says "a board is selected"; the command's own `when` says the
+    // same thing from the registry side, and the two are deliberately both there
+    // — the entry is drawn from the module and the behaviour is guarded by the
+    // command, whichever surface reaches it.
+    when: (ctx) => ctx.getSurfaceModelsByType(FrameworkBackgroundElementModel).length > 0,
+};
+/**
+ * "Export SVG" in the "⋮" of EVERY framework board (ADR 0025).
+ *
+ * ## Where it is registered
+ *
+ * `custom:affine:surface:*` — the wildcard slot merged into the toolbar of every
+ * canvas element — with an OWNER suffix. The bare key is already taken by
+ * `validation-toolbar.ts` (and `affine:surface:*` by the root's built-in misc
+ * module), so a second module on either would be a
+ * `DuplicateServiceDefinitionError` at setup rather than a menu entry;
+ * {@link toolbarModuleKey} is what gives a second contributor a distinct DI
+ * variant while `modulesFor` still hands it to the row drawn for that flavour.
+ *
+ * One registration therefore covers all eleven board kinds and every one that
+ * follows, which is the whole claim of the ADR: the export is generic, so it is
+ * registered once, generically, and a new framework inherits it by extending
+ * `FrameworkBackgroundElementModel` and doing nothing else.
+ */
+export const exportSvgToolbarExtension = ToolbarModuleExtension({
+    id: BlockFlavourIdentifier(toolbarModuleKey('custom:affine:surface:*', 'export-svg')),
+    config: exportSvgToolbarConfig,
+});

package/dist/_pkgs/affine-block-surface/extensions/index.d.ts

@@ -6,9 +6,12 @@ export * from './edit-props-middleware-builder.js';
 export * from './editor-anchored-panel.js';
 export * from './element-renderer.js';
 export * from './export-manager/index.js';
+export * from './export-svg/index.js';
 export * from './interchange.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';
+export * from './legend.js';
+export * from './legend-toolbar.js';
 export * from './map-quality.js';
 export * from './map-quality-widget.js';
 export * from './morph-toolbar.js';
@@ -16,9 +19,11 @@ export * from './query.js';
 export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
+export * from './record-action.js';
 export * from './spotlight.js';
 export * from './surface-middleware.js';
 export * from './svg-sketch.js';
+export * from './svg-sketch-translations.js';
 export * from './tags-toolbar.js';
 export * from './validation.js';
 export * from './validation-toolbar.js';

package/dist/_pkgs/affine-block-surface/extensions/index.js

@@ -6,9 +6,12 @@ export * from './edit-props-middleware-builder.js';
 export * from './editor-anchored-panel.js';
 export * from './element-renderer.js';
 export * from './export-manager/index.js';
+export * from './export-svg/index.js';
 export * from './interchange.js';
 export * from './interchange-import.js';
 export * from './legacy-slot-extension.js';
+export * from './legend.js';
+export * from './legend-toolbar.js';
 export * from './map-quality.js';
 export * from './map-quality-widget.js';
 export * from './morph-toolbar.js';
@@ -16,9 +19,11 @@ export * from './query.js';
 export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
+export * from './record-action.js';
 export * from './spotlight.js';
 export * from './surface-middleware.js';
 export * from './svg-sketch.js';
+export * from './svg-sketch-translations.js';
 export * from './tags-toolbar.js';
 export * from './validation.js';
 export * from './validation-toolbar.js';

package/dist/_pkgs/affine-block-surface/extensions/interchange-import.d.ts

@@ -1,6 +1,6 @@
 import type { ServiceProvider } from '../../global/di/index.js';
 import type { BlockStdScope } from '../../std/index.js';
-import { type InterchangeFormat, type InterchangeImportCapability, type InterchangeReport, type SerializedElementProps } from './interchange.js';
+import { type InterchangeFormat, type InterchangeImportCapability, type InterchangeNote, type InterchangeReport, type SerializedElementProps } from './interchange.js';
 /**
  * **The public import API** — what an editor, a host application or a plugin
  * calls to turn a foreign file into a board (`docs/adr/0012`).
@@ -50,11 +50,49 @@ import { type InterchangeFormat, type InterchangeImportCapability, type Intercha
  * whole blob and `addElement` writes it with everything else, which is the
  * whole-record LWW the field's own contract asks for (D2).
  *
+ * ## The reader's OWN names, and why there is a second map
+ *
+ * A source id is the file's, and there are two things a reader has to point at
+ * that the file never named: an element it MINTED (a framework artefact is
+ * routinely several elements — a shape, its compartments, and the group that
+ * makes them one thing), and the group membership between them. So a reader may
+ * also hand each element a provisional `id` of its own. `surface.addElement`
+ * overwrites it with a nanoid and is documented to, which is precisely what
+ * makes it safe to use as a local name: it reaches no document, and it is read
+ * here and nowhere else.
+ *
+ * A GROUP's `children` are therefore rewritten BEFORE the group is created, out
+ * of the map built so far — which costs nothing and asks the reader for the one
+ * thing it can always give: emit an element before the group that holds it. A
+ * connector is the opposite case (a flow may be written before either of its
+ * ends) and keeps its second pass.
+ *
+ * Source ids win over provisional ones wherever both could answer, so a reader
+ * that mints no local name behaves exactly as it did before this was here.
+ *
+ * ## Beside what is already drawn
+ *
+ * A reader writes the coordinates its FILE gave it, so importing the same file
+ * twice put the second board exactly on top of the first. The offset is applied
+ * here, once, for every framework, because the only thing that knows what the
+ * canvas already holds is the function doing the writing — see
+ * {@link importOffset}, and note that an empty surface is left alone.
+ *
+ * ## A read-only document is answered, not thrown at
+ *
+ * This is a public API — a host (labre-mcp) writes through it with no command
+ * in front of it — so the guard belongs here too and not only at the callers:
+ * a readonly document answers the empty array, which is the same "nothing was
+ * minted" every other refusal of this function returns, rather than an
+ * exception a caller would have to know to catch.
+ *
  * @param formatId the format whose payload key carries the source ids — the
  *   `id` of the capability's {@link InterchangeFormat}, and the ONLY thing this
  *   function ever knew about BPMN.
  */
-export declare function materializeInterchangeImport(std: BlockStdScope, formatId: string, elements: readonly SerializedElementProps[]): string[];
+export declare function materializeInterchangeImport(std: BlockStdScope, formatId: string, elements: readonly SerializedElementProps[], options?: {
+    onNote?: (note: InterchangeNote) => void;
+}): string[];
 /**
  * Say what the import did — the summary, and the remarks.
  *
@@ -109,7 +147,31 @@ export declare function reportInterchangeImport(std: BlockStdScope, format: Inte
  * deliberately so: a dialog a document cannot honour should never open in the
  * first place.
  */
-export declare function runInterchangeImportFile(std: BlockStdScope, capability: InterchangeImportCapability): Promise<void>;
+export declare function runInterchangeImportFile(std: BlockStdScope, capability: InterchangeImportCapability, options?: InterchangeImportOptions): Promise<void>;
+/** What a caller can put between the file's bytes and the declared reader. */
+export interface InterchangeImportOptions {
+    /**
+     * Turn the file's text into the text the reader takes — the seam for a
+     * format whose container is not the document.
+     *
+     * A reader is a PURE, synchronous function of text (`docs/adr/0012` P3), and
+     * that is not negotiable: it is what lets labre-mcp call the same function
+     * the command calls. Some containers put an asynchronous platform API between
+     * the bytes and the document all the same — a `.drawio` file holds its
+     * `<mxGraphModel>` as base64 of a raw deflate, and inflating it needs
+     * `DecompressionStream` (`gfx/uml/src/drawio-decode.ts`, `docs/adr/0019`);
+     * a zipped container would be the next one.
+     *
+     * So the unwrapping happens HERE, where a caller already has an editor and an
+     * `await`, and the reader keeps its purity. Anything this throws is shown as
+     * the import's failure notification, exactly as a reader's own refusal is —
+     * so the sentence it throws should name what is wrong with the file.
+     *
+     * Absent for every format whose file IS its document, which is all of them
+     * bar one.
+     */
+    decode?: (text: string, file: File) => string | Promise<string>;
+}
 /**
  * The import itself, over a file the caller ALREADY HAS: run the declared
  * capability (`docs/adr/0012`), write what it returned, bring it into view, and
@@ -147,7 +209,7 @@ export declare function runInterchangeImportFile(std: BlockStdScope, capability:
  * its refusals it was, so it is shown as it is rather than replaced with a
  * wording of our own that knows less.
  */
-export declare function importInterchangeFile(std: BlockStdScope, capability: InterchangeImportCapability, file: File): Promise<void>;
+export declare function importInterchangeFile(std: BlockStdScope, capability: InterchangeImportCapability, file: File, options?: InterchangeImportOptions): Promise<void>;
 /**
  * Every registered importer, indexed by the extensions it declares.
  *