@formicoidea/labre-core 0.43.1 → 0.45.0

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

@@ -1,9 +1,21 @@
 import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
+import { createIdentifier } from '../../../global/di/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 { DEFAULT_BOARD_SVG_EXPORT_OPTIONS, selectBoardSvgParts, } from './parts.js';
 import { createSvgContext, runWithRecordingPath2D } from './svg-context.js';
+export const BlockSvgPainterIdentifier = createIdentifier('block-svg-painter');
+export function BlockSvgPainterExtension(flavour, painter) {
+    return {
+        setup: di => {
+            di.addImpl(BlockSvgPainterIdentifier(flavour), () => painter);
+        },
+    };
+}
+/** The blocks the export redraws, all of them "other texts" (`parts.ts`). */
+const SVG_TEXT_BLOCK_FLAVOURS = ['affine:edgeless-text'];
 /**
  * The canvas elements that make up `board`'s picture, in paint order.
  *
@@ -34,37 +46,105 @@ export function selectBoardElements(board, candidates) {
         : [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.
+ * 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 function exportBoundOf(board, elements) {
-    let bound = Bound.deserialize(board.xywh);
+export function exportBoundOf(frame, elements) {
+    let bound = Bound.deserialize(frame.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) {
+export function renderBoardSvg(std, board, given) {
+    const options = given ?? DEFAULT_BOARD_SVG_EXPORT_OPTIONS;
     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.');
     }
+    const frame = Bound.deserialize(board.xywh);
     // 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);
+    // What you see is what you export (ADR 0031): what this viewer hid is
+    // neither painted nor allowed to widen the picture. The board itself stays,
+    // it is the sheet being exported.
+    const candidates = gfx
+        .getElementsByBound(frame, { type: 'canvas' })
+        .filter(element => element === board || !gfx.localVisibility.isHidden(element));
+    const textBlocks = gfx
+        .getElementsByBound(frame, { type: 'block' })
+        .filter(block => SVG_TEXT_BLOCK_FLAVOURS.includes(block.flavour) &&
+        !gfx.localVisibility.isHidden(block));
+    const { elements, textBlocks: texts } = selectBoardSvgParts(board, selectBoardElements(board, candidates), textBlocks, options, element => element.groups);
+    const drawn = [...elements, ...texts];
+    if (!drawn.length) {
+        // Unreachable without options: the board is always selected and answers
+        // to "Framework elements". Thrown rather than returned, so the overload
+        // that promises an export never hands back `null`.
+        if (given === undefined) {
+            throw new Error('SVG export drew nothing with every part on: the board itself was not selected.');
+        }
+        return null;
+    }
+    const bound = exportBoundOf(options.framework ? board : drawn[0], drawn);
     return runWithRecordingPath2D(() => {
-        const { ctx, canvas, serialize } = createSvgContext(bound.w, bound.h);
-        renderer.renderBoundTo(ctx, new RoughCanvas(canvas), bound, elements);
+        const { ctx, canvas, serialize, markRoot, markedGroup } = createSvgContext(bound.w, bound.h);
+        const rc = new RoughCanvas(canvas);
+        markRoot();
+        // One model per pass, each inside a group carrying its markers (ADR 0032
+        // §6), in the canvas' own z-order: a text block is painted at its layer
+        // index, between the elements it sits between on screen.
+        const blocks = new Set(texts);
+        for (const model of [...elements, ...texts].sort(gfx.layer.compare)) {
+            if (!blocks.has(model)) {
+                const element = model;
+                markedGroup(boardSvgMarkers(element, bound), () => renderer.renderBoundTo(ctx, rc, bound, [element]));
+                continue;
+            }
+            const block = model;
+            const paint = std.getOptional(BlockSvgPainterIdentifier(block.flavour));
+            if (!paint)
+                continue;
+            markedGroup(boardSvgMarkers(block, bound), () => {
+                ctx.save();
+                paint(block, ctx, new DOMMatrix().translate(block.x - bound.x, block.y - bound.y), renderer);
+                ctx.restore();
+            });
+        }
         return { svg: serialize(), bound };
     });
 }
+/**
+ * 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 function boardSvgMarkers(element, bound) {
+    const own = Bound.deserialize(element.xywh);
+    const markers = {
+        'data-labre-id': element.id,
+        'data-labre-type': element.type ?? element.flavour ?? '',
+        'data-labre-xywh': JSON.stringify([
+            own.x - bound.x,
+            own.y - bound.y,
+            own.w,
+            own.h,
+        ]),
+    };
+    if (element.role)
+        markers['data-labre-role'] = element.role;
+    if (element.source?.id)
+        markers['data-labre-source'] = element.source.id;
+    if (element.target?.id)
+        markers['data-labre-target'] = element.target.id;
+    if (element.group?.id)
+        markers['data-labre-group'] = element.group.id;
+    return markers;
+}

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

@@ -9,6 +9,14 @@ export interface SvgContext {
     canvas: HTMLCanvasElement;
     /** The finished document, with `viewBox`, `width`/`height` in px and `xmlns`. */
     serialize(): string;
