@ic-reactor/codegen 0.6.0 → 0.7.0

package/README.md

@@ -17,81 +17,35 @@ import { runCanisterPipeline } from "@ic-reactor/codegen"
 await runCanisterPipeline({
   canisterConfig: {
     name: "backend",
+    mode: "DisplayReactor",
     didFile: "./backend.did",
   },
   projectRoot: process.cwd(),
   globalConfig: {
     outDir: "src/declarations",
     clientManagerPath: "../../clients",
-    reactor: {
-      defaultMode: "display",
-      canisters: {
-        workflow_engine: "raw",
-      },
-    },
   },
 })
 ```
 
-## Reactor Mode Configuration
+## Reactor Class Configuration
 
-`reactor.defaultMode` controls whether generated default hook exports use:
+Set `canisterConfig.mode` to choose the generated reactor class:
 
-- `display` → `DisplayReactor` (current/default behavior)
-- `raw` → `Reactor` (raw Candid shapes)
+- `DisplayReactor` (default)
+- `Reactor`
+- `CandidReactor`
+- `CandidDisplayReactor`
+- `MetadataDisplayReactor`
 
-`reactor.canisters` lets you override specific canisters without editing generated files.
-
-## Generated File Layout (Stable Wrapper)
-
-Each canister now generates:
-
-- `index.generated.ts` (regenerated on every run)
-- `index.ts` (created only if missing; not overwritten)
-
-The stable wrapper defaults to:
-
-```ts
-export * from "./index.generated"
-```
-
-This lets applications customize exports once and keep them across regenerations.
-
-## Generated Output Examples
-
-Display default:
-
-```ts
-export function createBackendRawReactor() {
-  /* ... */
-}
-export function createBackendDisplayReactor() {
-  /* ... */
-}
-export const backendReactor = createBackendDisplayReactor()
-export const BackendReactorMode = "display" as const
-```
-
-Raw default:
-
-```ts
-export function createWorkflowEngineRawReactor() {
-  /* ... */
-}
-export function createWorkflowEngineDisplayReactor() {
-  /* ... */
-}
-export const workflowEngineReactor = createWorkflowEngineRawReactor()
-export const WorkflowEngineReactorMode = "raw" as const
-```
+Codegen writes a single `index.ts`. It overwrites that file only while it is still recognized as a generated file; if you replace it with your own file, regeneration leaves it untouched.
 
 ## Generators
 
 You can also use individual generators if you need more granular control:
 
 - **`generateDeclarations`**: Generates `.js` (factory), `.d.ts` (types), and `.did` copy.
-- **`generateReactorFile`**: Generates the `index.generated.ts` implementation with raw/display factories and typed hooks.
-- **`generateReactorWrapperFile`**: Generates the stable `index.ts` wrapper (create-once, preserve-on-regenerate).
+- **`generateReactorFile`**: Generates the `index.ts` file using either `DisplayReactor` or `Reactor`.
 - **`generateClientFile`**: Generates a `ClientManager` boilerplate file.
 
 ## Utilities

package/dist/index.cjs

@@ -35,7 +35,6 @@ __export(index_exports, {
   generateClientFile: () => generateClientFile,
   generateDeclarations: () => generateDeclarations,
   generateReactorFile: () => generateReactorFile,
-  generateReactorWrapperFile: () => generateReactorWrapperFile,
   getReactorName: () => getReactorName,
   getServiceTypeName: () => getServiceTypeName,
   parseDIDFile: () => parseDIDFile,
@@ -124,22 +123,32 @@ function getServiceTypeName(canisterName) {
 }
 
 // src/generators/reactor.ts
+function getReactorClassImportSource(reactorClass) {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react";
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid";
+  }
+}
 function generateReactorFile(options) {
   const {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
-    reactorMode = "display"
+    reactorClass = "DisplayReactor"
   } = options;
   const pascalName = toPascalCase(canisterName);
   const reactorName = getReactorName(canisterName);
   const serviceName = getServiceTypeName(canisterName);
-  const rawFactoryName = `create${pascalName}RawReactor`;
-  const displayFactoryName = `create${pascalName}DisplayReactor`;
-  const defaultFactoryName = reactorMode === "raw" ? rawFactoryName : displayFactoryName;
   const baseName = import_node_path2.default.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
-  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+  const reactorImportSource = getReactorClassImportSource(reactorClass);
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -151,25 +160,11 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export function ${rawFactoryName}() {
-  return new Reactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export function ${displayFactoryName}() {
-  return new DisplayReactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export const ${reactorName} = ${defaultFactoryName}()
-
-export const ${pascalName}ReactorMode = "${reactorMode}" as const
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})
 
 export const {
   useActorQuery: use${pascalName}Query,
@@ -181,28 +176,13 @@ export const {
 } = createActorHooks(${reactorName})
 `;
 }
