@formicoidea/labre-core 0.43.1 → 0.45.0

package/dist/_pkgs/affine-shared/services/telemetry-service/lifecycle.d.ts

@@ -320,3 +320,72 @@ export interface DocumentDamagedEvent extends TelemetryEvent {
 export type DocumentHealthEvents = {
     DocumentDamaged: DocumentDamagedEvent;
 };
+/**
+ * The selection pane was opened (ADR 0031 §14).
+ *
+ * Worth measuring for the reason any optional surface is: a pane nobody opens
+ * is chrome the toolbar pays a slot for. `source` is how the user got there —
+ * the edgeless toolbar's button, the palette (or the agent, which invokes by
+ * name as the palette does), or a bound chord. Opening only: closing reports
+ * nothing, and neither does a toggle that closes the pane.
+ *
+ * No ids at all: the event is about the pane, never about what it lists.
+ */
+export interface SelectionPaneOpenedEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    source: 'toolbar' | 'palette' | 'shortcut';
+}
+/**
+ * Something on the canvas was hidden or shown (ADR 0031 §14).
+ *
+ * `scope: 'local'` is the viewer's own hide, which writes nothing to the
+ * document; `'everyone'` is "hide for everyone", which stores
+ * `hiddenForEveryone` on each element and syncs it.
+ * `target: 'layer'` is reserved for the layers stage. `count` is how many
+ * elements the ONE gesture actually changed — a gesture that changes nothing
+ * reports nothing.
+ *
+ * Counts only: never an element id, a type, a group title or any text.
+ */
+export interface CanvasVisibilityChangedEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    target: 'element' | 'layer';
+    scope: 'local' | 'everyone';
+    hidden: boolean;
+    count: number;
+}
+/**
+ * The canvas grid was turned on or off (ADR 0031 §14).
+ *
+ * `scope: 'local'` is the viewer's own toggle, which writes nothing to the
+ * document; `'everyone'` is "Save for everyone", which stores the grid on the
+ * document. `visible` is the state after the gesture. A save that changes
+ * nothing in the document reports nothing.
+ */
+export interface CanvasGridToggledEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    scope: 'local' | 'everyone';
+    visible: boolean;
+}
+/**
+ * The user layers changed (ADR 0031 §14).
+ *
+ * `layerCount` is how many layers the surface holds AFTER the gesture;
+ * `memberCount` is how many models the gesture moved (for `move-elements`)
+ * or deleted with the layer (for `delete`). A gesture that changes nothing
+ * reports nothing.
+ *
+ * Counts only: never a layer name, a layer id or any element text.
+ */
+export interface CanvasLayerChangedEvent extends TelemetryEvent {
+    page?: 'whiteboard editor';
+    action: 'create' | 'rename' | 'reorder' | 'delete' | 'move-elements';
+    layerCount: number;
+    memberCount?: number;
+}
+export type CanvasPaneEvents = {
+    SelectionPaneOpened: SelectionPaneOpenedEvent;
+    CanvasVisibilityChanged: CanvasVisibilityChangedEvent;
+    CanvasGridToggled: CanvasGridToggledEvent;
+    CanvasLayerChanged: CanvasLayerChangedEvent;
+};

package/dist/_pkgs/affine-shared/services/telemetry-service/telemetry-service.d.ts

@@ -2,12 +2,12 @@ import type { ExtensionType } from '../../../store/index.js';
 import type { CitationEvents } from './citation.js';
 import type { CodeBlockEvents } from './code-block.js';
 import type { OutDatabaseAllEvents } from './database.js';
