@ahmednawaz/crank 0.1.9 → 0.2.2

package/AGENTS.md

@@ -103,20 +103,32 @@ See **[REPLIT.md](./REPLIT.md)** and `.crank/replit.md` (URLs after first run).
 
 ---
 
-## Panel injection (Vite vs React)
+## Panel injection (Retune pattern)
 
-Crank’s panel is a **script overlay** (`/dev-loader.js` → bookmarklet), **not** a Retune-style React component in the app tree.
+**Preferred** — CLI inject (no manual edits):
 
-| 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 |
+```bash
+npx @ahmednawaz/crank@latest setup
+npx @ahmednawaz/crank inject
+npx @ahmednawaz/crank start
+```
+
+`inject` finds `main.tsx` / `createRoot` / `ReactDOM.render`, adds:
+
+```tsx
+import { Crank } from '@ahmednawaz/crank/react'
+// ...
+<Crank />
+```
 
-**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`.
+Same idea as Sentry/Clerk setup CLIs. See `.crank/react-mount.md` after setup.
 
-Keep companion up via Workflow: `npx @ahmednawaz/crank start`. See `.crank/injection.md` after setup.
+| Stack | Integration |
+|-------|-------------|
+| **React** | `npx @ahmednawaz/crank inject` |
+| **Next.js** | same inject, or `import { Crank } from '@ahmednawaz/crank/next'` |
+| **Non-React Vite** | Optional `@ahmednawaz/crank/vite` plugin |
+| **Fallback** | Companion bookmarklet |
 
 ---
 

package/README.md

@@ -102,19 +102,17 @@ 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)
+### Panel injection (Retune-style)
 
-The panel is a **script overlay**, not a Retune-style React component.
+```bash
+npx @ahmednawaz/crank@latest setup
+npx @ahmednawaz/crank inject    # patches main.tsx — no manual edits
+npx @ahmednawaz/crank start
+```
 
-| 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 |
+`inject` installs the package and adds `import { Crank }` + `<Crank />` (Sentry/Clerk-style).
 
-Keep companion running (`npx @ahmednawaz/crank start`). See `.crank/injection.md` after setup.
+Replit public URL: `window.__CRANK_URL__` or `<Crank companionUrl="https://3344-….replit.dev" />` or `VITE_CRANK_URL`.
 
 Useful variants:
 

package/bin/crank.js

@@ -31,6 +31,7 @@ const {
   readRuntimeManifest
 } = require('../lib/urls');
 const { resolveProjectRoot, describeEnvironment } = require('../lib/resolve-project');
+const { injectCrank } = require('../lib/wire-react');
 
 const LOG_FILE = env('LOG', '/tmp/crank-companion.log');
 const PID_FILE = env('PID_FILE', '/tmp/crank-companion.pid');
@@ -39,11 +40,12 @@ function printHelp() {
   process.stdout.write(`Usage: crank [command] [project-root]
 
 Commands:
-  (default)     Init + start everything (companion, MCP, dev server when present)
-  setup         Same as init — Retune-style one-time config (alias for init)
-  init          Only write IDE / Vite / MCP setup into the project
-  mcp           Start stdio MCP server (used by npx crank mcp in IDE configs)
-  start         Start companion (assumes init already done)
+  (default)     Init + start companion (and npm run dev when present)
+  setup         One-time config (MCP, skill, package.json) — alias for init
+  init          Same as setup
+  inject        Patch main.tsx / entry with import { Crank } + <Crank /> (Retune-style)
+  mcp           Start stdio MCP server (used by IDE MCP configs)
+  start         Start companion (assumes setup already done)
   stop          Stop daemon companion + HTTP MCP listeners
   doctor        Print detected environment + runtime URLs
   status        Print whether companion /health responds
@@ -60,11 +62,16 @@ Flags:
   --http-mcp    Force HTTP MCP (Replit auto-enables this)
   -h, --help    Show help
 
+First run (React / Retune-style):
+  npx @ahmednawaz/crank@latest setup
+  npx @ahmednawaz/crank inject
+  npx @ahmednawaz/crank start
+
 Examples:
