@ahmednawaz/crank 0.1.8 → 0.1.9

package/AGENTS.md

@@ -103,6 +103,23 @@ See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
 
 ---
 
+## Panel injection (Vite vs React)
+
+Crank’s panel is a **script overlay** (`/dev-loader.js` → bookmarklet), **not** a Retune-style React component in the app tree.
+
+| Stack | What to do |
+|-------|------------|
+| **Vite** (React/Vue/Svelte/vanilla) | **Prefer** Vite plugin. `setup` writes `.crank/vite-plugin.cjs` and patches `vite.config` with Vizpatch-style graceful load (works when `pnpm add` fails — uses `packageRoot` from `.crank/config.json`). |
+| **Next.js** | Optional: `import { CrankScript } from '@ahmednawaz/crank/next'` |
+| **React without Vite** | Optional: `import { CrankLoader } from '@ahmednawaz/crank/react'` — injects the same script only |
+| **Any** | Bookmarklet from companion URL |
+
+**Agents must not** invent a fake in-tree `<Crank />` panel UI. If `hasVite: false` but a `vite.config.*` exists nearby, re-run setup from the app root or check `environment.viteConfig` from `doctor`.
+
+Keep companion up via Workflow: `npx @ahmednawaz/crank start`. See `.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,20 @@ 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 (Vite first)
+
+The panel is a **script overlay**, not a Retune-style React component.
+
+| Stack | Integration |
+|-------|-------------|
+| **Vite** | `setup` patches `vite.config` with Vizpatch-style graceful load via `.crank/vite-plugin.cjs` (resolves from `packageRoot` / npx cache when `pnpm add` fails) |
+| **Next.js** | `import { CrankScript } from '@ahmednawaz/crank/next'` |
+| **React (no Vite)** | `import { CrankLoader } from '@ahmednawaz/crank/react'` — script injector only |
+| **Webpack** | `crankWebpackPlugin()` from `@ahmednawaz/crank/webpack` |
+| **Fallback** | Companion bookmarklet |
+
+Keep companion running (`npx @ahmednawaz/crank start`). See `.crank/injection.md` after setup.
+
 Useful variants:
 
 ```bash

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) {
@@ -327,7 +482,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);
@@ -376,8 +535,18 @@ function initProject(projectRoot, options = {}) {
     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) {
+    // Still write stub so agents can wire the graceful load manually.
+    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 +699,94 @@ function copyAgentsDoc(projectRoot, results) {
   }
 }
 
