@formicoidea/labre-core 0.49.0 → 0.51.0

package/dist/_pkgs/affine-gfx-template/toolbar/template-panel.js

@@ -265,9 +265,10 @@ let EdgelessTemplatePanel = (() => {
     }
   `; }
         /**
-         * The GLOBAL half of the catalogue — `Other` and a host's `extend(...)`.
-         * Framework categories are not here: they live in the editor's DI container
-         * (`TemplateCategoryExtension`) and are read through {@link catalogue}.
+         * The GLOBAL half of the catalogue — `Other`. Framework and host
+         * categories are not here: they live in the editor's DI container
+         * (`TemplateCategoryExtension`, `FrameTemplateProvider`) and are read
+         * through {@link catalogue}.
          */
         static { this.templates = builtInTemplates; }
         /** What THIS edgeless offers: the global half plus its std's categories. */
@@ -485,10 +486,10 @@ let EdgelessTemplatePanel = (() => {
                 })}
                   ></affine-template-loading>`
                 : repeat(_templates, 
-                // The drag payload, `templateCache` and `isBeingDragged`
-                // below all key off this SAME identity — never the
-                // resolved (possibly translated) display name.
-                template => template.name, template => {
+                // The template object itself: two saved frames may share
+                // a title (`FrameTemplateProvider`), and a name key
+                // would draw one tile for both.
+                template => template, template => {
                     const preview = template.preview
                         ? template.preview.startsWith('<svg')
                             ? html `${unsafeSVG(template.preview)}`
@@ -498,8 +499,7 @@ let EdgelessTemplatePanel = (() => {
                               loading="lazy"
                             />`
                         : defaultPreview;
-                    const isBeingDragged = draggingElement &&
-                        draggingElement.data.name === template.name;
+                    const isBeingDragged = draggingElement && draggingElement.data === template;
                     // The one place that asks the host's catalogue for the
                     // WORDING above the identity — see `resolveTemplateName`.
                     const displayName = resolveTemplateName(this.edgeless.std, template);

package/dist/_pkgs/affine-gfx-template/toolbar/template-type.d.ts

@@ -70,9 +70,8 @@ export type TemplateCategory = {
      * key (`com.labre.framework.<id>`, the senior button's); a generic one
      * (`Other`) gets a key of its own. Absent for a category whose display name
      * cannot be attributed to one owner (Cynefin and Estuarine share a single
-     * `cynefin-estuarine` framework key that names neither individually) or that
-     * a host contributed through {@link TemplateManager.extend} — either way
-     * `name` is shown as is.
+     * `cynefin-estuarine` framework key that names neither individually), in
+     * which case `name` is shown as is.
      */
     nameKey?: string;
     templates: Template[] | (() => Promise<Template[]>);
@@ -83,5 +82,4 @@ export interface TemplateManager {
     search(keyword: string, category?: string): Promise<Template[]> | Template[];
     /** {@link TemplateCategory.nameKey} of the category named `name`, if any. */
     categoryLabel?(name: string): string | undefined;
-    extend?(manager: TemplateManager): void;
 }

package/dist/_pkgs/affine-gfx-template/translations.d.ts

@@ -18,6 +18,11 @@ export declare const TEMPLATE_PANEL_SEARCH_PLACEHOLDER: ChromeWording;
  * same word as {@link CATALOGUE_OTHER}, one key.
  */
 export declare const TEMPLATE_PANEL_CATEGORY_OTHER: ChromeWording;
+/**
+ * The tab of the frames a host keeps as templates (`FrameTemplateProvider`,
+ * `SAVED_FRAMES_CATEGORY`); there is no such tab without that host.
+ */
+export declare const TEMPLATE_PANEL_CATEGORY_SAVED_FRAMES: ChromeWording;
 /** The "Template" senior tool's own button name (`SeniorTool.labelKey`). */
 export declare const TEMPLATE_SENIOR_TOOL_NAME: ChromeWording;
 export declare const TEMPLATE_NAME_SWOT: ChromeWording;

package/dist/_pkgs/affine-gfx-template/translations.js

@@ -24,6 +24,14 @@ export const TEMPLATE_PANEL_SEARCH_PLACEHOLDER = [
  * same word as {@link CATALOGUE_OTHER}, one key.
  */
 export const TEMPLATE_PANEL_CATEGORY_OTHER = CATALOGUE_OTHER;
+/**
+ * The tab of the frames a host keeps as templates (`FrameTemplateProvider`,
+ * `SAVED_FRAMES_CATEGORY`); there is no such tab without that host.
+ */
+export const TEMPLATE_PANEL_CATEGORY_SAVED_FRAMES = [
+    'com.labre.template.panel.category.saved-frames',
+    'Saved frames',
+];
 /** The "Template" senior tool's own button name (`SeniorTool.labelKey`). */
 export const TEMPLATE_SENIOR_TOOL_NAME = [
     'com.labre.template.senior-tool.name',
@@ -65,6 +73,7 @@ export const TEMPLATE_NAME_GANTT_CHART = [
 export const TEMPLATE_PACKAGE_WORDINGS = [
     TEMPLATE_PANEL_ADD,
     TEMPLATE_PANEL_SEARCH_PLACEHOLDER,
+    TEMPLATE_PANEL_CATEGORY_SAVED_FRAMES,
     TEMPLATE_SENIOR_TOOL_NAME,
     TEMPLATE_NAME_SWOT,
     TEMPLATE_NAME_KANBAN_BOARD,

package/dist/_pkgs/affine-inline-footnote/adapters/markdown/inline-delta.js

@@ -1,4 +1,5 @@
 import { FOOTNOTE_DEFINITION_PREFIX, InlineDeltaToMarkdownAdapterExtension, } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 export const footnoteReferenceDeltaToMarkdownAdapterMatcher = InlineDeltaToMarkdownAdapterExtension({
     name: 'footnote-reference',
     match: delta => !!delta.attributes?.footnote,
@@ -19,6 +20,11 @@ export const footnoteReferenceDeltaToMarkdownAdapterMatcher = InlineDeltaToMarkd
         if (!configs.has(footnoteDefinitionKey)) {
             // clone the footnote reference
             const clonedFootnoteReference = { ...footnote.reference };
+            // A stored url with a refused scheme is not written back out.
+            if (clonedFootnoteReference.url &&
+                !isSafeLinkUrl(clonedFootnoteReference.url)) {
+                delete clonedFootnoteReference.url;
+            }
             // If the footnote reference contains url, encode it
             if (clonedFootnoteReference.url) {
                 clonedFootnoteReference.url = encodeURIComponent(clonedFootnoteReference.url);

package/dist/_pkgs/affine-inline-footnote/adapters/markdown/markdown-inline.js

@@ -1,5 +1,6 @@
 import { FootNoteReferenceParamsSchema } from '../../../affine-model/index.js';
 import { FOOTNOTE_DEFINITION_PREFIX, MarkdownASTToDeltaExtension, } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 export const markdownFootnoteReferenceToDeltaMatcher = MarkdownASTToDeltaExtension({
     name: 'footnote-reference',
     match: ast => ast.type === 'footnoteReference',
@@ -23,6 +24,12 @@ export const markdownFootnoteReferenceToDeltaMatcher = MarkdownASTToDeltaExtensi
                 footnoteDefinitionJson.favicon = decodeURIComponent(footnoteDefinitionJson.favicon);
             }
             const footnoteReference = FootNoteReferenceParamsSchema.parse(footnoteDefinitionJson);
+            // A refused scheme is not stored: the footnote keeps its label and
+            // loses the url, which the render side would refuse anyway.
+            if (footnoteReference.url !== undefined &&
+                !isSafeLinkUrl(footnoteReference.url)) {
+                delete footnoteReference.url;
+            }
             // If the footnote reference is an attachment, and the file type is not set,
             // Try to infer the file type from the file name.
             const { type: referenceType, fileName, fileType } = footnoteReference;

package/dist/_pkgs/affine-inline-link/adapters/html/html-inline.js

@@ -1,4 +1,5 @@
 import { HtmlASTToDeltaExtension, } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 const isElement = (ast) => {
     return ast.type === 'element';
 };
@@ -47,7 +48,9 @@ export const htmlLinkElementToDeltaMatcher = HtmlASTToDeltaExtension({
             }
         }
         return ast.children.flatMap(child => context.toDelta(child, { trim: false }).map(delta => {
-            if (href.startsWith('http')) {
+            // http(s) only, and by the parsed scheme: a prefix test let
+            // `httpx:` or `http-javascript:` through.
+            if (/^https?:/i.test(href.trim()) && isSafeLinkUrl(href)) {
                 delta.attributes = {
                     ...delta.attributes,
                     link: href,

package/dist/_pkgs/affine-inline-link/adapters/html/inline-delta.js

@@ -1,4 +1,5 @@
 import { InlineDeltaToHtmlAdapterExtension } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 export const linkDeltaToHtmlAdapterMatcher = InlineDeltaToHtmlAdapterExtension({
     name: 'link',
     match: delta => !!delta.attributes?.link,
@@ -8,7 +9,8 @@ export const linkDeltaToHtmlAdapterMatcher = InlineDeltaToHtmlAdapterExtension({
             value: delta.insert,
         };
         const link = delta.attributes?.link;
-        if (!link) {
+        // A stored link with a refused scheme is written as its text alone.
+        if (!link || !isSafeLinkUrl(link)) {
             return hast;
         }
         return {

package/dist/_pkgs/affine-inline-link/adapters/markdown/inline-delta.js

@@ -1,4 +1,5 @@
 import { InlineDeltaToMarkdownAdapterExtension } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 export const linkDeltaToMarkdownAdapterMatcher = InlineDeltaToMarkdownAdapterExtension({
     name: 'link',
     match: delta => !!delta.attributes?.link,
@@ -8,7 +9,9 @@ export const linkDeltaToMarkdownAdapterMatcher = InlineDeltaToMarkdownAdapterExt
             value: delta.insert,
         };
         const link = delta.attributes?.link;
-        if (!link) {
+        // A stored link with a refused scheme (an older document, a paste) is
+        // written as its text alone, never re-emitted as a link.
+        if (!link || !isSafeLinkUrl(link)) {
             return mdast;
         }
         const { current: currentMdast } = context;

package/dist/_pkgs/affine-inline-link/adapters/notion-html/html-inline.js

@@ -1,4 +1,5 @@
 import { NotionHtmlASTToDeltaExtension, } from '../../../affine-shared/adapters/index.js';
+import { isSafeLinkUrl } from '../../../affine-shared/utils/index.js';
 const isElement = (ast) => {
     return ast.type === 'element';
 };
@@ -29,7 +30,7 @@ export const notionHtmlLinkElementToDeltaMatcher = NotionHtmlASTToDeltaExtension
                     return delta;
                 }
             }
-            if (href.startsWith('http')) {
+            if (/^https?:/i.test(href.trim()) && isSafeLinkUrl(href)) {
                 delta.attributes = {
                     ...delta.attributes,
                     link: href,

package/dist/_pkgs/affine-inline-link/link-node/affine-link.d.ts

@@ -14,6 +14,13 @@ export declare class AffineLink extends AffineLink_base {
         setFloating: (element?: Element) => void;
         dispose: () => void;
     };
+    /**
+     * Opens this link's toolbar without a hover, as a proposal (see
+     * `proposeLinkViews`). The toolbar keeps the hover contract once the pointer
+     * enters it; until then any key or press outside it closes it, so the
+     * proposal never outlives the next gesture.
+     */
+    proposeViews(): void;
     connectedCallback(): void;
     get block(): BlockComponent<import("../../store/index.js").BlockModel<object>, import("../../std/index.js").BlockService, string> | null;
     get inlineEditor(): import("../../std/inline/inline-editor.js").InlineEditor<AffineTextAttributes> | undefined;

package/dist/_pkgs/affine-inline-link/link-node/affine-link.js

@@ -65,6 +65,43 @@ let AffineLink = (() => {
       text-decoration: underline;
     }
   `; }
+        /**
+         * Opens this link's toolbar without a hover, as a proposal (see
+         * `proposeLinkViews`). The toolbar keeps the hover contract once the pointer
+         * enters it; until then any key or press outside it closes it, so the
+         * proposal never outlives the next gesture.
+         */
+        proposeViews() {
+            const message$ = this.std.get(ToolbarRegistryIdentifier).message$;
+            let floating;
+            const controller = new AbortController();
+            const close = (event) => {
+                if (floating && event.composedPath().includes(floating))
+                    return;
+                controller.abort();
+                if (message$.peek()?.element === this)
+                    message$.value = null;
+            };
+            const options = { capture: true, signal: controller.signal };
+            document.addEventListener('keydown', close, options);
+            document.addEventListener('pointerdown', close, options);
+            this._disposables.add(() => controller.abort());
+            message$.value = {
+                flavour: 'affine:link',
+                element: this,
+                setFloating: element => {
+                    floating = element;
+                    this._whenHover.setFloating(element);
+                },
+            };
+            // Subscribed after the write: `subscribe` calls back at once with the
+            // current value, which must already be this proposal.
+            const unsubscribe = message$.subscribe(message => {
+                if (message?.element !== this)
+                    controller.abort();
+            });
+            controller.signal.addEventListener('abort', unsubscribe);
+        }
         connectedCallback() {
             super.connectedCallback();
             this._whenHover.setReference(this);

package/dist/_pkgs/affine-inline-link/link-node/index.d.ts

@@ -1,2 +1,3 @@
 export { AffineLink } from './affine-link.js';
 export { toggleLinkPopup } from './link-popup/toggle-link-popup.js';
+export { lonePastedUrl, proposeLinkViews } from './propose-views.js';

package/dist/_pkgs/affine-inline-link/link-node/index.js

@@ -1,2 +1,3 @@
 export { AffineLink } from './affine-link.js';
 export { toggleLinkPopup } from './link-popup/toggle-link-popup.js';
+export { lonePastedUrl, proposeLinkViews } from './propose-views.js';

package/dist/_pkgs/affine-inline-link/link-node/propose-views.d.ts

@@ -0,0 +1,22 @@
+import { type BlockStdScope } from '../../std/index.js';
+/**
+ * The URL a paste carries when its plain text is ONE http(s) URL and nothing
+ * else, or `null`. A sentence holding a URL, two URLs, a `mailto:` or any
+ * scheme `isSafeLinkUrl` refuses is not a lone URL: it pastes as text, as it
+ * always did.
+ */
+export declare function lonePastedUrl(text: string | null | undefined): string | null;
+/**
+ * After a lone URL was pasted in a page (labre REQ-IM-1), open the link's own
+ * toolbar on the link the paste wrote, so its view switcher offers "Card view"
+ * and "Embed view" next to the current "Inline view". Nothing is written: the
+ * paste already stored a plain link, which stays the default when the viewer
+ * picks nothing. The conversions are the toolbar's, with their own gates (a
+ * registered bookmark or embed view, an embed provider for the URL).
+ *
+ * Returns whether a toolbar was opened. Nothing opens when the paste did not
+ * leave a link at the caret (a URL the host recognised as one of its own
+ * documents became a reference), on a read-only document, or inside a table
+ * or a database cell, where the toolbar offers no conversion.
+ */
+export declare function proposeLinkViews(std: BlockStdScope, url: string): Promise<boolean>;

package/dist/_pkgs/affine-inline-link/link-node/propose-views.js

@@ -0,0 +1,59 @@
+import { isSafeLinkUrl, normalizeUrl } from '../../affine-shared/utils/index.js';
+import { TextSelection } from '../../std/index.js';
+import { AffineLink } from './affine-link.js';
+/**
+ * The URL a paste carries when its plain text is ONE http(s) URL and nothing
+ * else, or `null`. A sentence holding a URL, two URLs, a `mailto:` or any
+ * scheme `isSafeLinkUrl` refuses is not a lone URL: it pastes as text, as it
+ * always did.
+ */
+export function lonePastedUrl(text) {
+    const candidate = text?.trim();
+    if (!candidate || /\s/.test(candidate))
+        return null;
+    if (!isSafeLinkUrl(candidate))
+        return null;
+    if (!URL.canParse(candidate))
+        return null;
+    const { protocol } = new URL(candidate);
+    return protocol === 'http:' || protocol === 'https:' ? candidate : null;
+}
+/**
+ * After a lone URL was pasted in a page (labre REQ-IM-1), open the link's own
+ * toolbar on the link the paste wrote, so its view switcher offers "Card view"
+ * and "Embed view" next to the current "Inline view". Nothing is written: the
+ * paste already stored a plain link, which stays the default when the viewer
+ * picks nothing. The conversions are the toolbar's, with their own gates (a
+ * registered bookmark or embed view, an embed provider for the URL).
+ *
+ * Returns whether a toolbar was opened. Nothing opens when the paste did not
+ * leave a link at the caret (a URL the host recognised as one of its own
+ * documents became a reference), on a read-only document, or inside a table
+ * or a database cell, where the toolbar offers no conversion.
+ */
+export async function proposeLinkViews(std, url) {
+    if (std.store.readonly)
+        return false;
+    await std.host.updateComplete;
+    const caret = std.selection.find(TextSelection);
+    if (!caret)
+        return false;
+    const block = std.view.getBlock(caret.from.blockId);
+    if (!block)
+        return false;
+    await block.updateComplete;
+    if (block.closest('affine-database, affine-table'))
+        return false;
+    const href = normalizeUrl(url);
+    const links = Array.from(block.querySelectorAll('affine-link')).filter((node) => node instanceof AffineLink && node.link === href);
+    // The caret ends the pasted run; an equal link written earlier in the same
+    // paragraph must not be the one the toolbar points at.
+    const pasted = links.find(link => {
+        const range = link.selfInlineRange;
+        return !!range && range.index + range.length === caret.from.index;
+    }) ?? links.at(-1);
+    if (!pasted)
+        return false;
+    pasted.proposeViews();
+    return true;
+}

package/dist/_pkgs/affine-model/blocks/database/types.d.ts

@@ -16,12 +16,39 @@ export type SerializedCells = Record<string, Record<string, CellDataType>>;
  */
 export declare const DATABASE_VIEW_OPEN_IN: readonly ["side", "center", "full"];
 export type DatabaseViewOpenIn = (typeof DATABASE_VIEW_OPEN_IN)[number];
+/**
+ * The condition of a colour rule: a filter group, the very shape a view
+ * stores as its `filter` (`FilterGroup` of `@labre/data-view`, which reads
+ * and evaluates it). Opaque here: the model does not know the filter
+ * functions.
+ */
+export type DatabaseViewColorRuleFilter = {
+    type: 'group';
+    op: 'and' | 'or';
+    conditions: unknown[];
+};
+/**
+ * One conditional colour of a view (ADR 0036): rows (table, list) and cards
+ * (board, gallery) that match `filter` take `color` as a light background.
+ * `color` is a colour of the select options' palette, stored as an option
+ * stores it; a value this build does not know paints nothing. `id` names
+ * the rule for the editor, so a peer's reorder never retargets an edit.
+ */
+export type DatabaseViewColorRule = {
+    id: string;
+    color: string;
+    filter: DatabaseViewColorRuleFilter;
+};
 /**
  * The stored shape every view in `props.views` shares; each mode adds its own
  * data on top. `sourceId` and `openIn` arrived in 0.49 (ADR 0035 §8, red
  * zone): optional, `undefined` by default and never written on load, so a
  * view stored by 0.48 or earlier is still a valid view and a 0.48 client
  * ignores them. `sourceId` absent means the block's own implicit source.
+ * `colorRules` arrived in 0.50 (ADR 0036, red zone), on the same terms: absent
+ * until a gesture adds a rule, ordered (the first rule that matches a row
+ * wins), ignored by a 0.49 client, which keeps it through its own writes
+ * (`updateView` merges into the stored view).
  * Held by `view-basic-data.unit.spec.ts`.
  */
 export type ViewBasicDataType = {
@@ -30,4 +57,5 @@ export type ViewBasicDataType = {
     mode: string;
     sourceId?: string;
     openIn?: DatabaseViewOpenIn;
+    colorRules?: DatabaseViewColorRule[];
 };

package/dist/_pkgs/affine-model/blocks/image/image-crop.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The stored crop of an image block (ADR 0037): a view on the source, never
+ * new bytes. The rectangle is normalised to the source image (0..1 on each
+ * axis), so it needs no pixel size and survives any resize.
+ *
+ * Append-only: a mask token, once shipped, is never renamed or removed. A
+ * token this build does not know reads as `free`.
+ */
+export declare const IMAGE_CROP_MASKS: readonly ["free", "16:9", "4:3", "1:1"];
+export type ImageCropMask = (typeof IMAGE_CROP_MASKS)[number];
+export interface ImageCrop {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** The preset that drew the rectangle; absent means free. */
+    mask?: ImageCropMask;
+}
+/**
+ * Below this a side is a sliver nobody can grab again; the crop tool never
+ * writes one, and a stored one is treated as damaged.
+ */
+export declare const IMAGE_CROP_MIN_SIDE = 0.02;
+/**
+ * The crop to paint, or `undefined` for the whole image.
+ *
+ * Every reader goes through here: the value may come from a peer, an import
+ * or a damaged document, and a crop that cannot be honoured shows the whole
+ * picture rather than an empty box or an error. A rectangle covering the
+ * whole image is "no crop" too, so nothing downstream has to tell them apart.
+ */
+export declare function readImageCrop(value: unknown): ImageCrop | undefined;
+export declare function isWholeImage(rect: Pick<ImageCrop, 'x' | 'y' | 'w' | 'h'>): boolean;
+/**
+ * The part of the source, in source pixels, a crop keeps — what a raster
+ * export hands to `drawImage(image, sx, sy, sw, sh, …)`.
+ *
+ * `null` when there is nothing to cut: no crop, or a source with no pixel
+ * size (an SVG without intrinsic dimensions loads as 0×0). The caller then
+ * draws the whole image into the box, as before ADR 0037; a source
+ * rectangle of 0×0 would draw nothing at all.
+ */
+export declare function imageCropSourceRect(crop: ImageCrop | undefined, naturalWidth: number, naturalHeight: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;

package/dist/_pkgs/affine-model/blocks/image/image-crop.js

@@ -0,0 +1,78 @@
+/**
+ * The stored crop of an image block (ADR 0037): a view on the source, never
+ * new bytes. The rectangle is normalised to the source image (0..1 on each
+ * axis), so it needs no pixel size and survives any resize.
+ *
+ * Append-only: a mask token, once shipped, is never renamed or removed. A
+ * token this build does not know reads as `free`.
+ */
+export const IMAGE_CROP_MASKS = ['free', '16:9', '4:3', '1:1'];
+/**
+ * Below this a side is a sliver nobody can grab again; the crop tool never
+ * writes one, and a stored one is treated as damaged.
+ */
+export const IMAGE_CROP_MIN_SIDE = 0.02;
+const EPSILON = 1e-6;
+const isFraction = (value) => typeof value === 'number' && Number.isFinite(value);
+/**
+ * The crop to paint, or `undefined` for the whole image.
+ *
+ * Every reader goes through here: the value may come from a peer, an import
+ * or a damaged document, and a crop that cannot be honoured shows the whole
+ * picture rather than an empty box or an error. A rectangle covering the
+ * whole image is "no crop" too, so nothing downstream has to tell them apart.
+ */
+export function readImageCrop(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const { x, y, w, h, mask } = value;
+    if (!isFraction(x) || !isFraction(y) || !isFraction(w) || !isFraction(h)) {
+        return undefined;
+    }
+    if (x < -EPSILON || y < -EPSILON)
+        return undefined;
+    if (w < IMAGE_CROP_MIN_SIDE - EPSILON || h < IMAGE_CROP_MIN_SIDE - EPSILON) {
+        return undefined;
+    }
+    if (x + w > 1 + EPSILON || y + h > 1 + EPSILON)
+        return undefined;
+    if (isWholeImage({ x, y, w, h }))
+        return undefined;
+    const crop = {
+        x: Math.max(0, x),
+        y: Math.max(0, y),
+        w: Math.min(w, 1 - Math.max(0, x)),
+        h: Math.min(h, 1 - Math.max(0, y)),
+    };
+    if (typeof mask === 'string' &&
+        mask !== 'free' &&
+        IMAGE_CROP_MASKS.includes(mask)) {
+        crop.mask = mask;
+    }
+    return crop;
+}
+export function isWholeImage(rect) {
+    return (Math.abs(rect.x) < EPSILON &&
+        Math.abs(rect.y) < EPSILON &&
+        Math.abs(rect.w - 1) < EPSILON &&
+        Math.abs(rect.h - 1) < EPSILON);
+}
+/**
+ * The part of the source, in source pixels, a crop keeps — what a raster
+ * export hands to `drawImage(image, sx, sy, sw, sh, …)`.
+ *
+ * `null` when there is nothing to cut: no crop, or a source with no pixel
+ * size (an SVG without intrinsic dimensions loads as 0×0). The caller then
+ * draws the whole image into the box, as before ADR 0037; a source
+ * rectangle of 0×0 would draw nothing at all.
+ */
+export function imageCropSourceRect(crop, naturalWidth, naturalHeight) {
+    if (!crop || naturalWidth <= 0 || naturalHeight <= 0)
+        return null;
+    return {
+        x: crop.x * naturalWidth,
+        y: crop.y * naturalHeight,
+        w: crop.w * naturalWidth,
+        h: crop.h * naturalHeight,
+    };
+}

package/dist/_pkgs/affine-model/blocks/image/image-model.d.ts

@@ -1,5 +1,6 @@
 import type { GfxCommonBlockProps, GfxElementGeometry } from '../../../std/gfx/index.js';
 import type { BlockMeta } from '../../utils/types.js';
+import type { ImageCrop } from './image-crop.js';
 import { ImageBlockTransformer } from './image-transformer.js';
 export type ImageBlockProps = {
     caption?: string;
@@ -9,6 +10,11 @@ export type ImageBlockProps = {
     rotate: number;
     size?: number;
     comments?: Record<string, boolean>;
+    /**
+     * The part of the source this block shows (ADR 0037). Absent means the
+     * whole image; read it through `readImageCrop`, never directly.
+     */
+    crop?: ImageCrop;
 } & Omit<GfxCommonBlockProps, 'scale'> & BlockMeta;
 export declare const ImageBlockSchema: {
     version: number;

package/dist/_pkgs/affine-model/blocks/image/image-model.js

@@ -14,6 +14,8 @@ const defaultImageProps = {
     rotate: 0,
     size: -1,
     comments: undefined,
+    // `undefined`, so it is never written on load (ADR 0037).
+    crop: undefined,
     'meta:createdAt': undefined,
     'meta:createdBy': undefined,
     'meta:updatedAt': undefined,

package/dist/_pkgs/affine-model/blocks/image/index.d.ts

@@ -1,2 +1,3 @@
+export * from './image-crop.js';
 export * from './image-model.js';
 export * from './image-transformer.js';

package/dist/_pkgs/affine-model/blocks/image/index.js

@@ -1,2 +1,3 @@
+export * from './image-crop.js';
 export * from './image-model.js';
 export * from './image-transformer.js';

package/dist/_pkgs/affine-model/consts/shape.d.ts

@@ -21,3 +21,5 @@ export declare enum ShapeStyle {
     General = "General",
     Scribbled = "Scribbled"
 }
+export declare const SHAPE_TEXT_PADDING = 20;
+export declare const SHAPE_TEXT_VERTICAL_PADDING = 10;

package/dist/_pkgs/affine-model/consts/shape.js

@@ -39,3 +39,8 @@ export var ShapeStyle;
     ShapeStyle["General"] = "General";
     ShapeStyle["Scribbled"] = "Scribbled";
 })(ShapeStyle || (ShapeStyle = {}));
+// Moved here from `elements/shape/shape.ts`, unchanged, so the model's
+// headless entry exports them without the element class (ADR 0012, P3 as
+// amended 2026-10-14).
+export const SHAPE_TEXT_PADDING = 20;
+export const SHAPE_TEXT_VERTICAL_PADDING = 10;

package/dist/_pkgs/affine-model/elements/bpmn/consts.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Constants moved out of the element-class files of this folder, unchanged, so
+ * the model's headless entry (`@labre/affine-model/headless`) exports them
+ * without `@labre/std/gfx` behind them (ADR 0012, P3 as amended 2026-10-14).
+ * The folder index re-exports this file.
+ */
+/**
+ * Width of the participant band — the left margin strip the pool name is
+ * written up, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-bpmn`
+ * rather than the other way round. The pool's own hit test needs it (a pool is
+ * clickable by its title bands as well as its border, the bpmn.io convention),
+ * and `affine-model` cannot reach into `affine-block-surface` where the
+ * declaration is resolved. One number, owned by the layer that both the
+ * declaration and the hit test can read.
+ */
+export declare const POOL_BAND_WIDTH = 28;
+/**
+ * Width of a lane's own title band — the strip immediately inside the
+ * participant band, with the lane name turned on its side.
+ *
+ * Four units narrower than {@link POOL_BAND_WIDTH}, and for the same reason the
+ * lane font is two points smaller: the two strips sit side by side, so the
+ * subordinate one has to say so. Identical widths read as a single 56-unit
+ * gutter rather than as a participant containing lanes, which is exactly the
+ * relationship the picture has to carry.
+ *
+ * NO fill, divider only — what bpmn.io, Camunda and Visio all draw.
+ */
+export declare const POOL_LANE_BAND_WIDTH = 24;

package/dist/_pkgs/affine-model/elements/bpmn/consts.js

@@ -0,0 +1,31 @@
+/**
+ * Constants moved out of the element-class files of this folder, unchanged, so
+ * the model's headless entry (`@labre/affine-model/headless`) exports them
+ * without `@labre/std/gfx` behind them (ADR 0012, P3 as amended 2026-10-14).
+ * The folder index re-exports this file.
+ */
+/**
+ * Width of the participant band — the left margin strip the pool name is
+ * written up, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-bpmn`
+ * rather than the other way round. The pool's own hit test needs it (a pool is
+ * clickable by its title bands as well as its border, the bpmn.io convention),
+ * and `affine-model` cannot reach into `affine-block-surface` where the
+ * declaration is resolved. One number, owned by the layer that both the
+ * declaration and the hit test can read.
+ */
+export const POOL_BAND_WIDTH = 28;
+/**
+ * Width of a lane's own title band — the strip immediately inside the
+ * participant band, with the lane name turned on its side.
+ *
+ * Four units narrower than {@link POOL_BAND_WIDTH}, and for the same reason the
+ * lane font is two points smaller: the two strips sit side by side, so the
+ * subordinate one has to say so. Identical widths read as a single 56-unit
+ * gutter rather than as a participant containing lanes, which is exactly the
+ * relationship the picture has to carry.
+ *
+ * NO fill, divider only — what bpmn.io, Camunda and Visio all draw.
+ */
+export const POOL_LANE_BAND_WIDTH = 24;