-  cd ~/code/my-app && npx crank setup && npx crank
-  npx crank
-  npx crank mcp
-  npx crank stop
+  cd ~/code/my-app && npx @ahmednawaz/crank setup && npx @ahmednawaz/crank inject
+  npx @ahmednawaz/crank
+  npx @ahmednawaz/crank mcp
+  npx @ahmednawaz/crank stop
 `);
 }
 
@@ -113,7 +120,7 @@ function parseArgs(argv) {
   }
   let command = 'run';
   let projectRoot = process.cwd();
-  const cmds = new Set(['init', 'setup', 'start', 'doctor', 'stop', 'status', 'mcp']);
+  const cmds = new Set(['init', 'setup', 'start', 'doctor', 'stop', 'status', 'mcp', 'inject']);
   if (positional[0] === 'setup') {
     command = 'init';
   } else if (cmds.has(positional[0])) {
@@ -617,6 +624,37 @@ async function main() {
     return;
   }
 
+  if (command === 'inject') {
+    if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
+      console.error(`Project root not found: ${projectRoot}`);
+      process.exit(1);
+    }
+    console.log(`[Crank] Injecting <Crank /> into ${projectRoot}`);
+    const result = injectCrank(projectRoot, { install: true });
+    if (result.installed) {
+      console.log(`[Crank] Installed package (${result.installCommand})`);
+    } else if (result.installError) {
+      console.warn(`[Crank] Package install warning: ${result.installError}`);
+      console.warn('[Crank] Try: pnpm add -D @ahmednawaz/crank');
+    }
+    if (result.reactWire?.wired) {
+      console.log(`[Crank] Patched ${result.reactWire.file}`);
+      console.log('[Crank] Added: import { Crank } from \'@ahmednawaz/crank/react\' + <Crank />');
+      console.log('[Crank] Next: npx @ahmednawaz/crank start');
+      process.exit(0);
+    }
+    if (result.reactWire?.reason === 'already-present') {
+      console.log(`[Crank] Already injected in ${result.reactWire.file}`);
+      process.exit(0);
+    }
+    console.error(
+      `[Crank] Could not inject (${result.reactWire?.reason || 'unknown'}).` +
+        (result.reactWire?.file ? ` Looked at ${result.reactWire.file}.` : '') +
+        ' Add manually:\n\n  import { Crank } from \'@ahmednawaz/crank/react\'\n  <Crank />\n'
+    );
+    process.exit(1);
+  }
+
   if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory()) {
     console.error(`Project root not found: ${projectRoot}`);
     process.exit(1);

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/init.js

@@ -12,6 +12,7 @@ const {
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const { resolveUrls } = require('./urls');
+const { installCrankPackage } = require('./wire-react');
 
 function ensureGitignore(projectRoot) {
   const file = path.join(projectRoot, '.gitignore');
@@ -433,7 +434,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');
@@ -448,20 +449,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) {
@@ -519,9 +528,7 @@ function initProject(projectRoot, options = {}) {
 
   // MCP + skill (Retune-style: global IDE config, automatic skill sync)
   if (options.mcp !== false) {
-    if (!env.isReplit) {
-      ensureCrankDependency(projectRoot, results);
-    }
+    ensureCrankDependency(projectRoot, results);
     configureMcpRetuneStyle(env, projectRoot, results, options);
   }
 
@@ -529,7 +536,11 @@ function initProject(projectRoot, options = {}) {
     installCrankSkill(projectRoot, results);
   }
 
-  if (env.hasVite && options.vite !== false) {
+  // React apps: install dep + write out inject (Sentry/Clerk-style). Do not patch source here.
+  if (env.hasReact && options.react !== false) {
+    writeReactMountHint(projectRoot, env, results);
+    results.reactMount = true;
+  } else if (env.hasVite && options.vite !== false) {
     const viteResult = patchViteConfig(projectRoot);
     results.vite = viteResult;
     if (viteResult.patched) {
@@ -539,7 +550,6 @@ function initProject(projectRoot, options = {}) {
       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));
@@ -553,7 +563,7 @@ function initProject(projectRoot, options = {}) {
     const pkg = readJson(pkgPath, {});
     pkg.scripts = pkg.scripts || {};
     if (!pkg.scripts.crank) {
-      pkg.scripts.crank = 'crank';
+      pkg.scripts.crank = 'npx @ahmednawaz/crank';
       writeJson(pkgPath, pkg);
       results.wrote.push('package.json#scripts.crank');
     }
@@ -563,14 +573,9 @@ function initProject(projectRoot, options = {}) {
     writeReplitPlatformGuide(projectRoot, results);
   }
 
-  if (results.crankDependencyAdded && options.install !== false && !env.isReplit) {
-    try {
-      const { execSync } = require('child_process');
-      execSync('npm install', { cwd: projectRoot, stdio: 'inherit' });
-      results.installed = true;
-    } catch (err) {
-      results.installError = err.message;
-    }
+  if (options.install !== false && results.crankDependencyAdded) {
+    const install = installCrankPackage(projectRoot);
+    Object.assign(results, install);
   }
 
   return results;
@@ -699,76 +704,90 @@ 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)',
+      '',
+      'Run (preferred — no manual edits):',
+      '',
+      '```bash',
+      'npx @ahmednawaz/crank inject',
+      '```',
+      '',
+      'That installs `@ahmednawaz/crank` and patches your entry file with:',
+      '',
+      '```tsx',
+      "import { Crank } from '@ahmednawaz/crank/react'",
+      '',
+      '<Crank />',
+      '```',
+      '',
+      'Then start the companion:',
+      '',
+      '```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',
     '',
