@myrmidon/gve-snapshot-rendition 0.0.1

package/dist/models.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Generic name=value feature.
+ */
+export interface Feature {
+    name: string;
+    value: string;
+    setPolicy: FeatureSetPolicy;
+}
+/**
+ * Operation feature set policy.
+ */
+export declare enum FeatureSetPolicy {
+    multiple = 0,
+    single = 1,
+    singleFirst = 2
+}
+/**
+ * Operation feature.
+ */
+export interface OperationFeature extends Feature {
+    isNegated?: boolean;
+    isGlobal?: boolean;
+    isShortLived?: boolean;
+}
+/**
+ * Source about a text variant. This is typically used when
+ * variants come from different witnesses.
+ */
+export interface OperationSource {
+    id: string;
+    type: string;
+    rank?: number;
+    note?: string;
+}
+/**
+ * Diplomatic data for a text variant.
+ */
+export interface OperationDiplomatics {
+    g: string;
+    isNewTextHidden?: boolean;
+    features?: Feature[];
+    elementFeatures?: Record<string, Feature[]>;
+}
+/**
+ * Generic metadata about a text variant generation operation.
+ */
+export interface OperationMetadata {
+    type: OperationType;
+    id: string;
+    rank?: number;
+    groupId?: string;
+    features?: OperationFeature[];
+    sources?: OperationSource[];
+    diplomatics?: OperationDiplomatics;
+}
+/**
+ * Type of a text operation.
+ */
+export declare enum OperationType {
+    replace = 0,
+    delete = 1,
+    addBefore = 2,
+    addAfter = 3,
+    moveBefore = 4,
+    moveAfter = 5,
+    swap = 6,
+    annotate = 7
+}
+/**
+ * Metadata of a char-based chain operation.
+ */
+export interface CharChainOperation extends OperationMetadata {
+    at: number;
+    atAsIndex?: boolean;
+    to?: number;
+    toAsIndex?: boolean;
+    inputTag?: string;
+    outputTag?: string;
+    run: number;
+    toRun?: number;
+    value?: string;
+    noTraceFeatures?: boolean;
+    dsl?: string;
+}
+/**
+ * A single character node in an operation execution result.
+ */
+export interface CharNode {
+    id: number;
+    index: number;
+    label: string;
+    data: string;
+    sourceTag?: string;
+    features?: Feature[];
+}
+/**
+ * Execution step of a char-based chain operation.
+ */
+export interface ChainOperationContextStep {
+    /**
+     * The operation that was executed.
+     */
+    operation: CharChainOperation;
+    /**
+     * The input version tag.
+     */
+    inputTag: string;
+    /**
+     * The output version tag.
+     */
+    outputTag: string;
+    /**
+     * 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.
+     */
+    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.
+     */
+    steps: ChainOperationContextStep[];
+    /**
+     * The chain dump, which is the text representation of the chain.
+     */
+    chainDump: string;
+    /**
+     * The list of all unique tags in the chain.
+     */
+    chainTags: string[];
+    /**
+     * 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.
+     */
+    taggedNodes: {
+        [key: string]: CharNode[];
+    };
+}
+/**
+ * The input and output tags of a char-based chain operation.
+ */
+export interface ChainOperationTags {
+    inputTag: string;
+    outputTag: string;
+}
+/**
+ * The node of a character-based chain, used for diagnostic
+ * or demonstration purposes.
+ */
+export interface CharChainNode {
+    id: number;
+    label: string;
+    data: string;
+    sourceTag?: string;
+}
+/**
+ * The link of a character-based chain, used for diagnostic
+ * or demonstration purposes.
+ */
+export interface CharChainLink {
+    tag: string;
+    sourceId: number;
+    targetId: number;
+}
+/**
+ * The character-based chain, as resulting from running operations
+ * on a base text, used for diagnostic or demonstration purposes.
+ */
+export interface CharChain {
+    nodes: CharChainNode[];
+    links: CharChainLink[];
+}

