@formicoidea/labre-core 0.31.0 → 0.33.0

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

@@ -0,0 +1,206 @@
+/** The default card: a plain white rectangle, no border, no radius. */
+export const DEFAULT_BACKGROUND_SURFACE = {
+    fill: '#ffffff',
+};
+/** The plot rectangle of a background of size `w × h`, in element-local units. */
+export function backgroundPlot(def, w, h) {
+    const { margin } = def.geometry;
+    const x0 = margin.left;
+    const y0 = margin.top;
+    const x1 = w - margin.right;
+    const y1 = h - margin.bottom;
+    return { x0, y0, x1, y1, width: x1 - x0, height: y1 - y0 };
+}
+/** Element-local point of an anchor, given the plot it is expressed against. */
+export function backgroundPoint(anchor, plot) {
+    return [
+        plot.x0 + anchor.x * plot.width + (anchor.dx ?? 0),
+        plot.y0 + anchor.y * plot.height + (anchor.dy ?? 0),
+    ];
+}
+/**
+ * The colour a broken declaration paints in.
+ *
+ * Loud magenta on purpose: a background is DATA, and the cost of getting it
+ * wrong must be seen on the canvas in one glance rather than debugged from a
+ * `rgba(NaN,NaN,NaN,0.4)` that silently paints nothing.
+ */
+export const BROKEN_BACKGROUND_COLOR = '#ff00ff';
+/** Warn once per distinct problem: a renderer runs on every frame. */
+const warned = new Set();
+function warnOnce(reason) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`[framework-background] ${reason}`);
+}
+export function warnBrokenBackgroundColor(reason) {
+    warnOnce(reason);
+}
+/**
+ * Resolve `@name` against the palette; anything else is a literal colour.
+ *
+ * A name the palette does not carry is a typo in the declaration, not a
+ * request for transparency: it warns and returns {@link BROKEN_BACKGROUND_COLOR}.
+ */
+export function backgroundColor(color, palette) {
+    if (!color)
+        return 'transparent';
+    if (!color.startsWith('@'))
+        return color;
+    const resolved = palette?.[color.slice(1)];
+    if (resolved !== undefined)
+        return resolved;
+    warnBrokenBackgroundColor(`no palette entry for "${color}"`);
+    return BROKEN_BACKGROUND_COLOR;
+}
+/** Nothing to report, shared so the common case allocates no array. */
+const NO_INSTANCE_ZONES = Object.freeze([]);
+/**
+ * The plot partition ONE instance carries, as rectangles in plot ratios.
+ *
+ * The semantic accessor onto {@link BackgroundInstanceZonesDef}: everything
+ * that has to know where a user's own zones sit — the renderer that draws their
+ * dividers and their names, the audit that reports them, the rules a later
+ * tranche will judge inside them — reads them here, so a lane is one shape and
+ * not four that must agree. Named consumer: the BPMN pool's lanes (couloirs).
+ *
+ * Pure: declaration plus the instance's bag of props in, plain data out. Ratios
+ * and not model units, for the reason every position in this file is a ratio —
+ * an instance stretched to twice its height keeps the same partition.
+ *
+ * ## What a malformed partition does
+ *
+ * A partition is data the user edits, so it gets typos and half-written rows,
+ * and none of them may take the frame down or paint a picture that lies:
+ *
+ * - a missing, empty or non-array prop yields `[]` — a background that simply
+ *   has no partition yet, which is what every instance looks like the moment it
+ *   is created;
+ * - an entry that is not an object, or carries no string id, is dropped;
+ * - a size that is not a finite number, or is `0` or less, is dropped with a
+ *   warning: a zero-height band is a band nothing can be in, and a negative one
+ *   would eat into its neighbours. Dropped rather than clamped, for the reason
+ *   {@link FrameworkBackgroundDef.transitionBandWidth} drops its own degenerate
+ *   case — silently inventing a size is worse than showing one band fewer;
+ * - once for each distinct problem, like every other diagnostic on the paint
+ *   path (see {@link warnBrokenBackgroundColor}).
+ *
+ * The survivors keep their declaration ORDER, and their sizes are normalised
+ * over the sum of the survivors — so dropping a broken row redistributes its
+ * space rather than leaving a hole where it was.
+ */
+export function backgroundInstanceZones(def, model) {
+    const spec = def.instanceZones;
+    if (spec === undefined)
+        return NO_INSTANCE_ZONES;
+    const raw = model[spec.prop];
+    if (!Array.isArray(raw) || raw.length === 0)
+        return NO_INSTANCE_ZONES;
+    const items = [];
+    let total = 0;
+    for (const entry of raw) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const item = entry;
+        if (typeof item.id !== 'string' || item.id === '')
+            continue;
+        const size = item.size;
+        if (typeof size !== 'number' || !Number.isFinite(size) || size <= 0) {
+            warnOnce(`"${def.type}" instance zone "${item.id}" declares a size of ${String(size)} — a zone with no extent is one nothing can be inside, so it is ` +
+                `dropped and its neighbours share the space.`);
+            continue;
+        }
+        items.push({
+            id: item.id,
+            ...(typeof item.name === 'string' ? { name: item.name } : {}),
+            size,
+        });
+        total += size;
+    }
+    if (items.length === 0 || !(total > 0))
+        return NO_INSTANCE_ZONES;
+    const zones = [];
+    let at = 0;
+    for (const item of items) {
+        const share = item.size / total;
+        zones.push({
+            id: `${spec.idPrefix}:${item.id}`,
+            ...(item.name !== undefined ? { name: item.name } : {}),
+            rect: spec.stack === 'y'
+                ? { x: 0, y: at, w: 1, h: share }
+                : { x: at, y: 0, w: share, h: 1 },
+        });
+        at += share;
+    }
+    return zones;
+}
+/**
+ * The label STRIP of one instance zone, in element-local model units.
+ *
+ * `null` when the declaration asks for no band, or when there is no room for
+ * one. THE one place that knows where a lane title sits: the renderer paints
+ * from it and the framework's view hit-tests a double-click against it, so the
+ * words a user aims at and the words they get are the same rectangle by
+ * construction rather than by two constants that must agree.
+ *
+ * Clamped to the plot, the way a side band clamps to an element narrower than
+ * its own margin ({@link BackgroundSideBandDef}) — the same degenerate case,
+ * and the same answer.
+ */
+export function backgroundInstanceZoneBand(def, zone, plot) {
+    const spec = def.instanceZones;
+    const band = spec?.label?.band;
+    if (spec === undefined || band === undefined)
+        return null;
+    if (!(band.width > 0))
+        return null;
+    if (spec.stack === 'y') {
+        const width = Math.min(band.width, plot.width);
+        if (!(width > 0))
+            return null;
+        return {
+            x: plot.x0,
+            y: plot.y0 + zone.rect.y * plot.height,
+            w: width,
+            h: zone.rect.h * plot.height,
+        };
+    }
+    const height = Math.min(band.width, plot.height);
+    if (!(height > 0))
+        return null;
+    return {
+        x: plot.x0 + zone.rect.x * plot.width,
+        y: plot.y0,
+        w: zone.rect.w * plot.width,
+        h: height,
+    };
+}
+/**
+ * Whether the resize handles are offered for this element.
+ *
+ * The element's own `resizeEnabled` decides — it is what the toolbar toggle
+ * writes. The declaration's {@link BackgroundGeometry.resizable} is the
+ * fallback for an element that carries no such prop, which is what makes it
+ * live data rather than documentation.
+ */
+export function backgroundResizeAllowed(def, model) {
+    return model.resizeEnabled ?? def.geometry.resizable;
+}
+/**
+ * The size a fresh background of this framework is created at, never smaller
+ * than the bounds it is asked to cover — so a second map dropped on a board
+ * matches the biggest one already there instead of shrinking beside it.
+ */
+export function backgroundSize(def, atLeastWidth = 0, atLeastHeight = 0) {
+    const { width: refWidth, height: refHeight, lockAspectRatio } = def.geometry;
+    if (!lockAspectRatio) {
+        return {
+            width: Math.max(refWidth, atLeastWidth),
+            height: Math.max(refHeight, atLeastHeight),
+        };
+    }
+    const ratio = refHeight / refWidth;
+    const width = Math.max(refWidth, atLeastWidth, atLeastHeight / ratio);
+    return { width, height: width * ratio };
+}

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