+    /** Stamps the root `<svg>` with the marker version (ADR 0032 §6). */
+    markRoot(): void;
+    /**
+     * Runs `draw` inside a new `<g>` carrying `attributes`, then closes it —
+     * however many groups `draw` left open (`renderBoundTo` restores one more
+     * time than it saves), so the next element starts beside this one.
+     */
+    markedGroup(attributes: Record<string, string>, draw: () => void): void;
 }
 /** Marks a {@link RecordingPath2D} and carries what it recorded. */
 declare const RECORDED_D: unique symbol;
@@ -46,4 +54,10 @@ export declare function readLineDash(lineDash: unknown): number[];
  * handed to {@link CanvasRenderer.renderBoundTo}.
  */
 export declare function createSvgContext(width: number, height: number): SvgContext;
+/**
+ * The marker version an export writes on its root (`data-labre-svg`), and the
+ * one a reader of it must know (ADR 0032 §6). Bumped only when the meaning of
+ * a marker changes; adding one is not a new version.
+ */
+export declare const BOARD_SVG_MARKER_VERSION = "1";
 export {};

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

@@ -1,3 +1,4 @@
+import { parseCssColor } from '../../../affine-shared/adapters/index.js';
 import { Context } from 'svgcanvas/dist/svgcanvas.esm.js';
 const PATH_OPS = ['fill', 'stroke', 'clip'];
 /** Marks a {@link RecordingPath2D} and carries what it recorded. */
@@ -203,6 +204,63 @@ export function readLineDash(lineDash) {
         return [];
     return lineDash.split(',').map(Number);
 }
