@formicoidea/labre-core 0.42.0 → 0.45.0

package/dist/_pkgs/affine-block-surface/extensions/user-layers/commands.d.ts

@@ -0,0 +1,67 @@
+import type { AnyCommandDescriptor, BlockStdScope } from '../../../std/index.js';
+import { z } from 'zod';
+/**
+ * The user layers' commands (ADR 0031 §12), `owner: 'core'`, on the palette
+ * and the agent. The library's pane runs them through `runCommand`, and so
+ * does a host's: the read-only refusal and the undo step live in the
+ * actions, once.
+ *
+ * Each self-emits `CanvasLayerChanged` (see the telemetry README) when it
+ * wrote something — ids and counts only, never a layer name.
+ */
+export type CanvasLayerAction = 'create' | 'rename' | 'reorder' | 'delete' | 'move-elements';
+export declare function reportLayerChange(std: BlockStdScope, action: CanvasLayerAction, memberCount?: number): void;
+export declare const createLayerParams: z.ZodObject<{
+    /** Omitted: the seeded name, "Layer n". */
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name?: string | undefined;
+}, {
+    name?: string | undefined;
+}>;
+export type CreateLayerParams = z.infer<typeof createLayerParams>;
+export declare const renameLayerParams: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+}, {
+    name: string;
+    id: string;
+}>;
+export type RenameLayerParams = z.infer<typeof renameLayerParams>;
+export declare const reorderLayerParams: z.ZodObject<{
+    id: z.ZodString;
+    /** The layer it lands directly ABOVE; `null` puts it at the bottom. */
+    above: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    above: string | null;
+}, {
+    id: string;
+    above: string | null;
+}>;
+export type ReorderLayerParams = z.infer<typeof reorderLayerParams>;
+export declare const moveElementsToLayerParams: z.ZodObject<{
+    /** Omitted: the current canvas selection. */
+    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    layerId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    layerId: string;
+    ids?: string[] | undefined;
+}, {
+    layerId: string;
+    ids?: string[] | undefined;
+}>;
+export type MoveElementsToLayerParams = z.infer<typeof moveElementsToLayerParams>;
+export declare const deleteLayerParams: z.ZodObject<{
+    /** The layer to delete; `'@default'` is refused. */
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export type DeleteLayerParams = z.infer<typeof deleteLayerParams>;
+export declare const userLayerCommands: AnyCommandDescriptor[];

package/dist/_pkgs/affine-block-surface/extensions/user-layers/commands.js

@@ -0,0 +1,172 @@
+import { TelemetryProvider } from '../../../affine-shared/services/index.js';
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier } from '../../../std/gfx/index.js';
+import { z } from 'zod';
+import { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, userLayersBottomUp, } from './actions.js';
+export function reportLayerChange(std, action, memberCount) {
+    const layerCount = userLayersBottomUp(std.get(GfxControllerIdentifier).surface).length;
+    std.getOptional(TelemetryProvider)?.track('CanvasLayerChanged', {
+        page: 'whiteboard editor',
+        action,
+        layerCount,
+        ...(memberCount === undefined ? {} : { memberCount }),
+    });
+}
+export const createLayerParams = z.object({
+    /** Omitted: the seeded name, "Layer n". */
+    name: z.string().optional(),
+});
+const createLayer = {
+    id: 'canvas.layer.create',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.create',
+    labelFallback: 'New layer',
+    descriptionKey: 'com.labre.command.canvas.layer.create.description',
+    descriptionFallback: 'Add a layer on top of the others. New elements go into it until you choose another.',
+    keywords: ['layer', 'calque'],
+    surfaces: ['palette', 'agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: createLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = createLayerParams.safeParse(params ?? {});
+        if (!parsed.success)
+            return;
+        if (createUserLayer(std, parsed.data.name) === null)
+            return;
+        reportLayerChange(std, 'create');
+    },
+};
+export const renameLayerParams = z.object({
+    id: z.string().min(1),
+    name: z.string(),
+});
+const renameLayer = {
+    id: 'canvas.layer.rename',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.rename',
+    labelFallback: 'Rename layer',
+    descriptionKey: 'com.labre.command.canvas.layer.rename.description',
+    descriptionFallback: 'Give a layer a new name.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: renameLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = renameLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.rename: invalid params', parsed.error);
+            return;
+        }
+        if (!renameUserLayer(std, parsed.data.id, parsed.data.name))
+            return;
+        reportLayerChange(std, 'rename');
+    },
+};
+export const reorderLayerParams = z.object({
+    id: z.string().min(1),
+    /** The layer it lands directly ABOVE; `null` puts it at the bottom. */
+    above: z.string().min(1).nullable(),
+});
+const reorderLayer = {
+    id: 'canvas.layer.reorder',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.reorder',
+    labelFallback: 'Move layer',
+    descriptionKey: 'com.labre.command.canvas.layer.reorder.description',
+    descriptionFallback: 'Place a layer directly above another one: everything in it stacks there.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: reorderLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = reorderLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.reorder: invalid params', parsed.error);
+            return;
+        }
+        if (!reorderUserLayer(std, parsed.data.id, parsed.data.above))
+            return;
+        reportLayerChange(std, 'reorder');
+    },
+};
+export const moveElementsToLayerParams = z.object({
+    /** Omitted: the current canvas selection. */
+    ids: z.array(z.string()).optional(),
+    layerId: z.string().min(1),
+});
+const moveElementsToLayer = {
+    id: 'canvas.layer.moveElements',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.move-elements',
+    labelFallback: 'Move to layer',
+    descriptionKey: 'com.labre.command.canvas.layer.move-elements.description',
+    descriptionFallback: 'Move the selected elements to another layer. A grouped element moves with its group.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    params: moveElementsToLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = moveElementsToLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.moveElements: invalid params', parsed.error);
+            return;
+        }
+        const ids = parsed.data.ids ?? std.get(GfxControllerIdentifier).selection.selectedIds;
+        const count = moveModelsToUserLayer(std, ids, parsed.data.layerId);
+        if (!count)
+            return;
+        reportLayerChange(std, 'move-elements', count);
+    },
+};
+export const deleteLayerParams = z.object({
+    /** The layer to delete; `'@default'` is refused. */
+    id: z.string().min(1),
+});
+/**
+ * Delete a layer and everything in it, in one undo step (ADR 0031 §10). The
+ * default layer cannot be deleted, which is what keeps a canvas at one layer
+ * at least (ADR 0031 amendments): with the default layer alone — recorded or
+ * not — there is nothing to delete, so `when` withdraws the command rather
+ * than letting it fail.
+ */
+const deleteLayer = {
+    id: 'canvas.layer.delete',
+    owner: 'core',
+    kind: 'action',
+    labelKey: 'com.labre.command.canvas.layer.delete',
+    labelFallback: 'Delete layer',
+    descriptionKey: 'com.labre.command.canvas.layer.delete.description',
+    descriptionFallback: 'Delete a layer and every element in it. One undo brings them all back.',
+    surfaces: ['agent'],
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    when: std => userLayersBottomUp(std.get(GfxControllerIdentifier).surface).some(layer => layer.id !== DEFAULT_LAYER_ID),
+    params: deleteLayerParams,
+    run: (std, _invocation, params) => {
+        const parsed = deleteLayerParams.safeParse(params);
+        if (!parsed.success) {
+            console.error('canvas.layer.delete: invalid params', parsed.error);
+            return;
+        }
+        const removed = deleteUserLayer(std, parsed.data.id);
+        if (removed === null)
+            return;
+        reportLayerChange(std, 'delete', removed);
+    },
+};
+export const userLayerCommands = [
+    createLayer,
+    renameLayer,
+    reorderLayer,
+    moveElementsToLayer,
+    deleteLayer,
+];

