@formicoidea/labre-core 0.34.2 → 0.36.0

package/dist/_pkgs/affine-components/toolbar/menu-button.js

@@ -247,6 +247,46 @@ export class EditorMenuAction extends LitElement {
       pointer-events: none;
     }
 
+    /*
+     * ...unless the row is a TOGGLE rather than one of N. The rule above reads
+     * a selected row as inert, which is right for a single choice — re-picking
+     * the option already in force is a no-op, so swallowing the click costs
+     * nothing. A toggle is the opposite: re-clicking the value in force is the
+     * ONLY way to un-pick it (the qualification dropdown's tag values), and an
+     * inert row leaves the user with a tag that cannot be removed. Such a row
+     * opts the pointer back in through data-toggle.
+     */
+    :host([data-selected][data-toggle]) {
+      pointer-events: auto;
+    }
+
+    /*
+     * An OPTION row: one of N choices, the one in force carrying
+     * data-selected. Opt-in through data-option, because a plain command row is
+     * not a choice and keeps its left-packed icon and its grey highlight.
+     *
+     * The shape invents nothing. It is what edgeless-tool-icon-button draws
+     * with justify='space-between' and its default active-mode-color -- the
+     * Regular/Semibold menu -- and what size-dropdown-menu already spells out
+     * for its own check list: label left, tick right and ONLY when selected,
+     * the selected row in the primary colour. The colour IS the affordance, so
+     * the background highlight goes, and no gutter is held open on the left for
+     * a tick that is not there.
+     */
+    :host([data-option]) {
+      justify-content: space-between;
+    }
+
+    :host([data-option][data-selected]) {
+      color: var(--affine-primary-color);
+      background-color: unset;
+    }
+
+    /* The tick takes the row's colour rather than the neutral icon one. */
+    :host([data-option][data-selected]) ::slotted(svg) {
+      color: inherit;
+    }
+
     :host(:hover.delete),
     :host(:hover.delete) ::slotted(svg) {
       background-color: var(--affine-background-error-color);

package/dist/_pkgs/affine-gfx-connector/direction/direction-reveal.d.ts

@@ -6,7 +6,7 @@ import { type TypedEdge } from './typed-edge.js';
  * **M2 of `docs/adr/0010` — "show it".**
  *
  * A typed edge reveals its orientation on hover and on selection: ONE mark, the
- * role's verb laid ALONG the link — `depends on` — in a box whose far end is a
+ * role's verb laid ALONG the link — `needs` — in a box whose far end is a
  * point aimed at the target. At rest the board keeps the canonical arrowless
  * look, because on a Wardley map a permanent head already means something else
  * (evolution movement), and two meanings on one glyph make both unreadable.
@@ -66,7 +66,7 @@ export interface EdgeLabelAnchor {
      * this flag: the point of the box must face the TARGET, so on a link running
      * right-to-left — where the turn put the box's right end at the SOURCE — the
      * point moves to the box's left end. The words themselves never reverse; a
-     * mirrored `depends on` would be a smudge, not a rotation.
+     * mirrored `needs` would be a smudge, not a rotation.
      */
     flipped: boolean;
 }

package/dist/_pkgs/affine-gfx-connector/direction/direction-reveal.js

@@ -5,7 +5,7 @@ import { asTypedEdge, edgeIsBound, roleVocabularies, } from './typed-edge.js';
  * **M2 of `docs/adr/0010` — "show it".**
  *
  * A typed edge reveals its orientation on hover and on selection: ONE mark, the
- * role's verb laid ALONG the link — `depends on` — in a box whose far end is a
+ * role's verb laid ALONG the link — `needs` — in a box whose far end is a
  * point aimed at the target. At rest the board keeps the canonical arrowless
  * look, because on a Wardley map a permanent head already means something else
  * (evolution movement), and two meanings on one glyph make both unreadable.

package/dist/_pkgs/affine-gfx-connector/direction/direction-widget.d.ts

@@ -12,7 +12,7 @@ export declare const EDGE_DIRECTION_WIDGET = "affine-edge-direction-widget";
  * is an unreadable one):
  *
  * - **M2** — while a typed edge is hovered or selected, the role's VERB laid
