@clypra/runtime 1.0.0

package/.releaserc.json

@@ -0,0 +1,16 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@clypra/runtime",
+  "version": "1.0.0",
+  "description": "Shared runtime infrastructure for all Clypra Studio Labs",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./graph": "./dist/graph/index.js",
+    "./planner": "./dist/planner/index.js",
+    "./pixi": "./dist/pixi/index.js",
+    "./resources": "./dist/resources/index.js",
+    "./validation": "./dist/validation/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "pixi.js": "^8.6.6",
+    "pixi-filters": "^6.0.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsup": "^8.3.5",
+    "typescript": "~5.8.2",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AIEraDev/clypra-studio.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://github.com/AIEraDev/clypra-studio/tree/main/packages/runtime#readme",
+  "bugs": {
+    "url": "https://github.com/AIEraDev/clypra-studio/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/__tests__/integration.test.ts

@@ -0,0 +1,345 @@
+/**
+ * Integration Test - Graph → Planner → Renderer Pipeline
+ *
+ * This test verifies that the complete pipeline works end-to-end.
+ */
+
+import { describe, it, expect } from "vitest";
+import { GraphBuilder } from "../graph/builder";
+import { GraphValidator } from "../graph/validator";
+import { FrameGraphPlanner } from "../planner/planner";
+import type { MediaProcessingGraph } from "../graph/types";
+
+describe("Integration: Graph → Planner Pipeline", () => {
+  it("should build and plan a simple graph", () => {
+    // 1. Build a simple graph
+    const builder = new GraphBuilder();
+
+    // Create a simple input → effect → output graph
+    const graph: MediaProcessingGraph = {
+      id: "test-graph",
+      nodes: [
+        {
+          id: "input",
+          type: "source",
+          version: 1,
+          params: {},
+          inputs: {},
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: false,
+            geometry: false,
+            inputsCount: 0,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+        {
+          id: "effect",
+          type: "brightness",
+          version: 1,
+          params: { amount: 1.2 },
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: true,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+        {
+          id: "output",
+          type: "sink",
+          version: 1,
+          params: {},
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {},
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: false,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: false,
+          },
+          lifecycle: "Created",
+        },
+      ],
+      edges: [
+        {
+          fromNodeId: "input",
+          fromPinId: "out",
+          toNodeId: "effect",
+          toPinId: "in",
+        },
+        {
+          fromNodeId: "effect",
+          fromPinId: "out",
+          toNodeId: "output",
+          toPinId: "in",
+        },
+      ],
+    };
+
+    // 2. Validate the graph
+    const validator = new GraphValidator();
+    const validationResult = validator.validate(graph);
+
+    expect(validationResult.valid).toBe(true);
+    expect(validationResult.errors).toHaveLength(0);
+
+    // 3. Plan a frame
+    const planner = new FrameGraphPlanner({
+      targetWidth: 1920,
+      targetHeight: 1080,
+    });
+
+    const frameGraph = planner.plan(graph, 0, 0);
+
+    // Verify frame graph structure
+    expect(frameGraph).toBeDefined();
+    expect(frameGraph.passes).toBeDefined();
+    expect(frameGraph.passes.length).toBeGreaterThan(0);
+    expect(frameGraph.resourceRequests).toBeDefined();
+    expect(frameGraph.resourceRequests.length).toBeGreaterThan(0);
+
+    // Verify source and output resources
+    const resourceIds = frameGraph.resourceRequests.map((r) => r.id);
+
+    // Should have source resources
+    const hasSource = frameGraph.resourceRequests.some((r) => r.id.includes("source") || r.id.includes("input"));
+    expect(hasSource).toBe(true);
+
+    // Should have at least one resource
+    expect(frameGraph.resourceRequests.length).toBeGreaterThan(0);
+
+    // Verify passes have required properties
+    for (const pass of frameGraph.passes) {
+      expect(pass.id).toBeDefined();
+      expect(pass.shaderId).toBeDefined();
+      expect(pass.output).toBeDefined();
+      expect(pass.uniforms).toBeDefined();
+    }
+  });
+
+  it("should handle multi-pass effects", () => {
+    const graph: MediaProcessingGraph = {
+      id: "multipass-graph",
+      nodes: [
+        {
+          id: "input",
+          type: "source",
+          version: 1,
+          params: {},
+          inputs: {},
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: false,
+            geometry: false,
+            inputsCount: 0,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: true, // Multi-pass effect
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+        {
+          id: "blur",
+          type: "blur",
+          version: 1,
+          params: { radius: 10 },
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: true,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: true,
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+        {
+          id: "output",
+          type: "sink",
+          version: 1,
+          params: {},
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {},
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: false,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: false,
+          },
+          lifecycle: "Created",
+        },
+      ],
+      edges: [
+        {
+          fromNodeId: "input",
+          fromPinId: "out",
+          toNodeId: "blur",
+          toPinId: "in",
+        },
+        {
+          fromNodeId: "blur",
+          fromPinId: "out",
+          toNodeId: "output",
+          toPinId: "in",
+        },
+      ],
+    };
+
+    const planner = new FrameGraphPlanner({
+      targetWidth: 1920,
+      targetHeight: 1080,
+    });
+
+    const frameGraph = planner.plan(graph, 0, 0);
+
+    // Multi-pass effects should generate multiple passes
+    expect(frameGraph.passes.length).toBeGreaterThanOrEqual(2);
+
+    // Should have transient resources for intermediate results
+    const transientResources = frameGraph.resourceRequests.filter((r) => r.transient);
+    expect(transientResources.length).toBeGreaterThan(0);
+  });
+
+  it("should detect graph validation errors", () => {
+    // Create invalid graph (cycle)
+    const invalidGraph: MediaProcessingGraph = {
+      id: "invalid-graph",
+      nodes: [
+        {
+          id: "node1",
+          type: "effect",
+          version: 1,
+          params: {},
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: true,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+        {
+          id: "node2",
+          type: "effect",
+          version: 1,
+          params: {},
+          inputs: {
+            in: { id: "in", name: "input", type: "Texture" },
+          },
+          outputs: {
+            out: { id: "out", name: "output", type: "Texture" },
+          },
+          capabilities: {
+            temporal: false,
+            stateful: false,
+            spatial: true,
+            geometry: false,
+            inputsCount: 1,
+          },
+          requirements: {
+            temporalRadius: 0,
+            preferredPrecision: "fp16",
+            multipass: false,
+            supportsHalfResolution: true,
+          },
+          lifecycle: "Created",
+        },
+      ],
+      edges: [
+        {
+          fromNodeId: "node1",
+          fromPinId: "out",
+          toNodeId: "node2",
+          toPinId: "in",
+        },
+        {
+          fromNodeId: "node2",
+          fromPinId: "out",
+          toNodeId: "node1",
+          toPinId: "in",
+        },
+      ],
+    };
+
+    const validator = new GraphValidator();
+    const validationResult = validator.validate(invalidGraph);
+
+    expect(validationResult.valid).toBe(false);
+    expect(validationResult.errors.length).toBeGreaterThan(0);
+    expect(validationResult.errors.some((e) => e.type === "cycle")).toBe(true);
+  });
+});

package/src/graph/__tests__/builder.test.ts

@@ -0,0 +1,204 @@
+/**
+ * Unit Tests - Graph Builder
+ */
+
+import { describe, it, expect } from "vitest";
+import { GraphBuilder } from "../builder";
+import type { EffectDefinition, MediaInput } from "../builder";
+
+describe("GraphBuilder", () => {
+  describe("constructor", () => {
+    it("should create a new GraphBuilder instance", () => {
+      const builder = new GraphBuilder();
+      expect(builder).toBeDefined();
+      expect(builder).toBeInstanceOf(GraphBuilder);
+    });
+
+    it("should accept custom graph ID", () => {
+      const builder = new GraphBuilder("custom-graph-id");
+      const graph = builder.getGraph();
+      expect(graph.id).toBe("custom-graph-id");
+    });
+
+    it("should generate graph ID if not provided", () => {
+      const builder = new GraphBuilder();
+      const graph = builder.getGraph();
+      expect(graph.id).toMatch(/^graph-\d+$/);
+    });
+  });
+
+  describe("build", () => {
+    it("should build a simple graph with one effect", () => {
+      const builder = new GraphBuilder("test-graph");
+
+      const effect: EffectDefinition = {
+        id: "brightness-1",
+        type: "brightness",
+        parameters: { amount: 1.2 },
+      };
+
+      const inputs: MediaInput[] = [
+        {
+          id: "input-1",
+          type: "video",
+          source: "video.mp4",
+        },
+      ];
+
+      const graph = builder.build(effect, inputs);
+
+      expect(graph.nodes).toHaveLength(3); // input, effect, output
+      expect(graph.edges).toHaveLength(2); // input->effect, effect->output
+      expect(graph.nodes.some((n) => n.type === "brightness")).toBe(true);
+    });
+
+    it("should create input nodes for all inputs", () => {
+      const builder = new GraphBuilder();
+
+      const effect: EffectDefinition = {
+        id: "blend",
+        type: "blend",
+        inputs: [
+          { id: "input1", name: "Input 1", type: "Texture" },
+          { id: "input2", name: "Input 2", type: "Texture" },
+        ],
+      };
+
+      const inputs: MediaInput[] = [
+        { id: "input-1", type: "video", source: "video1.mp4" },
+        { id: "input-2", type: "video", source: "video2.mp4" },
+      ];
+
+      const graph = builder.build(effect, inputs);
+
+      const inputNodes = graph.nodes.filter((n) => n.type === "MediaInput");
+      expect(inputNodes).toHaveLength(2);
+    });
+
+    it("should set effect parameters correctly", () => {
+      const builder = new GraphBuilder();
+
+      const effect: EffectDefinition = {
+        id: "blur",
+        type: "blur",
+        parameters: { radius: 10, quality: "high" },
+      };
+
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.build(effect, inputs);
+
+      const effectNode = graph.nodes.find((n) => n.type === "blur");
+      expect(effectNode).toBeDefined();
+      expect(effectNode?.params).toEqual({ radius: 10, quality: "high" });
+    });
+
+    it("should set effect capabilities", () => {
+      const builder = new GraphBuilder();
+
+      const effect: EffectDefinition = {
+        id: "temporal-effect",
+        type: "motion-blur",
+        capabilities: {
+          temporal: true,
+          stateful: true,
+        },
+      };
+
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.build(effect, inputs);
+
+      const effectNode = graph.nodes.find((n) => n.type === "motion-blur");
+      expect(effectNode?.capabilities.temporal).toBe(true);
+      expect(effectNode?.capabilities.stateful).toBe(true);
+    });
+
+    it("should create output node", () => {
+      const builder = new GraphBuilder();
+
+      const effect: EffectDefinition = {
+        id: "effect-1",
+        type: "brightness",
+      };
+
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.build(effect, inputs);
+
+      const outputNode = graph.nodes.find((n) => n.type === "Output");
+      expect(outputNode).toBeDefined();
+      expect(outputNode?.id).toBe("output");
+    });
+  });
+
+  describe("buildComposite", () => {
+    it("should chain multiple effects", () => {
+      const builder = new GraphBuilder();
+
+      const effects: EffectDefinition[] = [
+        { id: "blur", type: "blur", parameters: { radius: 5 } },
+        { id: "brightness", type: "brightness", parameters: { amount: 1.2 } },
+        { id: "contrast", type: "contrast", parameters: { amount: 1.1 } },
+      ];
+
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.buildComposite(effects, inputs);
+
+      // Should have: 1 input + 3 effects + 1 output = 5 nodes
+      expect(graph.nodes).toHaveLength(5);
+
+      // Should have: input->blur, blur->brightness, brightness->contrast, contrast->output = 4 edges
+      expect(graph.edges).toHaveLength(4);
+    });
+
+    it("should preserve effect order", () => {
+      const builder = new GraphBuilder();
+
+      const effects: EffectDefinition[] = [
+        { id: "effect-1", type: "blur" },
+        { id: "effect-2", type: "brightness" },
+      ];
+
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.buildComposite(effects, inputs);
+
+      // Find the edges to verify order
+      const blurNode = graph.nodes.find((n) => n.id === "effect-1");
+      const brightnessNode = graph.nodes.find((n) => n.id === "effect-2");
+
+      expect(blurNode).toBeDefined();
+      expect(brightnessNode).toBeDefined();
+
+      // Verify blur comes before brightness
+      const blurToBrightness = graph.edges.find((e) => e.fromNodeId === "effect-1" && e.toNodeId === "effect-2");
+      expect(blurToBrightness).toBeDefined();
+    });
+
+    it("should handle empty effects array", () => {
+      const builder = new GraphBuilder();
+
+      const effects: EffectDefinition[] = [];
+      const inputs: MediaInput[] = [{ id: "input-1", type: "video", source: "video.mp4" }];
+
+      const graph = builder.buildComposite(effects, inputs);
+
+      // Should still have input and output
+      expect(graph.nodes.length).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  describe("getGraph", () => {
+    it("should return current graph", () => {
+      const builder = new GraphBuilder("test-graph");
+      const graph = builder.getGraph();
+
+      expect(graph).toBeDefined();
+      expect(graph.id).toBe("test-graph");
+      expect(graph.nodes).toBeDefined();
+      expect(graph.edges).toBeDefined();
+    });
+  });
+});