docs(readme): star-growth polish — positioning, badges, screenshots, comparison

[hoainho]

What this changes

Conversion-killer fixes from the star-growth research session. Pure docs/README, zero code touched.

Above the fold

• Stars badge + npm downloads badge added — social proof + FOMO
• New 1-line positioning statement: "The only Chrome extension that unifies React Timeline + Performance + Memory + Side Effects + Redux + CLS + AI analysis into a single DevTools tab — zero install in your app."
• ⚡ Try it in 30 seconds section with npx command above the fold
• Replaced the broken MP4 link with inline GIF reference (the linked MP4 react-ext-demo-3x.mp4 doesn't exist in docs/video/)

Why this extension

Expanded from 4 to 5 competitors with concrete weakness for each:

• react-devtools — no CLS, no memory leak detection
• Chrome Perf tab — no React context
• Redux DevTools — isolated from render cycle
• react-scan — requires app-code changes; no Redux/CLS/memory
• why-did-you-render — console-only, needs Babel

Then leads with the defensible triple-lock thesis: CLS overlay + useEffect audit + AI analysis — no other tool combines these.

Screenshots section

6 inline tab screenshots (Timeline, Performance, Memory, Side Effects, CLS, Redux) using existing assets in docs/images/. Audit flagged that these existed but were never surfaced in the README body.

Comparison table

8 features × 5 tools (React Debugger / react-devtools / react-scan / why-did-you-render / redux-devtools) — bold rows on the 3 features no competitor combines.

Star CTA + star-history chart

End-of-README "⭐ If this saves you time, please star" with star-history.com chart + Watch-releases prompt.

Why

Based on the competitive positioning research + repo audit. Current state: 14 stars. Goal: ship the conversion-killer fixes BEFORE driving any traffic, because driving traffic to a broken funnel is malpractice.

Net diff

+56 / -6 lines. No code, no behavior change.

Risk

Zero — README only. CI will re-run but no logic changes.

[gemini-code-assist]

Code Review

This pull request establishes a pluggable detector registry foundation, introduces React version adapters (supporting React 17 through 19.2), and migrates several detectors (including reconciler-keys, scan-overlay, and closure-leak) to this new architecture. Feedback on the changes highlights a critical bug in site-enablement checks post-migration, potential crash risks in fiber traversal and display name resolution, missing error handling in settings persistence, and opportunities to optimize traversal budgets and preserve pending render flashes during busy idle periods.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Once the settings migration is completed (migrationDone is true), any subsequent calls to checkIfSiteEnabled will fall back to querying the legacy STORAGE_KEY (react_debugger_disabled_sites). However, the migration process deletes this legacy key from storage. As a result, subsequent checks will read undefined, causing the debugger to be enabled on all sites and ignoring any site-specific overrides configured in the new settings.

Instead of falling back to the legacy key, we should always use the migrated settings. Since migrate() is idempotent and safely returns the existing settings if they already exist, we can simplify this function to always use migrate().

async function checkIfSiteEnabled(): Promise<boolean> {
  try {
    const hostname = window.location.hostname;
    const result = await migrate();
    const siteOverride = result.settings.perSite[hostname];
    if (siteOverride?.detectors) {
      const allDisabled = Object.values(siteOverride.detectors).every(
        (d) => !d.enabled
      );
      if (allDisabled) return false;
    }
    return true;
  } catch {
    return true;
  }
}

[gemini-code-assist]

If root is null or undefined, stack is initialized with [root]. When popped, fiber will be null, and accessing fiber.sibling or fiber.child outside of the try/catch block will throw a TypeError: Cannot read properties of null, crashing the traversal.

Additionally, the visitor currently returns void, meaning there is no way to abort the traversal early (e.g., when a budget/deadline is exceeded). We should allow the visitor to return boolean and break the loop if it returns false.

Suggested change

	export function walkFiberImpl(
	root: FiberNode,
	visitor: (fiber: FiberNode) => void,
	maxNodes = 5000,
	): void {
	export function walkFiberImpl(
	root: FiberNode,
	visitor: (fiber: FiberNode) => void | boolean,
	maxNodes = 5000,
	): void {
	if (root === null || root === undefined) return;
	let count = 0;
	const stack: FiberNode[] = [root];
	while (stack.length > 0 && count < maxNodes) {
	const fiber = stack.pop()!;
	count++;
	try {
	if (visitor(fiber) === false) {
	break;
	}
	} catch {
	// visitor errors must not abort the walk
	}

[gemini-code-assist]

With the updated walkFiberImpl supporting early termination, we should return false when the deadline is exceeded to stop the traversal immediately. Currently, returning void only skips the current node but continues traversing the rest of the tree (up to 5000 nodes), wasting CPU cycles.

Suggested change

	walkFiberImpl(root.current, (fiber) => {
	// Cheap deadline check — performance.now() is also cheap, but bail
	// out without doing the per-list work when we're already over.
	if (context.performance.now() > deadline) return;
	walkFiberImpl(root.current, (fiber) => {
	// Cheap deadline check — performance.now() is also cheap, but bail
	// out without doing the per-list work when we're already over.
	if (context.performance.now() > deadline) return false;

[gemini-code-assist]

If deadline.timeRemaining() <= 0 and it is not a forced run, the pending flashes are cleared (pending = []) and permanently dropped. This means the user will miss visual render flashes if the browser is temporarily busy.

Instead of dropping the batch, we should keep the items in pending and return early, allowing them to be painted on the next idle callback.

        if (deadline.timeRemaining() <= 0 && !deadline.didTimeout) {
          // No budget left and not a forced run — keep this batch for the next idle tick
          return;
        }
        const items = pending;
        pending = [];
        bridge.paint(items);

[gemini-code-assist]

The asynchronous write(updated) call is not wrapped in a try/catch block. If persisting to chrome.storage.local fails (e.g., due to quota limits or an invalidated extension context), the promise rejection will go unhandled, potentially crashing the panel or leaving the UI state out of sync with storage.

We should wrap the write operation in a try/catch block and revert the local state if it fails.

  const handleGlobalToggle = async (detectorId: string) => {
    if (!settings) return;
    const current = settings.detectors[detectorId];
    const currentEnabled = current?.enabled ?? false;
    const updated: Settings = {
      ...settings,
      detectors: {
        ...settings.detectors,
        [detectorId]: {
          ...current,
          enabled: !currentEnabled,
        },
      },
    };
    setSettings(updated);
    try {
      await write(updated);
    } catch (err) {
      setSettings(settings);
      console.error('Failed to save settings:', err);
    }
  };

[gemini-code-assist]

The parseSemver function expects a strict major.minor.patch format. If a React version string is non-standard or missing the patch version (e.g., "19", "19.2"), it returns [0, 0, 0], falling back to the React 17 adapter.

We should make the regex more robust by allowing optional minor and patch segments.

Suggested change

	/**
	* Parse a semver string into [major, minor, patch].
	* Returns [0, 0, 0] for unparseable strings.
	*/
	function parseSemver(version: string): [number, number, number] {
	const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
	if (!match) return [0, 0, 0];
	return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
	}
	function parseSemver(version: string): [number, number, number] {
	const match = version.match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
	if (!match) return [0, 0, 0];
	return [
	parseInt(match[1], 10),
	match[2] ? parseInt(match[2], 10) : 0,
	match[3] ? parseInt(match[3], 10) : 0,
	];
	}

[gemini-code-assist]

Throwing a hard error in getDisplayName is risky. If an unexpected tag is encountered in production, throwing an error can crash the host application's commit phase if not caught properly. It is safer to return null or log a warning to degrade gracefully.

  // Tags that CANNOT exist in r17 — return null to degrade gracefully
  if (tag === 26 || tag === 27 || tag === 28 || tag === 29 || tag === 30 || tag === 31) {
    return null;
  }