@formicoidea/labre-framework-cynefin 0.42.0 → 0.43.1

package/dist/cynefin/crop.d.ts

@@ -0,0 +1,6 @@
+import type { SerializedXYWH } from '@formicoidea/labre-core/global/gfx';
+/**
+ * The frame of `xywh` brought back onto the drawing it letterboxes, or `null`
+ * when it is already on it.
+ */
+export declare function cynefinCroppedXYWH(xywh: SerializedXYWH): SerializedXYWH | null;

package/dist/cynefin/crop.js

@@ -0,0 +1,45 @@
+import { Bound } from '@formicoidea/labre-core/global/gfx';
+import { refScale } from '../utils.js';
+import { REF_H, REF_W } from './consts.js';
+/**
+ * Cropping a Cynefin frame back onto its drawing, at the end of a resize.
+ *
+ * The diagram is a figurative reproduction of the official SVG, so it cannot be
+ * stretched: `element-renderer.ts` fits it uniformly and centres what is left
+ * over (`refScale`). Dragged off its 1080 × 777 proportion, the element
+ * therefore letterboxes — at 1600 × 600 there are FOUR HUNDRED model units of
+ * nothing either side of the picture. And a framework background is caught by
+ * its border and by nothing else
+ * (`model/src/elements/framework-background/hit-test.ts`, a band of `10 / zoom`
+ * around the `xywh`), so the frame the user has to aim at ends up hundreds of
+ * units away from anything drawn.
+ *
+ * The answer the PO chose (23/09/2026) is not to stretch the drawing and not to
+ * widen the hit test, but to bring the FRAME back to the picture when the user
+ * lets go of a resize handle. Nothing is deformed and nothing is truncated: the
+ * element simply stops claiming room it does not paint.
+ *
+ * Why it is safe under rotation: a uniform fit centres what it fits, so
+ * `ox + REF_W * s / 2 === w / 2`. The cropped box has the SAME CENTRE as the one
+ * it replaces, and a surface element rotates about its centre — so the drawing
+ * does not move, at any angle.
+ */
+/**
+ * Below half a model unit there is nothing to see, and writing anyway would
+ * cost an undo entry for a gesture that changed nothing. It is also what makes
+ * the crop idempotent: a frame already cropped is left alone.
+ */
+const CROP_EPSILON = 0.5;
+/**
+ * The frame of `xywh` brought back onto the drawing it letterboxes, or `null`
+ * when it is already on it.
+ */
+export function cynefinCroppedXYWH(xywh) {
+    const bound = Bound.deserialize(xywh);
+    if (!(bound.w > 0) || !(bound.h > 0))
+        return null;
+    const { s, ox, oy } = refScale(bound.w, bound.h, REF_W, REF_H);
+    if (ox < CROP_EPSILON && oy < CROP_EPSILON)
+        return null;
+    return new Bound(bound.x + ox, bound.y + oy, REF_W * s, REF_H * s).serialize();
+}

package/dist/cynefin/element-view.d.ts

@@ -17,7 +17,35 @@ export declare class CynefinView extends FrameworkBackgroundView<CynefinElementM
     protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
 }
 /**
- * Resize gating: the resize handles are hidden unless `model.resizeEnabled` is
- * true (toggled from the toolbar). Moving / selecting stays available.
+ * Resize gating and, when the handle is let go, the crop.
+ *
+ * ## Gating
+ *
+ * The resize handles are hidden unless `model.resizeEnabled` is true (toggled
+ * from the toolbar). Moving / selecting stays available.
+ *
+ * ## The crop
+ *
+ * The diagram is a fixed drawing fitted uniformly into the element, so dragged
+ * off its proportion the element letterboxes: 400 model units of nothing either
+ * side at 1600 × 600. `onResizeEnd` brings the frame back onto the picture (see
+ * `./crop.ts`) — the drawing is neither deformed nor truncated, the element
+ * simply stops claiming room it does not paint.
+ *
+ * ## Why here, and why one undo step
+ *
+ * A resize STASHES `xywh` on the way in, writes the model on every move, and
+ * commits the stash in `onResizeEnd`, inside the manager's own
+ * `store.transact` (`std/gfx/interactivity/manager.ts`). Writing the cropped
+ * box BEFORE calling `default` therefore changes what is committed rather than
+ * adding a second write: the whole gesture stays one Yjs write, and one undo
+ * step. `captureSync` would do the opposite here — it would close the step and
+ * make the crop a second one.
+ *
+ * This seam is also what keeps the crop a GESTURE. A cascade watching `xywh`
+ * would fire on a peer's resize too and re-crop, on every screen, a frame
+ * nobody on that screen touched; and it would fire on a document being loaded.
+ * The readonly guard is belt and braces — `handleElementResize` already refuses
+ * to start in a readonly store — but it is the invariant, so it is stated.
  */
 export declare const CynefinInteraction: import("@formicoidea/labre-core/store").ExtensionType;

package/dist/cynefin/element-view.js

@@ -1,6 +1,7 @@
 import { FrameworkBackgroundView, hitTestBackgroundLabel, } from '@formicoidea/labre-core/blocks/surface';
 import { translateKey, } from '@formicoidea/labre-core/shared/services';
 import { GfxViewInteractionExtension } from '@formicoidea/labre-core/std/gfx';