-    '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)',
+    '## Preferred — `npx @ahmednawaz/crank inject`',
     '',
-    'For Vite apps (React, Vue, Svelte, vanilla):',
+    'Patches your entry file automatically (Sentry/Clerk-style). No manual edits.',
     '',
-    '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',
-    '  ],',
-    '})',
+    '```bash',
+    'npx @ahmednawaz/crank@latest setup',
+    'npx @ahmednawaz/crank inject',
+    'npx @ahmednawaz/crank start',
     '```',
     '',
-    '`.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):',
+    'Adds:',
     '',
     '```tsx',
-    "import { CrankLoader } from '@ahmednawaz/crank/react'",
-    '// client root only — injects the same /dev-loader.js script',
-    '<CrankLoader />',
+    "import { Crank } from '@ahmednawaz/crank/react'",
+    '<Crank />',
     '```',
     '',
-    'Do **not** invent a fake in-tree `<Crank />` panel UI. `CrankLoader` / `Crank` only inject a script.',
+    '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 { CrankScript } from '@ahmednawaz/crank/next'",
-    '// app/layout.tsx or pages/_app',
-    '<CrankScript />',
+    '```bash',
+    'npx @ahmednawaz/crank inject',
     '```',
     '',
-    '## Webpack',
+    '## Non-React Vite (Vue / Svelte / vanilla)',
     '',
-    '```js',
-    "const { crankWebpackPlugin } = require('@ahmednawaz/crank/webpack')",
-    'plugins: [new HtmlWebpackPlugin(...), crankWebpackPlugin()]',
-    '```',
+    'Optional Vite plugin: `import { crank } from "@ahmednawaz/crank/vite"` — only if you are not using React.',
     '',
     '## Bookmarklet fallback',
     '',
@@ -776,9 +795,9 @@ function writeInjectionGuide(projectRoot, env, results) {
     '',
     '## Detected in this project',
     '',
+    `- hasReact: ${Boolean(env.hasReact)}`,
     `- hasVite: ${Boolean(env.hasVite)}`,
     `- viteConfig: ${env.viteConfig || '(none)'}`,
-    `- hasReact: ${Boolean(env.hasReact)}`,
     `- hasNext: ${Boolean(env.hasNext)}`,
     `- hasWebpack: ${Boolean(env.hasWebpack)}`,
     ''
@@ -796,15 +815,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)');
+  if (results?.reactMount || env.hasReact) {
+    console.log('    • Next: npx @ahmednawaz/crank inject   # patches main.tsx with <Crank />');
+  } 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 if the panel does not auto-load');
+    console.log('    • Vite detected — see .crank/injection.md');
   } 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('    • Next.js — run: npx @ahmednawaz/crank inject');
   }
+  console.log('    • Then: npx @ahmednawaz/crank start');
   console.log('    • Injection guide: .crank/injection.md');
   if (env.isReplit) {
     console.log('    • Workflow command: npx @ahmednawaz/crank start');
@@ -858,10 +878,10 @@ function writeReplitGuide(projectRoot, detectEnv, results, runtime) {
       '## Panel in preview',
       '',
       `- Companion: ${companionUrl}`,
-      '- **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`',
+      '- **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')
   );
@@ -881,6 +901,7 @@ module.exports = {
   writeVitePluginStub,
   patchViteConfig,
   writeInjectionGuide,
+  writeReactMountHint,
   patchReplitConfig,
   copyAgentsDoc
 };

package/lib/wire-react.js