package/dist/_pkgs/affine-block-surface/extensions/user-layers/creation.d.ts

@@ -0,0 +1,40 @@
+import type { BlockStdScope } from '../../../std/index.js';
+import { type SurfaceMiddleware, SurfaceMiddlewareBuilder } from '../../../std/gfx/index.js';
+/**
+ * The layer to REQUEST for a model derived from `source` — the note an
+ * auto-complete arrow clones, the note the slicer splits off, the block that
+ * replaces another when its view changes — so it lands beside its source
+ * once {@link resolveCreationLayer} has read it. A source in the default
+ * layer asks for {@link DEFAULT_LAYER_ID} explicitly: "absent" would hand the
+ * derived model to the viewer's active layer instead.
+ */
+export declare function sourceLayerOf(source: unknown): string;
+/**
+ * The layer a model being CREATED is stored in (ADR 0031 §6), as the value
+ * to write: a layer id, or `undefined` for the default layer.
+ *
+ * - `requested` names a layer of THIS surface → kept (a duplicate, an
+ *   alt-drag clone, a paste within the document stays beside its source);
+ * - `requested` is {@link DEFAULT_LAYER_ID} → the default layer, explicitly:
+ *   a caller that computed "default" (a new group whose highest member is in
+ *   it) is not overridden by the active layer;
+ * - anything else — absent, or an id with no record here (a paste from
+ *   another document, a template, an import) → the viewer's active layer.
+ *
+ * A surface with no layer at all writes nothing, whatever was asked.
+ */
+export declare function resolveCreationLayer(std: BlockStdScope, requested: unknown): string | undefined;
+/**
+ * Stamp the creation layer on `props` in place: set it, or remove the key so
+ * a default-layer model writes no `layer` at all.
+ */
+export declare function applyCreationLayer(std: BlockStdScope, props: Record<string, unknown>): void;
+/**
+ * Every `surface.addElement` goes through this `beforeAdd` middleware, beside
+ * `EditPropsMiddlewareBuilder` (ADR 0031 §6): a framework command adding an
+ * element directly gets the same rule as the canvas tools.
+ */
+export declare class UserLayerMiddlewareBuilder extends SurfaceMiddlewareBuilder {
+    static key: string;
+    middleware: SurfaceMiddleware;
+}

