@nitesh-tyagi/vectorflow 1.0.0

package/src/engine.js

@@ -0,0 +1,134 @@
+/**
+ * VectorFlow — Engine
+ * Route resolution, ms precedence, step expansion.
+ */
+
+/**
+ * Resolve the path from currentState to targetState using routes.
+ * Returns an array of state names to visit.
+ *
+ * @param {string} targetState
+ * @param {string} currentState
+ * @param {object} routes — normalized routes object
+ * @returns {string[]}
+ */
+export function resolvePath(targetState, currentState, routes) {
+  const routeBlock = routes[targetState];
+  if (!routeBlock) {
+    return [targetState]; // fallback: direct
+  }
+
+  // Try specific path for current state
+  if (Array.isArray(routeBlock[currentState])) {
+    return routeBlock[currentState];
+  }
+
+  // Try wildcard
+  if (Array.isArray(routeBlock['*'])) {
+    return routeBlock['*'];
+  }
+
+  // Fallback: direct
+  return [targetState];
+}
+
+/**
+ * Normalize a path by removing a leading state that matches currentState
+ * to avoid a no-op step.
+ *
+ * @param {string[]} path
+ * @param {string} currentState
+ * @returns {string[]}
+ */
+export function normalizePath(path, currentState) {
+  if (path.length > 0 && path[0] === currentState) {
+    return path.slice(1);
+  }
+  return path;
+}
+
+/**
+ * Resolve the ms for a step using the precedence chain:
+ * action.ms > routes[target].ms > json.ms > 120
+ *
+ * @param {number|undefined} actionMs
+ * @param {number|undefined} routeMs — routes[targetState].ms
+ * @param {number} jsonMs
+ * @returns {number}
+ */
+export function resolveMs(actionMs, routeMs, jsonMs) {
+  if (typeof actionMs === 'number' && actionMs > 0) return actionMs;
+  if (typeof routeMs === 'number' && routeMs > 0) return routeMs;
+  if (typeof jsonMs === 'number' && jsonMs > 0) return jsonMs;
+  return 120;
+}
+
+/**
+ * Expand a sequence action into a list of normalized steps.
+ *
+ * @param {string[]} order — target states to visit
+ * @param {string} currentState
+ * @param {object} routes
+ * @param {number|undefined} actionMs
+ * @param {number} jsonMs
+ * @param {Set<string>} validStates — set of known state names
+ * @returns {{ steps: Array<{state: string, ms: number}>, finalState: string }}
+ */
+export function expandSequence(order, currentState, routes, actionMs, jsonMs, validStates) {
+  const steps = [];
+  let current = currentState;
+
+  for (const targetState of order) {
+    // Validate state exists
+    if (validStates && !validStates.has(targetState)) {
+      throw new Error(`VectorFlow: State not found in SVG: "${targetState}"`);
+    }
+
+    const path = normalizePath(resolvePath(targetState, current, routes), current);
+
+    for (const nextState of path) {
+      if (validStates && !validStates.has(nextState)) {
+        throw new Error(`VectorFlow: State not found in SVG: "${nextState}"`);
+      }
+
+      const routeMs = routes[nextState]?.ms;
+      const ms = resolveMs(actionMs, routeMs, jsonMs);
+      steps.push({ state: nextState, ms });
+      current = nextState;
+    }
+  }
+
+  return { steps, finalState: current };
+}
+
+/**
+ * Expand a direct-mode action into steps (skip route resolution).
+ *
+ * @param {string[]} order
+ * @param {string} currentState
+ * @param {object} routes — still needed for ms lookup
+ * @param {number|undefined} actionMs
+ * @param {number} jsonMs
+ * @param {Set<string>} validStates
+ * @returns {{ steps: Array<{state: string, ms: number}>, finalState: string }}
+ */
+export function expandDirect(order, currentState, routes, actionMs, jsonMs, validStates) {
+  const steps = [];
+  let current = currentState;
+
+  for (const targetState of order) {
+    if (validStates && !validStates.has(targetState)) {
+      throw new Error(`VectorFlow: State not found in SVG: "${targetState}"`);
+    }
+
+    // In direct mode, skip if already at target
+    if (targetState === current) continue;
+
+    const routeMs = routes[targetState]?.ms;
+    const ms = resolveMs(actionMs, routeMs, jsonMs);
+    steps.push({ state: targetState, ms });
+    current = targetState;
+  }
+
+  return { steps, finalState: current };
+}