+/**
+ * A colour with alpha, rewritten as the comma `rgba()` svgcanvas recognises;
+ * any other value comes back unchanged.
+ *
+ * svgcanvas splits only a value containing `rgba` into `rgb()` plus an
+ * `-opacity` attribute and writes everything else verbatim, so an 8-digit hex
+ * (`AREA_FILL`, `PIPELINE_FILL`, the DDD zones) or `transparent` reached the
+ * file as-is. Neither is an SVG 1.1 paint, and an importer that sticks to 1.1
+ * (PowerPoint's) replaces it with its own theme colour. The alpha is fixed to
+ * six decimals because svgcanvas' parser reads no exponent (`1e-7`).
+ */
+function toSvgColor(value) {
+    const parsed = parseCssColor(value);
+    if (!parsed || parsed.alpha === 1)
+        return value;
+    const { r, g, b, alpha } = parsed;
+    return `rgba(${r}, ${g}, ${b}, ${Number(alpha.toFixed(6))})`;
+}
+/**
+ * {@link toSvgColor} for a `fill` or `stroke`, where a fully transparent colour
+ * is `none`: the one invisible paint every SVG reader honours. svgcanvas births
+ * every node with `fill="none" stroke="none"` and skips a stroke equal to that
+ * default, so an invisible second pass leaves an earlier paint in place — as
+ * painting it on a canvas would.
+ */
+function toSvgPaint(value) {
+    if (typeof value !== 'string')
+        return value;
+    return parseCssColor(value)?.alpha === 0 ? 'none' : toSvgColor(value);
+}
+/**
+ * Routes every `fillStyle` / `strokeStyle` write — including the ones
+ * svgcanvas' own `restore()` makes — and every gradient stop through the
+ * converters above. Gradients and patterns pass through untouched.
+ */
+function installStaticPaint(context) {
+    for (const key of ['fillStyle', 'strokeStyle']) {
+        let current = toSvgPaint(context[key]);
+        Object.defineProperty(context, key, {
+            configurable: true,
+            enumerable: true,
+            get: () => current,
+            set: (value) => {
+                current = toSvgPaint(value);
+            },
+        });
+    }
+    for (const key of ['createLinearGradient', 'createRadialGradient']) {
+        const create = context[key];
+        context[key] = (...args) => {
+            const gradient = create.apply(context, args);
+            const addColorStop = gradient.addColorStop;
+            gradient.addColorStop = (offset, color) => addColorStop.call(gradient, offset, toSvgColor(color));
+            return gradient;
+        };
+    }
+}
 /** Adds `viewBox` / `xmlns` / px units to the root `<svg>` if they are missing. */
 function finishSvg(svg, width, height) {
     return (svg
@@ -248,10 +306,33 @@ export function createSvgContext(width, height) {
     // 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);
+    const internals = context;
+    installPathOps(internals);
+    installStaticPaint(context);
     return {
         ctx,
         canvas: ctx.canvas,
         serialize: () => finishSvg(context.getSerializedSvg(true), width, height),
+        markRoot: () => internals
+            .getSvg()
+            .setAttribute('data-labre-svg', BOARD_SVG_MARKER_VERSION),
+        markedGroup: (attributes, draw) => {
+            const depth = internals.__groupStack.length;
+            // svgcanvas' `save()` IS a new `<g>`, and it becomes the current node.
+            internals.save();
+            const group = internals.__currentElement;
+            for (const [name, value] of Object.entries(attributes)) {
+                group.setAttribute(name, value);
+            }
+            draw();
+            while (internals.__groupStack.length > depth)
+                internals.restore();
+        },
     };
 }
+/**
+ * The marker version an export writes on its root (`data-labre-svg`), and the
+ * one a reader of it must know (ADR 0032 §6). Bumped only when the meaning of
+ * a marker changes; adding one is not a new version.
+ */
+export const BOARD_SVG_MARKER_VERSION = '1';

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

@@ -1,6 +1,6 @@
-import { type ToolbarContext } from '../../../affine-shared/services/index.js';
+import { type ToolbarAction, type ToolbarContext } from '../../../affine-shared/services/index.js';
 export declare const exportSvgToolbarConfig: {
-    readonly actions: [import("../../../affine-shared/services/index.js").ToolbarActionGenerator];
+    readonly actions: [ToolbarAction];
     readonly when: (ctx: ToolbarContext) => boolean;
 };
 /**

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

@@ -1,7 +1,11 @@
+import { menu, popMenu, popupTargetFromElement, } from '../../../affine-components/context-menu/index.js';
 import { FrameworkBackgroundElementModel } from '../../../affine-model/index.js';
-import { commandMoreAction, ToolbarModuleExtension, toolbarModuleKey, } from '../../../affine-shared/services/index.js';
-import { BlockFlavourIdentifier } from '../../../std/index.js';
+import { ActionPlacement, ToolbarModuleExtension, toolbarModuleKey, translateKey, } from '../../../affine-shared/services/index.js';
+import { BlockFlavourIdentifier, getRegisteredCommands, runCommand, } from '../../../std/index.js';
+import { signal } from '@preact/signals-core';
 import { html } from 'lit';
+import { DEFAULT_BOARD_SVG_EXPORT_OPTIONS, } from './parts.js';
+import { EXPORT_SVG_CONFIRM, EXPORT_SVG_OPTION_FRAMEWORK, EXPORT_SVG_OPTION_SHAPES, EXPORT_SVG_OPTION_TEXTS, } from './translations.js';
 /**
  * A sheet with an arrow leaving it: the board, on its way out of the editor.
  *
@@ -27,15 +31,113 @@ const ExportSvgIcon = html `<svg
 const EXPORT_SVG_COMMAND_ID = 'export.svg';
 const EXPORT_SVG_LABEL_KEY = 'com.labre.command.export.svg';
 const EXPORT_SVG_LABEL_FALLBACK = 'Export SVG';
+// `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.
+const EXPORT_SVG_ACTION_ID = 'z.z-export-svg';
+/** The same `source` the row's own entries report (`commandMoreAction`). */
+const INVOCATION = {
+    surface: 'contextual-toolbar',
+    source: 'toolbar:general',
+};
+const findCommand = (std) => getRegisteredCommands(std).find(command => command.id === EXPORT_SVG_COMMAND_ID);
+/**
+ * The reader's last choice, per editor and for the session only: it is a
+ * habit of the person exporting, not a property of the document, so it is
+ * neither stored in the document nor in the browser. Per editor rather than
+ * per module so two editors on one page do not answer for each other.
+ */
+const lastChoice = new WeakMap();
+const SWITCHES = [
+    ['framework', EXPORT_SVG_OPTION_FRAMEWORK],
+    ['shapes', EXPORT_SVG_OPTION_SHAPES],
+    ['texts', EXPORT_SVG_OPTION_TEXTS],
+];
+/**
+ * The options menu: three switches and Export, anchored on the "⋮" whose menu
+ * it replaces. Built from the library's menu primitives (`menu.toggleSwitch`,
+ * as the HTML embed's settings do) rather than a modal of its own.
+ *
+ * The choice lives in a signal read through `menu.dynamic`, so a row redrawn
+ * after a flip says the CURRENT value: `toggleSwitch` hands its row click the
+ * `on` it was built with, and a static `on` would undo a flip when the reader
+ * then clicked the row's words.
+ */
+function openExportSvgOptions(std, command, item) {
+    const more = item.closest('editor-menu-button');
+    more?.hide();
+    const choice = signal({
+        ...(lastChoice.get(std) ?? DEFAULT_BOARD_SVG_EXPORT_OPTIONS),
+    });
+    popMenu(popupTargetFromElement(more ?? item), {
+        options: {
+            items: [
+                menu.group({
+                    items: [
+                        menu.dynamic(() => SWITCHES.map(([part, wording]) => menu.toggleSwitch({
+                            name: translateKey(std, ...wording),
+                            on: choice.value[part],
+                            onChange: on => {
+                                choice.value = { ...choice.peek(), [part]: on };
+                            },
+                            testId: `export-svg-option-${part}`,
+                        }))),
+                    ],
+                }),
+                menu.group({
+                    items: [
+                        menu.action({
+                            name: translateKey(std, ...EXPORT_SVG_CONFIRM),
+                            prefix: ExportSvgIcon,
+                            testId: 'export-svg-confirm',
+                            select: () => {
+                                const options = { ...choice.peek() };
+                                lastChoice.set(std, options);
+                                runCommand(std, command, INVOCATION, options);
+                            },
+                        }),
+                    ],
+                }),
+            ],
+        },
+    });
+}
+/**
+ * The "⋮" entry. It invokes the registered command like `commandMoreAction`
+ * does — one behaviour, one availability rule, one usage record per export —
+ * but asks for the options first, so it draws its own line: a menu line's
+ * `run` is handed no element to anchor a popup on.
+ */
+const exportSvgMoreAction = {
+    id: EXPORT_SVG_ACTION_ID,
+    placement: ActionPlacement.More,
+    when: (ctx) => {
+        const command = findCommand(ctx.std);
+        return command !== undefined && (command.when?.(ctx.std) ?? true);
+    },
+    content: (ctx) => {
+        const label = translateKey(ctx.std, EXPORT_SVG_LABEL_KEY, EXPORT_SVG_LABEL_FALLBACK);
+        return html `
+      <editor-menu-action
+        data-testid="z-export-svg"
+        data-toolbar-action-id=${EXPORT_SVG_ACTION_ID}
+        aria-label=${label}
+        @click=${(event) => {
+            const command = findCommand(ctx.std);
+            if (!command)
+                return;
+            openExportSvgOptions(ctx.std, command, event.currentTarget);
+        }}
+      >
+        ${ExportSvgIcon}
+        <span class="label">${label}</span>
+      </editor-menu-action>
+    `;
+    },
+};
 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),
-    ],
+    actions: [exportSvgMoreAction],
     // 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

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

