@ic-reactor/codegen 0.5.1 → 0.6.0

package/README.md

@@ -23,16 +23,75 @@ await runCanisterPipeline({
   globalConfig: {
     outDir: "src/declarations",
     clientManagerPath: "../../clients",
+    reactor: {
+      defaultMode: "display",
+      canisters: {
+        workflow_engine: "raw",
+      },
+    },
   },
 })
 ```
 
+## Reactor Mode Configuration
+
+`reactor.defaultMode` controls whether generated default hook exports use:
+
+- `display` → `DisplayReactor` (current/default behavior)
+- `raw` → `Reactor` (raw Candid shapes)
+
+`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
+```
+
 ## 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.ts` file with `DisplayReactor` and hooks.
+- **`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).
 - **`generateClientFile`**: Generates a `ClientManager` boilerplate file.
 
 ## Utilities

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   generateClientFile: () => generateClientFile,
   generateDeclarations: () => generateDeclarations,
   generateReactorFile: () => generateReactorFile,
+  generateReactorWrapperFile: () => generateReactorWrapperFile,
   getReactorName: () => getReactorName,
   getServiceTypeName: () => getServiceTypeName,
   parseDIDFile: () => parseDIDFile,
@@ -124,13 +125,21 @@ function getServiceTypeName(canisterName) {
 
 // src/generators/reactor.ts
 function generateReactorFile(options) {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options;
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    reactorMode = "display"
+  } = 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, createActorHooks } from "@ic-reactor/react"
+  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -142,11 +151,25 @@ 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 const ${reactorName} = new DisplayReactor<${serviceName}>({
-  clientManager,
-  idlFactory,
-  name: "${canisterName}",
-})
+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 {
   useActorQuery: use${pascalName}Query,
@@ -158,8 +181,29 @@ 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 isLegacyGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(") && !isStableWrapperFile(content);
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -198,20 +242,41 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const reactorPath = import_node_path3.default.join(canisterOutDir, "index.ts");
+  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);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      reactorMode
+    });
+    const wrapperContent = generateReactorWrapperFile({
+      canisterName: name,
+      didFile: resolvedDidFile,
+      clientManagerPath: resolvedClientManagerPath,
+      reactorMode
     });
     import_node_fs2.default.mkdirSync(canisterOutDir, { recursive: true });
-    import_node_fs2.default.writeFileSync(reactorPath, reactorContent);
-    files.push({ success: true, filePath: reactorPath });
+    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 });
+    } 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 });
+      } else {
+        files.push({ success: true, filePath: wrapperPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,
-      filePath: reactorPath,
+      filePath: generatedReactorPath,
       error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`
     });
     return {
@@ -290,6 +355,7 @@ export const clientManager = new ClientManager({
   generateClientFile,
   generateDeclarations,
   generateReactorFile,
+  generateReactorWrapperFile,
   getReactorName,
   getServiceTypeName,
   parseDIDFile,

package/dist/index.d.cts

@@ -22,6 +22,19 @@ interface CanisterConfig {
     /** 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" }
+     */
+    canisters?: Record<string, ReactorMode>;
+}
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -38,6 +51,8 @@ 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>;
 }
@@ -62,7 +77,7 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor file (index.ts)
+ *  3. Generate reactor implementation + stable wrapper (`index.generated.ts` + `index.ts`)
  */
 
 interface PipelineOptions {
@@ -76,7 +91,7 @@ interface PipelineOptions {
     /**
      * Global codegen config (for fallback outDir and clientManagerPath).
      */
-    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">;
+    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath" | "reactor">;
 }
 interface PipelineResult {
     canisterName: string;
@@ -204,6 +219,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,11 +233,21 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /**
+     * Which reactor implementation should back the default exported hooks.
+     * Default: "display" (backward compatible)
+     */
+    reactorMode?: ReactorMode;
 }
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's `index.generated.ts` implementation 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
@@ -246,4 +272,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 ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, 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 ReactorGenerationConfig, type ReactorGeneratorOptions, type ReactorMode, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, generateReactorWrapperFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.d.ts

@@ -22,6 +22,19 @@ interface CanisterConfig {
     /** 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" }
+     */
+    canisters?: Record<string, ReactorMode>;
+}
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -38,6 +51,8 @@ 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>;
 }
@@ -62,7 +77,7 @@ interface GeneratorResult {
  * Pipeline steps (in order):
  *  1. Resolve paths (didFile, outDir)
  *  2. Generate declarations (JS + .d.ts + .did copy)
- *  3. Generate reactor file (index.ts)
+ *  3. Generate reactor implementation + stable wrapper (`index.generated.ts` + `index.ts`)
  */
 
 interface PipelineOptions {
@@ -76,7 +91,7 @@ interface PipelineOptions {
     /**
      * Global codegen config (for fallback outDir and clientManagerPath).
      */
-    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath">;
+    globalConfig: Pick<CodegenConfig, "outDir" | "clientManagerPath" | "reactor">;
 }
 interface PipelineResult {
     canisterName: string;
@@ -204,6 +219,7 @@ declare function declarationsExist(outDir: string, canisterName: string): boolea
  *     ...
  *   } = createActorHooks(backendReactor)
  */
+
 interface ReactorGeneratorOptions {
     /** Canister name (e.g. "backend") */
     canisterName: string;
@@ -217,11 +233,21 @@ interface ReactorGeneratorOptions {
      * Default: "../../clients"
      */
     clientManagerPath?: string;
+    /**
+     * Which reactor implementation should back the default exported hooks.
+     * Default: "display" (backward compatible)
+     */
+    reactorMode?: ReactorMode;
 }
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's `index.generated.ts` implementation 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
@@ -246,4 +272,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 ReactorGeneratorOptions, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, 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 ReactorGenerationConfig, type ReactorGeneratorOptions, type ReactorMode, declarationsExist, extractMethods, generateClientFile, generateDeclarations, generateReactorFile, generateReactorWrapperFile, getReactorName, getServiceTypeName, parseDIDFile, runCanisterPipeline, toPascalCase };

package/dist/index.js

@@ -79,13 +79,21 @@ function getServiceTypeName(canisterName) {
 
 // src/generators/reactor.ts
 function generateReactorFile(options) {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options;
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    reactorMode = "display"
+  } = 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, createActorHooks } from "@ic-reactor/react"
+  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -97,11 +105,25 @@ 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 const ${reactorName} = new DisplayReactor<${serviceName}>({
-  clientManager,
-  idlFactory,
-  name: "${canisterName}",
-})
+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 {
   useActorQuery: use${pascalName}Query,
@@ -113,8 +135,29 @@ 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 isLegacyGeneratedIndexFile(content) {
+  return content.includes("Auto-generated by @ic-reactor/codegen") && content.includes("createActorHooks(") && !isStableWrapperFile(content);
+}
 async function runCanisterPipeline(options) {
   const { canisterConfig, projectRoot, globalConfig } = options;
   const { name, didFile, clientManagerPath } = canisterConfig;
@@ -153,20 +196,41 @@ async function runCanisterPipeline(options) {
       error: `Declarations step failed: ${err instanceof Error ? err.message : String(err)}`
     };
   }
-  const reactorPath = path3.join(canisterOutDir, "index.ts");
+  const generatedReactorPath = path3.join(canisterOutDir, "index.generated.ts");
+  const wrapperPath = path3.join(canisterOutDir, "index.ts");
+  const reactorMode = resolveReactorMode(name, globalConfig);
   try {
     const reactorContent = generateReactorFile({
       canisterName: name,
       didFile: resolvedDidFile,
-      clientManagerPath: resolvedClientManagerPath
+      clientManagerPath: resolvedClientManagerPath,
+      reactorMode
+    });
+    const wrapperContent = generateReactorWrapperFile({
+      canisterName: name,
+      didFile: resolvedDidFile,
+      clientManagerPath: resolvedClientManagerPath,
+      reactorMode
     });
     fs2.mkdirSync(canisterOutDir, { recursive: true });
-    fs2.writeFileSync(reactorPath, reactorContent);
-    files.push({ success: true, filePath: reactorPath });
+    fs2.writeFileSync(generatedReactorPath, reactorContent);
+    files.push({ success: true, filePath: generatedReactorPath });
+    if (!fs2.existsSync(wrapperPath)) {
+      fs2.writeFileSync(wrapperPath, wrapperContent);
+      files.push({ success: true, filePath: wrapperPath });
+    } else {
+      const existingWrapperContent = fs2.readFileSync(wrapperPath, "utf-8");
+      if (isLegacyGeneratedIndexFile(existingWrapperContent)) {
+        fs2.writeFileSync(wrapperPath, wrapperContent);
+        files.push({ success: true, filePath: wrapperPath });
+      } else {
+        files.push({ success: true, filePath: wrapperPath, skipped: true });
+      }
+    }
   } catch (err) {
     files.push({
       success: false,
-      filePath: reactorPath,
+      filePath: generatedReactorPath,
       error: `Reactor generation failed: ${err instanceof Error ? err.message : String(err)}`
     });
     return {
@@ -244,6 +308,7 @@ export {
   generateClientFile,
   generateDeclarations,
   generateReactorFile,
+  generateReactorWrapperFile,
   getReactorName,
   getServiceTypeName,
   parseDIDFile,

package/package.json

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

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

@@ -0,0 +1,100 @@
+// 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"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/backend"
+
+export type BackendService = _SERVICE
+
+/**
+ * Backend Reactor
+ *
+ * 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 {
+  useActorQuery: useBackendQuery,
+  useActorSuspenseQuery: useBackendSuspenseQuery,
+  useActorInfiniteQuery: useBackendInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useBackendSuspenseInfiniteQuery,
+  useActorMutation: useBackendMutation,
+  useActorMethod: useBackendMethod,
+} = createActorHooks(backendReactor)
+"
+`;
+
+exports[`Reactor generator > supports raw mode generation > raw-mode-index-generated 1`] = `
+"import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/workflow_engine"
+
+export type WorkflowEngineService = _SERVICE
+
+/**
+ * WorkflowEngine Reactor
+ *
+ * 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 {
+  useActorQuery: useWorkflowEngineQuery,
+  useActorSuspenseQuery: useWorkflowEngineSuspenseQuery,
+  useActorInfiniteQuery: useWorkflowEngineInfiniteQuery,
+  useActorSuspenseInfiniteQuery: useWorkflowEngineSuspenseInfiniteQuery,
+  useActorMutation: useWorkflowEngineMutation,
+  useActorMethod: useWorkflowEngineMethod,
+} = createActorHooks(workflowEngineReactor)
+"
+`;

package/src/generators/index.ts

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

package/src/generators/reactor.ts

@@ -22,6 +22,7 @@
 
 import path from "node:path"
 import { toPascalCase, getReactorName, getServiceTypeName } from "../naming.js"
+import type { ReactorMode } from "../types.js"
 
 export interface ReactorGeneratorOptions {
   /** Canister name (e.g. "backend") */
@@ -36,23 +37,37 @@ export interface ReactorGeneratorOptions {
    * Default: "../../clients"
    */
   clientManagerPath?: string
+  /**
+   * Which reactor implementation should back the default exported hooks.
+   * Default: "display" (backward compatible)
+   */
+  reactorMode?: ReactorMode
 }
 
 /**
- * Generate the content of a canister's `index.ts` reactor file.
+ * Generate the content of a canister's `index.generated.ts` implementation file.
  */
 export function generateReactorFile(options: ReactorGeneratorOptions): string {
-  const { canisterName, didFile, clientManagerPath = "../../clients" } = options
+  const {
+    canisterName,
+    didFile,
+    clientManagerPath = "../../clients",
+    reactorMode = "display",
+  } = 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}`
 
-  return `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+  return `import { DisplayReactor, Reactor, createActorHooks } from "@ic-reactor/react"
 import { clientManager } from "${clientManagerPath}"
 import { idlFactory, type _SERVICE } from "${declarationsPath}"
 
@@ -64,11 +79,25 @@ 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 const ${reactorName} = new DisplayReactor<${serviceName}>({
-  clientManager,
-  idlFactory,
-  name: "${canisterName}",
-})
+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 {
   useActorQuery: use${pascalName}Query,
@@ -80,3 +109,23 @@ 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

@@ -6,7 +6,13 @@
  */
 
 // Core Types
-export type { CanisterConfig, CodegenConfig, GeneratorResult } from "./types.js"
+export type {
+  CanisterConfig,
+  CodegenConfig,
+  GeneratorResult,
+  ReactorMode,
+  ReactorGenerationConfig,
+} from "./types.js"
 
 // Pipeline (Primary Entry Point)
 export { runCanisterPipeline } from "./pipeline.js"

package/src/pipeline.test.ts

@@ -0,0 +1,178 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { runCanisterPipeline } from "./pipeline"
+
+describe("Codegen pipeline", () => {
+  const tempDirs: string[] = []
+
+  afterEach(() => {
+    for (const dir of tempDirs) {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+    tempDirs.length = 0
+  })
+
+  function createTempProject() {
+    const projectRoot = fs.mkdtempSync(
+      path.join(os.tmpdir(), "ic-reactor-codegen-pipeline-")
+    )
+    tempDirs.push(projectRoot)
+    return projectRoot
+  }
+
+  function writeDid(projectRoot: string, fileName: string) {
+    fs.writeFileSync(
+      path.join(projectRoot, fileName),
+      `service : {
+  greet: (text) -> (text) query;
+}`
+    )
+  }
+
+  it("applies per-canister reactor mode overrides over the global default", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "workflow_engine.did")
+
+    const result = await runCanisterPipeline({
+      canisterConfig: {
+        name: "workflow_engine",
+        didFile: "workflow_engine.did",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+        reactor: {
+          defaultMode: "display",
+          canisters: {
+            workflow_engine: "raw",
+          },
+        },
+      },
+    })
+
+    expect(result.success).toBe(true)
+
+    const generatedPath = path.join(
+      projectRoot,
+      "src/declarations/workflow_engine/index.generated.ts"
+    )
+    const generated = fs.readFileSync(generatedPath, "utf-8")
+
+    expect(generated).toContain("new Reactor<WorkflowEngineService>")
+    expect(generated).toContain(
+      'export const WorkflowEngineReactorMode = "raw" as const'
+    )
+  })
+
+  it("does not overwrite the wrapper file on regenerate", async () => {
+    const projectRoot = createTempProject()
+    writeDid(projectRoot, "backend.did")
+
+    const options = {
+      canisterConfig: {
+        name: "backend",
+        didFile: "backend.did",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    } as const
+
+    const first = await runCanisterPipeline(options)
+    expect(first.success).toBe(true)
+
+    const wrapperPath = path.join(
+      projectRoot,
+      "src/declarations/backend/index.ts"
+    )
+    fs.writeFileSync(
+      wrapperPath,
+      `// user wrapper
+export const customBackendWrapper = true
+`
+    )
+
+    const second = await runCanisterPipeline(options)
+    expect(second.success).toBe(true)
+
+    const wrapper = fs.readFileSync(wrapperPath, "utf-8")
+    expect(wrapper).toContain("customBackendWrapper = true")
+    expect(second.files).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          filePath: wrapperPath,
+          skipped: true,
+          success: true,
+        }),
+      ])
+    )
+  })
+
+  it("migrates a legacy generated index.ts into a stable wrapper", 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.
+    fs.writeFileSync(
+      path.join(canisterOutDir, "index.ts"),
+      `import { DisplayReactor, createActorHooks } from "@ic-reactor/react"
+import { clientManager } from "../../clients"
+import { idlFactory, type _SERVICE } from "./declarations/backend"
+
+export type BackendService = _SERVICE
+
+/**
+ * Backend Reactor
+ *
+ * Auto-generated by @ic-reactor/codegen — do not edit.
+ * Re-run \`ic-reactor generate\` (or the Vite plugin) to regenerate.
+ */
+export const backendReactor = new DisplayReactor<BackendService>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+})
+
+export const {
+  useActorQuery: useBackendQuery,
+} = createActorHooks(backendReactor)
+`
+    )
+
+    const result = await runCanisterPipeline({
+      canisterConfig: {
+        name: "backend",
+        didFile: "backend.did",
+      },
+      projectRoot,
+      globalConfig: {
+        outDir: "src/declarations",
+        clientManagerPath: "../../clients",
+      },
+    })
+
+    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'
+    )
+  })
+})

package/src/pipeline.ts

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

package/src/reactor.test.ts

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

package/src/types.ts

@@ -28,6 +28,21 @@ export interface CanisterConfig {
   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>
+}
+
 /**
  * Top-level codegen / CLI configuration (stored in `ic-reactor.json`).
  */
@@ -44,6 +59,8 @@ 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>
 }