+import { cynefinCroppedXYWH } from './crop.js';
 import { cynefinLabelHits } from './labels.js';
 /**
  * View for the Cynefin background. Registering it ensures `gfx.view.get(model)`
@@ -22,17 +23,55 @@ export class CynefinView extends FrameworkBackgroundView {
     }
 }
 /**
- * Resize gating: the resize handles are hidden unless `model.resizeEnabled` is
- * true (toggled from the toolbar). Moving / selecting stays available.
+ * Resize gating and, when the handle is let go, the crop.
+ *
+ * ## Gating
+ *
+ * The resize handles are hidden unless `model.resizeEnabled` is true (toggled
+ * from the toolbar). Moving / selecting stays available.
+ *
+ * ## The crop
+ *
+ * The diagram is a fixed drawing fitted uniformly into the element, so dragged
+ * off its proportion the element letterboxes: 400 model units of nothing either
+ * side at 1600 × 600. `onResizeEnd` brings the frame back onto the picture (see
+ * `./crop.ts`) — the drawing is neither deformed nor truncated, the element
+ * simply stops claiming room it does not paint.
+ *
+ * ## Why here, and why one undo step
+ *
+ * A resize STASHES `xywh` on the way in, writes the model on every move, and
+ * commits the stash in `onResizeEnd`, inside the manager's own
+ * `store.transact` (`std/gfx/interactivity/manager.ts`). Writing the cropped
+ * box BEFORE calling `default` therefore changes what is committed rather than
+ * adding a second write: the whole gesture stays one Yjs write, and one undo
+ * step. `captureSync` would do the opposite here — it would close the step and
+ * make the crop a second one.
+ *
+ * This seam is also what keeps the crop a GESTURE. A cascade watching `xywh`
+ * would fire on a peer's resize too and re-crop, on every screen, a frame
+ * nobody on that screen touched; and it would fire on a document being loaded.
+ * The readonly guard is belt and braces — `handleElementResize` already refuses
+ * to start in a readonly store — but it is the invariant, so it is stated.
  */
 export const CynefinInteraction = GfxViewInteractionExtension(CynefinView.type, {
-    handleResize({ model }) {
+    handleResize({ std, model }) {
         return {
             beforeResize({ set }) {
                 if (!model.resizeEnabled) {
                     set({ allowedHandlers: [] });
                 }
             },
+            onResizeEnd(context) {
+                if (!std.store.readonly) {
+                    const cropped = cynefinCroppedXYWH(model.xywh);
+                    // No write at all when the frame is already on the drawing: an
+                    // undo entry for a gesture that changed nothing is a bug.
+                    if (cropped)
+                        model.xywh = cropped;
+                }
+                context.default(context);
+            },
         };
     },
 });

package/dist/estuarine/consts.d.ts

@@ -1,13 +1,14 @@
 import type { ChromeWording } from '@formicoidea/labre-core/shared/services';
 /**
  * Visual constants for the Estuarine framework map, reproduced from the official
- * SVG (viewBox 0 0 690 801). All geometry is authored in that fixed reference
- * space; the renderer reads every coordinate below as a RATIO of it and maps it
- * onto the element's real width and height independently, so a stretched map
- * gets a longer time axis and a taller energy axis rather than the same drawing
- * letterboxed (see `EstuarineFit` in `./element-renderer.ts`). The e axis is
- * vertical & double-headed (energy), the t axis horizontal & single-headed
- * (time only flows one way).
+ * SVG (viewBox 0 0 690 801). All geometry is authored in that fixed space; the
+ * renderer reads every coordinate below as a RATIO of the CROPPED window onto
+ * it ({@link REF_X} … {@link REF_H}) and maps it onto the element's real width
+ * and height independently, so a stretched map gets a longer time axis and a
+ * taller energy axis rather than the same drawing letterboxed (see
+ * `EstuarineFit` in `./element-renderer.ts`). The e axis is vertical &
+ * double-headed (energy), the t axis horizontal & single-headed (time only
+ * flows one way).
  *
  * The three curve legends below (`LABELS`) carry a `wording`, resolved by
  * `element-renderer.ts` through the `CanvasRenderer` it is handed at paint
@@ -15,8 +16,40 @@ import type { ChromeWording } from '@formicoidea/labre-core/shared/services';
  * italic `e` / `t` axis LETTERS (`AXIS_LABELS`) are notation, not words, and
  * are deliberately NOT keyed (PO decision).
  */
-export declare const REF_W = 690;
-export declare const REF_H = 801;
+/**
+ * The CROPPED window onto the authored 690 × 801 SVG space — the rectangle the
+ * element's bounds are mapped onto.
+ *
+ * The SVG's own viewBox is loose around the drawing: the t axis stops at
+ * `x = 616 / 690` and the e axis at `y = 763 / 801`, so a board born on the raw
+ * viewBox carried dead space on every side (measured on the painted pixels at
+ * birth size: 16.6 left, 12.6 top, 35.5 right, 20.4 bottom, in model units).
+ * The board's own border is therefore nowhere near its drawing, which is both
+ * ugly and awkward — a background is grabbed BY that border
+ * (`framework-background/hit-test.ts`).
+ *
+ * So the reference box is the ink's bounding box grown by {@link REF_MARGIN},
+ * not the viewBox. `REF_X` / `REF_Y` is where that window starts in authored
+ * coordinates; every authored number in this file keeps its ORIGINAL value and
+ * the renderer subtracts the origin (`ax` / `ay`), so nothing about the drawing
+ * moves relative to anything else — only the frame around it tightens.
+ *
+ * `MAP_SCALE` (see `../presets.ts`) multiplies these, so a new board is born
+ * smaller while its drawing keeps exactly the size it had.
+ */
+export declare const REF_X = 8;
+export declare const REF_Y = 4.5;
+export declare const REF_W = 659;
+export declare const REF_H = 786.5;
+/**
+ * Space left between the ink and the edge of the board, in reference units.
+ *
+ * Small but not zero: a stroke is centred on its path, a glyph is measured
+ * generously, and a board whose ink touched its own border would look clipped.
+ * ~6 units is a little under one axis width (8) — enough to read as a margin,
+ * little enough that the border is visibly AROUND the drawing.
+ */
+export declare const REF_MARGIN = 6;
 export declare const COLORS: {
     readonly axis: "#941253";
     /** Italic e / t axis letters. */
@@ -42,12 +75,38 @@ export declare const T_AXIS: {
     readonly x2: 616;
 };
 export declare const AXIS_WIDTH = 8;
-/** Filled arrowhead triangles: [[tipX,tipY],[baseAX,baseAY],[baseBX,baseBY]]. */
-export declare const ARROWHEADS: ReadonlyArray<readonly [
-    readonly [number, number],
-    readonly [number, number],
-    readonly [number, number]
-]>;
+/**
+ * A filled arrowhead, welded to the END OF ITS AXIS.
+ *
+ * Declared the way the shared primitive declares one (`drawAxis`,
+ * `blocks/surface/src/framework-background/renderer.ts`): the head has ONE
+ * proportional anchor — {@link at}, the point where its axis stops, which
+ * travels with the stretch — and every other number below is an offset from
+ * that anchor in FIXED units, painted at the isotropic `strokeScale`.
+ *
+ * That split is the whole point. The vertices used to be three absolute
+ * authored points, so a stretch moved the tip by `sx` while the renderer
+ * rebuilt the base from the tip at the isotropic factor: as soon as
+ * `sx ≠ strokeScale` the triangle tore away from the line it belongs to
+ * (a 29-unit gap at 1600 × 400, the head drowning in the stroke at 400 × 1600).
+ * Anchoring the head to the axis end instead keeps it soldered at every ratio,
+ * and reproduces the authored SVG exactly when `sx === sy` — which is what the
+ * numbers below were read off.
+ */
+export interface EstuarineArrowhead {
+    /** Authored end of the axis this head is welded to — the ratio anchor. */
+    at: readonly [number, number];
+    /** Unit vector pointing OUT of the axis, towards the tip. */
+    dir: readonly [number, number];
+    /** How far past the axis end the tip sits, in fixed units. */
+    tip: number;
+    /** How far SHORT of the axis end the base sits: the weld's overlap. */
+    overlap: number;
+    /** Half the base's width, in fixed units. */
+    halfWidth: number;
+}
+/** The three heads: both ends of the e axis, the right end of the t axis. */
+export declare const ARROWHEADS: readonly EstuarineArrowhead[];
 /** Liminal: green boundary rising gently then dipping at the right end. */
 export declare const LIMINAL_PATH = "M 63 193 C 67 192, 78 189, 85 188 C 92 187, 100 186, 107 185 C 114 184, 122 183, 129 183 C 136 183, 144 183, 151 183 C 158 183, 166 183, 173 183 C 180 183, 188 184, 195 185 C 202 186, 210 188, 217 189 C 224 190, 232 192, 239 194 C 246 196, 254 198, 261 201 C 268 204, 276 207, 283 210 C 290 213, 298 217, 305 220 C 312 223, 320 226, 327 230 C 334 234, 342 238, 349 242 C 356 246, 364 250, 371 255 C 378 260, 386 264, 393 269 C 400 274, 408 278, 415 283 C 422 288, 430 292, 437 297 C 444 302, 451 306, 458 310 C 465 314, 473 319, 480 323 C 487 327, 495 332, 502 335 C 509 338, 517 341, 524 343 C 531 345, 539 348, 546 349 C 553 350, 561 350, 568 350 C 575 350, 583 348, 590 346 C 597 344, 605 340, 612 336 C 619 332, 626 325, 633 319 C 640 313, 648 302, 651 298 C 654 294, 654 295, 654 294";
 export declare const LIMINAL_WIDTH = 4.5;
@@ -99,17 +158,33 @@ export declare const LABELS: {
         readonly color: "#e63322";
     };
 };
-/** Italic Georgia axis letters (left-anchored, alphabetic baseline). */
+/**
+ * Italic Georgia axis letters (left-anchored, alphabetic baseline).
+ *
+ * Each letter NAMES an axis, so it is declared against that axis the way a
+ * declared background declares a word (`backgroundPoint`,
+ * `blocks/surface/src/framework-background/def.ts`): a proportional anchor
+ * (`at`, the end of the axis it names) plus a FIXED `dx`/`dy` gap, painted at
+ * the isotropic `strokeScale` like the glyph itself.
+ *
+ * They used to be absolute authored positions projected by `sx`/`sy` while the
+ * glyph was typed isotropically, so the gap between letter and axis grew or
+ * collapsed with the ratio — the `t` climbing onto its own axis at 1600 × 400,
+ * falling far below it at 400 × 1600. `at + d·strokeScale` is exactly the
+ * authored position when `sx === sy`, and a constant gap everywhere else.
+ */
 export declare const AXIS_LABELS: {
     readonly e: {
         readonly text: "e";
-        readonly x: 14;
-        readonly y: 138;
+        readonly at: readonly [43.5, 97];
+        readonly dx: -29.5;
+        readonly dy: 41;
     };
     readonly t: {
         readonly text: "t";
-        readonly x: 580;
-        readonly y: 685;
+        readonly at: readonly [616, 649];
+        readonly dx: -36;
+        readonly dy: 36;
     };
     readonly size: 34;
 };

package/dist/estuarine/consts.js

@@ -1,12 +1,13 @@
 /**
  * Visual constants for the Estuarine framework map, reproduced from the official
- * SVG (viewBox 0 0 690 801). All geometry is authored in that fixed reference
- * space; the renderer reads every coordinate below as a RATIO of it and maps it
- * onto the element's real width and height independently, so a stretched map
- * gets a longer time axis and a taller energy axis rather than the same drawing
- * letterboxed (see `EstuarineFit` in `./element-renderer.ts`). The e axis is
- * vertical & double-headed (energy), the t axis horizontal & single-headed
- * (time only flows one way).
+ * SVG (viewBox 0 0 690 801). All geometry is authored in that fixed space; the
+ * renderer reads every coordinate below as a RATIO of the CROPPED window onto
+ * it ({@link REF_X} … {@link REF_H}) and maps it onto the element's real width
+ * and height independently, so a stretched map gets a longer time axis and a
+ * taller energy axis rather than the same drawing letterboxed (see
+ * `EstuarineFit` in `./element-renderer.ts`). The e axis is vertical &
+ * double-headed (energy), the t axis horizontal & single-headed (time only
+ * flows one way).
  *
  * The three curve legends below (`LABELS`) carry a `wording`, resolved by
  * `element-renderer.ts` through the `CanvasRenderer` it is handed at paint
@@ -14,8 +15,40 @@
  * italic `e` / `t` axis LETTERS (`AXIS_LABELS`) are notation, not words, and
  * are deliberately NOT keyed (PO decision).
  */
-export const REF_W = 690;
-export const REF_H = 801;
+/**
+ * The CROPPED window onto the authored 690 × 801 SVG space — the rectangle the
+ * element's bounds are mapped onto.
+ *
+ * The SVG's own viewBox is loose around the drawing: the t axis stops at
+ * `x = 616 / 690` and the e axis at `y = 763 / 801`, so a board born on the raw
+ * viewBox carried dead space on every side (measured on the painted pixels at
+ * birth size: 16.6 left, 12.6 top, 35.5 right, 20.4 bottom, in model units).
+ * The board's own border is therefore nowhere near its drawing, which is both
+ * ugly and awkward — a background is grabbed BY that border
+ * (`framework-background/hit-test.ts`).
+ *
+ * So the reference box is the ink's bounding box grown by {@link REF_MARGIN},
+ * not the viewBox. `REF_X` / `REF_Y` is where that window starts in authored
+ * coordinates; every authored number in this file keeps its ORIGINAL value and
+ * the renderer subtracts the origin (`ax` / `ay`), so nothing about the drawing
+ * moves relative to anything else — only the frame around it tightens.
+ *
+ * `MAP_SCALE` (see `../presets.ts`) multiplies these, so a new board is born
+ * smaller while its drawing keeps exactly the size it had.
+ */
+export const REF_X = 8;
+export const REF_Y = 4.5;
+export const REF_W = 659;
+export const REF_H = 786.5;
+/**
+ * Space left between the ink and the edge of the board, in reference units.
+ *
+ * Small but not zero: a stroke is centred on its path, a glyph is measured
+ * generously, and a board whose ink touched its own border would look clipped.
+ * ~6 units is a little under one axis width (8) — enough to read as a margin,
+ * little enough that the border is visibly AROUND the drawing.
+ */
+export const REF_MARGIN = 6;
 export const COLORS = {
     axis: '#941253',
     /** Italic e / t axis letters. */
@@ -33,23 +66,32 @@ export const E_AXIS = { x: 43.5, y1: 97, y2: 763 };
 /** t axis (horizontal, single-headed → right): y, left x, right x. */
 export const T_AXIS = { y: 649, x1: 28, x2: 616 };
 export const AXIS_WIDTH = 8;
-/** Filled arrowhead triangles: [[tipX,tipY],[baseAX,baseAY],[baseBX,baseBY]]. */
+/** The three heads: both ends of the e axis, the right end of the t axis. */
 export const ARROWHEADS = [
-    [
-        [43.5, 72],
-        [30, 100],
-        [57, 100],
-    ], // e — top
-    [
-        [43.5, 785],
-        [30, 758],
-        [57, 758],
-    ], // e — bottom
-    [
-        [643, 649],
-        [613, 636],
-        [613, 662],
-    ], // t — right
+    // e — top
+    {
+        at: [E_AXIS.x, E_AXIS.y1],
+        dir: [0, -1],
+        tip: 25,
+        overlap: 3,
+        halfWidth: 13.5,
+    },
+    // e — bottom
+    {
+        at: [E_AXIS.x, E_AXIS.y2],
+        dir: [0, 1],
+        tip: 22,
+        overlap: 5,
+        halfWidth: 13.5,
+    },
+    // t — right
+    {
+        at: [T_AXIS.x2, T_AXIS.y],
+        dir: [1, 0],
+        tip: 27,
+        overlap: 3,
+        halfWidth: 13,
+    },
 ];
 /** Liminal: green boundary rising gently then dipping at the right end. */
 export const LIMINAL_PATH = 'M 63 193 C 67 192, 78 189, 85 188 C 92 187, 100 186, 107 185 C 114 184, 122 183, 129 183 C 136 183, 144 183, 151 183 C 158 183, 166 183, 173 183 C 180 183, 188 184, 195 185 C 202 186, 210 188, 217 189 C 224 190, 232 192, 239 194 C 246 196, 254 198, 261 201 C 268 204, 276 207, 283 210 C 290 213, 298 217, 305 220 C 312 223, 320 226, 327 230 C 334 234, 342 238, 349 242 C 356 246, 364 250, 371 255 C 378 260, 386 264, 393 269 C 400 274, 408 278, 415 283 C 422 288, 430 292, 437 297 C 444 302, 451 306, 458 310 C 465 314, 473 319, 480 323 C 487 327, 495 332, 502 335 C 509 338, 517 341, 524 343 C 531 345, 539 348, 546 349 C 553 350, 561 350, 568 350 C 575 350, 583 348, 590 346 C 597 344, 605 340, 612 336 C 619 332, 626 325, 633 319 C 640 313, 648 302, 651 298 C 654 294, 654 295, 654 294';
@@ -118,10 +160,24 @@ export const LABELS = {
         color: COLORS.volatile,
     },
 };
-/** Italic Georgia axis letters (left-anchored, alphabetic baseline). */
+/**
+ * Italic Georgia axis letters (left-anchored, alphabetic baseline).
+ *
+ * Each letter NAMES an axis, so it is declared against that axis the way a
+ * declared background declares a word (`backgroundPoint`,
+ * `blocks/surface/src/framework-background/def.ts`): a proportional anchor
+ * (`at`, the end of the axis it names) plus a FIXED `dx`/`dy` gap, painted at
+ * the isotropic `strokeScale` like the glyph itself.
+ *
+ * They used to be absolute authored positions projected by `sx`/`sy` while the
+ * glyph was typed isotropically, so the gap between letter and axis grew or
+ * collapsed with the ratio — the `t` climbing onto its own axis at 1600 × 400,
+ * falling far below it at 400 × 1600. `at + d·strokeScale` is exactly the
+ * authored position when `sx === sy`, and a constant gap everywhere else.
+ */
 export const AXIS_LABELS = {
-    e: { text: 'e', x: 14, y: 138 },
-    t: { text: 't', x: 580, y: 685 },
+    e: { text: 'e', at: [E_AXIS.x, E_AXIS.y1], dx: -29.5, dy: 41 },
+    t: { text: 't', at: [T_AXIS.x2, T_AXIS.y], dx: -36, dy: 36 },
     size: 34,
 };
 export const LABEL_LETTER_SPACING = 4;

package/dist/estuarine/element-renderer.d.ts

@@ -109,6 +109,13 @@ export declare function applyEstuarineTransform(ctx: CanvasRenderingContext2D, w
  *   arrowheads and every word. Their POSITION follows the stretch — an axis
  *   ends where the map now ends — while their SHAPE does not, because a
  *   stretched arrowhead or a squashed letter is a defect, never a feature.
+ *
+ *   One rule keeps that split honest, and it is the shared primitive's own
+ *   (`drawAxis` / `backgroundPoint`): **an anchor is a RATIO of the frame, and
+ *   every offset from an anchor is in FIXED units.** A shape must never take
+ *   its anchor from one and its offset from the other — that mix is exactly
+ *   what tore the arrowheads off their axes and slid the `e` / `t` letters
+ *   around on a stretched map.
  * - **Stretched reference space**, entered by {@link applyEstuarineTransform}:
  *   the three curves, which are boundaries across the plane and must cover
  *   whatever plane the user has made.

package/dist/estuarine/element-renderer.js

@@ -1,7 +1,7 @@
 import { ElementRendererExtension, taggedPath2D, } from '@formicoidea/labre-core/blocks/surface';
 import { translateKey, } from '@formicoidea/labre-core/shared/services';
 import { FONT_FAMILY } from '../utils.js';
-import { ARROWHEADS, AXIS_LABELS, AXIS_WIDTH, COLORS, COUNTERFACTUAL_PATH, COUNTERFACTUAL_WIDTH, E_AXIS, LABEL_LETTER_SPACING, LABELS, LIMINAL_PATH, LIMINAL_WIDTH, REF_H, REF_W, T_AXIS, VOLATILE_PATH, VOLATILE_WIDTH, } from './consts.js';
+import { ARROWHEADS, AXIS_LABELS, AXIS_WIDTH, COLORS, COUNTERFACTUAL_PATH, COUNTERFACTUAL_WIDTH, E_AXIS, LABEL_LETTER_SPACING, LABELS, LIMINAL_PATH, LIMINAL_WIDTH, REF_H, REF_W, REF_X, REF_Y, T_AXIS, VOLATILE_PATH, VOLATILE_WIDTH, } from './consts.js';
 import { estuarineLegendText } from './labels.js';
 /**
  * The three reference curves are drawn as a permanent GHOST (PO arbitration,
@@ -82,6 +82,10 @@ export function estuarineFit(w, h) {
 export function applyEstuarineTransform(ctx, w, h) {
     const fit = estuarineFit(w, h);
     ctx.scale(fit.sx, fit.sy);
+    // The crop: authored (REF_X, REF_Y) is the element's own origin. Applied
+    // INSIDE the scale so the translation is expressed in authored units, which
+    // is the space the `Path2D` this transform is meant for is written in.
+    ctx.translate(-REF_X, -REF_Y);
     return fit;
 }
 /**
@@ -97,6 +101,13 @@ export function applyEstuarineTransform(ctx, w, h) {
  *   arrowheads and every word. Their POSITION follows the stretch — an axis
  *   ends where the map now ends — while their SHAPE does not, because a
  *   stretched arrowhead or a squashed letter is a defect, never a feature.
+ *
+ *   One rule keeps that split honest, and it is the shared primitive's own
+ *   (`drawAxis` / `backgroundPoint`): **an anchor is a RATIO of the frame, and
+ *   every offset from an anchor is in FIXED units.** A shape must never take
+ *   its anchor from one and its offset from the other — that mix is exactly
+ *   what tore the arrowheads off their axes and slid the `e` / `t` letters
+ *   around on a stretched map.
  * - **Stretched reference space**, entered by {@link applyEstuarineTransform}:
  *   the three curves, which are boundaries across the plane and must cover
  *   whatever plane the user has made.
@@ -111,10 +122,10 @@ export const estuarine = (model, ctx, matrix, renderer) => {
         .rotateSelf(model.rotate)
         .translateSelf(-cx, -cy));
     const fit = estuarineFit(w, h);
-    /** Authored x → element x. Proportional: `43.5 / 690` of the real width. */
-    const ax = (x) => x * fit.sx;
+    /** Authored x → element x, through the cropped window (see `./consts.ts`). */
+    const ax = (x) => (x - REF_X) * fit.sx;
     /** Authored y → element y. */
-    const ay = (y) => y * fit.sy;
+    const ay = (y) => (y - REF_Y) * fit.sy;
     ctx.lineCap = 'round';
     ctx.lineJoin = 'round';
     // ── Axes ────────────────────────────────────────────────────────────
@@ -130,17 +141,29 @@ export const estuarine = (model, ctx, matrix, renderer) => {
     ctx.moveTo(ax(T_AXIS.x1), ay(T_AXIS.y));
     ctx.lineTo(ax(T_AXIS.x2), ay(T_AXIS.y));
     ctx.stroke();
-    // Each head is pinned by its TIP — which travels to the real end of its axis
-    // — and then built from the authored offsets at the isotropic scale, so the
-    // triangle keeps its shape at any aspect ratio.
-    for (const [[tx, ty], [px, py], [qx, qy]] of ARROWHEADS) {
-        const tipX = ax(tx);
-        const tipY = ay(ty);
-        const k = fit.strokeScale;
+    // Each head is welded to the END OF ITS AXIS — the one proportional anchor —
+    // and built entirely from fixed offsets around that point, exactly as the
+    // shared primitive's `drawAxis` builds one. Anchor by ratio, offset by fixed
+    // units, never a mix of the two on the two ends of one shape: that is the
+    // rule the old formula broke by pinning the tip proportionally and then
+    // rebuilding the base from it at the isotropic scale.
+    const k = fit.strokeScale;
+    for (const head of ARROWHEADS) {
+        const [dx, dy] = head.dir;
+        // Across the axis, same fixed units — the base's half-width.
+        const [px, py] = [-dy, dx];
+        const endX = ax(head.at[0]);
+        const endY = ay(head.at[1]);
+        // The base sits SHORT of the axis end, so the stroke dies inside the
+        // triangle and the two never come apart however the map is pulled.
+        const baseX = endX - dx * head.overlap * k;
+        const baseY = endY - dy * head.overlap * k;
+        const spreadX = px * head.halfWidth * k;
+        const spreadY = py * head.halfWidth * k;
         ctx.beginPath();
-        ctx.moveTo(tipX, tipY);
-        ctx.lineTo(tipX + (px - tx) * k, tipY + (py - ty) * k);
-        ctx.lineTo(tipX + (qx - tx) * k, tipY + (qy - ty) * k);
+        ctx.moveTo(endX + dx * head.tip * k, endY + dy * head.tip * k);
+        ctx.lineTo(baseX - spreadX, baseY - spreadY);
+        ctx.lineTo(baseX + spreadX, baseY + spreadY);
         ctx.closePath();
         ctx.fill();
     }
@@ -180,13 +203,18 @@ export const estuarine = (model, ctx, matrix, renderer) => {
         legend(curve.key);
     }
     // ── Italic e / t axis letters ───────────────────────────────────────
+    // A letter names an axis, so it rides the END of that axis (proportional)
+    // at a FIXED gap from it — the same anchor-plus-offset a declared background
+    // writes as `backgroundPoint`. The glyph and the gap then scale together, so
+    // the letter sits the same distance from its axis at every ratio.
     if (model.showAxisLabels) {
         ctx.fillStyle = COLORS.axisLabel;
-        ctx.font = `italic 700 ${AXIS_LABELS.size * fit.strokeScale}px Georgia, serif`;
+        ctx.font = `italic 700 ${AXIS_LABELS.size * k}px Georgia, serif`;
         ctx.textAlign = 'left';
         ctx.textBaseline = 'alphabetic';
-        ctx.fillText(AXIS_LABELS.e.text, ax(AXIS_LABELS.e.x), ay(AXIS_LABELS.e.y));
-        ctx.fillText(AXIS_LABELS.t.text, ax(AXIS_LABELS.t.x), ay(AXIS_LABELS.t.y));
+        for (const letter of [AXIS_LABELS.e, AXIS_LABELS.t]) {
+            ctx.fillText(letter.text, ax(letter.at[0]) + letter.dx * k, ay(letter.at[1]) + letter.dy * k);
+        }
     }
 };
 export const EstuarineRendererExtension = ElementRendererExtension('estuarine', estuarine);

package/dist/estuarine/labels.d.ts

@@ -33,7 +33,8 @@ export declare function estuarineLegendText(model: EstuarineElementModel, key: E
  * Clickable boxes of the visible legends, in ELEMENT-LOCAL coordinates.
  *
  * Anchored through the same fit the renderer anchors them with: proportionally
- * in both directions, typed isotropically. A legend whose curve is switched off
- * is not painted and is therefore not aimable either.
+ * in both directions — through the same cropped window (`REF_X` / `REF_Y`) —
+ * and typed isotropically. A legend whose curve is switched off is not painted
+ * and is therefore not aimable either.
  */
 export declare function estuarineLabelHits(model: EstuarineElementModel, fit: EstuarineLegendFit, translate: EstuarineWordingResolver): BackgroundLabelHit[];

package/dist/estuarine/labels.js

@@ -1,5 +1,5 @@
 import { backgroundTextHitBox } from '@formicoidea/labre-core/blocks/surface';
-import { LABEL_LETTER_SPACING, LABELS } from './consts.js';
+import { LABEL_LETTER_SPACING, LABELS, REF_X, REF_Y } from './consts.js';
 /**
  * What a legend SAYS: the user's own word, else the vocabulary.
  *
@@ -20,8 +20,9 @@ export function estuarineLegendText(model, key, translate) {
  * Clickable boxes of the visible legends, in ELEMENT-LOCAL coordinates.
  *
  * Anchored through the same fit the renderer anchors them with: proportionally
- * in both directions, typed isotropically. A legend whose curve is switched off
- * is not painted and is therefore not aimable either.
+ * in both directions — through the same cropped window (`REF_X` / `REF_Y`) —
+ * and typed isotropically. A legend whose curve is switched off is not painted
+ * and is therefore not aimable either.
  */
 export function estuarineLabelHits(model, fit, translate) {
     const props = model;
@@ -31,7 +32,7 @@ export function estuarineLabelHits(model, fit, translate) {
         if (!props[label.visibleProp])
             continue;
         const text = estuarineLegendText(model, key, translate);
-        const box = backgroundTextHitBox(text, label.size * fit.strokeScale, label.x * fit.sx, label.y * fit.sy, 'center');
+        const box = backgroundTextHitBox(text, label.size * fit.strokeScale, (label.x - REF_X) * fit.sx, (label.y - REF_Y) * fit.sy, 'center');
         // A legend is letter-spaced, so it is wider than the shared estimate: half
         // of the extra width on each side, since the word is centred on its anchor.
         const spread = (Math.max(text.length - 1, 0) * LABEL_LETTER_SPACING * fit.strokeScale) /

package/dist/presets.d.ts

@@ -8,9 +8,20 @@
  * the estuarine background was drawn at scale 1 while the button drew it at
  * 1.2. Derived from one table, neither can happen again.
  */
-/** Estuarine map default scale (REF aspect, scaled up so it reads on canvas). */
+/**
+ * Estuarine map default scale: how many canvas units one reference unit of the
+ * drawing is worth when the map is born. The DRAWING's size, in other words —
+ * which is why it is this number, and not the birth box, that is the constant.
+ */
 export declare const MAP_SCALE = 1.2;
-/** The box an estuarine map is born in — the size the toolbox draws. */
+/**
+ * The box an estuarine map is born in — the size the toolbox draws.
+ *
+ * Derived from the CROPPED reference box (`estuarine/consts.ts`), so the board
+ * is born just big enough to hold its drawing plus a thin margin. It shrank
+ * when the crop tightened (828 × 961.2 → 790.8 × 943.8) and the drawing inside
+ * it did not change size by a single unit — `MAP_SCALE` is still 1.2.
+ */
 export declare const ESTUARINE_MAP_W: number;
 export declare const ESTUARINE_MAP_H: number;
 /** The box a Cynefin frame is born in. */

package/dist/presets.js

@@ -12,9 +12,20 @@ import { ESTUARINE_ROLE } from './estuarine/roles.js';
  * the estuarine background was drawn at scale 1 while the button drew it at
  * 1.2. Derived from one table, neither can happen again.
  */
-/** Estuarine map default scale (REF aspect, scaled up so it reads on canvas). */
+/**
+ * Estuarine map default scale: how many canvas units one reference unit of the
+ * drawing is worth when the map is born. The DRAWING's size, in other words —
+ * which is why it is this number, and not the birth box, that is the constant.
+ */
 export const MAP_SCALE = 1.2;
-/** The box an estuarine map is born in — the size the toolbox draws. */
+/**
+ * The box an estuarine map is born in — the size the toolbox draws.
+ *
+ * Derived from the CROPPED reference box (`estuarine/consts.ts`), so the board
+ * is born just big enough to hold its drawing plus a thin margin. It shrank
+ * when the crop tightened (828 × 961.2 → 790.8 × 943.8) and the drawing inside
+ * it did not change size by a single unit — `MAP_SCALE` is still 1.2.
+ */
 export const ESTUARINE_MAP_W = EST_W * MAP_SCALE;
 export const ESTUARINE_MAP_H = EST_H * MAP_SCALE;
 /** The box a Cynefin frame is born in. */

package/dist/templates/index.js

@@ -3,7 +3,7 @@ import { FontFamily, ShapeStyle, TextAlign } from '@formicoidea/labre-core/model
 import { NOTATION_NEUTRALS } from '@formicoidea/labre-core/shared/consts';
 import { translateKey, } from '@formicoidea/labre-core/shared/services';
 import { cynefinEstuarineCommands } from '../commands.js';
-import { HEX_SIZE } from '../estuarine/consts.js';
+import { HEX_SIZE, REF_X, REF_Y } from '../estuarine/consts.js';
 import { CYNEFIN_H, CYNEFIN_W, cynefinBackgroundProps, ESTUARINE_MAP_H, ESTUARINE_MAP_W, estuarineHexagonBox, estuarineHexagonProps, estuarineMapProps, MAP_SCALE, } from '../presets.js';
 /**
  * The Cynefin / Estuarine palettes — DERIVED from the toolbox, one template per
@@ -12,8 +12,8 @@ import { CYNEFIN_H, CYNEFIN_W, cynefinBackgroundProps, ESTUARINE_MAP_H, ESTUARIN
  * Every single-artefact entry below is what its command actually draws, run
  * once against a recording surface. Hand-written, they had drifted exactly as
  * far as a copy drifts: the hexagons had lost the `textFitMode` #52 gave them,
- * and the estuarine background was drawn at scale 1 (690×801) where the button
- * draws it at 1.2 (828×961). Derived, neither can happen again — and
+ * and the estuarine background was drawn at scale 1 where the button draws it
+ * at `MAP_SCALE`. Derived, neither can happen again — and
  * `templates-parity.unit.spec.ts` re-runs each command and compares.
  *
  * The two COMPOSITIONS stay hand-written: a sorting board and a constraint map
@@ -47,12 +47,19 @@ function sticky(x, y, text) {
     };
 }
 /**
- * A constraint on the shipped map, placed by its CENTRE in the map's reference
- * space (690×801) — the frame the drawing was laid out in — carried onto the
- * box the map is actually born at.
+ * A constraint on the shipped map, placed by its CENTRE in the map's AUTHORED
+ * space (the 690×801 the drawing was laid out in), carried onto the box the map
+ * is actually born at.
+ *
+ * `- REF_X` / `- REF_Y` is the map's crop: the board's own origin is authored
+ * `(REF_X, REF_Y)`, not `(0, 0)`, so a hexagon placed on a curve stays on that
+ * curve. Derived, never restated — tightening the crop moves the drawing and
+ * the constraints on it together.
  */
+const mapX = (cx) => (cx - REF_X) * MAP_SCALE;
+const mapY = (cy) => (cy - REF_Y) * MAP_SCALE;
 const hexAt = (cx, cy) => estuarineHexagonProps({
-    xywh: estuarineHexagonBox(cx * MAP_SCALE, cy * MAP_SCALE),
+    xywh: estuarineHexagonBox(mapX(cx), mapY(cy)),
 });
 const CAPTION_W = 120;
 const CAPTION_H = 24;
@@ -69,8 +76,8 @@ const CAPTION_GAP = 8;
  * Neutral, and staying so: a name is nobody's artefact.
  */
 function caption(cx, cy, str) {
-    const x = cx * MAP_SCALE - CAPTION_W / 2;
-    const y = cy * MAP_SCALE + HEX_SIZE / 2 + CAPTION_GAP;
+    const x = mapX(cx) - CAPTION_W / 2;
+    const y = mapY(cy) + HEX_SIZE / 2 + CAPTION_GAP;
     return {
         type: 'text',
         text: surfaceText(str),

package/dist/utils.d.ts

@@ -1,11 +1,9 @@
 /**
- * Uniform fit of a fixed reference design (`refW × refH`) into an element of
- * size `w × h`: the scale factor plus the centering offsets (letterboxed).
- * Keeps the artwork undistorted at any element size.
+ * Uniform fit of a fixed reference design into an element, THE one in the
+ * library: `@labre/affine-block-surface`'s `refScale`. Re-exported here because
+ * both diagrams of this package draw an authored artwork and have always called
+ * it by this name — the body used to be copied here, and in two other packages
+ * besides (R37, one source of truth).
  */
-export declare function refScale(w: number, h: number, refW: number, refH: number): {
-    s: number;
-    ox: number;
-    oy: number;
-};
+export { refScale } from '@formicoidea/labre-core/blocks/surface';
 export declare const FONT_FAMILY = "Inter, sans-serif";

package/dist/utils.js

@@ -1,10 +1,9 @@
 /**
- * Uniform fit of a fixed reference design (`refW × refH`) into an element of
- * size `w × h`: the scale factor plus the centering offsets (letterboxed).
- * Keeps the artwork undistorted at any element size.
+ * Uniform fit of a fixed reference design into an element, THE one in the
+ * library: `@labre/affine-block-surface`'s `refScale`. Re-exported here because
+ * both diagrams of this package draw an authored artwork and have always called
+ * it by this name — the body used to be copied here, and in two other packages
+ * besides (R37, one source of truth).
  */
-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 };
-}
+export { refScale } from '@formicoidea/labre-core/blocks/surface';
 export const FONT_FAMILY = 'Inter, sans-serif';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@formicoidea/labre-framework-cynefin",
   "description": "Labre cynefin-estuarine framework for @formicoidea/labre-core.",
-  "version": "0.42.0",
+  "version": "0.43.1",
   "type": "module",
   "sideEffects": false,
   "author": "lajola",
@@ -31,7 +31,7 @@
     "dist"
   ],
   "dependencies": {
-    "@formicoidea/labre-core": "0.42.0",
+    "@formicoidea/labre-core": "0.43.1",
     "@preact/signals-core": "^1.8.0",
     "lit": "^3.2.0"
   }