@@ -0,0 +1,297 @@
+'use strict';
+
+/**
+ * Auto-wire Retune-style <Crank /> into the app entry file (Sentry/Clerk-style inject).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { exists } = require('./detect');
+
+const ENTRY_CANDIDATES = [
+  'src/main.tsx',
+  'src/main.jsx',
+  'src/main.ts',
+  'src/main.js',
+  'src/index.tsx',
+  'src/index.jsx',
+  'src/index.ts',
+  'src/index.js',
+  'client/src/main.tsx',
+  'client/src/main.jsx',
+  'client/src/index.tsx',
+  'app/main.tsx',
+  'src/App.tsx',
+  'src/App.jsx',
+  'App.tsx',
+  'App.jsx',
+  'main.tsx',
+  'main.jsx',
+  'index.tsx',
+  'index.jsx'
+];
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.turbo',
+  '.cache',
+  '.crank'
+]);
+
+function findEntryByCreateRoot(projectRoot) {
+  const queue = [{ dir: path.resolve(projectRoot), depth: 0 }];
+  const hits = [];
+  while (queue.length) {
+    const { dir, depth } = queue.shift();
+    if (depth > 3) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+          queue.push({ dir: full, depth: depth + 1 });
+        }
+        continue;
+      }
+      if (!/\.(tsx|jsx|ts|js)$/.test(entry.name)) continue;
+      let src;
+      try {
+        src = fs.readFileSync(full, 'utf8');
+      } catch {
+        continue;
+      }
+      if (
+        /createRoot\s*\(/.test(src) ||
+        /ReactDOM\.render\s*\(/.test(src) ||
+        /hydrateRoot\s*\(/.test(src)
+      ) {
+        hits.push(full);
+      }
+    }
+  }
+  // Prefer main/index over App
+  hits.sort((a, b) => {
+    const score = (p) => {
+      const base = path.basename(p).toLowerCase();
+      if (base.startsWith('main')) return 0;
+      if (base.startsWith('index')) return 1;
+      return 2;
+    };
+    return score(a) - score(b);
+  });
+  return hits[0] || null;
+}
+
+function findEntry(projectRoot) {
+  for (const rel of ENTRY_CANDIDATES) {
+    const full = path.join(projectRoot, rel);
+    if (exists(full)) {
+      return full;
+    }
+  }
+  return findEntryByCreateRoot(projectRoot);
+}
+
+function alreadyWired(source) {
+  return (
+    /@ahmednawaz\/crank\/react/.test(source) ||
+    /from ['"]@ahmednawaz\/crank['"]/.test(source) ||
+    /<Crank[\s/>]/.test(source)
+  );
+}
+
+function insertImport(source) {
+  const importLine = `import { Crank } from '@ahmednawaz/crank/react';`;
+  const matches = [...source.matchAll(/^import\s.+;?\s*$/gm)];
+  if (matches.length) {
+    const last = matches[matches.length - 1];
+    const idx = last.index + last[0].length;
+    return source.slice(0, idx) + `\n${importLine}` + source.slice(idx);
+  }
+  return `${importLine}\n${source}`;
+}
+
+function insertCrankJsx(source) {
+  if (/<Crank[\s/>]/.test(source)) {
+    return { source, patched: true };
+  }
+
+  if (/<StrictMode>/.test(source)) {
+    return {
+      source: source.replace(/(<StrictMode>\s*)/, '$1\n    <Crank />\n    '),
+      patched: true
+    };
+  }
+
+  if (/\.render\s*\(\s*<>/.test(source) || /\.render\s*\(\s*<React\.Fragment>/.test(source)) {
+    return {
+      source: source.replace(/(<>\s*|<React\.Fragment>\s*)/, '$1\n    <Crank />\n    '),
+      patched: true
+    };
+  }
+
+  // createRoot(...).render(<App />) or multi-line JSX root
+  if (/\.render\s*\(/.test(source)) {
+    // Single-line: .render(<App />)
+    let next = source.replace(
+      /\.render\s*\(\s*(<(?!>)[^]*?>)\s*\)/m,
+      '.render(\n  <>\n    $1\n    <Crank />\n  </>\n)'
+    );
+    if (next !== source && /<Crank[\s/>]/.test(next)) {
+      return { source: next, patched: true };
+    }
+
+    // Multi-line root starting with <Something
+    next = source.replace(
+      /(\.render\s*\(\s*\n\s*)(<[A-Za-z/])/,
+      '$1<>\n    <Crank />\n    $2'
+    );
+    if (next !== source) {
+      // close fragment before the render's closing paren — best effort
+      next = next.replace(
+        /(\.render\s*\([\s\S]*?)(\n\s*\))/,
+        (match, body, close) => {
+          if (body.includes('<Crank') && !body.includes('</>')) {
+            return `${body}\n  </>${close}`;
+          }
+          return match;
+        }
+      );
+      if (/<Crank[\s/>]/.test(next)) {
+        return { source: next, patched: true };
+      }
+    }
+  }
+
+  if (/ReactDOM\.render\s*\(/.test(source)) {
+    const next = source.replace(
+      /ReactDOM\.render\s*\(\s*(<(?!>)[^]*?>)\s*,/,
+      'ReactDOM.render(\n  <>\n    $1\n    <Crank />\n  </>,'
+    );
+    if (next !== source && /<Crank[\s/>]/.test(next)) {
+      return { source: next, patched: true };
+    }
+  }
+
+  if (/<App\b[^/]*?\/>/.test(source)) {
+    return {
+      source: source.replace(/(<App\b[^/]*?\/>)/, '<Crank />\n      $1'),
+      patched: true
+    };
+  }
+  if (/<App\b[^>]*>/.test(source)) {
+    return {
+      source: source.replace(/(<App\b[^>]*>)/, '<Crank />\n      $1'),
+      patched: true
+    };
+  }
+
+  return { source, patched: false };
+}
+
+/**
+ * Patch the React entry to mount <Crank />. Idempotent.
+ * @returns {{ wired: boolean, reason?: string, file?: string }}
+ */
+function wireReactEntry(projectRoot) {
+  const entryPath = findEntry(projectRoot);
+  if (!entryPath) {
+    return { wired: false, reason: 'no-entry' };
+  }
+
+  let source = fs.readFileSync(entryPath, 'utf8');
+  if (alreadyWired(source)) {
+    return { wired: false, reason: 'already-present', file: entryPath };
+  }
+
+  source = insertImport(source);
+  const { source: next, patched } = insertCrankJsx(source);
+  source = next;
+
+  if (!patched) {
+    return { wired: false, reason: 'unrecognized-entry-shape', file: entryPath };
+  }
+
+  fs.writeFileSync(entryPath, source);
+  return { wired: true, file: entryPath };
+}
+
+function detectInstallCommand(projectRoot) {
+  if (
+    exists(path.join(projectRoot, 'pnpm-lock.yaml')) ||
+    exists(path.join(projectRoot, 'pnpm-workspace.yaml'))
+  ) {
+    return { cmd: 'pnpm', args: ['add', '-D', '@ahmednawaz/crank'] };
+  }
+  if (exists(path.join(projectRoot, 'yarn.lock'))) {
+    return { cmd: 'yarn', args: ['add', '-D', '@ahmednawaz/crank'] };
+  }
+  return { cmd: 'npm', args: ['install', '-D', '@ahmednawaz/crank'] };
+}
+
+function installCrankPackage(projectRoot) {
+  const { execFileSync } = require('child_process');
+  const { cmd, args } = detectInstallCommand(projectRoot);
+  const result = { installed: false, installCommand: `${cmd} ${args.join(' ')}` };
+  try {
+    execFileSync(cmd, args, { cwd: projectRoot, stdio: 'inherit', env: process.env });
+    result.installed = true;
+    return result;
+  } catch (err) {
+    result.installError = err.message;
+  }
+  if (cmd !== 'npm') {
+    try {
+      execFileSync('npm', ['install', '-D', '@ahmednawaz/crank'], {
+        cwd: projectRoot,
+        stdio: 'inherit',
+        env: process.env
+      });
+      result.installed = true;
+      result.installCommand = 'npm install -D @ahmednawaz/crank';
+      delete result.installError;
+    } catch (err2) {
+      result.installError = err2.message;
+    }
+  }
+  return result;
+}
+
+/**
+ * Full inject flow: ensure dep → install → patch entry.
+ */
+function injectCrank(projectRoot, options = {}) {
+  const results = {
+    projectRoot,
+    wrote: []
+  };
+
+  if (options.install !== false) {
+    Object.assign(results, installCrankPackage(projectRoot));
+  }
+
+  const wire = wireReactEntry(projectRoot);
+  results.reactWire = wire;
+  if (wire.wired && wire.file) {
+    results.wrote.push(path.relative(projectRoot, wire.file));
+  }
+  return results;
+}
+
+module.exports = {
+  wireReactEntry,
+  installCrankPackage,
+  injectCrank,
+  findEntry,
+  detectInstallCommand
+};

