@myrmidon/gve-snapshot-rendition 2.0.5 → 2.0.7

package/dist/models.d.ts

@@ -91,78 +91,49 @@ export interface CharNode {
     label: string;
     data: string;
     sourceTag?: string;
-    features?: Feature[];
+    /** Features keyed by version tag (e.g. "v1" → feature list). */
+    features?: Record<string, Feature[]>;
 }
 /**
  * Execution step of a char-based chain operation.
  */
 export interface ChainOperationContextStep {
-    /**
-     * The operation that was executed.
-     */
+    /** The operation that was executed. */
     operation: CharChainOperation;
-    /**
-     * The input version tag.
-     */
+    /** The input version tag. */
     inputTag: string;
-    /**
-     * The output version tag.
-     */
+    /** The output version tag. */
     outputTag: string;
-    /**
-     * The string synthetically representing the resulting text
-     * version.
-     */
+    /** The string synthetically representing the resulting text version. */
     result?: string;
-    /**
-     * The features emitted up to the executed operation.
-     * These are the features of the text as a whole, and
-     * those belonging to specific nodes, each keyed under
-     * a string built with `v` + output version tag + `_`
-     * + node ID (e.g. `v1_2` for node with ID 2 at version 1).
-     */
-    featureSet: {
-        features: OperationFeature[];
-        nodeFeatures: Record<string, OperationFeature[]>;
-    };
-    /**
-     * The reference node IDs of the operation which was
-     * executed.
-     */
+    /** The reference node IDs of the operation which was executed. */
     refNodeIds: number[];
 }
 /**
  * Result of execution of a char-based chain.
  */
 export interface CharChainResult {
-    /**
-     * The base text, as an array of character nodes or string.
-     * This is not returned by the API, but can be supplied
-     * by the caller.
-     */
-    text?: CharNode[] | string;
-    /**
-     * The execution steps of the chain.
-     */
+    /** The execution steps of the chain. */
     steps: ChainOperationContextStep[];
+    /** The chain dump, which is the text representation of the chain. */
+    chainDump: string | null;
+    /** The list of all unique tags in the chain, including v0. */
+    chainTags: string[];
     /**
-     * The chain dump, which is the text representation of the chain.
+     * All character nodes in the chain (base text and added nodes).
+     * Node features are keyed by version tag.
      */
-    chainDump: string;
+    nodes: CharNode[];
     /**
-     * The list of all unique tags in the chain.
+     * IDs of nodes forming each version's text, keyed by version tag.
+     * Includes v0 (base text).
      */
-    chainTags: string[];
+    versionNodeIds: Record<string, number[]>;
     /**
-     * The sets of nodes in their order, for each version tag.
-     * These nodes are collected by following the path defined
-     * by the set of links of each version tag; so each of the
-     * sets contains only the nodes used at that step to build
-     * the text version, with their features up to that stage.
+     * Global features accumulated up to each version, keyed by version tag.
+     * Includes v0 (empty list).
      */
-    taggedNodes: {
-        [key: string]: CharNode[];
-    };
+    globalFeatures: Record<string, OperationFeature[]>;
 }
 /**
  * The input and output tags of a char-based chain operation.

package/dist/rendering/feature-resolver.d.ts

@@ -1,4 +1,4 @@
-import { Feature, OperationFeature } from "../models";
+import { Feature, CharNode } from "../models";
 import { GveRenditionSettings } from "../settings/settings";
 import { Logger } from "../core/logger";
 /**
@@ -11,7 +11,6 @@ export interface HintOverrides {
     scaleX?: string;
     scaleY?: string;
     rotation?: string;
-    solid?: boolean;
     displacedSpan?: {
         nodeId: number;
         count: number;
@@ -36,13 +35,13 @@ export interface RenditionConfig {
     textPosition?: string;
     textOffsetX: number | string;
     textOffsetY: number | string;
-    textSolid?: boolean;
     textDisplacedSpan?: {
         nodeId: number;
         count: number;
     };
+    textValue?: string;
     hints?: string[];
-    hintOverrides?: Map<string, HintOverrides>;
+    hintOverrides?: Map<string | number, HintOverrides>;
     hintVars?: Map<string, string>;
 }
 /**
@@ -63,20 +62,19 @@ export declare class FeatureResolver {
      * @returns Resolved rendition configuration
      */
     resolve(baseSettings: GveRenditionSettings, features: Feature[] | undefined, nodeFeatureContext?: {
-        nodeFeatures: Record<string, OperationFeature[]>;
+        refNodes: CharNode[];
         outputTag: string;
-        refNodeIds: number[];
     }): RenditionConfig;
     /**
      * Extract character offsets from init features.
      * This is used for base text layout adjustments.
      *
      * @param features - Features from the first annotate operation (init features)
-     * @returns Map of node IDs to their offsets
+     * @returns Map of node IDs to their offsets (values may be numbers or "Ntw"/"Nth" strings)
      */
     extractCharOffsets(features: Feature[] | undefined): Map<number, {
-        x?: number;
-        y?: number;
+        x?: number | string;
+        y?: number | string;
     }>;
     /**
      * Check if features contain a specific rendition feature.
@@ -88,7 +86,9 @@ export declare class FeatureResolver {
     getRenditionFeatureValue(features: Feature[] | undefined, featureName: string): string | undefined;
     /**
      * Parse r_h-* hint override features.
-     * Format: "value" applies to all hints, or "@hintId1 hintId2:value" applies to specific hints.
+     * Format: "value" applies to all hints, or "@target1 target2:value" applies to specific hints.
+     * Targets can be hint ID strings or 1-based ordinal integers (e.g., "@1 beta:e" targets
+     * the first hint by position and all hints with key "beta"). Numbers and keys can be mixed.
      *
      * @param featureName - The feature name (e.g., "r_h-position")
      * @param value - The feature value

package/dist/rendering/hint-renderer.d.ts

@@ -4,7 +4,6 @@ import { OperationHint } from "../settings/hint-models";
 import { Logger } from "../core/logger";
 import { AnimationEngine } from "../animation/animation-engine";
 import { BoundsCache } from "./bounds-cache";
-import { SpreadingEngine } from "./spreading-engine";
 import { HintOverrides } from "./feature-resolver";
 /**
  * Hint renderer handles rendering of operation hints.
@@ -15,8 +14,7 @@ export declare class HintRenderer {
     private _logger;
     private _animationEngine;
     private _boundsCache;
-    private _spreadingEngine;
-    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache, spreadingEngine: SpreadingEngine);
+    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache);
     /**
      * Render a hint for an operation.
      *
@@ -35,10 +33,13 @@ export declare class HintRenderer {
      * @param viewportHeight - Height of the visible viewport (for prolog)
      * @returns Promise that resolves when rendering completes
      */