+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',
+    '',
+    'Crank’s panel is a **script overlay** (companion `/dev-loader.js` → bookmarklet).',
+    'It is **not** a Retune-style React UI component living in your component tree.',
+    '',
+    '## Prefer Vite plugin (default)',
+    '',
+    'For Vite apps (React, Vue, Svelte, vanilla):',
+    '',
+    '1. Run `npx @ahmednawaz/crank setup` (writes `.crank/vite-plugin.cjs` + patches `vite.config`).',
+    '2. Keep a **Workflow** running: `npx @ahmednawaz/crank start` (companion on **3344**).',
+    '3. Dev server loads the panel automatically via the Vite plugin.',
+    '',
+    'Graceful load (Vizpatch-style) — works even when `pnpm add @ahmednawaz/crank` fails:',
+    '',
+    '```ts',
+    "import { createRequire } from 'node:module'",
+    "import { existsSync } from 'node:fs'",
+    "import { fileURLToPath } from 'node:url'",
+    '',
+    'let crank = null',
+    'try {',
+    "  const pluginPath = fileURLToPath(new URL('./.crank/vite-plugin.cjs', import.meta.url))",
+    '  if (existsSync(pluginPath)) {',
+    '    const require = createRequire(import.meta.url)',
+    '    crank = require(pluginPath).crank',
+    '  }',
+    '} catch {}',
+    '',
+    'export default defineConfig({',
+    '  plugins: [',
+    '    ...(crank ? [crank()] : []),',
+    '    // ...your plugins',
+    '  ],',
+    '})',
+    '```',
+    '',
+    '`.crank/vite-plugin.cjs` resolves Crank from `config.json` → `packageRoot` (npx cache),',
+    'then `node_modules`, and noops if missing.',
+    '',
+    '## React adapter (non-Vite React only)',
+    '',
+    'Use only when there is **no** Vite config (CRA / custom webpack React):',
+    '',
+    '```tsx',
+    "import { CrankLoader } from '@ahmednawaz/crank/react'",
+    '// client root only — injects the same /dev-loader.js script',
+    '<CrankLoader />',
+    '```',
+    '',
+    'Do **not** invent a fake in-tree `<Crank />` panel UI. `CrankLoader` / `Crank` only inject a script.',
+    '',
+    '## Next.js',
+    '',
+    '```tsx',
+    "import { CrankScript } from '@ahmednawaz/crank/next'",
+    '// app/layout.tsx or pages/_app',
+    '<CrankScript />',
+    '```',
+    '',
+    '## Webpack',
+    '',
+    '```js',
+    "const { crankWebpackPlugin } = require('@ahmednawaz/crank/webpack')",
+    'plugins: [new HtmlWebpackPlugin(...), crankWebpackPlugin()]',
+    '```',
+    '',
+    '## Bookmarklet fallback',
+    '',
+    'Open the companion URL → drag the bookmarklet onto any preview page.',
+    '',
+    '## Detected in this project',
+    '',
+    `- hasVite: ${Boolean(env.hasVite)}`,
+    `- viteConfig: ${env.viteConfig || '(none)'}`,
+    `- hasReact: ${Boolean(env.hasReact)}`,
+    `- 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 +796,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?.vite?.patched) {
+    console.log('    • Vite plugin patched (graceful load via .crank/vite-plugin.cjs)');
+  } else if (env.hasVite) {
+    console.log('    • Vite detected — see .crank/injection.md if the panel does not auto-load');
+  } else if (env.hasNext) {
+    console.log('    • Next.js — add <CrankScript /> from @ahmednawaz/crank/next (see .crank/injection.md)');
+  } else if (env.hasReact) {
+    console.log('    • React without Vite — add <CrankLoader /> from @ahmednawaz/crank/react (see .crank/injection.md)');
+  }
+  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 +858,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.',
+      '- **Vite:** panel auto-loads via `.crank/vite-plugin.cjs` (graceful load). Keep companion Workflow running.',
+      '- **React/Next without Vite:** see `.crank/injection.md` (`CrankLoader` / `CrankScript`).',
+      '- **Fallback:** open the companion URL and use the bookmarklet on your preview tab.',
+      '- Full guide: `.crank/injection.md`',
       ''
     ].join('\n')
   );
@@ -608,5 +877,10 @@ module.exports = {
   configureMcpRetuneStyle,
   printSetupNextSteps,
   writeReplitGuide,
-  patchReplitConfig
+  writeReplitPlatformGuide,
+  writeVitePluginStub,
+  patchViteConfig,
+  writeInjectionGuide,
+  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,63 @@
+'use strict';
+
+/**
+ * Optional Next.js adapter — injects Crank via next/script (App Router or Pages).
+ *
+ * Prefer Vite plugin for Vite apps. Use this for Next.js when there is no vite.config.
+ *
+ *   // app/layout.tsx (or a client layout section)
+ *   import { CrankScript } from '@ahmednawaz/crank/next'
+ *   <CrankScript />
+ *
+ * peerDependencies: react, next
+ */
+
+const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
+const { CrankLoader } = require('./react');
+
+function getReact() {
+  try {
+    return require('react');
+  } catch {
+    throw new Error(
+      '@ahmednawaz/crank/next requires react. Prefer @ahmednawaz/crank/vite for Vite apps.'
+    );
+  }
+}
+
+function getNextScript() {
+  try {
+    return require('next/script');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ src?: string, companionUrl?: string, strategy?: string }} props
+ */
+function CrankScript(props) {
+  const React = getReact();
+  const NextScript = getNextScript();
+  const src = resolveCompanionLoaderUrl(props || {});
+  const strategy = (props && props.strategy) || 'afterInteractive';
+
+  if (NextScript) {
+    const Script = NextScript.default || NextScript;
+    return React.createElement(Script, {
+      src,
+      strategy,
+      'data-crank-loader': '1'
+    });
+  }
+
+  // Fallback when next/script is unavailable (tests / non-Next bundlers).
+  return React.createElement(CrankLoader, props || {});
+}
+
+module.exports = {
+  CrankScript,
+  CrankLoader,
+  Crank: CrankScript,
+  resolveCompanionLoaderUrl
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Internal Motive UX copy iteration: select UI text → Glean variants → MCP apply. Cursor, Replit, Claude.",
   "repository": {
     "type": "git",
@@ -14,8 +14,21 @@
   "exports": {
     ".": "./vite.js",
     "./vite": "./vite.js",
+    "./react": "./react.js",
+    "./next": "./next.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 +70,9 @@
     "skill",
     "panel",
     "vite.js",
+    "react.js",
+    "next.js",
+    "webpack.js",
     ".env.example",
     "AGENTS.md",
     "REPLIT.md",

package/react.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Optional React adapter for non-Vite React apps (CRA, custom webpack, etc.).
+ *
+ * This is NOT a Retune-style UI component. It only injects the same /dev-loader.js
+ * script the Vite plugin uses. Prefer `@ahmednawaz/crank/vite` when the app uses Vite.
+ *
+ *   import { CrankLoader } from '@ahmednawaz/crank/react'
+ *   // in App / root layout (client-only):
+ *   <CrankLoader />
+ *
+ * peerDependency: react >= 17
+ */
+
+const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
+
+function getReact() {
+  try {
+    // eslint-disable-next-line import/no-extraneous-dependencies
+    return require('react');
+  } catch {
+    throw new Error(
+      '@ahmednawaz/crank/react requires react as a peer dependency. Prefer the Vite plugin when possible: import { crank } from "@ahmednawaz/crank/vite".'
+    );
+  }
+}
+
+/**
+ * Injects Crank's companion loader once on the client. Renders null.
+ * @param {{ src?: string, companionUrl?: string, port?: string|number, host?: string }} props
+ */
+function CrankLoader(props) {
+  const React = getReact();
+  const src = resolveCompanionLoaderUrl(props || {});
+
+  React.useEffect(() => {
+    if (typeof document === 'undefined') {
+      return undefined;
+    }
+    if (window.__CRANK_LOADER__) {
+      return undefined;
+    }
+    window.__CRANK_LOADER__ = true;
+
+    const existing = document.querySelector('script[data-crank-loader="1"]');
+    if (existing) {
+      return undefined;
+    }
+
+    const script = document.createElement('script');
+    script.src = src;
+    script.defer = true;
+    script.dataset.crankLoader = '1';
+    document.documentElement.appendChild(script);
+    return undefined;
+  }, [src]);
+
+  return null;
+}
+
+/** Alias — still only a script injector, not an in-tree panel UI. */
+const Crank = CrankLoader;
+
+module.exports = {
+  CrankLoader,
+  Crank,
+  resolveCompanionLoaderUrl
+};

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 injection:** Vite apps use the Vite plugin (graceful `.crank/vite-plugin.cjs`) — not a React component. See **AGENTS.md** / `.crank/injection.md`. Keep companion running in a Workflow.
 
 ## 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
+};