package/next.js

@@ -1,63 +1,53 @@
 '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
+ * CJS Next adapter — prefer ESM `next.mjs` via package exports.
  */
 
-const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
-const { CrankLoader } = require('./react');
+const {
+  Crank: CrankEffect,
+  resolveCrankLoaderSrc,
+  resolveCrankCompanionUrl
+} = require('./react.js');
 
 function getReact() {
   try {
     return require('react');
   } catch {
-    throw new Error(
-      '@ahmednawaz/crank/next requires react. Prefer @ahmednawaz/crank/vite for Vite apps.'
-    );
+    throw new Error('@ahmednawaz/crank/next requires react');
   }
 }
 
-function getNextScript() {
+function Crank(props) {
+  const React = getReact();
+  props = props || {};
+  const src = resolveCrankLoaderSrc(props);
+  const strategy = props.strategy || 'afterInteractive';
+
+  let Script = null;
   try {
-    return require('next/script');
+    const mod = require('next/script');
+    Script = mod.default || mod;
   } catch {
-    return null;
+    Script = 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;
+  if (Script) {
     return React.createElement(Script, {
-      src,
+      src: src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now(),
       strategy,
       'data-crank-loader': '1'
     });
   }
 
-  // Fallback when next/script is unavailable (tests / non-Next bundlers).
-  return React.createElement(CrankLoader, props || {});
+  return React.createElement(CrankEffect, props);
 }
 
 module.exports = {
-  CrankScript,
-  CrankLoader,
-  Crank: CrankScript,
-  resolveCompanionLoaderUrl
+  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.9",
+  "version": "0.2.2",
   "description": "Internal Motive UX copy iteration: select UI text → Glean variants → MCP apply. Cursor, Replit, Claude.",
   "repository": {
     "type": "git",
@@ -10,12 +10,28 @@
   "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",
-    "./react": "./react.js",
-    "./next": "./next.js",
     "./webpack": "./webpack.js",
     "./package.json": "./package.json"
   },
@@ -25,9 +41,15 @@
     "react": ">=17"
   },
   "peerDependenciesMeta": {
-    "react": { "optional": true },
-    "next": { "optional": true },
-    "html-webpack-plugin": { "optional": true }
+    "react": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
+    "html-webpack-plugin": {
+      "optional": true
+    }
   },
   "workspaces": [
     "companion",
@@ -71,7 +93,10 @@
     "panel",
     "vite.js",
     "react.js",
+    "react.mjs",
+    "react.d.ts",
     "next.js",
+    "next.mjs",
     "webpack.js",
     ".env.example",
     "AGENTS.md",
@@ -87,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

@@ -1,56 +1,61 @@
 '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
+ * CJS build of @ahmednawaz/crank/react (browser-safe, no Node/fs).
+ * Vite / modern apps should import the ESM build via package exports "import" condition.
  */
 
-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".'
+      '@ahmednawaz/crank/react requires react as a peer dependency (npm i react / pnpm add react).'
     );
   }
 }
 