package/dist/rendering/bounds-cache.d.ts

@@ -0,0 +1,62 @@
+import { Logger } from "../core/logger";
+/**
+ * Bounding rectangle with position and dimensions.
+ */
+export interface BoundingRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Cache for storing bounding rectangles of SVG elements.
+ * This avoids expensive getBBox() calls and improves spreading performance.
+ */
+export declare class BoundsCache {
+    private _cache;
+    private _logger;
+    constructor(logger: Logger);
+    /**
+     * Add or update a bounding rectangle for an element.
+     */
+    set(elementId: string, bounds: DOMRect | SVGRect): void;
+    /**
+     * Get the bounding rectangle for an element.
+     */
+    get(elementId: string): BoundingRect | undefined;
+    /**
+     * Check if an element's bounds are cached.
+     */
+    has(elementId: string): boolean;
+    /**
+     * Remove bounds for an element.
+     */
+    delete(elementId: string): void;
+    /**
+     * Clear all cached bounds.
+     */
+    clear(): void;
+    /**
+     * Get all cached element IDs.
+     */
+    getAllIds(): string[];
+    /**
+     * Get all cached bounds.
+     */
+    getAllBounds(): BoundingRect[];
+    /**
+     * Update bounds for an element by ID from the DOM.
+     * Returns true if successful, false if element not found.
+     */
+    updateFromElement(element: SVGElement): boolean;
+    /**
+     * Get the bounding rectangle that encloses multiple elements.
+     */
+    getUnionBounds(elementIds: string[]): BoundingRect | undefined;
+    /**
+     * Get the number of cached items.
+     */
+    size(): number;
+}

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

