@formicoidea/labre-framework-cynefin 0.32.0 → 0.33.0

package/dist/estuarine/ghost-overlay.d.ts

@@ -0,0 +1,134 @@
+import { type CanvasRenderer, Overlay, type RoughCanvas } from '@formicoidea/labre-core/blocks/surface';
+import { InteractivityExtension } from '@formicoidea/labre-core/std/gfx';
+/**
+ * The REVEAL — the ~600 ms animation that plays when an Estuarine curve is
+ * switched back on (WS4, PO arbitration of 26/08/2026).
+ *
+ * The permanent look of a curve is now a discreet ghost (`GHOST_ALPHA`, dashed:
+ * see `./element-renderer.ts`). That is the right resting state and the wrong
+ * ARRIVAL: a user who clicks "show the Volatile line" and gets a 45 %-opacity
+ * dashed curve on a busy map can reasonably fail to notice anything happened,
+ * and conclude the toggle is broken. So the flip is animated — the dashes march
+ * along the path while a second, brighter stroke rides above the ghost, then
+ * decays away and leaves the ghost alone.
+ *
+ * An OVERLAY rather than a renderer change, for the same reasons the validation
+ * bracket is one: it touches no element model, writes nothing to the document,
+ * creates no undo entry, and holds nothing that could survive a reload. "When
+ * did I last flip this toggle" is session state and must never reach the
+ * document.
+ */
+/** How long the reveal stroke takes to march across the curve. */
+export declare const GHOST_REVEAL_MS = 600;
+/** How long it then takes to fade back into the permanent ghost. */
+export declare const GHOST_DECAY_MS = 200;
+/** Total life of one reveal. */
+export declare const GHOST_TOTAL_MS: number;
+/**
+ * Reference-space units the dash pattern travels during the reveal — four
+ * periods of {@link GHOST_DASH}, so the march reads as motion rather than as a
+ * jitter.
+ */
+export declare const GHOST_DASH_TRAVEL: number;
+/**
+ * Peak opacity of the reveal stroke, ON TOP of the ghost the renderer already
+ * painted. Chosen so the two together reach a full-strength line at the crest
+ * and never exceed it.
+ */
+export declare const GHOST_PEAK_ALPHA = 0.55;
+/** One frame of the reveal. */
+export interface GhostRevealFrame {
+    /** Opacity of the reveal stroke; `0` means "paint nothing". */
+    alpha: number;
+    /** `lineDashOffset` for this frame, negative so the dashes march forward. */
+    dashOffset: number;
+    /** Whether this reveal is over and can be forgotten. */
+    done: boolean;
+}
+/**
+ * The whole animation, as a pure function of elapsed milliseconds.
+ *
+ * Pure and exported on purpose: it is the only part of this file that has an
+ * opinion, and a function taking a number is testable without a canvas, a
+ * surface, a DI container or a clock. The overlay below is then reduced to
+ * "ask this, then stroke" — which is the part that cannot go wrong quietly.
+ *
+ * Out-of-range input is answered rather than trusted: a negative or non-finite
+ * elapsed (a clock that went backwards, a `performance.now()` mock) paints
+ * nothing instead of throwing or flashing.
+ */
+export declare function ghostRevealFrame(elapsed: number): GhostRevealFrame;
+/**
+ * Whether the user has asked their system for less motion.
+ *
+ * Read at every reveal rather than cached: the setting can change mid-session
+ * (an OS toggle, a devtools emulation), and the answer costs one media query.
+ * `globalThis.matchMedia` is optional-chained because this module is imported
+ * by unit specs running under Node.
+ */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Paints the reveal stroke over whatever curves are currently on.
+ *
+ * The rAF loop is copied from `ValidationOverlay`, deliberately and including
+ * its two guards: the clock is never armed when nothing is animating, and a
+ * detached renderer stops it dead. An overlay that keeps requesting frames for
+ * a surface that no longer exists is sixty repaints a second of nothing.
+ */
+export declare class EstuarineGhostOverlay extends Overlay {
+    static overlayName: string;
+    /** Element id → `performance.now()` at the moment its toggle flipped. */
+    private readonly _reveals;
+    /** Armed only while something is still revealing. */
+    private _frame;
+    /**
+     * Whether the renderer this overlay paints into is gone. The manager below
+     * lives on the gfx scope and keeps its subscriptions on the surface MODEL,
+     * which outlives the surface COMPONENT — so a toggle can perfectly well be
+     * flipped after this overlay was torn down.
+     */
+    private _detached;
+    private readonly _onFrame;
+    /** Whether any reveal is still inside its window at `now`. */
+    isAnimating(now: number): boolean;
+    /**
+     * Start (or restart) the reveal on `elementId`.
+     *
+     * Reduced motion is honoured HERE rather than at the call site, so every
+     * future trigger inherits it: the permanent ghost the renderer paints is
+     * already the end state, so declining to animate is a complete no-op and not
+     * a degraded mode.
+     */
+    reveal(elementId: string): void;
+    /**
+     * Repaint, and keep repainting while a reveal is inside its window. Stops on
+     * its own: an idle board requests no animation frame at all.
+     */
+    private _schedule;
+    private _cancelFrame;
+    private _forget;
+    setRenderer(renderer: CanvasRenderer | null): void;
+    clear(): void;
+    dispose(): void;
+    render(ctx: CanvasRenderingContext2D, _rc: RoughCanvas): void;
+}
+/**
+ * Turns "a curve toggle just went from off to on" into a reveal.
+ *
+ * The transition is read from the `elementUpdated` payload — `props` carries
+ * the new value, `oldValues` the previous one — and BOTH halves are required:
+ * `props.showVolatile === true` alone also fires when the map is created, when
+ * a remote peer syncs an unrelated change, or when the value is rewritten
+ * identically. Only a genuine `false → true` flip is a user asking to see a
+ * line appear.
+ */
+export declare class EstuarineGhostManager extends InteractivityExtension {
+    static key: string;
+    private _subscriptions;
+    private _disposeSurfaceEffect;
+    private get _overlay();
+    mounted(): void;
+    unmounted(): void;
+    private _unsubscribe;
+    private _resubscribe;
+}