@@ -0,0 +1,13 @@
+import type { ChromeWording } from '../../../affine-shared/services/index.js';
+/**
+ * The words of the "Export SVG" options menu (ADR 0025, amendment of
+ * 2026-10-04), one switch per part of the picture, and the one sentence said
+ * when the switches leave nothing to draw. The command's own label and
+ * description are declared on its descriptor.
+ */
+export declare const EXPORT_SVG_OPTION_FRAMEWORK: ChromeWording;
+export declare const EXPORT_SVG_OPTION_SHAPES: ChromeWording;
+export declare const EXPORT_SVG_OPTION_TEXTS: ChromeWording;
+export declare const EXPORT_SVG_CONFIRM: ChromeWording;
+export declare const EXPORT_SVG_NOTHING_TO_EXPORT: ChromeWording;
+export declare const EXPORT_SVG_WORDINGS: readonly ChromeWording[];

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

@@ -0,0 +1,33 @@
+/**
+ * The words of the "Export SVG" options menu (ADR 0025, amendment of
+ * 2026-10-04), one switch per part of the picture, and the one sentence said
+ * when the switches leave nothing to draw. The command's own label and
+ * description are declared on its descriptor.
+ */
+export const EXPORT_SVG_OPTION_FRAMEWORK = [
+    'com.labre.export.svg.option.framework',
+    'Framework elements',
+];
+export const EXPORT_SVG_OPTION_SHAPES = [
+    'com.labre.export.svg.option.shapes',
+    'Other shapes and strokes',
+];
+export const EXPORT_SVG_OPTION_TEXTS = [
+    'com.labre.export.svg.option.texts',
+    'Other texts',
+];
+export const EXPORT_SVG_CONFIRM = [
+    'com.labre.export.svg.confirm',
+    'Export',
+];
+export const EXPORT_SVG_NOTHING_TO_EXPORT = [
+    'com.labre.export.svg.nothing',
+    'Nothing to export: the options leave nothing of this board to draw.',
+];
+export const EXPORT_SVG_WORDINGS = [
+    EXPORT_SVG_OPTION_FRAMEWORK,
+    EXPORT_SVG_OPTION_SHAPES,
+    EXPORT_SVG_OPTION_TEXTS,
+    EXPORT_SVG_CONFIRM,
+    EXPORT_SVG_NOTHING_TO_EXPORT,
+];

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