@@ -0,0 +1,98 @@
+import { Feature, OperationFeature } from "../models";
+import { GveRenditionSettings } from "../settings/settings";
+import { Logger } from "../core/logger";
+/**
+ * Hint property overrides from r_h-* features.
+ */
+export interface HintOverrides {
+    position?: string;
+    offsetX?: string;
+    offsetY?: string;
+    scaleX?: string;
+    scaleY?: string;
+    rotation?: string;
+    solid?: boolean;
+    displacedSpan?: {
+        nodeId: number;
+        count: number;
+    };
+}
+/**
+ * Resolved rendition configuration for text rendering.
+ */
+export interface RenditionConfig {
+    fontSize: number;
+    fontFamily: string;
+    foreColor: string;
+    backColor: string;
+    italic: boolean;
+    bold: boolean;
+    underline?: number;
+    overline?: number;
+    strike?: number;
+    textLineStyle?: string;
+    textLineColor?: string;
+    rotate?: number;
+    textPosition?: string;
+    textOffsetX: number | string;
+    textOffsetY: number | string;
+    textSolid?: boolean;
+    textDisplacedSpan?: {
+        nodeId: number;
+        count: number;
+    };
+    hints?: string[];
+    hintOverrides?: Map<string, HintOverrides>;
+    hintVars?: Map<string, string>;
+}
+/**
+ * Feature resolver converts features into rendition configuration.
+ * This handles all the r_* rendition features and applies them to create
+ * a complete configuration for rendering.
+ */
+export declare class FeatureResolver {
+    private _logger;
+    constructor(logger: Logger);
+    /**
+     * Resolve rendition features into a complete configuration.
+     * Features override the base settings.
+     *
+     * @param baseSettings - The base settings from component
+     * @param features - Array of features to apply
+     * @param nodeFeatureContext - Optional context for extracting node features for placeholder resolution
+     * @returns Resolved rendition configuration
+     */
+    resolve(baseSettings: GveRenditionSettings, features: Feature[] | undefined, nodeFeatureContext?: {
+        nodeFeatures: Record<string, OperationFeature[]>;
+        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
+     */
+    extractCharOffsets(features: Feature[] | undefined): Map<number, {
+        x?: number;
+        y?: number;
+    }>;
+    /**
+     * Check if features contain a specific rendition feature.
+     */
+    hasRenditionFeature(features: Feature[] | undefined, featureName: string): boolean;
+    /**
+     * Get the value of a rendition feature.
+     */
+    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.
+     *
+     * @param featureName - The feature name (e.g., "r_h-position")
+     * @param value - The feature value
+     * @param config - The rendition config to update
+     */
+    private parseHintOverride;
+}

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

@@ -0,0 +1,109 @@
+import { CharNode } from "../models";
+import { GveRenditionSettings } from "../settings/settings";
+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.
+ * Hints are visual counterparts of editing operations.
+ */
+export declare class HintRenderer {
+    private _settings;
+    private _logger;
+    private _animationEngine;
+    private _boundsCache;
+    private _spreadingEngine;
+    constructor(settings: GveRenditionSettings, logger: Logger, animationEngine: AnimationEngine, boundsCache: BoundsCache, spreadingEngine: SpreadingEngine);
+    /**
+     * Render a hint for an operation.
+     *
+     * @param hintId - ID of the hint from settings.hints
+     * @param hint - The hint configuration
+     * @param referenceNodes - Nodes referenced by the operation (for RBR calculation)
+     * @param rootSvg - Root SVG element to append hint to
+     * @param variables - Variables from r_hint-vars for placeholder resolution
+     * @param operationId - ID of the operation (for unique hint ID)
+     * @param hintOrdinal - Ordinal number of this hint for the operation (1, 2, 3...)
+     * @param allBaseNodes - All base text nodes (for displaced span)
+     * @param versionTag - Version tag to add as CSS class
+     * @param hintOverrides - Optional overrides from r_h-* features
+     * @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
+     */
+    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>;
+    /**
+     * Calculate Reference Bounding Rectangles (RBRs) from reference nodes.
+     * Nodes on different lines create separate RBRs.
+     */
+    private calculateRBRs;
+    /**
+     * Calculate RBRs from a displaced span reference (IDxN format).
+     */
+    private calculateDisplacedRBRs;
+    /**
+     * Calculate scaling information for the hint.
+     * Returns scale factors and target dimensions.
+     */
+    private calculateScalingInfo;
+    /**
+     * Apply size transforms (scale and rotation) to the hint.
+     * Per documentation, these are applied BEFORE positioning.
+     *
+     * IMPORTANT: We DON'T actually apply these as transforms on the element.
+     * Instead, we just return the scaling info and rotation, and later we'll create
+     * a combined transform that includes both sizing and positioning.
+     */
+    private applyHintSizeTransforms;
+    /**
+     * Apply complete transform to the hint (both sizing and positioning).
+     * This builds a single transform that:
+     * 1. Translates so the EBR alignment point is at origin
+     * 2. Scales and rotates the hint
+     * 3. Translates to the final RBR position
+     *
+     * 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.
+     */
+    private applyHintPositionTransform;
+    /**
+     * Get the EBR (Element Bounding Rectangle) for positioning.
+     * Per documentation: if the hint has a handle element, use its bounding box.
+     * Otherwise, use the whole hint's bounding box.
+     */
+    private getEBRBounds;
+    /**
+     * Calculate the alignment point on the RBR based on position type.
+     * This is where the EBR's corresponding alignment point should be positioned.
+     */
+    private calculateRBRAlignmentPoint;
+    /**
+     * Calculate the alignment point on the EBR based on position type.
+     * 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 ("*").
+     *
+     * @param hint - Original hint design
+     * @param hintId - ID of the hint being rendered
+     * @param hintOverrides - Map of overrides from r_h-* features
+     * @param allBaseNodes - All base nodes for displaced span resolution
+     * @returns Modified hint with overrides applied
+     */
+    private applyHintOverrides;
+    /**
+     * Update settings.
+     */
+    updateSettings(settings: GveRenditionSettings): void;
+}

package/dist/rendering/spreading-engine.d.ts

@@ -0,0 +1,98 @@
+import { BoundsCache, BoundingRect } from "./bounds-cache";
+import { Logger } from "../core/logger";
+/**
+ * Result of spreading calculation.
+ */
+export interface SpreadingResult {
+    /** Map of element ID to its horizontal shift amount */
+    horizontalShifts: Map<string, number>;
+    /** Map of element ID to its vertical shift amount */
+    verticalShifts: Map<string, number>;
+    /** Whether any spreading was needed */
+    hasShifts: boolean;
+}
+/**
+ * Metadata about spreading applied to an element for a specific version.
+ */
+export interface SpreadingMetadata {
+    /** Version index that caused this spreading */
+    versionIndex: number;
+    /** Horizontal shift applied (in pixels) */
+    horizontalShift: number;
+    /** Vertical shift applied (in pixels) */
+    verticalShift: number;
+}
+/**
+ * Engine for calculating spreading (making room for new elements).
+ * Implements the "stone in pond" ripple effect to preserve layout.
+ */
+export declare class SpreadingEngine {
+    private _boundsCache;
+    private _logger;
+    /**
+     * Map of element ID to array of spreading metadata (one per version).
+     * Each element can be shifted multiple times by different versions.
+     */
+    private _spreadingHistory;
+    constructor(boundsCache: BoundsCache, logger: Logger);
+    /**
+     * Track spreading metadata for elements affected by a version.
+     * Called after spreading is applied to record what happened.
+     *
+     * @param versionIndex - Version index that caused the spreading
+     * @param horizontalShifts - Map of element IDs to horizontal shifts
+     * @param verticalShifts - Map of element IDs to vertical shifts
+     */
+    trackSpreading(versionIndex: number, horizontalShifts: Map<string, number>, verticalShifts: Map<string, number>): void;
+    /**
+     * Get spreading metadata for elements affected by a specific version.
+     * Used when reversing spreading during backward navigation.
+     *
+     * @param versionIndex - Version index to get spreading for
+     * @returns Map of element ID to spreading metadata
+     */
+    getSpreadingForVersion(versionIndex: number): Map<string, SpreadingMetadata>;
+    /**
+     * Remove spreading history for a specific version.
+     * Called after spreading is reversed during backward navigation.
+     *
+     * @param versionIndex - Version index to remove history for
+     */
+    clearSpreadingForVersion(versionIndex: number): void;
+    /**
+     * Calculate spreading required to make room for a new element.
+     *
+     * @param newElementBounds - Bounds of the element to be added
+     * @param excludeIds - Element IDs to exclude from shifting (e.g., the new element itself)
+     * @returns Spreading result with shift amounts for each affected element
+     */
+    calculateSpreading(newElementBounds: BoundingRect, excludeIds?: string[]): SpreadingResult;
+    /**
+     * Calculate horizontal spreading.
+     * Elements overlapping on the left are shifted left, those on the right are shifted right.
+     */
+    private calculateHorizontalSpreading;
+    /**
+     * Calculate vertical spreading.
+     * Elements overlapping from above are shifted up, those from below are shifted down.
+     */
+    private calculateVerticalSpreading;
+    /**
+     * Calculate the horizontal overlap between two bounding rectangles.
+     * Returns 0 if there is no overlap.
+     */
+    private calculateHorizontalOverlap;
+    /**
+     * Calculate the vertical overlap between two bounding rectangles.
+     * Returns 0 if there is no overlap.
+     */
+    private calculateVerticalOverlap;
+    /**
+     * Check if two bounding rectangles overlap.
+     */
+    checkOverlap(rect1: BoundingRect, rect2: BoundingRect): boolean;
+    /**
+     * Find all elements that overlap with given bounds.
+     */
+    findOverlappingElements(bounds: BoundingRect, excludeIds?: string[]): string[];
+}

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

@@ -0,0 +1,112 @@
+/**
+ * SVG utility functions for creating and manipulating SVG elements.
+ */
+/**
+ * Create an SVG element with the given tag name.
+ */
+export declare function createSVGElement<K extends keyof SVGElementTagNameMap>(tagName: K): SVGElementTagNameMap[K];
+/**
+ * Set multiple attributes on an SVG element.
+ */
+export declare function setAttributes(element: SVGElement, attributes: Record<string, string | number>): void;
+/**
+ * Create an SVG text element with content and attributes.
+ */
+export declare function createTextElement(content: string, attributes?: Record<string, string | number>): SVGTextElement;
+/**
+ * Create an SVG group element.
+ */
+export declare function createGroup(id?: string, classes?: string[]): SVGGElement;
+/**
+ * Create an SVG rect element.
+ */
+export declare function createRect(x: number, y: number, width: number, height: number, attributes?: Record<string, string | number>): SVGRectElement;
+/**
+ * Create an SVG line element.
+ */
+export declare function createLine(x1: number, y1: number, x2: number, y2: number, attributes?: Record<string, string | number>): SVGLineElement;
+/**
+ * Apply text styling attributes based on settings.
+ */
+export declare function applyTextStyle(element: SVGTextElement, style: {
+    fontFamily?: string;
+    fontSize?: number;
+    foreColor?: string;
+    backColor?: string;
+    italic?: boolean;
+    bold?: boolean;
+    underline?: number;
+    overline?: number;
+    strike?: number;
+    rotate?: number;
+}): void;
+/**
+ * Apply line decoration to text (for custom thickness support).
+ * This creates actual line elements for better control over thickness.
+ */
+export declare function applyLineDecoration(parentGroup: SVGGElement, textElement: SVGTextElement, type: "underline" | "overline" | "strike", thickness: number, color: string, style?: string): SVGLineElement;
+/**
+ * Parse SVG from string and return the root element.
+ * Assumes the SVG content has a root <g> element.
+ */
+export declare function parseSVGContent(svgString: string): SVGGElement | null;
+/**
+ * Clone an SVG element and all its children.
+ */
+export declare function cloneSVGElement<T extends SVGElement>(element: T): T;
+/**
+ * Get the bounding box of an SVG element in a safe way.
+ * Returns a default rectangle if getBBox() fails.
+ *
+ * IMPORTANT: This returns the bbox in LOCAL coordinates (without transforms).
+ * Use getTransformedBBox() if you need the actual screen/SVG coordinates.
+ */
+export declare function getSafeBBox(element: SVGElement): DOMRect;
+/**
+ * Get the bounding box of an SVG element WITH transforms applied.
+ * This returns the actual position in the SVG coordinate system.
+ *
+ * This is crucial for visibility checks because getBBox() returns local coords
+ * which don't reflect the element's actual position after transforms.
+ *
+ * @param element - The SVG element
+ * @returns The bounding box in SVG coordinate space (with transforms applied)
+ */
+export declare function getTransformedBBox(element: SVGElement): DOMRect;
+/**
+ * Apply a transform to an SVG element.
+ */
+export declare function applyTransform(element: SVGElement, transform: {
+    translateX?: number;
+    translateY?: number;
+    scaleX?: number;
+    scaleY?: number;
+    rotate?: number;
+    originX?: number;
+    originY?: number;
+}): void;
+/**
+ * Calculate the center point of a bounding rectangle.
+ */
+export declare function getRectCenter(rect: DOMRect | {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+};
+/**
+ * Get computed text width for a given text and style.
+ * Creates a temporary SVG element to measure.
+ */
+export declare function getTextWidth(text: string, fontFamily: string, fontSize: number, bold?: boolean, italic?: boolean): number;
+/**
+ * Move an element to the back (lowest z-index in SVG).
+ */
+export declare function moveToBack(element: SVGElement): void;
+/**
+ * Move an element to the front (highest z-index in SVG).
+ */
+export declare function moveToFront(element: SVGElement): void;