-/**
- * 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) {
+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();
-  const src = resolveCompanionLoaderUrl(props || {});
+  props = props || {};
+  const src = resolveCrankLoaderSrc(props);
 
   React.useEffect(() => {
     if (typeof document === 'undefined') {
       return undefined;
     }
-    if (window.__CRANK_LOADER__) {
+    if (document.querySelector('script[data-crank-loader="1"]')) {
       return undefined;
     }
-    window.__CRANK_LOADER__ = true;
-
-    const existing = document.querySelector('script[data-crank-loader="1"]');
-    if (existing) {
+    if (window.__CRANK_LOADER__ && document.getElementById('vp-shell')) {
       return undefined;
     }
 
     const script = document.createElement('script');
-    script.src = src;
-    script.defer = true;
+    script.src = src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now();
+    script.async = true;
     script.dataset.crankLoader = '1';
     document.documentElement.appendChild(script);
     return undefined;
@@ -59,11 +64,10 @@ function CrankLoader(props) {
   return null;
 }
 
-/** Alias — still only a script injector, not an in-tree panel UI. */
-const Crank = CrankLoader;
-
 module.exports = {
-  CrankLoader,
   Crank,
-  resolveCompanionLoaderUrl
+  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,7 +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.
+5. **Panel:** `npx @ahmednawaz/crank inject` patches `main.tsx` with `<Crank />` (no manual edits). Then keep companion Workflow running with `npx @ahmednawaz/crank start`.
 
 ## When the user says "start Crank" or pastes `npx crank`