@ahmednawaz/crank 0.2.6 → 0.2.8

package/CLAUDE.md

@@ -58,7 +58,9 @@ Visual copy tooling that persists text changes to source via the coding agent (M
 - Secrets: `CRANK_TEAM_TOKEN`
 - Workflow Run: `npx @ahmednawaz/crank start`
 - Ports: **3344** (panel), **3345** (`/mcp`)
-- If preview is not localhost: `window.__CRANK_URL__` or `VITE_CRANK_URL` = public `https://3344-…` URL
+- Panel loads via same-origin Vite proxy `/@crank/*` (setup registers `crank({ inject: false })`). Restart **Vite** after setup.
+- Fallback: `window.__CRANK_URL__` / `VITE_CRANK_URL` = public `https://3344-…` URL
+- After closing the panel (×), a **Crank** chip appears bottom-right to reopen.
 
 ## Apply workflow
 

package/bin/crank.js

@@ -710,12 +710,9 @@ async function main() {
     });
   }
 
-  // One-shot parity: setup/default always try inject on React apps (idempotent).
-  if (
-    (command === 'init' || command === 'run') &&
-    detectEnv.hasReact &&
-    flags.mcp !== false
-  ) {
+  // One-shot: always try <Crank /> inject (idempotent). Do not gate on hasReact —
+  // root package.json often omits react in monorepos / Replit layouts.
+  if ((command === 'init' || command === 'run') && flags.mcp !== false) {
     const injectResult = injectCrank(projectRoot, { install: true });
     initResult = initResult || { wrote: [], projectRoot };
     initResult.inject = injectResult;

package/bookmarklet/crank-bookmarklet.js

@@ -96,10 +96,15 @@
   function detectCompanionOrigin() {
     try {
       const scripts = document.querySelectorAll(
-        'script[src*="bookmarklet.js"],script[src*="dev-loader.js"]'
+        'script[src*="bookmarklet.js"],script[src*="dev-loader.js"],script[data-crank-loader="1"]'
       );
       for (const s of scripts) {
-        return new URL(s.src, location.href).origin;
+        const u = new URL(s.src, location.href);
+        // Vite same-origin proxy: /@crank/dev-loader.js → companion base is origin+/@crank
+        if (u.pathname.indexOf('/@crank/') === 0 || u.pathname === '/@crank') {
+          return u.origin + '/@crank';
+        }
+        return u.origin;
       }
     } catch (_) {}
     return null;
@@ -2256,14 +2261,47 @@
     document.removeEventListener('keydown', onKey, true);
   }
 
+  function showReopenChip() {
+    if (document.getElementById('vp-crank-reopen')) {
+      return;
+    }
+    const chip = document.createElement('button');
+    chip.id = 'vp-crank-reopen';
+    chip.type = 'button';
+    chip.textContent = 'Crank';
+    chip.setAttribute('aria-label', 'Reopen Crank panel');
+    chip.style.cssText =
+      'position:fixed;bottom:16px;right:16px;z-index:2147483646;padding:8px 12px;' +
+      'border-radius:999px;border:1px solid rgba(0,0,0,.12);background:#0f766e;color:#fff;' +
+      'font:600 12px/1.2 system-ui,sans-serif;cursor:pointer;box-shadow:0 4px 14px rgba(0,0,0,.18);';
+    chip.addEventListener('click', function () {
+      chip.remove();
+      window.__CRANK_LOADER__ = false;
+      window.__crankActive = false;
+      const s = document.createElement('script');
+      s.src = COMPANION_HTTP + '/bookmarklet.js?t=' + Date.now();
+      s.async = true;
+      s.dataset.crankLoader = '1';
+      document.documentElement.appendChild(s);
+    });
+    document.documentElement.appendChild(chip);
+  }
+
   function teardown() {
     stopSelect();
     restoreOriginal();
     if (socket) socket.close();
-    panel.remove();
-    highlight.remove();
+    if (panel && panel.parentNode) panel.remove();
+    if (highlight && highlight.parentNode) highlight.remove();
     window.__crankActive = false;
     window.__crankTeardown = null;
+    window.__CRANK_LOADER__ = false;
+    try {
+      document.querySelectorAll('script[data-crank-loader="1"]').forEach(function (el) {
+        el.remove();
+      });
+    } catch (_) {}
+    showReopenChip();
   }
 
   window.__crankTeardown = teardown;

package/lib/detect.js

@@ -123,6 +123,91 @@ function packageHasDep(pkg, name) {
   );
 }
 
+const REACT_DEP_NAMES = [
+  'react',
+  'react-dom',
+  '@vitejs/plugin-react',
+  '@vitejs/plugin-react-swc',
+  'next'
+];
+
+const REACT_ENTRY_HINTS = [
+  'src/main.tsx',
+  'src/main.jsx',
+  'src/index.tsx',
+  'src/index.jsx',
+  'client/src/main.tsx',
+  'app/main.tsx',
+  'main.tsx',
+  'main.jsx',
+  'index.tsx',
+  'index.jsx'
+];
+
+function packageLooksLikeReact(pkg) {
+  return REACT_DEP_NAMES.some((name) => packageHasDep(pkg, name));
+}
+
+function dirHasNextConfig(dir) {
+  return (
+    exists(path.join(dir, 'next.config.js')) ||
+    exists(path.join(dir, 'next.config.mjs')) ||
+    exists(path.join(dir, 'next.config.ts'))
+  );
+}
+
+function dirHasReactEntryHint(dir) {
+  return REACT_ENTRY_HINTS.some((rel) => exists(path.join(dir, rel)));
+}
+
+/**
+ * True when this directory (or a common app child) looks like a React app.
+ * Root package.json often omits react in monorepos / Replit multi-package layouts.
+ */
+function detectHasReact(projectRoot, packageJson, viteConfig) {
+  if (packageLooksLikeReact(packageJson) || dirHasNextConfig(projectRoot)) {
+    return true;
+  }
+  if (dirHasReactEntryHint(projectRoot)) {
+    return true;
+  }
+
+  const dirs = new Set([projectRoot]);
+  for (const sub of APP_DIR_CANDIDATES) {
+    if (sub === '.') continue;
+    dirs.add(path.join(projectRoot, sub));
+  }
+  if (viteConfig) {
+    dirs.add(path.dirname(viteConfig));
+  }
+
+  for (const dir of dirs) {
+    if (!exists(dir) || dir === projectRoot) continue;
+    const pkg = readJson(path.join(dir, 'package.json'), null);
+    if (packageLooksLikeReact(pkg) || dirHasNextConfig(dir) || dirHasReactEntryHint(dir)) {
+      return true;
+    }
+  }
+
+  // Vite + JSX plugin import in config is a strong React signal
+  if (viteConfig && exists(viteConfig)) {
+    try {
+      const src = fs.readFileSync(viteConfig, 'utf8');
+      if (
+        /@vitejs\/plugin-react/.test(src) ||
+        /\bplugin-react\b/.test(src) ||
+        /from ['"]react['"]/.test(src)
+      ) {
+        return true;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return false;
+}
+
 function detectEnvironment(projectRoot) {
   const env = process.env;
   const isReplit = Boolean(
@@ -134,16 +219,13 @@ function detectEnvironment(projectRoot) {
     : 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 hasReact = detectHasReact(projectRoot, packageJson, viteConfig);
   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'));
+    dirHasNextConfig(projectRoot) ||
+    [...APP_DIR_CANDIDATES]
+      .filter((s) => s !== '.')
+      .some((sub) => dirHasNextConfig(path.join(projectRoot, sub)));
   const hasWebpack =
     packageHasDep(packageJson, 'webpack') ||
     exists(path.join(projectRoot, 'webpack.config.js')) ||
@@ -182,6 +264,8 @@ module.exports = {
   readJson,
   writeJson,
   detectEnvironment,
+  detectHasReact,
+  packageLooksLikeReact,
   findViteConfig,
   VITE_CONFIG_NAMES,
   APP_DIR_CANDIDATES

package/lib/init.js

@@ -12,7 +12,7 @@ const {
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const { resolveUrls } = require('./urls');
-const { installCrankPackage } = require('./wire-react');
+const { installCrankPackage, findEntry } = require('./wire-react');
 
 function ensureGitignore(projectRoot) {
   const file = path.join(projectRoot, '.gitignore');
@@ -228,20 +228,33 @@ function missingNodeImportLines(source) {
   return NODE_IMPORT_SPECS.filter(({ re }) => !re.test(source)).map(({ line }) => line);
 }
 
-function ensureCrankInPlugins(source) {
-  if (/\bcrank\s*\?\s*\[\s*crank\s*\(\s*\)\s*\]/.test(source) || /\[\s*\.\.\.\s*\(\s*crank\s*\?/.test(source)) {
+function ensureCrankInPlugins(source, options = {}) {
+  const call = options.inject === false ? 'crank({ inject: false })' : 'crank()';
+  const already =
+    /\bcrank\s*\?\s*\[\s*crank\s*\(/.test(source) ||
+    /\[\s*\.\.\.\s*\(\s*crank\s*\?/.test(source);
+  if (already) {
+    // Upgrade bare crank() → crank({ inject: false }) when requested (React + proxy).
+    if (options.inject === false && /crank\(\s*\)/.test(source) && !/crank\(\s*\{\s*inject\s*:/.test(source)) {
+      return {
+        source: source.replace(/crank\(\s*\)/g, 'crank({ inject: false })'),
+        changed: true,
+        ok: true
+      };
+    }
     return { source, changed: false, ok: true };
   }
+  const pluginsExpr = `[...(crank ? [${call}] : [])]`;
   if (/plugins\s*:\s*\[\s*\]/.test(source)) {
     return {
-      source: source.replace(/plugins\s*:\s*\[\s*\]/, 'plugins: [...(crank ? [crank()] : [])]'),
+      source: source.replace(/plugins\s*:\s*\[\s*\]/, `plugins: ${pluginsExpr}`),
       changed: true,
       ok: true
     };
   }
   if (/plugins\s*:\s*\[/.test(source)) {
     return {
-      source: source.replace(/plugins\s*:\s*\[/, 'plugins: [...(crank ? [crank()] : []), '),
+      source: source.replace(/plugins\s*:\s*\[/, `plugins: [...(crank ? [${call}] : []), `),
       changed: true,
       ok: true
     };
@@ -250,7 +263,7 @@ function ensureCrankInPlugins(source) {
     return {
       source: source.replace(
         /defineConfig\s*\(\s*\{/,
-        'defineConfig({\n  plugins: [...(crank ? [crank()] : [])],'
+        `defineConfig({\n  plugins: ${pluginsExpr},`
       ),
       changed: true,
       ok: true
@@ -260,7 +273,7 @@ function ensureCrankInPlugins(source) {
     return {
       source: source.replace(
         /export\s+default\s+\{/,
-        'export default {\n  plugins: [...(crank ? [crank()] : [])],'
+        `export default {\n  plugins: ${pluginsExpr},`
       ),
       changed: true,
       ok: true
@@ -270,7 +283,7 @@ function ensureCrankInPlugins(source) {
     return {
       source: source.replace(
         /module\.exports\s*=\s*\{/,
-        'module.exports = {\n  plugins: [...(crank ? [crank()] : [])],'
+        `module.exports = {\n  plugins: ${pluginsExpr},`
       ),
       changed: true,
       ok: true
@@ -279,7 +292,7 @@ function ensureCrankInPlugins(source) {
   return { source, changed: false, ok: false };
 }
 
-function patchViteConfig(projectRoot) {
+function patchViteConfig(projectRoot, options = {}) {
   const configPath = findViteConfig(projectRoot);
   const stubPath = writeVitePluginStub(projectRoot);
 
@@ -297,6 +310,17 @@ function patchViteConfig(projectRoot) {
   }
 
   if (hasCrankVitePatch(source)) {
+    const upgraded = ensureCrankInPlugins(source, options);
+    if (upgraded.changed) {
+      source = dedupeCrankNodeImports(upgraded.source).source;
+      fs.writeFileSync(configPath, source);
+      return {
+        patched: true,
+        reason: 'upgraded-inject-false',
+        file: configPath,
+        plugin: stubPath
+      };
+    }
     return {
       patched: repaired.changed,
       reason: repaired.changed ? 'repaired-duplicate-imports' : 'already-present',
@@ -338,7 +362,7 @@ try {
       source = gracefulBlock + source;
     }
 
-    const plugged = ensureCrankInPlugins(source);
+    const plugged = ensureCrankInPlugins(source, options);
     if (!plugged.ok) {
       return {
         patched: false,
@@ -359,7 +383,7 @@ try {
     if (!/vite-plugin\.cjs/.test(source) && !/_crankPluginPath/.test(source)) {
       source = gracefulBlock + source;
     }
-    const plugged = ensureCrankInPlugins(source);
+    const plugged = ensureCrankInPlugins(source, options);
     if (!plugged.ok) {
       return {
         patched: false,
@@ -623,10 +647,22 @@ function initProject(projectRoot, options = {}) {
   // React apps: <Crank /> only — do not inject the Vite plugin (avoids duplicating
   // node: imports when vite.config already has Vizpatch-style loaders).
   // Still repair duplicate imports left by older Crank versions.
-  if (env.hasReact && options.react !== false) {
+  // Treat findEntry hits as React even when root package.json omits the dep.
+  const looksLikeReact = env.hasReact || Boolean(findEntry(projectRoot));
+  if (looksLikeReact && options.react !== false) {
     writeReactMountHint(projectRoot, env, results);
     results.reactMount = true;
-    if (env.hasVite) {
+    // Still register Vite plugin with inject:false — enables /@crank proxy (Replit iframe).
+    if (env.hasVite && options.vite !== false) {
+      const viteResult = patchViteConfig(projectRoot, { inject: false });
+      results.vite = viteResult;
+      if (viteResult.patched || viteResult.reason === 'repaired-duplicate-imports') {
+        results.wrote.push(path.relative(projectRoot, viteResult.file));
+      }
+      if (viteResult.plugin) {
+        results.wrote.push(path.relative(projectRoot, viteResult.plugin));
+      }
+    } else if (env.hasVite) {
       const repaired = repairViteConfigDuplicates(projectRoot);
       if (repaired.repaired) {
         results.vite = repaired;

package/lib/loader-url.js

@@ -31,6 +31,11 @@ function resolveCompanionLoaderUrl(options = {}) {
     return String(options.src);
   }
 
+  // Prefer same-origin Vite proxy path (works inside Replit iframe / CSP).
+  if (options.preferProxy !== false && !options.companionUrl && !options.absolute) {
+    return '/@crank/dev-loader.js';
+  }
+
   const projectRoot = options.projectRoot || findProjectRoot(process.cwd());
   const runtime = readRuntimeManifest(projectRoot);
   if (runtime?.companion?.devLoader) {
@@ -49,7 +54,17 @@ function resolveCompanionLoaderUrl(options = {}) {
   return `${base}/dev-loader.js`;
 }
 
+/** Internal companion base for Vite `server.proxy` target (always loopback). */
+function resolveCompanionProxyTarget(options = {}) {
+  if (options.target) {
+    return String(options.target).replace(/\/$/, '');
+  }
+  const port = String(options.port || env('PORT', '3344')).replace(/[^0-9]/g, '') || '3344';
+  return `http://127.0.0.1:${port}`;
+}
+
 module.exports = {
   findProjectRoot,
-  resolveCompanionLoaderUrl
+  resolveCompanionLoaderUrl,
+  resolveCompanionProxyTarget
 };

package/lib/resolve-project.js

@@ -3,7 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { exists, readJson } = require('./detect');
+const { exists, readJson, findViteConfig, packageLooksLikeReact } = require('./detect');
 
 const APP_DIR_CANDIDATES = [
   '.',
@@ -37,6 +37,59 @@ function hasFrameworkMarker(dir) {
   return FRAMEWORK_FILES.some((name) => exists(path.join(dir, name)));
 }
 
+function dirPackageLooksLikeReact(dir) {
+  return packageLooksLikeReact(readJson(path.join(dir, 'package.json'), null));
+}
+
+/**
+ * Prefer the real app package (Vite/React) over a bare repo-root package.json.
+ */
+function findAppDirectory(repoRoot) {
+  const root = path.resolve(repoRoot);
+
+  // 1. Known app subdirs with a framework config (before root — monorepos)
+  for (const rel of APP_DIR_CANDIDATES) {
+    if (rel === '.') continue;
+    const candidate = path.join(root, rel);
+    if (exists(candidate) && hasFrameworkMarker(candidate)) {
+      return { appRoot: candidate, reason: `framework in ${rel}/` };
+    }
+  }
+
+  // 2. Vite config found via shallow search (e.g. artifacts/<app>/ on Replit)
+  const viteConfig = findViteConfig(root);
+  if (viteConfig) {
+    const viteDir = path.dirname(viteConfig);
+    if (viteDir !== root) {
+      // Prefer the vite package dir when it looks like React, or root does not.
+      if (dirPackageLooksLikeReact(viteDir) || !dirPackageLooksLikeReact(root)) {
+        return {
+          appRoot: viteDir,
+          reason: `vite.config in ${path.relative(root, viteDir) || '.'}`
+        };
+      }
+    }
+  }
+
+  // 3. Root has framework
+  if (hasFrameworkMarker(root)) {
+    return { appRoot: root, reason: 'framework at repo root' };
+  }
+
+  // 4. Subdir / root package.json
+  for (const rel of APP_DIR_CANDIDATES) {
+    const candidate = path.join(root, rel === '.' ? '' : rel);
+    if (exists(candidate) && exists(path.join(candidate, 'package.json'))) {
+      return {
+        appRoot: candidate,
+        reason: `package.json in ${rel === '.' ? 'root' : rel + '/'}`
+      };
+    }
+  }
+
+  return { appRoot: root, reason: 'repo root (fallback)' };
+}
+
 function readCrankConfig(startDir) {
   let dir = path.resolve(startDir);
   for (let i = 0; i < 12; i++) {
@@ -95,33 +148,6 @@ function findPackageRoot(startDir) {
   return path.resolve(startDir);
 }
 
-/**
- * Retune-style: find the app directory inside a repo (app/, client/, web/, …).
- */
-function findAppDirectory(repoRoot) {
-  const root = path.resolve(repoRoot);
-  if (hasFrameworkMarker(root)) {
-    return { appRoot: root, reason: 'framework at repo root' };
-  }
-
-  for (const rel of APP_DIR_CANDIDATES) {
-    if (rel === '.') continue;
-    const candidate = path.join(root, rel);
-    if (exists(candidate) && hasFrameworkMarker(candidate)) {
-      return { appRoot: candidate, reason: `framework in ${rel}/` };
-    }
-  }
-
-  for (const rel of APP_DIR_CANDIDATES) {
-    const candidate = path.join(root, rel === '.' ? '' : rel);
-    if (exists(candidate) && exists(path.join(candidate, 'package.json'))) {
-      return { appRoot: candidate, reason: `package.json in ${rel === '.' ? 'root' : rel + '/'}` };
-    }
-  }
-
-  return { appRoot: root, reason: 'repo root (fallback)' };
-}
-
 /**
  * Resolve where the user's app code lives — no manual path required.
  * Priority: CRANK_PROJECT_ROOT → .crank/config → git root + app dir → package.json walk → cwd.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Internal Motive UX copy iteration: select UI text \u2192 Glean variants \u2192 MCP apply. Cursor, Replit, Claude.",
   "repository": {
     "type": "git",
@@ -67,7 +67,8 @@
     "prepare:publish": "node scripts/prepare-publish.js",
     "verify:deps": "node scripts/verify-deps.js",
     "publish:team": "node scripts/prepare-publish.js && node scripts/verify-deps.js && npm publish --access public",
-    "test:patch-vite": "node scripts/test-patch-vite.js"
+    "test:patch-vite": "node scripts/test-patch-vite.js",
+    "test:react-detect": "node scripts/test-react-detect.js"
   },
   "engines": {
     "node": ">=18"

package/react.d.ts

@@ -11,15 +11,20 @@ export interface CrankProps {
 
 export declare function resolveCrankCompanionUrl(props?: CrankProps): string;
 export declare function resolveCrankLoaderSrc(props?: CrankProps): string;
+/** Infer https://3344-… from the current Replit preview hostname. */
+export declare function detectReplitCompanionUrl(): string | null;
 
 /**
- * Retune-style mount — injects companion `/dev-loader.js` once. Renders null.
+ * Mount — injects companion loader once. Renders null.
+ *
+ * Prefers same-origin `/@crank/dev-loader.js` (Vite proxy) so the panel works
+ * inside Replit iframe previews; falls back to public companion / localhost.
  *
  *   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`
+ * Optional: `window.__CRANK_URL__` or `VITE_CRANK_URL`. Keep companion up:
+ * `npx @ahmednawaz/crank start`
  */
 export declare function Crank(props?: CrankProps): ReactElement | null;
 export declare const CrankLoader: typeof Crank;

package/react.js

@@ -2,9 +2,10 @@
 
 /**
  * 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 PROXY_LOADER = '/@crank/dev-loader.js';
+
 function getReact() {
   try {
     return require('react');
@@ -15,6 +16,22 @@ function getReact() {
   }
 }
 
+function detectReplitCompanionUrl() {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  try {
+    const host = window.location.hostname || '';
+    if (!/\.replit\.dev$|\.repl\.co$|\.replit\.app$/.test(host)) {
+      return null;
+    }
+    const base = host.replace(/^\d+-/, '');
+    return 'https://3344-' + base;
+  } catch {
+    return null;
+  }
+}
+
 function resolveCrankCompanionUrl(props) {
   props = props || {};
   if (typeof window !== 'undefined' && window.__CRANK_URL__) {
@@ -26,6 +43,23 @@ function resolveCrankCompanionUrl(props) {
   if (props.url) {
     return String(props.url).replace(/\/$/, '');
   }
+  try {
+    if (
+      typeof process !== 'undefined' &&
+      process.env &&
+      (process.env.VITE_CRANK_URL || process.env.VITE_CRANK_COMPANION_URL)
+    ) {
+      return String(
+        process.env.VITE_CRANK_URL || process.env.VITE_CRANK_COMPANION_URL
+      ).replace(/\/$/, '');
+    }
+  } catch {
+    // ignore
+  }
+  const replit = detectReplitCompanionUrl();
+  if (replit) {
+    return replit;
+  }
   return 'http://localhost:3344';
 }
 
@@ -34,32 +68,57 @@ function resolveCrankLoaderSrc(props) {
   if (props.src) {
     return String(props.src);
   }
-  return `${resolveCrankCompanionUrl(props)}/dev-loader.js`;
+  if (
+    typeof window !== 'undefined' &&
+    !props.companionUrl &&
+    !props.url &&
+    !(typeof window !== 'undefined' && window.__CRANK_URL__)
+  ) {
+    return PROXY_LOADER;
+  }
+  return resolveCrankCompanionUrl(props) + '/dev-loader.js';
+}
+
+function appendLoaderScript(src, onError) {
+  const script = document.createElement('script');
+  script.src = src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now();
+  script.async = true;
+  script.dataset.crankLoader = '1';
+  if (onError) {
+    script.onerror = onError;
+  }
+  document.documentElement.appendChild(script);
+  return script;
 }
 
 function Crank(props) {
   const React = getReact();
   props = props || {};
-  const src = resolveCrankLoaderSrc(props);
+  const preferredSrc = resolveCrankLoaderSrc(props);
 
-  React.useEffect(() => {
+  React.useEffect(function () {
     if (typeof document === 'undefined') {
       return undefined;
     }
-    if (document.querySelector('script[data-crank-loader="1"]')) {
+    if (document.getElementById('vp-shell') || document.getElementById('vp-crank-reopen')) {
       return undefined;
     }
-    if (window.__CRANK_LOADER__ && document.getElementById('vp-shell')) {
+    if (document.querySelector('script[data-crank-loader="1"]')) {
       return undefined;
     }
 
-    const script = document.createElement('script');
-    script.src = src.indexOf('?') >= 0 ? src : src + '?t=' + Date.now();
-    script.async = true;
-    script.dataset.crankLoader = '1';
-    document.documentElement.appendChild(script);
+    const fallback = resolveCrankCompanionUrl(props) + '/dev-loader.js';
+    appendLoaderScript(preferredSrc, function () {
+      if (preferredSrc !== fallback && !document.getElementById('vp-shell')) {
+        document.querySelectorAll('script[data-crank-loader="1"]').forEach(function (el) {
+          el.remove();
+        });
+        window.__CRANK_LOADER__ = false;
+        appendLoaderScript(fallback);
+      }
+    });
     return undefined;
-  }, [src]);
+  }, [preferredSrc]);
 
   return null;
 }
@@ -67,6 +126,7 @@ function Crank(props) {
 module.exports = {
   Crank,
   CrankLoader: Crank,
+  detectReplitCompanionUrl,
   resolveCrankCompanionUrl,
   resolveCrankLoaderSrc,
   default: Crank

package/react.mjs

@@ -1,20 +1,41 @@
 /**
- * Retune-style React entry — browser-only, Vite-bundlable (no Node/fs).
+ * Browser-safe React entry — 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`
+ * Loads companion `/dev-loader.js` (prefers same-origin `/@crank` Vite proxy on Replit).
+ * Requires: `npx @ahmednawaz/crank start`
  *
  * peerDependency: react >= 17
  */
 
 import { useEffect } from 'react';
 
+const PROXY_LOADER = '/@crank/dev-loader.js';
+
+/**
+ * Replit public companion host from the current preview hostname.
+ * e.g. 5000-foo.replit.dev → https://3344-foo.replit.dev
+ * @returns {string | null}
+ */
+export function detectReplitCompanionUrl() {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  try {
+    const host = window.location.hostname || '';
+    if (!/\.replit\.dev$|\.repl\.co$|\.replit\.app$/.test(host)) {
+      return null;
+    }
+    const base = host.replace(/^\d+-/, '');
+    const port = 3344;
+    return `https://${port}-${base}`;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * @param {{ companionUrl?: string, url?: string, src?: string }} [props]
  * @returns {string}
@@ -40,6 +61,10 @@ export function resolveCrankCompanionUrl(props = {}) {
   } catch {
     // ignore
   }
+  const replit = detectReplitCompanionUrl();
+  if (replit) {
+    return replit;
+  }
   return 'http://localhost:3344';
 }
 
@@ -51,38 +76,67 @@ export function resolveCrankLoaderSrc(props = {}) {
   if (props.src) {
     return String(props.src);
   }
+  // Same-origin Vite proxy first (Replit iframe / CSP safe).
+  if (typeof window !== 'undefined' && !props.companionUrl && !props.url && !window.__CRANK_URL__) {
+    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 PROXY_LOADER;
+      }
+    } catch {
+      return PROXY_LOADER;
+    }
+  }
   return `${resolveCrankCompanionUrl(props)}/dev-loader.js`;
 }
 
+function appendLoaderScript(src, onError) {
+  const script = document.createElement('script');
+  script.src = src.includes('?') ? src : `${src}?t=${Date.now()}`;
+  script.async = true;
+  script.dataset.crankLoader = '1';
+  if (onError) {
+    script.onerror = onError;
+  }
+  document.documentElement.appendChild(script);
+  return script;
+}
+
 /**
- * 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.
+ * Mount near app root. Renders null; injects the companion loader once.
  *
  * @param {{ companionUrl?: string, url?: string, src?: string }} [props]
  */
 export function Crank(props = {}) {
-  const src = resolveCrankLoaderSrc(props);
+  const preferredSrc = resolveCrankLoaderSrc(props);
 
   useEffect(() => {
     if (typeof document === 'undefined') {
       return undefined;
     }
-    if (document.querySelector('script[data-crank-loader="1"]')) {
+    if (document.getElementById('vp-shell') || document.getElementById('vp-crank-reopen')) {
       return undefined;
     }
-    // Panel already live (bookmarklet / prior mount)
-    if (window.__CRANK_LOADER__ && document.getElementById('vp-shell')) {
+    if (document.querySelector('script[data-crank-loader="1"]')) {
       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);
+    const fallback = `${resolveCrankCompanionUrl(props)}/dev-loader.js`;
+    const primary = preferredSrc;
+
+    appendLoaderScript(primary, () => {
+      // Proxy missing (no Vite plugin) — fall back to public / localhost companion.
+      if (primary !== fallback && !document.getElementById('vp-shell')) {
+        document.querySelectorAll('script[data-crank-loader="1"]').forEach((el) => el.remove());
+        window.__CRANK_LOADER__ = false;
+        appendLoaderScript(fallback);
+      }
+    });
     return undefined;
-  }, [src]);
+  }, [preferredSrc]);
 
   return null;
 }

package/vite.js

@@ -2,30 +2,55 @@
 
 /**
  * Vite / Rolldown-vite / Vitest-compatible plugin.
- * Injects Crank into the app during `vite` / `npm run dev` — no React component needed.
  *
- *   // vite.config.ts
- *   import { crank } from '@ahmednawaz/crank/vite'
- *   // or: import { crank } from 'crank/vite'
- *   export default { plugins: [crank()] }
+ * - Proxies `/@crank/*` → companion (same-origin; required on Replit iframe previews)
+ * - Optionally injects the loader into index.html (skip when using React `<Crank />`)
  *
- * Prefer this for Vite apps (React, Vue, Svelte, vanilla). The panel is a script overlay,
- * not a component in your React tree.
+ *   import { crank } from '@ahmednawaz/crank/vite'
+ *   export default { plugins: [crank()] }                 // Vite-only apps
+ *   export default { plugins: [crank({ inject: false })] } // React + <Crank />
  */
 
-const { resolveCompanionLoaderUrl } = require('./lib/loader-url');
+const { resolveCompanionLoaderUrl, resolveCompanionProxyTarget } = require('./lib/loader-url');
+
+const PROXY_PREFIX = '/@crank';
 
 function crank(options = {}) {
-  const src = resolveCompanionLoaderUrl(options);
+  const inject = options.inject !== false;
+  const target = resolveCompanionProxyTarget(options);
+  const src =
+    options.src ||
+    `${PROXY_PREFIX}/dev-loader.js`;
 
   return {
     name: 'crank-dev-loader',
     apply: 'serve',
+    config() {
+      return {
+        server: {
+          proxy: {
+            [PROXY_PREFIX]: {
+              target,
+              changeOrigin: true,
+              ws: true,
+              rewrite: (p) => p.replace(new RegExp(`^${PROXY_PREFIX}`), '') || '/'
+            }
+          }
+        }
+      };
+    },
     transformIndexHtml(html) {
-      if (String(html).includes('/dev-loader.js') || String(html).includes('crank/dev-loader')) {
+      if (!inject) {
+        return html;
+      }
+      if (
+        String(html).includes('/dev-loader.js') ||
+        String(html).includes('crank/dev-loader') ||
+        String(html).includes('/@crank/')
+      ) {
         return html;
       }
-      const tag = `<script src="${src}" defer></script>`;
+      const tag = `<script src="${src}?t=${Date.now()}" defer></script>`;
       if (html.includes('</head>')) {
         return html.replace('</head>', `  ${tag}\n</head>`);
       }
@@ -37,5 +62,6 @@ function crank(options = {}) {
 module.exports = {
   crank,
   crankDevLoader: crank,
-  resolveCompanionLoaderUrl
+  resolveCompanionLoaderUrl,
+  PROXY_PREFIX
 };