package/dist/_pkgs/affine-block-surface/extensions/user-layers/creation.js

@@ -0,0 +1,69 @@
+import { DEFAULT_LAYER_ID, GfxControllerIdentifier, ownLayerOf, SurfaceMiddlewareBuilder, } from '../../../std/gfx/index.js';
+import { CanvasActiveLayer } from './active-layer.js';
+/**
+ * The layer to REQUEST for a model derived from `source` — the note an
+ * auto-complete arrow clones, the note the slicer splits off, the block that
+ * replaces another when its view changes — so it lands beside its source
+ * once {@link resolveCreationLayer} has read it. A source in the default
+ * layer asks for {@link DEFAULT_LAYER_ID} explicitly: "absent" would hand the
+ * derived model to the viewer's active layer instead.
+ */
+export function sourceLayerOf(source) {
+    return ownLayerOf(source) ?? DEFAULT_LAYER_ID;
+}
+/**
+ * The layer a model being CREATED is stored in (ADR 0031 §6), as the value
+ * to write: a layer id, or `undefined` for the default layer.
+ *
+ * - `requested` names a layer of THIS surface → kept (a duplicate, an
+ *   alt-drag clone, a paste within the document stays beside its source);
+ * - `requested` is {@link DEFAULT_LAYER_ID} → the default layer, explicitly:
+ *   a caller that computed "default" (a new group whose highest member is in
+ *   it) is not overridden by the active layer;
+ * - anything else — absent, or an id with no record here (a paste from
+ *   another document, a template, an import) → the viewer's active layer.
+ *
+ * A surface with no layer at all writes nothing, whatever was asked.
+ */
+export function resolveCreationLayer(std, requested) {
+    const layers = std.get(GfxControllerIdentifier).surface?.props.layers;
+    if (!layers)
+        return undefined;
+    if (requested === DEFAULT_LAYER_ID)
+        return undefined;
+    if (typeof requested === 'string' && layers[requested])
+        return requested;
+    const active = std.getOptional(CanvasActiveLayer)?.resolve() ?? DEFAULT_LAYER_ID;
+    return active === DEFAULT_LAYER_ID ? undefined : active;
+}
+/**
+ * Stamp the creation layer on `props` in place: set it, or remove the key so
+ * a default-layer model writes no `layer` at all.
+ */
+export function applyCreationLayer(std, props) {
+    const layer = resolveCreationLayer(std, props.layer);
+    if (layer === undefined) {
+        delete props.layer;
+    }
+    else {
+        props.layer = layer;
+    }
+}
+/**
+ * Every `surface.addElement` goes through this `beforeAdd` middleware, beside
+ * `EditPropsMiddlewareBuilder` (ADR 0031 §6): a framework command adding an
+ * element directly gets the same rule as the canvas tools.
+ */
+export class UserLayerMiddlewareBuilder extends SurfaceMiddlewareBuilder {
+    constructor() {
+        super(...arguments);
+        this.middleware = ctx => {
+            if (ctx.type !== 'beforeAdd')
+                return;
+            const props = { ...ctx.payload.props };
+            applyCreationLayer(this.std, props);
+            ctx.payload.props = props;
+        };
+    }
+    static { this.key = 'userLayer'; }
+}

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

