@clypra/runtime 1.0.0

package/src/graph/types.ts

@@ -0,0 +1,176 @@
+/**
+ * @clypra/runtime — Graph Types
+ *
+ * Defines immutable node, value, capability, and lifecycle schemas for the Media Processing Graph.
+ * These types are shared across all Labs (Video, Transition, Body).
+ */
+
+export type NodeLifecycleState = "Created" | "Validated" | "Compiled" | "Prepared" | "Executing" | "Completed" | "Disposed";
+
+export type GraphDataType = "Texture" | "Depth" | "MotionField" | "BoundingBoxes" | "Mask" | "Pose" | "FaceMesh" | "Particles" | "AudioSpectrum" | "Metadata";
+
+export interface GraphValue<T = any> {
+  readonly type: GraphDataType;
+  readonly payload: T;
+}
+
+export interface EffectCapabilities {
+  readonly temporal: boolean;
+  readonly stateful: boolean;
+  readonly spatial: boolean;
+  readonly geometry: boolean;
+  readonly inputsCount: number;
+}
+
+export interface EffectRequirements {
+  readonly temporalRadius: number;
+  readonly preferredPrecision: "fp8" | "fp16" | "fp32";
+  readonly multipass: boolean;
+  readonly supportsHalfResolution: boolean;
+}
+
+export interface GraphPin {
+  readonly id: string;
+  readonly name: string;
+  readonly type: GraphDataType;
+}
+
+export interface GraphNode {
+  readonly id: string;
+  readonly type: string;
+  readonly version: number; // Current parameter version for dirty propagation
+  readonly params: Readonly<Record<string, any>>;
+  readonly inputs: Readonly<Record<string, GraphPin>>;
+  readonly outputs: Readonly<Record<string, GraphPin>>;
+  readonly capabilities: EffectCapabilities;
+  readonly requirements: EffectRequirements;
+  readonly lifecycle: NodeLifecycleState;
+}
+
+export interface GraphEdge {
+  readonly fromNodeId: string;
+  readonly fromPinId: string;
+  readonly toNodeId: string;
+  readonly toPinId: string;
+}
+
+export interface MediaProcessingGraph {
+  readonly id: string;
+  readonly nodes: readonly GraphNode[];
+  readonly edges: readonly GraphEdge[];
+}
+
+/**
+ * Immutable graph helper functions
+ */
+export class GraphHelper {
+  static create(id: string): MediaProcessingGraph {
+    return { id, nodes: [], edges: [] };
+  }
+
+  static withNode(graph: MediaProcessingGraph, node: GraphNode): MediaProcessingGraph {
+    return {
+      ...graph,
+      nodes: [...graph.nodes.filter((n) => n.id !== node.id), node],
+    };
+  }
+
+  static withEdge(graph: MediaProcessingGraph, fromNodeId: string, fromPinId: string, toNodeId: string, toPinId: string): MediaProcessingGraph {
+    const edge: GraphEdge = { fromNodeId, fromPinId, toNodeId, toPinId };
+    return {
+      ...graph,
+      edges: [...graph.edges, edge],
+    };
+  }
+
+  static getIncomingEdges(graph: MediaProcessingGraph, nodeId: string): GraphEdge[] {
+    return graph.edges.filter((e) => e.toNodeId === nodeId);
+  }
+
+  static getOutgoingEdges(graph: MediaProcessingGraph, nodeId: string): GraphEdge[] {
+    return graph.edges.filter((e) => e.fromNodeId === nodeId);
+  }
+
+  static findNode(graph: MediaProcessingGraph, nodeId: string): GraphNode | undefined {
+    return graph.nodes.find((n) => n.id === nodeId);
+  }
+
+  static getDependencies(graph: MediaProcessingGraph, nodeId: string): GraphNode[] {
+    const incoming = this.getIncomingEdges(graph, nodeId);
+    return incoming.map((edge) => this.findNode(graph, edge.fromNodeId)).filter((node): node is GraphNode => node !== undefined);
+  }
+
+  static hasCycles(graph: MediaProcessingGraph): boolean {
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    const dfs = (nodeId: string): boolean => {
+      visited.add(nodeId);
+      recursionStack.add(nodeId);
+
+      const outgoing = this.getOutgoingEdges(graph, nodeId);
+      for (const edge of outgoing) {
+        if (!visited.has(edge.toNodeId)) {
+          if (dfs(edge.toNodeId)) return true;
+        } else if (recursionStack.has(edge.toNodeId)) {
+          return true; // Cycle detected
+        }
+      }
+
+      recursionStack.delete(nodeId);
+      return false;
+    };
+
+    for (const node of graph.nodes) {
+      if (!visited.has(node.id)) {
+        if (dfs(node.id)) return true;
+      }
+    }
+
+    return false;
+  }
+
+  static topologicalSort(graph: MediaProcessingGraph): GraphNode[] {
+    const inDegree = new Map<string, number>();
+    const sorted: GraphNode[] = [];
+    const queue: GraphNode[] = [];
+
+    // Initialize in-degrees
+    for (const node of graph.nodes) {
+      inDegree.set(node.id, 0);
+    }
+
+    // Calculate in-degrees
+    for (const edge of graph.edges) {
+      inDegree.set(edge.toNodeId, (inDegree.get(edge.toNodeId) || 0) + 1);
+    }
+
+    // Find nodes with no incoming edges
+    for (const node of graph.nodes) {
+      if (inDegree.get(node.id) === 0) {
+        queue.push(node);
+      }
+    }
+
+    // Process nodes
+    while (queue.length > 0) {
+      const node = queue.shift()!;
+      sorted.push(node);
+
+      const outgoing = this.getOutgoingEdges(graph, node.id);
+      for (const edge of outgoing) {
+        const targetNode = this.findNode(graph, edge.toNodeId);
+        if (!targetNode) continue;
+
+        const newInDegree = (inDegree.get(edge.toNodeId) || 0) - 1;
+        inDegree.set(edge.toNodeId, newInDegree);
+
+        if (newInDegree === 0) {
+          queue.push(targetNode);
+        }
+      }
+    }
+
+    return sorted;
+  }
+}