-    renderHint(hintId: string, hint: OperationHint, referenceNodes: CharNode[], rootSvg: SVGElement, variables: Map<string, string>, operationId: string, hintOrdinal: number, allBaseNodes: CharNode[], versionTag: string, hintOverrides?: Map<string, HintOverrides>, panZoomInstance?: any, viewportWidth?: number, viewportHeight?: number): Promise<void>;
+    renderHint(hintId: string, hint: OperationHint, referenceNodes: CharNode[], rootSvg: SVGElement, variables: Map<string, string>, operationId: string, hintOrdinal: number, allBaseNodes: CharNode[], versionTag: string, hintOverrides?: Map<string | number, HintOverrides>, panZoomInstance?: any, viewportWidth?: number, viewportHeight?: number): Promise<void>;
     /**
      * 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).
      */
     private calculateRBRs;
     /**
@@ -86,18 +87,14 @@ export declare class HintRenderer {
      * This is the point on the EBR that should align with the RBR alignment point.
      */
     private calculateEBRAlignmentPoint;
-    /**
-     * Handle spreading for solid hints.
-     * @param versionTag - Version tag for tracking spreading history
-     */
-    private handleSpreading;
     /**
      * Apply r_h-* overrides to hint properties.
-     * Overrides can target specific hints or all hints ("*").
+     * Priority (lowest to highest): wildcard ("*") < key-based < ordinal-based.
      *
      * @param hint - Original hint design
-     * @param hintId - ID of the hint being rendered
-     * @param hintOverrides - Map of overrides from r_h-* features
+     * @param hintId - ID (key) of the hint being rendered
+     * @param hintOrdinal - 1-based ordinal position of this hint within the operation
+     * @param hintOverrides - Map of overrides from r_h-* features (keyed by ID string or ordinal number)
      * @param allBaseNodes - All base nodes for displaced span resolution
      * @returns Modified hint with overrides applied
      */

package/dist/rendering/svg-utils.d.ts

