@buoy-gg/core 7.0.41 → 7.0.42

package/README.md

@@ -1,109 +1,28 @@
+<div align="center">
+
 # @buoy-gg/core
 
-[![npm version](https://img.shields.io/npm/v/@buoy-gg/core?style=flat-square&labelColor=1c1c1c&color=10B981)](https://www.npmjs.com/package/@buoy-gg/core)
-[![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/core?style=flat-square&labelColor=1c1c1c&color=10B981&label=downloads%2Fmonth)](https://www.npmjs.com/package/@buoy-gg/core)
+The floating developer-tools menu for your React Native app. Add the tool packages you need to inspect requests, app state, storage and performance.
+
+<a href="https://buoy.gg/buoy/latest/docs/quick-start"><b>Quick start</b></a> &nbsp;·&nbsp; <a href="https://buoy.gg">buoy.gg</a> &nbsp;·&nbsp; <a href="https://github.com/Buoy-gg/buoy">All tools</a>
 
-Buoy adds a floating developer-tools menu to your React Native app. Install the tools you need to inspect captured requests, app state, storage, and performance.
+[![npm version](https://img.shields.io/npm/v/@buoy-gg/core?style=flat-square&labelColor=10302a&color=2a9d78)](https://www.npmjs.com/package/@buoy-gg/core) [![npm downloads](https://img.shields.io/npm/dm/@buoy-gg/core?style=flat-square&labelColor=10302a&color=2a9d78&label=downloads%2Fmonth)](https://www.npmjs.com/package/@buoy-gg/core)
 
-## Install and quick start
+<a href="https://buoy.gg"><img src="https://raw.githubusercontent.com/Buoy-gg/buoy/main/.github/readme/film.png" alt="Play the 53-second Buoy film on buoy.gg" width="640" /></a>
 
-Install from your app’s directory, then sign in:
+</div>
+
+## Install
 
 ```bash
 npm install @buoy-gg/core @buoy-gg/network
 npx --package=@buoy-gg/core buoy login
 ```
 
-In an Expo Router project, keep your existing navigator and providers. For example:
-
-```tsx
-import { Stack } from "expo-router";
-import { Buoy, FloatingDevTools } from "@buoy-gg/core";
-
-Buoy.init({ licenseKey: process.env.EXPO_PUBLIC_BUOY_KEY });
-
-export default function RootLayout() {
-  return (
-    <>
-      <Stack />
-      <FloatingDevTools />
-    </>
-  );
-}
-```
-
-The login command writes the Expo key to `.env.local`. Keep the navigator and menu inside your existing providers. Without Expo Router, keep your app’s root content in place of `Stack`. For React Native CLI, load the key through your app’s environment configuration and pass it to `Buoy.init`; `.env.local` is not loaded automatically.
-
-Restart the development server after installation. Open Buoy, complete any account prompt, and select Network. Trigger a new HTTP request in your app and check its URL and status. If no request appears, check whether the app used cached data or an unsupported transport.
-
-See the [Quick Start](https://buoy.gg/buoy/latest/docs/quick-start) for the full setup and [Installation](https://buoy.gg/buoy/latest/docs/installation) for requirements. Other tools may need store registration, provider context, or native dependencies.
-
-The dial shows the most recently opened tool first. Tools you haven’t opened keep their registration order.
-
-## Tools
-
-| Tool | Package | What it does |
-| --- | --- | --- |
-| [Network](https://buoy.gg/buoy/latest/docs/tools/network) | `@buoy-gg/network` | Inspect HTTP requests captured through your React Native app’s global `fetch` and `XMLHttpRequest` hooks. Open a request to see its URL, status, headers, timing, and captured body. |
-| [Storage](https://buoy.gg/buoy/latest/docs/tools/storage) | `@buoy-gg/storage` | Browse and edit supported AsyncStorage, registered MMKV instances, and registered SecureStore keys inside your app. |
-| [Time Machine](https://buoy.gg/buoy/latest/docs/tools/time-machine) | `@buoy-gg/time-machine` | Save and restore supported client state; external side effects are not reversed. |
-| [Ask Buoy](https://buoy.gg/buoy/latest/docs/tools/ask-buoy) | `@buoy-gg/ask-buoy` | Use an in-app assistant with your model endpoint and configured tools. |
-| [Env](https://buoy.gg/buoy/latest/docs/tools/env) | `@buoy-gg/env` | Inspect runtime environment values and validate required variables. |
-| [Query](https://buoy.gg/buoy/latest/docs/tools/react-query) | `@buoy-gg/react-query` | Inspect the TanStack Query cache used by your app. Refetch or invalidate a query and simulate states while checking the screen that consumes it. |
-| [Routes](https://buoy.gg/buoy/latest/docs/tools/routes) | `@buoy-gg/route-events` | Inspect recorded navigation events and supported routes. |
-| [Debug Borders](https://buoy.gg/buoy/latest/docs/tools/debug-borders) | `@buoy-gg/debug-borders` | Show layout borders and component labels over your React Native app. Tap a label to inspect the component’s available properties. |
-| [Highlight Updates](https://buoy.gg/buoy/latest/docs/tools/highlight-updates) | `@buoy-gg/highlight-updates` | Highlight observed React component updates in development builds and inspect the available render details. |
-| [Bench](https://buoy.gg/buoy/latest/docs/tools/perf-monitor) | `@buoy-gg/perf-monitor` | Measure available frame-rate, CPU, and memory metrics on a device. Record comparable runs to investigate performance changes. |
-| [JS Top](https://buoy.gg/buoy/latest/docs/tools/js-top) | `@buoy-gg/js-top` | Task Manager for the JS thread — which timers, Promise chains & callbacks eat your JS FPS |
-| [Images](https://buoy.gg/buoy/latest/docs/tools/images) | `@buoy-gg/images` | Inspect image loads observed by Buoy’s supported image hooks, including timing, dimensions, and estimated decoded memory. |
-| [Assets](https://buoy.gg/buoy/latest/docs/tools/assets) | `@buoy-gg/assets` | Inspect assets visible to the runtime registry and, in development, the Metro dependency graph. Compare sizes and find possible duplicates. |
-| [Events](https://buoy.gg/buoy/latest/docs/tools/events) | `@buoy-gg/events` | Review events from configured Buoy tools in one timeline. Filter by source, inspect an event, and export a selection for debugging. |
-| [Console](https://buoy.gg/buoy/latest/docs/tools/console) | `@buoy-gg/console` | Read captured JavaScript console logs in your React Native app. Filter messages by level, search their contents, and inspect logged objects. |
-| [Sentry](https://buoy.gg/buoy/latest/docs/tools/sentry) | `@buoy-gg/sentry` | Inspect captured Sentry envelopes and diagnostic estimates. |
-| [Redux](https://buoy.gg/buoy/latest/docs/tools/redux) | `@buoy-gg/redux` | Inspect your connected Redux store, review captured actions and state changes, and dispatch actions from your device. |
-| [Zustand](https://buoy.gg/buoy/latest/docs/tools/zustand) | `@buoy-gg/zustand` | Inspect the Zustand stores you register with Buoy. Review changes, edit state, and restore retained snapshots. |
-| [Jotai](https://buoy.gg/buoy/latest/docs/tools/jotai) | `@buoy-gg/jotai` | Inspect registered Jotai atoms and their captured changes, with live values and per-atom history. |
-| [Impersonate](https://buoy.gg/buoy/latest/docs/tools/impersonate) | `@buoy-gg/impersonate` | Connect your app’s user-switching flow to Buoy so testers can switch test accounts, roles, or flags without rebuilding. |
-| [Overlay](https://buoy.gg/buoy/latest/docs/tools/image-overlay) | `@buoy-gg/image-overlay` | Place a reference image over your app to compare spacing, alignment, and sizing on the device. |
-
-TV tools and the iOS Simulator camera have separate [platform requirements](https://buoy.gg/buoy/latest/docs/overview).
-
-## Desktop and AI
-
-Inspect configured tools in the floating menu on your device. You can also connect them to:
-
-- [Buoy Desktop](https://github.com/Buoy-gg/Buoy-Desktop), for desktop panels and remote actions. React Native apps need `@buoy-gg/external-sync`; follow the [connection guide](https://buoy.gg/buoy/latest/docs/desktop) and sign in to Desktop separately.
-- [MCP](https://buoy.gg/buoy/latest/docs/mcp), for an AI editor to inspect and act on the app. Configure both process and device accounts; data and action tools require Pro.
-- [Ask Buoy](https://buoy.gg/buoy/latest/docs/tools/ask-buoy), for an in-app assistant. It requires Pro, a model endpoint you configure, and the tool integrations its tasks depend on.
-
-Supported features vary by platform, build, and installed tools. [Flutter](https://buoy.gg/buoy/latest/docs/flutter/quick-start) has a separate debug-build setup.
-
-## Account and plan requirements
-
-Use a Free or Pro Buoy account. History limits and paid features vary by tool; see [pricing](https://buoy.gg/pricing). Production access requires Pro where supported. Development-only hooks and actions remain unavailable in release builds.
-
-## Production and connections
-
-Start with a development build. Before enabling Buoy in a shipped app, restrict access using your app’s authorization checks and review the [component reference](https://buoy.gg/buoy/latest/docs/floating-devtools). Production access requires Pro, and development-only capabilities remain unavailable.
-
-Hiding the menu is not a substitute for backend authorization. Headless mode hides the on-device UI; it still requires account admission and sync configuration. Release sync is disabled by default and must be explicitly enabled.
-
-Device sessions can travel over your LAN to the configured broker. Buoy also makes account and license requests; development telemetry is described in [Telemetry](https://buoy.gg/buoy/latest/docs/telemetry). Ask Buoy sends model requests to the endpoint you configure.
-
-## License
-
-Proprietary software. © Buoy LLC. All rights reserved. See the [Terms of Service](https://buoy.gg/terms).
-
-### Custom floating controls
-
-The DevTools bubble uses the shared `FloatingTool` shell. Custom tools can use the same shell with `openFloatingTool`; `FloatingDevTools` already mounts the host. See the [integration guide](https://buoy.gg/buoy/latest/docs/custom-tools/floating-tools).
-
-## Web support (unreleased)
-
-Import `FloatingDevTools` from `@buoy-gg/core/web` and pass the tool namespaces through `modules`. Settings, account status, and modal persistence share their implementation with native. The browser build is available in this checkout and has not been published yet. See the [web setup guide](https://buoy.gg/buoy/latest/docs/web-preview) for registration, dependencies, and browser boundaries.
+Call `Buoy.init` with your key and render `<FloatingDevTools />` inside your existing providers. The login command writes the Expo key to `.env.local`; React Native CLI apps load the key through their own environment config.
 
-In a Vite app, run `pnpm exec buoy login` from the app directory. The CLI writes `VITE_BUOY_KEY` to `.env.development.local` for Free accounts or `.env.local` for paid accounts. Pass `import.meta.env.VITE_BUOY_KEY` to the host's `licenseKey` prop.
+The [Quick start](https://buoy.gg/buoy/latest/docs/quick-start) walks through the full setup, and [every tool](https://buoy.gg/buoy/latest/docs/overview) has its own guide.
 
-The browser dial supports Tab, arrow keys between tools, Enter to activate controls, and Escape to close. Its center button opens settings. Drag panel backgrounds or handles to move them; tabs and inputs keep their normal mouse behavior. Minimized tools stay above the floating bar and scroll when needed. They open below only when there is not enough room above for one row.
+---
 
-The web dial follows the shared Background selection in Settings, including changes made while the dial is open.
+<sub>Part of <a href="https://buoy.gg">Buoy</a>, developer tools that live inside your app. Proprietary software. © Buoy LLC. <a href="https://buoy.gg/terms">Terms</a></sub>

package/bin/buoy.js

@@ -1,352 +1,31 @@
 #!/usr/bin/env node
-/**
- * The `buoy` CLI.
- *
- * Ships as a bin on @buoy-gg/core rather than its own package so that
- * `npx buoy login` resolves from the project's own node_modules — anyone who
- * already installed Buoy has it, with nothing extra to install and no npm
- * package name to own.
- *
- * Plain CommonJS with ZERO dependencies, on purpose: it runs via npx inside
- * someone else's project, so every dependency would be an install-time cost and
- * a supply-chain surface for a tool whose entire job takes ten seconds.
- */
-
-'use strict';
-
-const http = require('node:http');
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { spawn } = require('node:child_process');
-
-const SITE = process.env.BUOY_SITE_URL || 'https://buoy.gg';
-const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
-
-const ESC = '\x1b[';
-const color = (code) => (s) => `${ESC}${code}m${s}${ESC}0m`;
-const cyan = color(36);
-const green = color(32);
-const red = color(31);
-const dim = color(2);
-const bold = color(1);
-
-function log(msg) {
-  process.stdout.write(`${msg}\n`);
-}
-
-function fail(msg) {
-  process.stderr.write(`${red('x')} ${msg}\n`);
-  process.exit(1);
-}
-
-/**
- * Open a URL in the user's default browser.
- *
- * Failure is not fatal: headless boxes, SSH sessions and locked-down machines
- * all land here, and the URL is printed regardless so it can be opened by hand.
- */
-function openBrowser(url) {
-  const cmd =
-    process.platform === 'darwin'
-      ? 'open'
-      : process.platform === 'win32'
-        ? 'cmd'
-        : 'xdg-open';
-  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-  try {
-    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
-  } catch {
-    /* the URL is printed either way */
-  }
-}
-
-/** Select the public variable prefix supported by the app's bundler. */
-function detectEnvVarName(root) {
-  let webVarName = null;
-  try {
-    const pkgPath = path.join(root, 'package.json');
-    if (fs.existsSync(pkgPath)) {
-      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-      const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
-      if (deps.expo) return 'EXPO_PUBLIC_BUOY_KEY';
-      if (deps.vite) webVarName = 'VITE_BUOY_KEY';
-    }
-    if (
-      fs.existsSync(path.join(root, 'app.config.js')) ||
-      fs.existsSync(path.join(root, 'app.config.ts'))
-    ) {
-      return 'EXPO_PUBLIC_BUOY_KEY';
-    }
-    const appJson = path.join(root, 'app.json');
-    if (fs.existsSync(appJson)) {
-      const parsed = JSON.parse(fs.readFileSync(appJson, 'utf8'));
-      if (parsed && parsed.expo) return 'EXPO_PUBLIC_BUOY_KEY';
-    }
-  } catch {
-    /* Use the detected bundler or the generic name. */
-  }
-  return webVarName || 'BUOY_KEY';
-}
-
-/**
- * Expo and Vite include `.env.local` in production builds. Free keys belong
- * in `.env.development.local` to keep them in development builds and avoid
- * account verification from every production client. Paid keys can also be
- * used in TestFlight or QA builds, so they keep `.env.local`.
- */
-function envFileFor(varName, tier) {
-  if (varName !== 'EXPO_PUBLIC_BUOY_KEY' && varName !== 'VITE_BUOY_KEY') return '.env.local';
-  return tier === 'pro' || tier === 'business' ? '.env.local' : '.env.development.local';
-}
-
-/** Drop `NAME=...` from an env file if present. True when a line was removed. */
-function removeEnvVar(root, name, fileName) {
-  const file = path.join(root, fileName);
-  let contents;
-  try {
-    contents = fs.readFileSync(file, 'utf8');
-  } catch {
-    return false;
-  }
-  const pattern = new RegExp('^' + name + '=.*\\n?', 'm');
-  if (!pattern.test(contents)) return false;
-  fs.writeFileSync(file, contents.replace(pattern, ''), { mode: 0o600 });
-  return true;
-}
-
-/** Upsert `NAME=value` in an env file, preserving everything else in the file. */
-function writeEnvVar(root, name, value, fileName = '.env.local') {
-  const file = path.join(root, fileName);
-  let contents = '';
-  try {
-    contents = fs.readFileSync(file, 'utf8');
-  } catch {
-    /* new file */
-  }
-
-  const line = `${name}=${value}`;
-  const pattern = new RegExp('^' + name + '=.*$', 'm');
-
-  if (pattern.test(contents)) {
-    contents = contents.replace(pattern, line);
-  } else {
-    if (contents && !contents.endsWith('\n')) contents += '\n';
-    contents += `${line}\n`;
-  }
-
-  fs.writeFileSync(file, contents, { mode: 0o600 });
-  return file;
-}
-
-/**
- * Make sure the env file is ignored.
- *
- * The whole point of a per-developer key is that it identifies one person; a
- * key committed to a shared repo turns the count back into "repos", which is
- * exactly what this flow exists to avoid.
- */
-function ensureGitignored(root, fileName = '.env.local') {
-  const file = path.join(root, '.gitignore');
-  let contents = '';
-  try {
-    contents = fs.readFileSync(file, 'utf8');
-  } catch {
-    return false;
-  }
-  const exact = new RegExp('^' + fileName.replace(/\./g, '\\.') + '$', 'm');
-  // `.env*`, `*.local` and `.env*.local` all cover both files we might write.
-  if (exact.test(contents) || /^\.env\*|^\*\.local$|^\.env\*\.local$/m.test(contents)) return false;
-
-  if (contents && !contents.endsWith('\n')) contents += '\n';
-  contents += `\n# Buoy license key (per developer - do not commit)\n${fileName}\n`;
-  fs.writeFileSync(file, contents);
-  return true;
-}
-
-/**
- * Loopback auth.
- *
- * The browser does the signing in (it already holds the Clerk session), then
- * hands the key back to a short-lived server on 127.0.0.1. Chosen over a
- * device-code flow because it needs no server-side pending-code state, and over
- * redirecting with the key in the URL because that would write a credential
- * into browser history.
- */
-function awaitKeyFromBrowser() {
-  return new Promise((resolve, reject) => {
-    const state = crypto.randomBytes(16).toString('hex');
-
-    const server = http.createServer((req, res) => {
-      // The page runs on buoy.gg and posts here cross-origin.
-      if (req.headers.origin === SITE) {
-        res.setHeader('Access-Control-Allow-Origin', SITE);
-        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
-        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
-        // Private Network Access: Chrome is moving to require a public site to
-        // be granted permission before it may reach loopback, via this header
-        // on the preflight. Sending it costs nothing today and is the
-        // difference between this flow surviving that rollout and silently
-        // failing for every Chrome user on the same day.
-        res.setHeader('Access-Control-Allow-Private-Network', 'true');
-      }
-
-      if (req.method === 'OPTIONS') {
-        res.writeHead(204).end();
-        return;
-      }
-      if (req.method !== 'POST') {
-        res.writeHead(405).end();
-        return;
-      }
-
-      let body = '';
-      req.on('data', (chunk) => {
-        body += chunk;
-        // A local server that accepts unbounded input is a local server that
-        // can be made to eat all your memory.
-        if (body.length > 4096) req.destroy();
-      });
-      req.on('end', () => {
-        let parsed = {};
-        try {
-          parsed = JSON.parse(body);
-        } catch {
-          /* handled by the check below */
-        }
-
-        // Any page in any tab can POST to localhost. The nonce is what proves
-        // this response belongs to the login WE just started.
-        if (parsed.state !== state || typeof parsed.key !== 'string' || !parsed.key) {
-          res.writeHead(400).end();
-          return;
-        }
-
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end('{"ok":true}');
-        server.close();
-        resolve({
-          key: parsed.key.trim(),
-          tier: parsed.tier || 'free',
-          email: parsed.email || '',
-        });
-      });
-    });
-
-    server.on('error', reject);
-
-    // Port 0 = let the OS pick. Bound to loopback only, so nothing on the
-    // network can reach it.
-    server.listen(0, '127.0.0.1', () => {
-      const { port } = server.address();
-      const url = `${SITE}/cli/login?port=${port}&state=${state}`;
-
-      log('');
-      log(`  Opening ${cyan(url)}`);
-      log(dim('  If your browser did not open, paste that URL into a browser on this computer.'));
-      log('');
-      log(dim('  Waiting for you to finish signing in...'));
-
-      openBrowser(url);
-    });
-
-    setTimeout(() => {
-      server.close();
-      reject(new Error('Timed out waiting for the browser (5 minutes).'));
-    }, LOGIN_TIMEOUT_MS).unref();
-  });
-}
-
-async function login() {
-  const root = process.cwd();
-
-  let result;
-  try {
-    result = await awaitKeyFromBrowser();
-  } catch (err) {
-    fail(`${err.message}\n  Nothing was written.`);
-    return;
-  }
-
-  const varName = detectEnvVarName(root);
-  const fileName = envFileFor(varName, result.tier);
-  const file = writeEnvVar(root, varName, result.key, fileName);
-  // An earlier login may have left the key in .env.local; a free key there
-  // would still ride along into release builds.
-  const moved = fileName !== '.env.local' && removeEnvVar(root, varName, '.env.local');
-  const addedIgnore = ensureGitignored(root, fileName);
-  const relative = path.relative(root, file) || fileName;
-
-  log('');
-  log(
-    `${green('OK')} Signed in${result.email ? ' as ' + bold(result.email) : ''} - ${bold(result.tier)} tier`
-  );
-  log(`  Wrote ${cyan(varName)} to ${cyan(relative)}`);
-  if (moved) log(dim(`  Removed the old ${varName} line from .env.local`));
-  if (fileName === '.env.development.local') {
-    log(dim('  This file is loaded in development, keeping the key out of production builds.'));
-  }
-  if (addedIgnore) log(dim(`  Added ${fileName} to .gitignore`));
-  log('');
-  log('  Use it in your app:');
-  log('');
-  if (varName === 'VITE_BUOY_KEY') {
-    log(cyan('    <FloatingDevTools modules={modules} licenseKey={import.meta.env.VITE_BUOY_KEY} />'));
-    log('');
-    log(dim('  Keep your existing tool modules and providers, then reload the web app.'));
-  } else {
-    log(cyan(`    Buoy.init({ licenseKey: ${varName} });`));
-    log('');
-    log(dim('  Swift: pass the key through BuoyConfig.licenseKey in your development build.'));
-    log(dim('  Bare React Native does not load .env.local automatically; wire your existing env loader.'));
-  }
-  log('');
-}
-
-function help() {
-  log(`
-  ${bold('buoy')} - React Buoy CLI
-
-  ${bold('Usage')}
+"use strict";const http=require("node:http");const fs=require("node:fs");const path=require("node:path");const crypto=require("node:crypto");const{spawn}=require("node:child_process");const SITE=process.env.BUOY_SITE_URL||"https://buoy.gg";const LOGIN_TIMEOUT_MS=5*60*1e3;const ESC="\x1B[";const color=e=>o=>`${ESC}${e}m${o}${ESC}0m`;const cyan=color(36);const green=color(32);const red=color(31);const dim=color(2);const bold=color(1);function log(e){process.stdout.write(`${e}
+`)}function fail(e){process.stderr.write(`${red("x")} ${e}
+`);process.exit(1)}function openBrowser(e){const o=process.platform==="darwin"?"open":process.platform==="win32"?"cmd":"xdg-open";const s=process.platform==="win32"?["/c","start","",e]:[e];try{spawn(o,s,{stdio:"ignore",detached:true}).unref()}catch{}}function detectEnvVarName(e){let o=null;try{const s=path.join(e,"package.json");if(fs.existsSync(s)){const i=JSON.parse(fs.readFileSync(s,"utf8"));const n=Object.assign({},i.dependencies,i.devDependencies);if(n.expo)return"EXPO_PUBLIC_BUOY_KEY";if(n.next)o="NEXT_PUBLIC_BUOY_KEY";else if(n.vite)o="VITE_BUOY_KEY"}if(fs.existsSync(path.join(e,"app.config.js"))||fs.existsSync(path.join(e,"app.config.ts"))){return"EXPO_PUBLIC_BUOY_KEY"}const t=path.join(e,"app.json");if(fs.existsSync(t)){const i=JSON.parse(fs.readFileSync(t,"utf8"));if(i&&i.expo)return"EXPO_PUBLIC_BUOY_KEY"}}catch{}return o||"BUOY_KEY"}function envFileFor(e,o){if(!["EXPO_PUBLIC_BUOY_KEY","VITE_BUOY_KEY","NEXT_PUBLIC_BUOY_KEY"].includes(e))return".env.local";return o==="pro"||o==="business"?".env.local":".env.development.local"}function removeEnvVar(e,o,s){const t=path.join(e,s);let i;try{i=fs.readFileSync(t,"utf8")}catch{return false}const n=new RegExp("^"+o+"=.*\\n?","m");if(!n.test(i))return false;fs.writeFileSync(t,i.replace(n,""),{mode:384});return true}function writeEnvVar(e,o,s,t=".env.local"){const i=path.join(e,t);let n="";try{n=fs.readFileSync(i,"utf8")}catch{}const c=`${o}=${s}`;const r=new RegExp("^"+o+"=.*$","m");if(r.test(n)){n=n.replace(r,c)}else{if(n&&!n.endsWith("\n"))n+="\n";n+=`${c}
+`}fs.writeFileSync(i,n,{mode:384});return i}function ensureGitignored(e,o=".env.local"){const s=path.join(e,".gitignore");let t="";try{t=fs.readFileSync(s,"utf8")}catch{return false}const i=new RegExp("^"+o.replace(/\./g,"\\.")+"$","m");if(i.test(t)||/^\.env\*|^\*\.local$|^\.env\*\.local$/m.test(t))return false;if(t&&!t.endsWith("\n"))t+="\n";t+=`
+# Buoy license key (per developer - do not commit)
+${o}
+`;fs.writeFileSync(s,t);return true}function awaitKeyFromBrowser(){return new Promise((e,o)=>{const s=crypto.randomBytes(16).toString("hex");const t=http.createServer((i,n)=>{if(i.headers.origin===SITE){n.setHeader("Access-Control-Allow-Origin",SITE);n.setHeader("Access-Control-Allow-Headers","Content-Type");n.setHeader("Access-Control-Allow-Methods","POST, OPTIONS");n.setHeader("Access-Control-Allow-Private-Network","true")}if(i.method==="OPTIONS"){n.writeHead(204).end();return}if(i.method!=="POST"){n.writeHead(405).end();return}let c="";i.on("data",r=>{c+=r;if(c.length>4096)i.destroy()});i.on("end",()=>{let r={};try{r=JSON.parse(c)}catch{}if(r.state!==s||typeof r.key!=="string"||!r.key){n.writeHead(400).end();return}n.writeHead(200,{"Content-Type":"application/json"});n.end('{"ok":true}');t.close();e({key:r.key.trim(),tier:r.tier||"free",email:r.email||""})})});t.on("error",o);t.listen(0,"127.0.0.1",()=>{const{port:i}=t.address();const n=`${SITE}/cli/login?port=${i}&state=${s}`;log("");log(`  Opening ${cyan(n)}`);log(dim("  If your browser did not open, paste that URL into a browser on this computer."));log("");log(dim("  Waiting for you to finish signing in..."));openBrowser(n)});setTimeout(()=>{t.close();o(new Error("Timed out waiting for the browser (5 minutes)."))},LOGIN_TIMEOUT_MS).unref()})}async function login(){const e=process.cwd();let o;try{o=await awaitKeyFromBrowser()}catch(a){fail(`${a.message}
+  Nothing was written.`);return}const s=detectEnvVarName(e);const t=envFileFor(s,o.tier);const i=writeEnvVar(e,s,o.key,t);const n=t!==".env.local"&&removeEnvVar(e,s,".env.local");const c=ensureGitignored(e,t);const r=path.relative(e,i)||t;log("");log(`${green("OK")} Signed in${o.email?" as "+bold(o.email):""} - ${bold(o.tier)} tier`);log(`  Wrote ${cyan(s)} to ${cyan(r)}`);if(n)log(dim(`  Removed the old ${s} line from .env.local`));if(t===".env.development.local"){log(dim("  This file is loaded in development, keeping the key out of production builds."))}if(c)log(dim(`  Added ${t} to .gitignore`));log("");log("  Use it in your app:");log("");if(s==="VITE_BUOY_KEY"){log(cyan("    <FloatingDevTools modules={modules} licenseKey={import.meta.env.VITE_BUOY_KEY} />"));log("");log(dim("  Keep your existing tool modules and providers, then reload the web app."))}else if(s==="NEXT_PUBLIC_BUOY_KEY"){log(cyan("    <FloatingDevTools modules={modules} licenseKey={process.env.NEXT_PUBLIC_BUOY_KEY} />"));log("");log(dim("  Restart next dev so it picks up the new variable."))}else{log(cyan(`    Buoy.init({ licenseKey: ${s} });`));log("");log(dim("  Swift: pass the key through BuoyConfig.licenseKey in your development build."));log(dim("  Bare React Native does not load .env.local automatically; wire your existing env loader."))}log("")}function help(){log(`
+  ${bold("buoy")} - React Buoy CLI
+
+  ${bold("Usage")}
     npx --package=@buoy-gg/core buoy <command>
 
-  ${dim('(if npx picks the wrong one)')}
+  ${dim("(if npx picks the wrong one)")}
 
-  ${bold('Commands')}
+  ${bold("Commands")}
     login     Sign in and write your license key to an env file
     help      Show this message
 
-  ${bold('Notes')}
+  ${bold("Notes")}
     Run login from your app directory. Complete browser sign-in to receive
-    your account key. Expo uses EXPO_PUBLIC_BUOY_KEY; Vite uses VITE_BUOY_KEY.
-    For both, a free key goes to .env.development.local and a paid key goes
-    to .env.local. Other projects receive BUOY_KEY in .env.local and must
+    your account key. Expo uses EXPO_PUBLIC_BUOY_KEY, Vite uses VITE_BUOY_KEY
+    and Next.js uses NEXT_PUBLIC_BUOY_KEY. For these, a free key goes to
+    .env.development.local and a paid key goes to .env.local. Other projects receive BUOY_KEY in .env.local and must
     configure their own environment loader and variable mapping.
     This command does not install tools or verify a Desktop connection.
 
     Docs: ${SITE}/buoy/latest/docs/installation
-`);
-}
-
-// Only dispatch when run as a program. Without this guard, importing the file
-// in a test would parse the test runner's own argv and exit the process.
-if (require.main === module) {
-  const command = process.argv[2];
-
-  if (command === 'login') {
-    login();
-  } else if (!command || command === 'help' || command === '--help' || command === '-h') {
-    help();
-  } else {
-    fail(`Unknown command: ${command}\n  Run \`npx buoy help\` to see what is available.`);
-  }
-}
-
-module.exports = {
-  detectEnvVarName,
-  envFileFor,
-  writeEnvVar,
-  removeEnvVar,
-  ensureGitignored,
-  awaitKeyFromBrowser,
-};
+`)}if(require.main===module){const e=process.argv[2];if(e==="login"){login()}else if(!e||e==="help"||e==="--help"||e==="-h"){help()}else{fail(`Unknown command: ${e}
+  Run \`npx buoy help\` to see what is available.`)}}module.exports={detectEnvVarName,envFileFor,writeEnvVar,removeEnvVar,ensureGitignored,awaitKeyFromBrowser};

package/lib/commonjs/Buoy.js

@@ -1,107 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.default = exports.Buoy = void 0;
-exports.isTelemetryEnabled = isTelemetryEnabled;
-var _license = require("@buoy-gg/license");
-/**
- * Buoy SDK - Main entry point for React Buoy configuration
- *
- * Initialize once at app startup, before rendering any components:
- *
- * @example
- * ```tsx
- * import { Buoy } from '@buoy-gg/core';
- *
- * Buoy.init({
- *   licenseKey: 'YOUR_LICENSE_KEY',
- * });
- * ```
- */
-
-/**
- * Telemetry stays on unless an app explicitly opts out. Read at ping time
- * rather than captured, so `Buoy.init()` still wins if it runs after mount.
- */
-let telemetryEnabled = true;
-
-/** Whether the anonymous install ping is allowed to fire. */
-function isTelemetryEnabled() {
-  return telemetryEnabled;
-}
-
-/**
- * Buoy SDK namespace
- *
- * Use `Buoy.init()` to configure your license key at app startup.
- */
-const Buoy = exports.Buoy = {
-  /**
-   * Initialize Buoy with your license key
-   *
-   * Call this once at app startup, before rendering FloatingDevTools.
-   * Typically placed in App.tsx or index.js.
-   *
-   * @example
-   * ```tsx
-   * import { Buoy } from '@buoy-gg/core';
-   *
-   * // With hardcoded key
-   * Buoy.init({
-   *   licenseKey: '36063C-27282E-8E73F5-55488F-2213DF-V3',
-   * });
-   *
-   * // With environment variable
-   * Buoy.init({
-   *   licenseKey: process.env.BUOY_LICENSE_KEY!,
-   * });
-   * ```
-   */
-  init(config) {
-    if (config.telemetry === false) telemetryEnabled = false;
-    void _license.LicenseManager.configure(config.licenseKey).catch(error => {
-      console.warn("[Buoy] License initialization failed:", error);
-    });
-  },
-  /**
-   * Initialize Buoy asynchronously
-   *
-   * Use this if you need to wait for initialization to complete.
-   *
-   * @example
-   * ```tsx
-   * await Buoy.initAsync({
-   *   licenseKey: 'YOUR_LICENSE_KEY',
-   * });
-   * console.log('Buoy is ready!');
-   * ```
-   */
-  async initAsync(config) {
-    if (config.telemetry === false) telemetryEnabled = false;
-    return _license.LicenseManager.configure(config.licenseKey);
-  },
-  /**
-   * Check if Buoy Pro is active
-   */
-  isPro() {
-    return _license.LicenseManager.isPro();
-  },
-  /**
-   * Get the current license state
-   */
-  getState() {
-    return _license.LicenseManager.getState();
-  },
-  /**
-   * Force device re-registration (debugging helper)
-   * Clears cached fingerprint so next init will register device again
-   */
-  async forceReregister() {
-    await _license.LicenseManager.forceReregister();
-  }
-};
-
-// Also export as default for flexibility
-var _default = exports.default = Buoy;
+"use strict";Object.defineProperty(exports,"__esModule",{value:true});exports.default=exports.Buoy=void 0;exports.isTelemetryEnabled=isTelemetryEnabled;var _license=require("@buoy-gg/license");let telemetryEnabled=true;function isTelemetryEnabled(){return telemetryEnabled}const Buoy=exports.Buoy={init(e){if(e.telemetry===false)telemetryEnabled=false;void _license.LicenseManager.configure(e.licenseKey).catch(r=>{console.warn("[Buoy] License initialization failed:",r)})},async initAsync(e){if(e.telemetry===false)telemetryEnabled=false;return _license.LicenseManager.configure(e.licenseKey)},isPro(){return _license.LicenseManager.isPro()},getState(){return _license.LicenseManager.getState()},async forceReregister(){await _license.LicenseManager.forceReregister()}};var _default=exports.default=Buoy;