package/src/index.d.ts

@@ -0,0 +1,63 @@
+declare type VectorFlowEvent = 'stateChange' | 'actionStart' | 'actionEnd' | 'error';
+
+declare interface VectorFlowOptions {
+  /** An SVG DOM element or raw SVG string */
+  svgElement: SVGElement | string;
+  /** VectorFlow JSON config (object or string) */
+  json: VectorFlowConfig | string;
+}
+
+declare interface VectorFlowConfig {
+  name?: string;
+  initial_state: string;
+  ms?: number;
+  routes: Record<string, VectorFlowRoute>;
+  actions: Record<string, VectorFlowAction>;
+}
+
+declare interface VectorFlowRoute {
+  ms?: number;
+  [sourceState: string]: string[] | number | undefined;
+}
+
+declare interface VectorFlowAction {
+  type?: 'sequence' | 'loop';
+  order: string[];
+  ms?: number;
+  count?: number;
+  mode?: 'direct';
+}
+
+declare class VectorFlow {
+  constructor(options: VectorFlowOptions);
+
+  /** All discovered state names */
+  readonly states: string[];
+  /** Current active state */
+  readonly currentState: string;
+  /** Actions config from JSON */
+  readonly actions: Record<string, VectorFlowAction>;
+  /** The SVG element being animated */
+  readonly svgElement: SVGElement;
+  /** Whether an action is currently playing */
+  readonly isPlaying: boolean;
+  /** Name of the currently playing action */
+  readonly currentAction: string | null;
+
+  /** Play a named action. Auto-cancels any running action. */
+  play(actionName: string): Promise<void>;
+  /** Cancel current playback immediately. */
+  stop(): void;
+  /** Register an event listener. */
+  on(event: 'stateChange', callback: (state: string) => void): this;
+  on(event: 'actionStart', callback: (actionName: string) => void): this;
+  on(event: 'actionEnd', callback: (actionName: string) => void): this;
+  on(event: 'error', callback: (error: Error) => void): this;
+  /** Remove an event listener. */
+  off(event: VectorFlowEvent, callback: (...args: any[]) => void): this;
+  /** Clean up: stop playback, restore SVG, remove listeners. */
+  destroy(): void;
+}
+
+export default VectorFlow;
+export { VectorFlow, VectorFlowOptions, VectorFlowConfig, VectorFlowRoute, VectorFlowAction, VectorFlowEvent };

package/src/index.js

