@formicoidea/labre-framework-cynefin 0.31.0 → 0.33.0

package/dist/estuarine/element-renderer.js

@@ -1,83 +1,186 @@
 import { ElementRendererExtension, } from '@formicoidea/labre-core/blocks/surface';
-import { FONT_FAMILY, refScale } from '../utils.js';
+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';
+/**
+ * The three reference curves are drawn as a permanent GHOST (PO arbitration,
+ * 26/08/2026): dashed, translucent, never solid again.
+ *
+ * The reasoning is what an Estuarine line IS. Liminal, Volatile and
+ * Counter-factual are not measurements — they are boundaries a group argues
+ * itself into, and the printed map is a support for that argument, not a
+ * verdict about where the boundary lies. A solid stroke made the tool's own
+ * curve look like the answer, and the group's negotiated line (drawn on top,
+ * with a brush or a connector) look like an annotation on it. Dashing the
+ * reference inverts that: the tool suggests, the group states.
+ *
+ * The toggles keep their meaning exactly — ON shows the ghost, OFF hides it.
+ * What changed is only how ON looks, plus the ~600 ms reveal animation the
+ * moment a toggle flips (see `./ghost-overlay.ts`), which exists so a line
+ * that comes back at 45 % opacity is still SEEN arriving.
+ *
+ * The legends stay solid. A label is a name, not a boundary.
+ */
+/** Dash pattern of the ghost, in reference-space units. */
+export const GHOST_DASH = [12, 10];
+/** Opacity of the permanent ghost. */
+export const GHOST_ALPHA = 0.45;
+/**
+ * The three curves, with their `Path2D` built ONCE.
+ *
+ * A lazy memo (`??=`) rather than a module-level constant, and that is not a
+ * micro-optimisation: `Path2D` does not exist under Node, and `./consts.ts` —
+ * which this module imports — is pulled in by the unit specs. Building the
+ * paths at import time would make merely importing this framework's constants
+ * throw in every non-browser environment. Built on the first PAINT instead,
+ * which by definition happens on a canvas.
+ */
+let _curves;
+export function estuarineCurves() {
+    return (_curves ??= [
+        {
+            key: 'liminal',
+            path: new Path2D(LIMINAL_PATH),
+            color: COLORS.liminal,
+            width: LIMINAL_WIDTH,
+            visibleProp: 'showLiminal',
+        },
+        {
+            key: 'volatile',
+            path: new Path2D(VOLATILE_PATH),
+            color: COLORS.volatile,
+            width: VOLATILE_WIDTH,
+            visibleProp: 'showVolatile',
+        },
+        {
+            key: 'counterfactual',
+            path: new Path2D(COUNTERFACTUAL_PATH),
+            color: COLORS.counterfactual,
+            width: COUNTERFACTUAL_WIDTH,
+            visibleProp: 'showCounterfactual',
+        },
+    ]);
+}
+export function estuarineFit(w, h) {
+    const sx = w / REF_W;
+    const sy = h / REF_H;
+    const strokeScale = Math.sqrt(sx * sy);
+    return { sx, sy, strokeScale, curveLineScale: strokeScale / ((sx + sy) / 2) };
+}
+/**
+ * Put `ctx` into the map's STRETCHED reference space, where the authored
+ * geometry (a `Path2D` built from `./consts.ts`) lands on the element's real
+ * bounds in both directions.
+ *
+ * The single source of truth for that transform, and it has to stay single:
+ * the ghost overlay paints the very same curves one layer above and must land
+ * on them to the pixel. Everything that must NOT be stretched — axes,
+ * arrowheads, legends — is drawn outside it, in element coordinates, from the
+ * same {@link EstuarineFit}.
+ */
+export function applyEstuarineTransform(ctx, w, h) {
+    const fit = estuarineFit(w, h);
+    ctx.scale(fit.sx, fit.sy);
+    return fit;
+}
 /**
  * Canvas renderer for the Estuarine framework map — reproduces the official SVG:
  * the e (vertical, double-headed) / t (horizontal, single-headed) axes and the
  * three reference curves (Liminal / Volatile / Counter-factual), each with its
- * legend and individually hideable. Drawn in the fixed reference space and
- * scaled uniformly to the element bounds.
+ * legend and individually hideable.
+ *
+ * Two spaces, and which one a mark belongs to is the whole design:
+ *
+ * - **Element coordinates**, entered by mapping each authored coordinate
+ *   through {@link EstuarineFit} by hand (`ax` / `ay` below): the axes, their
+ *   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.
+ * - **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.
  */
 export const estuarine = (model, ctx, matrix) => {
     const [, , w, h] = model.deserializedXYWH;
     const cx = w / 2;
     const cy = h / 2;
-    ctx.setTransform(matrix.translateSelf(cx, cy).rotateSelf(model.rotate).translateSelf(-cx, -cy));
-    const { s, ox, oy } = refScale(w, h, REF_W, REF_H);
-    ctx.translate(ox, oy);
-    ctx.scale(s, s);
+    ctx.setTransform(matrix
+        .translateSelf(cx, cy)
+        .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 y → element y. */
+    const ay = (y) => y * fit.sy;
     ctx.lineCap = 'round';
     ctx.lineJoin = 'round';
     // ── Axes ────────────────────────────────────────────────────────────
+    // Drawn in element coordinates so the e axis spans the real height and the
+    // t axis the real width, while `lineWidth` stays one honest thickness
+    // instead of being fattened in whichever direction the map was pulled.
     ctx.strokeStyle = COLORS.axis;
     ctx.fillStyle = COLORS.axis;
-    ctx.lineWidth = AXIS_WIDTH;
+    ctx.lineWidth = AXIS_WIDTH * fit.strokeScale;
     ctx.beginPath();
-    ctx.moveTo(E_AXIS.x, E_AXIS.y1);
-    ctx.lineTo(E_AXIS.x, E_AXIS.y2);
-    ctx.moveTo(T_AXIS.x1, T_AXIS.y);
-    ctx.lineTo(T_AXIS.x2, T_AXIS.y);
+    ctx.moveTo(ax(E_AXIS.x), ay(E_AXIS.y1));
+    ctx.lineTo(ax(E_AXIS.x), ay(E_AXIS.y2));
+    ctx.moveTo(ax(T_AXIS.x1), ay(T_AXIS.y));
+    ctx.lineTo(ax(T_AXIS.x2), ay(T_AXIS.y));
     ctx.stroke();
-    for (const [[tx, ty], [ax, ay], [bx, by]] of ARROWHEADS) {
+    // 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;
         ctx.beginPath();
-        ctx.moveTo(tx, ty);
-        ctx.lineTo(ax, ay);
-        ctx.lineTo(bx, by);
+        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.closePath();
         ctx.fill();
     }
     // Uppercase legend (centre-anchored, alphabetic baseline, letter-spaced).
+    // Anchored proportionally, typed isotropically — never inside the stretch.
     const hasSpacing = 'letterSpacing' in ctx;
     const legend = (l) => {
         ctx.fillStyle = l.color;
-        ctx.font = `600 ${l.size}px ${FONT_FAMILY}`;
+        ctx.font = `600 ${l.size * fit.strokeScale}px ${FONT_FAMILY}`;
         ctx.textAlign = 'center';
         ctx.textBaseline = 'alphabetic';
-        if (hasSpacing)
-            ctx.letterSpacing = `${LABEL_LETTER_SPACING}px`;
-        ctx.fillText(l.text, l.x, l.y);
+        if (hasSpacing) {
+            ctx.letterSpacing = `${LABEL_LETTER_SPACING * fit.strokeScale}px`;
+        }
+        ctx.fillText(l.text, ax(l.x), ay(l.y));
         if (hasSpacing)
             ctx.letterSpacing = '0px';
     };
-    // ── Liminal (green) ─────────────────────────────────────────────────
-    if (model.showLiminal) {
-        ctx.strokeStyle = COLORS.liminal;
-        ctx.lineWidth = LIMINAL_WIDTH;
-        ctx.stroke(new Path2D(LIMINAL_PATH));
-        legend(LABELS.liminal);
-    }
-    // ── Volatile (red) ──────────────────────────────────────────────────
-    if (model.showVolatile) {
-        ctx.strokeStyle = COLORS.volatile;
-        ctx.lineWidth = VOLATILE_WIDTH;
-        ctx.stroke(new Path2D(VOLATILE_PATH));
-        legend(LABELS.volatile);
-    }
-    // ── Counter-factual (dark) ──────────────────────────────────────────
-    if (model.showCounterfactual) {
-        ctx.strokeStyle = COLORS.counterfactual;
-        ctx.lineWidth = COUNTERFACTUAL_WIDTH;
-        ctx.stroke(new Path2D(COUNTERFACTUAL_PATH));
-        legend(LABELS.counterfactual);
+    // ── The three curves, as ghosts ─────────────────────────────────────
+    // `save`/`restore` around each one so neither the stretch nor the dash nor
+    // the alpha leaks onto the legend that follows it — a legend is a name, and
+    // names stay solid, upright and undeformed.
+    for (const curve of estuarineCurves()) {
+        if (!model[curve.visibleProp])
+            continue;
+        ctx.save();
+        applyEstuarineTransform(ctx, w, h);
+        ctx.strokeStyle = curve.color;
+        ctx.lineWidth = curve.width * fit.curveLineScale;
+        ctx.globalAlpha = GHOST_ALPHA;
+        ctx.setLineDash([...GHOST_DASH]);
+        ctx.stroke(curve.path);
+        ctx.restore();
+        legend(LABELS[curve.key]);
     }
     // ── Italic e / t axis letters ───────────────────────────────────────
     if (model.showAxisLabels) {
         ctx.fillStyle = COLORS.axisLabel;
-        ctx.font = `italic 700 ${AXIS_LABELS.size}px Georgia, serif`;
+        ctx.font = `italic 700 ${AXIS_LABELS.size * fit.strokeScale}px Georgia, serif`;
         ctx.textAlign = 'left';
         ctx.textBaseline = 'alphabetic';
-        ctx.fillText(AXIS_LABELS.e.text, AXIS_LABELS.e.x, AXIS_LABELS.e.y);
-        ctx.fillText(AXIS_LABELS.t.text, AXIS_LABELS.t.x, AXIS_LABELS.t.y);
+        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));
     }
 };
 export const EstuarineRendererExtension = ElementRendererExtension('estuarine', estuarine);

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);
+        }));
+    }
+}