@ahmednawaz/crank 0.1.8 → 0.2.0

package/AGENTS.md

@@ -103,6 +103,38 @@ See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
 
 ---
 
+## Panel injection (Retune pattern)
+
+**Preferred for React apps** — install the package and mount once:
+
+```bash
+pnpm add -D @ahmednawaz/crank
+# or: npm i -D @ahmednawaz/crank
+```
+
+```tsx
+import { Crank } from '@ahmednawaz/crank/react'
+
+// main.tsx
+<App />
+<Crank />
+```
+
+Keep companion running: `npx @ahmednawaz/crank start`
+
+On Replit set public companion URL if needed: `window.__CRANK_URL__`, `<Crank companionUrl="…" />`, or `VITE_CRANK_URL`.
+
+| Stack | Integration |
+|-------|-------------|
+| **React + Vite** | `<Crank />` from `@ahmednawaz/crank/react` (bundled like Retune — **no Vite plugin**) |
+| **Next.js** | `<Crank />` from `@ahmednawaz/crank/next` |
+| **Vue / Svelte / vanilla Vite** | Optional `@ahmednawaz/crank/vite` plugin |
+| **Any** | Bookmarklet from companion URL |
+
+Agents: do **not** invent Vite-plugin path workarounds for React apps. See `.crank/react-mount.md` / `.crank/injection.md` after setup.
+
+---
+
 ## MCP tools (agent pull workflow)
 
 When the user clicks **Agent** on a copy variant or says *“Apply the pending Crank change”*:

package/README.md

@@ -102,6 +102,35 @@ No external sibling tool required. Crank ships:
 
 Optional: `CRANK_ASSET_ROOT` overrides where packaged UI assets are loaded from (defaults to this install).
 
