@myrmidon/gve-snapshot-rendition 2.0.5 → 2.0.7

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export type { OperationHint } from "./settings/hint-models";
 export { DEFAULT_SETTINGS } from "./settings/settings";
 export type { HintDesignerData, HintDesignerSettings, StringPair, } from "./hint-designer/hint-designer-models";
 export { DEFAULT_HINT_DESIGNER_SETTINGS } from "./hint-designer/hint-designer-models";
+export { OperationSummaryService } from "./ui/operation-summary-service";
 export type { Feature, OperationFeature, OperationSource, OperationDiplomatics, OperationMetadata, CharChainOperation, CharNode, ChainOperationContextStep, CharChainResult, ChainOperationTags, CharChainNode, CharChainLink, CharChain, } from "./models";
 export { FeatureSetPolicy, OperationType } from "./models";

package/dist/index.js

@@ -863,6 +863,24 @@ function getTextWidth(text, fontFamily, fontSize, bold = false, italic = false,
     }
     return width;
 }
+/**
+ * Reference character used to compute the "average character width/height"
+ * that the "tw"/"th" offset units resolve against (see getAverageCharWidth).
+ * This is the same reference character used to size the space character.
+ */
+const REFERENCE_CHAR = "m";
+/**
+ * Get the average character width for the given font settings, using
+ * REFERENCE_CHAR ("m") as the reference glyph. This is the basis for the
+ * "tw" (text width) unit used by r_char-offsets, r_t-offset-x/y, and
+ * r_h-offset-x/y — NOT the bounding box of a whole reference text span.
+ *
+ * @param measurementRoot - Optional SVG element to use as measurement context
+ *                          (see getTextWidth for why this matters).
+ */
+function getAverageCharWidth(fontFamily, fontSize, bold = false, italic = false, measurementRoot) {
+    return getTextWidth(REFERENCE_CHAR, fontFamily, fontSize, bold, italic, measurementRoot);
+}
 
 /**
  * Text processing utilities.
@@ -1021,11 +1039,6 @@ function parseHintVars(value) {
     return result;
 }
 
-/**
- * Reference character for calculating space width.
- * This can be changed if needed.
- */
-const REFERENCE_CHAR = "m";
 /**
  * Text layout calculator.
  * Handles positioning of base text characters, respecting line breaks,
@@ -1061,7 +1074,7 @@ class TextLayout {
      * Calculate the width of a space character based on reference character.
      */
     calculateSpaceWidth() {
-        const refCharWidth = getTextWidth(REFERENCE_CHAR, this._settings.fontFamily, this._settings.fontSize, this._settings.bold, this._settings.italic, this._measurementRoot // Use measurement root for consistent font metrics
+        const refCharWidth = getAverageCharWidth(this._settings.fontFamily, this._settings.fontSize, this._settings.bold, this._settings.italic, this._measurementRoot // Use measurement root for consistent font metrics
         );
         return refCharWidth * this._settings.spaceWidthFraction;
     }
@@ -1079,7 +1092,7 @@ class TextLayout {
         // Compute the average character dimensions used to resolve "tw" and "th" units.
         // tw = average character width (width of the reference character 'm' in the current font)
         // th = average character height  (≈ font size, which is the em-square in CSS/SVG pixels)
-        const avgCharWidth = getTextWidth(REFERENCE_CHAR, this._settings.fontFamily, this._settings.fontSize, this._settings.bold, this._settings.italic, this._measurementRoot);
+        const avgCharWidth = getAverageCharWidth(this._settings.fontFamily, this._settings.fontSize, this._settings.bold, this._settings.italic, this._measurementRoot);
         const avgCharHeight = this._settings.fontSize;
         const positions = [];
         let currentX = this._settings.marginLeft;
@@ -1405,10 +1418,10 @@ class TextRenderer {
         let rbrs;
         if (config.textDisplacedSpan) {
             const nodes = getNodeSpan(allBaseNodes, config.textDisplacedSpan.nodeId, config.textDisplacedSpan.count);
-            rbrs = this.calculateRBRs(nodes);
+            rbrs = this.calculateRBRs(nodes, rootSvg);
         }
         else {
-            rbrs = this.calculateRBRs(referenceNodes);
+            rbrs = this.calculateRBRs(referenceNodes, rootSvg);
         }
         if (rbrs.length === 0) {
             this._logger.warn("No RBRs calculated for additional text, skipping");
@@ -1417,10 +1430,14 @@ class TextRenderer {
         // Use first RBR for positioning (additional text doesn't repeat per RBR)
         const rbr = rbrs[0];
         this._logger.debug("TextRenderer", `Using RBR for positioning`, rbr);
-        // 2. Calculate position and offsets
+        // 2. Calculate position and offsets.
+        // "tw"/"th" resolve against the average character width/height in the
+        // current (possibly r_font-size/r_font-family-overridden) font, not the RBR.
         const position = config.textPosition || "o";
-        const offsetX = parseOffset(config.textOffsetX || 0, rbr.height, rbr.width);
-        const offsetY = parseOffset(config.textOffsetY || 0, rbr.height, rbr.width);
+        const avgCharWidth = getAverageCharWidth(config.fontFamily, config.fontSize, config.bold, config.italic, rootSvg);
+        const avgCharHeight = config.fontSize;
+        const offsetX = parseOffset(config.textOffsetX || 0, avgCharHeight, avgCharWidth);
+        const offsetY = parseOffset(config.textOffsetY || 0, avgCharHeight, avgCharWidth);
         // 3. Render characters at preliminary positions (baseline y=0) into a hidden
         //    temporary group so we can measure the actual visual EBR via getBBox().
         //    This mirrors the hint renderer's approach: render → measure → reposition.
@@ -1600,31 +1617,43 @@ class TextRenderer {
     /**
      * Calculate RBRs from reference nodes.
      * Nodes on different lines create separate RBRs.
+     *
+     * @param rootSvg - Root SVG element, used to read each character's laid-out
+     *   baseline `y` attribute for line-break detection (see below).
      */
-    calculateRBRs(nodes) {
+    calculateRBRs(nodes, rootSvg) {
         if (nodes.length === 0)
             return [];
         const rbrs = [];
         const nodeElementIds = nodes.map((n) => `n_${n.id}`);
-        // Group nodes by line by checking their Y coordinates
+        // Group nodes by line by checking their Y coordinates.
+        // IMPORTANT: this compares the character's laid-out baseline Y (the `y`
+        // attribute TextLayout assigned when positioning it), NOT its cached
+        // getBBox().y. The tight ink bbox top varies per glyph shape (ascenders,
+        // descenders, x-height-only glyphs), easily by more than the 5px
+        // tolerance below, even on the very same line — using bbox.y here would
+        // spuriously split one line into multiple RBRs.
         const lineGroups = [];
         let currentLineGroup = [];
-        let lastY = null;
+        let lastBaselineY = null;
         for (const elementId of nodeElementIds) {
             const bounds = this._boundsCache.get(elementId);
             if (!bounds) {
                 this._logger.warn(`Bounds not found for node element ${elementId}`);
                 continue;
             }
-            // If Y coordinate significantly different, start new line group
-            if (lastY !== null && Math.abs(bounds.y - lastY) > 5) {
+            const el = rootSvg?.querySelector(`#${elementId}`);
+            const attrY = el?.getAttribute("y");
+            const baselineY = attrY !== null && attrY !== undefined ? parseFloat(attrY) : bounds.y;
+            // If baseline Y coordinate significantly different, start new line group
+            if (lastBaselineY !== null && Math.abs(baselineY - lastBaselineY) > 5) {
                 if (currentLineGroup.length > 0) {
                     lineGroups.push([...currentLineGroup]);
                     currentLineGroup = [];
                 }
             }
             currentLineGroup.push(elementId);
-            lastY = bounds.y;
+            lastBaselineY = baselineY;
         }
         // Add last group
         if (currentLineGroup.length > 0) {
@@ -1704,15 +1733,20 @@ class HintRenderer {
             let rbrs;
             if (effectiveHint.displacedRefSpan) {
                 // Use displaced span instead of reference nodes
-                rbrs = this.calculateDisplacedRBRs(effectiveHint.displacedRefSpan, allBaseNodes);
+                rbrs = this.calculateDisplacedRBRs(effectiveHint.displacedRefSpan, allBaseNodes, rootSvg);
             }
             else {
-                rbrs = this.calculateRBRs(referenceNodes);
+                rbrs = this.calculateRBRs(referenceNodes, rootSvg);
             }
             if (rbrs.length === 0) {
                 this._logger.warn(`No RBRs calculated for hint ${hintId}, skipping`);
                 return;
             }
+            // Average character width/height in the default text settings, used to
+            // resolve "tw"/"th" units in offsetX/offsetY (r_h-offset-x/y). These are
+            // NOT the RBR (reference text bounds) — see docs "Hints" properties.
+            const avgCharWidth = getAverageCharWidth(this._settings.fontFamily, this._settings.fontSize, this._settings.bold, this._settings.italic, rootSvg);
+            const avgCharHeight = this._settings.fontSize;
             // 5. Check if this is a placeholder hint
             const hasPlaceholder = hintGroup.querySelector("#placeholder") !== null;
             // Default-mode placeholder: a placeholder element WITHOUT class="fit".
@@ -1754,7 +1788,7 @@ class HintRenderer {
                 // This is either the handle's bbox or the whole hint's bbox
                 const ebrBounds = this.getEBRBounds(currentHintGroup);
                 // 11. Apply positioning transform - align EBR with RBR based on position
-                await this.applyHintPositionTransform(currentHintGroup, effectiveHint, rbr, ebrBounds, scalingInfo);
+                await this.applyHintPositionTransform(currentHintGroup, effectiveHint, rbr, ebrBounds, scalingInfo, avgCharWidth, avgCharHeight);
                 // 10. Check if prolog panning is needed (element visibility check)
                 // This must happen AFTER positioning and spreading, but BEFORE making visible
                 if (panZoomInstance && viewportWidth && viewportHeight && this._settings.prologDuration > 0) {
@@ -1802,16 +1836,28 @@ class HintRenderer {
     /**
      * Calculate Reference Bounding Rectangles (RBRs) from reference nodes.
      * Nodes on different lines create separate RBRs.
+     *
+     * @param rootSvg - Root SVG element, used to read each character's laid-out
+     *   baseline `y` attribute for line-break detection (see below).
      */
-    calculateRBRs(nodes) {
+    calculateRBRs(nodes, rootSvg) {
         if (nodes.length === 0)
             return [];
         const rbrs = [];
         this._logger.debug("HintRenderer", `Calculating RBRs for ${nodes.length} nodes`);
-        // Group nodes by line by checking their Y coordinates
+        // Group nodes by line by checking their Y coordinates.
+        // IMPORTANT: this compares the character's laid-out baseline Y (the `y`
+        // attribute TextLayout assigned when positioning it), NOT its cached
+        // getBBox().y. The tight ink bbox top varies per glyph shape (e.g. an
+        // ascender like "t" vs. a descender like "g" vs. an x-height-only glyph
+        // like "s"), easily by more than the 5px tolerance below, even though
+        // the characters sit on the very same line. Using bbox.y here would
+        // spuriously split a single line into multiple "line groups" — and thus
+        // multiple RBRs, causing hints to be rendered (and animated) more than
+        // once for what is really a single reference span.
         const lineGroups = [];
         let currentLineGroup = [];
-        let lastY = null;
+        let lastBaselineY = null;
         const missingBounds = [];
         const skippedInvisible = [];
         for (const node of nodes) {
@@ -1830,15 +1876,21 @@ class HintRenderer {
                 missingBounds.push(elementId);
                 continue;
             }
-            // If Y coordinate significantly different, start new line group
-            if (lastY !== null && Math.abs(bounds.y - lastY) > 5) {
+            // Prefer the laid-out baseline `y` attribute (deterministic, identical
+            // for every character on the same line); fall back to the cached ink
+            // bbox top only if the element can't be found (defensive).
+            const el = rootSvg?.querySelector(`#${elementId}`);
+            const attrY = el?.getAttribute("y");
+            const baselineY = attrY !== null && attrY !== undefined ? parseFloat(attrY) : bounds.y;
+            // If baseline Y coordinate significantly different, start new line group
+            if (lastBaselineY !== null && Math.abs(baselineY - lastBaselineY) > 5) {
                 if (currentLineGroup.length > 0) {
                     lineGroups.push([...currentLineGroup]);
                     currentLineGroup = [];
                 }
             }
             currentLineGroup.push(elementId);
-            lastY = bounds.y;
+            lastBaselineY = baselineY;
         }
         // Add last group
         if (currentLineGroup.length > 0) {
@@ -1863,7 +1915,7 @@ class HintRenderer {
     /**
      * Calculate RBRs from a displaced span reference (IDxN format).
      */
-    calculateDisplacedRBRs(displacedRefSpan, allBaseNodes) {
+    calculateDisplacedRBRs(displacedRefSpan, allBaseNodes, rootSvg) {
         const parsed = parseDisplacedSpan(displacedRefSpan);
         if (!parsed) {
             this._logger.warn(`Invalid displaced span format: ${displacedRefSpan}`);
@@ -1874,7 +1926,7 @@ class HintRenderer {
             this._logger.warn(`No nodes found for displaced span ${displacedRefSpan}`);
             return [];
         }
-        return this.calculateRBRs(nodes);
+        return this.calculateRBRs(nodes, rootSvg);
     }
     /**
      * Calculate scaling information for the hint.
@@ -1928,14 +1980,15 @@ class HintRenderer {
      * Per documentation: hints use the handle's bounding box as EBR if a handle element exists,
      * otherwise they use the whole hint's bounding box as EBR.
      */
-    async applyHintPositionTransform(hintGroup, hint, rbr, ebrBounds, scalingInfo) {
+    async applyHintPositionTransform(hintGroup, hint, rbr, ebrBounds, scalingInfo, avgCharWidth, avgCharHeight) {
         // Calculate the alignment point on the RBR
         const rbrAlignPoint = this.calculateRBRAlignmentPoint(hint.position, rbr);
         // Calculate the alignment point on the EBR (in local/untransformed coordinates)
         const ebrAlignPoint = this.calculateEBRAlignmentPoint(hint.position, ebrBounds);
-        // Parse offsets (they can be px or "th"/"tw")
-        const offsetX = parseOffset(hint.offsetX, rbr.height, rbr.width);
-        const offsetY = parseOffset(hint.offsetY, rbr.height, rbr.width);
+        // Parse offsets (they can be px or "th"/"tw", resolved against the average
+        // character height/width, not the RBR — see docs "Hints" properties).
+        const offsetX = parseOffset(hint.offsetX, avgCharHeight, avgCharWidth);
+        const offsetY = parseOffset(hint.offsetY, avgCharHeight, avgCharWidth);
         // Apply offsets to the RBR alignment point
         const finalRbrX = rbrAlignPoint.x + offsetX;
         const finalRbrY = rbrAlignPoint.y + offsetY;
@@ -1980,6 +2033,7 @@ class HintRenderer {
             ebrAlignPoint_LOCAL: ebrAlignPoint,
             scalingInfo,
             rotation: hint.rotation,
+            offsetInputs: { x: hint.offsetX, y: hint.offsetY, avgCharWidth, avgCharHeight },
             offsets: { x: offsetX, y: offsetY },
             finalRbrPoint: { x: finalRbrX, y: finalRbrY },
             transformString,
@@ -25917,7 +25971,7 @@ class GveSnapshotRendition extends HTMLElement {
      * of the web component is loaded.
      */
     static get version() {
-        return "2.0.5";
+        return "2.0.7";
     }
     constructor() {
         super();
@@ -25930,6 +25984,12 @@ class GveSnapshotRendition extends HTMLElement {
         this._autoForwardEnabled = false;
         this._autoForwardTimerId = null;
         this._renderScheduled = false;
+        // Guards against re-entrant navigation: a slideshow tick (or a rapid
+        // double-click/keypress) firing while a previous goToVersionIndex() call
+        // is still awaiting its hint/text animations would otherwise re-run the
+        // whole render pipeline for the same transition, duplicating every
+        // element and animation involved (see goToVersionIndex()).
+        this._isNavigating = false;
         // Initialize with default settings
         this._settings = { ...DEFAULT_SETTINGS };
         this._autoForwardEnabled = this._settings.autoForwardOnGroup;
@@ -26634,55 +26694,72 @@ class GveSnapshotRendition extends HTMLElement {
     async goToVersionIndex(targetIndex) {
         if (!this._data || !this._textRenderer || !this._rootSvg)
             return;
-        this._logger.info(`Navigating from v${this._currentVersionIndex} to v${targetIndex}`);
         // Determine direction
         if (targetIndex === this._currentVersionIndex) {
             // Already at target
             return;
         }
-        // Stop any pending auto-forward when user manually navigates
-        this.stopAutoForward();
-        // Clear hilites before navigating
-        if (this._hilites && this._hilites.hasActiveHilites()) {
-            await this._hilites.clearHilites();
-        }
-        if (this._versionsListArea) {
-            this._versionsListArea.clearHilites();
-        }
-        if (targetIndex > this._currentVersionIndex) {
-            // FORWARD navigation: add elements
-            await this.navigateForward(targetIndex);
-        }
-        else {
-            // BACKWARD navigation: remove elements
-            await this.navigateBackward(targetIndex);
-        }
-        // Update versions list area
-        const versionTag = `v${targetIndex}`;
-        if (this._versionsListArea) {
-            this._versionsListArea.updateCurrentVersion(versionTag);
+        // Re-entrancy guard: a previous call may still be awaiting its hint/text
+        // animations (which can take arbitrarily long, since hints and their
+        // animations are user-defined). _currentVersionIndex is only updated
+        // once that call finishes, so without this guard a caller that fires
+        // again in the meantime (e.g. a slideshow tick, or a fast double-click)
+        // would re-run the whole render pipeline for the same transition,
+        // duplicating every hint/text element and animation it touches.
+        if (this._isNavigating) {
+            this._logger.warn(`Ignoring navigation to v${targetIndex} - a navigation is already in progress`);
+            return;
         }
-        // Update toolbar
-        if (this._toolbar) {
-            this._toolbar.setCurrentIndex(targetIndex);
+        this._isNavigating = true;
+        try {
+            this._logger.info(`Navigating from v${this._currentVersionIndex} to v${targetIndex}`);
+            // Stop any pending auto-forward when user manually navigates
+            this.stopAutoForward();
+            // Clear hilites before navigating
+            if (this._hilites && this._hilites.hasActiveHilites()) {
+                await this._hilites.clearHilites();
+            }
+            if (this._versionsListArea) {
+                this._versionsListArea.clearHilites();
+            }
+            if (targetIndex > this._currentVersionIndex) {
+                // FORWARD navigation: add elements
+                await this.navigateForward(targetIndex);
+            }
+            else {
+                // BACKWARD navigation: remove elements
+                await this.navigateBackward(targetIndex);
+            }
+            // Update versions list area
+            const versionTag = `v${targetIndex}`;
+            if (this._versionsListArea) {
+                this._versionsListArea.updateCurrentVersion(versionTag);
+            }
+            // Update toolbar
+            if (this._toolbar) {
+                this._toolbar.setCurrentIndex(targetIndex);
+            }
+            // Update version text area
+            this.updateVersionText(targetIndex);
+            // Update details area
+            this.updateDetailsArea(targetIndex);
+            // Re-setup hover listeners (new text elements may have been added)
+            this.setupTextElementHoverListeners();
+            // Check if we should auto-forward through grouped operations
+            // Only auto-forward if:
+            // 1. Feature is enabled
+            // 2. We moved forward (targetIndex > previous index)
+            // 3. Current operation has a groupId
+            // 4. Not already in slideshow mode
+            if (this._autoForwardEnabled &&
+                targetIndex > 0 &&
+                targetIndex <= (this._data?.steps?.length || 0) &&
+                this._slideshowTimerId === null) {
+                this.checkAndTriggerAutoForward(targetIndex);
+            }
         }
-        // Update version text area
-        this.updateVersionText(targetIndex);
-        // Update details area
-        this.updateDetailsArea(targetIndex);
-        // Re-setup hover listeners (new text elements may have been added)
-        this.setupTextElementHoverListeners();
-        // Check if we should auto-forward through grouped operations
-        // Only auto-forward if:
-        // 1. Feature is enabled
-        // 2. We moved forward (targetIndex > previous index)
-        // 3. Current operation has a groupId
-        // 4. Not already in slideshow mode
-        if (this._autoForwardEnabled &&
-            targetIndex > 0 &&
-            targetIndex <= (this._data?.steps?.length || 0) &&
-            this._slideshowTimerId === null) {
-            this.checkAndTriggerAutoForward(targetIndex);
+        finally {
+            this._isNavigating = false;
         }
     }
     /**
@@ -27154,9 +27231,24 @@ class GveSnapshotRendition extends HTMLElement {
             this._toolbar.setSlideshowActive(true);
             this._toolbar.setNavigationDisabled(true);
         }
-        this._slideshowTimerId = window.setInterval(() => {
-            this.slideshowAdvance();
-        }, this._settings.slideshowInterval);
+        // Use a self-rescheduling setTimeout rather than setInterval: each tick
+        // is scheduled only after the previous slideshowAdvance() (and the
+        // navigation/animations it awaits) has fully completed. A fixed-tick
+        // setInterval would keep firing regardless of how long a transition's
+        // (user-defined) hint animations actually take, and once a tick landed
+        // mid-transition it would re-enter goToVersionIndex() for the very same
+        // transition, duplicating every hint/text element it renders.
+        const scheduleTick = () => {
+            this._slideshowTimerId = window.setTimeout(async () => {
+                await this.slideshowAdvance();
+                // Only reschedule if still active - slideshowAdvance() may have
+                // called stopSlideshow() (reached the end/start with no loop).
+                if (this._slideshowTimerId !== null) {
+                    scheduleTick();
+                }
+            }, this._settings.slideshowInterval);
+        };
+        scheduleTick();
     }
     /**
      * Stop slideshow mode.
@@ -27167,7 +27259,7 @@ class GveSnapshotRendition extends HTMLElement {
             return;
         }
         this._logger.info("Stopping slideshow");
-        window.clearInterval(this._slideshowTimerId);
+        window.clearTimeout(this._slideshowTimerId);
         this._slideshowTimerId = null;
         if (this._toolbar) {
             this._toolbar.setSlideshowActive(false);
@@ -40860,7 +40952,7 @@ function requireD () {
 	      + 'pragma private protected public pure ref return scope shared static struct '
 	      + 'super switch synchronized template this throw try typedef typeid typeof union '
 	      + 'unittest version void volatile while with __FILE__ __LINE__ __gshared|10 '
-	      + '__thread __traits __DATE__ __EOF__ __TIME__ __TIMESTAMP__ __VENDOR__ 2.0.5',
+	      + '__thread __traits __DATE__ __EOF__ __TIME__ __TIMESTAMP__ __VENDOR__ 2.0.7',
 	    built_in:
 	      'bool cdouble cent cfloat char creal dchar delegate double dstring float function '
 	      + 'idouble ifloat ireal long real short string ubyte ucent uint ulong ushort wchar '