@@ -100,8 +100,45 @@ export declare function getRectCenter(rect: DOMRect | {
 /**
  * Get computed text width for a given text and style.
  * Creates a temporary SVG element to measure.
+ *
+ * IMPORTANT: The measurementRoot parameter is critical for correct measurements
+ * when the component runs inside Angular or other frameworks that apply global
+ * CSS styles (like font-family) to document.body. Without it, measurements
+ * happen in document.body where inherited styles may affect font metrics,
+ * but actual rendering happens inside Shadow DOM where styles are isolated.
+ * This mismatch causes text positions and hint placements to be incorrect.
+ *
+ * When measurementRoot is provided (typically the component's root SVG element),
+ * measurements happen in the same CSS context as the actual rendering,
+ * ensuring consistent font metrics.
+ *
+ * @param text - The text to measure
+ * @param fontFamily - Font family to use
+ * @param fontSize - Font size in pixels
+ * @param bold - Whether text is bold
+ * @param italic - Whether text is italic
+ * @param measurementRoot - Optional SVG element to use as measurement context.
+ *                          If provided, a temporary text element is appended here
+ *                          for measurement (same CSS context as rendering).
+ *                          If not provided, falls back to document.body (legacy behavior).
+ */
+export declare function getTextWidth(text: string, fontFamily: string, fontSize: number, bold?: boolean, italic?: boolean, measurementRoot?: SVGElement): number;
+/**
+ * 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.
+ */
+export declare 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).
  */
-export declare function getTextWidth(text: string, fontFamily: string, fontSize: number, bold?: boolean, italic?: boolean): number;
+export declare function getAverageCharWidth(fontFamily: string, fontSize: number, bold?: boolean, italic?: boolean, measurementRoot?: SVGElement): number;
 /**
  * Move an element to the back (lowest z-index in SVG).
  */

package/dist/rendering/text-layout.d.ts

@@ -1,6 +1,7 @@
 import { CharNode } from "../models";
 import { GveRenditionSettings } from "../settings/settings";
 import { Logger } from "../core/logger";
+import { RenditionConfig } from "./feature-resolver";
 /**
  * Position information for a character node.
  */
@@ -19,7 +20,29 @@ export declare class TextLayout {
     private _settings;
     private _logger;
     private _spaceWidth;
+    /**
+     * The SVG element used as the measurement context for text width calculations.
+     * This ensures measurements happen in the same CSS context as actual rendering,
+     * which is critical when the component runs inside frameworks like Angular
+     * that may apply global CSS styles affecting font metrics.
+     *
+     * When this is undefined, measurements fall back to document.body (legacy behavior)
+     * which can cause position mismatches if global styles differ from Shadow DOM styles.
+     */
+    private _measurementRoot?;
     constructor(settings: GveRenditionSettings, logger: Logger);
+    /**
+     * Set the measurement root for text width calculations.
+     * This should be called with the root SVG element after it's created,
+     * before any layout calculations are performed.
+     *
+     * IMPORTANT: This ensures text measurements happen in the same CSS context
+     * as actual rendering (inside Shadow DOM), avoiding position mismatches
+     * caused by different font metrics in document.body vs Shadow DOM.
+     *
+     * @param root - The SVG element to use as measurement context
+     */
+    setMeasurementRoot(root: SVGElement): void;
     /**
      * Calculate the width of a space character based on reference character.
      */
@@ -28,13 +51,15 @@ export declare class TextLayout {
      * Calculate positions for all base text nodes.
      *
      * @param nodes - The character nodes to position
-     * @param charOffsets - Map of node IDs to their offset overrides (from r_char-offsets feature)
+     * @param charOffsets - Map of node IDs to their offset overrides (from r_char-offsets feature).
+     *   Offset values may be plain numbers (px) or strings with units "tw"/"th"
+     *   (average character width / height of the current font).
      * @returns Array of character positions
      */
     calculateBaseTextPositions(nodes: CharNode[], charOffsets?: Map<number, {
-        x?: number;
-        y?: number;
-    }>): CharPosition[];
+        x?: number | string;
+        y?: number | string;
+    }>, nodeConfigs?: Map<number, RenditionConfig>): CharPosition[];
     /**
      * Calculate position for a single additional text node.
      * Additional text positioning is driven by rendition features.

package/dist/rendering/text-renderer.d.ts

@@ -3,7 +3,6 @@ import { GveRenditionSettings } from "../settings/settings";
 import { Logger } from "../core/logger";
 import { AnimationEngine } from "../animation/animation-engine";
 import { BoundsCache } from "./bounds-cache";
-import { SpreadingEngine } from "./spreading-engine";
 import { RenditionConfig } from "./feature-resolver";
 /**
  * Text renderer handles rendering of base text and additional text.
@@ -13,10 +12,15 @@ export declare class TextRenderer {
     private _logger;
     private _animationEngine;
     private _boundsCache;
-    private _spreadingEngine;
     private _textLayout;
-    private _featureResolver;
-    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache, spreadingEngine: SpreadingEngine);
+    /**
+     * Reference to the root SVG element for text width measurements.
+     * This ensures measurements happen in the same CSS context as rendering,
+     * which is critical when running inside Angular or other frameworks
+     * that apply global CSS styles to document.body.
+     */
+    private _measurementRoot?;
+    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache);
     /**
      * Render base text (v0).
      *
@@ -26,9 +30,9 @@ export declare class TextRenderer {
      * @returns Promise that resolves when rendering completes
      */
     renderBaseText(nodes: CharNode[], rootSvg: SVGElement, charOffsets?: Map<number, {
-        x?: number;
-        y?: number;
-    }>): Promise<void>;
+        x?: number | string;
+        y?: number | string;
+    }>, nodeConfigs?: Map<number, RenditionConfig>): Promise<void>;
     /**
      * Render a single character node.
      */