- *   along the link: `depends on`, in a box that ends in a point aimed at the
+ *   along the link: `needs`, in a box that ends in a point aimed at the
  *   provider. Since the PO acceptance of 02/08/2026 this is the only mark the
  *   reveal draws; the canvas chevron it used to sit on top of is folded into
  *   that point (see `direction-reveal.ts`). Since the second pass of the same

package/dist/_pkgs/affine-gfx-connector/direction/direction-widget.js

@@ -86,7 +86,7 @@ const EDGE_DIRECTION_Z_INDEX = 0;
  * is an unreadable one):
  *
  * - **M2** — while a typed edge is hovered or selected, the role's VERB laid
- *   along the link: `depends on`, in a box that ends in a point aimed at the
+ *   along the link: `needs`, in a box that ends in a point aimed at the
  *   provider. Since the PO acceptance of 02/08/2026 this is the only mark the
  *   reveal draws; the canvas chevron it used to sit on top of is folded into
  *   that point (see `direction-reveal.ts`). Since the second pass of the same
@@ -139,6 +139,11 @@ let EdgeDirectionWidget = (() => {
      * point has no border to speak of, and a hairline diagonal at 40 % zoom is
      * a smudge. Solid house blue with white text reads in both themes and
      * cannot be mistaken for the map's own ink.
+     *
+     * The background here is the DEFAULT, which every role that declares no
+     * chipColor keeps: render() overrides it inline only for a role that asks
+     * for one, so a colour decision taken about one relation never repaints the
+     * others.
      */
     .edge-direction-label {
       --edge-direction-point: 9px;
@@ -325,6 +330,9 @@ let EdgeDirectionWidget = (() => {
             const verb = this._verbFor(edge);
             if (!verb)
                 return nothing;
+            // Declared by the ROLE, defaulted by the stylesheet: only a relation that
+            // asked for its own colour gets an inline background at all.
+            const chipColor = edge.direction?.chipColor;
             const { viewport } = this.gfx;
             const [x, y] = viewport.toViewCoord(anchor.at[0], anchor.at[1]);
             // Two decimals: below what a reader can see on a 12 px box, and it keeps
@@ -341,6 +349,7 @@ let EdgeDirectionWidget = (() => {
       style=${styleMap({
                 left: `${x}px`,
                 top: `${y}px`,
+                ...(chipColor ? { background: chipColor } : {}),
                 // Read right to left, as CSS composes it: scale by the zoom and turn
                 // onto the line, both about the box's centre, and only THEN slide that
                 // centre onto the anchor. The lengths in the class are model units, so

package/dist/_pkgs/affine-gfx-shape/element-view.d.ts

@@ -1,7 +1,24 @@
 import { ShapeElementModel } from '../affine-model/index.js';
 import { GfxElementModelView } from '../std/gfx/index.js';
 import { PolygonVertexEditingOverlay } from './overlay/polygon-vertex-editing-overlay.js';
-export declare class ShapeElementView extends GfxElementModelView<ShapeElementModel> {
+/**
+ * The view every shape gets, and the base a framework NODE view extends when
+ * its model is a {@link ShapeElementModel} subclass.
+ *
+ * Generic over the model, with the plain shape as the default, so
+ * `WardleyNodeView extends ShapeElementView<WardleyNodeElementModel>` reads its
+ * own `kind` off `this.model` without a cast. Every existing call site names no
+ * type argument and is unchanged.
+ *
+ * A framework node that extends this inherits the polygon VERTEX EDITOR, which
+ * is the whole reason to: {@link enterVertexEditingMode} is what the toolbar's
+ * "Edit vertices" action calls, and the action checks `view instanceof
+ * ShapeElementView` — a node view outside this hierarchy makes that button
+ * silently do nothing. What such a subclass usually does NOT want is the other
+ * thing wired here, the double-click-to-edit; {@link editsTextOnDblClick} is
+ * the one line it has to say so.
+ */
+export declare class ShapeElementView<T extends ShapeElementModel = ShapeElementModel> extends GfxElementModelView<T> {
     static type: string;
     /** Overlay for polygon vertex editing (only active for polygon shapes). */
     private _vertexEditingOverlay;
@@ -16,6 +33,17 @@ export declare class ShapeElementView extends GfxElementModelView<ShapeElementMo
      * visually correct on every drag frame.
      */
     private _syncConnectorPaths;
+    /**
+     * Whether a double-click on THIS element opens its own inner-text editor.
+     *
+     * True for every plain shape, which is what this editor has always done: a
+     * shape is a box you write in. It is a HOOK rather than a constant because a
+     * framework node is often not one — its name may be a text element grouped
+     * beside it, or the element may be a glyph's own wiring that must carry no
+     * words at all — and a subclass that overrode `onCreated` to dodge this one
+     * wiring would lose the vertex editor set up beside it.
+     */
+    protected editsTextOnDblClick(): boolean;
     private _initDblClickToEdit;
     /**
      * Whether a vertex is currently being dragged.
@@ -61,6 +89,19 @@ export declare class ShapeElementView extends GfxElementModelView<ShapeElementMo
      * The overlay is shown when a polygon is selected and removed when
      * deselected or when a non-polygon shape is selected.
      */
+    /**
+     * Whether THIS element's corners may be moved by hand.
+     *
+     * True for every plain polygon. The companion of {@link editsTextOnDblClick},
+     * and a hook for the same reason: a framework polygon's outline is often the
+     * NOTATION rather than a drawing — a Wardley accelerator points right and a
+     * decelerator points left, and that direction is the whole of what separates
+     * them — so hovering one must not offer a handle that can only turn a
+     * statement into a blob. Declining here skips the selection overlay, the
+     * pointer wiring and {@link enterVertexEditingMode} together, which is the
+     * point: a half-wired overlay is worse than none.
+     */
+    protected editsVerticesOnSelection(): boolean;
     private _initPolygonVertexEditing;
     private _ensureVertexEditingOverlay;
     private _removeVertexEditingOverlay;

package/dist/_pkgs/affine-gfx-shape/element-view.js

@@ -6,6 +6,23 @@ import { GfxElementModelView, GfxViewInteractionExtension, } from '../std/gfx/in
 import { normalizeShapeBound } from './element-renderer/index.js';
 import { PolygonVertexEditingOverlay } from './overlay/polygon-vertex-editing-overlay.js';
 import { mountShapeTextEditor } from './text/edgeless-shape-text-editor.js';
+/**
+ * The view every shape gets, and the base a framework NODE view extends when
+ * its model is a {@link ShapeElementModel} subclass.
+ *
+ * Generic over the model, with the plain shape as the default, so
+ * `WardleyNodeView extends ShapeElementView<WardleyNodeElementModel>` reads its
+ * own `kind` off `this.model` without a cast. Every existing call site names no
+ * type argument and is unchanged.
+ *
+ * A framework node that extends this inherits the polygon VERTEX EDITOR, which
+ * is the whole reason to: {@link enterVertexEditingMode} is what the toolbar's
+ * "Edit vertices" action calls, and the action checks `view instanceof
+ * ShapeElementView` — a node view outside this hierarchy makes that button
+ * silently do nothing. What such a subclass usually does NOT want is the other
+ * thing wired here, the double-click-to-edit; {@link editsTextOnDblClick} is
+ * the one line it has to say so.
+ */
 export class ShapeElementView extends GfxElementModelView {
     constructor() {
         super(...arguments);
@@ -78,8 +95,23 @@ export class ShapeElementView extends GfxElementModelView {
             ConnectorPathGenerator.updatePath(connector, null, elementGetter);
         }
     }
+    /**
+     * Whether a double-click on THIS element opens its own inner-text editor.
+     *
+     * True for every plain shape, which is what this editor has always done: a
+     * shape is a box you write in. It is a HOOK rather than a constant because a
+     * framework node is often not one — its name may be a text element grouped
+     * beside it, or the element may be a glyph's own wiring that must carry no
+     * words at all — and a subclass that overrode `onCreated` to dodge this one
+     * wiring would lose the vertex editor set up beside it.
+     */
+    editsTextOnDblClick() {
+        return true;
+    }
     _initDblClickToEdit() {
         this.on('dblclick', () => {
+            if (!this.editsTextOnDblClick())
+                return;
             const edgeless = this.std.view.getBlock(this.std.store.root.id);
             if (edgeless &&
                 !this.model.isLocked() &&
@@ -333,9 +365,26 @@ export class ShapeElementView extends GfxElementModelView {
      * The overlay is shown when a polygon is selected and removed when
      * deselected or when a non-polygon shape is selected.
      */
+    /**
+     * Whether THIS element's corners may be moved by hand.
+     *
+     * True for every plain polygon. The companion of {@link editsTextOnDblClick},
+     * and a hook for the same reason: a framework polygon's outline is often the
+     * NOTATION rather than a drawing — a Wardley accelerator points right and a
+     * decelerator points left, and that direction is the whole of what separates
+     * them — so hovering one must not offer a handle that can only turn a
+     * statement into a blob. Declining here skips the selection overlay, the
+     * pointer wiring and {@link enterVertexEditingMode} together, which is the
+     * point: a half-wired overlay is worse than none.
+     */
+    editsVerticesOnSelection() {
+        return true;
+    }
     _initPolygonVertexEditing() {
         if (this.model.shapeType !== ShapeType.Polygon)
             return;
+        if (!this.editsVerticesOnSelection())
+            return;
         // Subscribe to selection changes to manage overlay lifecycle
         this.disposable.add(this.gfx.selection.slots.updated.subscribe(() => {
             const selectedIds = this.gfx.selection.selectedIds;
@@ -481,6 +530,11 @@ export class ShapeElementView extends GfxElementModelView {
     enterVertexEditingMode() {
         if (this.model.shapeType !== ShapeType.Polygon)
             return;
+        // The same hook the selection wiring reads, asked again here: this is the
+        // other door into the mode, and an element that declined the wiring would
+        // otherwise get an overlay with no pointer handlers behind it.
+        if (!this.editsVerticesOnSelection())
+            return;
         this._ensureVertexEditingOverlay();
         this._enterVertexEditingMode();
     }

package/dist/_pkgs/affine-gfx-shape/toolbar/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config.js';
 export * from './icons.js';
+export * from './palette-color-action.js';
 export * from './senior-tool.js';
 export * from './shape-menu-config.js';

package/dist/_pkgs/affine-gfx-shape/toolbar/index.js

@@ -1,4 +1,5 @@
 export * from './config.js';
 export * from './icons.js';
+export * from './palette-color-action.js';
 export * from './senior-tool.js';
 export * from './shape-menu-config.js';

package/dist/_pkgs/affine-gfx-shape/toolbar/palette-color-action.d.ts

@@ -0,0 +1,25 @@
+import { type Color, type Palette, ShapeElementModel } from '../../affine-model/index.js';
+import type { ToolbarAction } from '../../affine-shared/services/index.js';
+export declare function neutralPalettes(): Palette[];
+/**
+ * A fill / stroke colour picker identical to the shape one, seeded with the
+ * caller's swatches (`.palettes`) instead of the default editor palette.
+ *
+ * Frameworks whose nodes are {@link ShapeElementModel} subclasses (EDGY,
+ * Wardley, …) all want the same picker with their own colours in front of it,
+ * so the ~100 lines that wire `edgeless-shape-color-picker` to the models live
+ * here once rather than being copied per framework.
+ */
+/**
+ * The last word on what a picked swatch actually WRITES as a model's fill.
+ *
+ * The identity by default, which is what a colour picker means everywhere. It
+ * exists because a swatch is a hue and some elements are washes: a Wardley
+ * ZONE is drawn over the map it groups, so its fill carries an alpha, and a
+ * picked swatch that replaced `#c6dbfc99` with an opaque `#5b9cf6` would hide
+ * the very map the zone is there to annotate. A framework that has such
+ * elements says so here — per model, because the same picker serves its
+ * washes and its opaque artefacts.
+ */
+export type FillColorFor = (model: ShapeElementModel, value: Color) => Color;
+export declare function paletteColorAction(id: string, palettes: Palette[], fillColorFor?: FillColorFor): ToolbarAction;

package/dist/_pkgs/affine-gfx-shape/toolbar/palette-color-action.js

@@ -0,0 +1,123 @@
+import { EdgelessCRUDIdentifier } from '../../affine-block-surface/index.js';
+import { packColor, } from '../../affine-components/color-picker/index.js';
+import { DefaultTheme, isTransparent, LineWidth, resolveColor, ShapeElementModel, StrokeStyle, } from '../../affine-model/index.js';
+import { getMostCommonValue } from '../../affine-shared/utils/index.js';
+import { html } from 'lit';
+/**
+ * The neutrals of the default editor palette: greys, white, black, transparent.
+ *
+ * A framework that seeds the picker with its OWN swatches drops the historical
+ * editor colours — they say nothing in that notation — but keeps the neutrals,
+ * which every drawing needs and no notation owns.
+ */
+const NEUTRAL_KEY = /grey|gray|white|black|transparent/i;
+export function neutralPalettes() {
+    return DefaultTheme.Palettes.filter(p => NEUTRAL_KEY.test(p.key));
+}
+// Mirror of the shape color action's text-color rule.
+function getTextColor(fillColor) {
+    if (fillColor === DefaultTheme.black)
+        return DefaultTheme.white;
+    if (fillColor === DefaultTheme.white)
+        return DefaultTheme.black;
+    return DefaultTheme.shapeTextColor;
+}
+export function paletteColorAction(id, palettes, fillColorFor = (_model, value) => value) {
+    return {
+        id,
+        when(ctx) {
+            return ctx.getSurfaceModelsByType(ShapeElementModel).length > 0;
+        },
+        content(ctx) {
+            const models = ctx.getSurfaceModelsByType(ShapeElementModel);
+            if (!models.length)
+                return null;
+            const enableCustomColor = ctx.features.getFlag('enable_color_picker');
+            const theme = ctx.theme.edgeless$.value;
+            const firstModel = models[0];
+            const originalFillColor = firstModel.fillColor;
+            const originalStrokeColor = firstModel.strokeColor;
+            const mapped = models.map(({ filled, fillColor, strokeColor, strokeWidth, strokeStyle }) => ({
+                fillColor: filled
+                    ? resolveColor(fillColor, theme)
+                    : DefaultTheme.transparent,
+                strokeColor: resolveColor(strokeColor, theme),
+                strokeWidth,
+                strokeStyle,
+            }));
+            const fillColor = getMostCommonValue(mapped, 'fillColor') ??
+                resolveColor(DefaultTheme.shapeFillColor, theme);
+            const strokeColor = getMostCommonValue(mapped, 'strokeColor') ??
+                resolveColor(DefaultTheme.shapeStrokeColor, theme);
+            const strokeWidth = getMostCommonValue(mapped, 'strokeWidth') ?? LineWidth.Four;
+            const strokeStyle = getMostCommonValue(mapped, 'strokeStyle') ?? StrokeStyle.Solid;
+            const pickColorWrapper = (field, pickCallback) => (e) => {
+                e.stopPropagation();
+                switch (e.detail.type) {
+                    case 'pick':
+                        pickCallback(e.detail.detail);
+                        break;
+                    case 'start':
+                        ctx.store.captureSync();
+                        models.forEach(model => model.stash(field));
+                        break;
+                    case 'end':
+                        ctx.store.transact(() => {
+                            models.forEach(model => model.pop(field));
+                        });
+                }
+            };
+            const onPickFillColor = pickColorWrapper('fillColor', palette => {
+                const value = palette.value;
+                const filled = isTransparent(value);
+                const crud = ctx.std.get(EdgelessCRUDIdentifier);
+                models.forEach(model => {
+                    // Per model, so a selection mixing a wash and an opaque artefact
+                    // gets the right fill on each — and `packColor` runs on what the
+                    // hook returned, since that is the value the document stores.
+                    const props = packColor('fillColor', fillColorFor(model, value));
+                    if (filled && !model.filled) {
+                        const color = getTextColor(value);
+                        Object.assign(props, { filled, color });
+                    }
+                    crud.updateElement(model.id, props);
+                });
+            });
+            const onPickStrokeColor = pickColorWrapper('strokeColor', palette => {
+                const props = packColor('strokeColor', palette.value);
+                const crud = ctx.std.get(EdgelessCRUDIdentifier);
+                models.forEach(model => crud.updateElement(model.id, props));
+            });
+            const onPickStrokeStyle = (e) => {
+                e.stopPropagation();
+                const { type, value } = e.detail;
+                const crud = ctx.std.get(EdgelessCRUDIdentifier);
+                const props = type === 'size'
+                    ? { strokeWidth: value }
+                    : { strokeStyle: value };
+                for (const model of models) {
+                    crud.updateElement(model.id, props);
+                }
+            };
+            return html `
+        <edgeless-shape-color-picker
+          @pickFillColor=${onPickFillColor}
+          @pickStrokeColor=${onPickStrokeColor}
+          @pickStrokeStyle=${onPickStrokeStyle}
+          .palettes=${palettes}
+          .payload=${{
+                fillColor,
+                strokeColor,
+                strokeWidth,
+                strokeStyle,
+                originalFillColor,
+                originalStrokeColor,
+                theme,
+                enableCustomColor,
+            }}
+        >
+        </edgeless-shape-color-picker>
+      `;
+        },
+    };
+}

package/dist/_pkgs/affine-model/elements/c4/board.d.ts

@@ -1,6 +1,29 @@
 import type { SerializedXYWH } from '../../../global/gfx/index.js';
+import type { PointTestOptions } from '../../../std/gfx/index.js';
 import type { FrameworkBackgroundProps } from '../framework-background/index.js';
 import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Height of the board's title band — the header strip across the top of the
+ * sheet the diagram title is written in, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-c4` rather
+ * than the other way round, for the reason `POOL_BAND_WIDTH` is: the
+ * board's own hit test needs it (a board is clickable by its title band as well
+ * as its border), 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.
+ *
+ * It is the board's TOP MARGIN, and it always was — the deep inset the plot
+ * gives up so the title has somewhere to be written. Naming it says out loud
+ * what was already true, so the strip that is painted, the strip that is picked
+ * and the strip that opens the rename are one number rather than three.
+ *
+ * 56 is what the title has been written in since the pack shipped: a 20-unit
+ * title, sitting on a baseline a third of the band up from its foot, with the
+ * rest as breathing room above and below. Changing it moves the title, so it is
+ * a visual decision and not a hit-test one.
+ */
+export declare const C4_BOARD_TITLE_BAND_HEIGHT = 56;
 /**
  * Which of C4's levels this board draws — the DECLARED fact, as opposed to the
  * title, which is free text and says whatever its author wants it to.
@@ -85,4 +108,30 @@ export declare class C4BoardElementModel extends FrameworkBackgroundElementModel
      * on a board that declares none — no fact, no rule (PRD principle 8).
      */
     accessor level: C4BoardLevel | undefined;
+    /**
+     * A board is picked by its BORDER — and by its TITLE BAND, the one carve-out
+     * this frame keeps (issues #194 / #197).
+     *
+     * The same carve-out a BPMN pool makes, for the same reason and by the same
+     * arithmetic: the band is the only part of the sheet that is the SHEET rather
+     * than the diagram drawn on it. The title is written there, nothing is ever
+     * dropped there by convention, and the plot below is where the work goes — so
+     * a click there belongs to whatever node is under the pointer.
+     *
+     * Without this the title became unreachable the day backgrounds stopped being
+     * picked by their area: the only thing left answering was the view's
+     * double-click zone, which is the tight box of the DRAWN glyphs, and a single
+     * click on the title selected nothing at all.
+     *
+     * ## Where the geometry comes from
+     *
+     * The band is the top margin, full width — one number
+     * ({@link C4_BOARD_TITLE_BAND_HEIGHT}), read from here by the framework
+     * declaration, so what is painted is what is selectable. There is no
+     * zoom-grown target here as there is on a pool: the pool grows its 28-unit
+     * strip to stay reachable when zoomed out, which would put the rename zone
+     * outside the selectable one. A 56-unit header does not need it, and the
+     * promise "what is painted is what is picked" is worth more than the pixels.
+     */
+    includesPoint(x: number, y: number, options?: PointTestOptions): boolean;
 }

package/dist/_pkgs/affine-model/elements/c4/board.js

@@ -32,8 +32,31 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     }
     return useValue ? value : void 0;
 };
+import { rotatePoint } from '../../../global/gfx/index.js';
 import { field } from '../../../std/gfx/index.js';
 import { FrameworkBackgroundElementModel } from '../framework-background/index.js';
+/**
+ * Height of the board's title band — the header strip across the top of the
+ * sheet the diagram title is written in, in model units.
+ *
+ * Declared HERE, in the model, and re-exported by `@labre/affine-gfx-c4` rather
+ * than the other way round, for the reason `POOL_BAND_WIDTH` is: the
+ * board's own hit test needs it (a board is clickable by its title band as well
+ * as its border), 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.
+ *
+ * It is the board's TOP MARGIN, and it always was — the deep inset the plot
+ * gives up so the title has somewhere to be written. Naming it says out loud
+ * what was already true, so the strip that is painted, the strip that is picked
+ * and the strip that opens the rename are one number rather than three.
+ *
+ * 56 is what the title has been written in since the pack shipped: a 20-unit
+ * title, sitting on a baseline a third of the band up from its foot, with the
+ * rest as breathing room above and below. Changing it moves the title, so it is
+ * a visual decision and not a hit-test one.
+ */
+export const C4_BOARD_TITLE_BAND_HEIGHT = 56;
 /**
  * The C4 board: the sheet one diagram of the model is drawn on — a context
  * diagram, a container diagram, a component diagram. A framework background like
@@ -119,6 +142,51 @@ let C4BoardElementModel = (() => {
          */
         get level() { return this.#level_accessor_storage; }
         set level(value) { this.#level_accessor_storage = value; }
+        /**
+         * A board is picked by its BORDER — and by its TITLE BAND, the one carve-out
+         * this frame keeps (issues #194 / #197).
+         *
+         * The same carve-out a BPMN pool makes, for the same reason and by the same
+         * arithmetic: the band is the only part of the sheet that is the SHEET rather
+         * than the diagram drawn on it. The title is written there, nothing is ever
+         * dropped there by convention, and the plot below is where the work goes — so
+         * a click there belongs to whatever node is under the pointer.
+         *
+         * Without this the title became unreachable the day backgrounds stopped being
+         * picked by their area: the only thing left answering was the view's
+         * double-click zone, which is the tight box of the DRAWN glyphs, and a single
+         * click on the title selected nothing at all.
+         *
+         * ## Where the geometry comes from
+         *
+         * The band is the top margin, full width — one number
+         * ({@link C4_BOARD_TITLE_BAND_HEIGHT}), read from here by the framework
+         * declaration, so what is painted is what is selectable. There is no
+         * zoom-grown target here as there is on a pool: the pool grows its 28-unit
+         * strip to stay reachable when zoomed out, which would put the rename zone
+         * outside the selectable one. A 56-unit header does not need it, and the
+         * promise "what is painted is what is picked" is worth more than the pixels.
+         */
+        includesPoint(x, y, options) {
+            if (super.includesPoint(x, y, options))
+                return true;
+            const [ex, ey, w, h] = this.deserializedXYWH;
+            // Element-local coordinates, undoing the element rotation about its centre
+            // — the band is axis-aligned inside the board, not on the canvas.
+            let lx = x - ex;
+            let ly = y - ey;
+            const rotate = this.rotate ?? 0;
+            if (rotate) {
+                const [ux, uy] = rotatePoint([x, y], [ex + w / 2, ey + h / 2], -rotate);
+                lx = ux - ex;
+                ly = uy - ey;
+            }
+            if (lx < 0 || lx > w || ly < 0)
+                return false;
+            // Clamped to a board shorter than its own header — the degenerate case the
+            // renderer clamps too.
+            return ly <= Math.min(C4_BOARD_TITLE_BAND_HEIGHT, h);
+        }
         constructor() {
             super(...arguments);
             __runInitializers(this, _level_extraInitializers);

package/dist/_pkgs/affine-model/elements/wardley/node.d.ts

@@ -1,16 +1,31 @@
 import { ShapeElementModel } from '../shape/index.js';
-export type WardleyNodeKind = 'component' | 'anchor' | 'pipeline' | 'handle' | 'market' | 'ecosystem' | 'method';
+export type WardleyNodeKind = 'component' | 'anchor' | 'pipeline' | 'handle' | 'market' | 'ecosystem' | 'method' | 'porter' | 'accelerator' | 'decelerator' | 'area';
 /**
  * A Wardley map node. Extends {@link ShapeElementModel} (a native ellipse) so it
  * inherits ALL shape behaviour — editable stroke width / colors, native resize,
  * center connector anchor, the shape context toolbar — for free. `kind`
  * discriminates the plain `component`, the `anchor` (which the renderer
  * decorates with an inscribed person glyph), the two pieces of a pipeline (the
- * `pipeline` body + its square `handle`), the `market` outer circle, and the
- * `ecosystem` grey backing disk. Composite nodes (pipeline / market / ecosystem)
- * are built by grouping several of these + native connectors + a text label. The
- * text label is a SEPARATE native text element grouped with the node, not stored
- * here.
+ * `pipeline` body + its square `handle`), the `market` outer circle, the
+ * `ecosystem` grey backing disk, the `porter` circle — a Porter's-forces
+ * glyph, which is the one kind that is NOT a link in the value chain: it marks
+ * an external competition force acting on the map — and the `accelerator` /
+ * `decelerator` arrows, which are not links in the chain either: they annotate
+ * the CLIMATE, saying that something is speeding evolution up or slowing it
+ * down. Those two are the first kinds drawn as a native POLYGON rather than an
+ * ellipse or a rect — and the `area` is the third: a translucent ZONE of the
+ * map, drawn as a rect or as a polygon over the components it groups, and the
+ * only kind whose two shapes are the same kind (the `shapeType` says which).
+ * Composite nodes (pipeline / market / ecosystem / porter / accelerator /
+ * decelerator) are built by grouping several of these + native connectors + a
+ * text label. The text label is a SEPARATE native text element grouped with the
+ * node, not stored here — the `porter` and the `area` being the exceptions that
+ * prove it, since the porter's one letter and the area's name are the shape's
+ * own inner text.
+ *
+ * `kind` is ADDITIVE by construction: a value is only ever appended, so a
+ * document written before a value was appended carries none of it and opens
+ * unchanged. `area` is the most recent, and needs no migration.
  */
 export declare class WardleyNodeElementModel extends ShapeElementModel {
     get type(): string;