@myrmidon/gve-snapshot-rendition 0.0.1

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

@@ -0,0 +1,75 @@
+import { CharNode } from "../models";
+import { GveRenditionSettings } from "../settings/settings";
+import { Logger } from "../core/logger";
+/**
+ * Position information for a character node.
+ */
+export interface CharPosition {
+    x: number;
+    y: number;
+    nodeId: number;
+    lineNumber: number;
+}
+/**
+ * Text layout calculator.
+ * Handles positioning of base text characters, respecting line breaks,
+ * spaces, and character offsets.
+ */
+export declare class TextLayout {
+    private _settings;
+    private _logger;
+    private _spaceWidth;
+    constructor(settings: GveRenditionSettings, logger: Logger);
+    /**
+     * Calculate the width of a space character based on reference character.
+     */
+    private calculateSpaceWidth;
+    /**
+     * 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)
+     * @returns Array of character positions
+     */
+    calculateBaseTextPositions(nodes: CharNode[], charOffsets?: Map<number, {
+        x?: number;
+        y?: number;
+    }>): CharPosition[];
+    /**
+     * Calculate position for a single additional text node.
+     * Additional text positioning is driven by rendition features.
+     *
+     * @param referencePosition - The position to use as reference (e.g., from RBR)
+     * @param position - Position type (n, ne, e, se, s, sw, w, nw, o)
+     * @param offsetX - X offset (can be number or string like "0.5th")
+     * @param offsetY - Y offset (can be number or string like "0.5tw")
+     * @param refBounds - Reference bounding rectangle dimensions
+     * @returns Calculated position
+     */
+    calculateAdditionalTextPosition(referencePosition: {
+        x: number;
+        y: number;
+    }, position: string, offsetX: number, offsetY: number, refBounds: {
+        width: number;
+        height: number;
+    }): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Get the line number for a given node ID from positions.
+     */
+    getLineNumber(positions: CharPosition[], nodeId: number): number;
+    /**
+     * Get all positions for a specific line.
+     */
+    getLinePositions(positions: CharPosition[], lineNumber: number): CharPosition[];
+    /**
+     * Update settings and recalculate space width.
+     */
+    updateSettings(settings: GveRenditionSettings): void;
+    /**
+     * Get the computed space width.
+     */
+    getSpaceWidth(): number;
+}

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