-function generateReactorWrapperFile(options) {
-  const { canisterName } = options;
-  const pascalName = toPascalCase(canisterName);
-  return `/**
- * ${pascalName} canister exports
- *
- * This wrapper is created once by @ic-reactor/codegen and is not overwritten.
- * Customize it if you need to swap reactor implementations or compose custom exports.
- */
-export * from "./index.generated"
-`;
-}
 
 // src/pipeline.ts
-function resolveReactorMode(canisterName, globalConfig) {
-  return globalConfig.reactor?.canisters?.[canisterName] ?? globalConfig.reactor?.defaultMode ?? "display";
-}
-function isStableWrapperFile(content) {
-  return content.includes('export * from "./index.generated"');
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
 }
-function isLegacyGeneratedIndexFile(content) {
-  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(") && !isStableWrapperFile(content);
+function isGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
 }
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
@@ -242,41 +222,32 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const generatedReactorPath = import_node_path3.default.join(canisterOutDir, "index.generated.ts");
-  const wrapperPath = import_node_path3.default.join(canisterOutDir, "index.ts");
-  const reactorMode = resolveReactorMode(name, globalConfig);
+  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
-      reactorMode
-    });
-    const wrapperContent = generateReactorWrapperFile({
-      canisterName: name,
-      didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath,
-      reactorMode
+      reactorClass
     });
     import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