@@ -0,0 +1,188 @@
+import type { Bound } from '../../global/gfx/index.js';
+import { 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).
+ *
+ * `def.ts` describes a background so it can be PAINTED. The same declaration
+ * already says everything a rule needs to know about the frame of reference —
+ * which axes exist, which way they run, where one zone ends and the next
+ * begins — and this file is the semantic accessor onto that, so the validation
+ * engine never re-derives geometry a framework already declared, and never
+ * imports a renderer to find out.
+ *
+ * Pure data in, pure data out: no canvas, no element model, no DI. Everything
+ * here is a function of the declaration (plus, for the model-space helpers, the
+ * bounds of ONE instance of it, and — for the transition bands — the bag of
+ * props that instance carries, which is data too).
+ */
+/**
+ * An axis, as a rule sees it.
+ *
+ * {@link forward} is the unit vector of INCREASING value in MODEL space, where
+ * `y` grows DOWNWARDS. So a horizontal axis runs `[1, 0]` and a vertical one
+ * `[0, -1]` — "more" is up, which is the opposite of increasing screen `y` and
+ * exactly what {@link BackgroundAxisDef} documents.
+ *
+ * Derived from `orientation` rather than from a new declared field: the
+ * direction of progression is not a free choice a framework makes, it is the
+ * convention every axis in `def.ts` is already written against ("`forward` is
+ * the direction of increasing value"). A framework that one day needs a
+ * reversed axis adds a field there and this reads it — until then, inventing
+ * one would be a knob nobody turns.
+ *
+ * ponytail: a ROTATED instance is not accounted for. `forward` is a function of
+ * the declaration alone, so it describes an upright background — turn a map
+ * 180° on the canvas and W1 reads a correct change arrow as pointing backwards
+ * (and a correct one as fine), because the axis it is compared against never
+ * turned with it. Distinct from the reversed-axis case above: that one is a
+ * framework declaring a different convention, this one is a user rotating one
+ * instance of the same convention. Left as is because nothing rotates a
+ * framework background today and no user has asked to. Upgrade: fold the
+ * instance's `rotate` into the vector — a rotation of `forward` by the
+ * instance's angle at the one call site that has the element in hand, not a new
+ * declared field.
+ */
+export interface BackgroundAxisFact {
+    id: string;
+    orientation: 'horizontal' | 'vertical';
+    /** Unit vector of increasing value, in model space (`y` grows downwards). */
+    forward: readonly [number, number];
+    /**
+     * The model prop that SHOWS this axis' graduations — the dividers a reader
+     * sees the zone transitions BY.
+     *
+     * `undefined` when the axis declares no graduations, or declares them
+     * ungated, i.e. always drawn. Read straight off
+     * {@link BackgroundTicksDef.visibleProp}: the line that paints the frontier
+     * is the line that names its own toggle, so a rule judging against that
+     * frontier and the renderer drawing it can never disagree about whether it
+     * is there.
+     */
+    transitionsVisibleProp?: string;
+}
+/** 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. */
+export declare function backgroundAxisFact(def: FrameworkBackgroundDef, axisId: string): BackgroundAxisFact | undefined;
+/**
+ * Where one zone ends and the next begins, as PLOT RATIOS, split by the plot
+ * axis the transition runs across.
+ *
+ * `x` holds the ratios of the vertical lines separating zones left to right —
+ * on a Wardley map, the three phase transitions (`0.175`, `0.4`, `0.7`). `y`
+ * holds the horizontal ones.
+ *
+ * INTERIOR edges only: `0` and `1` are the borders of the plot, not transitions
+ * between two zones, and a rule saying "sit on a transition" must not accept
+ * the left edge of the map as one. Sorted and de-duplicated, so adjacent zones
+ * sharing an edge contribute it once.
+ */
+export declare function backgroundZoneBoundaries(def: FrameworkBackgroundDef): {
+    x: readonly Ratio[];
+    y: readonly Ratio[];
+};
+/**
+ * The same transitions in MODEL coordinates, for ONE instance of the
+ * background occupying `bound`.
+ *
+ * Ratios are of the PLOT, i.e. the element box minus the declared margin — so
+ * this is the only place that knows a transition drawn at `0.175` does not sit
+ * at 17.5% of the element's width. A rule asking "is this element on a phase
+ * transition" compares against these numbers and nothing else.
+ */
+export declare function backgroundBoundaryCoords(def: FrameworkBackgroundDef, bound: Bound): {
+    x: number[];
+    y: number[];
+};
+/**
+ * One transition, taken as the BAND it really is, in model coordinates.
+ *
+ * The line a renderer draws is where two zones meet; the band is the region in
+ * which a reader would say something is "at" that frontier. Wardley calls it
+ * the zone of PUNCTUATED EQUILIBRIUM — inertia lives at the transition, not on
+ * a coordinate — and it is the shape any rule asking "is this on the boundary"
+ * has to measure against.
+ */
+export interface BackgroundTransitionBand {
+    /**
+     * The two zones the transition separates, `custom-built|product`. A name, not
+     * an index: it comes from the declaration, so it survives a zone being added
+     * between two others and says which frontier a finding is about.
+     */
+    id: string;
+    /** The transition line itself. The band's centre. */
+    at: number;
+    /** The band, in model coordinates: `at` ± half the declared width. */
+    min: number;
+    max: number;
+}
+/**
+ * Whether the part of ONE instance that DRAWS the transitions across a plot
+ * axis is currently shown.
+ *
+ * The frontier a rule measures against is only a frontier the user can see
+ * while the graduations that draw it are on the canvas. A framework says which
+ * prop shows them — `axes[].ticks.visibleProp`, the very line the renderer
+ * reads — and this resolves it against the instance's own props.
+ *
+ * `true` when nothing gates them: an axis with ungated graduations, an axis
+ * with none at all, a framework declaring no axis. A background that never
+ * offered the toggle is a background whose frontiers are always there, which is
+ * exactly the behaviour every framework had before this existed.
+ */
+export declare function backgroundTransitionsShown(def: FrameworkBackgroundDef, plotAxis: 'x' | 'y', model: BackgroundModelLike | undefined): boolean;
+/**
+ * Every model prop that can make a transition appear or disappear on this
+ * background.
+ *
+ * The reactive half of {@link backgroundTransitionsShown}: whoever recomputes
+ * verdicts has to know which props change one. Data, so the engine learns the
+ * list from the declarations it was handed and names no framework.
+ */
+export declare function backgroundTransitionVisibleProps(def: FrameworkBackgroundDef): readonly string[];
+/**
+ * Every transition of ONE instance of the background, as named BANDS in model
+ * coordinates.
+ *
+ * The width comes from {@link FrameworkBackgroundDef.transitionBandWidth},
+ * which is a ratio of the plot — so a map stretched to twice its size keeps a
+ * band twice as wide in model units and exactly as wide to the eye. That is the
+ * whole point of declaring it there rather than as a number of units in a rule:
+ * an absolute slack is four times as strict on a map four times as big, and a
+ * user who drops a symbol on the drawn line has no way of knowing which.
+ *
+ * Empty on a background that declares no width: silence, not a guessed one.
+ *
+ * ## Two shapes a band may not silently take
+ *
+ * A declaration is data, and data gets typos. Both are caught here rather than
+ * downstream, because the failure modes are invisible on the canvas:
+ *
+ * - a width of `0` or less would make an INVERTED band (`min > max`) that
+ *   nothing can be inside — a rule requiring one would indict every subject on
+ *   the board, over a number nobody meant. The requirement is dropped instead;
+ * - a width wider than the gap between two transitions would make OVERLAPPING
+ *   bands, so a point could be "at" two frontiers at once and the middle of a
+ *   phase would qualify as a boundary. The width is narrowed to that gap.
+ *
+ * Both warn once in the console: a declaration that quietly means something
+ * other than what it says is worse than one that fails loudly.
+ *
+ * ## A hidden frontier is not a frontier
+ *
+ * `model` is the bag of props of the instance being measured. Given one, an
+ * axis whose graduations the user has switched off contributes NO band along
+ * its plot axis (see {@link backgroundTransitionsShown}) — a caller asking "is
+ * this at a transition" gets the same silence as on a frame that declares no
+ * transition at all. Nothing is judged against a line nobody can see.
+ *
+ * Omitting `model` asks the question of the DECLARATION alone: every declared
+ * transition, whatever any instance shows. That is what a caller describing the
+ * map's meaning rather than judging its drawing wants, and it is what every
+ * caller got before this argument existed.
+ */
+export declare function backgroundTransitionBands(def: FrameworkBackgroundDef, bound: Bound, model?: BackgroundModelLike): {
+    x: BackgroundTransitionBand[];
+    y: BackgroundTransitionBand[];
+};

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