package/src/graph/validator.ts

@@ -0,0 +1,208 @@
+/**
+ * @clypra/runtime — Graph Validator
+ *
+ * Validates media processing graphs for correctness.
+ * Checks for cycles, type mismatches, missing connections, etc.
+ */
+
+import type { MediaProcessingGraph, GraphNode, GraphEdge } from "./types";
+import { GraphHelper } from "./types";
+
+export interface ValidationError {
+  type: "cycle" | "type-mismatch" | "missing-connection" | "invalid-node";
+  message: string;
+  nodeId?: string;
+  edgeFrom?: string;
+  edgeTo?: string;
+}
+
+export interface GraphValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationWarning[];
+}
+
+export interface ValidationWarning {
+  type: "performance" | "compatibility" | "best-practice";
+  message: string;
+  severity: "low" | "medium" | "high";
+  nodeId?: string;
+}
+
+/**
+ * GraphValidator - Validates graph structure and semantics
+ */
+export class GraphValidator {
+  /**
+   * Validate a media processing graph
+   */
+  validate(graph: MediaProcessingGraph): GraphValidationResult {
+    const errors: ValidationError[] = [];
+    const warnings: ValidationWarning[] = [];
+
+    // Check for cycles
+    if (GraphHelper.hasCycles(graph)) {
+      errors.push({
+        type: "cycle",
+        message: "Graph contains cycles",
+      });
+    }
+
+    // Validate each node
+    for (const node of graph.nodes) {
+      const nodeErrors = this.validateNode(graph, node);
+      errors.push(...nodeErrors);
+
+      const nodeWarnings = this.generateWarnings(graph, node);
+      warnings.push(...nodeWarnings);
+    }
+
+    // Validate each edge
+    for (const edge of graph.edges) {
+      const edgeErrors = this.validateEdge(graph, edge);
+      errors.push(...edgeErrors);
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    };
+  }
+
+  /**
+   * Validate a single node
+   */
+  private validateNode(graph: MediaProcessingGraph, node: GraphNode): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    // Check if node type is valid
+    if (!node.type) {
+      errors.push({
+        type: "invalid-node",
+        message: `Node ${node.id} has no type`,
+        nodeId: node.id,
+      });
+    }
+
+    // Check if required inputs are connected
+    const inputKeys = Object.keys(node.inputs);
+    const incomingEdges = GraphHelper.getIncomingEdges(graph, node.id);
+
+    for (const inputKey of inputKeys) {
+      const hasConnection = incomingEdges.some((edge) => edge.toPinId === inputKey);
+      if (!hasConnection && node.type !== "MediaInput") {
+        errors.push({
+          type: "missing-connection",
+          message: `Node ${node.id} input '${inputKey}' is not connected`,
+          nodeId: node.id,
+        });
+      }
+    }
+
+    return errors;
+  }
+
+  /**
+   * Validate a single edge
+   */
+  private validateEdge(graph: MediaProcessingGraph, edge: GraphEdge): ValidationError[] {
+    const errors: ValidationError[] = [];
+
+    const fromNode = GraphHelper.findNode(graph, edge.fromNodeId);
+    const toNode = GraphHelper.findNode(graph, edge.toNodeId);
+
+    if (!fromNode) {
+      errors.push({
+        type: "invalid-node",
+        message: `Edge references non-existent source node: ${edge.fromNodeId}`,
+        edgeFrom: edge.fromNodeId,
+        edgeTo: edge.toNodeId,
+      });
+      return errors;
+    }
+
+    if (!toNode) {
+      errors.push({
+        type: "invalid-node",
+        message: `Edge references non-existent target node: ${edge.toNodeId}`,
+        edgeFrom: edge.fromNodeId,
+        edgeTo: edge.toNodeId,
+      });
+      return errors;
+    }
+
+    // Check if pins exist
+    const fromPin = fromNode.outputs[edge.fromPinId];
+    const toPin = toNode.inputs[edge.toPinId];
+
+    if (!fromPin) {
+      errors.push({
+        type: "missing-connection",
+        message: `Source node ${edge.fromNodeId} has no output pin '${edge.fromPinId}'`,
+        edgeFrom: edge.fromNodeId,
+        edgeTo: edge.toNodeId,
+      });
+    }
+
+    if (!toPin) {
+      errors.push({
+        type: "missing-connection",
+        message: `Target node ${edge.toNodeId} has no input pin '${edge.toPinId}'`,
+        edgeFrom: edge.fromNodeId,
+        edgeTo: edge.toNodeId,
+      });
+    }
+
+    // Check type compatibility
+    if (fromPin && toPin && fromPin.type !== toPin.type) {
+      errors.push({
+        type: "type-mismatch",
+        message: `Type mismatch: ${edge.fromNodeId}.${edge.fromPinId} (${fromPin.type}) → ${edge.toNodeId}.${edge.toPinId} (${toPin.type})`,
+        edgeFrom: edge.fromNodeId,
+        edgeTo: edge.toNodeId,
+      });
+    }
+
+    return errors;
+  }
+
+  /**
+   * Generate performance and best-practice warnings
+   */
+  private generateWarnings(graph: MediaProcessingGraph, node: GraphNode): ValidationWarning[] {
+    const warnings: ValidationWarning[] = [];
+
+    // Warn about multipass effects
+    if (node.requirements.multipass) {
+      warnings.push({
+        type: "performance",
+        message: `Node ${node.id} requires multiple render passes`,
+        severity: "medium",
+        nodeId: node.id,
+      });
+    }
+
+    // Warn about high temporal radius
+    if (node.requirements.temporalRadius > 5) {
+      warnings.push({
+        type: "performance",
+        message: `Node ${node.id} has high temporal radius (${node.requirements.temporalRadius} frames)`,
+        severity: "high",
+        nodeId: node.id,
+      });
+    }
+
+    // Warn about stateful effects
+    if (node.capabilities.stateful) {
+      warnings.push({
+        type: "compatibility",
+        message: `Node ${node.id} is stateful - may not work well with random access`,
+        severity: "low",
+        nodeId: node.id,
+      });
+    }
+
+    return warnings;
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @clypra/runtime
+ *
+ * Shared runtime infrastructure for all Clypra Studio Labs.
+ * This package contains the core execution engine used by Video Lab, Transition Lab, and Body Lab.
+ */
+
+// Graph building
+export * from "./graph";
+
+// Frame planning
+export * from "./planner";
+
+// Pixi rendering backend
+export * from "./pixi";
+
+// Resource management
+export * from "./resources";
+
+// Runtime validation
+export * from "./validation";
+
+// Testing & Publishing (Phase 6)
+export * from "./testing/goldenTests";
+export * from "./testing/benchmarkRunner";
+export { validateEffect, EffectValidator, type ValidationResult, type EffectDefinition } from "./validation/effectValidator";
+
+export const RUNTIME_VERSION = "1.0.0";

package/src/pixi/filters.ts

@@ -0,0 +1,98 @@
+/**
+ * @clypra/runtime — Pixi Filter Utilities
+ *
+ * Helper functions for creating and configuring Pixi filters.
+ */
+
+import * as PIXI from "pixi.js";
+import { AdjustmentFilter } from "pixi-filters";
+
+/**
+ * Create a filter for a given shader ID
+ */
+export function createFilter(shaderId: string, uniforms: Record<string, any> = {}): PIXI.Filter {
+  switch (shaderId) {
+    case "brightness":
+      return new AdjustmentFilter({ brightness: uniforms.brightness ?? 1.0 });
+
+    case "contrast":
+      return new AdjustmentFilter({ contrast: uniforms.contrast ?? 1.0 });
+
+    case "saturation":
+      return new AdjustmentFilter({ saturation: uniforms.saturation ?? 1.0 });
+
+    case "gaussian-blur":
+    case "gaussian-blur-h":
+    case "gaussian-blur-v":
+      return new PIXI.BlurFilter({
+        strength: uniforms.strength ?? 8,
+        quality: uniforms.quality ?? 4,
+      });
+
+    case "color-adjustments":
+      return new AdjustmentFilter({
+        brightness: uniforms.brightness ?? 1.0,
+        contrast: uniforms.contrast ?? 1.0,
+        saturation: uniforms.saturation ?? 1.0,
+        red: uniforms.red ?? 1.0,
+        green: uniforms.green ?? 1.0,
+        blue: uniforms.blue ?? 1.0,
+      });
+
+    case "copy":
+    case "blit":
+      // No-op filter
+      return new AdjustmentFilter({ brightness: 1, contrast: 1, saturation: 1 });
+
+    default:
+      // Default adjustment filter
+      return new AdjustmentFilter({});
+  }
+}
+
+/**
+ * Update filter uniforms
+ */
+export function updateFilterUniforms(filter: PIXI.Filter, uniforms: Record<string, any>, shaderId?: string): void {
+  if (filter instanceof AdjustmentFilter) {
+    if (uniforms.brightness !== undefined) {
+      filter.brightness = Number(uniforms.brightness);
+    }
+    if (uniforms.contrast !== undefined) {
+      filter.contrast = Number(uniforms.contrast);
+    }
+    if (uniforms.saturation !== undefined) {
+      filter.saturation = Number(uniforms.saturation);
+    }
+    if (uniforms.red !== undefined) {
+      filter.red = Number(uniforms.red);
+    }
+    if (uniforms.green !== undefined) {
+      filter.green = Number(uniforms.green);
+    }
+    if (uniforms.blue !== undefined) {
+      filter.blue = Number(uniforms.blue);
+    }
+  } else if (filter instanceof PIXI.BlurFilter) {
+    if (uniforms.strength !== undefined) {
+      filter.strength = Number(uniforms.strength);
+    }
+    if (uniforms.quality !== undefined) {
+      filter.quality = Number(uniforms.quality);
+    }
+  }
+}
+
+/**
+ * Normalize color adjustment uniforms
+ */
+export function normalizeColorUniforms(uniforms: Record<string, any>): Record<string, number> {
+  return {
+    brightness: uniforms.brightness !== undefined ? 1.0 + Number(uniforms.brightness) : 1.0,
+    contrast: uniforms.contrast !== undefined ? 1.0 + Number(uniforms.contrast) : 1.0,
+    saturation: uniforms.saturation !== undefined ? 1.0 + Number(uniforms.saturation) : 1.0,
+    red: uniforms.red ?? 1.0,
+    green: uniforms.green ?? 1.0,
+    blue: uniforms.blue ?? 1.0,
+  };
+}

package/src/pixi/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @clypra/runtime — Pixi.js Rendering Backend
+ *
+ * GPU-accelerated rendering using Pixi.js.
+ * Executes frame graphs and manages texture resources.
+ */
+
+export * from "./types";
+export * from "./renderer";
+export * from "./filters";
+export * from "./texture-pool";