@@ -0,0 +1,73 @@
+import { CharNode } from "../models";
+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.
+ */
+export declare class TextRenderer {
+    private _settings;
+    private _logger;
+    private _animationEngine;
+    private _boundsCache;
+    private _spreadingEngine;
+    private _textLayout;
+    private _featureResolver;
+    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache, spreadingEngine: SpreadingEngine);
+    /**
+     * Render base text (v0).
+     *
+     * @param nodes - Character nodes to render
+     * @param rootSvg - Root SVG element
+     * @param charOffsets - Optional character offset overrides
+     * @returns Promise that resolves when rendering completes
+     */
+    renderBaseText(nodes: CharNode[], rootSvg: SVGElement, charOffsets?: Map<number, {
+        x?: number;
+        y?: number;
+    }>): Promise<void>;
+    /**
+     * Render a single character node.
+     */
+    private renderCharacter;
+    /**
+     * Render additional text added by operations.
+     *
+     * @param nodes - Nodes to render
+     * @param rootSvg - Root SVG element
+     * @param config - Rendition configuration
+     * @param versionTag - Version tag for class
+     * @param referenceNodes - Reference nodes for RBR calculation
+     * @param allBaseNodes - All base text nodes (for displaced span)
+     * @param panZoomInstance - The svg-pan-zoom instance (for prolog)
+     * @param viewportWidth - Width of the visible viewport (for prolog)
+     * @param viewportHeight - Height of the visible viewport (for prolog)
+     * @returns Promise that resolves when rendering completes
+     */
+    renderAdditionalText(nodes: CharNode[], rootSvg: SVGElement, config: RenditionConfig, versionTag: string, referenceNodes: CharNode[], allBaseNodes: CharNode[], panZoomInstance?: any, viewportWidth?: number, viewportHeight?: number): Promise<void>;
+    /**
+     * Calculate positions for additional text characters.
+     * Additional text flows left to right from the base position.
+     */
+    private calculateAdditionalTextPositions;
+    /**
+     * Calculate RBRs from reference nodes.
+     * Nodes on different lines create separate RBRs.
+     */
+    private calculateRBRs;
+    /**
+     * Calculate target position on the RBR based on position type.
+     */
+    private calculateTargetPosition;
+    /**
+     * Calculate bounding rectangle for a set of positioned characters.
+     */
+    private calculateTextBounds;
+    /**
+     * Update settings.
+     */
+    updateSettings(settings: GveRenditionSettings): void;
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Models for operation hints.
+ */
+import { RelativePosition } from "../core/gve-snapshot-rendition";
+/**
+ * An editing operation's hint.
+ * Hints represent the visual counterpart of an operation.
+ */
+export interface OperationHint {
+    /**
+     * SVG code for hint's visuals.
+     * Always has a root `g` element.
+     * May contain placeholders in {{name}} format.
+     */
+    svg: string;
+    /**
+     * Relative position for the hint with respect to the reference bounding rectangle.
+     */
+    position: RelativePosition;
+    /**
+     * X offset from the computed position.
+     * Can be:
+     * - A number (pixels)
+     * - A string with suffix: "0.5th" (half text height), "0.5tw" (half text width)
+     */
+    offsetX: number | string;
+    /**
+     * Y offset from the computed position.
+     * Can be:
+     * - A number (pixels)
+     * - A string with suffix: "0.5th" (half text height), "0.5tw" (half text width)
+     */
+    offsetY: number | string;
+    /**
+     * Horizontal scale: 1 = match bounds width, 1.1 = 110% of bounds width.
+     * Default: 1
+     */
+    scaleX: number;
+    /**
+     * Vertical scale: 1 = match bounds height, 1.1 = 110% of bounds height.
+     * Default: 1
+     */
+    scaleY: number;
+    /**
+     * Rotation in degrees. 0 = no rotation.
+     * 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.
+     * The code receives parameters: (gsap, hintEl, rootEl)
+     */
+    animation?: string;
+    /**
+     * A span of base text with format IDxN where ID=node ID and N=count of chars,
+     * to be used as the RBR instead of the default RBR.
+     * Used for displaced hints.
+     */
+    displacedRefSpan?: string;
+}

package/dist/settings/settings.d.ts