@@ -1,4 +1,5 @@
 export * from './audit.js';
+export * from './canvas-grid/index.js';
 export * from './clipboard-config.js';
 export * from './crud-extension.js';
 export * from './dom-element-renderer.js';
@@ -20,11 +21,13 @@ export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
 export * from './record-action.js';
+export * from './selection-pane/index.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 './user-layers/index.js';
 export * from './validation.js';
 export * from './validation-toolbar.js';
 export * from './violation-detail-widget.js';

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

@@ -1,4 +1,5 @@
 export * from './audit.js';
+export * from './canvas-grid/index.js';
 export * from './clipboard-config.js';
 export * from './crud-extension.js';
 export * from './dom-element-renderer.js';
@@ -20,11 +21,13 @@ export * from './reading.js';
 export * from './reading-toolbar.js';
 export * from './reading-widget.js';
 export * from './record-action.js';
+export * from './selection-pane/index.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 './user-layers/index.js';
 export * from './validation.js';
 export * from './validation-toolbar.js';
 export * from './violation-detail-widget.js';

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

@@ -130,13 +130,20 @@ export declare class ReadingProposalWidget extends EditorAnchoredPanel {
      */
     private _renderValueFlow;
     /**
-     * Where the subject sits along the frame's phase axis.
+     * The zone of the frame the subject sits in — Wardley's evolution phase, a
+     * Core Domain Chart's quadrant, a BPMN lane — under the framework's own
+     * heading (`frame.label`), or the engine's default for a profile that names
+     * none (`readingFrameWording`).
      *
-     * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
-     * frame. The empty state below is about a component that could have been on a
-     * map and is not; telling the author of a BPMN task that it is "not on a
-     * framework background" would be answering a question their notation never
-     * asks.
+     * Absent ENTIRELY — not "no zone to read" — for a framework that declares no
+     * frame. The empty state below is about an artefact that could have been on
+     * a frame and is not, in the framework's own words (`frame.none`) or the
+     * default ones.
+     *
+     * The zone is named the way the board names it: the user's words when they
+     * wrote some (a renamed quadrant, a lane's name), the vocabulary otherwise,
+     * and "Unnamed" for a zone the board paints but never writes on — never the
+     * zone's id, which is not a word anyone drew.
      */
     private _renderPhase;
     private _renderNaming;

package/dist/_pkgs/affine-block-surface/extensions/reading-widget.js

@@ -40,7 +40,7 @@ import { css, html, nothing } from 'lit';
 import { state } from 'lit/decorators.js';
 import { literal, unsafeStatic } from 'lit/static-html.js';
 import { EditorAnchoredPanel, editorAnchoredPanelStyles, } from './editor-anchored-panel.js';
-import { PivotRecordPickerProvider, ReadingManager, readingRelationDefs, readRecord, readValueFlows, } from './reading.js';
+import { PivotRecordPickerProvider, ReadingManager, readingFrameWording, readingRelationDefs, readRecord, readValueFlows, } from './reading.js';
 export const READING_PROPOSAL_WIDGET = 'affine-reading-proposal-widget';
 /** The two commands the confirmations drive. Spelled once. */
 const TAG_SET_ID = 'tag.set';
@@ -514,21 +514,37 @@ let ReadingProposalWidget = (() => {
           </div>`)}`);
         }
         /**
-         * Where the subject sits along the frame's phase axis.
+         * The zone of the frame the subject sits in — Wardley's evolution phase, a
+         * Core Domain Chart's quadrant, a BPMN lane — under the framework's own
+         * heading (`frame.label`), or the engine's default for a profile that names
+         * none (`readingFrameWording`).
          *
-         * Absent ENTIRELY — not "no phase to read" — for a framework that declares no
-         * frame. The empty state below is about a component that could have been on a
-         * map and is not; telling the author of a BPMN task that it is "not on a
-         * framework background" would be answering a question their notation never
-         * asks.
+         * Absent ENTIRELY — not "no zone to read" — for a framework that declares no
+         * frame. The empty state below is about an artefact that could have been on
+         * a frame and is not, in the framework's own words (`frame.none`) or the
+         * default ones.
+         *
+         * The zone is named the way the board names it: the user's words when they
+         * wrote some (a renamed quadrant, a lane's name), the vocabulary otherwise,
+         * and "Unnamed" for a zone the board paints but never writes on — never the
+         * zone's id, which is not a word anyone drew.
          */
         _renderPhase(reading, profile) {
             if (!profile.frame)
                 return nothing;
+            const { label, none } = readingFrameWording(profile.frame);
             const { phase } = reading;
-            return this._field('reading-phase', translateKey(this.std, 'com.labre.reading.field.phase', 'Evolution phase'), phase
+            const words = !phase
+                ? ''
+                : phase.name !== undefined
+                    ? phase.name.trim()
+                    : phase.labelKey !== undefined
+                        ? translateKey(this.std, phase.labelKey, phase.labelFallback ?? phase.labelKey)
+                        : (phase.labelFallback ?? '');
+            return this._field('reading-phase', translateKey(this.std, label.labelKey, label.labelFallback), phase
                 ? html `<div class="reading-value" data-zone-id=${phase.zoneId}>
-              ${translateKey(this.std, phase.labelKey ?? phase.zoneId, phase.labelFallback ?? phase.zoneId)}
+              ${words ||
+                    translateKey(this.std, 'com.labre.reading.zone.unnamed', 'Unnamed')}
             </div>
             ${phase.inTransitionBand
                     ? html `<div class="reading-note" data-testid="reading-phase-band">
@@ -537,7 +553,7 @@ let ReadingProposalWidget = (() => {
                 </div>`
                     : nothing}`
                 : html `<div class="reading-empty" data-testid="reading-phase-none">
-            ${translateKey(this.std, 'com.labre.reading.phase.none', 'Not on a framework background — no phase to read.')}
+            ${translateKey(this.std, none.labelKey, none.labelFallback)}
           </div>`);
         }
         _renderNaming(reading) {