@@ -0,0 +1,5 @@
+export { CanvasActiveLayer } from './active-layer.js';
+export { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, setUserLayersHiddenForEveryone, userLayerName, userLayersBottomUp, writeModelLayer, } from './actions.js';
+export { type CanvasLayerAction, type CreateLayerParams, createLayerParams, type DeleteLayerParams, deleteLayerParams, type MoveElementsToLayerParams, moveElementsToLayerParams, type RenameLayerParams, renameLayerParams, type ReorderLayerParams, reorderLayerParams, reportLayerChange, userLayerCommands, } from './commands.js';
+export { applyCreationLayer, resolveCreationLayer, sourceLayerOf, UserLayerMiddlewareBuilder, } from './creation.js';
+export { LAYER_SEED_NAME, USER_LAYER_SEED_WORDINGS } from './translations.js';

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

@@ -0,0 +1,5 @@
+export { CanvasActiveLayer } from './active-layer.js';
+export { createUserLayer, deleteUserLayer, moveModelsToUserLayer, renameUserLayer, reorderUserLayer, setUserLayersHiddenForEveryone, userLayerName, userLayersBottomUp, writeModelLayer, } from './actions.js';
+export { createLayerParams, deleteLayerParams, moveElementsToLayerParams, renameLayerParams, reorderLayerParams, reportLayerChange, userLayerCommands, } from './commands.js';
+export { applyCreationLayer, resolveCreationLayer, sourceLayerOf, UserLayerMiddlewareBuilder, } from './creation.js';
+export { LAYER_SEED_NAME, USER_LAYER_SEED_WORDINGS } from './translations.js';

package/dist/_pkgs/affine-block-surface/extensions/user-layers/translations.d.ts

@@ -0,0 +1,10 @@
+import type { ChromeWording } from '../../../affine-shared/services/index.js';
+/**
+ * The name a new user layer is created with (ADR 0031 §2). A SEED: the
+ * creation site resolves it through the translation seam once and writes
+ * the result into the document, where it is content from then on — a layer
+ * renamed, or opened under another locale, keeps its name.
+ */
+export declare const LAYER_SEED_NAME: ChromeWording;
+/** The seeds this package writes into a document for user layers. */
+export declare const USER_LAYER_SEED_WORDINGS: readonly ChromeWording[];

package/dist/_pkgs/affine-block-surface/extensions/user-layers/translations.js

