@formicoidea/labre-core 0.41.0 → 0.42.0

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

@@ -0,0 +1,89 @@
+import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { downloadBlob, safeFilename } from '../../../affine-shared/utils/index.js';
+import { GfxControllerIdentifier } from '../../../std/gfx/index.js';
+import { renderBoardSvg } from './render.js';
+/** What the file is, told to the browser. */
+const SVG_MIME = 'image/svg+xml';
+/** The name a board with no document title falls back to. */
+const SVG_FILENAME_FALLBACK = 'board';
+/**
+ * The framework boards in the current canvas selection.
+ *
+ * `FrameworkBackgroundElementModel` is the whole test, and that is the point of
+ * this command: eleven board kinds today — a Wardley map, a BPMN pool, a C4
+ * board and its boundaries, the three DDD boards, Cynefin, Estuarine, the two
+ * EDGY ones — and whatever a framework adds next, because a board IS the class
+ * and nothing about SVG is per framework (ADR 0025).
+ */
+export function selectedBoards(std) {
+    return std
+        .get(GfxControllerIdentifier)
+        .selection.selectedElements.filter((element) => element instanceof FrameworkBackgroundElementModel);
+}
+/**
+ * Render the selected board and hand it to the browser.
+ *
+ * ponytail: ONE board per click, the first of the selection. Browsers throttle
+ * (and Safari silently drops) programmatic downloads fired in a burst, so a
+ * selection of three boards would yield one file, two files or three depending
+ * on the browser — a result nobody can read off the gesture. One board, one
+ * file, every time.
+ */
+export function exportBoardSvg(std) {
+    const [board] = selectedBoards(std);
+    if (!board)
+        return;
+    const { svg } = renderBoardSvg(std, board);
+    const title = std.store.workspace.meta.getDocMeta(std.store.id)?.title;
+    downloadBlob(
+    // The charset is the browser's business, not the format's: `image/svg+xml`
+    // is what the file IS, and this is how a blob is told to carry it.
+    new Blob([svg], { type: `${SVG_MIME};charset=utf-8` }), `${safeFilename(title, SVG_FILENAME_FALLBACK)}.svg`);
+}
+/**
+ * "Export SVG", in the command registry (ADR 0025).
+ *
+ * `owner: 'core'` and not a framework's, for the reason `map.audit` and
+ * `validation.mapQuality` are core: the command belongs to no framework —
+ * it renders whatever board is selected with the renderer that already paints
+ * it — and a framework owner would have forced the id prefix `wardley.` and
+ * then a second, identical command for every framework that follows. `'core'`
+ * owners are exempt from the id-prefix rule (ADR 0008).
+ *
+ * It READS, so there is no read-only guard: taking a picture of a board you
+ * cannot edit is precisely what a reader does.
+ *
+ * No `telemetry` field: `CommandTelemetry.framework` is typed on `FrameworkId`,
+ * and this command cannot name one — the surface package knows a board by its
+ * MODEL CLASS, and nothing in it maps `bpmnPool` back to `bpmn` without
+ * importing the framework packages the layering forbids. Usage is still
+ * measured, because `runCommand` records it outside the telemetry condition.
+ */
+const exportSvg = {
+    id: 'export.svg',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.export.svg',
+    labelFallback: 'Export SVG',
+    descriptionKey: 'com.labre.command.export.svg.description',
+    descriptionFallback: 'Download the selected board and everything drawn on it as an SVG file.',
+    // The category the framework exports already file under: this is the same
+    // shelf as `wardley.exportOwm`, `bpmn.exportXml` and `c4.exportMermaid`, and
+    // a host catalogue groups them together.
+    category: 'interchange',
+    // Deliberately NOT `'senior-menu'`: those slots are for artefacts you DRAW,
+    // and "Export SVG" answers no question asked of a row of shapes — the same
+    // arbitration `bpmn.exportXml` is filed under (ADR 0014, R4).
+    surfaces: ['catalogue', 'contextual-toolbar', 'palette', 'agent'],
+    scope: 'edgeless',
+    // Keyless by intent. Still bindable from Settings › Shortcuts, which is what
+    // `toShortcutDescriptor` being total buys.
+    defaultKeys: { mac: [], other: [] },
+    // The serializable precondition a host catalogue can show; `when` narrows it
+    // to "…and that selection contains a board", which no member of the closed
+    // union can express.
+    availability: 'selection:framework',
+    when: std => selectedBoards(std).length > 0,
+    run: std => exportBoardSvg(std),
+};
+export const exportSvgCommands = [exportSvg];

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

@@ -0,0 +1,7 @@
+export { exportBoardSvg, exportSvgCommands, selectedBoards, } from './command.js';
+export type { BoardSvgExport } from './render.js';
+export { exportBoundOf, renderBoardSvg, selectBoardElements, } from './render.js';
+export { taggedPath2D } from './tagged-path.js';
+export type { SvgContext } from './svg-context.js';
+export { createSvgContext, runWithRecordingPath2D } from './svg-context.js';
+export { exportSvgToolbarConfig, exportSvgToolbarExtension, } from './toolbar.js';

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

@@ -0,0 +1,5 @@
+export { exportBoardSvg, exportSvgCommands, selectedBoards, } from './command.js';
+export { exportBoundOf, renderBoardSvg, selectBoardElements, } from './render.js';
+export { taggedPath2D } from './tagged-path.js';
+export { createSvgContext, runWithRecordingPath2D } from './svg-context.js';
+export { exportSvgToolbarConfig, exportSvgToolbarExtension, } from './toolbar.js';

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

