@ahmednawaz/crank 0.1.9 → 0.2.0

package/AGENTS.md

@@ -103,20 +103,35 @@ 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 for React apps** — install the package and mount once:
 
-| 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
+pnpm add -D @ahmednawaz/crank
+# or: npm i -D @ahmednawaz/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`.
+```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 |
 
-Keep companion up via Workflow: `npx @ahmednawaz/crank start`. See `.crank/injection.md` after setup.
+Agents: do **not** invent Vite-plugin path workarounds for React apps. See `.crank/react-mount.md` / `.crank/injection.md` after setup.
 
 ---
 

package/README.md

@@ -102,20 +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 (Vite first)
+### Panel injection (Retune-style React)
 
-The panel is a **script overlay**, not a Retune-style React component.
+**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 |
 |-------|-------------|
-| **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` |
+| **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 |
 
-Keep companion running (`npx @ahmednawaz/crank start`). See `.crank/injection.md` after setup.
-
 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/init.js

@@ -433,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');
@@ -448,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) {
@@ -529,7 +537,10 @@ 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) {
@@ -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));
@@ -699,76 +709,99 @@ 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',
     '',
-    '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):',
+    '## Preferred — React component (Retune pattern)',
     '',
-    '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.',
+    'Crank ships a normal npm React export. Vite bundles it like any other dependency.',
+    '**No Vite plugin. No npx-cache paths.**',
     '',
-    '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',
+    'pnpm add -D @ahmednawaz/crank',
     '```',
     '',
-    '`.crank/vite-plugin.cjs` resolves Crank from `config.json` → `packageRoot` (npx cache),',
-    'then `node_modules`, and noops if missing.',
+    '```tsx',
+    "import { Crank } from '@ahmednawaz/crank/react'",
     '',
-    '## React adapter (non-Vite React only)',
+    '// main.tsx — mount once',
+    '<App />',
+    '<Crank />',
+    '```',
     '',
-    'Use only when there is **no** Vite config (CRA / custom webpack React):',
+    'Companion must be running: `npx @ahmednawaz/crank start`',
     '',
-    '```tsx',
-    "import { CrankLoader } from '@ahmednawaz/crank/react'",
-    '// client root only — injects the same /dev-loader.js script',
-    '<CrankLoader />',
-    '```',
+    '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`',
     '',
-    'Do **not** invent a fake in-tree `<Crank />` panel UI. `CrankLoader` / `Crank` only inject a script.',
+    '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 />',
+    "import { Crank } from '@ahmednawaz/crank/next'",
+    '<Crank />',
     '```',
     '',
-    '## 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 +809,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,14 +829,14 @@ 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('    • 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 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 — mount <Crank /> from @ahmednawaz/crank/next');
   }
   console.log('    • Injection guide: .crank/injection.md');
   if (env.isReplit) {
@@ -858,10 +891,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 +914,7 @@ module.exports = {
   writeVitePluginStub,
   patchViteConfig,
   writeInjectionGuide,
+  writeReactMountHint,
   patchReplitConfig,
   copyAgentsDoc
 };

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.0",
   "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 (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`