@formicoidea/labre-core 0.43.1 → 0.45.0

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

@@ -30,8 +30,7 @@
 import { getAuditCriteria, requestAudit, TelemetryProvider, } from '../../affine-shared/services/index.js';
 import { GfxControllerIdentifier, GfxPrimitiveElementModel, roleIsA, } from '../../std/gfx/index.js';
 import { z } from 'zod';
-import { backgroundInstanceZones, backgroundPlot, } from '../framework-background/def.js';
-import { backgroundAxisFacts, containingFrame, } from '../framework-background/facts.js';
+import { backgroundAxisFacts, backgroundPlotRatios, backgroundZoneAt, backgroundZones, containingFrame, } from '../framework-background/facts.js';
 import { ValidationManager, ValidationRuleIdentifier, } from './validation.js';
 /**
  * `map.audit` takes no required parameter: the assistant audits what is
@@ -113,69 +112,21 @@ function collectFrames(rules, elements) {
                     type: def.type,
                     ...(typeof profileId === 'string' ? { profileId } : {}),
                     axes: backgroundAxisFacts(def),
-                    // The framework's zones first, then the ones THIS frame declares —
-                    // a BPMN pool's lanes. Concatenated rather than merged: the two
-                    // namespaces are kept apart by the instance ids' prefix, so `zoneAt`
-                    // resolves them by the same containment test and a framework zone
-                    // still wins a genuine overlap, which is the reading that was true
-                    // before an element could partition its own plot.
-                    zones: [
-                        ...(def.zones ?? []).map(zone => ({
-                            id: zone.id,
-                            rect: { ...zone.rect },
-                        })),
-                        ...backgroundInstanceZones(def, el).map(zone => ({
-                            id: zone.id,
-                            ...(zone.name !== undefined ? { name: zone.name } : {}),
-                            rect: { ...zone.rect },
-                        })),
-                    ],
+                    // The zones THIS frame has — the framework's, in the variant it is
+                    // turned to, then its own (a BPMN pool's lanes) — read through the
+                    // helper the reading panel uses, so the two cannot disagree. Copied
+                    // field by field: the declared label is painting data, not a fact.
+                    zones: backgroundZones(def, el).map(zone => ({
+                        id: zone.id,
+                        ...(zone.name !== undefined ? { name: zone.name } : {}),
+                        rect: { ...zone.rect },
+                    })),
                 },
             });
         }
     }
     return frames;
 }
-/**
- * Where an element's centre sits inside a frame's PLOT, as ratios.
- *
- * A POSITION, not a membership test: it is asked only about an element some
- * frame already contains, and answers where in that frame's plot it lies.
- *
- * Ratios of the plot and not of the element box: a Wardley transition drawn at
- * `0.4` is 40 % of the PLOT, not of the map element, and the margin between the
- * two is exactly where the axis titles live. `backgroundPlot` is the one place
- * that knows the difference, and this is the only reason this function exists
- * rather than a subtraction at the call site.
- *
- * Not clamped: an element just off the left edge reads as `-0.03`, which is a
- * true and useful thing to say. `null` for a degenerate plot.
- */
-function plotRatios(frame, bound) {
-    const plot = backgroundPlot(frame.def, frame.bound.w, frame.bound.h);
-    if (!(plot.width > 0) || !(plot.height > 0))
-        return null;
-    const cx = bound.x + bound.w / 2;
-    const cy = bound.y + bound.h / 2;
-    return [
-        (cx - frame.bound.x - plot.x0) / plot.width,
-        (cy - frame.bound.y - plot.y0) / plot.height,
-    ];
-}
-/**
- * The zone a plot-ratio point falls in, if any — one the framework declares or
- * one the frame itself does. It needs to know nothing about the difference: the
- * fact carries both, in that order, as rectangles in the same ratios.
- */
-function zoneAt(frame, at) {
-    for (const zone of frame.fact.zones) {
-        const { x, y, w, h } = zone.rect;
-        if (at[0] >= x && at[0] <= x + w && at[1] >= y && at[1] <= y + h) {
-            return zone.id;
-        }
-    }
-    return undefined;
-}
 /**
  * Levels 1 and 2, copied out of the engine's verdict.
  *
@@ -245,8 +196,9 @@ export function collectAuditFacts(std) {
             elementFacts.push({ id: el.id, role });
             continue;
         }
-        const at = plotRatios(frame, bound);
-        const zone = at === null ? undefined : zoneAt(frame, at);
+        // A POSITION, not a membership test: `frame` already contains the element.
+        const at = backgroundPlotRatios(frame.def, frame.bound, bound);
+        const zone = at === null ? undefined : backgroundZoneAt(frame.fact.zones, at)?.id;
         elementFacts.push({
             id: el.id,
             role,

package/dist/_pkgs/affine-block-surface/extensions/canvas-grid/commands.d.ts

@@ -0,0 +1,2 @@
+import type { AnyCommandDescriptor } from '../../../std/index.js';
+export declare const canvasGridCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-block-surface/extensions/canvas-grid/commands.js

@@ -0,0 +1,71 @@
+import { CanvasGrid, TelemetryProvider } from '../../../affine-shared/services/index.js';
+/**
+ * The canvas grid's two commands (ADR 0031 §11, §12), `owner: 'core'`, on the
+ * palette and the agent. The library has no page "more" menu — that belongs
+ * to the host — so these are the grid's whole UI here; a host puts them in
+ * its own menu through `runCommand`.
+ *
+ * Both self-emit `CanvasGridToggled` (see the telemetry README): `scope` is
+ * which gesture ran, and a save that changes nothing reports nothing.
+ */
+function reportGrid(std, scope, visible) {
+    std.getOptional(TelemetryProvider)?.track('CanvasGridToggled', {
+        page: 'whiteboard editor',
+        scope,
+        visible,
+    });
+}
+/**
+ * Show or hide the grid for THIS viewer, on this document. Writes nothing to
+ * the document, so a reader may do it too.
+ */
+const toggleGrid = {
+    id: 'canvas.grid.toggle',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.grid.toggle',
+    labelFallback: 'Show or hide the grid',
+    descriptionKey: 'com.labre.command.canvas.grid.toggle.description',
+    descriptionFallback: 'Show or hide the canvas grid on your screen only. Nothing changes for anyone else.',
+    keywords: ['grid', 'dots', 'background'],
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    when: std => !!std.getOptional(CanvasGrid),
+    run: std => {
+        const grid = std.getOptional(CanvasGrid);
+        if (!grid)
+            return;
+        reportGrid(std, 'local', grid.toggle());
+    },
+};
+/**
+ * Store the grid as this viewer sees it on the document, for everyone, and
+ * drop this viewer's own override. Read-only refuses (`availability`, and
+ * again in `CanvasGrid.saveForEveryone`).
+ */
+const saveGridForEveryone = {
+    id: 'canvas.grid.saveForEveryone',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.grid.save-for-everyone',
+    labelFallback: 'Save the grid for everyone',
+    descriptionKey: 'com.labre.command.canvas.grid.save-for-everyone.description',
+    descriptionFallback: 'Make the grid as you see it now the setting of this document, for everyone who opens it.',
+    keywords: ['grid', 'dots', 'background', 'document'],
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => !!std.getOptional(CanvasGrid),
+    run: std => {
+        const saved = std.getOptional(CanvasGrid)?.saveForEveryone() ?? null;
+        if (saved === null)
+            return;
+        reportGrid(std, 'everyone', saved);
+    },
+};
+export const canvasGridCommands = [
+    toggleGrid,
+    saveGridForEveryone,
+];

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

