nodality 1.1.11 → 1.1.13

package/lib/morph-node.js

@@ -1,5 +1,5 @@
 /*!
- * nodality v1.1.11
+ * nodality v1.1.13
  * (c) 2026 Filip Vabrousek
  * License: MIT
  */
@@ -121,6 +121,80 @@ const chainFor = (effect) => {
     try { return preset(effect) || []; } catch (e) { return []; }
 };
 
+const norm = (t) => String(t || "").replace(/\s+/g, " ").trim().toLowerCase();
+
+/**
+ * A morph node, in one shape: a list of EDGES.
+ *
+ * A node is written either as a single hop —
+ *
+ *     { op: "morph", from: "topnav", to: { About: "about" } }
+ *
+ * — or as a chain, which is the same thing with more than one edge:
+ *
+ *     { op: "morph", effect: "t-vhs", duration: 900, back: true,
+ *       chain: [ { from: "topnav",  to: { About: "about" } },
+ *                { from: "about",   to: { Detail: "about-detail" } } ] }
+ *
+ * Both arrive here as a list, so there is exactly one code path below and
+ * the single hop is not a special case of anything. `chain` entries are
+ * EDGES rather than keyframes: entry two does not happen after entry one,
+ * it is reachable FROM the state entry one lands on. That is why they
+ * carry no ordinal — array order is already order, and a number would
+ * claim a sequence the graph does not have.
+ *
+ * Per-edge options fall back to the node, so the common settings are
+ * written once and an edge overrides only what differs.
+ */
+const normalizeEdges = (m) => {
+    const raw = Array.isArray(m.chain) && m.chain.length
+        ? m.chain
+        : [{ from: m.from, to: m.to }];
+
+    return raw.map((e) => {
+        const opt = (key, fallback) =>
+            (e[key] !== undefined ? e[key]
+                : m[key] !== undefined ? m[key] : fallback);
+
+        // `to` takes two forms, and the object form is the one that
+        // survives a real navbar:
+        //
+        //   ["work", "about"]                by POSITION — link i goes to i
+        //   { Work: "work", About: "about" } by LABEL — link text decides
+        //
+        // Position looks tidier and is wrong for anything but a toy nav. A
+        // responsive bar renders a DIFFERENT set of links per breakpoint
+        // (About/Services/Contact wide, About/About/Contact collapsed), so
+        // index i is not the same destination at two window sizes. And a
+        // nav that repeats a label sends two links to one arbitrary place.
+        // Labels are what the user is actually reading and clicking.
+        const byLabel = e.to && !Array.isArray(e.to) && typeof e.to === "object"
+            ? e.to : null;
+        const toIds = byLabel
+            ? [...new Set(Object.values(e.to))]
+            : (Array.isArray(e.to) ? e.to : [e.to]);
+
+        const labelToId = new Map();
+        if (byLabel) {
+            for (const [label, id] of Object.entries(e.to)) {
+                labelToId.set(norm(label), id);
+            }
+        }
+
+        return {
+            from: e.from, byLabel, toIds, labelToId,
+            effect: opt("effect"),
+            duration: opt("duration", 900),
+            // Written as `!== false` rather than a truthy test: the
+            // documented default is on, and only an explicit false is a
+            // request to leave the destination without a way back.
+            back: opt("back", true) !== false,
+            live: opt("live") === true,
+            fade: opt("fade", "morph"),
+        };
+    });
+};
+
 /**
  * @param {Element} mount     the container Des rendered into
  * @param {object[]} elements the E array, in order
@@ -148,39 +222,43 @@ function applyMorphNodes(mount, elements, nodes) {
 }
 
 function setUpMorph(mount, m, resolve) {
-    const fromEl = resolve(m.from);
-
-    // `to` takes two forms, and the object form is the one that survives
-    // a real navbar:
+    // ── the controller's model ───────────────────────────────────────
     //
-    //   ["work", "about"]              by POSITION — link i goes to i
-    //   { Work: "work", About: "about" }  by LABEL — link text decides
+    // One controller owns one stage and EVERY state in the graph. The
+    // alternative — a controller per edge — cannot work: edge two's
+    // source is edge one's destination, which the first controller has
+    // already detached as a template, so two controllers would fight over
+    // the same element and stack two block-level stages.
     //
-    // Position looks tidier and is wrong for anything but a toy nav. A
-    // responsive bar renders a DIFFERENT set of links per breakpoint
-    // (About/Services/Contact wide, About/About/Contact collapsed), so
-    // index i is not the same destination at two window sizes. And a nav
-    // that repeats a label sends two links to one arbitrary place. Labels
-    // are what the user is actually reading and clicking.
-    const byLabel = m.to && !Array.isArray(m.to) && typeof m.to === "object"
-        ? m.to : null;
-    const toIds = byLabel
-        ? [...new Set(Object.values(m.to))]
-        : (Array.isArray(m.to) ? m.to : [m.to]);
-    const toEls = toIds.map(resolve);
-    if (!fromEl || !toEls.some(Boolean)) {
-        console.warn("[nodality] morph: could not resolve", m.from, "->", toIds);
-        return null;
-    }
-    const norm = (t) => String(t || "").replace(/\s+/g, " ").trim().toLowerCase();
-    const labelToIndex = new Map();
-    if (byLabel) {
-        for (const [label, id] of Object.entries(m.to)) {
-            const i = toIds.indexOf(id);
-            if (i >= 0) labelToIndex.set(norm(label), i);
+    // States are keyed by id rather than held in a positional array,
+    // because an edge names its destinations by id and a chain's second
+    // edge starts from a state the first edge introduced. Position means
+    // nothing once there is more than one source.
+    const edges = normalizeEdges(m);
+    const rootEdge = edges[0];
+    const rootId = rootEdge && rootEdge.from;
+    const rootEl = rootId != null ? resolve(rootId) : null;
+
+    const states = new Map();
+    if (rootEl) states.set(rootId, rootEl);
+    for (const e of edges) {
+        const src = resolve(e.from);
+        if (src && !states.has(e.from)) states.set(e.from, src);
+        for (const id of e.toIds) {
+            const el = resolve(id);
+            if (el && !states.has(id)) states.set(id, el);
         }
     }
 
+    if (!rootEl || !rootEdge.toIds.some((id) => states.has(id))) {
+        console.warn("[nodality] morph: could not resolve",
+            rootId, "->", rootEdge ? rootEdge.toIds : []);
+        return null;
+    }
+
+    /** The edge leaving a state, or null where the graph ends. */
+    const edgeFrom = (id) => edges.find((e) => e.from === id) || null;
+
     // A positioned stage, standing where the source stood. The source and
     // the destinations are siblings inside it rather than in page flow,
     // because a morph interpolates a BOX and both ends need a common