package/dist/estuarine/ghost-overlay.js

@@ -0,0 +1,277 @@
+import { Overlay, OverlayIdentifier, } from '@formicoidea/labre-core/blocks/surface';
+import { EstuarineElementModel } from '@formicoidea/labre-core/model';
+import { InteractivityExtension } from '@formicoidea/labre-core/std/gfx';
+import { effect } from '@preact/signals-core';
+import { applyEstuarineTransform, estuarineCurves, GHOST_DASH, } from './element-renderer.js';
+/**
+ * The REVEAL — the ~600 ms animation that plays when an Estuarine curve is
+ * switched back on (WS4, PO arbitration of 26/08/2026).
+ *
+ * The permanent look of a curve is now a discreet ghost (`GHOST_ALPHA`, dashed:
+ * see `./element-renderer.ts`). That is the right resting state and the wrong
+ * ARRIVAL: a user who clicks "show the Volatile line" and gets a 45 %-opacity
+ * dashed curve on a busy map can reasonably fail to notice anything happened,
+ * and conclude the toggle is broken. So the flip is animated — the dashes march
+ * along the path while a second, brighter stroke rides above the ghost, then
+ * decays away and leaves the ghost alone.
+ *
+ * An OVERLAY rather than a renderer change, for the same reasons the validation
+ * bracket is one: it touches no element model, writes nothing to the document,
+ * creates no undo entry, and holds nothing that could survive a reload. "When
+ * did I last flip this toggle" is session state and must never reach the
+ * document.
+ */
+/** How long the reveal stroke takes to march across the curve. */
+export const GHOST_REVEAL_MS = 600;
+/** How long it then takes to fade back into the permanent ghost. */
+export const GHOST_DECAY_MS = 200;
+/** Total life of one reveal. */
+export const GHOST_TOTAL_MS = GHOST_REVEAL_MS + GHOST_DECAY_MS;
+/**
+ * Reference-space units the dash pattern travels during the reveal — four
+ * periods of {@link GHOST_DASH}, so the march reads as motion rather than as a
+ * jitter.
+ */
+export const GHOST_DASH_TRAVEL = 4 * (GHOST_DASH[0] + GHOST_DASH[1]);
+/**
+ * Peak opacity of the reveal stroke, ON TOP of the ghost the renderer already
+ * painted. Chosen so the two together reach a full-strength line at the crest
+ * and never exceed it.
+ */
+export const GHOST_PEAK_ALPHA = 0.55;
+/**
+ * The whole animation, as a pure function of elapsed milliseconds.
+ *
+ * Pure and exported on purpose: it is the only part of this file that has an
+ * opinion, and a function taking a number is testable without a canvas, a
+ * surface, a DI container or a clock. The overlay below is then reduced to
+ * "ask this, then stroke" — which is the part that cannot go wrong quietly.
+ *
+ * Out-of-range input is answered rather than trusted: a negative or non-finite
+ * elapsed (a clock that went backwards, a `performance.now()` mock) paints
+ * nothing instead of throwing or flashing.
+ */
+export function ghostRevealFrame(elapsed) {
+    if (!Number.isFinite(elapsed) || elapsed <= 0) {
+        return { alpha: 0, dashOffset: 0, done: false };
+    }
+    if (elapsed >= GHOST_TOTAL_MS) {
+        return { alpha: 0, dashOffset: 0, done: true };
+    }
+    // The march stops when the reveal does; the decay fades a still line.
+    const marched = Math.min(elapsed, GHOST_REVEAL_MS) / GHOST_REVEAL_MS;
+    const dashOffset = -GHOST_DASH_TRAVEL * marched;
+    const alpha = elapsed <= GHOST_REVEAL_MS
+        ? GHOST_PEAK_ALPHA * marched
+        : GHOST_PEAK_ALPHA * (1 - (elapsed - GHOST_REVEAL_MS) / GHOST_DECAY_MS);
+    return { alpha, dashOffset, done: false };
+}
+/**
+ * Whether the user has asked their system for less motion.
+ *
+ * Read at every reveal rather than cached: the setting can change mid-session
+ * (an OS toggle, a devtools emulation), and the answer costs one media query.
+ * `globalThis.matchMedia` is optional-chained because this module is imported
+ * by unit specs running under Node.
+ */
+export function prefersReducedMotion() {
+    return (globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false);
+}
+/**
+ * Paints the reveal stroke over whatever curves are currently on.
+ *
+ * The rAF loop is copied from `ValidationOverlay`, deliberately and including
+ * its two guards: the clock is never armed when nothing is animating, and a
+ * detached renderer stops it dead. An overlay that keeps requesting frames for
+ * a surface that no longer exists is sixty repaints a second of nothing.
+ */
+export class EstuarineGhostOverlay extends Overlay {
+    constructor() {
+        super(...arguments);
+        /** Element id → `performance.now()` at the moment its toggle flipped. */
+        this._reveals = new Map();
+        /** Armed only while something is still revealing. */
+        this._frame = null;
+        /**
+         * Whether the renderer this overlay paints into is gone. The manager below
+         * lives on the gfx scope and keeps its subscriptions on the surface MODEL,
+         * which outlives the surface COMPONENT — so a toggle can perfectly well be
+         * flipped after this overlay was torn down.
+         */
+        this._detached = false;
+        this._onFrame = () => {
+            this._frame = null;
+            this._schedule();
+        };
+    }
+    static { this.overlayName = 'estuarine-ghost'; }
+    /** Whether any reveal is still inside its window at `now`. */
+    isAnimating(now) {
+        for (const start of this._reveals.values()) {
+            if (!ghostRevealFrame(now - start).done)
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Start (or restart) the reveal on `elementId`.
+     *
+     * Reduced motion is honoured HERE rather than at the call site, so every
+     * future trigger inherits it: the permanent ghost the renderer paints is
+     * already the end state, so declining to animate is a complete no-op and not
+     * a degraded mode.
+     */
+    reveal(elementId) {
+        if (this._detached)
+            return;
+        if (prefersReducedMotion())
+            return;
+        this._reveals.set(elementId, performance.now());
+        this._schedule();
+    }
+    /**
+     * Repaint, and keep repainting while a reveal is inside its window. Stops on
+     * its own: an idle board requests no animation frame at all.
+     */
+    _schedule() {
+        if (this._detached)
+            return;
+        this.refresh();
+        if (this._frame !== null)
+            return;
+        if (!this.isAnimating(performance.now()))
+            return;
+        this._frame = requestAnimationFrame(this._onFrame);
+    }
+    _cancelFrame() {
+        if (this._frame === null)
+            return;
+        cancelAnimationFrame(this._frame);
+        this._frame = null;
+    }
+    _forget() {
+        this._cancelFrame();
+        this._reveals.clear();
+    }
+    setRenderer(renderer) {
+        this._detached = renderer === null;
+        super.setRenderer(renderer);
+    }
+    clear() {
+        this._forget();
+        super.clear();
+    }
+    dispose() {
+        this._detached = true;
+        this._forget();
+        super.dispose();
+    }
+    render(ctx, _rc) {
+        if (this._reveals.size === 0)
+            return;
+        const surface = this.gfx.surface;
+        if (!surface)
+            return;
+        const now = performance.now();
+        for (const [id, start] of [...this._reveals]) {
+            const frame = ghostRevealFrame(now - start);
+            if (frame.done) {
+                this._reveals.delete(id);
+                continue;
+            }
+            if (frame.alpha <= 0)
+                continue;
+            const model = surface.getElementById(id);
+            // Deleted, or replaced by something else entirely: the reveal is about
+            // an element that no longer exists.
+            if (!(model instanceof EstuarineElementModel)) {
+                this._reveals.delete(id);
+                continue;
+            }
+            const [x, y, w, h] = model.deserializedXYWH;
+            ctx.save();
+            // Model space, exactly like the element renderer: translate to the
+            // element, rotate about its centre, then enter the STRETCHED reference
+            // frame through the shared transform — the reveal stroke has to sit on
+            // the ghost to the pixel, so the two go through one function, never two
+            // copies of the same arithmetic. Recomputed at PAINT time rather than
+            // captured at reveal time, so the stroke follows a map the user drags,
+            // rotates or resizes mid-animation.
+            ctx.translate(x, y);
+            ctx.translate(w / 2, h / 2);
+            ctx.rotate((model.rotate * Math.PI) / 180);
+            ctx.translate(-w / 2, -h / 2);
+            const fit = applyEstuarineTransform(ctx, w, h);
+            ctx.lineCap = 'round';
+            ctx.lineJoin = 'round';
+            ctx.globalAlpha = frame.alpha;
+            ctx.setLineDash([...GHOST_DASH]);
+            ctx.lineDashOffset = frame.dashOffset;
+            for (const curve of estuarineCurves()) {
+                if (!model[curve.visibleProp])
+                    continue;
+                ctx.strokeStyle = curve.color;
+                ctx.lineWidth = curve.width * fit.curveLineScale;
+                ctx.stroke(curve.path);
+            }
+            ctx.restore();
+        }
+    }
+}
+/** The three toggles a reveal can be triggered by. */
+const SHOW_PROPS = [
+    'showLiminal',
+    'showVolatile',
+    'showCounterfactual',
+];
+/**
+ * Turns "a curve toggle just went from off to on" into a reveal.
+ *
+ * The transition is read from the `elementUpdated` payload — `props` carries
+ * the new value, `oldValues` the previous one — and BOTH halves are required:
+ * `props.showVolatile === true` alone also fires when the map is created, when
+ * a remote peer syncs an unrelated change, or when the value is rewritten
+ * identically. Only a genuine `false → true` flip is a user asking to see a
+ * line appear.
+ */
+export class EstuarineGhostManager extends InteractivityExtension {
+    constructor() {
+        super(...arguments);
+        this._subscriptions = [];
+        this._disposeSurfaceEffect = null;
+    }
+    static { this.key = 'estuarine-ghost'; }
+    get _overlay() {
+        return this.std.getOptional(OverlayIdentifier(EstuarineGhostOverlay.overlayName));
+    }
+    mounted() {
+        // The surface is a SIGNAL, not a fact: it can be null at mount and arrive
+        // later, and it is replaced if the surface block is.
+        this._disposeSurfaceEffect = effect(() => {
+            this._resubscribe(this.gfx.surface$.value);
+        });
+    }
+    unmounted() {
+        this._disposeSurfaceEffect?.();
+        this._disposeSurfaceEffect = null;
+        this._unsubscribe();
+        super.unmounted();
+    }
+    _unsubscribe() {
+        for (const subscription of this._subscriptions)
+            subscription.unsubscribe();
+        this._subscriptions = [];
+    }
+    _resubscribe(surface) {
+        this._unsubscribe();
+        if (!surface)
+            return;
+        this._subscriptions.push(surface.elementUpdated.subscribe(({ id, props, oldValues }) => {
+            if (!props || !oldValues)
+                return;
+            const flipped = SHOW_PROPS.some(prop => props[prop] === true && oldValues[prop] === false);
+            if (flipped)
+                this._overlay?.reveal(id);
+        }));
+    }
+}

package/dist/estuarine/nudges.d.ts

@@ -0,0 +1,41 @@
+import type { QualityNudge } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * Estuarine **map quality** — the checklist, and this framework's ENTIRE
+ * contribution to validation (WS4).
+ *
+ * ## No rules, and therefore no profiles (PO arbitration, 26/08/2026)
+ *
+ * The 26/08 study looked for deterministic rules on an Estuarine map and found
+ * none worth shipping. Everything an Estuarine session decides — where the
+ * counter-factual line falls, which constraints are volatile, whether a
+ * constraint is a constructor or an actor — is a judgement the group makes out
+ * loud; an algorithm that claimed to check any of it would be lying about the
+ * one thing the method exists to produce.
+ *
+ * A severity profile is a dial over rules. With no rule to dial, a profile
+ * picker is a control that decides nothing: three entries, no observable
+ * effect, and a user reasonably concluding that the tool checks something it
+ * does not. So this framework ships **no `profiles.ts`** — deliberately, not
+ * by omission. The profiles will be born WITH the first rule, if one is ever
+ * born; until then the file's absence is the honest statement.
+ *
+ * What does reach the user is this checklist, offered on the map because
+ * `ValidationFrameworkExtension` declares `estuarine:map` a root instance
+ * (WS0.3) — the gate no longer needs a rule to exist.
+ *
+ * Registered from the flag-gated `CynefinEstuarineViewExtension`, beside the
+ * framework declaration: a checklist is tooling. Switching the flag off takes
+ * it away and leaves the ticks written on the map, unread, until it comes back.
+ */
+/**
+ * **Q1–Q4** — the four things an Estuarine map needs in order to do its job,
+ * and that no algorithm can check.
+ *
+ * Q1 and Q2 are about the two lines that make the map a map: a counter-factual
+ * line nobody argued over is a curve, not a boundary, and an undelimited
+ * volatile zone leaves every constraint equally urgent. Q3 is the method's own
+ * discipline — above the counter-factual line you do not act, you Monitor,
+ * Research or Request. Q4 is the typing the hexagons carry in the group's head
+ * and nowhere in the document.
+ */
+export declare const ESTUARINE_NUDGES: readonly QualityNudge[];

package/dist/estuarine/nudges.js

@@ -0,0 +1,69 @@
+/**
+ * Estuarine **map quality** — the checklist, and this framework's ENTIRE
+ * contribution to validation (WS4).
+ *
+ * ## No rules, and therefore no profiles (PO arbitration, 26/08/2026)
+ *
+ * The 26/08 study looked for deterministic rules on an Estuarine map and found
+ * none worth shipping. Everything an Estuarine session decides — where the
+ * counter-factual line falls, which constraints are volatile, whether a
+ * constraint is a constructor or an actor — is a judgement the group makes out
+ * loud; an algorithm that claimed to check any of it would be lying about the
+ * one thing the method exists to produce.
+ *
+ * A severity profile is a dial over rules. With no rule to dial, a profile
+ * picker is a control that decides nothing: three entries, no observable
+ * effect, and a user reasonably concluding that the tool checks something it
+ * does not. So this framework ships **no `profiles.ts`** — deliberately, not
+ * by omission. The profiles will be born WITH the first rule, if one is ever
+ * born; until then the file's absence is the honest statement.
+ *
+ * What does reach the user is this checklist, offered on the map because
+ * `ValidationFrameworkExtension` declares `estuarine:map` a root instance
+ * (WS0.3) — the gate no longer needs a rule to exist.
+ *
+ * Registered from the flag-gated `CynefinEstuarineViewExtension`, beside the
+ * framework declaration: a checklist is tooling. Switching the flag off takes
+ * it away and leaves the ticks written on the map, unread, until it comes back.
+ */
+/**
+ * **Q1–Q4** — the four things an Estuarine map needs in order to do its job,
+ * and that no algorithm can check.
+ *
+ * Q1 and Q2 are about the two lines that make the map a map: a counter-factual
+ * line nobody argued over is a curve, not a boundary, and an undelimited
+ * volatile zone leaves every constraint equally urgent. Q3 is the method's own
+ * discipline — above the counter-factual line you do not act, you Monitor,
+ * Research or Request. Q4 is the typing the hexagons carry in the group's head
+ * and nowhere in the document.
+ */
+export const ESTUARINE_NUDGES = [
+    {
+        id: 'estuarine.q1-counterfactual',
+        framework: 'estuarine',
+        labelKey: 'com.labre.estuarine.quality.counterfactual',
+        fallback: 'The counter-factual line has been negotiated and drawn by the group',
+        order: 1,
+    },
+    {
+        id: 'estuarine.q2-volatile-zone',
+        framework: 'estuarine',
+        labelKey: 'com.labre.estuarine.quality.volatile-zone',
+        fallback: 'The volatile zone has been delimited',
+        order: 2,
+    },
+    {
+        id: 'estuarine.q3-strategies',
+        framework: 'estuarine',
+        labelKey: 'com.labre.estuarine.quality.strategies',
+        fallback: 'Every element above the counter-factual line has a Monitor, Research or Request strategy',
+        order: 3,
+    },
+    {
+        id: 'estuarine.q4-hexagon-types',
+        framework: 'estuarine',
+        labelKey: 'com.labre.estuarine.quality.hexagon-types',
+        fallback: 'Every hexagon is typed: constraint, constructor or actor',
+        order: 4,
+    },
+];

package/dist/estuarine/roles.d.ts

@@ -0,0 +1,48 @@
+import type { RoleDefs } from '@formicoidea/labre-core/std/gfx';
+/**
+ * Estuarine role vocabulary (WS4).
+ *
+ * Two roles, and deliberately only two: the MAP — the axes and the three
+ * reference curves an Estuarine session is read against — and the CONSTRAINT
+ * hexagon the group drops onto it. Everything else on such a board (the
+ * captions, the stickies, a free arrow drawn to link two hexagons) is a plain
+ * drawing and stays neutral, because nothing in this framework has anything to
+ * say about it.
+ *
+ * ## Cynefin declares NO role, and never will
+ *
+ * The two frameworks share this package and share nothing else here. The PO's
+ * arbitration of 26/08/2026 is that Cynefin is out of the validation perimeter
+ * for good: its four domains are a sense-making device, not a notation with
+ * rules, so giving its background a role would advertise tooling — a profile
+ * picker, a quality checklist — over a framework that has nothing to check.
+ * A role with no consumer is a promise the product does not keep.
+ *
+ * ## What a role buys Estuarine, which ships no rule either
+ *
+ * The map role is what makes the map a ROOT INSTANCE: it is handed to
+ * `ValidationFrameworkExtension` so the engine can answer "is this element
+ * somebody's frame?" and offer the Map quality checklist on it. That gate used
+ * to be derived from the registered rules alone, which is exactly why WS0.3
+ * gave it a second, explicit source — see `ValidationFrameworkDef`.
+ *
+ * The constraint role earns its keep on its own: a hexagon is a plain polygon
+ * shape on the canvas, so nothing about its geometry says what it means, and
+ * the first rule this framework ever writes will be written against this role
+ * rather than against `shapeType === 'polygon'`.
+ *
+ * ## Compatibility
+ *
+ * No backfill (promise #71): maps and hexagons drawn before today carry no
+ * role, are nobody's frame, and go on painting exactly as they did. They simply
+ * offer no checklist until they are redrawn.
+ */
+/** Every role this framework declares. */
+export type EstuarineRole = 'map' | 'constraint';
+export type EstuarineRoleId = `estuarine:${EstuarineRole}`;
+/** Role ids, keyed by the name used at the creation sites. */
+export declare const ESTUARINE_ROLE: {
+    readonly map: "estuarine:map";
+    readonly constraint: "estuarine:constraint";
+};
+export declare const ESTUARINE_ROLES: RoleDefs;

package/dist/estuarine/roles.js

@@ -0,0 +1,28 @@
+/** Role ids, keyed by the name used at the creation sites. */
+export const ESTUARINE_ROLE = {
+    map: 'estuarine:map',
+    constraint: 'estuarine:constraint',
+};
+const DEFS = [
+    // The map itself: the e / t axes and the three curves everything else is
+    // positioned against. A frame, so it specialises nothing — a rule written on
+    // `estuarine:constraint` must never match the map it is measured against.
+    {
+        id: ESTUARINE_ROLE.map,
+        kind: 'node',
+        labelKey: 'com.labre.estuarine.role.map',
+        labelFallback: 'Estuarine map',
+    },
+    // The hexi constraint. A `node`: it is measured by its bounds, which is
+    // exactly what an Estuarine reading is about — where on the energy/time
+    // plane the group placed this constraint.
+    {
+        id: ESTUARINE_ROLE.constraint,
+        kind: 'node',
+        labelKey: 'com.labre.estuarine.role.constraint',
+        labelFallback: 'Constraint',
+    },
+];
+// Null prototype: a lookup table keyed by ids that may one day come from
+// host-supplied packs, so `defs['toString']` must not resolve.
+export const ESTUARINE_ROLES = Object.assign(Object.create(null), Object.fromEntries(DEFS.map(def => [def.id, def])));

package/dist/estuarine/toolbar/config.js

@@ -3,13 +3,67 @@ import { EstuarineElementModel } from '@formicoidea/labre-core/model';
 import { ToolbarModuleExtension, } from '@formicoidea/labre-core/shared/services';
 import { BlockFlavourIdentifier } from '@formicoidea/labre-core/std';
 import { html } from 'lit';
-const ResizeIcon = html `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M9 5H5v4M15 19h4v-4" /><path d="M5 5l6 6M19 19l-6-6" /></svg>`;
+const ResizeIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.6"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M9 5H5v4M15 19h4v-4" />
+  <path d="M5 5l6 6M19 19l-6-6" />
+</svg>`;
 // All curve icons use currentColor so the toolbar can grey them when inactive;
 // they are distinguished by shape (wave / arc / hooked curve).
-const LiminalIcon = html `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M3 13c3-6 6 4 9 0s6-6 9 0" /></svg>`;
-const VolatileIcon = html `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M7 4a9 9 0 0 1 0 18" /></svg>`;
-const CounterfactualIcon = html `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="M4 7c7 0 11 4 12 14" /></svg>`;
-const AxisIcon = html `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3v18M6 12h15" /><path d="M3 6l3-3 3 3M18 9l3 3-3 3" /></svg>`;
+const LiminalIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+>
+  <path d="M3 13c3-6 6 4 9 0s6-6 9 0" />
+</svg>`;
+const VolatileIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+>
+  <path d="M7 4a9 9 0 0 1 0 18" />
+</svg>`;
+const CounterfactualIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+>
+  <path d="M4 7c7 0 11 4 12 14" />
+</svg>`;
+const AxisIcon = html `<svg
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.6"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M6 3v18M6 12h15" />
+  <path d="M3 6l3-3 3 3M18 9l3 3-3 3" />
+</svg>`;
 function booleanToggle(id, tooltip, icon, prop) {
     return {
         id,