-    import_node_fs2.default.writeFileSync(generatedReactorPath, reactorContent);
-    files.push({ success: true, filePath: generatedReactorPath });
-    if (!import_node_fs2.default.existsSync(wrapperPath)) {
-      import_node_fs2.default.writeFileSync(wrapperPath, wrapperContent);
-      files.push({ success: true, filePath: wrapperPath });
+    if (!import_node_fs2.default.existsSync(reactorPath)) {
+      import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+      files.push({ success: true, filePath: reactorPath });
     } else {
-      const existingWrapperContent = import_node_fs2.default.readFileSync(wrapperPath, "utf-8");
-      if (isLegacyGeneratedIndexFile(existingWrapperContent)) {
-        import_node_fs2.default.writeFileSync(wrapperPath, wrapperContent);
-        files.push({ success: true, filePath: wrapperPath });
+      const existingIndexContent = import_node_fs2.default.readFileSync(reactorPath, "utf-8");
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
+        files.push({ success: true, filePath: reactorPath });
       } else {
-        files.push({ success: true, filePath: wrapperPath, skipped: true });
+        files.push({ success: true, filePath: reactorPath, skipped: true });
       }
     }
   } catch (err) {
     files.push({
       success: false,
-      filePath: generatedReactorPath,
+      filePath: reactorPath,
       error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`
     });
     return {
@@ -355,7 +326,6 @@ export const clientManager = new ClientManager({
   generateClientFile,
   generateDeclarations,
   generateReactorFile,
-  generateReactorWrapperFile,
   getReactorName,
   getServiceTypeName,
   parseDIDFile,

package/dist/index.d.cts

@@ -19,22 +19,15 @@ interface CanisterConfig {
      * Example: "../../clients" → `import { clientManager } from "../../clients"`
      */
     clientManagerPath?: string;
-    /** Optional fixed canister ID */
-    canisterId?: string;
-}
-type ReactorMode = "raw" | "display";
-interface ReactorGenerationConfig {
-    /**
-     * Default reactor mode used for generated hook exports.
-     * `display` preserves current behavior.
-     */
-    defaultMode?: ReactorMode;
     /**
-     * Optional per-canister overrides keyed by canister name.
-     * Example: { workflow_engine: "raw" }
+     * Reactor class used for generated hooks in this canister.
+     * Defaults to DisplayReactor for backward compatibility.
      */
-    canisters?: Record<string, ReactorMode>;
+    mode?: ReactorClassName;
+    /** Optional fixed canister ID */
+    canisterId?: string;
 }
+type ReactorClassName = "Reactor" | "DisplayReactor" | "CandidReactor" | "CandidDisplayReactor" | "MetadataDisplayReactor";
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -51,8 +44,6 @@ interface CodegenConfig {
      * Individual canisters can override via `CanisterConfig.clientManagerPath`.
      */
     clientManagerPath?: string;
-    /** Optional reactor mode generation settings */
-    reactor?: ReactorGenerationConfig;
     /** Canister configurations, keyed by canister name */
     canisters: Record<string, CanisterConfig>;
 }
@@ -77,7 +68,7 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor implementation + stable wrapper (`index.generated.ts` + `index.ts`)
+ *  3. Generate reactor file (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -91,7 +82,7 @@ interface PipelineOptions {
     /**
      * Global codegen config (for fallback outDir and clientManagerPath).
      */
-    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath" | "reactor">;
+    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">;
 }
 interface PipelineResult {
     canisterName: string;
@@ -234,20 +225,15 @@ interface ReactorGeneratorOptions {
      */
     clientManagerPath?: string;
     /**
-     * Which reactor implementation should back the default exported hooks.
-     * Default: "display" (backward compatible)
+     * Which reactor class should back the generated hooks.
+     * Default: "DisplayReactor" (backward compatible)
      */
-    reactorMode?: ReactorMode;
+    reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.generated.ts` implementation file.
+ * Generate the content of a canister's `index.ts` file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
-/**
- * Generate the stable user wrapper `index.ts` for a canister.
- * This file is intended to be created once and preserved across regenerations.
- */
-declare function generateReactorWrapperFile(options: ReactorGeneratorOptions): string;
 
 /**
  * Client Manager Generator
@@ -272,4 +258,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorGenerationConfig, type ReactorGeneratorOptions, type ReactorMode, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, generateReactorWrapperFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.d.ts

@@ -19,22 +19,15 @@ interface CanisterConfig {
      * Example: "../../clients" → `import { clientManager } from "../../clients"`
      */
     clientManagerPath?: string;
-    /** Optional fixed canister ID */
-    canisterId?: string;
-}
-type ReactorMode = "raw" | "display";
-interface ReactorGenerationConfig {
-    /**
-     * Default reactor mode used for generated hook exports.
-     * `display` preserves current behavior.
-     */
-    defaultMode?: ReactorMode;
     /**
-     * Optional per-canister overrides keyed by canister name.
-     * Example: { workflow_engine: "raw" }
+     * Reactor class used for generated hooks in this canister.
+     * Defaults to DisplayReactor for backward compatibility.
      */
-    canisters?: Record<string, ReactorMode>;
+    mode?: ReactorClassName;
+    /** Optional fixed canister ID */
+    canisterId?: string;
 }
+type ReactorClassName = "Reactor" | "DisplayReactor" | "CandidReactor" | "CandidDisplayReactor" | "MetadataDisplayReactor";
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -51,8 +44,6 @@ interface CodegenConfig {
      * Individual canisters can override via `CanisterConfig.clientManagerPath`.
      */
     clientManagerPath?: string;
-    /** Optional reactor mode generation settings */
-    reactor?: ReactorGenerationConfig;
     /** Canister configurations, keyed by canister name */
     canisters: Record<string, CanisterConfig>;
 }
@@ -77,7 +68,7 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor implementation + stable wrapper (`index.generated.ts` + `index.ts`)
+ *  3. Generate reactor file (`index.ts`)
  */
 
 interface PipelineOptions {
@@ -91,7 +82,7 @@ interface PipelineOptions {
     /**
      * Global codegen config (for fallback outDir and clientManagerPath).
      */
-    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath" | "reactor">;
+    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">;
 }
 interface PipelineResult {
     canisterName: string;
@@ -234,20 +225,15 @@ interface ReactorGeneratorOptions {
      */
     clientManagerPath?: string;
     /**
-     * Which reactor implementation should back the default exported hooks.
-     * Default: "display" (backward compatible)
+     * Which reactor class should back the generated hooks.
+     * Default: "DisplayReactor" (backward compatible)
      */
-    reactorMode?: ReactorMode;
+    reactorClass?: ReactorClassName;
 }
 /**
- * Generate the content of a canister's `index.generated.ts` implementation file.
+ * Generate the content of a canister's `index.ts` file.
  */
 declare function generateReactorFile(options: ReactorGeneratorOptions): string;
-/**
- * Generate the stable user wrapper `index.ts` for a canister.
- * This file is intended to be created once and preserved across regenerations.
- */
-declare function generateReactorWrapperFile(options: ReactorGeneratorOptions): string;
 
 /**
  * Client Manager Generator
@@ -272,4 +258,4 @@ interface ClientGeneratorOptions {
  */
 declare function generateClientFile(options?: ClientGeneratorOptions): string;
 
-export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorGenerationConfig, type ReactorGeneratorOptions, type ReactorMode, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, generateReactorWrapperFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };
+export { type CanisterConfig, type ClientGeneratorOptions, type CodegenConfig, type DeclarationsGeneratorOptions, type DeclarationsGeneratorResult, type GeneratorResult, type MethodInfo, type MethodType, type PipelineOptions, type PipelineResult, type ReactorClassName, type ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.js

@@ -78,22 +78,32 @@ function getServiceTypeName(canisterName) {
 }
 
 // src/generators/reactor.ts
+function getReactorClassImportSource(reactorClass) {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react";
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid";
+  }
+}
 function generateReactorFile(options) {
   const {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
-    reactorMode = "display"
+    reactorClass = "DisplayReactor"
   } = options;
   const pascalName = toPascalCase(canisterName);
   const reactorName = getReactorName(canisterName);
   const serviceName = getServiceTypeName(canisterName);
-  const rawFactoryName = `create${pascalName}RawReactor`;
-  const displayFactoryName = `create${pascalName}DisplayReactor`;
-  const defaultFactoryName = reactorMode === "raw" ? rawFactoryName : displayFactoryName;
   const baseName = path2.basename(didFile, ".did");
   const declarationsPath = `./declarations/${baseName}`;
-  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+  const reactorImportSource = getReactorClassImportSource(reactorClass);
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -105,25 +115,11 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen \u2014 do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export function ${rawFactoryName}() {
-  return new Reactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export function ${displayFactoryName}() {
-  return new DisplayReactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export const ${reactorName} = ${defaultFactoryName}()
-
-export const ${pascalName}ReactorMode = "${reactorMode}" as const
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})
 
 export const {
   useActorQuery: use${pascalName}Query,
@@ -135,28 +131,13 @@ export const {
 } = createActorHooks(${reactorName})
 `;
 }
-function generateReactorWrapperFile(options) {
-  const { canisterName } = options;
-  const pascalName = toPascalCase(canisterName);
-  return `/**
- * ${pascalName} canister exports
- *
- * This wrapper is created once by @ic-reactor/codegen and is not overwritten.
- * Customize it if you need to swap reactor implementations or compose custom exports.
- */
-export * from "./index.generated"
-`;
-}
 
 // src/pipeline.ts
-function resolveReactorMode(canisterName, globalConfig) {
-  return globalConfig.reactor?.canisters?.[canisterName] ?? globalConfig.reactor?.defaultMode ?? "display";
-}
-function isStableWrapperFile(content) {
-  return content.includes('export * from "./index.generated"');
+function resolveReactorClass(canisterConfig) {
+  return canisterConfig.mode ?? "DisplayReactor";
 }
-function isLegacyGeneratedIndexFile(content) {
-  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(") && !isStableWrapperFile(content);
+function isGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(");
 }
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
@@ -196,41 +177,32 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const generatedReactorPath = path3.join(canisterOutDir, "index.generated.ts");
-  const wrapperPath = path3.join(canisterOutDir, "index.ts");
-  const reactorMode = resolveReactorMode(name, globalConfig);
+  const reactorPath = path3.join(canisterOutDir, "index.ts");
+  const reactorClass = resolveReactorClass(canisterConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
-      reactorMode
-    });
-    const wrapperContent = generateReactorWrapperFile({
-      canisterName: name,
-      didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath,
-      reactorMode
+      reactorClass
     });
     fs2.mkdirSync(canisterOutDir, { recursive: true });
-    fs2.writeFileSync(generatedReactorPath, reactorContent);
-    files.push({ success: true, filePath: generatedReactorPath });
-    if (!fs2.existsSync(wrapperPath)) {
-      fs2.writeFileSync(wrapperPath, wrapperContent);
-      files.push({ success: true, filePath: wrapperPath });
+    if (!fs2.existsSync(reactorPath)) {
+      fs2.writeFileSync(reactorPath, reactorContent);
+      files.push({ success: true, filePath: reactorPath });
     } else {
-      const existingWrapperContent = fs2.readFileSync(wrapperPath, "utf-8");
-      if (isLegacyGeneratedIndexFile(existingWrapperContent)) {
-        fs2.writeFileSync(wrapperPath, wrapperContent);
-        files.push({ success: true, filePath: wrapperPath });
+      const existingIndexContent = fs2.readFileSync(reactorPath, "utf-8");
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        fs2.writeFileSync(reactorPath, reactorContent);
+        files.push({ success: true, filePath: reactorPath });
       } else {
-        files.push({ success: true, filePath: wrapperPath, skipped: true });
+        files.push({ success: true, filePath: reactorPath, skipped: true });
       }
     }
   } catch (err) {
     files.push({
       success: false,
-      filePath: generatedReactorPath,
+      filePath: reactorPath,
       error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`
     });
     return {
@@ -308,7 +280,6 @@ export {
   generateClientFile,
   generateDeclarations,
   generateReactorFile,
-  generateReactorWrapperFile,
   getReactorName,
   getServiceTypeName,
   parseDIDFile,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ic-reactor/codegen",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared code generation utilities for IC Reactor",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/__snapshots__/reactor.test.ts.snap

@@ -1,18 +1,8 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Reactor generator > generates a stable wrapper file > stable-wrapper-index 1`] = `
-"/**
- * Backend canister exports
- *
- * This wrapper is created once by @ic-reactor/codegen and is not overwritten.
- * Customize it if you need to swap reactor implementations or compose custom exports.
- */
-export * from "./index.generated"
-"
-`;
-
-exports[`Reactor generator > keeps default behavior as display mode > display-mode-index-generated 1`] = `
-"import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+exports[`Reactor generator > keeps default behavior as DisplayReactor > display-reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { DisplayReactor } from "@ic-reactor/react"
 import { clientManager } from "../../clients"
 import { idlFactory, type _SERVICE } from "./declarations/backend"
 
@@ -24,25 +14,11 @@ export type BackendService = _SERVICE
  * Auto-generated by @ic-reactor/codegen — do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export function createBackendRawReactor() {
-  return new Reactor<BackendService>({
-    clientManager,
-    idlFactory,
-    name: "backend",
-  })
-}
-
-export function createBackendDisplayReactor() {
-  return new DisplayReactor<BackendService>({
-    clientManager,
-    idlFactory,
-    name: "backend",
-  })
-}
-
-export const backendReactor = createBackendDisplayReactor()
-
-export const BackendReactorMode = "display" as const
+export const backendReactor = new DisplayReactor<BackendService>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+})
 
 export const {
   useActorQuery: useBackendQuery,
@@ -55,8 +31,9 @@ export const {
 "
 `;
 
-exports[`Reactor generator > supports raw mode generation > raw-mode-index-generated 1`] = `
-"import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+exports[`Reactor generator > supports Reactor mode generation > reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { Reactor } from "@ic-reactor/react"
 import { clientManager } from "../../clients"
 import { idlFactory, type _SERVICE } from "./declarations/workflow_engine"
 
@@ -68,25 +45,11 @@ export type WorkflowEngineService = _SERVICE
  * Auto-generated by @ic-reactor/codegen — do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export function createWorkflowEngineRawReactor() {
-  return new Reactor<WorkflowEngineService>({
-    clientManager,
-    idlFactory,
-    name: "workflow_engine",
-  })
-}
-
-export function createWorkflowEngineDisplayReactor() {
-  return new DisplayReactor<WorkflowEngineService>({
-    clientManager,
-    idlFactory,
-    name: "workflow_engine",
-  })
-}
-
-export const workflowEngineReactor = createWorkflowEngineRawReactor()
-
-export const WorkflowEngineReactorMode = "raw" as const
+export const workflowEngineReactor = new Reactor<WorkflowEngineService>({
+  clientManager,
+  idlFactory,
+  name: "workflow_engine",
+})
 
 export const {
   useActorQuery: useWorkflowEngineQuery,
@@ -98,3 +61,34 @@ export const {
 } = createActorHooks(workflowEngineReactor)
 "
 `;
+
+exports[`Reactor generator > supports candid reactor subclasses > metadata-display-reactor-index 1`] = `
+"import { createActorHooks } from "@ic-reactor/react"
+import { MetadataDisplayReactor } from "@ic-reactor/candid"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/ledger"
+
+export type LedgerService = _SERVICE
+
+/**
+ * Ledger Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+export const ledgerReactor = new MetadataDisplayReactor<LedgerService>({
+  clientManager,
+  idlFactory,
+  name: "ledger",
+})
+
+export const {
+  useActorQuery: useLedgerQuery,
+  useActorSuspenseQuery: useLedgerSuspenseQuery,
+  useActorInfiniteQuery: useLedgerInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useLedgerSuspenseInfiniteQuery,
+  useActorMutation: useLedgerMutation,
+  useActorMethod: useLedgerMethod,
+} = createActorHooks(ledgerReactor)
+"
+`;

package/src/generators/index.ts

@@ -11,7 +11,7 @@ export type {
   DeclarationsGeneratorResult,
 } from "./declarations.js"
 
-export { generateReactorFile, generateReactorWrapperFile } from "./reactor.js"
+export { generateReactorFile } from "./reactor.js"
 export type { ReactorGeneratorOptions } from "./reactor.js"
 
 export { generateClientFile } from "./client.js"

package/src/generators/reactor.ts

@@ -22,7 +22,7 @@
 
 import path from "node:path"
 import { toPascalCase, getReactorName, getServiceTypeName } from "../naming.js"
-import type { ReactorMode } from "../types.js"
+import type { ReactorClassName } from "../types.js"
 
 export interface ReactorGeneratorOptions {
   /** Canister name (e.g. "backend") */
@@ -38,36 +38,48 @@ export interface ReactorGeneratorOptions {
    */
   clientManagerPath?: string
   /**
-   * Which reactor implementation should back the default exported hooks.
-   * Default: "display" (backward compatible)
+   * Which reactor class should back the generated hooks.
+   * Default: "DisplayReactor" (backward compatible)
    */
-  reactorMode?: ReactorMode
+  reactorClass?: ReactorClassName
+}
+
+function getReactorClassImportSource(
+  reactorClass: ReactorClassName
+): "@ic-reactor/react" | "@ic-reactor/candid" {
+  switch (reactorClass) {
+    case "Reactor":
+    case "DisplayReactor":
+      return "@ic-reactor/react"
+    case "CandidReactor":
+    case "CandidDisplayReactor":
+    case "MetadataDisplayReactor":
+      return "@ic-reactor/candid"
+  }
 }
 
 /**
- * Generate the content of a canister's `index.generated.ts` implementation file.
+ * Generate the content of a canister's `index.ts` file.
  */
 export function generateReactorFile(options: ReactorGeneratorOptions): string {
   const {
     canisterName,
     didFile,
     clientManagerPath = "../../clients",
-    reactorMode = "display",
+    reactorClass = "DisplayReactor",
   } = options
 
   const pascalName = toPascalCase(canisterName)
   const reactorName = getReactorName(canisterName)
   const serviceName = getServiceTypeName(canisterName)
-  const rawFactoryName = `create${pascalName}RawReactor`
-  const displayFactoryName = `create${pascalName}DisplayReactor`
-  const defaultFactoryName =
-    reactorMode === "raw" ? rawFactoryName : displayFactoryName
 
   // Derive the declarations import path from the .did filename
   const baseName = path.basename(didFile, ".did")
   const declarationsPath = `./declarations/${baseName}`
+  const reactorImportSource = getReactorClassImportSource(reactorClass)
 
-  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+  return `import { createActorHooks } from "@ic-reactor/react"
+import { ${reactorClass} } from "${reactorImportSource}"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -79,25 +91,11 @@ export type ${serviceName} = _SERVICE
  * Auto-generated by @ic-reactor/codegen — do not edit.
  * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
  */
-export function ${rawFactoryName}() {
-  return new Reactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export function ${displayFactoryName}() {
-  return new DisplayReactor<${serviceName}>({
-    clientManager,
-    idlFactory,
-    name: "${canisterName}",
-  })
-}
-
-export const ${reactorName} = ${defaultFactoryName}()
-
-export const ${pascalName}ReactorMode = "${reactorMode}" as const
+export const ${reactorName} = new ${reactorClass}<${serviceName}>({
+  clientManager,
+  idlFactory,
+  name: "${canisterName}",
+})
 
 export const {
   useActorQuery: use${pascalName}Query,
@@ -109,23 +107,3 @@ export const {
 } = createActorHooks(${reactorName})
 `
 }
-
-/**
- * Generate the stable user wrapper `index.ts` for a canister.
- * This file is intended to be created once and preserved across regenerations.
- */
-export function generateReactorWrapperFile(
-  options: ReactorGeneratorOptions
-): string {
-  const { canisterName } = options
-  const pascalName = toPascalCase(canisterName)
-
-  return `/**
- * ${pascalName} canister exports
- *
- * This wrapper is created once by @ic-reactor/codegen and is not overwritten.
- * Customize it if you need to swap reactor implementations or compose custom exports.
- */
-export * from "./index.generated"
-`
-}

package/src/index.ts

@@ -10,8 +10,7 @@ export type {
   CanisterConfig,
   CodegenConfig,
   GeneratorResult,
-  ReactorMode,
-  ReactorGenerationConfig,
+  ReactorClassName,
 } from "./types.js"
 
 // Pipeline (Primary Entry Point)

package/src/pipeline.test.ts

@@ -31,7 +31,7 @@ describe("Codegen pipeline", () => {
     )
   }
 
-  it("applies per-canister reactor mode overrides over the global default", async () => {
+  it("uses per-canister mode to generate Reactor-based hooks", async () => {
     const projectRoot = createTempProject()
     writeDid(projectRoot, "workflow_engine.did")
 
@@ -39,35 +39,28 @@ describe("Codegen pipeline", () => {
       canisterConfig: {
         name: "workflow_engine",
         didFile: "workflow_engine.did",
+        mode: "Reactor",
       },
       projectRoot,
       globalConfig: {
         outDir: "src/declarations",
         clientManagerPath: "../../clients",
-        reactor: {
-          defaultMode: "display",
-          canisters: {
-            workflow_engine: "raw",
-          },
-        },
       },
     })
 
     expect(result.success).toBe(true)
 
-    const generatedPath = path.join(
+    const indexPath = path.join(
       projectRoot,
-      "src/declarations/workflow_engine/index.generated.ts"
+      "src/declarations/workflow_engine/index.ts"
     )
-    const generated = fs.readFileSync(generatedPath, "utf-8")
+    const generated = fs.readFileSync(indexPath, "utf-8")
 
     expect(generated).toContain("new Reactor<WorkflowEngineService>")
-    expect(generated).toContain(
-      'export const WorkflowEngineReactorMode = "raw" as const'
-    )
+    expect(generated).not.toContain("new DisplayReactor<WorkflowEngineService>")
   })
 
-  it("does not overwrite the wrapper file on regenerate", async () => {
+  it("does not overwrite user-modified index.ts on regenerate", async () => {
     const projectRoot = createTempProject()
     writeDid(projectRoot, "backend.did")
 
@@ -86,26 +79,26 @@ describe("Codegen pipeline", () => {
     const first = await runCanisterPipeline(options)
     expect(first.success).toBe(true)
 
-    const wrapperPath = path.join(
+    const indexPath = path.join(
       projectRoot,
       "src/declarations/backend/index.ts"
     )
     fs.writeFileSync(
-      wrapperPath,
-      `// user wrapper
-export const customBackendWrapper = true
+      indexPath,
+      `// user custom canister file
+export const customBackendIndex = true
 `
     )
 
     const second = await runCanisterPipeline(options)
     expect(second.success).toBe(true)
 
-    const wrapper = fs.readFileSync(wrapperPath, "utf-8")
-    expect(wrapper).toContain("customBackendWrapper = true")
+    const wrapper = fs.readFileSync(indexPath, "utf-8")
+    expect(wrapper).toContain("customBackendIndex = true")
     expect(second.files).toEqual(
       expect.arrayContaining([
         expect.objectContaining({
-          filePath: wrapperPath,
+          filePath: indexPath,
           skipped: true,
           success: true,
         }),
@@ -113,14 +106,14 @@ export const customBackendWrapper = true
     )
   })
 
-  it("migrates a legacy generated index.ts into a stable wrapper", async () => {
+  it("overwrites legacy generated index.ts during regeneration", async () => {
     const projectRoot = createTempProject()
     writeDid(projectRoot, "backend.did")
 
     const canisterOutDir = path.join(projectRoot, "src/declarations/backend")
     fs.mkdirSync(canisterOutDir, { recursive: true })
 
-    // Simulate the pre-wrapper generated index.ts content from older versions.
+    // Simulate a generated index.ts content from older versions.
     fs.writeFileSync(
       path.join(canisterOutDir, "index.ts"),
       `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
@@ -161,18 +154,10 @@ export const {
 
     expect(result.success).toBe(true)
 
-    const wrapperPath = path.join(canisterOutDir, "index.ts")
-    const wrapper = fs.readFileSync(wrapperPath, "utf-8")
-    expect(wrapper).toContain('export * from "./index.generated"')
-    expect(wrapper).not.toContain("createActorHooks(")
-
-    const generated = fs.readFileSync(
-      path.join(canisterOutDir, "index.generated.ts"),
-      "utf-8"
-    )
-    expect(generated).toContain("createBackendDisplayReactor")
-    expect(generated).toContain(
-      'export const BackendReactorMode = "display" as const'
-    )
+    const indexPath = path.join(canisterOutDir, "index.ts")
+    const generated = fs.readFileSync(indexPath, "utf-8")
+    expect(generated).toContain("new DisplayReactor<BackendService>")
+    expect(generated).toContain("useBackendMutation")
+    expect(generated).not.toContain('export * from "./index.generated"')
   })
 })

package/src/pipeline.ts

@@ -7,7 +7,7 @@
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor implementation + stable wrapper (`index.generated.ts` + `index.ts`)
+ *  3. Generate reactor file (`index.ts`)
  */
 
 import fs from "node:fs"
@@ -16,13 +16,10 @@ import type {
   CanisterConfig,
   CodegenConfig,
   GeneratorResult,
-  ReactorMode,
+  ReactorClassName,
 } from "./types.js"
 import { generateDeclarations } from "./generators/declarations.js"
-import {
-  generateReactorFile,
-  generateReactorWrapperFile,
-} from "./generators/reactor.js"
+import { generateReactorFile } from "./generators/reactor.js"
 
 export interface PipelineOptions {
   /** Canister name and config */
@@ -35,29 +32,17 @@ export interface PipelineOptions {
   /**
    * Global codegen config (for fallback outDir and clientManagerPath).
    */
-  globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath" | "reactor">
+  globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">
 }
 
-function resolveReactorMode(
-  canisterName: string,
-  globalConfig: Pick<CodegenConfig, "reactor">
-): ReactorMode {
-  return (
-    globalConfig.reactor?.canisters?.[canisterName] ??
-    globalConfig.reactor?.defaultMode ??
-    "display"
-  )
+function resolveReactorClass(canisterConfig: CanisterConfig): ReactorClassName {
+  return canisterConfig.mode ?? "DisplayReactor"
 }
 
-function isStableWrapperFile(content: string): boolean {
-  return content.includes('export * from "./index.generated"')
-}
-
-function isLegacyGeneratedIndexFile(content: string): boolean {
+function isGeneratedIndexFile(content: string): boolean {
   return (
     content.includes("Auto-generated by @ic-reactor/codegen") &&
-    content.includes("createActorHooks(") &&
-    !isStableWrapperFile(content)
+    content.includes("createActorHooks(")
   )
 }
 
@@ -137,48 +122,37 @@ export async function runCanisterPipeline(
     }
   }
 
-  // ── Step 2: Reactor implementation + stable wrapper ───────────────────────
+  // ── Step 2: Reactor file ───────────────────────────────────────────────────
 
-  const generatedReactorPath = path.join(canisterOutDir, "index.generated.ts")
-  const wrapperPath = path.join(canisterOutDir, "index.ts")
-  const reactorMode = resolveReactorMode(name, globalConfig)
+  const reactorPath = path.join(canisterOutDir, "index.ts")
+  const reactorClass = resolveReactorClass(canisterConfig)
 
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
       clientManagerPath: resolvedClientManagerPath,
-      reactorMode,
-    })
-    const wrapperContent = generateReactorWrapperFile({
-      canisterName: name,
-      didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath,
-      reactorMode,
+      reactorClass,
     })
 
     fs.mkdirSync(canisterOutDir, { recursive: true })
-    fs.writeFileSync(generatedReactorPath, reactorContent)
-
-    files.push({ success: true, filePath: generatedReactorPath })
-
-    if (!fs.existsSync(wrapperPath)) {
-      fs.writeFileSync(wrapperPath, wrapperContent)
-      files.push({ success: true, filePath: wrapperPath })
+    if (!fs.existsSync(reactorPath)) {
+      fs.writeFileSync(reactorPath, reactorContent)
+      files.push({ success: true, filePath: reactorPath })
     } else {
-      const existingWrapperContent = fs.readFileSync(wrapperPath, "utf-8")
+      const existingIndexContent = fs.readFileSync(reactorPath, "utf-8")
 
-      if (isLegacyGeneratedIndexFile(existingWrapperContent)) {
-        fs.writeFileSync(wrapperPath, wrapperContent)
-        files.push({ success: true, filePath: wrapperPath })
+      if (isGeneratedIndexFile(existingIndexContent)) {
+        fs.writeFileSync(reactorPath, reactorContent)
+        files.push({ success: true, filePath: reactorPath })
       } else {
-        files.push({ success: true, filePath: wrapperPath, skipped: true })
+        files.push({ success: true, filePath: reactorPath, skipped: true })
       }
     }
   } catch (err) {
     files.push({
       success: false,
-      filePath: generatedReactorPath,
+      filePath: reactorPath,
       error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`,
     })
 

package/src/reactor.test.ts

@@ -1,42 +1,45 @@
 import { describe, expect, it } from "vitest"
-import { generateReactorFile, generateReactorWrapperFile } from "./generators"
+import { generateReactorFile } from "./generators"
 
 describe("Reactor generator", () => {
-  it("keeps default behavior as display mode", () => {
+  it("keeps default behavior as DisplayReactor", () => {
     const content = generateReactorFile({
       canisterName: "backend",
       didFile: "mock/backend.did",
       clientManagerPath: "../../clients",
     })
 
-    expect(content).toMatchSnapshot("display-mode-index-generated")
+    expect(content).toMatchSnapshot("display-reactor-index")
     expect(content).toContain("new DisplayReactor<BackendService>")
-    expect(content).toContain(
-      'export const BackendReactorMode = "display" as const'
-    )
+    expect(content).not.toContain("export const BackendReactorMode")
   })
 
-  it("supports raw mode generation", () => {
+  it("supports Reactor mode generation", () => {
     const content = generateReactorFile({
       canisterName: "workflow_engine",
       didFile: "mock/workflow_engine.did",
-      reactorMode: "raw",
+      reactorClass: "Reactor",
     })
 
-    expect(content).toMatchSnapshot("raw-mode-index-generated")
+    expect(content).toMatchSnapshot("reactor-index")
     expect(content).toContain("new Reactor<WorkflowEngineService>")
-    expect(content).toContain(
-      'export const WorkflowEngineReactorMode = "raw" as const'
-    )
+    expect(content).not.toContain("createWorkflowEngineDisplayReactor")
   })
 
-  it("generates a stable wrapper file", () => {
-    const content = generateReactorWrapperFile({
-      canisterName: "backend",
-      didFile: "mock/backend.did",
+  it("supports candid reactor subclasses", () => {
+    const content = generateReactorFile({
+      canisterName: "ledger",
+      didFile: "mock/ledger.did",
+      reactorClass: "MetadataDisplayReactor",
     })
 
-    expect(content).toMatchSnapshot("stable-wrapper-index")
-    expect(content).toContain('export * from "./index.generated"')
+    expect(content).toMatchSnapshot("metadata-display-reactor-index")
+    expect(content).toContain(
+      'import { createActorHooks } from "@ic-reactor/react"'
+    )
+    expect(content).toContain(
+      'import { MetadataDisplayReactor } from "@ic-reactor/candid"'
+    )
+    expect(content).toContain("new MetadataDisplayReactor<LedgerService>")
   })
 })

package/src/types.ts

@@ -24,24 +24,21 @@ export interface CanisterConfig {
    * Example: "../../clients" → `import { clientManager } from "../../clients"`
    */
   clientManagerPath?: string
+  /**
+   * Reactor class used for generated hooks in this canister.
+   * Defaults to DisplayReactor for backward compatibility.
+   */
+  mode?: ReactorClassName
   /** Optional fixed canister ID */
   canisterId?: string
 }
 
-export type ReactorMode = "raw" | "display"
-
-export interface ReactorGenerationConfig {
-  /**
-   * Default reactor mode used for generated hook exports.
-   * `display` preserves current behavior.
-   */
-  defaultMode?: ReactorMode
-  /**
-   * Optional per-canister overrides keyed by canister name.
-   * Example: { workflow_engine: "raw" }
-   */
-  canisters?: Record<string, ReactorMode>
-}
+export type ReactorClassName =
+  | "Reactor"
+  | "DisplayReactor"
+  | "CandidReactor"
+  | "CandidDisplayReactor"
+  | "MetadataDisplayReactor"
 
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
@@ -59,8 +56,6 @@ export interface CodegenConfig {
    * Individual canisters can override via `CanisterConfig.clientManagerPath`.
    */
   clientManagerPath?: string
-  /** Optional reactor mode generation settings */
-  reactor?: ReactorGenerationConfig
   /** Canister configurations, keyed by canister name */
   canisters: Record<string, CanisterConfig>
 }