-import type { AuditEvents, BlockLifecycleEvents, DocumentHealthEvents, FrameworkDiagramEvents, ValidationEvents } from './lifecycle.js';
+import type { AuditEvents, BlockLifecycleEvents, CanvasPaneEvents, DocumentHealthEvents, FrameworkDiagramEvents, ValidationEvents } from './lifecycle.js';
 import type { LinkToolbarEvents } from './link.js';
 import type { NoteEvents } from './note.js';
 import type { SlashMenuEvents } from './slash-menu.js';
 import type { AttachmentReloadedEvent, AttachmentReloadedEventInToolbar, AttachmentUpgradedEvent, AttachmentUploadedEvent, BlockCreationEvent, DocCreatedEvent, EdgelessToolPickedEvent, ElementCreationEvent, ElementLockEvent, ElementUpdatedEvent, LatexEvent, LinkedDocCreatedEvent, LinkEvent, MindMapCollapseEvent, TelemetryEvent } from './types.js';
-export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & ValidationEvents & AuditEvents & DocumentHealthEvents & {
+export type TelemetryEventMap = OutDatabaseAllEvents & LinkToolbarEvents & SlashMenuEvents & CodeBlockEvents & NoteEvents & CitationEvents & BlockLifecycleEvents & FrameworkDiagramEvents & ValidationEvents & AuditEvents & CanvasPaneEvents & DocumentHealthEvents & {
     DocCreated: DocCreatedEvent;
     Link: TelemetryEvent;
     LinkedDocCreated: LinkedDocCreatedEvent;

package/dist/_pkgs/affine-shared/services/translation-service/chrome.d.ts

@@ -188,6 +188,11 @@ export declare const STYLE_MENU_LABEL: ChromeWording;
 export declare const TEXT_FORMAT_BOLD: ChromeWording;
 export declare const TEXT_FORMAT_ITALIC: ChromeWording;
 export declare const TEXT_FORMAT_UNDERLINE: ChromeWording;
+/**
+ * Said by the canvas text toolbar's decoration toggles (`gfx/text`, beside
+ * {@link TEXT_FORMAT_UNDERLINE}) and by the inline format bar (ADR 0030).
+ */
+export declare const TEXT_FORMAT_OVERLINE: ChromeWording;
 export declare const TEXT_FORMAT_STRIKETHROUGH: ChromeWording;
 /**
  * The font weights and the one non-default font style a text toolbar offers —

package/dist/_pkgs/affine-shared/services/translation-service/chrome.js

@@ -335,6 +335,14 @@ export const TEXT_FORMAT_UNDERLINE = [
     'com.labre.text-format.underline',
     'Underline',
 ];
+/**
+ * Said by the canvas text toolbar's decoration toggles (`gfx/text`, beside
+ * {@link TEXT_FORMAT_UNDERLINE}) and by the inline format bar (ADR 0030).
+ */
+export const TEXT_FORMAT_OVERLINE = [
+    'com.labre.text-format.overline',
+    'Overline',
+];
 export const TEXT_FORMAT_STRIKETHROUGH = [
     'com.labre.text-format.strikethrough',
     'Strikethrough',
@@ -1203,6 +1211,7 @@ export const CHROME_WORDINGS = [
     TEXT_FORMAT_BOLD,
     TEXT_FORMAT_ITALIC,
     TEXT_FORMAT_UNDERLINE,
+    TEXT_FORMAT_OVERLINE,
     TEXT_FORMAT_STRIKETHROUGH,
     FONT_WEIGHT_LIGHT,
     FONT_WEIGHT_REGULAR,

package/dist/_pkgs/affine-shared/styles/index.d.ts

@@ -1,5 +1,6 @@
 export { fontBaseStyle, fontSMStyle, fontXSStyle } from './font.js';
 export { reducedMotionStyle, SPRING_DURATION_MS, SPRING_EASING, springDuration, springEasing, } from './motion.js';
 export { panelBaseColorsStyle, panelBaseStyle } from './panel.js';
+export { PANEL_DRAG_THRESHOLD_PX, panelDragStarted, panelHeaderStyles, } from './panel-header.js';
 export { scrollbarStyle } from './scrollbar-style.js';
 export { affineTextStyles } from './text.js';

package/dist/_pkgs/affine-shared/styles/index.js

@@ -1,5 +1,6 @@
 export { fontBaseStyle, fontSMStyle, fontXSStyle } from './font.js';
 export { reducedMotionStyle, SPRING_DURATION_MS, SPRING_EASING, springDuration, springEasing, } from './motion.js';
 export { panelBaseColorsStyle, panelBaseStyle } from './panel.js';
+export { PANEL_DRAG_THRESHOLD_PX, panelDragStarted, panelHeaderStyles, } from './panel-header.js';
 export { scrollbarStyle } from './scrollbar-style.js';
 export { affineTextStyles } from './text.js';

package/dist/_pkgs/affine-shared/styles/panel-header.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The header of a side panel, as the frame panel draws it
+ * (`fragments/frame-panel`, `header/frame-panel-header.ts`): one 36px row,
+ * 8px side padding, no divider under it, a 14px / 500 secondary-text title
+ * and icon buttons whose glyph is secondary until hovered or active.
+ *
+ * Every side panel's header takes it from here — the frame panel, the
+ * selection pane and the artefact catalogue — so the three cannot drift
+ * apart (held by `panel-header-parity.unit.spec.ts` in `affine/all`). It lives
+ * this low because a widget may not import the frame panel: the frame panel
+ * depends on the frame block, which depends on the edgeless toolbar.
+ *
+ * A component opts in by adding the three classes to its own markup:
+ * `affine-panel-header` on the row, `affine-panel-header-title` on the title,
+ * `affine-panel-header-button` on each icon button.
+ */
+export declare const panelHeaderStyles: import("lit").CSSResult;
+/**
+ * Pointer travel, on either axis, before a press on a card or a row of a side
+ * panel becomes a drag rather than a click — the frame panel's threshold,
+ * shared with the selection pane so the two panels start a drag alike.
+ */
+export declare const PANEL_DRAG_THRESHOLD_PX = 5;
+/** Whether a press at `from` moved to `to` has travelled far enough to drag. */
+export declare function panelDragStarted(from: {
+    x: number;
+    y: number;
+}, to: {
+    x: number;
+    y: number;
+}): boolean;

package/dist/_pkgs/affine-shared/styles/panel-header.js

@@ -0,0 +1,61 @@
+import { css } from 'lit';
+import { fontSMStyle } from './font.js';
+/**
+ * The header of a side panel, as the frame panel draws it
+ * (`fragments/frame-panel`, `header/frame-panel-header.ts`): one 36px row,
+ * 8px side padding, no divider under it, a 14px / 500 secondary-text title
+ * and icon buttons whose glyph is secondary until hovered or active.
+ *
+ * Every side panel's header takes it from here — the frame panel, the
+ * selection pane and the artefact catalogue — so the three cannot drift
+ * apart (held by `panel-header-parity.unit.spec.ts` in `affine/all`). It lives
+ * this low because a widget may not import the frame panel: the frame panel
+ * depends on the frame block, which depends on the edgeless toolbar.
+ *
+ * A component opts in by adding the three classes to its own markup:
+ * `affine-panel-header` on the row, `affine-panel-header-title` on the title,
+ * `affine-panel-header-button` on each icon button.
+ */
+export const panelHeaderStyles = css `
+  .affine-panel-header {
+    display: flex;
+    flex: none;
+    width: 100%;
+    height: 36px;
+    align-items: center;
+    justify-content: space-between;
+    gap: 8px;
+    box-sizing: border-box;
+    padding: 0 8px;
+  }
+
+  ${fontSMStyle('.affine-panel-header-title')}
+
+  .affine-panel-header-title {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--affine-text-secondary-color);
+  }
+
+  .affine-panel-header-button svg {
+    color: var(--affine-icon-secondary);
+  }
+
+  .affine-panel-header-button:hover svg,
+  .affine-panel-header-button.active svg {
+    color: var(--affine-icon-color);
+  }
+`;
+/**
+ * Pointer travel, on either axis, before a press on a card or a row of a side
+ * panel becomes a drag rather than a click — the frame panel's threshold,
+ * shared with the selection pane so the two panels start a drag alike.
+ */
+export const PANEL_DRAG_THRESHOLD_PX = 5;
+/** Whether a press at `from` moved to `to` has travelled far enough to drag. */
+export function panelDragStarted(from, to) {
+    return (Math.abs(from.x - to.x) >= PANEL_DRAG_THRESHOLD_PX ||
+        Math.abs(from.y - to.y) >= PANEL_DRAG_THRESHOLD_PX);
+}

package/dist/_pkgs/affine-shared/styles/text.js

@@ -1,11 +1,11 @@
 export function affineTextStyles(props, override) {
-    let textDecorations = '';
-    if (props.underline) {
-        textDecorations += 'underline';
-    }
-    if (props.strike) {
-        textDecorations += ' line-through';
-    }
+    const textDecorations = [
+        props.underline && 'underline',
+        props.overline && 'overline',
+        props.strike && 'line-through',
+    ]
+        .filter(Boolean)
+        .join(' ');
     let inlineCodeStyle = {};
     if (props.code) {
         inlineCodeStyle = {

package/dist/_pkgs/affine-shared/types/index.d.ts

@@ -24,6 +24,12 @@ export type AffineTextStyleAttributes = {
     bold?: true | null;
     italic?: true | null;
     underline?: true | null;
+    /**
+     * Declared at the affine level only, like `color`: the store's base
+     * attributes do not know it (ADR 0030 §5), and the editor schema is the
+     * intersection of those and every inline spec.
+     */
+    overline?: true | null;
     strike?: true | null;
     code?: true | null;
     color?: string | null;

package/dist/_pkgs/affine-shared/utils/canvas-export-colors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Turns one colour the browser understands into `rgb()` / `rgba()`.
+ */
+export type ResolveLegacyColor = (color: string) => string;
+/**
+ * `value` with every modern colour function in it replaced by what `resolve`
+ * makes of it — the whole of `oklch(0.7 0.1 200)`, or each colour of a
+ * `box-shadow` list. A value with none comes back as the same string. Also
+ * what the `backgroundColor` option of html2canvas goes through.
+ */
+export declare function toLegacyColors(value: string, resolve?: ResolveLegacyColor): string;
+/**
+ * Rewrites, inline on the html2canvas CLONE, every computed colour html2canvas
+ * would choke on, so a host theme in `oklch()` (or the library's own
+ * `color-mix()`) cannot abort a PNG/PDF export or a "copy as image". Call it
+ * first in every `onclone`.
+ *
+ * html2canvas parses the computed style of the captured subtree AND of the
+ * clone's `<html>` and `<body>` (their background), so those two are covered
+ * too; shadow roots are already flattened into the clone by then. The resolved
+ * value is written over whatever produced it — a CSS variable, a stylesheet
+ * rule — as an `!important` inline declaration, which is what the computed
+ * style then reports. Every value is read before any is written, so the
+ * cascade is recomputed once rather than once per node.
+ */
+export declare function normalizeCanvasExportColors(documentClone: Document, subtree: Element, resolve?: ResolveLegacyColor): void;

package/dist/_pkgs/affine-shared/utils/canvas-export-colors.js

@@ -0,0 +1,127 @@
+/**
+ * The colour functions html2canvas 1.4.1 cannot parse. Its parser knows hex,
+ * `rgb[a]()`, `hsl[a]()` and keywords and THROWS on anything else, aborting
+ * the whole export. `color(` is what Chrome computes `color-mix(in srgb, …)`
+ * to; `color-mix` and `light-dark` are here for a computed value that keeps
+ * them. `color-mix` precedes `color` so the longer name wins.
+ */
+const MODERN_COLOR_FUNCTION = /\b(?:oklch|oklab|lch|lab|hwb|color-mix|color|light-dark)\(/gi;
+/**
+ * Every computed property html2canvas reads a colour from. Shorthands are
+ * absent on purpose: html2canvas reads the longhands.
+ */
+const COLOR_PROPERTIES = [
+    'color',
+    'background-color',
+    'background-image',
+    'border-top-color',
+    'border-right-color',
+    'border-bottom-color',
+    'border-left-color',
+    'outline-color',
+    'text-decoration-color',
+    '-webkit-text-stroke-color',
+    'text-shadow',
+    'box-shadow',
+    'caret-color',
+    'fill',
+    'stroke',
+];
+let probe;
+const resolved = new Map();
+/**
+ * The browser's own reading of a colour, through a 1×1 canvas: paint it, read
+ * the pixel back. Reading `fillStyle` back is not enough — recent engines keep
+ * the modern syntax there. Cached per string, since a theme repeats a handful
+ * of colours across every node. Where no 2D context exists the colour comes
+ * back unchanged: there is nothing to rasterise with either.
+ */
+const resolveColorThroughCanvas = color => {
+    const cached = resolved.get(color);
+    if (cached !== undefined)
+        return cached;
+    probe ??= Object.assign(document.createElement('canvas'), {
+        width: 1,
+        height: 1,
+    }).getContext('2d', { willReadFrequently: true });
+    if (!probe)
+        return color;
+    probe.clearRect(0, 0, 1, 1);
+    probe.fillStyle = color;
+    probe.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = probe.getImageData(0, 0, 1, 1).data;
+    const legacy = a === 255
+        ? `rgb(${r}, ${g}, ${b})`
+        : `rgba(${r}, ${g}, ${b}, ${Number((a / 255).toFixed(3))})`;
+    resolved.set(color, legacy);
+    return legacy;
+};
+/**
+ * `value` with every modern colour function in it replaced by what `resolve`
+ * makes of it — the whole of `oklch(0.7 0.1 200)`, or each colour of a
+ * `box-shadow` list. A value with none comes back as the same string. Also
+ * what the `backgroundColor` option of html2canvas goes through.
+ */
+export function toLegacyColors(value, resolve = resolveColorThroughCanvas) {
+    MODERN_COLOR_FUNCTION.lastIndex = 0;
+    let match = MODERN_COLOR_FUNCTION.exec(value);
+    if (!match)
+        return value;
+    let out = '';
+    let from = 0;
+    while (match) {
+        // Balanced parentheses: `color-mix()` nests whole colours.
+        let end = match.index + match[0].length;
+        for (let depth = 1; end < value.length && depth > 0; end++) {
+            if (value[end] === '(')
+                depth++;
+            else if (value[end] === ')')
+                depth--;
+        }
+        out +=
+            value.slice(from, match.index) + resolve(value.slice(match.index, end));
+        from = end;
+        MODERN_COLOR_FUNCTION.lastIndex = end;
+        match = MODERN_COLOR_FUNCTION.exec(value);
+    }
+    return out + value.slice(from);
+}
+/**
+ * Rewrites, inline on the html2canvas CLONE, every computed colour html2canvas
+ * would choke on, so a host theme in `oklch()` (or the library's own
+ * `color-mix()`) cannot abort a PNG/PDF export or a "copy as image". Call it
+ * first in every `onclone`.
+ *
+ * html2canvas parses the computed style of the captured subtree AND of the
+ * clone's `<html>` and `<body>` (their background), so those two are covered
+ * too; shadow roots are already flattened into the clone by then. The resolved
+ * value is written over whatever produced it — a CSS variable, a stylesheet
+ * rule — as an `!important` inline declaration, which is what the computed
+ * style then reports. Every value is read before any is written, so the
+ * cascade is recomputed once rather than once per node.
+ */
+export function normalizeCanvasExportColors(documentClone, subtree, resolve = resolveColorThroughCanvas) {
+    const view = documentClone.defaultView ?? window;
+    const nodes = new Set([
+        documentClone.documentElement,
+        documentClone.body,
+        subtree,
+        ...subtree.querySelectorAll('*'),
+    ]);
+    const writes = [];
+    for (const node of nodes) {
+        const style = node?.style;
+        if (!node || !style)
+            continue;
+        const computed = view.getComputedStyle(node);
+        for (const property of COLOR_PROPERTIES) {
+            const value = computed.getPropertyValue(property);
+            const legacy = toLegacyColors(value, resolve);
+            if (legacy !== value)
+                writes.push([style, property, legacy]);
+        }
+    }
+    for (const [style, property, legacy] of writes) {
+        style.setProperty(property, legacy, 'important');
+    }
+}

package/dist/_pkgs/affine-shared/utils/file/filesys.d.ts

@@ -55,17 +55,14 @@ export declare function getImageFilesFromLocal(): Promise<File[]>;
 /**
  * A name a file system will accept, minus the extension.
  *
- * The sanitiser the framework exports each wrote for themselves
- * (`wardleySafeFilename`, `c4SafeFilename`, BPMN's) — same five steps, same
- * 120-character ceiling — lifted here for the callers that belong to no
- * framework at all. The generic SVG export (ADR 0025) is the first of them: it
- * writes a file for ELEVEN kinds of board, so it has no framework's fallback to
- * borrow and takes one as a parameter instead.
- *
- * The three framework copies stay where they are: each is part of an
- * interchange capability with its own format id and its own declared fallback
- * (`map`, `board`, `process`), and rewriting them to call this one would touch
- * three exported APIs for no behaviour change.
+ * Every file the library writes is named through it: the generic SVG export
+ * (ADR 0025), which writes a file for every kind of board and so takes its
+ * fallback as a parameter, and the framework interchanges, whose exported
+ * sanitisers (`wardleySafeFilename`, `c4SafeFilename`, `bpmnSafeFilename`,
+ * `umlSafeFilename`) keep their names and signatures and only supply their own
+ * fallback word. They were verbatim copies of this rule;
+ * `safe-filename-parity.unit.spec.ts` in `packages/affine/all` holds every one
+ * to it, because what a downloaded file is called is visible behaviour.
  */
 export declare function safeFilename(raw: string | undefined, fallback: string): string;
 export declare function downloadBlob(blob: Blob, name: string): void;

package/dist/_pkgs/affine-shared/utils/file/filesys.js

@@ -191,17 +191,14 @@ export async function getImageFilesFromLocal() {
 /**
  * A name a file system will accept, minus the extension.
  *
- * The sanitiser the framework exports each wrote for themselves
- * (`wardleySafeFilename`, `c4SafeFilename`, BPMN's) — same five steps, same
- * 120-character ceiling — lifted here for the callers that belong to no
- * framework at all. The generic SVG export (ADR 0025) is the first of them: it
- * writes a file for ELEVEN kinds of board, so it has no framework's fallback to
- * borrow and takes one as a parameter instead.
- *
- * The three framework copies stay where they are: each is part of an
- * interchange capability with its own format id and its own declared fallback
- * (`map`, `board`, `process`), and rewriting them to call this one would touch
- * three exported APIs for no behaviour change.
+ * Every file the library writes is named through it: the generic SVG export
+ * (ADR 0025), which writes a file for every kind of board and so takes its
+ * fallback as a parameter, and the framework interchanges, whose exported
+ * sanitisers (`wardleySafeFilename`, `c4SafeFilename`, `bpmnSafeFilename`,
+ * `umlSafeFilename`) keep their names and signatures and only supply their own
+ * fallback word. They were verbatim copies of this rule;
+ * `safe-filename-parity.unit.spec.ts` in `packages/affine/all` holds every one
+ * to it, because what a downloaded file is called is visible behaviour.
  */
 export function safeFilename(raw, fallback) {
     const safe = (raw ?? '')

package/dist/_pkgs/affine-shared/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from './auto-scroll.js';
 export * from './button-popper.js';
+export * from './canvas-export-colors.js';
 export * from './collapsed/index.js';
 export * from './computing.js';
 export * from './dnd/index.js';
@@ -13,6 +14,7 @@ export * from './fractional-indexing.js';
 export * from './image.js';
 export * from './insert.js';
 export * from './is-abort-error.js';
+export * from './label-mode.js';
 export * from './link-preview-refresh.js';
 export * from './math.js';
 export * from './model/index.js';

package/dist/_pkgs/affine-shared/utils/index.js

@@ -1,5 +1,6 @@
 export * from './auto-scroll.js';
 export * from './button-popper.js';
+export * from './canvas-export-colors.js';
 export * from './collapsed/index.js';
 export * from './computing.js';
 export * from './dnd/index.js';
@@ -13,6 +14,7 @@ export * from './fractional-indexing.js';
 export * from './image.js';
 export * from './insert.js';
 export * from './is-abort-error.js';
+export * from './label-mode.js';
 export * from './link-preview-refresh.js';
 export * from './math.js';
 export * from './model/index.js';

package/dist/_pkgs/affine-shared/utils/label-mode.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Whether a catalogue symbol can carry its name INSIDE it, or the name must
+ * GRAVITATE around it (rule R38, `docs/add-a-framework/02-framework-rules.md`;
+ * ADR 0029).
+ *
+ * The rule has one criterion, the symbol's size: a normal-size text — 18 model
+ * units, the size Wardley's prominent labels and BPMN's inner text use — of two
+ * five-letter words must fit legibly inside the shape at its canonical creation
+ * size, without enlarging it. If it does not, the label is a free text element
+ * grouped with the symbol (R16) instead of the shape's own `text`.
+ *
+ * The test is arithmetic on the preset, so a framework's spec can assert its
+ * label mode for every kind without a canvas:
+ *
+ *  - the inner box is the shape minus the native shape text insets
+ *    (`SHAPE_TEXT_VERTICAL_PADDING` = 10, `SHAPE_TEXT_PADDING` = 20 in
+ *    `@labre/affine-model`, the defaults below);
+ *  - a non-rectangular silhouette only offers the rectangle inscribed in it:
+ *    ≈ 1/√2 of each side for an ellipse (0.7), half of each side for a diamond;
+ *  - the probe is "Hello World" (two five-letter words and a space), set on one
+ *    line or broken into two lines of five letters; it fits if either layout
+ *    fits.
+ *
+ * Average advance 0.5 em: Inter's advances for the probe itself ("Hello World"
+ * ≈ 5.4 em) average 0.49 em, which is what decides a 140-wide annotation at 18
+ * units — a generic 0.55 em prose average would reject a box the probe
+ * visibly fits. Line height 1.2 em, the renderer's default for single-spaced
+ * canvas text.
+ *
+ * ponytail: no real font metrics — a fixed per-glyph average and a fixed line
+ * height, so a shape within a few units of the threshold may be judged wrongly
+ * for a font other than Inter. The upgrade is to measure the probe with the
+ * shape renderer's `wrapText` / `getLineHeight` in a browser-mode spec.
+ */
+export interface InscribedLabelProbe {
+    /** Canonical creation width, model units. */
+    w: number;
+    /** Canonical creation height, model units. */
+    h: number;
+    /** Native shape type: `ellipse`, `diamond`, `rect`, or a polygon name. */
+    shapeType: string;
+    /** Reference size of the fit test, not a mandate for the label's own size. */
+    fontSize?: number;
+    /** `[vertical, horizontal]` inset, as the native shape pads its text. */
+    padding?: [number, number];
+}
+export declare const fitsInscribedLabel: ({ w, h, shapeType, fontSize, padding, }: InscribedLabelProbe) => boolean;

package/dist/_pkgs/affine-shared/utils/label-mode.js

@@ -0,0 +1,55 @@
+/**
+ * Whether a catalogue symbol can carry its name INSIDE it, or the name must
+ * GRAVITATE around it (rule R38, `docs/add-a-framework/02-framework-rules.md`;
+ * ADR 0029).
+ *
+ * The rule has one criterion, the symbol's size: a normal-size text — 18 model
+ * units, the size Wardley's prominent labels and BPMN's inner text use — of two
+ * five-letter words must fit legibly inside the shape at its canonical creation
+ * size, without enlarging it. If it does not, the label is a free text element
+ * grouped with the symbol (R16) instead of the shape's own `text`.
+ *
+ * The test is arithmetic on the preset, so a framework's spec can assert its
+ * label mode for every kind without a canvas:
+ *
+ *  - the inner box is the shape minus the native shape text insets
+ *    (`SHAPE_TEXT_VERTICAL_PADDING` = 10, `SHAPE_TEXT_PADDING` = 20 in
+ *    `@labre/affine-model`, the defaults below);
+ *  - a non-rectangular silhouette only offers the rectangle inscribed in it:
+ *    ≈ 1/√2 of each side for an ellipse (0.7), half of each side for a diamond;
+ *  - the probe is "Hello World" (two five-letter words and a space), set on one
+ *    line or broken into two lines of five letters; it fits if either layout
+ *    fits.
+ *
+ * Average advance 0.5 em: Inter's advances for the probe itself ("Hello World"
+ * ≈ 5.4 em) average 0.49 em, which is what decides a 140-wide annotation at 18
+ * units — a generic 0.55 em prose average would reject a box the probe
+ * visibly fits. Line height 1.2 em, the renderer's default for single-spaced
+ * canvas text.
+ *
+ * ponytail: no real font metrics — a fixed per-glyph average and a fixed line
+ * height, so a shape within a few units of the threshold may be judged wrongly
+ * for a font other than Inter. The upgrade is to measure the probe with the
+ * shape renderer's `wrapText` / `getLineHeight` in a browser-mode spec.
+ */
+/** The probe: two five-letter words, as in "Hello World". */
+const PROBE_WORD_LENGTH = 5;
+const PROBE_ONE_LINE_LENGTH = 2 * PROBE_WORD_LENGTH + 1;
+/** Average Inter advance over the probe, in em. */
+const AVERAGE_ADVANCE_EM = 0.5;
+const LINE_HEIGHT_EM = 1.2;
+/** Share of each side of the inner box a silhouette leaves usable. */
+const INSCRIBED_FACTOR = Object.assign(Object.create(null), { ellipse: 0.7, diamond: 0.5 });
+export const fitsInscribedLabel = ({ w, h, shapeType, fontSize = 18, padding = [10, 20], }) => {
+    const factor = INSCRIBED_FACTOR[shapeType] ?? 1;
+    const innerW = (w - 2 * padding[1]) * factor;
+    const innerH = (h - 2 * padding[0]) * factor;
+    if (innerW <= 0 || innerH <= 0)
+        return false;
+    const advance = AVERAGE_ADVANCE_EM * fontSize;
+    const lineHeight = LINE_HEIGHT_EM * fontSize;
+    const oneLine = PROBE_ONE_LINE_LENGTH * advance <= innerW && lineHeight <= innerH;
+    if (oneLine)
+        return true;
+    return PROBE_WORD_LENGTH * advance <= innerW && 2 * lineHeight <= innerH;
+};

package/dist/_pkgs/affine-shared/utils/model/merge-to-code-model.js

@@ -18,7 +18,13 @@ export function mergeToCodeModel(models) {
     })
         .filter(Boolean)
         .join('\n');
-    models.forEach(model => doc.deleteBlock(model));
+    // Add first and delete only once the code block exists: `addBlock` returns
+    // an id even when the parent rejected the flavour (a callout only takes
+    // paragraphs and lists), and deleting first lost the text (#418).
     const id = doc.addBlock('affine:code', { text: new Text(text) }, parent, index);
+    if (!doc.getModelById(id)) {
+        return null;
+    }
+    models.forEach(model => doc.deleteBlock(model));
     return id;
 }

package/dist/_pkgs/affine-shared/utils/model/transform-model.js

@@ -12,7 +12,12 @@ export function transformModel(model, flavour, props) {
     const index = parent.children.indexOf(model);
     // Sometimes the new block can not be added due to some reason, e.g. invalid schema check.
     // So we need to try to add the new block first, and if it fails, we will not delete the old block.
+    // `addBlock` returns an id even when the schema check threw (`transact`
+    // swallows it), so only `getModelById` proves the block exists (#418).
     const id = doc.addBlock(flavour, blockProps, parent, index);
+    if (!doc.getModelById(id)) {
+        return null;
+    }
     doc.deleteBlock(model, {
         deleteChildren: false,
     });