@@ -188,7 +266,7 @@ function setUpMorph(mount, m, resolve) {
     const stage = document.createElement("div");
     stage.className = "nod-morph";
     stage.style.cssText = "position:relative;";
-    mount.insertBefore(stage, fromEl);
+    mount.insertBefore(stage, rootEl);
 
     const rhost = document.createElement("div");
     rhost.className = "nod-morph-host";
@@ -202,55 +280,82 @@ function setUpMorph(mount, m, resolve) {
     stage.appendChild(rhost);
     stage.appendChild(live);
 
-    live.appendChild(fromEl);
-    fromEl.style.position = "absolute";
-    fromEl.style.left = fromEl.style.top = "0";
-
-    // Destinations start OFF the page. Without this every subview renders
-    // stacked under the nav, which is the whole "why is everything
-    // visible at once" problem.
-    const templates = toEls.map((el) => {
-        if (!el) return null;
-        el.remove();
-        return el;
-    });
+    live.appendChild(rootEl);
+    rootEl.style.position = "absolute";
+    rootEl.style.left = rootEl.style.top = "0";
+
+    // Every state except the root starts OFF the page. Without this every
+    // subview renders stacked under the nav, which is the whole "why is
+    // everything visible at once" problem.
+    for (const [id, el] of states) {
+        if (id !== rootId) el.remove();
+    }
+
+    // Where the graph is now. `current` moves only when a transition
+    // COMPLETES — a morph that is interrupted half way has not arrived
+    // anywhere, and treating it as though it had is what makes interrupt
+    // handling incoherent. The history stack is the record of states
+    // actually landed on, which is what `back` unwinds.
+    let current = rootId;
+    const history = [];
+
+    const currentEl = () => states.get(current) || rootEl;
 
     const sizeStage = (h) => {
         stage.style.minHeight =
-            Math.max(fromEl.getBoundingClientRect().height, h || 0) + 24 + "px";
+            Math.max(currentEl().getBoundingClientRect().height, h || 0) + 24 + "px";
     };
     sizeStage(0);
 
     let pipe = null;
     let tl = null;
     let active = -1;
+    // The two elements a running transition is between. The frame loop
+    // needs them by identity rather than by position in the host: from
+    // the second hop onward the outgoing state is ALSO a child of the
+    // host, so "the first child" no longer means "the destination".
+    let incoming = null;
+    let outgoing = null;
+    // The pair the CURRENT pipeline was built from, as state ids. A
+    // reversal may reuse that pipeline only when it is already exactly
+    // the hop being unwound — keying the decision on the history top
+    // instead let a stale pipeline satisfy it, resolve at zero
+    // immediately, and move the graph without moving the screen.
+    let lastFrom = null;
+    // Set while the root is being measured for a reversal INTO it. The
+    // root lives in the live layer, which is display:none whenever the
+    // graph is deeper in — and an element inside display:none has no box
+    // at all, so capturing it without this yields a 0x0 still and a
+    // transition that reverses into nothing.
+    let measuring = false;
+    let pipeOld = null;   // state id on the pipeline's old side
+    let pipeNew = null;   // state id on its new side
+
+    // A chain replaces one view with another in the same place; a single
+    // hop opens its destination BELOW the source and has done since the
+    // first morph shipped. gesos.cz renders with that placement today, so
+    // it stays exactly as it was, and only a genuine chain changes it —
+    // marching each successive state further down the page would also
+    // break hop two's arithmetic, which assumes a source at the top.
+    const inPlace = edges.length > 1;
 
-    const goTo = async (i) => {
-        const dest = templates[i];
-        if (!dest) return;
-        active = i;
-
-        for (const p of activeRasterPipelines()) {
-            if (stage.contains(p.canvas)) p.destroy();
-        }
-        rhost.innerHTML = "";
-        rhost.appendChild(dest);
-        // Hidden from the moment it enters the document. Between insertion
-        // and applyRasterPipeline there are two awaited captures, and a
-        // destination that is merely in the DOM paints for those frames —
-        // which is the destination flashing before the morph runs.
-        // visibility (not display) so it still lays out and can be measured.
-        dest.style.visibility = "hidden";
-
+    /**
+     * Capture two states and stand a transition pipeline up between them.
+     *
+     * Shared by both directions. A reversal is not a forward transition
+     * to an earlier state: it is THIS, with the state being returned to
+     * passed as the old side, so the effect runs backwards rather than
+     * playing forwards into the past.
+     */
+    const buildTransition = async (oldEl, newEl, edge) => {
         // WAIT FOR IMAGES before measuring anything.
         //
         // An <img> has no intrinsic box until it decodes — even from a
         // data: URL, which is async too. Measure before that and the
-        // destination's rect is its pre-image layout, so the shader draws
-        // the capture into a box that does not match where the real card
-        // ends up. The handover then pops between two different sizes,
-        // which is the flash at the end of the transition.
-        const imgs = [...dest.querySelectorAll("img")];
+        // rect is the pre-image layout, so the shader draws the capture
+        // into a box that does not match where the real card ends up.
+        // The handover then pops between two different sizes.
+        const imgs = [...newEl.querySelectorAll("img")];
         if (imgs.length) {
             await Promise.all(imgs.map((im) => {
                 if (im.complete && im.naturalWidth) return null;
@@ -260,52 +365,268 @@ function setUpMorph(mount, m, resolve) {
                     im.addEventListener("error", res, { once: true });
                 });
             }));
-            // One more frame so layout reflects the decoded intrinsic size.
             await new Promise((r) => requestAnimationFrame(r));
         }
 
-        const fromRect = rectIn(rhost, fromEl);
-        Object.assign(dest.style, { position: "absolute", left: "0",
-            top: Math.round(fromRect.h + 20) + "px", boxSizing: "border-box" });
-        const toRect = rectIn(rhost, dest);
-        sizeStage(toRect.y + toRect.h);
+        const oldRect = rectIn(rhost, oldEl);
+        const newRect = rectIn(rhost, newEl);
+        sizeStage(Math.max(oldRect.y + oldRect.h, newRect.y + newRect.h));
 
         const [oldImage, newImage] = await Promise.all([
-            capture(fromEl, fromRect.w, fromRect.h),
-            capture(dest, toRect.w, toRect.h),
+            capture(oldEl, oldRect.w, oldRect.h),
+            capture(newEl, newRect.w, newRect.h),
         ]);
 
-        pipe = applyRasterPipeline(rhost, chainFor(m.effect), {
+        pipe = applyRasterPipeline(rhost, chainFor(edge.effect), {
             transition: {
                 oldImage, newImage,
-                oldRect: fromRect, oldTo: toRect,
-                newRect: toRect, newFrom: fromRect,
+                oldRect, oldTo: newRect,
+                newRect, newFrom: oldRect,
                 // The morph owns the screen strictly BETWEEN its ends: the
                 // real source presents at t=0, the real destination at t=1.
                 standDownAtStart: true,
                 // Opt back into the HTML-in-Canvas backend. Off by default
                 // for a morph: it moves the content INTO the canvas, where
                 // it becomes fallback content and stops being hit-testable.
-                live: m.live === true,
+                live: edge.live === true,
                 // Per-pixel choice rather than a uniform mix. A crossfade
                 // shows 50% of each at the midpoint, which reads as two
                 // states at once rather than one becoming the other.
-                fade: m.fade || "morph",
+                fade: edge.fade || "morph",
             },
         });
 
         if (tl) tl.destroy();
-        tl = progressTimeline(pipe, { duration: m.duration != null ? m.duration : 900 });
+        tl = progressTimeline(pipe, {
+            duration: edge.duration != null ? edge.duration : 900,
+        });
+    };
+
+    /**
+     * Transition from wherever the graph is now to `destId`.
+     *
+     * Keyed by state id rather than by index: an index is only meaningful
+     * relative to one edge's destination list, and the controller has to
+     * answer "go here" from whichever state happens to be current.
+     */
+    const goToState = async (destId) => {
+        const edge = edgeFrom(current);
+        if (!edge || !edge.toIds.includes(destId)) return;
+        const dest = states.get(destId);
+        if (!dest) return;
+        const srcEl = currentEl();
+        active = edge.toIds.indexOf(destId);
+        lastFrom = current;
+
+        for (const p of activeRasterPipelines()) {
+            if (stage.contains(p.canvas)) p.destroy();
+        }
+        // Clear everything EXCEPT the state being transitioned from.
+        // Emptying the host outright is what the single hop did, and it
+        // was safe only because the source lived in the live layer. From
+        // the second hop onward the source is a landed state sitting in
+        // this host, and emptying would delete the very element about to
+        // be captured. For a single hop the source is still in the live
+        // layer, so this removes exactly what it always did.
+        for (const child of [...rhost.children]) {
+            if (child !== srcEl) child.remove();
+        }
+        rhost.appendChild(dest);
+        outgoing = srcEl;
+        incoming = dest;
+        // Hidden from the moment it enters the document. Between insertion
+        // and applyRasterPipeline there are two awaited captures, and a
+        // destination that is merely in the DOM paints for those frames —
+        // which is the destination flashing before the morph runs.
+        // visibility (not display) so it still lays out and can be measured.
+        dest.style.visibility = "hidden";
+
+        // Place the destination before anything is measured: in a chain
+        // it takes the source's own position, so views replace each other
+        // in one region rather than marching down the page.
+        const fromRect = rectIn(rhost, srcEl);
+        Object.assign(dest.style, { position: "absolute", left: "0",
+            top: Math.round(inPlace ? fromRect.y : fromRect.h + 20) + "px",
+            boxSizing: "border-box" });
+
+        await buildTransition(srcEl, dest, edge);
+        if (!tl) return;
+        pipeOld = lastFrom; pipeNew = destId;
         tl.set(0);
 
-        if (m.back !== false) {
-            const btn = dest.querySelector("button");
-            if (btn && !btn.dataset.nodMorphBack) {
-                btn.dataset.nodMorphBack = "1";
-                btn.addEventListener("click", () => { if (tl) tl.to(0); });
+        // Wire the destination BEFORE the timeline runs, not on arrival.
+        // Progress reaches 1 a frame before `to(1)`'s promise resolves, so
+        // wiring at landing leaves a window in which the destination is
+        // fully presented and its controls are dead — which a caller
+        // polling progress hits every time.
+        //
+        // Order still matters: forward triggers first, then back from
+        // whatever is left, so the roles cannot swap.
+        wireState(destId);
+        if (edge.back) claimBack(dest);
+
+        // `to()` resolves with the progress actually reached, and resolves
+        // rather than hanging when something interrupts it. So the
+        // resolved value IS the answer to "did we arrive?" — anything
+        // short of 1 means another transition took over, and a morph that
+        // did not arrive must not move the graph.
+        const reached = await tl.to(1);
+        if (reached === 1 && incoming === dest) land(destId, srcEl, edge);
+    };
+
+    /**
+     * Unwind one step of the path actually taken.
+     *
+     * `back` is history, not an edge. The graph may offer a route from
+     * here to somewhere else entirely — `aurora` has a forward edge to
+     * `contact` — but going back means returning the way you came, which
+     * is what every user already expects from a browser. So the stack of
+     * landed states decides the destination, not the edge list.
+     */
+    let backing = false;
+    let queuedBacks = 0;
+
+    /** Unwind exactly one step of the path taken. */
+    const stepBack = async () => {
+        if (!history.length) return;
+        const targetId = history[history.length - 1];
+        const targetEl = states.get(targetId);
+        if (!targetEl) return;
+        const fromEl = currentEl();
+
+        // The live pipeline is already the right pair when the last thing
+        // that ran was the hop being unwound. Reusing it is what makes an
+        // immediate back feel instant, and it is also what lets a back
+        // INTERRUPT a still-running forward — the timeline simply
+        // reverses from wherever it is.
+        if (pipe && tl && pipeOld === targetId && pipeNew === current) {
+            const reached = await tl.to(0);
+            if (reached === 0) landBack(targetId);
+            return;
+        }
+        await reverseRebuild(targetId, targetEl, fromEl);
+    };
+
+    const goBack = async () => {
+        // Presses arriving mid-reversal are QUEUED, not dropped and not
+        // run concurrently. Dropping them makes a user hammering back sit
+        // one level down and look stuck; running them at once re-targets
+        // the hop that just finished, because `current` updates a tick
+        // after progress reaches its endpoint. Queuing gives the only
+        // behaviour that matches the control: one press, one level.
+        if (backing) { queuedBacks++; return; }
+        backing = true;
+        try {
+            await stepBack();
+            while (queuedBacks > 0 && history.length) {
+                queuedBacks--;
+                await stepBack();
             }
+        } finally { backing = false; queuedBacks = 0; }
+    };
+
+    /** The reversal that cannot reuse the live pipeline: build it. */
+    const reverseRebuild = async (targetId, targetEl, fromEl) => {
+
+        // The old pipeline is kept ALIVE across the measuring phase and
+        // retired only once its replacement exists. It is what covers the
+        // stage while the state being returned to is revealed underneath
+        // it, and that ordering is what lets the reveal use `display`
+        // alone — no `visibility: hidden` anywhere.
+        //
+        // That matters beyond flicker. HTML-in-Canvas uploads an element
+        // through its PAINT RECORD, and a hidden element has none:
+        // `texElementImage2D` then throws "No cached paint record for
+        // element" and the pipeline falls back to snapshot mid-flight.
+        // Measuring something while hiding it is not an option on the
+        // live backend — it has to be painted, and merely covered.
+        //
+        // Retiring it too early is the other failure: destroying it
+        // before the replacement exists leaves a gap with nothing
+        // presenting, and never retiring it leaves its canvas stacked in
+        // the host showing a stale frame over the real transition.
+        const stale = [...activeRasterPipelines()].filter(
+            (p) => stage.contains(p.canvas));
+
+        const edge = edgeFrom(targetId) || {};
+        if (targetEl === rootEl) {
+            // Revealed, not shown: it needs a box to be measured and a
+            // paint record to be uploaded. The stale canvas above covers
+            // it until the transition takes over.
+            measuring = true;
+            live.style.display = "";
+        } else if (targetEl.parentNode !== rhost) {
+            // A later hop swept it out of the host; it has to be back in
+            // the document to be measured and captured.
+            targetEl.style.visibility = "hidden";
+            rhost.appendChild(targetEl);
+            const cur = rectIn(rhost, fromEl);
+            Object.assign(targetEl.style, {
+                position: "absolute", left: "0",
+                top: Math.round(inPlace ? cur.y : 0) + "px",
+                boxSizing: "border-box",
+            });
         }
-        tl.to(1);
+
+        await buildTransition(targetEl, fromEl, edge);
+        for (const p of stale) p.destroy();
+        measuring = false;
+        if (!tl) return;
+        pipeOld = targetId; pipeNew = current;
+        outgoing = targetEl;
+        incoming = fromEl;
+        tl.set(1);
+        const reached = await tl.to(0);
+        if (reached === 0) landBack(targetId);
+    };
+
+    /** Arriving back: pop the step being unwound and present it. */
+    const landBack = (targetId) => {
+        if (history[history.length - 1] === targetId) history.pop();
+        current = targetId;
+        lastFrom = history.length ? history[history.length - 1] : null;
+        wireState(targetId);
+    };
+
+    /**
+     * A transition completed: the destination is now where the graph is,
+     * and therefore now a source in its own right.
+     */
+    const land = (id, previousEl, viaEdge) => {
+        // The step just completed becomes the top of the stack — this is
+        // what `back` unwinds, and why back returns the way you came
+        // rather than following some edge that happens to point earlier.
+        if (lastFrom != null && lastFrom !== id) history.push(lastFrom);
+        current = id;
+        // The state left behind STAYS in the host, hidden by the frame
+        // loop. Removing it here was wrong in both directions: going back
+        // has to present it again, and the shader's t=0 frame is a
+        // picture of it, so the real element must be there to take over.
+        // The next forward transition sweeps it out, because the
+        // selective clear keeps only the state it departs from.
+        outgoing = previousEl && previousEl !== rootEl ? previousEl : null;
+        // Idempotent re-wire. The destination was wired before the
+        // timeline ran; this covers anything its own subtree changed
+        // during the transition.
+        wireState(id);
+        if (viaEdge && viaEdge.back) claimBack(states.get(id));
+    };
+
+    /** The back control is a button the forward wiring did not claim. */
+    const claimBack = (el) => {
+        if (!el) return;
+        const btn = [...el.querySelectorAll("button")].find(
+            (b) => !b.dataset.nodMorphWired && !b.dataset.nodMorphBack);
+        if (!btn) return;
+        btn.dataset.nodMorphBack = "1";
+        btn.addEventListener("click", () => { goBack(); });
+    };
+
+    // Positional entry point, kept for the handle's published shape: the
+    // index is resolved against the CURRENT state's edge.
+    const goTo = (i) => {
+        const edge = edgeFrom(current);
+        return edge ? goToState(edge.toIds[i]) : undefined;
     };
 
     // Link i in the source goes to destination i. By POSITION, not label:
@@ -321,45 +642,75 @@ function setUpMorph(mount, m, resolve) {
      * case a plain call-to-action button is. If the source is itself the
      * control (a lone button), the source is the trigger.
      */
-    const triggersOf = () => {
-        const links = [...fromEl.querySelectorAll("a")];
+    const triggersOf = (el) => {
+        const links = [...el.querySelectorAll("a")];
         if (links.length) return links;
-        const btns = [...fromEl.querySelectorAll("button, [role=button]")];
+        const btns = [...el.querySelectorAll("button, [role=button]")];
         if (btns.length) return btns;
-        return [fromEl];
+        return [el];
     };
 
-    const wire = (a) => {
+    /**
+     * Wire one trigger against the edge leaving its state.
+     *
+     * `byName` says the edge's labels actually match something in this
+     * state, and it decides which rule applies. The single-destination
+     * shortcut — any trigger goes to the only destination — is right for
+     * a lone call-to-action button whose text matches no declared label,
+     * and wrong for a card that has both a forward control and a back
+     * control: there, "any trigger" sweeps up the back button too. When
+     * the labels match, the labels rule.
+     */
+    const wire = (a, edge, triggers, byName) => {
         if (a.dataset.nodMorphWired) return;
-        const triggers = triggersOf();
-        // One destination means there is nothing to disambiguate: any
-        // trigger goes there, whatever it is labelled. Only a fan-out
-        // needs a label map or an index.
-        const idx = toIds.length === 1 ? 0
-            : byLabel ? labelToIndex.get(norm(a.textContent))
-            : triggers.indexOf(a);
-        if (idx == null || idx < 0 || !templates[idx]) return;
+        // The back control is claimed first and is never also a forward
+        // trigger. The two wirings guard on independent flags, so a state
+        // whose only controls are buttons — `triggersOf` falls through to
+        // buttons — and whose edge has a single destination — any trigger
+        // goes there — would otherwise fire BOTH on one click.
+        if (a.dataset.nodMorphBack) return;
+        const destId = byName ? edge.labelToId.get(norm(a.textContent))
+            // One destination and no matching label: nothing to
+            // disambiguate, so any trigger goes there.
+            : edge.toIds.length === 1 ? edge.toIds[0]
+            : edge.byLabel ? edge.labelToId.get(norm(a.textContent))
+            : edge.toIds[triggers.indexOf(a)];
+        if (!destId || !states.has(destId)) return;
         a.dataset.nodMorphWired = "1";
-        a.dataset.nodMorphTo = toIds[idx];
+        a.dataset.nodMorphTo = destId;
         a.addEventListener("click", (e) => {
             // Nothing resolved -> the link keeps its own behaviour, which
             // on an ordinary page is real navigation.
-            if (!templates[idx]) return;
+            if (!states.has(destId)) return;
             e.preventDefault();
-            goTo(idx);
+            goToState(destId);
         });
     };
-    const wireAll = () => triggersOf().forEach(wire);
-    wireAll();
-
-    // A responsive nav REPLACES its links when it crosses a breakpoint —
-    // the Switcher swaps the whole view — so anything wired once is gone
-    // after a resize. Re-wire whatever appears; `nodMorphWired` keeps it
-    // idempotent.
-    if (typeof MutationObserver !== "undefined") {
-        new MutationObserver(wireAll).observe(fromEl,
-            { childList: true, subtree: true });
-    }
+
+    /** Wire every trigger of a state, if that state has an outgoing edge. */
+    const observed = new Set();
+    const wireState = (id) => {
+        const edge = edgeFrom(id);
+        const el = states.get(id);
+        if (!edge || !el) return;
+        const triggers = triggersOf(el);
+        const byName = !!edge.byLabel &&
+            triggers.some((t) => edge.labelToId.has(norm(t.textContent)));
+        triggers.forEach((t) => wire(t, edge, triggers, byName));
+
+        // A responsive nav REPLACES its links when it crosses a
+        // breakpoint — the Switcher swaps the whole view — so anything
+        // wired once is gone after a resize. Re-wire whatever appears;
+        // `nodMorphWired` keeps it idempotent. Every state that can be a
+        // source gets this, not just the root, because a chain can be
+        // resized while three levels deep.
+        if (typeof MutationObserver !== "undefined" && !observed.has(id)) {
+            observed.add(id);
+            new MutationObserver(() => wireState(id))
+                .observe(el, { childList: true, subtree: true });
+        }
+    };
+    wireState(rootId);
 
     // Only the source is on screen until something is chosen.
     const frame = () => {
@@ -403,22 +754,42 @@ function setUpMorph(mount, m, resolve) {
         // canvas alone showed BOTH ends at t=1, because at that point the
         // canvas is down and nothing distinguished the two.
         const handover = !pipe || !canvasUp;
-        const wantLive = handover && t <= 0 ? "" : "none";
+        // The live layer holds the ROOT state only. Landed states live in
+        // the host, so from the second hop onward "t is at zero" does not
+        // mean the root should be showing — `current` decides that.
+        const wantLive = measuring ? ""
+            : handover && t <= 0 && (current === rootId || outgoing === rootEl)
+                ? "" : "none";
         if (live.style.display !== wantLive) live.style.display = wantLive;
-        const dest = rhost.firstElementChild;
+        // By identity, not by position: during a chain hop the outgoing
+        // state is also a child of this host, so `firstElementChild`
+        // would sometimes name the wrong one of the two.
+        const dest = incoming || rhost.firstElementChild;
         if (dest && dest.style) {
             const want = pipe && handover && t >= 1 ? "" : "hidden";
             if (dest.style.visibility !== want) dest.style.visibility = want;
         }
+        // The state being left behind is the other end of the same rule:
+        // it presents at t=0, and only while the canvas has stood down.
+        // The root is exempt because the live layer's display already
+        // governs it, and driving both would fight.
+        if (outgoing && outgoing !== rootEl && outgoing.style) {
+            const want = handover && t <= 0 ? "" : "hidden";
+            if (outgoing.style.visibility !== want) outgoing.style.visibility = want;
+        }
         requestAnimationFrame(frame);
     };
     requestAnimationFrame(frame);
 
     return {
-        stage, from: fromEl, destinations: templates,
+        stage, from: rootEl,
+        get destinations() { return rootEdge.toIds.map((id) => states.get(id) || null); },
+        get states() { return states; },
+        get current() { return current; },
+        get history() { return [...history]; },
         get progress() { return pipe ? pipe.progress : 0; },
         get active() { return active; },
-        goTo,
+        goTo, goToState,
         back() { if (tl) tl.to(0); },
         destroy() {
             if (tl) tl.destroy();