@@ -0,0 +1 @@
+export { canvasGridCommands } from './commands.js';

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

@@ -0,0 +1 @@
+export { canvasGridCommands } from './commands.js';

package/dist/_pkgs/affine-block-surface/extensions/clipboard-config.js

@@ -4,12 +4,16 @@ import { StdIdentifier } from '../../std/index.js';
 import { Extension } from '../../store/index.js';
 import { getSurfaceComponent } from '../utils/get-surface-block.js';
 import { EdgelessCRUDIdentifier } from './crud-extension.js';
+import { applyCreationLayer } from './user-layers/creation.js';
 export const EdgelessClipboardConfigIdentifier = createIdentifier('edgeless-clipboard-config');
 export class EdgelessClipboardConfig extends Extension {
     constructor(std) {
         super();
         this.std = std;
         this.onBlockSnapshotPaste = async (snapshot, doc, parent, index) => {
+            // The clipboard's block path follows the elements' rule (ADR 0031 §6):
+            // a layer of this surface is kept, anything else lands in the active one.
+            applyCreationLayer(this.std, snapshot.props);
             const block = await this.std.clipboard.pasteBlockSnapshot(snapshot, doc, parent, index);
             return block?.id ?? null;
         };

package/dist/_pkgs/affine-block-surface/extensions/crud-extension.js

@@ -5,6 +5,7 @@ import { GfxBlockElementModel, GfxControllerIdentifier, isGfxGroupCompatibleMode
 import { Extension } from '../../store/index.js';
 import { getLastPropsKey } from '../utils/get-last-props-key.js';
 import { isConnectable, isNoteBlock } from './query.js';
+import { applyCreationLayer } from './user-layers/creation.js';
 export const EdgelessCRUDIdentifier = createIdentifier('AffineEdgelessCrudService');
 export class EdgelessCRUDExtension extends Extension {
     constructor(std) {
@@ -48,6 +49,9 @@ export class EdgelessCRUDExtension extends Extension {
                 ...props,
                 index: gfx.layer.generateIndex(),
             };
+            // A gfx block gets the elements' rule (ADR 0031 §6): its own layer if it
+            // names one of this surface, else the viewer's active layer.
+            applyCreationLayer(this.std, nProps);
             return this.std.store.addBlock(flavour, nProps, parentId, parentIndex);
         };
         this.addElement = (type, props) => {

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

@@ -3,6 +3,18 @@ import { type BlockStdScope, type EditorHost } from '../../../std/index.js';
 import { GfxBlockElementModel, type GfxController, GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
 import type { ExtensionType, Store } from '../../../store/index.js';
 import { CanvasRenderer } from '../../renderer/canvas-renderer.js';
+export type EdgelessBackgroundOptions = {
+    size: number;
+    backgroundColor: string;
+    /** `null` when the grid is off (ADR 0031 §11): the background alone. */
+    gridColor: string | null;
+};
+/**
+ * The SVG the PNG export paints the canvas background from: the background
+ * colour, plus the dotted grid unless `gridColor` is `null` — what this
+ * viewer sees, as `CanvasGrid.visible$` says.
+ */
+export declare function edgelessBackgroundSvg(width: number, height: number, { size, backgroundColor, gridColor }: EdgelessBackgroundOptions): string;
 export declare class ExportManager {
     readonly std: BlockStdScope;
     /**

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

@@ -1,8 +1,8 @@
 import { ImageBlockModel } from '../../../affine-model/index.js';
 import { FetchUtils, ImageProxyService } from '../../../affine-shared/adapters/index.js';
 import { CANVAS_EXPORT_IGNORE_TAGS } from '../../../affine-shared/consts/index.js';
-import { CHROME_UNTITLED, translateKey } from '../../../affine-shared/services/index.js';
-import { isInsidePageEditor, matchModels } from '../../../affine-shared/utils/index.js';
+import { CanvasGrid, CHROME_UNTITLED, translateKey, } from '../../../affine-shared/services/index.js';
+import { isInsidePageEditor, matchModels, normalizeCanvasExportColors, toLegacyColors, } from '../../../affine-shared/utils/index.js';
 import { BlockSuiteError, ErrorCode } from '../../../global/exceptions/index.js';
 import { deserializeXYWH } from '../../../global/gfx/index.js';
 import { StdIdentifier, } from '../../../std/index.js';
@@ -10,6 +10,17 @@ import { GfxBlockElementModel, GfxControllerIdentifier, GfxPrimitiveElementModel
 import { CanvasRenderer } from '../../renderer/canvas-renderer.js';
 import { getBgGridGap } from '../../utils/get-bg-grip-gap.js';
 import { FileExporter } from './file-exporter.js';
+/**
+ * The SVG the PNG export paints the canvas background from: the background
+ * colour, plus the dotted grid unless `gridColor` is `null` — what this
+ * viewer sees, as `CanvasGrid.visible$` says.
+ */
+export function edgelessBackgroundSvg(width, height, { size, backgroundColor, gridColor }) {
+    const grid = gridColor === null
+        ? ''
+        : ` background-image: radial-gradient(${gridColor} 1px, ${backgroundColor} 1px)`;
+    return `<svg width='${width}px' height='${height}px' xmlns='http://www.w3.org/2000/svg' style='background-size:${size}px ${size}px;background-color:${backgroundColor};${grid}'></svg>`;
+}
 export class ExportManager {
     /**
      * The image proxy every remote-image fetch of the export goes through —
@@ -157,11 +168,12 @@ export class ExportManager {
                     return false;
                 }
             },
-            onclone: async (_documentClone, element) => {
+            onclone: async (documentClone, element) => {
+                normalizeCanvasExportColors(documentClone, element);
                 element.style.height = `${viewportHeight}px`;
                 await this.replaceImgSrcWithSvg(element);
             },
-            backgroundColor: window.getComputedStyle(viewportElement).backgroundColor,
+            backgroundColor: toLegacyColors(window.getComputedStyle(viewportElement).backgroundColor),
             x: pageLeft - viewport.left,
             width: pageWidth,
             height: viewportHeight,
@@ -179,8 +191,8 @@ export class ExportManager {
         this._checkCanContinueToCanvas(pathname, editorMode);
         return data;
     }
-    _drawEdgelessBackground(ctx, { size, backgroundColor, gridColor, }) {
-        const svgImg = `<svg width='${ctx.canvas.width}px' height='${ctx.canvas.height}px' xmlns='http://www.w3.org/2000/svg' style='background-size:${size}px ${size}px;background-color:${backgroundColor}; background-image: radial-gradient(${gridColor} 1px, ${backgroundColor} 1px)'></svg>`;
+    _drawEdgelessBackground(ctx, options) {
+        const svgImg = edgelessBackgroundSvg(ctx.canvas.width, ctx.canvas.height, options);
         const img = new Image();
         const cleanup = () => {
             img.onload = null;
@@ -218,6 +230,7 @@ export class ExportManager {
                 }
             },
             onclone: async (documentClone, element) => {
+                normalizeCanvasExportColors(documentClone, element);
                 // html2canvas can't support transform feature
                 element.style.setProperty('transform', 'none');
                 const layer = element.classList.contains('.affine-edgeless-layer')
@@ -300,7 +313,10 @@ export class ExportManager {
             await this._drawEdgelessBackground(ctx, {
                 backgroundColor: containerComputedStyle.getPropertyValue('--affine-background-primary-color'),
                 size: getBgGridGap(edgelessBackground.zoom),
-                gridColor: containerComputedStyle.getPropertyValue('--affine-edgeless-grid-color'),
+                // What this viewer sees: off leaves the background colour alone.
+                gridColor: (this.std.getOptional(CanvasGrid)?.visible$.peek() ?? true)
+                    ? containerComputedStyle.getPropertyValue('--affine-edgeless-grid-color')
+                    : null,
             });
         }
         if (!blocks && !elements) {
@@ -331,6 +347,10 @@ export class ExportManager {
             elements = [...elementSet];
             blocks = [...blockSet];
         }
+        // What you see is what you export (ADR 0031, resolved at acceptance): a
+        // block this viewer hid is not drawn. Canvas elements are left out by the
+        // renderer's own paint predicate.
+        blocks = blocks.filter(block => !gfx.localVisibility.isHidden(block));
         for (const block of blocks) {
             if (matchModels(block, [ImageBlockModel])) {
                 if (!block.props.sourceId)

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

@@ -1,5 +1,6 @@
 import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
 import type { AnyCommandDescriptor, BlockStdScope } from '../../../std/index.js';
+import { type BoardSvgExportOptions } from './parts.js';
 /**
  * The framework boards in the current canvas selection.
  *
@@ -19,5 +20,5 @@ export declare function selectedBoards(std: BlockStdScope): FrameworkBackgroundE
  * on the browser — a result nobody can read off the gesture. One board, one
  * file, every time.
  */
-export declare function exportBoardSvg(std: BlockStdScope): void;
+export declare function exportBoardSvg(std: BlockStdScope, options?: Readonly<BoardSvgExportOptions>): void;
 export declare const exportSvgCommands: AnyCommandDescriptor[];

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

@@ -1,7 +1,10 @@
 import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { NotificationProvider, translateKey, } from '../../../affine-shared/services/index.js';
 import { downloadBlob, safeFilename } from '../../../affine-shared/utils/index.js';
 import { GfxControllerIdentifier } from '../../../std/gfx/index.js';
+import { boardSvgExportOptions, DEFAULT_BOARD_SVG_EXPORT_OPTIONS, } from './parts.js';
 import { renderBoardSvg } from './render.js';
+import { EXPORT_SVG_NOTHING_TO_EXPORT } from './translations.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. */
@@ -29,11 +32,20 @@ export function selectedBoards(std) {
  * on the browser — a result nobody can read off the gesture. One board, one
  * file, every time.
  */
-export function exportBoardSvg(std) {
+export function exportBoardSvg(std, options = DEFAULT_BOARD_SVG_EXPORT_OPTIONS) {
     const [board] = selectedBoards(std);
     if (!board)
         return;
-    const { svg } = renderBoardSvg(std, board);
+    const rendered = renderBoardSvg(std, board, options);
+    if (!rendered) {
+        // Every part left was switched off. Said once, through the host's
+        // notification seam; a host without one simply gets no file.
+        std
+            .getOptional(NotificationProvider)
+            ?.toast(translateKey(std, ...EXPORT_SVG_NOTHING_TO_EXPORT));
+        return;
+    }
+    const { svg } = rendered;
     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`
@@ -53,6 +65,13 @@ export function exportBoardSvg(std) {
  * It READS, so there is no read-only guard: taking a picture of a board you
  * cannot edit is precisely what a reader does.
  *
+ * Its optional params are the export options (`parts.ts`), which the "⋮"
+ * entry asks for before it runs this. Every other surface — the palette, the
+ * catalogue, a shortcut, the agent — passes nothing and exports everything,
+ * without a dialog. They are deliberately not declared as `params`: the agent
+ * contract stays "export the selected board", and `run` re-validates whatever
+ * arrives.
+ *
  * 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
@@ -84,6 +103,6 @@ const exportSvg = {
     // union can express.
     availability: 'selection:framework',
     when: std => selectedBoards(std).length > 0,
-    run: std => exportBoardSvg(std),
+    run: (std, _invocation, params) => exportBoardSvg(std, boardSvgExportOptions(params)),
 };
 export const exportSvgCommands = [exportSvg];

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

@@ -1,7 +1,10 @@
 export { exportBoardSvg, exportSvgCommands, selectedBoards, } from './command.js';
-export type { BoardSvgExport } from './render.js';
-export { exportBoundOf, renderBoardSvg, selectBoardElements, } from './render.js';
+export type { BoardSvgExportOptions, BoardSvgExportPart, SvgExportCandidate, } from './parts.js';
+export { boardSvgExportOptions, boardSvgExportPartOf, DEFAULT_BOARD_SVG_EXPORT_OPTIONS, selectBoardSvgParts, } from './parts.js';
+export type { BlockSvgPainter, BoardSvgExport } from './render.js';
+export { BlockSvgPainterExtension, BlockSvgPainterIdentifier, boardSvgMarkers, 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 { BOARD_SVG_MARKER_VERSION, createSvgContext, runWithRecordingPath2D, } from './svg-context.js';
 export { exportSvgToolbarConfig, exportSvgToolbarExtension, } from './toolbar.js';
+export { EXPORT_SVG_WORDINGS } from './translations.js';

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

@@ -1,5 +1,7 @@
 export { exportBoardSvg, exportSvgCommands, selectedBoards, } from './command.js';
-export { exportBoundOf, renderBoardSvg, selectBoardElements, } from './render.js';
+export { boardSvgExportOptions, boardSvgExportPartOf, DEFAULT_BOARD_SVG_EXPORT_OPTIONS, selectBoardSvgParts, } from './parts.js';
+export { BlockSvgPainterExtension, BlockSvgPainterIdentifier, boardSvgMarkers, exportBoundOf, renderBoardSvg, selectBoardElements, } from './render.js';
 export { taggedPath2D } from './tagged-path.js';
-export { createSvgContext, runWithRecordingPath2D } from './svg-context.js';
+export { BOARD_SVG_MARKER_VERSION, createSvgContext, runWithRecordingPath2D, } from './svg-context.js';
 export { exportSvgToolbarConfig, exportSvgToolbarExtension, } from './toolbar.js';
+export { EXPORT_SVG_WORDINGS } from './translations.js';

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

@@ -0,0 +1,63 @@
+/**
+ * What "Export SVG" puts in the file — the three switches of its options menu,
+ * all on by default (ADR 0025, amendment of 2026-10-04).
+ */
+export interface BoardSvgExportOptions {
+    /** The board, its framework's artefacts and its generated legend. */
+    framework: boolean;
+    /** Every other canvas element that is not a text: shapes, connectors, strokes. */
+    shapes: boolean;
+    /** Every other text: canvas texts, and the edgeless text blocks. */
+    texts: boolean;
+}
+export type BoardSvgExportPart = keyof BoardSvgExportOptions;
+export declare const DEFAULT_BOARD_SVG_EXPORT_OPTIONS: Readonly<BoardSvgExportOptions>;
+/**
+ * The options a command invocation carries, re-validated: the palette and the
+ * agent pass nothing and get everything, and only an explicit `false` switches
+ * a part off — a stray value never empties a file.
+ */
+export declare function boardSvgExportOptions(params: unknown): BoardSvgExportOptions;
+/**
+ * The stored facts the rule reads, and nothing else: an element's `role` and
+ * `type`, and a group's `childElements`. Structural, so the rule runs over a
+ * real model and over a recorded creation alike.
+ */
+export interface SvgExportCandidate {
+    readonly role?: string;
+    readonly type?: string;
+    readonly childElements?: readonly SvgExportCandidate[];
+}
+/**
+ * Which switch an element on `board` answers to.
+ *
+ * - **Framework elements**: the board itself; anything whose role shares the
+ *   board's role namespace (`wardley:map` owns `wardley:component`,
+ *   `wardley:label`, `wardley:dependency`…); the generated legend
+ *   (`core:legend`, ADR 0026) and every glyph in it; and a ROLE-LESS element
+ *   grouped with any of those. The last clause is what a framework artefact is
+ *   made of: an EDGY person and its name, a Wardley market and its three dots,
+ *   a Core Domain sub-domain and its title are one group in which only one
+ *   member carries the role.
+ * - **Other texts**: any other `text` element — a plain one, or one of ANOTHER
+ *   framework lying on this board, which is a text like any other here.
+ * - **Other shapes and strokes**: everything else — plain shapes, plain
+ *   connectors, brush and highlighter strokes, mind maps, another framework's
+ *   shapes, and a plain group (which paints nothing of its own in an export).
+ *
+ * Read off the namespace rather than a `FrameworkId` on purpose: three DDD
+ * frameworks spell their roles `es:`, `core-domain:` and `context-map:`, and
+ * the board says which one it speaks. A board with no role (Cynefin, which
+ * paints its domains itself) owns itself and nothing else. Edgeless text
+ * BLOCKS never reach this function: they carry no role and are always "other
+ * texts" ({@link selectBoardSvgParts}).
+ */
+export declare function boardSvgExportPartOf(board: SvgExportCandidate, element: SvgExportCandidate, groups: readonly SvgExportCandidate[]): BoardSvgExportPart;
+/**
+ * What the file draws under `options`: the canvas elements, in the paint order
+ * they came in, and the edgeless text blocks, which are all "other texts".
+ */
+export declare function selectBoardSvgParts<E extends SvgExportCandidate, B>(board: SvgExportCandidate, elements: readonly E[], textBlocks: readonly B[], options: Readonly<BoardSvgExportOptions>, groupsOf: (element: E) => readonly SvgExportCandidate[]): {
+    elements: E[];
+    textBlocks: B[];
+};

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

@@ -0,0 +1,67 @@
+import { LEGEND_ROLE } from '../legend.js';
+export const DEFAULT_BOARD_SVG_EXPORT_OPTIONS = Object.freeze({ framework: true, shapes: true, texts: true });
+/**
+ * The options a command invocation carries, re-validated: the palette and the
+ * agent pass nothing and get everything, and only an explicit `false` switches
+ * a part off — a stray value never empties a file.
+ */
+export function boardSvgExportOptions(params) {
+    const given = (params !== null && typeof params === 'object' ? params : {});
+    return {
+        framework: given.framework !== false,
+        shapes: given.shapes !== false,
+        texts: given.texts !== false,
+    };
+}
+/** `'wardley:component'` → `'wardley'`; nothing for a missing or empty role. */
+const namespaceOf = (role) => role?.split(':')[0] || undefined;
+/**
+ * Which switch an element on `board` answers to.
+ *
+ * - **Framework elements**: the board itself; anything whose role shares the
+ *   board's role namespace (`wardley:map` owns `wardley:component`,
+ *   `wardley:label`, `wardley:dependency`…); the generated legend
+ *   (`core:legend`, ADR 0026) and every glyph in it; and a ROLE-LESS element
+ *   grouped with any of those. The last clause is what a framework artefact is
+ *   made of: an EDGY person and its name, a Wardley market and its three dots,
+ *   a Core Domain sub-domain and its title are one group in which only one
+ *   member carries the role.
+ * - **Other texts**: any other `text` element — a plain one, or one of ANOTHER
+ *   framework lying on this board, which is a text like any other here.
+ * - **Other shapes and strokes**: everything else — plain shapes, plain
+ *   connectors, brush and highlighter strokes, mind maps, another framework's
+ *   shapes, and a plain group (which paints nothing of its own in an export).
+ *
+ * Read off the namespace rather than a `FrameworkId` on purpose: three DDD
+ * frameworks spell their roles `es:`, `core-domain:` and `context-map:`, and
+ * the board says which one it speaks. A board with no role (Cynefin, which
+ * paints its domains itself) owns itself and nothing else. Edgeless text
+ * BLOCKS never reach this function: they carry no role and are always "other
+ * texts" ({@link selectBoardSvgParts}).
+ */
+export function boardSvgExportPartOf(board, element, groups) {
+    if (element === board)
+        return 'framework';
+    const own = namespaceOf(board.role);
+    const owned = (role) => role === LEGEND_ROLE || (own !== undefined && namespaceOf(role) === own);
+    if (owned(element.role))
+        return 'framework';
+    if (element.role === undefined) {
+        const enclosing = element.childElements ? [element, ...groups] : groups;
+        const ownedGroup = enclosing.some(group => owned(group.role) ||
+            group.childElements?.some(child => owned(child.role)));
+        if (ownedGroup)
+            return 'framework';
+    }
+    return element.type === 'text' ? 'texts' : 'shapes';
+}
+/**
+ * What the file draws under `options`: the canvas elements, in the paint order
+ * they came in, and the edgeless text blocks, which are all "other texts".
+ */
+export function selectBoardSvgParts(board, elements, textBlocks, options, groupsOf) {
+    return {
+        elements: elements.filter(element => options[boardSvgExportPartOf(board, element, groupsOf(element))]),
+        textBlocks: options.texts ? [...textBlocks] : [],
+    };
+}

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

@@ -1,13 +1,30 @@
 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';
+import { type GfxBlockElementModel, type GfxPrimitiveElementModel } from '../../../std/gfx/index.js';
+import type { ExtensionType } from '../../../store/index.js';
+import { CanvasRenderer } from '../../renderer/canvas-renderer.js';
+import { type BoardSvgExportOptions } from './parts.js';
 export interface BoardSvgExport {
     /** A standalone SVG document. */
     svg: string;
     /** The world-space rectangle the document covers. */
     bound: Bound;
 }
+/**
+ * How a BLOCK paints itself into the export's 2D context, in model units, the
+ * block's top-left at the origin of `matrix`.
+ *
+ * Blocks are DOM, so the canvas renderer never sees them (ADR 0025,
+ * Consequences). The one block the export draws anyway is the edgeless text —
+ * what the text tool creates by default — and its painter lives with it, in
+ * `@labre/affine-block-edgeless-text`, because the text metrics it needs
+ * (`@labre/affine-gfx-text`) sit ABOVE this package. Keyed by flavour; a block
+ * with no painter registered is simply not drawn.
+ */
+export type BlockSvgPainter<T extends GfxBlockElementModel = GfxBlockElementModel> = (model: T, ctx: CanvasRenderingContext2D, matrix: DOMMatrix, renderer: CanvasRenderer) => void;
+export declare const BlockSvgPainterIdentifier: import("../../../global/di/types.js").ServiceIdentifier<BlockSvgPainter<GfxBlockElementModel<import("../../../std/gfx/index.js").GfxCompatibleProps>>> & (<U extends BlockSvgPainter<GfxBlockElementModel<import("../../../std/gfx/index.js").GfxCompatibleProps>> = BlockSvgPainter<GfxBlockElementModel<import("../../../std/gfx/index.js").GfxCompatibleProps>>>(variant: import("../../../global/di/types.js").ServiceVariant) => import("../../../global/di/types.js").ServiceIdentifier<U>);
+export declare function BlockSvgPainterExtension<T extends GfxBlockElementModel>(flavour: string, painter: BlockSvgPainter<T>): ExtensionType;
 /**
  * The canvas elements that make up `board`'s picture, in paint order.
  *
@@ -28,14 +45,54 @@ export interface BoardSvgExport {
  */
 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.
+ * The frame, widened to the union of what is painted: a Wardley label
+ * overhanging the right edge, or a connector ending just outside, is part of
+ * the picture and must not be cut off. The frame is the board's — or, with
+ * "Framework elements" switched off, the first thing still drawn.
  */
-export declare function exportBoundOf(board: FrameworkBackgroundElementModel, elements: readonly GfxPrimitiveElementModel[]): Bound;
+export declare function exportBoundOf(frame: {
+    readonly xywh: string;
+}, elements: readonly {
+    readonly xywh: string;
+}[]): 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.
+ *
+ * `options` says which parts are drawn (`parts.ts`). `null` when they leave
+ * nothing to draw: an empty file is not a picture of anything.
+ *
+ * Without `options` every part is drawn, the board among them, so the 0.43
+ * call shape `renderBoardSvg(std, board).svg` keeps its non-null return
+ * (`render-board-svg-signature.unit.spec.ts`). Only the overload that takes
+ * options can answer `null`.
  */
 export declare function renderBoardSvg(std: BlockStdScope, board: FrameworkBackgroundElementModel): BoardSvgExport;
+export declare function renderBoardSvg(std: BlockStdScope, board: FrameworkBackgroundElementModel, options: Readonly<BoardSvgExportOptions>): BoardSvgExport | null;
+/**
+ * What an element's group says about it in the file (ADR 0032 §6): its id, its
+ * type, its role, its stored bound in the FILE's coordinates, the two ends of
+ * a connector and the group it belongs to — base-class fields only, so every
+ * board's SVG carries them and no framework is named here.
+ *
+ * Ids and vocabulary, never prose: no `pivotDocId` (its contract forbids an
+ * exporter to read it), no `interchange`, no tag, no link, no text — a name is
+ * read back from the `<text>` the renderer already drew.
+ */
+export declare function boardSvgMarkers(element: {
+    id: string;
+    xywh: string;
+    type?: string;
+    flavour?: string;
+    role?: string;
+    group?: {
+        id: string;
+    } | null;
+    source?: {
+        id?: string;
+    } | null;
+    target?: {
+        id?: string;
+    } | null;
+}, bound: Bound): Record<string, string>;