@myrmidon/gve-snapshot-rendition 0.0.1

package/LICENSE

@@ -0,0 +1,4 @@
+License: Pending
+
+This package is published for internal evaluation and staging use only.
+A final open-source license will be added in a future release.

package/README.md

@@ -0,0 +1,135 @@
+# GVE Snapshot Rendition Component
+
+This workspace contains a custom web component for the rendition of a complex Academic model representing the transformations of an autograph text. This peculiar document was written by the hand of the author, and contains a lot of often chaotic annotations on top of a base text. These annotations represent changes to the first draft of the text mostly by the hand of the author himself, thus providing a unique insight in the writer's creative process.
+
+For the purpose of the visualization of the digital model designed to represent this text with all its variations together with its diplomatic data, we consider 3 entities to display:
+
+- the base text, which is the starting point and the bearer of all the annotations.
+- the added text. This is text added by operations like add or replace.
+- all other signs: these are the visual counterparts of editing operations on the text, which hint at them in a graphical way. For instance, a line on top of a text meaning it should be deleted. There is no limit to the variety of these signs: they might be lines, shapes, callouts, boxes, etc.
+
+Text (whether it is base or added text) is represented character by character; each character is named _node_, because in backend, where all the transformations happen, there is a graph-like structure which recombines the same characters to form different versions of the text, just like nodes are connected by edges in a graph.
+
+The transformations are essentially represented by a set of editing operations (like delete, replace, add, move, swap) which are executed one after another starting with a base text. The base text is known as version 0 (tag=`v0`). All the operations are executed in their order and each outputs a new version of the text, progressively numbered (`v1`, `v2`...).
+
+Operations also inject metadata, in form of features (essentially name=value pairs), either into versions as a whole (for global features), or into specific characters of the output text (node features). A specific set of features (rendition features, all starting with prefix `r_`) is used to represent the visual counterpart of each operation; for instance, a delete might be visually represented by a diagonal line on top of the portion of the text being deleted. In this case, multiple features of the operation (which injects them into nodes) are used to set the drawing connected to it, in this case a line, and specify additional parameters like its color. Such drawings are often recurring multiple times; so, they belong to a catalog of so-called "hints", because they hint at the operation with their appearance (e.g. a line stroke on a text hints at its deletion). These hints have entrance animations, handled by GSAP (like any other animations in this project). These too typically belong to a catalog of animations.
+
+Both hints and animations are part of the settings for the component. The component is found under [src/core/gve-snapshot-rendition.ts](src/core/gve-snapshot-rendition.ts), and most of its logic is properly encapsulated in its own set of classes, following a systematic separation of concerns to ensure flexibility, extendibility, and easy maintenance.
+
+## Documentation
+
+Conceptual documentation and sample data:
+
+- [snapshot backend model](docs/snapshot.md): overview of the backend data used by the component.
+- [rendition description](docs/rendition.md): details about the architecture and logic of this component.
+- [sample request to backend snapshot processor](docs/sample/request.json): the request used to generate our sample data via backend. This is used only when we want to change our sample data.
+- [sample response from backend snapshot processor](docs/sample/response.json): the response received from backend corresponding to our request. This is used only when we want to change our sample data.
+- [data used in the demo](data.json): the data loaded in the web component to test it. This is copied from [response.json](docs/sample/response.json), and contains all the data received by the web component for rendering.
+- [features adapter services](docs/adapter.md): complementary services independent from the GVE snapshot rendition component, possibly used to adapt data before passing it to the component.
+
+The test page used in this project is `index.html` and its code is `consumer.js`. The data model is `CharChainResult` and it is found with all the imported models in `models.ts`. These are the models imported from another package and should not be touched.
+
+### Feature Adapter
+
+The **Feature Adapter** is a utility system for transforming features in snapshot data. It enables you to adapt high-level features into low-level rendition features that the component can use:
+
+- [Feature Adapter Overview](docs/adapter.md): Architecture and usage guide.
+- [Detailed Documentation](src/adapter/README.md): Complete API reference and examples.
+
+### Hint Designer
+
+The **Hint Designer** is a companion web component which can be used to help users edit and test their hints SVG and JS animation code. The main web component used for display has no relation with it. Rather, the hint designer component reuses some logic from the main component, while still being aside.
+
+- [hint designer documentation](docs/hint-designer.md)
+- [hint designer usage](src/hint-designer/README.md)
+
+Use the npm script to start the designer:
+
+```bash
+pnpm run start:designer
+```
+
+This will build the component and open the hint designer in your browser.
+
+## Quick Start
+
+To start working with this code:
+
+1. clone this repository.
+2. download dependencies with `pnpm i`.
+3. run with `pnpm start`.
+
+Note: if you need to **update sample data**, follow these steps:
+
+1. open the GVE backend solution and run the demo.
+2. set text and operations as you want (to start with the current data, pick the "rendition features" preset).
+3. click the "build request" button.
+4. paste the request in [docs/sample/request.json](docs/sample/request.json) if you want to make it the default data.
+5. run the GVE backend API and use Postman or similar to send the request body with this header:
+
+    ```txt
+    POST http://localhost:5239/api/text/operations/run
+    Accept: application/json
+    Content-Type: application/json
+
+    ...paste your JSON request body here...
+    ```
+
+6. copy the response and paste it into [data.json](data.json) and also into [docs/sample/response.json](docs/sample/response.json) if you want to make it the default data.
+
+## Requirements
+
+This component requires the following packages:
+
+- [GSAP](https://gsap.com) for animations (`pnpm i gsap @types/gsap`).
+- [svg-pan-zoom](https://github.com/bumbu/svg-pan-zoom) for zooming and panning (`pnpm i svg-pan-zoom @types/svg-pan-zoom`).
+- [fast-diff](https://github.com/jhchen/fast-diff) for text diffing (`pnpm i fast-diff @types/fast-diff`).
+- [feather-icons](https://github.com/feathericons/feather) for icons. See also the [icons list](https://feathericons.com) (`pnpm i feather-icons`).
+- [highlight.js](https://highlightjs.org/) for the hint designer (syntax highlight for SVG and JS code; `pnpm i highlight.js`).
+
+## Task List
+
+This is only a reminder.
+
+- consider simplifying logic by drawing node features from tagged nodes rather than from steps.
+
+## Deployment
+
+You must be logged into NPM with your account (verify with `npm whoami`, login with `npm login` if required).
+
+1. ensure that tests pass (`pnpm test`) and be sure to build (`pnpm build`).
+2. publish via `pnpm run publish:public` or directly via `npm publish --access=public`.
+
+Check that your package is available:
+
+```bash
+npm view @myrmidon/gve-snapshot-rendition
+```
+
+Or visit: <https://www.npmjs.com/package/@myrmidon/gve-snapshot-rendition>
+
+The following files/directories are included in the package (defined in `package.json` `files` field):
+
+- `dist/` - Compiled JavaScript and TypeScript declarations
+- `README.md` - Package documentation
+- `LICENSE` - License file
+
+The package includes these automated scripts:
+
+- **prepublishOnly**: Runs before `npm publish` - executes tests and build
+- **prepack**: Runs before creating a tarball - executes build
+- **publish:public**: Custom script to publish with public access
+
+To unpublish a specific version:
+
+```bash
+npm unpublish @myrmidon/gve-snapshot-rendition@0.0.1
+```
+
+To unpublish the entire package (only allowed within 72 hours):
+
+```bash
+npm unpublish @myrmidon/gve-snapshot-rendition --force
+```
+
+>⚠️ Unpublishing can break projects that depend on your package. Only do this for critical security issues or accidental publications.

package/dist/adapter/adapter-models.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Models and types for the feature adapter system.
+ */
+import { Feature } from "../models.js";
+/**
+ * Comparison operator for feature matching.
+ */
+export declare enum ComparisonOperator {
+    /** Equals (string) */
+    EQUALS = "=",
+    /** Not equals (string) */
+    NOT_EQUALS = "!=",
+    /** Starts with */
+    STARTS_WITH = "^=",
+    /** Ends with */
+    ENDS_WITH = "$=",
+    /** Contains */
+    CONTAINS = "*=",
+    /** Matches wildcards (? and *) */
+    MATCHES_WILDCARDS = "?=",
+    /** Matches regular expression */
+    MATCHES_REGEX = "~",
+    /** Numeric equals */
+    NUMERIC_EQUALS = "==",
+    /** Numeric not equals */
+    NUMERIC_NOT_EQUALS = "<>",
+    /** Numeric greater than */
+    NUMERIC_GT = ">",
+    /** Numeric less than */
+    NUMERIC_LT = "<",
+    /** Numeric greater than or equal */
+    NUMERIC_GTE = ">=",
+    /** Numeric less than or equal */
+    NUMERIC_LTE = "<="
+}
+/**
+ * Logical operator for combining clauses.
+ */
+export declare enum LogicalOperator {
+    AND = "AND",
+    OR = "OR",
+    AND_NOT = "AND NOT",
+    OR_NOT = "OR NOT"
+}
+/**
+ * Token type for DSL parsing.
+ */
+export declare enum TokenType {
+    /** Feature name */
+    NAME = 0,
+    /** Comparison operator */
+    OPERATOR = 1,
+    /** Value (quoted or unquoted) */
+    VALUE = 2,
+    /** Logical operator (AND, OR, AND NOT, OR NOT) */
+    LOGICAL = 3,
+    /** Left parenthesis */
+    LPAREN = 4,
+    /** Right parenthesis */
+    RPAREN = 5,
+    /** Left square bracket for group capture */
+    LBRACKET = 6,
+    /** Right square bracket for group capture */
+    RBRACKET = 7,
+    /** Colon (used in named groups) */
+    COLON = 8,
+    /** End of input */
+    EOF = 9
+}
+/**
+ * Token from DSL parsing.
+ */
+export interface Token {
+    type: TokenType;
+    value: string;
+    position: number;
+}
+/**
+ * A single clause in a pattern (e.g., "name=value").
+ */
+export interface Clause {
+    /** Feature name to match */
+    name: string;
+    /** Comparison operator (optional if just matching by name) */
+    operator?: ComparisonOperator;
+    /** Value to compare against (optional if just matching by name) */
+    value?: string;
+    /** Whether this clause should be captured as a group */
+    capture?: boolean;
+    /** Group name (if named capture), or undefined for numbered capture */
+    groupName?: string;
+}
+/**
+ * Pattern expression node (for AST representation).
+ */
+export interface PatternExpression {
+    type: "clause" | "logical";
+}
+/**
+ * Clause expression node.
+ */
+export interface ClauseExpression extends PatternExpression {
+    type: "clause";
+    clause: Clause;
+}
+/**
+ * Logical expression node (binary operation).
+ */
+export interface LogicalExpression extends PatternExpression {
+    type: "logical";
+    operator: LogicalOperator;
+    left: PatternExpression;
+    right: PatternExpression;
+}
+/**
+ * Result of matching a pattern against features.
+ */
+export interface MatchResult {
+    /** Whether the pattern matched */
+    matched: boolean;
+    /** Captured groups (keyed by group name or number as string) */
+    captures: Map<string, CapturedGroup>;
+    /** Features that were matched */
+    matchedFeatures: Feature[];
+}
+/**
+ * A captured group from pattern matching.
+ */
+export interface CapturedGroup {
+    name: string;
+    value: string;
+}
+/**
+ * Mode for feature processing.
+ */
+export declare enum ProcessingMode {
+    /** Add features without removing matched ones */
+    ADD = "add",
+    /** Replace: remove matched features, then add new ones */
+    REPLACE = "replace"
+}
+/**
+ * A single adapter operation configuration.
+ */
+export interface AdapterOperation {
+    /** Pattern DSL string to match features */
+    pattern: string;
+    /** Features to add (with format "name=value", can include placeholders) */
+    features: string[];
+    /** Processing mode (default: add) */
+    mode?: ProcessingMode;
+}
+/**
+ * Configuration for the feature adapter.
+ */
+export interface FeatureAdapterSettings {
+    /** List of adapter operations to apply in order */
+    operations: AdapterOperation[];
+}
+/**
+ * Error thrown during DSL parsing or pattern matching.
+ */
+export declare class AdapterError extends Error {
+    position?: number | undefined;
+    context?: string | undefined;
+    constructor(message: string, position?: number | undefined, context?: string | undefined);
+    /**
+     * Format error message with context.
+     */
+    toString(): string;
+}

package/dist/adapter/data-feature-adapter.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Data feature adapter for applying feature transformations to CharChainResult data.
+ */
+import { CharChainResult } from "../models";
+import { FeatureAdapterSettings } from "./adapter-models";
+/**
+ * Adapter service that applies feature transformations to CharChainResult data.
+ * This service creates a copy of the data and adapts all features except those
+ * belonging to operation metadata.
+ */
+export declare class DataFeatureAdapter {
+    private featureAdapter;
+    constructor(settings: FeatureAdapterSettings);
+    /**
+     * Adapt all features in the CharChainResult data.
+     * Returns a new copy of the data with adapted features.
+     *
+     * Features adapted:
+     * - steps[i].featureSet.features (global features)
+     * - steps[i].featureSet.nodeFeatures (node-specific features)
+     * - taggedNodes[version][i].features (features on nodes)
+     *
+     * Features NOT adapted:
+     * - steps[i].operation.features (operation metadata)
+     */
+    adaptData(data: CharChainResult): CharChainResult;
+    /**
+     * Deep copy the CharChainResult data structure.
+     */
+    private deepCopyData;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Feature adapter service for transforming feature sets.
+ */
+import { FeatureAdapterSettings } from "./adapter-models";
+import { Feature } from "../models";
+/**
+ * Service for adapting features based on configured operations.
+ */
+export declare class FeatureAdapter {
+    private settings;
+    private compiledPatterns;
+    private matcher;
+    constructor(settings: FeatureAdapterSettings);
+    /**
+     * Adapt a feature array by applying all configured operations.
+     */
+    adapt(features: Feature[]): Feature[];
+    /**
+     * Apply a single operation to a feature array.
+     */
+    private applyOperation;
+    /**
+     * Create features from feature specifications, resolving placeholders.
+     */
+    private createFeatures;
+    /**
+     * Resolve placeholders in a string (e.g., $1.value, $color.name).
+     */
+    private resolvePlaceholders;
+    /**
+     * Pre-compile all patterns to detect errors early.
+     */
+    private compilePatterns;
+}

package/dist/adapter/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Feature adapter module - public API.
+ */
+export { FeatureAdapter } from "./feature-adapter.js";
+export { DataFeatureAdapter } from "./data-feature-adapter.js";
+export type { FeatureAdapterSettings, AdapterOperation, ProcessingMode, ComparisonOperator, LogicalOperator, AdapterError, } from "./adapter-models.js";

package/dist/adapter/matcher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Feature matching engine for the adapter.
+ */
+import { PatternExpression, MatchResult } from "./adapter-models";
+import { Feature } from "../models";
+/**
+ * Matches features against a pattern expression.
+ */
+export declare class FeatureMatcher {
+    /**
+     * Match features against a parsed pattern expression.
+     */
+    match(features: Feature[], expression: PatternExpression): MatchResult;
+    /**
+     * Evaluate a pattern expression against features.
+     */
+    private evaluateExpression;
+    /**
+     * Evaluate a clause against features.
+     */
+    private evaluateClause;
+    /**
+     * Check if a single feature matches a clause.
+     */
+    private matchFeature;
+    /**
+     * Compare values using the specified operator.
+     */
+    private compareValues;
+    /**
+     * Match a value against a wildcard pattern (? and *).
+     */
+    private matchWildcard;
+    /**
+     * Compare numeric values.
+     */
+    private compareNumeric;
+}

package/dist/adapter/parser.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Parser for the feature adapter DSL.
+ * Implements recursive descent parsing with operator precedence:
+ * 1. NOT (highest)
+ * 2. AND
+ * 3. OR (lowest)
+ */
+import { PatternExpression } from "./adapter-models";
+/**
+ * Parser for DSL patterns.
+ */
+export declare class Parser {
+    private input;
+    private tokens;
+    private position;
+    private current;
+    private groupCounter;
+    constructor(input: string);
+    /**
+     * Parse the pattern and return the AST.
+     */
+    parse(): PatternExpression;
+    /**
+     * Parse OR expression (lowest precedence).
+     * or_expr := and_expr (OR and_expr | OR NOT and_expr)*
+     */
+    private parseOrExpression;
+    /**
+     * Parse AND expression (middle precedence).
+     * and_expr := primary (AND primary | AND NOT primary)*
+     */
+    private parseAndExpression;
+    /**
+     * Parse primary expression (clause or grouped expression).
+     * primary := clause | '(' or_expr ')' | '[' clause ']' | '[' NAME ':' clause ']'
+     */
+    private parsePrimary;
+    /**
+     * Parse a captured clause: [name:clause] or [clause]
+     */
+    private parseCapturedClause;
+    /**
+     * Parse a clause: name [operator value]
+     */
+    private parseClause;
+    /**
+     * Advance to the next token.
+     */
+    private advance;
+    /**
+     * Peek at the next token without consuming it.
+     */
+    private peek;
+    /**
+     * Get context around a position for error messages.
+     */
+    private getContext;
+}

package/dist/adapter/tokenizer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Tokenizer for the feature adapter DSL.
+ */
+import { Token } from "./adapter-models";
+/**
+ * Tokenizes a DSL pattern string into tokens.
+ */
+export declare class Tokenizer {
+    private input;
+    private position;
+    private current;
+    private expectValue;
+    constructor(input: string);
+    /**
+     * Tokenize the entire input.
+     */
+    tokenize(): Token[];
+    /**
+     * Get the next token from input.
+     */
+    private nextToken;
+    /**
+     * Try to read a comparison operator.
+     */
+    private tryReadOperator;
+    /**
+     * Read a quoted string (handles escape sequences).
+     */
+    private readQuotedString;
+    /**
+     * Read a word (name or keyword).
+     */
+    private readWord;
+    /**
+     * Read an unquoted value (after an operator).
+     * Values can include special characters like *, ?, ^, $, etc.
+     */
+    private readUnquotedValue;
+    /**
+     * Peek at the next word without consuming it.
+     */
+    private peekWord;
+    /**
+     * Skip whitespace.
+     */
+    private skipWhitespace;
+    /**
+     * Advance to next character.
+     */
+    private advance;
+    /**
+     * Get context around current position for error messages.
+     */
+    private getContext;
+}

package/dist/animation/animation-engine.d.ts

@@ -0,0 +1,118 @@
+import { Logger } from "../core/logger";
+import { AnimationFactory, AnimationFunction } from "./animation-factory";
+/**
+ * Animation engine that wraps GSAP and provides a consistent API.
+ */
+export declare class AnimationEngine {
+    private _gsap;
+    private _logger;
+    private _factory;
+    constructor(gsap: any, logger: Logger);
+    /**
+     * Get the animation factory.
+     */
+    getFactory(): AnimationFactory;
+    /**
+     * Animate an element with an animation function.
+     *
+     * @param element - The target SVG element
+     * @param animation - The animation function to execute
+     * @param rootElement - The root SVG element
+     * @returns Promise that resolves when animation completes
+     */
+    animate(element: SVGElement, animation: AnimationFunction, rootElement: SVGElement): Promise<void>;
+    /**
+     * Animate multiple elements with spreading transitions.
+     * All elements are animated in parallel with GSAP.
+     *
+     * @param shifts - Map of element IDs to their shift amounts {x, y}
+     * @param duration - Duration in milliseconds
+     * @param rootElement - The root SVG element containing all elements
+     * @returns Promise that resolves when all animations complete
+     */
+    animateSpreading(shifts: Map<string, {
+        x: number;
+        y: number;
+    }>, duration: number, rootElement: SVGElement): Promise<void>;
+    /**
+     * Fade in multiple elements (used for hilites).
+     *
+     * @param elements - Array of elements to fade in
+     * @param duration - Duration in milliseconds
+     * @returns Promise that resolves when animation completes
+     */
+    fadeIn(elements: SVGElement[], duration: number): Promise<void>;
+    /**
+     * Fade out multiple elements (used for hilites).
+     *
+     * @param elements - Array of elements to fade out
+     * @param duration - Duration in milliseconds
+     * @returns Promise that resolves when animation completes
+     */
+    fadeOut(elements: SVGElement[], duration: number): Promise<void>;
+    /**
+     * Animate pan and zoom transition.
+     *
+     * @param panZoomInstance - The svg-pan-zoom instance
+     * @param newPan - New pan coordinates {x, y}
+     * @param newZoom - New zoom level
+     * @param duration - Duration in milliseconds
+     * @returns Promise that resolves when animation completes
+     */
+    animatePanZoom(panZoomInstance: any, newPan: {
+        x: number;
+        y: number;
+    }, newZoom: number, duration: number): Promise<void>;
+    /**
+     * Animate prolog panning to make an element visible.
+     * This gracefully pans the viewport so there is room to display an element
+     * that would otherwise fall outside the visible area.
+     *
+     * @param panZoomInstance - The svg-pan-zoom instance
+     * @param elementBounds - Bounding rectangle of the element to make visible
+     * @param viewportWidth - Width of the visible viewport
+     * @param viewportHeight - Height of the visible viewport
+     * @param duration - Duration in milliseconds
+     * @returns Promise that resolves when animation completes
+     */
+    animateProlog(panZoomInstance: any, elementBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, viewportWidth: number, viewportHeight: number, duration: number): Promise<void>;
+    /**
+     * Calculate the pan adjustment needed to make an element visible.
+     * Returns null if the element is already fully visible.
+     *
+     * @param elementBounds - Bounding rectangle of the element in SVG coordinates
+     * @param panZoomInstance - The svg-pan-zoom instance
+     * @param viewportWidth - Width of the visible viewport
+     * @param viewportHeight - Height of the visible viewport
+     * @returns New pan coordinates or null if no adjustment needed
+     */
+    private calculatePrologPan;
+    /**
+     * Check if an element is fully visible in the current viewport.
+     *
+     * @param elementBounds - Bounding rectangle of the element in SVG coordinates
+     * @param panZoomInstance - The svg-pan-zoom instance
+     * @param viewportWidth - Width of the visible viewport
+     * @param viewportHeight - Height of the visible viewport
+     * @returns True if element is fully visible, false otherwise
+     */
+    isElementVisible(elementBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, panZoomInstance: any, viewportWidth: number, viewportHeight: number): boolean;
+    /**
+     * Kill all active animations.
+     */
+    killAll(): void;
+    /**
+     * Get the GSAP instance.
+     */
+    getGsap(): any;
+}