@@ -51,21 +55,28 @@ export declare class TextRenderer {
     /**
      * Calculate positions for additional text characters.
      * Additional text flows left to right from the base position.
+     * When config is provided its font metrics are used for character width
+     * measurement, matching what applyTextStyle will actually render.
      */
     private calculateAdditionalTextPositions;
     /**
-     * Calculate RBRs from reference nodes.
-     * Nodes on different lines create separate RBRs.
+     * Calculate the RBR anchor point for a given position type.
+     * This is the point on the RBR where the corresponding EBR point will land.
      */
-    private calculateRBRs;
+    private calculateRBRAlignmentPoint;
     /**
-     * Calculate target position on the RBR based on position type.
+     * Calculate the EBR anchor point for a given position type.
+     * This is the point on the EBR that should coincide with the RBR anchor point.
      */
-    private calculateTargetPosition;
+    private calculateEBRAlignmentPoint;
     /**
-     * Calculate bounding rectangle for a set of positioned characters.
+     * 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).
      */
-    private calculateTextBounds;
+    private calculateRBRs;
     /**
      * Update settings.
      */

package/dist/settings/hint-models.d.ts

@@ -46,11 +46,6 @@ export interface OperationHint {
      * Rotation is applied with reference to the origin of the reference bounding rectangle.
      */
     rotation: number;
-    /**
-     * Whether this hint is "solid" and requires spreading.
-     * Default: false (most hints are overlays that don't need spreading)
-     */
-    solid?: boolean;
     /**
      * JS code for animating the hint's entrance via GSAP.
      * If it starts with "#", it references an animation from settings.animations.

package/dist/settings/settings.d.ts

@@ -78,8 +78,6 @@ export interface GveRenditionSettings {
     animations: Record<string, string>;
     /** ID of animation to use for each character (from animations catalog) */
     charAnimationId?: string;
-    /** Duration in milliseconds for spreading animation (0=no animation) */
-    spreadTime: number;
     /** Duration in milliseconds for element fade-out animation
      * (backward navigation only): 0=no animation */
     backwardFadeOutTime: number;
@@ -88,8 +86,6 @@ export interface GveRenditionSettings {
     prologDuration: number;
     /** Dictionary of hints, keyed by hint ID */
     hints: Record<string, OperationHint>;
-    /** Margin around each rendered hint in pixels */
-    hintMargin: number;
     /** Design-time width used when creating hints */
     hintDesignWidth: number;
     /** Design-time height used when creating hints */

package/dist/ui/details-area.d.ts

@@ -11,6 +11,7 @@ export declare class DetailsArea {
     private hoveredElementsSection;
     private hiddenFeaturesCheckbox;
     private collapseBtn;
+    private resizeHandle;
     private _settings;
     private _logger;
     private _summaryService;
@@ -18,6 +19,11 @@ export declare class DetailsArea {
     private _showHiddenFeatures;
     private _data;
     private _currentVersionTag;
+    private _isResizing;
+    private _initialHeight;
+    private _initialMouseY;
+    private _isPinned;
+    private _pinnedElements;
     constructor(settings: GveRenditionSettings, logger: Logger);
     create(): HTMLElement;
     /**
@@ -28,6 +34,18 @@ export declare class DetailsArea {
      * Attach event listeners.
      */
     private attachEventListeners;
+    /**
+     * Start resizing the details area.
+     */
+    private startResize;
+    /**
+     * Handle resize drag.
+     */
+    private handleResize;
+    /**
+     * Stop resizing the details area.
+     */
+    private stopResize;
     /**
      * Toggle collapse/expand state.
      */
@@ -53,7 +71,20 @@ export declare class DetailsArea {
     updateHoveredElements(hoveredElements: Array<{
         element: SVGTextElement;
         node: CharNode;
+        versionTag: string;
     }>): void;
+    /**
+     * Render hovered elements with pin button.
+     */
+    private renderHoveredElements;
+    /**
+     * Toggle pin state.
+     */
+    private togglePin;
+    /**
+     * Pin a specific element (triggered by click).
+     */
+    pinElement(element: SVGTextElement, node: CharNode, versionTag: string): void;
     /**
      * Filter features based on hidden features setting.
      */

package/dist/ui/hilites.d.ts

@@ -1,5 +1,4 @@
 import { Logger } from "../core/logger";
-import { CharChainResult } from "../models";
 /**
  * Hilites manager - handles creating and animating hilite rectangles.
  */
@@ -21,20 +20,15 @@ export declare class Hilites {
     updateSettings(hilitePadding: number, hiliteFadeTime: number): void;
     /**
      * Show hilites for a specific version.
-     * @param data - The CharChainResult data
-     * @param versionTag - Version tag to hilite
+     * @param nodeIds - IDs of nodes to hilite (from versionNodeIds[versionTag])
+     * @param versionTag - Version tag label (for logging)
      * @param color - Hilite color
      */
-    showHilites(data: CharChainResult, versionTag: string, color: string): Promise<void>;
+    showHilites(nodeIds: number[], versionTag: string, color: string): Promise<void>;
     /**
      * Clear all hilites.
      */
     clearHilites(): Promise<void>;
-    /**
-     * Get node IDs for a specific version.
-     * For v0, if not found in taggedNodes, falls back to extracting from base text.
-     */
-    private getVersionNodeIds;
     /**
      * Create a hilite rectangle for a text element.
      *

package/dist/ui/operation-summary-service.d.ts

@@ -32,17 +32,14 @@ export declare class OperationSummaryService {
      */
     getNodeText(nodeId: number, versionTag: string): string;
     /**
-     * Get a node by ID, searching in version tagged nodes.
-     *
-     * Searches backwards from the specified version to v0. Since v0 is normalized
-     * and added to taggedNodes by the component during data processing, no special
-     * handling is needed.
+     * Get a node by ID from the flat nodes array.
+     * All nodes (including deleted ones) are always present.
      *
      * @param nodeId - Node ID
-     * @param versionTag - Version tag to search in (searches backwards if not found)
+     * @param versionTag - Unused in new model; kept for API compatibility
      * @returns The node, or null
      */
-    getNode(nodeId: number, versionTag: string): CharNode | null;
+    getNode(nodeId: number, versionTag?: string): CharNode | null;
     /**
      * Get text from a span of nodes.
      * @param nodeIds - Array of node IDs

package/dist/ui/toolbar.d.ts

@@ -13,6 +13,7 @@ export declare class Toolbar {
     private lastBtn;
     private versionLabel;
     private groupBadge;
+    private logDisplay;
     private slideshowStartBtn;
     private slideshowStopBtn;
     private slideshowReverseBtn;
@@ -21,6 +22,7 @@ export declare class Toolbar {
     private zoomOutBtn;
     private fitBtn;
     private downloadBtn;
+    private resetLayoutBtn;
     private _data;
     private _currentVersionIndex;
     private _customButtons;
@@ -56,6 +58,10 @@ export declare class Toolbar {
      * Update version label with current version information.
      */
     private updateVersionLabel;
+    /**
+     * Update the log display with the current operation's log feature.
+     */
+    private updateLogDisplay;
     /**
      * Get version information for current step.
      */
@@ -96,6 +102,10 @@ export declare class Toolbar {
      * Dispatch display event for parent component to handle.
      */
     private dispatchDisplayEvent;
+    /**
+     * Dispatch layout event for parent component to handle.
+     */
+    private dispatchLayoutEvent;
     /**
      * Update data reference (for staged version detection).
      */

package/dist/utils/feature-utils.d.ts

@@ -43,12 +43,16 @@ export declare function filterRenditionFeatures(features: Feature[] | undefined,
  * Parse char-offsets feature value.
  * Format: "ID:y=...,x=... ID:y=...,x=..." (multiple patterns separated by space)
  * Each pattern: ID:y=value,x=value (y and x are optional, can be in any order)
+ * Values can be plain pixels (e.g. "10") or use font-relative units:
+ *   tw = average character width of the base text font
+ *   th = average character height of the base text font (≈ font size)
+ * e.g. "0.5th" = half the average character height, "2tw" = twice the average width.
  *
- * @returns Map of node ID to {x?: number, y?: number}
+ * @returns Map of node ID to {x?: number|string, y?: number|string}
  */
 export declare function parseCharOffsets(value: string): Map<number, {
-    x?: number;
-    y?: number;
+    x?: number | string;
+    y?: number | string;
 }>;
 /**
  * Parse displaced span reference.