retiam 1.0.2 → 1.0.3

package/dist/src/engine/_core/VectorEntity.d.ts

@@ -1,3 +1,4 @@
+import { IndexInfo, ShowIndicesOptions } from '../utils/IndexInspector';
 import { Entity, EntityOptions } from './Entity';
 import { Path } from '../entities/primitives/2d/Path';
 import { Camera } from '../camera/Camera';
@@ -5,6 +6,10 @@ import { Vec2 } from '../math/vector/Vec2';
 import { Vec3 } from '../math/vector/Vec3';
 import { ISpatialField, SpatialMappingFunction, HomotopyFunction, ComplexMappingFunction } from '../math/fields/SpatialField';
 import { SubdivisionOptions } from '../utils/SubdivisionEngine';
+export declare function registerIndexInspector(inspector: {
+    inspect: (e: any) => any;
+    show: (e: any, opt?: any) => any;
+}): void;
 /**
  * Abstract base class for all 2D vector-based entities.
  * Guarantees support for mathematical path extraction, morphing, and sub-path animations.
@@ -148,4 +153,13 @@ export declare abstract class VectorEntity extends Entity {
      * @param fn Callback invoked for each leaf Path instance along with its sequential index.
      */
     forEachPath(fn: (path: Path, index: number) => void): this;
+    /**
+     * Inspects all sub-paths and prints a formatted table to console.table.
+     */
+    inspectIndices(): IndexInfo[];
+    /**
+     * Generates an overlaid VGroup of numbered badges corresponding to each sub-path index.
+     * Add directly to the scene to visually identify path indices.
+     */
+    showIndices(options?: ShowIndicesOptions): any;
 }

package/dist/src/engine/animation/transform/TransformMatchingShapes.d.ts

@@ -3,8 +3,22 @@ import { Entity } from '../../_core/Entity';
 import { AnimOptions } from '../AnimOptions';
 import { State } from '../../_core/State';
 import { VectorEntity } from '../../_core/VectorEntity';