@@ -0,0 +1,122 @@
+import { OperationHint } from "./hint-models";
+/**
+ * Settings for a custom button added to the toolbar.
+ */
+export interface CustomButtonSettings {
+    /** Unique ID for the custom button */
+    id: string;
+    /** Icon to use for the button (can be emoji, Unicode symbol, or HTML) */
+    icon: string;
+    /** Text label for the button */
+    label: string;
+    /** Tooltip shown on hover */
+    tooltip: string;
+    /** Callback invoked when button is pressed */
+    callback: (id: string, svg: SVGElement) => void;
+}
+/**
+ * Settings for the GVE Snapshot Rendition component.
+ */
+export interface GveRenditionSettings {
+    /** Default font size in pixels */
+    fontSize: number;
+    /** Default font family */
+    fontFamily: string;
+    /** Default foreground color */
+    foreColor: string;
+    /** Default background color */
+    backColor: string;
+    /** Default italic state */
+    italic: boolean;
+    /** Default bold state */
+    bold: boolean;
+    /** Default underline thickness in pixels (undefined = no underline) */
+    underline?: number;
+    /** Default overline thickness in pixels (undefined = no overline) */
+    overline?: number;
+    /** Default strikethrough thickness in pixels (undefined = no strike) */
+    strike?: number;
+    /** Fraction of reference character width to use for space width (default: 0.33) */
+    spaceWidthFraction: number;
+    /** Spacing between each character in pixels */
+    charSpacing: number;
+    /** Line height multiplier (1.5 = 150% of font size) */
+    lineHeight: number;
+    /** Additional spacing between lines in pixels */
+    lineSpacing: number;
+    /** Top margin of the text rendition area in pixels */
+    marginTop: number;
+    /** Left margin of the text rendition area in pixels */
+    marginLeft: number;
+    /** Right margin of the text rendition area in pixels */
+    marginRight: number;
+    /** Bottom margin of the text rendition area in pixels */
+    marginBottom: number;
+    /** Initial zoom factor */
+    initialZoom: number;
+    /** Minimum zoom factor */
+    minZoom: number;
+    /** Maximum zoom factor */
+    maxZoom: number;
+    /** Zoom step for zoom in/out */
+    zoomStep: number;
+    /** Milliseconds between each frame in slideshow mode */
+    slideshowInterval: number;
+    /** Whether to loop the slideshow when it ends */
+    slideshowLoop: boolean;
+    /** Milliseconds delay between slideshow restarts (when looping) */
+    slideshowDelay: number;
+    /** Automatically continue forward through operations with the same groupId */
+    autoForwardOnGroup: boolean;
+    /** Enable detailed logging for diagnostic purposes */
+    debug?: boolean;
+    /** Array of custom buttons to add to the toolbar */
+    customButtons?: CustomButtonSettings[];
+    /** Array of button IDs (including custom buttons) to disable */
+    disabledButtonIds?: string[];
+    /** Catalog of animation JS code fragments, keyed by ID */
+    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;
+    /** Duration in milliseconds for prolog panning animation when added
+     * elements would be outside viewport (0=no animation) */
+    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 */
+    hintDesignHeight: number;
+    /** Show the handle element from SVG hint (for diagnostic purposes) */
+    showHintHandles: boolean;
+    /** Padding to increase hilite rectangle size in pixels */
+    hilitePadding: number;
+    /** Duration in milliseconds for hilite fade in/out animation */
+    hiliteFadeTime: number;
+    /** Font family for the version text pane */
+    textPaneFontFamily: string;
+    /** Font size for the version text pane in pixels */
+    textPaneFontSize: number;
+    /** Function to generate operation summary HTML from data, version tag,
+     *  and summary service */
+    opSummaryFn?: (data: any, versionTag: string, summaryService: any) => string;
+    /** Reference glyph width in pixels for scaling hovered text elements */
+    refGlyphWidth: number;
+    /** Reference glyph height in pixels for scaling hovered text elements */
+    refGlyphHeight: number;
+    /** Array of feature names to hide when "hidden features" option is not checked */
+    hiddenFeatures?: string[];
+    /** Optional map of version tag to color (e.g., {v0: '#FFE4E1', v1: '#E1FFE4'}) */
+    versionColors?: Record<string, string>;
+}
+/**
+ * Default settings for the component.
+ */
+export declare const DEFAULT_SETTINGS: GveRenditionSettings;

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

@@ -0,0 +1,81 @@
+import { GveRenditionSettings } from "../settings/settings";
+import { Logger } from "../core/logger";
+import { CharChainResult, CharNode } from "../models";
+/**
+ * Details area component - displays operation metadata and hovered element details.
+ */
+export declare class DetailsArea {
+    private container;
+    private operationSection;
+    private versionFeaturesSection;
+    private hoveredElementsSection;
+    private hiddenFeaturesCheckbox;
+    private collapseBtn;
+    private _settings;
+    private _logger;
+    private _summaryService;
+    private _isCollapsed;
+    private _showHiddenFeatures;
+    private _data;
+    private _currentVersionTag;
+    constructor(settings: GveRenditionSettings, logger: Logger);
+    create(): HTMLElement;
+    /**
+     * Replace feather icon placeholders with actual SVG icons.
+     */
+    private replaceFeatherIcons;
+    /**
+     * Attach event listeners.
+     */
+    private attachEventListeners;
+    /**
+     * Toggle collapse/expand state.
+     */
+    private toggleCollapse;
+    /**
+     * Update the details area with version information.
+     * @param data - The CharChainResult data
+     * @param versionTag - The version tag (e.g., "v0", "v1")
+     */
+    updateVersion(data: CharChainResult | null, versionTag: string): void;
+    /**
+     * Update the operation section with operation summary and features.
+     */
+    private updateOperationSection;
+    /**
+     * Update the version features section with global features.
+     */
+    private updateVersionFeaturesSection;
+    /**
+     * Update the hovered elements section.
+     * @param hoveredElements - Array of hovered text SVG elements with their node data
+     */
+    updateHoveredElements(hoveredElements: Array<{
+        element: SVGTextElement;
+        node: CharNode;
+    }>): void;
+    /**
+     * Filter features based on hidden features setting.
+     */
+    private filterFeatures;
+    /**
+     * Render a list of features as HTML.
+     */
+    private renderFeatureList;
+    /**
+     * Get version index from version tag.
+     */
+    private getVersionIndex;
+    /**
+     * Escape HTML special characters.
+     */
+    private escapeHtml;
+    /**
+     * Clear all sections.
+     */
+    clear(): void;
+    /**
+     * Update settings.
+     */
+    updateSettings(settings: GveRenditionSettings): void;
+}