@@ -0,0 +1,14 @@
+/**
+ * The name a new user layer is created with (ADR 0031 §2). A SEED: the
+ * creation site resolves it through the translation seam once and writes
+ * the result into the document, where it is content from then on — a layer
+ * renamed, or opened under another locale, keeps its name.
+ */
+export const LAYER_SEED_NAME = [
+    'com.labre.layer.seed.name',
+    'Layer {{n}}',
+];
+/** The seeds this package writes into a document for user layers. */
+export const USER_LAYER_SEED_WORDINGS = [
+    LAYER_SEED_NAME,
+];

package/dist/_pkgs/affine-block-surface/framework-background/background-view.js

@@ -105,7 +105,7 @@ export class FrameworkBackgroundView extends GfxElementModelView {
             font: '14px Inter, sans-serif',
             color: 'var(--affine-text-primary-color, #1f2328)',
             background: 'var(--affine-background-overlay-panel-color, #ffffff)',
-            border: '1px solid var(--affine-primary-color, #1e96eb)',
+            border: '1px solid var(--affine-primary-color)',
             borderRadius: '6px',
             boxShadow: 'var(--affine-shadow-2, 0 2px 8px rgba(0,0,0,0.18))',
             outline: 'none',

package/dist/_pkgs/affine-block-surface/framework-background/facts.d.ts

@@ -1,6 +1,6 @@
 import type { Bound } from '../../global/gfx/index.js';
-import { type FrameworkBackgroundDef, type Ratio } from './def.js';
-import type { BackgroundModelLike } from './labels.js';
+import { type BackgroundTextDef, type FrameworkBackgroundDef, type Ratio } from './def.js';
+import { type BackgroundModelLike } from './labels.js';
 /**
  * The framework-background declaration read as EVALUATION FACTS (PF5.15/PF5.16).
  *
@@ -85,6 +85,59 @@ export interface BackgroundAxisFact {
 export declare function containingFrame<T extends {
     id: string;
 }>(bound: Bound, candidates: Iterable<T>, boundOf: (candidate: T) => Bound): T | null;
+/**
+ * One zone of ONE instance, as a reader sees it: a framework zone the instance
+ * shows, or a zone the instance declares for itself.
+ */
+export interface BackgroundZoneFact {
+    /** The declared id, or `${idPrefix}:${item.id}` for an instance zone. */
+    id: string;
+    rect: {
+        x: Ratio;
+        y: Ratio;
+        w: Ratio;
+        h: Ratio;
+    };
+    /** A framework zone's name, as declared — key, fallback and stored prop. */
+    label?: BackgroundTextDef;
+    /** An instance zone's name, as the user wrote it. */
+    name?: string;
+}
+/**
+ * Every zone ONE instance actually has: the framework's zones in the variant
+ * the instance is turned to, then the zones it declares for itself — a BPMN
+ * pool's lanes.
+ *
+ * THE answer to "which zones are on this frame", shared by the reading and the
+ * audit so they cannot disagree. Before it existed the audit concatenated every
+ * declared zone whatever the instance's variant, and could place a sub-domain
+ * on a migration chart in a classic quadrant nobody can see — the same gate
+ * the renderer and the validation engine already passed through
+ * (`backgroundInVariant`), forgotten in one reader out of three.
+ *
+ * Framework zones first, so a framework zone still wins a genuine overlap: the
+ * order the audit has always reported them in.
+ */
+export declare function backgroundZones(def: FrameworkBackgroundDef, model: BackgroundModelLike): BackgroundZoneFact[];
+/**
+ * Where the centre of `bound` sits inside the PLOT of the instance occupying
+ * `frame`, as ratios.
+ *
+ * Ratios of the plot and not of the element box: a Wardley transition drawn at
+ * `0.4` is 40 % of the PLOT, and the margin between the two is exactly where the
+ * axis titles live. 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.
+ */
+export declare function backgroundPlotRatios(def: FrameworkBackgroundDef, frame: Bound, bound: Bound): readonly [number, number] | null;
+/**
+ * The first zone whose rectangle holds a plot-ratio point, in the order given.
+ *
+ * Inclusive on all four edges and first match wins, so a point exactly on a
+ * divider belongs to the zone declared first — the tie the audit and
+ * `bpmnLaneOf` have always broken that way.
+ */
+export declare function backgroundZoneAt<T extends Pick<BackgroundZoneFact, 'rect'>>(zones: readonly T[], at: readonly [number, number]): T | undefined;
 /** The declared axes, as facts. Empty for a background that declares none. */
 export declare function backgroundAxisFacts(def: FrameworkBackgroundDef): readonly BackgroundAxisFact[];
 /** The declared axis with this id, as a fact. */

package/dist/_pkgs/affine-block-surface/framework-background/facts.js

@@ -1,4 +1,5 @@
-import { backgroundPlot, } from './def.js';
+import { backgroundInstanceZones, backgroundPlot, } from './def.js';
+import { backgroundInVariant } from './labels.js';
 const FORWARD = {
     horizontal: [1, 0],
     vertical: [0, -1],
@@ -60,6 +61,67 @@ export function containingFrame(bound, candidates, boundOf) {
     }
     return found;
 }
+/**
+ * Every zone ONE instance actually has: the framework's zones in the variant
+ * the instance is turned to, then the zones it declares for itself — a BPMN
+ * pool's lanes.
+ *
+ * THE answer to "which zones are on this frame", shared by the reading and the
+ * audit so they cannot disagree. Before it existed the audit concatenated every
+ * declared zone whatever the instance's variant, and could place a sub-domain
+ * on a migration chart in a classic quadrant nobody can see — the same gate
+ * the renderer and the validation engine already passed through
+ * (`backgroundInVariant`), forgotten in one reader out of three.
+ *
+ * Framework zones first, so a framework zone still wins a genuine overlap: the
+ * order the audit has always reported them in.
+ */
+export function backgroundZones(def, model) {
+    const zones = [];
+    for (const zone of def.zones ?? []) {
+        if (!backgroundInVariant(def, zone.variants, model))
+            continue;
+        zones.push({
+            id: zone.id,
+            rect: zone.rect,
+            ...(zone.label !== undefined ? { label: zone.label } : {}),
+        });
+    }
+    zones.push(...backgroundInstanceZones(def, model));
+    return zones;
+}
+/**
+ * Where the centre of `bound` sits inside the PLOT of the instance occupying
+ * `frame`, as ratios.
+ *
+ * Ratios of the plot and not of the element box: a Wardley transition drawn at
+ * `0.4` is 40 % of the PLOT, and the margin between the two is exactly where the
+ * axis titles live. 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.
+ */
+export function backgroundPlotRatios(def, frame, bound) {
+    const plot = backgroundPlot(def, frame.w, frame.h);
+    if (!(plot.width > 0) || !(plot.height > 0))
+        return null;
+    return [
+        (bound.x + bound.w / 2 - frame.x - plot.x0) / plot.width,
+        (bound.y + bound.h / 2 - frame.y - plot.y0) / plot.height,
+    ];
+}
+/**
+ * The first zone whose rectangle holds a plot-ratio point, in the order given.
+ *
+ * Inclusive on all four edges and first match wins, so a point exactly on a
+ * divider belongs to the zone declared first — the tie the audit and
+ * `bpmnLaneOf` have always broken that way.
+ */
+export function backgroundZoneAt(zones, at) {
+    return zones.find(({ rect }) => at[0] >= rect.x &&
+        at[0] <= rect.x + rect.w &&
+        at[1] >= rect.y &&
+        at[1] <= rect.y + rect.h);
+}
 /** The declared axes, as facts. Empty for a background that declares none. */
 export function backgroundAxisFacts(def) {
     return (def.axes ?? []).map(axis => ({

package/dist/_pkgs/affine-block-surface/framework-background/fit.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a framework that draws a FIXED reference artwork puts it in its element.
+ *
+ * A declared background (`FrameworkBackgroundDef`) never needs this: it is made
+ * of ratios of a plot and stretches with the element by construction. The
+ * frameworks that reproduce an authored drawing — Cynefin, Estuarine, EDGY, the
+ * DDD stencils — cannot stretch: circles would turn into ellipses and a
+ * hand-drawn boundary into a smear. They fit the artwork uniformly instead and
+ * centre what is left over.
+ *
+ * This was written three times over — `gfx/cynefin-estuarine/src/utils.ts`,
+ * `gfx/ddd-shared/src/shared/utils.ts` and `gfx/edgy/src/consts.ts` — with the
+ * same body each time. One source of truth (R37): the three call it, and a
+ * board that crops itself onto its drawing
+ * (`gfx/cynefin-estuarine/src/cynefin/crop.ts`) reads the very function the
+ * renderer painted through, so the two can never disagree about where the
+ * drawing is.
+ */
+/** A uniform fit: the scale, and the offsets that centre the letterbox. */
+export interface RefFit {
+    /** Scale from reference units to element units. */
+    s: number;
+    /** Left offset of the fitted artwork inside the element, in element units. */
+    ox: number;
+    /** Top offset of the fitted artwork inside the element, in element units. */
+    oy: number;
+}
+/**
+ * Uniform fit of a `refW × refH` reference design into a `w × h` box: the
+ * scale factor plus the centring offsets (letterboxed), undistorted.
+ *
+ * The fitted artwork is `refW * s` by `refH * s` and shares the box's CENTRE —
+ * `ox + refW * s / 2 === w / 2` — which is what lets a board crop itself onto
+ * its drawing without the drawing moving, rotation included.
+ */
+export declare function refScale(w: number, h: number, refW: number, refH: number): RefFit;

package/dist/_pkgs/affine-block-surface/framework-background/fit.js

@@ -0,0 +1,30 @@
+/**
+ * How a framework that draws a FIXED reference artwork puts it in its element.
+ *
+ * A declared background (`FrameworkBackgroundDef`) never needs this: it is made
+ * of ratios of a plot and stretches with the element by construction. The
+ * frameworks that reproduce an authored drawing — Cynefin, Estuarine, EDGY, the
+ * DDD stencils — cannot stretch: circles would turn into ellipses and a
+ * hand-drawn boundary into a smear. They fit the artwork uniformly instead and
+ * centre what is left over.
+ *
+ * This was written three times over — `gfx/cynefin-estuarine/src/utils.ts`,
+ * `gfx/ddd-shared/src/shared/utils.ts` and `gfx/edgy/src/consts.ts` — with the
+ * same body each time. One source of truth (R37): the three call it, and a
+ * board that crops itself onto its drawing
+ * (`gfx/cynefin-estuarine/src/cynefin/crop.ts`) reads the very function the
+ * renderer painted through, so the two can never disagree about where the
+ * drawing is.
+ */
+/**
+ * Uniform fit of a `refW × refH` reference design into a `w × h` box: the
+ * scale factor plus the centring offsets (letterboxed), undistorted.
+ *
+ * The fitted artwork is `refW * s` by `refH * s` and shares the box's CENTRE —
+ * `ox + refW * s / 2 === w / 2` — which is what lets a board crop itself onto
+ * its drawing without the drawing moving, rotation included.
+ */
+export function refScale(w, h, refW, refH) {
+    const s = Math.min(w / refW, h / refH);
+    return { s, ox: (w - refW * s) / 2, oy: (h - refH * s) / 2 };
+}

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

@@ -1,6 +1,7 @@
 export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
+export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';

package/dist/_pkgs/affine-block-surface/framework-background/index.js

@@ -1,6 +1,7 @@
 export * from './background-view.js';
 export * from './def.js';
 export * from './facts.js';
+export * from './fit.js';
 export * from './interaction.js';
 export * from './labels.js';
 export * from './renderer.js';