@@ -0,0 +1,284 @@
+import { backgroundPlot, } from './def.js';
+const FORWARD = {
+    horizontal: [1, 0],
+    vertical: [0, -1],
+};
+/**
+ * Frozen at module load, and not as a formality.
+ *
+ * `as const` is a COMPILE-TIME claim: it stops `FORWARD.horizontal[0] = -1`
+ * from type-checking and does nothing whatsoever at runtime. These vectors are
+ * handed out by reference — {@link backgroundAxisFacts} returns the constant
+ * itself, not a copy — and they are what
+ * `evaluateOrientationAgainstAxis` multiplies a subject's direction against. A
+ * single write into one of them flips the axis convention for the whole
+ * process: correct arrows start reporting as violations, on every map, for the
+ * rest of the session.
+ *
+ * `AuditProvider` made that reachable — the audit seam hands the facts to a
+ * host-supplied assistant (PF14.1). `requestAudit` clones the whole request, so
+ * that path is closed at the boundary; this closes the class at the SOURCE, for
+ * every other caller of {@link collectAuditFacts} and of these accessors,
+ * present and future. Two defences, and the cheap one is the one that cannot be
+ * forgotten by a caller who has not read the boundary.
+ *
+ * Cost: three `Object.freeze` calls, once, at module load. Effect: a mutation
+ * throws in strict mode (every ES module) instead of silently corrupting the
+ * engine three frames later.
+ */
+Object.freeze(FORWARD.horizontal);
+Object.freeze(FORWARD.vertical);
+Object.freeze(FORWARD);
+/** The declared axes, as facts. Empty for a background that declares none. */
+export function backgroundAxisFacts(def) {
+    return (def.axes ?? []).map(axis => ({
+        id: axis.id,
+        orientation: axis.orientation,
+        forward: FORWARD[axis.orientation],
+        ...(axis.ticks?.visibleProp !== undefined
+            ? { transitionsVisibleProp: axis.ticks.visibleProp }
+            : {}),
+    }));
+}
+/** The declared axis with this id, as a fact. */
+export function backgroundAxisFact(def, axisId) {
+    return backgroundAxisFacts(def).find(axis => axis.id === axisId);
+}
+/**
+ * Where one zone ends and the next begins, as PLOT RATIOS, split by the plot
+ * axis the transition runs across.
+ *
+ * `x` holds the ratios of the vertical lines separating zones left to right —
+ * on a Wardley map, the three phase transitions (`0.175`, `0.4`, `0.7`). `y`
+ * holds the horizontal ones.
+ *
+ * INTERIOR edges only: `0` and `1` are the borders of the plot, not transitions
+ * between two zones, and a rule saying "sit on a transition" must not accept
+ * the left edge of the map as one. Sorted and de-duplicated, so adjacent zones
+ * sharing an edge contribute it once.
+ */
+export function backgroundZoneBoundaries(def) {
+    const x = new Set();
+    const y = new Set();
+    for (const zone of def.zones ?? []) {
+        const { rect } = zone;
+        for (const [set, edge] of [
+            [x, rect.x],
+            [x, rect.x + rect.w],
+            [y, rect.y],
+            [y, rect.y + rect.h],
+        ]) {
+            if (edge > 0 && edge < 1)
+                set.add(edge);
+        }
+    }
+    const sorted = (set) => Array.from(set).sort((a, b) => a - b);
+    return { x: sorted(x), y: sorted(y) };
+}
+/**
+ * The same transitions in MODEL coordinates, for ONE instance of the
+ * background occupying `bound`.
+ *
+ * Ratios are of the PLOT, i.e. the element box minus the declared margin — so
+ * this is the only place that knows a transition drawn at `0.175` does not sit
+ * at 17.5% of the element's width. A rule asking "is this element on a phase
+ * transition" compares against these numbers and nothing else.
+ */
+export function backgroundBoundaryCoords(def, bound) {
+    const plot = backgroundPlot(def, bound.w, bound.h);
+    const ratios = backgroundZoneBoundaries(def);
+    return {
+        x: ratios.x.map(at => bound.x + plot.x0 + at * plot.width),
+        y: ratios.y.map(at => bound.y + plot.y0 + at * plot.height),
+    };
+}
+/** The plot axis a transition drawn by this axis' graduations runs across. */
+function plotAxisOf(orientation) {
+    // A HORIZONTAL axis is graduated by VERTICAL lines, which sit at `x` ratios.
+    return orientation === 'horizontal' ? 'x' : 'y';
+}
+/**
+ * Whether a visibility gate is open, asked ON BEHALF OF A RULE.
+ *
+ * Deliberately not `backgroundVisible`, which the renderer uses. Painting asks
+ * "do I draw this", and a prop the model does not carry means there is nothing
+ * to draw. A rule asks the opposite question — "has the user HIDDEN the line I
+ * am about to judge against" — and a prop the model does not carry is not the
+ * user hiding anything. So the gate closes only on a value the instance
+ * actually carries and that reads false; an instance that has never heard of
+ * the prop keeps the rule it has always had.
+ *
+ * In a real document the two never diverge: a visibility toggle is declared
+ * `@field(true)`, so every element carries it from the moment it is created.
+ */
+function gateOpen(prop, model) {
+    if (model === undefined)
+        return true;
+    const value = model[prop];
+    return value === undefined ? true : Boolean(value);
+}
+/**
+ * Whether the part of ONE instance that DRAWS the transitions across a plot
+ * axis is currently shown.
+ *
+ * The frontier a rule measures against is only a frontier the user can see
+ * while the graduations that draw it are on the canvas. A framework says which
+ * prop shows them — `axes[].ticks.visibleProp`, the very line the renderer
+ * reads — and this resolves it against the instance's own props.
+ *
+ * `true` when nothing gates them: an axis with ungated graduations, an axis
+ * with none at all, a framework declaring no axis. A background that never
+ * offered the toggle is a background whose frontiers are always there, which is
+ * exactly the behaviour every framework had before this existed.
+ */
+export function backgroundTransitionsShown(def, plotAxis, model) {
+    let gated = false;
+    for (const axis of def.axes ?? []) {
+        const prop = axis.ticks?.visibleProp;
+        if (prop === undefined)
+            continue;
+        if (plotAxisOf(axis.orientation) !== plotAxis)
+            continue;
+        gated = true;
+        // Several axes may graduate the same plot axis; one of them being drawn is
+        // enough for the frontier to be on the canvas.
+        if (gateOpen(prop, model))
+            return true;
+    }
+    return !gated;
+}
+/**
+ * Every model prop that can make a transition appear or disappear on this
+ * background.
+ *
+ * The reactive half of {@link backgroundTransitionsShown}: whoever recomputes
+ * verdicts has to know which props change one. Data, so the engine learns the
+ * list from the declarations it was handed and names no framework.
+ */
+export function backgroundTransitionVisibleProps(def) {
+    const props = [];
+    for (const axis of def.axes ?? []) {
+        const prop = axis.ticks?.visibleProp;
+        if (prop !== undefined && !props.includes(prop))
+            props.push(prop);
+    }
+    return props;
+}
+/**
+ * Complain once per distinct problem. These accessors run on every evaluation,
+ * so a bare `console.warn` about a malformed declaration would fill the console
+ * at 8 Hz while somebody drags.
+ */
+const warned = new Set();
+function warnOnce(reason) {
+    if (warned.has(reason))
+        return;
+    warned.add(reason);
+    console.warn(`[framework-background] ${reason}`);
+}
+/** The ids of the zones meeting at `edge`, along one plot axis. */
+function zonesMeetingAt(def, axis, edge) {
+    let before = '';
+    let after = '';
+    for (const { id, rect } of def.zones ?? []) {
+        const start = axis === 'x' ? rect.x : rect.y;
+        const span = axis === 'x' ? rect.w : rect.h;
+        if (start + span === edge)
+            before = id;
+        if (start === edge)
+            after = id;
+    }
+    return `${before}|${after}`;
+}
+/**
+ * Every transition of ONE instance of the background, as named BANDS in model
+ * coordinates.
+ *
+ * The width comes from {@link FrameworkBackgroundDef.transitionBandWidth},
+ * which is a ratio of the plot — so a map stretched to twice its size keeps a
+ * band twice as wide in model units and exactly as wide to the eye. That is the
+ * whole point of declaring it there rather than as a number of units in a rule:
+ * an absolute slack is four times as strict on a map four times as big, and a
+ * user who drops a symbol on the drawn line has no way of knowing which.
+ *
+ * Empty on a background that declares no width: silence, not a guessed one.
+ *
+ * ## Two shapes a band may not silently take
+ *
+ * A declaration is data, and data gets typos. Both are caught here rather than
+ * downstream, because the failure modes are invisible on the canvas:
+ *
+ * - a width of `0` or less would make an INVERTED band (`min > max`) that
+ *   nothing can be inside — a rule requiring one would indict every subject on
+ *   the board, over a number nobody meant. The requirement is dropped instead;
+ * - a width wider than the gap between two transitions would make OVERLAPPING
+ *   bands, so a point could be "at" two frontiers at once and the middle of a
+ *   phase would qualify as a boundary. The width is narrowed to that gap.
+ *
+ * Both warn once in the console: a declaration that quietly means something
+ * other than what it says is worse than one that fails loudly.
+ *
+ * ## A hidden frontier is not a frontier
+ *
+ * `model` is the bag of props of the instance being measured. Given one, an
+ * axis whose graduations the user has switched off contributes NO band along
+ * its plot axis (see {@link backgroundTransitionsShown}) — a caller asking "is
+ * this at a transition" gets the same silence as on a frame that declares no
+ * transition at all. Nothing is judged against a line nobody can see.
+ *
+ * Omitting `model` asks the question of the DECLARATION alone: every declared
+ * transition, whatever any instance shows. That is what a caller describing the
+ * map's meaning rather than judging its drawing wants, and it is what every
+ * caller got before this argument existed.
+ */
+export function backgroundTransitionBands(def, bound, model) {
+    const declared = def.transitionBandWidth;
+    if (declared === undefined)
+        return { x: [], y: [] };
+    if (!(declared > 0)) {
+        warnOnce(`"${def.type}" declares a transitionBandWidth of ${declared} — a band ` +
+            `with no width is a band nothing can be inside, so the requirement is ` +
+            `dropped rather than refusing every subject on the board.`);
+        return { x: [], y: [] };
+    }
+    const plot = backgroundPlot(def, bound.w, bound.h);
+    const ratios = backgroundZoneBoundaries(def);
+    const bands = (axis, along, origin, span) => {
+        const width = fittedWidth(def, declared, along);
+        return along.map(at => {
+            const centre = origin + at * span;
+            const half = (width * span) / 2;
+            return {
+                id: zonesMeetingAt(def, axis, at),
+                at: centre,
+                min: centre - half,
+                max: centre + half,
+            };
+        });
+    };
+    const shown = (plotAxis) => model === undefined || backgroundTransitionsShown(def, plotAxis, model);
+    return {
+        x: shown('x') ? bands('x', ratios.x, bound.x + plot.x0, plot.width) : [],
+        y: shown('y') ? bands('y', ratios.y, bound.y + plot.y0, plot.height) : [],
+    };
+}
+/**
+ * The declared width, narrowed so that two adjacent bands cannot overlap.
+ *
+ * Clamped to the smallest gap between two transitions, which is the widest a
+ * band can be while every point still belongs to at most one frontier (the two
+ * neighbours then meet at a single point). Nothing to clamp when the axis
+ * carries fewer than two transitions.
+ */
+function fittedWidth(def, declared, along) {
+    let gap = Infinity;
+    for (let i = 1; i < along.length; i++) {
+        gap = Math.min(gap, along[i] - along[i - 1]);
+    }
+    if (declared <= gap)
+        return declared;
+    warnOnce(`"${def.type}" declares a transitionBandWidth of ${declared}, wider than ` +
+        `the ${gap} between two of its transitions — the bands would overlap and ` +
+        `a point would sit at two frontiers at once. Narrowed to ${gap}.`);
+    return gap;
+}

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

@@ -0,0 +1,5 @@
+export * from './def.js';
+export * from './facts.js';
+export * from './interaction.js';
+export * from './labels.js';
+export * from './renderer.js';