@@ -0,0 +1,264 @@
+/**
+ * VectorFlow — Main entry point
+ * Public API: VectorFlow class.
+ */
+
+import {
+  parseAndValidateJSON,
+  discoverStates,
+  discoverParts,
+  setupLiveCharacter,
+  buildStateSnapshots,
+} from './parser.js';
+
+import {
+  expandSequence,
+  expandDirect,
+} from './engine.js';
+
+import { runAction } from './player.js';
+
+/**
+ * VectorFlow — A JSON-driven SVG pose animation runner.
+ *
+ * Usage:
+ *   const vf = new VectorFlow({ svgElement, json });
+ *   vf.play('shuffle');
+ *   vf.stop();
+ *   vf.on('stateChange', (state) => console.log(state));
+ */
+class VectorFlow {
+  /**
+   * @param {object} options
+   * @param {SVGElement|string} options.svgElement — An SVG DOM element or an SVG string
+   * @param {object|string} options.json — A VectorFlow JSON config (object or string)
+   */
+  constructor({ svgElement, json }) {
+    // Event listeners
+    this._listeners = {
+      stateChange: [],
+      actionStart: [],
+      actionEnd: [],
+      error: [],
+    };
+
+    // Current abort controller for cancellation
+    this._abortController = null;
+    this._currentActionName = null;
+
+    // Parse JSON
+    this._config = parseAndValidateJSON(json);
+
+    // Resolve SVG element
+    if (typeof svgElement === 'string') {
+      const container = document.createElement('div');
+      container.innerHTML = svgElement.trim();
+      this._svgElement = container.querySelector('svg');
+      if (!this._svgElement) {
+        throw new Error('VectorFlow: Provided SVG string does not contain an <svg> element.');
+      }
+    } else if (svgElement instanceof SVGElement) {
+      this._svgElement = svgElement;
+    } else {
+      throw new Error('VectorFlow: svgElement must be an SVG DOM element or an SVG string.');
+    }
+
+    // Discover states and parts
+    this._stateMap = discoverStates(this._svgElement);
+    this._stateParts = discoverParts(this._stateMap);
+    this._validStates = new Set(this._stateMap.keys());
+
+    // Validate initial_state exists
+    if (!this._validStates.has(this._config.initial_state)) {
+      const available = Array.from(this._validStates).join(', ');
+      throw new Error(
+        `VectorFlow: initial_state "${this._config.initial_state}" not found in SVG. Available states: ${available}`
+      );
+    }
+
+    // Build snapshots from original state groups (before hiding)
+    this._stateSnapshots = buildStateSnapshots(this._stateParts);
+
+    // Set up live character
+    const { liveGroup, liveParts } = setupLiveCharacter(
+      this._svgElement, this._stateMap, this._config.initial_state
+    );
+    this._liveGroup = liveGroup;
+    this._liveParts = liveParts;
+
+    // Track current state
+    this._currentState = this._config.initial_state;
+  }
+
+  // ---- Public API: Properties ----
+
+  /** Get all discovered state names. */
+  get states() {
+    return Array.from(this._validStates);
+  }
+
+  /** Get the current state name. */
+  get currentState() {
+    return this._currentState;
+  }
+
+  /** Get the actions config object. */
+  get actions() {
+    return { ...this._config.actions };
+  }
+
+  /** Get the SVG element being animated. */
+  get svgElement() {
+    return this._svgElement;
+  }
+
+  /** Whether an action is currently playing. */
+  get isPlaying() {
+    return this._abortController !== null && !this._abortController.signal.aborted;
+  }
+
+  /** Name of the currently playing action (null if none). */
+  get currentAction() {
+    return this._currentActionName;
+  }
+
+  // ---- Public API: Methods ----
+
+  /**
+   * Play a named action. Cancels any currently playing action.
+   * @param {string} actionName
+   * @returns {Promise<void>}
+   */
+  async play(actionName) {
+    const action = this._config.actions[actionName];
+    if (!action) {
+      const err = new Error(`VectorFlow: Unknown action "${actionName}"`);
+      this._emit('error', err);
+      throw err;
+    }
+
+    if (action.order.length === 0) {
+      console.warn(`VectorFlow: Action "${actionName}" has empty order — no-op.`);
+      return;
+    }
+
+    // Cancel any running action
+    this.stop();
+
+    // New abort controller
+    this._abortController = new AbortController();
+    this._currentActionName = actionName;
+    this._emit('actionStart', actionName);
+
+    try {
+      const finalState = await runAction(
+        action,
+        this._currentState,
+        this._config.routes,
+        this._config.ms,
+        this._validStates,
+        this._liveParts,
+        this._stateSnapshots,
+        this._abortController.signal,
+        (state) => {
+          this._currentState = state;
+          this._emit('stateChange', state);
+        },
+        { expandSequence, expandDirect }
+      );
+
+      if (finalState) {
+        this._currentState = finalState;
+      }
+
+      this._currentActionName = null;
+      this._emit('actionEnd', actionName);
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        // Cancelled — not an error
+        return;
+      }
+      this._currentActionName = null;
+      this._emit('error', err);
+      throw err;
+    }
+  }
+
+  /**
+   * Stop/cancel any currently playing action.
+   */
+  stop() {
+    if (this._abortController) {
+      this._abortController.abort();
+      this._abortController = null;
+      if (this._currentActionName) {
+        const name = this._currentActionName;
+        this._currentActionName = null;
+        this._emit('actionEnd', name);
+      }
+    }
+  }
+
+  /**
+   * Register an event listener.
+   * @param {'stateChange'|'actionStart'|'actionEnd'|'error'} event
+   * @param {function} callback
+   */
+  on(event, callback) {
+    if (!this._listeners[event]) {
+      this._listeners[event] = [];
+    }
+    this._listeners[event].push(callback);
+    return this;
+  }
+
+  /**
+   * Remove an event listener.
+   * @param {string} event
+   * @param {function} callback
+   */
+  off(event, callback) {
+    if (this._listeners[event]) {
+      this._listeners[event] = this._listeners[event].filter(cb => cb !== callback);
+    }
+    return this;
+  }
+
+  /**
+   * Clean up: stop playback, restore SVG state groups, remove live character.
+   */
+  destroy() {
+    this.stop();
+
+    // Show original state groups again
+    if (this._stateMap) {
+      for (const [, groupEl] of this._stateMap) {
+        groupEl.style.display = '';
+      }
+    }
+
+    // Remove live group
+    if (this._liveGroup && this._liveGroup.parentNode) {
+      this._liveGroup.remove();
+    }
+
+    this._listeners = { stateChange: [], actionStart: [], actionEnd: [], error: [] };
+  }
+
+  // ---- Private ----
+
+  _emit(event, data) {
+    if (this._listeners[event]) {
+      for (const cb of this._listeners[event]) {
+        try {
+          cb(data);
+        } catch (e) {
+          console.error(`VectorFlow: Error in "${event}" listener:`, e);
+        }
+      }
+    }
+  }
+}
+
+export default VectorFlow;
+export { VectorFlow };