+import { IndexMap, KeyMap } from './TransformMatchingTex';
 export interface TransformMatchingShapesOptions extends AnimOptions {
     morphUnmatched?: boolean;
+    /**
+     * Explicit path/contour index pair mappings [sourceIndex, targetIndex][].
+     * Direct surgical control: forces source shape path at sourceIndex to map to targetIndex.
+     * Takes highest precedence before geometric/label matching.
+     * @example [[0, 2]] or { 0: 2 }
+     */
+    indexMap?: IndexMap;
+    /**
+     * Explicit shape label or constructor name mapping.
+     * Maps source shape LABEL/name to target shape LABEL/name.
+     * @example { "circle": "square", "leftArm": "rightArm" }
+     */
+    keyMap?: KeyMap;
 }
 export declare class TransformMatchingShapes extends Concurrent {
     private sourceEntity;

package/dist/src/engine/animation/transform/TransformMatchingTex.d.ts

@@ -2,8 +2,23 @@ import { Concurrent } from '../Concurrent';
 import { Tex } from '../../entities/composites/text/Tex';
 import { Text } from '../../entities/composites/text/Text';
 import { AnimOptions } from '../AnimOptions';
+export type IndexMap = [number, number][] | Record<number, number> | Map<number, number>;
+export type KeyMap = Record<string, string> | Map<string, string>;
 export interface TransformMatchingTexOptions extends AnimOptions {
     morphUnmatched?: boolean;
+    /**
+     * Explicit index pair mappings [sourceIndex, targetIndex][].
+     * Direct surgical control: forces path at sourceIndex to map to targetIndex.
+     * Takes highest precedence before key/anchor matching.
+     * @example [[2, 5]] or { 2: 5 }
+     */
+    indexMap?: IndexMap;
+    /**
+     * Explicit symbol/substring translation map.
+     * Maps source symbol/substring to target symbol/substring.
+     * @example { "+": "-", "b^2": "b^2", "\\alpha": "\\beta" }
+     */
+    keyMap?: KeyMap;
 }
 export declare class TransformMatchingTex extends Concurrent {
     /** Resolves the absolute world state matrix mapping. */

package/dist/src/engine/animation/transform/TransformMatchingText.d.ts

@@ -1,8 +1,22 @@
 import { Concurrent } from '../Concurrent';
 import { Text } from '../../entities/composites/text/Text';
 import { AnimOptions } from '../AnimOptions';
+import { IndexMap, KeyMap } from './TransformMatchingTex';
 export interface TransformMatchingOptions extends AnimOptions {
     morphUnmatched?: boolean;
+    /**
+     * Explicit index pair mappings [sourceCharIndex, targetCharIndex][].
+     * Direct surgical control: forces char at sourceCharIndex to map to targetCharIndex.
+     * Takes highest precedence before key/anchor matching.
+     * @example [[0, 3]] or { 0: 3 }
+     */
+    indexMap?: IndexMap;
+    /**
+     * Explicit substring or character translation map.
+     * Maps source substring/character to target substring/character.
+     * @example { "apple": "orange", "A": "B" }
+     */
+    keyMap?: KeyMap;
 }
 export declare class TransformMatchingText extends Concurrent {
     /**

package/dist/src/engine/entities/composites/coordinates/Axes.d.ts

@@ -5,6 +5,7 @@ import { Vec3 } from '../../../math/vector/Vec3';
 import { VGroup } from '../../layout/VGroup';
 import { Path } from '../../primitives/2d/Path';
 import { PathEffect } from '../../../material/PathEffect';
+import { Arrow, ArrowTipType } from '../geometry/Arrow';
 /**
  * Configuration options for the [[Axes]] 2D coordinate system.
  */
@@ -39,6 +40,16 @@ export interface AxesOptions extends CoordinateSystemOptions {
     yLabelFormatter?: AxisLabelFormatter;
     /** Custom formatter callback for 2D coordinate pairs. */
     labelFormatter?: CoordinateLabelFormatter;
+    /** Tip style for the main axis arrows ('stealth' | 'triangle' | 'line' | etc.). Default: 'stealth' */
+    tipType?: ArrowTipType;
+    /** Physical length of arrowhead along the axis. */
+    arrowHeadLength?: number;
+    /** Physical total width of arrowhead transverse to the axis. */
+    arrowHeadWidth?: number;
+    /** Whether to render arrowheads on main axes. Default: true */
+    showArrows?: boolean;
+    /** Alias for showArrows. Default: true */
+    includeArrows?: boolean;
 }
 export declare class Axes extends CoordinateSystem {
     axesGroup: VGroup;
@@ -53,6 +64,14 @@ export declare class Axes extends CoordinateSystem {
     xLabelFormatter?: AxisLabelFormatter;
     yLabelFormatter?: AxisLabelFormatter;
     labelFormatter?: CoordinateLabelFormatter;
+    tipType: ArrowTipType;
+    arrowHeadLength?: number;
+    arrowHeadWidth?: number;
+    showArrows: boolean;
+    xAxis: Arrow;
+    yAxis: Arrow;
+    get xAxisArrow(): Arrow;
+    get yAxisArrow(): Arrow;
     rangeVersion: number;
     private linePool;
     private activeLineCount;
@@ -83,6 +102,7 @@ export declare class Axes extends CoordinateSystem {
      * Adds numerical coordinate labels along the X and Y axes.
      */
     addCoordinates(options?: CoordinateLabelOptions): this;
+    setTipType(type: ArrowTipType): this;
     toPaths(): Path[];
     getSubEntities(): VectorEntity[];
 }

package/dist/src/engine/entities/composites/geometry/Arrow.d.ts

@@ -3,6 +3,10 @@ import { VectorEntity } from '../../../_core/VectorEntity';
 import { Path } from '../../primitives/2d/Path';
 import { Vec3, Vec3Type } from '../../../math/vector/Vec3';
 import { Color } from '../../../math/Color';
+import { Animation } from '../../../animation/Animation';
+import { CreateOptions } from '../../../animation/creation/Create';
+import { TrackBuilder } from '../../../animation/TrackBuilder';
+import { PathEffect } from '../../../material/PathEffect';
 export type ArrowTipType = 'triangle' | 'stealth' | 'line' | 'circle' | 'dot' | 'diamond' | 'bar' | 'tee' | 'square' | 'none';
 export interface ArrowOptions extends EntityOptions {
     points?: Vec3Type[];
@@ -10,6 +14,7 @@ export interface ArrowOptions extends EntityOptions {
     tension?: number;
     segments?: number;
     color?: Color;
+    strokeShader?: PathEffect | string;
     headLength?: number;
     headWidth?: number;
     headAngle?: number;
@@ -76,6 +81,7 @@ export declare class Arrow extends VectorEntity {
     private lastT2;
     private lastT1;
     private lastStrokeWidth;
+    private lastOpacity;
     constructor(start?: Vec3Type, end?: Vec3Type, options?: ArrowOptions);
     setPoints(points: Vec3Type[]): void;
     putStartAndEndOn(start: Vec3Type, end: Vec3Type): void;
@@ -90,6 +96,7 @@ export declare class Arrow extends VectorEntity {
         width?: number;
         color?: Color;
     }): void;
+    setStrokeShader(shader?: PathEffect | string): void;
     private addLineSegment;
     private rebuildCurve;
     private buildTipGeometry;
@@ -98,6 +105,14 @@ export declare class Arrow extends VectorEntity {
     private rebuildSingleHead;
     update(t: number, dt: number): void;
     private syncArrowState;
+    /**
+     * Creation animation hook for TrackBuilder and `Create(arrow)` / `createAnim(arrow)`.
+     */
+    createAnim(t?: TrackBuilder, options?: CreateOptions): Animation;
+    /**
+     * Erase/uncreate animation hook for `Uncreate(arrow)`.
+     */
+    uncreateAnim(options?: CreateOptions): Animation;
     /**
      * Resolves the distinct animatable path structures inside the Arrow (the shaft and the tip(s)).
      */
@@ -107,3 +122,23 @@ export declare class Arrow extends VectorEntity {
      */
     toPaths(): Path[];
 }
+export declare class ArrowCreateAnimation extends Animation {
+    private arrow;
+    private targetT1;
+    private targetT2;
+    private originalStroke;
+    private originalStrokeWidth;
+    private targetStroke;
+    private targetStrokeWidth;
+    constructor(arrow: Arrow, options?: CreateOptions);
+    prepare(): void;
+    update(dt: number): boolean;
+}
+export declare class ArrowUncreateAnimation extends Animation {
+    private arrow;
+    private startT1;
+    private startT2;
+    constructor(arrow: Arrow, options?: CreateOptions);
+    prepare(): void;
+    update(dt: number): boolean;
+}

package/dist/src/engine/entities/composites/geometry/Arrow3D.d.ts

@@ -5,6 +5,9 @@ import { Vec3Type } from '../../../math/vector/Vec3';
 import { Color } from '../../../math/Color';
 import { VectorEntity } from '../../../_core/VectorEntity';
 import { Path } from '../../primitives/2d/Path';
+import { Animation } from '../../../animation/Animation';
+import { CreateOptions } from '../../../animation/creation/Create';
+import { TrackBuilder } from '../../../animation/TrackBuilder';
 export interface Arrow3DOptions extends EntityOptions {
     points?: Vec3Type[];
     isSmooth?: boolean;
@@ -29,6 +32,34 @@ export declare class Arrow3D extends VectorEntity {
     private rebuildCurve;
     update(t: number, dt: number): void;
     private syncArrowState;
+    /**
+     * Creation animation hook for TrackBuilder and `Create(arrow3D)` / `createAnim(arrow3D)`.
+     */
+    createAnim(t?: TrackBuilder, options?: CreateOptions): Animation;
+    /**
+     * Erase/uncreate animation hook for `Uncreate(arrow3D)`.
+     */
+    uncreateAnim(options?: CreateOptions): Animation;
     getSubEntities(): VectorEntity[];
     toPaths(): Path[];
 }
+export declare class Arrow3DCreateAnimation extends Animation {
+    private arrow;
+    private targetT1;
+    private targetT2;
+    private originalStroke;
+    private originalStrokeWidth;
+    private targetStroke;
+    private targetStrokeWidth;
+    constructor(arrow: Arrow3D, options?: CreateOptions);
+    prepare(): void;
+    update(dt: number): boolean;
+}
+export declare class Arrow3DUncreateAnimation extends Animation {
+    private arrow;
+    private startT1;
+    private startT2;
+    constructor(arrow: Arrow3D, options?: CreateOptions);
+    prepare(): void;
+    update(dt: number): boolean;
+}

package/dist/src/engine/utils/IndexInspector.d.ts

@@ -0,0 +1,44 @@
+import { VectorEntity } from '../_core/VectorEntity';
+import { VGroup } from '../entities/layout/VGroup';
+import { Color } from '../math/Color';
+import { Vec3 } from '../math/vector/Vec3';
+export interface IndexInfo {
+    index: number;
+    symbol?: string;
+    label: string;
+    center: Vec3;
+    bounds: Vec3;
+}
+export interface ShowIndicesOptions {
+    /** Font size of the numeric badge labels. Default: 9 */
+    fontSize?: number;
+    /** Foreground text color. Default: Color.fromHex("#facc15") (amber/yellow) */
+    color?: Color;
+    /** Overall badge opacity (0 = transparent, 1 = opaque). Default: 0.75 */
+    opacity?: number;
+    /** Whether to draw a circular badge backdrop behind each number. Default: true */
+    background?: boolean;
+    /** Badge background circle fill color. Default: Color.fromHex("#111827aa") (semi-transparent dark) */
+    backgroundColor?: Color;
+    /** Badge background circle stroke outline color. Default: Color.fromHex("#eab308cc") */
+    borderColor?: Color;
+    /** Badge circle radius in world units. Default: 7.5 */
+    radius?: number;
+}
+/**
+ * Inspects all sub-paths of a VectorEntity (Tex, Text, SVG, VGroup, etc.)
+ * and logs a formatted table to console.table showing their indices, symbols, centers, and bounds.
+ *
+ * @param entity The vector entity to inspect.
+ * @returns Array of metadata objects for each child path.
+ */
+export declare function inspectIndices(entity: VectorEntity): IndexInfo[];
+/**
+ * Generates an overlaid VGroup of numbered circular badges corresponding to each sub-path index.
+ * Useful during scene development to visually identify path indices directly on the canvas.
+ *
+ * @param entity The vector entity whose sub-path indices to show.
+ * @param options Styling options for the index badges.
+ * @returns A VGroup containing the visual badges.
+ */
+export declare function showIndices(entity: VectorEntity, options?: ShowIndicesOptions): VGroup;

package/dist/src/engine/utils/PathEqualizer.d.ts

@@ -18,6 +18,16 @@ export declare class PathEqualizer {
     private static padPaths;
     private static matchPathsSpatially;
     private static getCentroid;
+    /**
+     * Solves minimum-weight bipartite matching.
+     * Uses exact permutation search for small N <= 8, or greedy fallback for larger.
+     */
+    private static solveBipartite;
+    /**
+     * Hierarchical contour classification and matching.
+     * Outer boundaries strictly match Outer boundaries; Holes strictly match Holes.
+     * Matching is evaluated in normalized relative space to eliminate translation distortion.
+     */
     private static equalizePathContours;
     private static padContours;
     private static getControidOfContour;
@@ -26,6 +36,11 @@ export declare class PathEqualizer {
     private static getSignedArea;
     private static reverseContour;
     private static shiftClosedPath;
+    /**
+     * Determines optimal cyclic shift for closed contours.
+     * Evaluates alignment in zero-centered local coordinates to prevent translation distance
+     * from skewing the cyclic dot product.
+     */
     private static findOptimalShift;
     /**
      * O(N) Single-Pass Subdivision.

package/dist/src/index.d.ts

@@ -423,6 +423,7 @@ export * from './engine/utils/Builder';
 export * from './engine/utils/Builder3D';
 export * from './engine/utils/CurveSampleUtils';
 export * from './engine/utils/CurveUtil';
+export * from './engine/utils/IndexInspector';
 export * from './engine/utils/GeometrySnapshot';
 export * from './engine/utils/MarchingSquares';
 export * from './engine/utils/OBJLoader';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retiam",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "WebGPU powered animation engine",
   "type": "module",
   "main": "./dist/retiam.es.js",