package/dist/ui/hilites.d.ts

@@ -0,0 +1,69 @@
+import { Logger } from "../core/logger";
+import { CharChainResult } from "../models";
+/**
+ * Hilites manager - handles creating and animating hilite rectangles.
+ */
+export declare class Hilites {
+    private _logger;
+    private _rootSvg;
+    private _hilitesGroup;
+    private _activeHilites;
+    private _hilitePadding;
+    private _hiliteFadeTime;
+    constructor(logger: Logger, hilitePadding: number, hiliteFadeTime: number);
+    /**
+     * Set root SVG element reference.
+     */
+    setRootSvg(rootSvg: SVGSVGElement): void;
+    /**
+     * Update settings.
+     */
+    updateSettings(hilitePadding: number, hiliteFadeTime: number): void;
+    /**
+     * Show hilites for a specific version.
+     * @param data - The CharChainResult data
+     * @param versionTag - Version tag to hilite
+     * @param color - Hilite color
+     */
+    showHilites(data: CharChainResult, 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.
+     *
+     * IMPORTANT: Since hilites are now placed in the same container (viewport group)
+     * as the text elements, they share the same coordinate space and transforms.
+     * This means getBBox() gives us the correct relative coordinates, and the
+     * hilites will automatically pan/zoom with the text when PROLOG is triggered.
+     */
+    private createHiliteRect;
+    /**
+     * Animate hilites in using GSAP.
+     */
+    private animateHilitesIn;
+    /**
+     * Animate hilites out using GSAP.
+     */
+    private animateHilitesOut;
+    /**
+     * Check if hilites are currently active.
+     */
+    hasActiveHilites(): boolean;
+    /**
+     * Get the SVG container where hilites should be added.
+     * When svg-pan-zoom is active, this returns the viewport group.
+     * Otherwise, returns the root SVG.
+     *
+     * CRITICAL: svg-pan-zoom wraps all content in a <g> viewport element.
+     * Hilites MUST be added to this group, not the root SVG, so they
+     * transform with the content when PROLOG panning occurs.
+     */
+    private getSvgContainer;
+}

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

@@ -0,0 +1,76 @@
+import { CharChainResult, CharNode, ChainOperationContextStep, OperationType } from "../models";
+import { Logger } from "../core/logger";
+/**
+ * Service for building operation summaries.
+ * Provides helper functions to extract and format operation data.
+ */
+export declare class OperationSummaryService {
+    private _logger;
+    private _data;
+    constructor(logger: Logger);
+    /**
+     * Update the data reference.
+     */
+    setData(data: CharChainResult | null): void;
+    /**
+     * Get operation by version tag.
+     * @param versionTag - Version tag (e.g., "v1", "v2")
+     * @returns The step containing the operation, or null
+     */
+    getStepByVersionTag(versionTag: string): ChainOperationContextStep | null;
+    /**
+     * Get operation by ID.
+     * @param operationId - Operation ID
+     * @returns The step containing the operation, or null
+     */
+    getStepByOperationId(operationId: string): ChainOperationContextStep | null;
+    /**
+     * Get text from a node ID by searching in version tagged nodes.
+     * @param nodeId - Node ID
+     * @param versionTag - Version tag to search in (searches backwards if not found)
+     * @returns The node's text, or empty string
+     */
+    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.
+     *
+     * @param nodeId - Node ID
+     * @param versionTag - Version tag to search in (searches backwards if not found)
+     * @returns The node, or null
+     */
+    getNode(nodeId: number, versionTag: string): CharNode | null;
+    /**
+     * Get text from a span of nodes.
+     * @param nodeIds - Array of node IDs
+     * @param versionTag - Version tag
+     * @returns Concatenated text
+     */
+    getSpanText(nodeIds: number[], versionTag: string): string;
+    /**
+     * Get context text around a node or span, including the affected text.
+     * Extends context to word boundaries (space or LF) after collecting minimum characters.
+     * @param nodeIds - Node IDs of the target span (used when atAsIndex is false)
+     * @param versionTag - Version tag
+     * @param atValue - The 'at' value from the operation (node ID or index depending on atAsIndex)
+     * @param atAsIndex - Whether 'at' is an index (true) or node ID (false)
+     * @param contextSize - Minimum number of characters before/after (default: 20)
+     * @returns Context text including the affected span
+     */
+    getContext(nodeIds: number[], versionTag: string, atValue?: number, atAsIndex?: boolean, contextSize?: number): string;
+    /**
+     * Get the operation type as a readable string.
+     */
+    getOperationTypeName(type: OperationType): string;
+    /**
+     * Get version index from version tag.
+     */
+    private getVersionIndex;
+    /**
+     * Escape HTML special characters.
+     */
+    escapeHtml(text: string): string;
+}

package/dist/ui/toolbar.d.ts

@@ -0,0 +1,131 @@
+import { CharChainResult } from "../models";
+import { CustomButtonSettings } from "../settings/settings";
+/**
+ * Comprehensive toolbar component for version navigation, slideshow, zoom, and custom actions.
+ */
+export declare class Toolbar {
+    private container;
+    private firstBtn;
+    private prevBtn;
+    private prevStagedBtn;
+    private nextStagedBtn;
+    private nextBtn;
+    private lastBtn;
+    private versionLabel;
+    private groupBadge;
+    private slideshowStartBtn;
+    private slideshowStopBtn;
+    private slideshowReverseBtn;
+    private autoForwardBtn;
+    private zoomInBtn;
+    private zoomOutBtn;
+    private fitBtn;
+    private downloadBtn;
+    private _data;
+    private _currentVersionIndex;
+    private _customButtons;
+    private _disabledButtonIds;
+    private _slideshowReverse;
+    private _autoForwardEnabled;
+    /**
+     * Get slideshow reverse state.
+     */
+    getSlideshowReverse(): boolean;
+    constructor(container: HTMLElement);
+    /**
+     * Render toolbar UI elements.
+     */
+    private render;
+    /**
+     * Replace feather icon placeholders with actual SVG icons.
+     */
+    private replaceFeatherIcons;
+    /**
+     * Attach event listeners to buttons.
+     */
+    private attachEventListeners;
+    /**
+     * Render custom buttons from settings.
+     */
+    private renderCustomButtons;
+    /**
+     * Update button states and version label.
+     */
+    private updateButtons;
+    /**
+     * Update version label with current version information.
+     */
+    private updateVersionLabel;
+    /**
+     * Get version information for current step.
+     */
+    private getVersionInfo;
+    /**
+     * Check if there is a previous staged version.
+     */
+    private hasPrevStagedVersion;
+    /**
+     * Check if there is a next staged version.
+     */
+    private hasNextStagedVersion;
+    /**
+     * Update slideshow reverse button appearance.
+     */
+    private updateSlideshowReverseButton;
+    /**
+     * Update auto-forward button visual state.
+     */
+    private updateAutoForwardButton;
+    /**
+     * Apply disabled state to buttons from settings.
+     */
+    private applyDisabledButtons;
+    /**
+     * Dispatch navigation event for parent component to handle.
+     */
+    private dispatchNavigationEvent;
+    /**
+     * Dispatch slideshow event for parent component to handle.
+     */
+    private dispatchSlideshowEvent;
+    /**
+     * Dispatch auto-forward event for parent component to handle.
+     */
+    private dispatchAutoForwardEvent;
+    /**
+     * Dispatch display event for parent component to handle.
+     */
+    private dispatchDisplayEvent;
+    /**
+     * Update data reference (for staged version detection).
+     */
+    updateData(data: CharChainResult | null): void;
+    /**
+     * Set current version index (for external updates).
+     */
+    setCurrentIndex(index: number): void;
+    /**
+     * Get current version index.
+     */
+    getCurrentIndex(): number;
+    /**
+     * Set custom buttons from settings.
+     */
+    setCustomButtons(customButtons: CustomButtonSettings[]): void;
+    /**
+     * Set disabled button IDs from settings.
+     */
+    setDisabledButtons(disabledButtonIds: string[]): void;
+    /**
+     * Set slideshow active state (show/hide start/stop buttons).
+     */
+    setSlideshowActive(active: boolean): void;
+    /**
+     * Disable all navigation buttons (e.g., during slideshow).
+     */
+    setNavigationDisabled(disabled: boolean): void;
+    /**
+     * Set auto-forward enabled state and update button appearance.
+     */
+    setAutoForwardEnabled(enabled: boolean): void;
+}