@ahmednawaz/crank 0.2.7 → 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/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/init.js

@@ -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,
@@ -628,7 +652,17 @@ function initProject(projectRoot, options = {}) {
   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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmednawaz/crank",
-  "version": "0.2.7",
+  "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",

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
 };