@@ -0,0 +1,41 @@
+import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { Bound } from '../../../global/gfx/index.js';
+import type { BlockStdScope } from '../../../std/index.js';
+import { type GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
+export interface BoardSvgExport {
+    /** A standalone SVG document. */
+    svg: string;
+    /** The world-space rectangle the document covers. */
+    bound: Bound;
+}
+/**
+ * The canvas elements that make up `board`'s picture, in paint order.
+ *
+ * `candidates` comes from a bound query, so it also holds whatever a NEIGHBOUR
+ * board happens to overlap with. Another framework background is kept only
+ * when its frame lies ENTIRELY inside the exported one (edges may touch): that
+ * is a nested frame — a UML subject, partition, region or fragment inside its
+ * diagram frame, a C4 boundary inside a C4 board — and it is part of the
+ * picture. One that merely overlaps is a neighbour and is dropped: without
+ * that, a map sitting next to this one would paint its whole frame into this
+ * file. So is one that ENCLOSES the board, the diagram frame around an
+ * exported partition. Non-background elements are kept whoever owns them — an
+ * element inside the exported frame belongs to the picture.
+ *
+ * Containment is read on the stored `xywh`, the same rectangle
+ * {@link exportBoundOf} starts from; a background at exactly the board's own
+ * rectangle therefore counts as nested.
+ */
+export declare function selectBoardElements<T extends GfxPrimitiveElementModel>(board: FrameworkBackgroundElementModel, candidates: readonly T[]): (FrameworkBackgroundElementModel | T)[];
+/**
+ * The board's frame, widened to the union of what is painted on it: a Wardley
+ * label overhanging the right edge, or a connector ending just outside, is part
+ * of the picture and must not be cut off.
+ */
+export declare function exportBoundOf(board: FrameworkBackgroundElementModel, elements: readonly GfxPrimitiveElementModel[]): Bound;
+/**
+ * The selected board and everything painted within its frame, as an SVG
+ * document — a true vector export, produced by replaying the very element
+ * renderers the canvas uses into an SVG-emitting 2D context.
+ */
+export declare function renderBoardSvg(std: BlockStdScope, board: FrameworkBackgroundElementModel): BoardSvgExport;

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

@@ -0,0 +1,70 @@
+import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { Bound } from '../../../global/gfx/index.js';
+import { GfxControllerIdentifier, } from '../../../std/gfx/index.js';
+import { CanvasRenderer } from '../../renderer/canvas-renderer.js';
+import { RoughCanvas } from '../../utils/rough/canvas.js';
+import { createSvgContext, runWithRecordingPath2D } from './svg-context.js';
+/**
+ * The canvas elements that make up `board`'s picture, in paint order.
+ *
+ * `candidates` comes from a bound query, so it also holds whatever a NEIGHBOUR
+ * board happens to overlap with. Another framework background is kept only
+ * when its frame lies ENTIRELY inside the exported one (edges may touch): that
+ * is a nested frame — a UML subject, partition, region or fragment inside its
+ * diagram frame, a C4 boundary inside a C4 board — and it is part of the
+ * picture. One that merely overlaps is a neighbour and is dropped: without
+ * that, a map sitting next to this one would paint its whole frame into this
+ * file. So is one that ENCLOSES the board, the diagram frame around an
+ * exported partition. Non-background elements are kept whoever owns them — an
+ * element inside the exported frame belongs to the picture.
+ *
+ * Containment is read on the stored `xywh`, the same rectangle
+ * {@link exportBoundOf} starts from; a background at exactly the board's own
+ * rectangle therefore counts as nested.
+ */
+export function selectBoardElements(board, candidates) {
+    const frame = Bound.deserialize(board.xywh);
+    const kept = candidates.filter(element => element === board ||
+        !(element instanceof FrameworkBackgroundElementModel) ||
+        frame.contains(Bound.deserialize(element.xywh)));
+    // A background paints under everything, so a board missing from the query
+    // (an empty bound, a stub) goes in front of the list, not at the end.
+    return kept.some(element => element === board)
+        ? kept
+        : [board, ...kept];
+}
+/**
+ * The board's frame, widened to the union of what is painted on it: a Wardley
+ * label overhanging the right edge, or a connector ending just outside, is part
+ * of the picture and must not be cut off.
+ */
+export function exportBoundOf(board, elements) {
+    let bound = Bound.deserialize(board.xywh);
+    for (const element of elements) {
+        bound = bound.unite(Bound.deserialize(element.xywh));
+    }
+    return bound;
+}
+/**
+ * The selected board and everything painted within its frame, as an SVG
+ * document — a true vector export, produced by replaying the very element
+ * renderers the canvas uses into an SVG-emitting 2D context.
+ */
+export function renderBoardSvg(std, board) {
+    const gfx = std.get(GfxControllerIdentifier);
+    const renderer = gfx.surfaceComponent?.renderer;
+    if (!(renderer instanceof CanvasRenderer)) {
+        throw new Error('SVG export needs the surface to be painted by a CanvasRenderer.');
+    }
+    // Already sorted by `layer.compare`, which is the canvas' own z-order.
+    const candidates = gfx.getElementsByBound(Bound.deserialize(board.xywh), {
+        type: 'canvas',
+    });
+    const elements = selectBoardElements(board, candidates);
+    const bound = exportBoundOf(board, elements);
+    return runWithRecordingPath2D(() => {
+        const { ctx, canvas, serialize } = createSvgContext(bound.w, bound.h);
+        renderer.renderBoundTo(ctx, new RoughCanvas(canvas), bound, elements);
+        return { svg: serialize(), bound };
+    });
+}

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,
+});