package/src/parser.js

@@ -0,0 +1,226 @@
+/**
+ * VectorFlow — Parser
+ * JSON validation/normalization + SVG state/part discovery.
+ */
+
+import { readSnapshot } from './utils.js';
+
+/**
+ * Parse and validate a VectorFlow JSON config.
+ * Returns a normalized config object.
+ * Throws on invalid input.
+ */
+export function parseAndValidateJSON(input) {
+  let json;
+  if (typeof input === 'string') {
+    try {
+      json = JSON.parse(input);
+    } catch (e) {
+      throw new Error(`VectorFlow: Invalid JSON — ${e.message}`);
+    }
+  } else if (typeof input === 'object' && input !== null) {
+    json = input;
+  } else {
+    throw new Error('VectorFlow: JSON input must be a string or object');
+  }
+
+  // Validate required fields
+  if (!json.initial_state || typeof json.initial_state !== 'string') {
+    throw new Error('VectorFlow: JSON must have a string "initial_state" field');
+  }
+  if (!json.routes || typeof json.routes !== 'object') {
+    throw new Error('VectorFlow: JSON must have a "routes" object');
+  }
+  if (!json.actions || typeof json.actions !== 'object') {
+    throw new Error('VectorFlow: JSON must have an "actions" object');
+  }
+
+  // Normalize top-level ms
+  const globalMs = (typeof json.ms === 'number' && json.ms > 0) ? json.ms : 120;
+
+  // Validate routes
+  const routes = {};
+  for (const [target, block] of Object.entries(json.routes)) {
+    if (typeof block !== 'object' || block === null) {
+      throw new Error(`VectorFlow: routes["${target}"] must be an object`);
+    }
+    routes[target] = {};
+    for (const [key, value] of Object.entries(block)) {
+      if (key === 'ms') {
+        if (typeof value !== 'number') {
+          throw new Error(`VectorFlow: routes["${target}"].ms must be a number`);
+        }
+        routes[target].ms = value;
+      } else {
+        if (!Array.isArray(value) || !value.every(s => typeof s === 'string')) {
+          throw new Error(`VectorFlow: routes["${target}"]["${key}"] must be an array of strings`);
+        }
+        routes[target][key] = value;
+      }
+    }
+  }
+
+  // Normalize actions
+  const actions = {};
+  for (const [name, action] of Object.entries(json.actions)) {
+    const type = (action.type === 'loop') ? 'loop' : 'sequence';
+
+    if (!Array.isArray(action.order) || action.order.length === 0) {
+      console.warn(`VectorFlow: action "${name}" has no valid order — will be a no-op`);
+      actions[name] = { type, order: [], ms: undefined, count: undefined, mode: undefined };
+      continue;
+    }
+
+    const ms = (typeof action.ms === 'number' && action.ms > 0) ? action.ms : undefined;
+    let count;
+    let mode;
+
+    if (type === 'loop') {
+      count = (typeof action.count === 'number' && action.count > 0) ? action.count : 99999;
+      mode = (typeof action.mode === 'string') ? action.mode : undefined;
+    }
+
+    actions[name] = { type, order: action.order, ms, count, mode };
+  }
+
+  return {
+    name: json.name || 'untitled',
+    initial_state: json.initial_state,
+    ms: globalMs,
+    routes,
+    actions,
+  };
+}
+
+/**
+ * Discover state groups from an SVG element.
+ * Returns a Map: stateName → SVG <g> element.
+ * Throws if no state groups found.
+ */
+export function discoverStates(svgElement) {
+  const stateGroups = svgElement.querySelectorAll('g[id^="state_"]');
+  if (stateGroups.length === 0) {
+    throw new Error('VectorFlow: No state groups found in SVG. Expected groups with id="state_{name}".');
+  }
+
+  const stateMap = new Map();
+  for (const g of stateGroups) {
+    const stateName = g.id.replace(/^state_/, '');
+    if (stateName) {
+      stateMap.set(stateName, g);
+    }
+  }
+
+  if (stateMap.size === 0) {
+    throw new Error('VectorFlow: No valid state groups found in SVG.');
+  }
+
+  return stateMap;
+}
+
+/**
+ * Discover parts from all state groups.
+ * Returns a Map: stateName → Map(partName → element).
+ * Validates that all states have identical part sets.
+ */
+export function discoverParts(stateMap) {
+  const stateParts = new Map();
+  let referencePartNames = null;
+  let referenceStateName = null;
+
+  for (const [stateName, groupEl] of stateMap) {
+    const parts = new Map();
+    const partEls = groupEl.querySelectorAll('[data-part]');
+
+    for (const el of partEls) {
+      const partName = el.getAttribute('data-part');
+      if (partName) {
+        parts.set(partName, el);
+      }
+    }
+
+    if (parts.size === 0) {
+      throw new Error(`VectorFlow: State "${stateName}" has no parts (elements with data-part attribute).`);
+    }
+
+    // Validate matching part sets
+    const currentPartNames = Array.from(parts.keys()).sort().join(',');
+    if (referencePartNames === null) {
+      referencePartNames = currentPartNames;
+      referenceStateName = stateName;
+    } else if (currentPartNames !== referencePartNames) {
+      throw new Error(
+        `VectorFlow: Part mismatch between states. ` +
+        `State "${referenceStateName}" has parts [${referencePartNames}] ` +
+        `but state "${stateName}" has parts [${currentPartNames}].`
+      );
+    }
+
+    stateParts.set(stateName, parts);
+  }
+
+  return stateParts;
+}
+
+/**
+ * Set up the live character group.
+ * Clones the initial state, inserts into SVG, hides original state groups.
+ * Returns { liveGroup: element, liveParts: Map(partName → element) }.
+ */
+export function setupLiveCharacter(svgElement, stateMap, initialState) {
+  const initialGroup = stateMap.get(initialState);
+  if (!initialGroup) {
+    const available = Array.from(stateMap.keys()).join(', ');
+    throw new Error(
+      `VectorFlow: initial_state "${initialState}" not found in SVG. Available states: ${available}`
+    );
+  }
+
+  // Remove any existing live group
+  const existingLive = svgElement.querySelector('#live_character');
+  if (existingLive) {
+    existingLive.remove();
+  }
+
+  // Clone initial state
+  const liveGroup = initialGroup.cloneNode(true);
+  liveGroup.id = 'live_character';
+  liveGroup.removeAttribute('style');
+  liveGroup.style.display = '';
+
+  // Insert live group into SVG
+  svgElement.appendChild(liveGroup);
+
+  // Hide all original state groups
+  for (const [, groupEl] of stateMap) {
+    groupEl.style.display = 'none';
+  }
+
+  // Build live parts map
+  const liveParts = new Map();
+  const partEls = liveGroup.querySelectorAll('[data-part]');
+  for (const el of partEls) {
+    const partName = el.getAttribute('data-part');
+    if (partName) {
+      liveParts.set(partName, el);
+    }
+  }
+
+  return { liveGroup, liveParts };
+}
+
+/**
+ * Build snapshots for all states and parts.
+ * Returns Map: stateName → Map(partName → snapshot).
+ */
+export function buildStateSnapshots(stateParts) {
+  const snapshots = new Map();
+  for (const [stateName, parts] of stateParts) {
+    const partSnapshots = new Map();
+    for (const [partName, el] of parts) {
+      partSnapshots.set(partName, readSnapshot(el));
+    }
+    snapshots.set(stateName, partSnapshots);
+  }
+  return snapshots;
+}