+### Panel injection (Retune-style React)
+
+**Preferred** — install and mount like Retune:
+
+```bash
+pnpm add -D @ahmednawaz/crank
+```
+
+```tsx
+import { Crank } from '@ahmednawaz/crank/react'
+
+createRoot(document.getElementById('root')!).render(
+  <>
+    <App />
+    <Crank />
+  </>
+)
+```
+
+Companion: `npx @ahmednawaz/crank start`  
+Replit public URL: `window.__CRANK_URL__` or `<Crank companionUrl="https://3344-….replit.dev" />` or `VITE_CRANK_URL`.
+
+| Stack | Integration |
+|-------|-------------|
+| **React** | `<Crank />` — bundled by Vite, **no plugin** |
+| **Next.js** | `import { Crank } from '@ahmednawaz/crank/next'` |
+| **Non-React Vite** | Optional `import { crank } from '@ahmednawaz/crank/vite'` |
+| **Fallback** | Companion bookmarklet |
+
 Useful variants:
 
 ```bash

package/companion/dev-loader.js

@@ -1,8 +1,8 @@
 'use strict';
 
 /**
- * Injected by Vite plugin (or bookmarklet fallback).
- * Loads the Crank panel from the local companion.
+ * Injected by <Crank /> (React) or the optional Vite plugin / bookmarklet.
+ * Loads the Crank panel from the companion that served this script.
  */
 (function () {
   if (window.__CRANK_LOADER__) {

package/lib/detect.js

@@ -4,6 +4,41 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+const VITE_CONFIG_NAMES = [
+  'vite.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.cjs',
+  'vite.config.mts',
+  'vite.config.cts'
+];
+
+const APP_DIR_CANDIDATES = [
+  '.',
+  'app',
+  'client',
+  'web',
+  'frontend',
+  'ui',
+  'src',
+  'packages/app',
+  'packages/web',
+  'apps/web',
+  'apps/frontend'
+];
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.turbo',
+  '.cache',
+  '.crank'
+]);
+
 function exists(p) {
   try {
     return fs.existsSync(p);
@@ -25,21 +60,97 @@ function writeJson(file, data) {
   fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
 }
 
+function findViteConfigInDir(dir) {
+  for (const name of VITE_CONFIG_NAMES) {
+    const full = path.join(dir, name);
+    if (exists(full)) {
+      return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Find vite.config.* at project root, common app subdirs, then shallow BFS.
+ */
+function findViteConfig(projectRoot) {
+  const root = path.resolve(projectRoot);
+  for (const sub of APP_DIR_CANDIDATES) {
+    const dir = sub === '.' ? root : path.join(root, sub);
+    const hit = findViteConfigInDir(dir);
+    if (hit) {
+      return hit;
+    }
+  }
+
+  // Shallow walk (depth 2) for monorepos / Replit layouts
+  const queue = [{ dir: root, depth: 0 }];
+  while (queue.length) {
+    const { dir, depth } = queue.shift();
+    if (depth > 0) {
+      const hit = findViteConfigInDir(dir);
+      if (hit) {
+        return hit;
+      }
+    }
+    if (depth >= 2) {
+      continue;
+    }
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+        continue;
+      }
+      queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+    }
+  }
+  return null;
+}
+
+function packageHasDep(pkg, name) {
+  if (!pkg || typeof pkg !== 'object') {
+    return false;
+  }
+  return Boolean(
+    pkg.dependencies?.[name] ||
+      pkg.devDependencies?.[name] ||
+      pkg.peerDependencies?.[name]
+  );
+}
+
 function detectEnvironment(projectRoot) {
   const env = process.env;
   const isReplit = Boolean(
     env.REPL_ID || env.REPL_SLUG || env.REPLIT_DEV_DOMAIN || env.REPLIT_DB_URL
   );
-  const hasVite =
-    exists(path.join(projectRoot, 'vite.config.ts')) ||
-    exists(path.join(projectRoot, 'vite.config.js')) ||
-    exists(path.join(projectRoot, 'vite.config.mjs')) ||
-    exists(path.join(projectRoot, 'vite.config.cjs'));
   const hasPackageJson = exists(path.join(projectRoot, 'package.json'));
-  const hasCursor = exists(path.join(projectRoot, '.cursor')) ||
-    exists(path.join(os.homedir(), '.cursor'));
-  const hasVsCode = exists(path.join(projectRoot, '.vscode')) ||
-    exists(path.join(projectRoot, '.vscode'.replace('s', 's')));
+  const packageJson = hasPackageJson
+    ? readJson(path.join(projectRoot, 'package.json'), {})
+    : null;
+  const viteConfig = findViteConfig(projectRoot);
+  const hasVite = Boolean(viteConfig) || packageHasDep(packageJson, 'vite');
+  const hasReact =
+    packageHasDep(packageJson, 'react') ||
+    exists(path.join(projectRoot, 'next.config.js')) ||
+    exists(path.join(projectRoot, 'next.config.mjs')) ||
+    exists(path.join(projectRoot, 'next.config.ts'));
+  const hasNext =
+    packageHasDep(packageJson, 'next') ||
+    exists(path.join(projectRoot, 'next.config.js')) ||
+    exists(path.join(projectRoot, 'next.config.mjs')) ||
+    exists(path.join(projectRoot, 'next.config.ts'));
+  const hasWebpack =
+    packageHasDep(packageJson, 'webpack') ||
+    exists(path.join(projectRoot, 'webpack.config.js')) ||
+    exists(path.join(projectRoot, 'webpack.config.ts'));
+
+  const hasCursor =
+    exists(path.join(projectRoot, '.cursor')) || exists(path.join(os.homedir(), '.cursor'));
   const claudeConfig = path.join(
     os.homedir(),
     'Library',
@@ -52,37 +163,26 @@ function detectEnvironment(projectRoot) {
   return {
     isReplit,
     hasVite,
+    viteConfig,
+    hasReact,
+    hasNext,
+    hasWebpack,
     hasPackageJson,
     hasCursor,
     hasVsCode: exists(path.join(projectRoot, '.vscode')),
     hasClaudeDesktop,
     claudeConfig,
     replitDomain: env.REPLIT_DEV_DOMAIN || null,
-    packageJson: hasPackageJson
-      ? readJson(path.join(projectRoot, 'package.json'), {})
-      : null
+    packageJson
   };
 }
 
-function findViteConfig(projectRoot) {
-  for (const name of [
-    'vite.config.ts',
-    'vite.config.js',
-    'vite.config.mjs',
-    'vite.config.cjs'
-  ]) {
-    const full = path.join(projectRoot, name);
-    if (exists(full)) {
-      return full;
-    }
-  }
-  return null;
-}
-
 module.exports = {
   exists,
   readJson,
   writeJson,
   detectEnvironment,
-  findViteConfig
+  findViteConfig,
+  VITE_CONFIG_NAMES,
+  APP_DIR_CANDIDATES
 };

package/lib/init.js

@@ -94,59 +94,214 @@ function mergeVsCodeMcp(file, projectRoot) {
   return file;
 }
 
+function writeVitePluginStub(projectRoot) {
+  const dir = path.join(projectRoot, '.crank');
+  fs.mkdirSync(dir, { recursive: true });
+  const stubPath = path.join(dir, 'vite-plugin.cjs');
+  const stub = `'use strict';
+
+/**
+ * Crank Vite plugin loader — Vizpatch-style graceful resolve.
+ * Generated by \`npx @ahmednawaz/crank setup\`. Does not throw if Crank is missing.
+ *
+ * Resolves from (in order):
+ *   1. .crank/config.json packageRoot (npx cache / local checkout)
+ *   2. node_modules/@ahmednawaz/crank or node_modules/crank
+ *   3. require('@ahmednawaz/crank/vite')
+ */
+const fs = require('fs');
+const path = require('path');
+
+function load() {
+  const candidates = [];
+  try {
+    const configPath = path.join(__dirname, 'config.json');
+    if (fs.existsSync(configPath)) {
+      const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (cfg && cfg.packageRoot) {
+        candidates.push(path.join(cfg.packageRoot, 'vite.js'));
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  const cwd = process.cwd();
+  candidates.push(
+    path.join(cwd, 'node_modules', '@ahmednawaz', 'crank', 'vite.js'),
+    path.join(cwd, 'node_modules', 'crank', 'vite.js'),
+    path.join(__dirname, '..', 'node_modules', '@ahmednawaz', 'crank', 'vite.js'),
+    path.join(__dirname, '..', 'node_modules', 'crank', 'vite.js')
+  );
+
+  for (const file of candidates) {
+    try {
+      if (file && fs.existsSync(file)) {
+        return require(file);
+      }
+    } catch {
+      // try next
+    }
+  }
+
+  try {
+    return require('@ahmednawaz/crank/vite');
+  } catch {
+    // ignore
+  }
+  try {
+    return require('@ahmednawaz/crank');
+  } catch {
+    // ignore
+  }
+  try {
+    return require('crank/vite');
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function noopPlugin() {
+  return {
+    name: 'crank-dev-loader-noop',
+    apply: 'serve',
+    transformIndexHtml(html) {
+      return html;
+    }
+  };
+}
+
+const mod = load();
+const crankFn =
+  mod && typeof mod.crank === 'function' ? mod.crank : noopPlugin;
+
+module.exports = {
+  crank: crankFn,
+  crankDevLoader: crankFn,
+  resolveCompanionLoaderUrl: mod && mod.resolveCompanionLoaderUrl
+};
+`;
+  fs.writeFileSync(stubPath, stub);
+  return stubPath;
+}
+
 function patchViteConfig(projectRoot) {
   const configPath = findViteConfig(projectRoot);
+  const stubPath = writeVitePluginStub(projectRoot);
+
   if (!configPath) {
-    return { patched: false, reason: 'no-vite-config' };
+    return { patched: false, reason: 'no-vite-config', plugin: stubPath };
   }
+
   let source = fs.readFileSync(configPath, 'utf8');
-  if (/(\bcrank)\s*\(/.test(source) && /plugins/.test(source)) {
-    return { patched: false, reason: 'already-present', file: configPath };
+  if (
+    /vite-plugin\.cjs/.test(source) ||
+    (/(\bcrank)\s*\(/.test(source) && /plugins/.test(source))
+  ) {
+    return { patched: false, reason: 'already-present', file: configPath, plugin: stubPath };
   }
 
-  // Copy plugin into the project so Vite can resolve a relative import everywhere.
-  const localPluginDir = path.join(projectRoot, '.crank');
-  fs.mkdirSync(localPluginDir, { recursive: true });
-  const localPlugin = path.join(localPluginDir, 'vite-plugin.cjs');
-  fs.copyFileSync(path.join(PACKAGE_ROOT, 'vite.js'), localPlugin);
+  let relStub = path.relative(path.dirname(configPath), stubPath).replace(/\\/g, '/');
+  if (!relStub.startsWith('.')) {
+    relStub = `./${relStub}`;
+  }
 
-  const rel = './.crank/vite-plugin.cjs';
   const isEsm =
     configPath.endsWith('.mjs') ||
-    (/^import\s/m.test(source) && !configPath.endsWith('.cjs'));
-  const importLine = isEsm
-    ? `import { crank } from '${rel}';\n`
-    : `const { crank } = require('${rel}');\n`;
-
-  if (!/vite-plugin\.cjs|from ['"]crank/.test(source)) {
-    source = importLine + source;
-  }
-
-  if (/plugins\s*:\s*\[\s*\]/.test(source)) {
-    source = source.replace(/plugins\s*:\s*\[\s*\]/, 'plugins: [crank()]');
-  } else if (/plugins\s*:\s*\[/.test(source)) {
-    source = source.replace(/plugins\s*:\s*\[/, 'plugins: [crank(), ');
-  } else if (/defineConfig\s*\(\s*\{/.test(source)) {
-    source = source.replace(
-      /defineConfig\s*\(\s*\{/,
-      'defineConfig({\n  plugins: [crank()],'
-    );
-  } else if (/export\s+default\s+\{/.test(source)) {
-    source = source.replace(
-      /export\s+default\s+\{/,
-      'export default {\n  plugins: [crank()],'
-    );
-  } else if (/module\.exports\s*=\s*\{/.test(source)) {
-    source = source.replace(
-      /module\.exports\s*=\s*\{/,
-      'module.exports = {\n  plugins: [crank()],'
-    );
+    configPath.endsWith('.mts') ||
+    (/^import\s/m.test(source) && !configPath.endsWith('.cjs') && !configPath.endsWith('.cts'));
+
+  if (isEsm) {
+    const isTs = /\.tsx?$|\.mts$/.test(configPath);
+    const crankDecl = isTs
+      ? 'let crank: null | (() => unknown) = null'
+      : 'let crank = null';
+    const gracefulBlock = `import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+// Crank Vite plugin — graceful load (same pattern as Vizpatch); skip if unavailable
+${crankDecl}
+try {
+  const _crankPluginPath = fileURLToPath(new URL('${relStub}', import.meta.url))
+  if (existsSync(_crankPluginPath)) {
+    const require = createRequire(import.meta.url)
+    crank = require(_crankPluginPath).crank
+  }
+} catch {}
+
+`;
+    if (!/_crankPluginPath/.test(source)) {
+      source = gracefulBlock + source;
+    }
+
+    if (/plugins\s*:\s*\[\s*\]/.test(source)) {
+      source = source.replace(
+        /plugins\s*:\s*\[\s*\]/,
+        'plugins: [...(crank ? [crank()] : [])]'
+      );
+    } else if (/plugins\s*:\s*\[/.test(source)) {
+      source = source.replace(
+        /plugins\s*:\s*\[/,
+        'plugins: [...(crank ? [crank()] : []), '
+      );
+    } else if (/defineConfig\s*\(\s*\{/.test(source)) {
+      source = source.replace(
+        /defineConfig\s*\(\s*\{/,
+        'defineConfig({\n  plugins: [...(crank ? [crank()] : [])],'
+      );
+    } else if (/export\s+default\s+\{/.test(source)) {
+      source = source.replace(
+        /export\s+default\s+\{/,
+        'export default {\n  plugins: [...(crank ? [crank()] : [])],'
+      );
+    } else {
+      return {
+        patched: false,
+        reason: 'unrecognized-vite-shape',
+        file: configPath,
+        plugin: stubPath
+      };
+    }
   } else {
-    return { patched: false, reason: 'unrecognized-vite-shape', file: configPath };
+    const gracefulBlock = `// Crank Vite plugin — graceful load (same pattern as Vizpatch)
+let crank = null;
+try {
+  crank = require('${relStub}').crank;
+} catch {}
+
+`;
+    if (!/vite-plugin\.cjs/.test(source)) {
+      source = gracefulBlock + source;
+    }
+    if (/plugins\s*:\s*\[\s*\]/.test(source)) {
+      source = source.replace(
+        /plugins\s*:\s*\[\s*\]/,
+        'plugins: [...(crank ? [crank()] : [])]'
+      );
+    } else if (/plugins\s*:\s*\[/.test(source)) {
+      source = source.replace(
+        /plugins\s*:\s*\[/,
+        'plugins: [...(crank ? [crank()] : []), '
+      );
+    } else if (/module\.exports\s*=\s*\{/.test(source)) {
+      source = source.replace(
+        /module\.exports\s*=\s*\{/,
+        'module.exports = {\n  plugins: [...(crank ? [crank()] : [])],'
+      );
+    } else {
+      return {
+        patched: false,
+        reason: 'unrecognized-vite-shape',
+        file: configPath,
+        plugin: stubPath
+      };
+    }
   }
 
   fs.writeFileSync(configPath, source);
-  return { patched: true, file: configPath, plugin: localPlugin };
+  return { patched: true, file: configPath, plugin: stubPath };
 }
 
 function writeProjectEnvExample(projectRoot) {
@@ -278,7 +433,7 @@ function mergeUserCursorMcp(projectRoot, results) {
 }
 
 /**
- * Retune-style: add crank to devDependencies so `npx crank` works with no path.
+ * Retune-style: add @ahmednawaz/crank to devDependencies (scoped — works with pnpm).
  */
 function ensureCrankDependency(projectRoot, results) {
   const pkgPath = path.join(projectRoot, 'package.json');
@@ -293,20 +448,28 @@ function ensureCrankDependency(projectRoot, results) {
   const crankPkg = readJson(path.join(PACKAGE_ROOT, 'package.json'), {});
   pkg.devDependencies = pkg.devDependencies || {};
 
-  let spec;
+  const scoped = '@ahmednawaz/crank';
+  let versionSpec;
   if (process.env.CRANK_NPM_SPEC) {
-    spec = process.env.CRANK_NPM_SPEC;
+    versionSpec = process.env.CRANK_NPM_SPEC;
   } else {
-    spec = `@ahmednawaz/crank@^${crankPkg.version || '0.1.0'}`;
+    versionSpec = `^${crankPkg.version || '0.2.0'}`;
   }
 
-  if (pkg.devDependencies.crank === spec) {
+  const prev = pkg.devDependencies[scoped];
+  const hadLegacyAlias = Boolean(pkg.devDependencies.crank);
+  pkg.devDependencies[scoped] = versionSpec;
+  if (hadLegacyAlias) {
+    delete pkg.devDependencies.crank;
+  }
+
+  if (prev === versionSpec && !hadLegacyAlias) {
     return;
   }
-  pkg.devDependencies.crank = spec;
+
   writeJson(pkgPath, pkg);
-  results.wrote.push('package.json#devDependencies.crank');
-  results.crankDependencyAdded = spec;
+  results.wrote.push(`package.json#devDependencies.${scoped}`);
+  results.crankDependencyAdded = `${scoped}@${versionSpec}`;
 }
 
 function writeConfig(projectRoot, env) {
@@ -327,7 +490,11 @@ function writeConfig(projectRoot, env) {
     createdAt: new Date().toISOString(),
     environment: {
       isReplit: env.isReplit,
-      hasVite: env.hasVite
+      hasVite: env.hasVite,
+      viteConfig: env.viteConfig || null,
+      hasReact: env.hasReact,
+      hasNext: env.hasNext,
+      hasWebpack: env.hasWebpack
     }
   };
   writeJson(configPath, config);
@@ -370,14 +537,26 @@ function initProject(projectRoot, options = {}) {
     installCrankSkill(projectRoot, results);
   }
 
-  if (env.hasVite && options.vite !== false) {
+  // Retune-style: React apps mount <Crank /> — do not rely on Vite plugin path hacks.
+  if (env.hasReact && options.react !== false) {
+    writeReactMountHint(projectRoot, env, results);
+  } else if (env.hasVite && options.vite !== false) {
     const viteResult = patchViteConfig(projectRoot);
     results.vite = viteResult;
     if (viteResult.patched) {
       results.wrote.push(path.relative(projectRoot, viteResult.file));
     }
+    if (viteResult.plugin) {
+      results.wrote.push(path.relative(projectRoot, viteResult.plugin));
+    }
+  } else if (options.vite !== false) {
+    const stub = writeVitePluginStub(projectRoot);
+    results.vite = { patched: false, reason: 'no-vite-detected', plugin: stub };
+    results.wrote.push(path.relative(projectRoot, stub));
   }
 
+  writeInjectionGuide(projectRoot, env, results);
+
   // package.json script convenience
   if (env.hasPackageJson && options.scripts !== false) {
     const pkgPath = path.join(projectRoot, 'package.json');
@@ -530,6 +709,117 @@ function copyAgentsDoc(projectRoot, results) {
   }
 }
 
+function writeReactMountHint(projectRoot, env, results) {
+  const hint = path.join(projectRoot, '.crank', 'react-mount.md');
+  fs.mkdirSync(path.dirname(hint), { recursive: true });
+  fs.writeFileSync(
+    hint,
+    [
+      '# Mount Crank (Retune-style)',
+      '',
+      '1. Install (from the app package in a monorepo):',
+      '',
+      '```bash',
+      'pnpm add -D @ahmednawaz/crank',
+      '# or: npm i -D @ahmednawaz/crank',
+      '```',
+      '',
+      '2. Mount once near your app root (e.g. `main.tsx` / `App.tsx`):',
+      '',
+      '```tsx',
+      "import { Crank } from '@ahmednawaz/crank/react'",
+      '',
+      'createRoot(document.getElementById("root")!).render(',
+      '  <>',
+      '    <App />',
+      '    <Crank />',
+      '  </>',
+      ')',
+      '```',
+      '',
+      '3. Keep the companion running:',
+      '',
+      '```bash',
+      'npx @ahmednawaz/crank start',
+      '```',
+      '',
+      'On Replit, set the public companion URL if the preview is not on localhost:',
+      '',
+      '```ts',
+      "window.__CRANK_URL__ = 'https://3344-<your-repl>.replit.dev'",
+      '// or: <Crank companionUrl="https://3344-….replit.dev" />',
+      '// or: VITE_CRANK_URL=https://3344-….replit.dev',
+      '```',
+      '',
+      'No Vite plugin required.',
+      ''
+    ].join('\n')
+  );
+  results.wrote.push('.crank/react-mount.md');
+  results.reactMount = true;
+}
+
+function writeInjectionGuide(projectRoot, env, results) {
+  const guide = path.join(projectRoot, '.crank', 'injection.md');
+  fs.mkdirSync(path.dirname(guide), { recursive: true });
+  const lines = [
+    '# Crank panel injection',
+    '',
+    '## Preferred — React component (Retune pattern)',
+    '',
+    'Crank ships a normal npm React export. Vite bundles it like any other dependency.',
+    '**No Vite plugin. No npx-cache paths.**',
+    '',
+    '```bash',
+    'pnpm add -D @ahmednawaz/crank',
+    '```',
+    '',
+    '```tsx',
+    "import { Crank } from '@ahmednawaz/crank/react'",
+    '',
+    '// main.tsx — mount once',
+    '<App />',
+    '<Crank />',
+    '```',
+    '',
+    'Companion must be running: `npx @ahmednawaz/crank start`',
+    '',
+    'URL resolution (first match):',
+    '1. `window.__CRANK_URL__`',
+    '2. `<Crank companionUrl="…" />` / `url` prop',
+    '3. `VITE_CRANK_URL` / `VITE_CRANK_COMPANION_URL`',
+    '4. `http://localhost:3344`',
+    '',
+    'See `.crank/react-mount.md` when this project has React.',
+    '',
+    '## Next.js',
+    '',
+    '```tsx',
+    "import { Crank } from '@ahmednawaz/crank/next'",
+    '<Crank />',
+    '```',
+    '',
+    '## Non-React Vite (Vue / Svelte / vanilla)',
+    '',
+    'Optional Vite plugin: `import { crank } from "@ahmednawaz/crank/vite"` — only if you are not using React.',
+    '',
+    '## Bookmarklet fallback',
+    '',
+    'Open the companion URL → drag the bookmarklet onto any preview page.',
+    '',
+    '## Detected in this project',
+    '',
+    `- hasReact: ${Boolean(env.hasReact)}`,
+    `- hasVite: ${Boolean(env.hasVite)}`,
+    `- viteConfig: ${env.viteConfig || '(none)'}`,
+    `- hasNext: ${Boolean(env.hasNext)}`,
+    `- hasWebpack: ${Boolean(env.hasWebpack)}`,
+    ''
+  ];
+  fs.writeFileSync(guide, lines.join('\n'));
+  results.wrote.push('.crank/injection.md');
+}
+
 function printSetupNextSteps(env, runtime, results) {
   console.log('');
   console.log('  Setup complete (Retune-style):');
@@ -539,6 +829,16 @@ function printSetupNextSteps(env, runtime, results) {
   if (results?.wrote?.some((w) => String(w).includes('skills'))) {
     console.log('    • Skill crank-apply-changes installed (auto-syncs on start)');
   }
+  if (results?.reactMount || env.hasReact) {
+    console.log('    • React: mount <Crank /> from @ahmednawaz/crank/react (see .crank/react-mount.md)');
+  } else if (results?.vite?.patched) {
+    console.log('    • Vite plugin patched (non-React stack)');
+  } else if (env.hasVite) {
+    console.log('    • Vite detected — see .crank/injection.md');
+  } else if (env.hasNext) {
+    console.log('    • Next.js — mount <Crank /> from @ahmednawaz/crank/next');
+  }
+  console.log('    • Injection guide: .crank/injection.md');
   if (env.isReplit) {
     console.log('    • Workflow command: npx @ahmednawaz/crank start');
     console.log('    • Add CRANK_TEAM_TOKEN in Secrets (not in the command)');
@@ -591,8 +891,10 @@ function writeReplitGuide(projectRoot, detectEnv, results, runtime) {
       '## Panel in preview',
       '',
       `- Companion: ${companionUrl}`,
-      '- Vite apps: panel auto-loads in the webview.',
-      '- Other stacks: open the companion URL and use the bookmarklet on your preview tab.',
+      '- **React (preferred):** `pnpm add -D @ahmednawaz/crank` then `<Crank />` from `@ahmednawaz/crank/react` (Retune pattern).',
+      '- Set `window.__CRANK_URL__` or `VITE_CRANK_URL` to the public companion URL on Replit.',
+      '- Keep companion Workflow running: `npx @ahmednawaz/crank start`.',
+      '- See `.crank/react-mount.md` and `.crank/injection.md`.',
       ''
     ].join('\n')
   );
@@ -608,5 +910,11 @@ module.exports = {
   configureMcpRetuneStyle,
   printSetupNextSteps,
   writeReplitGuide,
-  patchReplitConfig
+  writeReplitPlatformGuide,
+  writeVitePluginStub,
+  patchViteConfig,
+  writeInjectionGuide,
+  writeReactMountHint,
+  patchReplitConfig,
+  copyAgentsDoc
 };

package/lib/loader-url.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Shared companion loader URL for Vite / React / Next / webpack adapters.
+ * All paths inject the same /dev-loader.js → bookmarklet panel (not a React UI tree).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { env } = require('./env');
+const { readRuntimeManifest } = require('./urls');
+
+function findProjectRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, '.crank', 'runtime.json'))) {
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(startDir || process.cwd());
+}
+
+function resolveCompanionLoaderUrl(options = {}) {
+  if (options.src) {
+    return String(options.src);
+  }
+
+  const projectRoot = options.projectRoot || findProjectRoot(process.cwd());
+  const runtime = readRuntimeManifest(projectRoot);
+  if (runtime?.companion?.devLoader) {
+    return runtime.companion.devLoader;
+  }
+
+  const publicUrl = (
+    options.companionUrl ||
+    env('PUBLIC_URL', '') ||
+    ''
+  ).replace(/\/$/, '');
+
+  const port = String(options.port || env('PORT', '3344')).replace(/[^0-9]/g, '') || '3344';
+  const host = options.host || env('HOST', '127.0.0.1');
+  const base = publicUrl || `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
+  return `${base}/dev-loader.js`;
+}
+
+module.exports = {
+  findProjectRoot,
+  resolveCompanionLoaderUrl
+};

package/next.js

@@ -0,0 +1,53 @@
+'use strict';
+
+/**
+ * CJS Next adapter — prefer ESM `next.mjs` via package exports.
+ */
+
+const {
+  Crank: CrankEffect,
+  resolveCrankLoaderSrc,
+  resolveCrankCompanionUrl
+} = require('./react.js');
+
+function getReact() {
+  try {
+    return require('react');
+  } catch {
+    throw new Error('@ahmednawaz/crank/next requires react');
+  }
+}
+
+function Crank(props) {
+  const React = getReact();
+  props = props || {};
+  const src = resolveCrankLoaderSrc(props);
+  const strategy = props.strategy || 'afterInteractive';
+
+  let Script = null;
+  try {
+    const mod = require('next/script');
+    Script = mod.default || mod;
+  } catch {
+    Script = null;
+  }
+
+  if (Script) {
+    return React.createElement(Script, {
+      src: src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now(),
+      strategy,
+      'data-crank-loader': '1'
+    });
+  }
+
+  return React.createElement(CrankEffect, props);
+}
+
+module.exports = {
+  Crank,
+  CrankScript: Crank,
+  CrankLoader: Crank,
+  resolveCrankLoaderSrc,
+  resolveCrankCompanionUrl,
+  default: Crank
+};

package/next.mjs

@@ -0,0 +1,17 @@
+/**
+ * Next.js entry — same Retune-style `<Crank />` (client component).
+ *
+ *   import { Crank } from '@ahmednawaz/crank/next'
+ *   <Crank />
+ */
+
+'use client';
+
+export {
+  Crank,
+  CrankLoader,
+  resolveCrankCompanionUrl,
+  resolveCrankLoaderSrc
+} from './react.mjs';
+
+export { Crank as CrankScript, Crank as default } from './react.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Internal Motive UX copy iteration: select UI text → Glean variants → MCP apply. Cursor, Replit, Claude.",
   "repository": {
     "type": "git",
@@ -10,12 +10,47 @@
   "bin": {
     "crank": "bin/crank.js"
   },
-  "main": "vite.js",
+  "main": "./react.js",
+  "module": "./react.mjs",
+  "types": "./react.d.ts",
   "exports": {
-    ".": "./vite.js",
+    ".": {
+      "types": "./react.d.ts",
+      "import": "./react.mjs",
+      "require": "./react.js",
+      "default": "./react.mjs"
+    },
+    "./react": {
+      "types": "./react.d.ts",
+      "import": "./react.mjs",
+      "require": "./react.js",
+      "default": "./react.mjs"
+    },
+    "./next": {
+      "import": "./next.mjs",
+      "require": "./next.js",
+      "default": "./next.mjs"
+    },
     "./vite": "./vite.js",
+    "./webpack": "./webpack.js",
     "./package.json": "./package.json"
   },
+  "peerDependencies": {
+    "html-webpack-plugin": ">=5",
+    "next": ">=13",
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "html-webpack-plugin": {
+      "optional": true
+    }
+  },
   "workspaces": [
     "companion",
     "mcp-server"
@@ -57,6 +92,12 @@
     "skill",
     "panel",
     "vite.js",
+    "react.js",
+    "react.mjs",
+    "react.d.ts",
+    "next.js",
+    "next.mjs",
+    "webpack.js",
     ".env.example",
     "AGENTS.md",
     "REPLIT.md",
@@ -71,6 +112,7 @@
     "glean",
     "mcp",
     "copy",
-    "ux-writing"
+    "ux-writing",
+    "react"
   ]
 }

package/react.d.ts

@@ -0,0 +1,35 @@
+import type { ReactElement } from 'react';
+
+export interface CrankProps {
+  /** Full loader script URL (overrides companionUrl). */
+  src?: string;
+  /** Companion base URL, e.g. https://3344-….replit.dev */
+  companionUrl?: string;
+  /** Alias for companionUrl. */
+  url?: string;
+}
+
+export declare function resolveCrankCompanionUrl(props?: CrankProps): string;
+export declare function resolveCrankLoaderSrc(props?: CrankProps): string;
+
+/**
+ * Retune-style mount — injects companion `/dev-loader.js` once. Renders null.
+ *
+ *   import { Crank } from '@ahmednawaz/crank/react'
+ *   <Crank />
+ *
+ * Optional: `window.__CRANK_URL__` or `VITE_CRANK_URL` for Replit public companion host.
+ * Keep companion running: `npx @ahmednawaz/crank start`
+ */
+export declare function Crank(props?: CrankProps): ReactElement | null;
+export declare const CrankLoader: typeof Crank;
+export default Crank;
+
+declare global {
+  interface Window {
+    __CRANK_URL__?: string;
+    __CRANK_LOADER__?: boolean;
+  }
+}
+
+export {};

package/react.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * CJS build of @ahmednawaz/crank/react (browser-safe, no Node/fs).
+ * Vite / modern apps should import the ESM build via package exports "import" condition.
+ */
+
+function getReact() {
+  try {
+    return require('react');
+  } catch {
+    throw new Error(
+      '@ahmednawaz/crank/react requires react as a peer dependency (npm i react / pnpm add react).'
+    );
+  }
+}
+
+function resolveCrankCompanionUrl(props) {
+  props = props || {};
+  if (typeof window !== 'undefined' && window.__CRANK_URL__) {
+    return String(window.__CRANK_URL__).replace(/\/$/, '');
+  }
+  if (props.companionUrl) {
+    return String(props.companionUrl).replace(/\/$/, '');
+  }
+  if (props.url) {
+    return String(props.url).replace(/\/$/, '');
+  }
+  return 'http://localhost:3344';
+}
+
+function resolveCrankLoaderSrc(props) {
+  props = props || {};
+  if (props.src) {
+    return String(props.src);
+  }
+  return `${resolveCrankCompanionUrl(props)}/dev-loader.js`;
+}
+
+function Crank(props) {
+  const React = getReact();
+  props = props || {};
+  const src = resolveCrankLoaderSrc(props);
+
+  React.useEffect(() => {
+    if (typeof document === 'undefined') {
+      return undefined;
+    }
+    if (document.querySelector('script[data-crank-loader="1"]')) {
+      return undefined;
+    }
+    if (window.__CRANK_LOADER__ && document.getElementById('vp-shell')) {
+      return undefined;
+    }
+
+    const script = document.createElement('script');
+    script.src = src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now();
+    script.async = true;
+    script.dataset.crankLoader = '1';
+    document.documentElement.appendChild(script);
+    return undefined;
+  }, [src]);
+
+  return null;
+}
+
+module.exports = {
+  Crank,
+  CrankLoader: Crank,
+  resolveCrankCompanionUrl,
+  resolveCrankLoaderSrc,
+  default: Crank
+};

package/react.mjs

@@ -0,0 +1,93 @@
+/**
+ * Retune-style React entry — browser-only, Vite-bundlable (no Node/fs).
+ *
+ *   // main.tsx
+ *   import { Crank } from '@ahmednawaz/crank/react'
+ *   // or: import { Crank } from '@ahmednawaz/crank'
+ *
+ *   <Crank />
+ *
+ * Mount near your app root. Injects companion `/dev-loader.js` once (same panel as the
+ * optional Vite plugin). Requires the companion process: `npx @ahmednawaz/crank start`
+ *
+ * peerDependency: react >= 17
+ */
+
+import { useEffect } from 'react';
+
+/**
+ * @param {{ companionUrl?: string, url?: string, src?: string }} [props]
+ * @returns {string}
+ */
+export function resolveCrankCompanionUrl(props = {}) {
+  if (typeof window !== 'undefined' && window.__CRANK_URL__) {
+    return String(window.__CRANK_URL__).replace(/\/$/, '');
+  }
+  if (props.companionUrl) {
+    return String(props.companionUrl).replace(/\/$/, '');
+  }
+  if (props.url) {
+    return String(props.url).replace(/\/$/, '');
+  }
+  try {
+    const envUrl =
+      typeof import.meta !== 'undefined' &&
+      import.meta.env &&
+      (import.meta.env.VITE_CRANK_URL || import.meta.env.VITE_CRANK_COMPANION_URL);
+    if (envUrl) {
+      return String(envUrl).replace(/\/$/, '');
+    }
+  } catch {
+    // ignore
+  }
+  return 'http://localhost:3344';
+}
+
+/**
+ * @param {{ companionUrl?: string, url?: string, src?: string }} [props]
+ * @returns {string}
+ */
+export function resolveCrankLoaderSrc(props = {}) {
+  if (props.src) {
+    return String(props.src);
+  }
+  return `${resolveCrankCompanionUrl(props)}/dev-loader.js`;
+}
+
+/**
+ * Retune-style one-liner. Renders null; injects the companion loader script on the client.
+ *
+ * Do not set window.__CRANK_LOADER__ here — `/dev-loader.js` owns that flag and loads the panel.
+ *
+ * @param {{ companionUrl?: string, url?: string, src?: string }} [props]
+ */
+export function Crank(props = {}) {
+  const src = resolveCrankLoaderSrc(props);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') {
+      return undefined;
+    }
+    if (document.querySelector('script[data-crank-loader="1"]')) {
+      return undefined;
+    }
+    // Panel already live (bookmarklet / prior mount)
+    if (window.__CRANK_LOADER__ && document.getElementById('vp-shell')) {
+      return undefined;
+    }
+
+    const script = document.createElement('script');
+    script.src = src.includes('?') ? src : `${src}?t=${Date.now()}`;
+    script.async = true;
+    script.dataset.crankLoader = '1';
+    document.documentElement.appendChild(script);
+    return undefined;
+  }, [src]);
+
+  return null;
+}
+
+/** Explicit alias. */
+export const CrankLoader = Crank;
+
+export default Crank;

package/skill/SKILL.md

@@ -33,6 +33,7 @@ When the user asks to start Crank:
    ```
    `start` skips setup/init — companion on **3344** (+ HTTP MCP on **3345** on Replit). Add `CRANK_TEAM_TOKEN` in Secrets first.
 4. Call **`crank_get_environment`** after the companion is up.
+5. **Panel (React):** `pnpm add -D @ahmednawaz/crank` then mount `<Crank />` from `@ahmednawaz/crank/react` in `main.tsx` (Retune pattern — no Vite plugin). Keep companion Workflow running. See `.crank/react-mount.md`.
 
 ## When the user says "start Crank" or pastes `npx crank`
 

package/vite.js

@@ -1,53 +1,19 @@
 'use strict';
 
-const fs = require('fs');
-const path = require('path');
-const { env } = require('./lib/env');
-const { readRuntimeManifest } = require('./lib/urls');
-
 /**
  * Vite / Rolldown-vite / Vitest-compatible plugin.
- * Injects Crank into the app during `vite` / `npm run dev` — no bookmarklet needed.
+ * Injects Crank into the app during `vite` / `npm run dev` — no React component needed.
  *
  *   // vite.config.ts
- *   import { crank } from 'crank/vite'
+ *   import { crank } from '@ahmednawaz/crank/vite'
+ *   // or: import { crank } from 'crank/vite'
  *   export default { plugins: [crank()] }
+ *
+ * Prefer this for Vite apps (React, Vue, Svelte, vanilla). The panel is a script overlay,
+ * not a component in your React tree.
  */
 
-function findProjectRoot(startDir) {
-  let dir = path.resolve(startDir || process.cwd());
-  for (let i = 0; i < 8; i++) {
-    if (fs.existsSync(path.join(dir, '.crank', 'runtime.json'))) {
-      return dir;
-    }
-    if (fs.existsSync(path.join(dir, 'package.json'))) {
-      return dir;
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return path.resolve(startDir || process.cwd());
-}
-
-function resolveCompanionLoaderUrl(options = {}) {
-  const projectRoot = options.projectRoot || findProjectRoot(process.cwd());
-  const runtime = readRuntimeManifest(projectRoot);
-  if (runtime?.companion?.devLoader) {
-    return runtime.companion.devLoader;
-  }
-
-  const publicUrl = (
-    options.companionUrl ||
-    env('PUBLIC_URL', '') ||
-    ''
-  ).replace(/\/$/, '');
-
-  const port = String(options.port || env('PORT', '3344')).replace(/[^0-9]/g, '') || '3344';
-  const host = options.host || env('HOST', '127.0.0.1');
-  const base = publicUrl || `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${port}`;
-  return `${base}/dev-loader.js`;
-}
+const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
 
 function crank(options = {}) {
   const src = resolveCompanionLoaderUrl(options);

package/webpack.js

@@ -0,0 +1,58 @@
+'use strict';
+
+/**
+ * Optional webpack adapter — injects /dev-loader.js via html-webpack-plugin.
+ *
+ *   // webpack.config.js
+ *   const { crankWebpackPlugin } = require('@ahmednawaz/crank/webpack')
+ *   plugins: [new HtmlWebpackPlugin(...), crankWebpackPlugin()]
+ *
+ * Prefer @ahmednawaz/crank/vite when the project uses Vite.
+ */
+
+const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
+
+function crankWebpackPlugin(options = {}) {
+  const src = resolveCompanionLoaderUrl(options);
+
+  return {
+    apply(compiler) {
+      compiler.hooks.compilation.tap('CrankWebpackPlugin', (compilation) => {
+        let hooks;
+        try {
+          // eslint-disable-next-line import/no-extraneous-dependencies
+          const HtmlWebpackPlugin = require('html-webpack-plugin');
+          hooks = HtmlWebpackPlugin.getHooks(compilation);
+        } catch {
+          compilation.errors.push(
+            new Error(
+              '@ahmednawaz/crank/webpack requires html-webpack-plugin. Prefer the Vite plugin when possible.'
+            )
+          );
+          return;
+        }
+
+        hooks.alterAssetTagGroups.tap('CrankWebpackPlugin', (data) => {
+          const already = (data.headTags || []).some(
+            (t) =>
+              t.tagName === 'script' &&
+              String(t.attributes?.src || '').includes('dev-loader.js')
+          );
+          if (!already) {
+            data.headTags.push({
+              tagName: 'script',
+              voidTag: false,
+              attributes: { src, defer: true, 'data-crank-loader': '1' }
+            });
+          }
+          return data;
+        });
+      });
+    }
+  };
+}
+
+module.exports = {
+  crankWebpackPlugin,
+  resolveCompanionLoaderUrl
+};