@atlassian/chippy 0.0.1-beta.1 → 0.0.1-beta.2

package/lib/extension/chippy-page-bridge.js

@@ -8,6 +8,16 @@
   /** @type {ChippyPageRuntime} */
   const chippy = global.__CHIPPY = global.__CHIPPY || {};
   const BRIDGE_VERSION = '0.2.5';
+  // Returned by every command that needs __AVALANCHE__.bridge when the Avalanche
+  // runtime is absent. The helper reports it as an unavailable runtime rather
+  // than an empty result, so callers never read `count: 0` as "nothing found".
+  const BRIDGE_MODULE_MISSING = Object.freeze({
+    ok: false,
+    code: 'bridge-module-missing',
+    error: 'bridge module not loaded',
+  });
+  // Read and removed by startup-handoff.js on the next document.
+  const STARTUP_HANDOFF_KEY = '__chippyStartupHandoff';
   if (chippy.pageBridge) {
     // Always tear down and reinstall — version-equality skip caused stale code to win.
     try { chippy.pageBridge.destroy?.(); } catch (e) {}
@@ -37,18 +47,53 @@
     return config?.integration || global.__CHIPPY_OWNER__?.integration || null;
   }
 
+  // Same-origin frames share sessionStorage, so each frame keys its id by its
+  // position in the frame tree; the Storybook manager and its preview iframe
+  // must not share one client id. The top frame keeps the original key.
+  function frameKeySuffix() {
+    const path = [];
+    try {
+      /** @type {Window} */
+      let current = global;
+      while (current !== current.parent && path.length < 16) {
+        const siblings = current.parent.frames;
+        let index = -1;
+        for (let i = 0; i < siblings.length; i += 1) {
+          if (siblings[i] === current) { index = i; break; }
+        }
+        path.unshift(index);
+        current = current.parent;
+      }
+    } catch {
+      return path.length ? ':frame' : '';
+    }
+    return path.length ? ':' + path.join('.') : '';
+  }
+
   function getStoredClientId() {
+    const key = '__chippyClientId' + frameKeySuffix();
     try {
-      const existing = global.sessionStorage?.getItem('__chippyClientId');
+      const existing = global.sessionStorage?.getItem(key);
       if (existing) return existing;
       const next = global.crypto?.randomUUID?.() || `chippy-${Date.now()}`;
-      global.sessionStorage?.setItem('__chippyClientId', next);
+      global.sessionStorage?.setItem(key, next);
       return next;
     } catch {
       return `chippy-${Date.now()}`;
     }
   }
 
+  // The extension is the fallback integration. A live owner of another kind,
+  // such as the Storybook addon in its manager window, outranks it.
+  function isLiveForeignOwner(owner) {
+    if (!owner || !owner.integration || owner.integration.kind === 'extension') return false;
+    return !owner.staleAfterMs || Date.now() - (owner.heartbeatAt || 0) <= owner.staleAfterMs;
+  }
+
+  function isExtensionBridge() {
+    return config?.integration?.kind === 'extension';
+  }
+
   function getStoryId() {
     const params = new URLSearchParams(global.location.search || '');
     return params.get('id') || null;
@@ -363,6 +408,7 @@
   let onLayoutLabUpdate = null;
   let onWindowMessage = null;
   let onExtCommand = null;
+  let onOwnerClaimed = null;
   let publishTimer = null;
   let snapshotSequence = 0;
   let lastLocationHref = global.location.href;
@@ -542,18 +588,55 @@
     const b = getBridge();
     return b
       ? b.readAvalancheStatus(getAvalancheApi(), getAvalancheModule())
-      : { ok: false, available: false, error: 'bridge module not loaded' };
+      : { ok: false, available: false, ...BRIDGE_MODULE_MISSING };
   }
 
   function evalAvalanche(command) {
     const b = getBridge();
     if (!b) {
       const action = String(command?.action || 'status');
-      return { ok: false, available: false, action, error: 'bridge module not loaded' };
+      return { ok: false, available: false, action, ...BRIDGE_MODULE_MISSING };
     }
     return b.evalAvalanche(command, getAvalancheApi(), getAvalancheModule());
   }
 
+  // An armed reload must install Avalanche before the next document's React
+  // commits. The arm config travels in sessionStorage, which the next
+  // document's startup script reads synchronously; the extension registers that
+  // script for one navigation. Without the extension the wait times out and the
+  // page reloads anyway. Returns how early startup was prepared, for the ack.
+  function prepareReload(avalanche) {
+    if (!avalanche || !avalanche.autoStart) return Promise.resolve('not-armed');
+    try {
+      const startup = /** @type {any} */ (global).__CHIPPY_STARTUP_CONFIG || {};
+      global.sessionStorage.setItem(STARTUP_HANDOFF_KEY, JSON.stringify({
+        at: Date.now(),
+        helperBaseUrl: config.helperBaseUrl,
+        plugins: Array.isArray(startup.plugins) ? startup.plugins : undefined,
+        avalanche: avalanche,
+      }));
+    } catch (e) {
+      return Promise.resolve('storage-unavailable');
+    }
+    return new Promise(function(done) {
+      let settled = false;
+      function finish(state) {
+        if (settled) return;
+        settled = true;
+        global.document.removeEventListener('chippy-armed-reload-ready', onReady);
+        done(state);
+      }
+      function onReady(event) {
+        let detail = {};
+        try { detail = JSON.parse(String(event.detail || '{}')); } catch (e) {}
+        finish(detail.ok ? 'registered' : 'handoff-only');
+      }
+      global.document.addEventListener('chippy-armed-reload-ready', onReady);
+      setTimeout(function() { finish('handoff-only'); }, 500);
+      global.document.dispatchEvent(new CustomEvent('chippy-armed-reload-prepare'));
+    });
+  }
+
   function handleCommand(command) {
     switch (command?.type) {
       case 'activate':
@@ -581,15 +664,19 @@
         setContextUiEnabled(command.enabled !== false, 'set-context-ui');
         break;
       case 'reload':
-        try { send({ type: 'reload-ack', clientId, requestId: command.requestId || null }); } catch (e) {}
-        setTimeout(function() { try { window.location.reload(); } catch (e) {} }, 50);
+        prepareReload(command.avalanche).then(function(earlyStartup) {
+          try { send({ type: 'reload-ack', clientId, requestId: command.requestId || null, earlyStartup: earlyStartup }); } catch (e) {}
+          setTimeout(function() { try { window.location.reload(); } catch (e) {} }, 50);
+        });
         break;
       case 'storybook-force-remount': {
         // The Storybook addon owns the host API. The bridge only relays the
         // request so a Storybook SUT remount does not navigate its preview.
+        // The arm, when present, lets the addon install Avalanche before the
+        // remount commits.
         const remountEvent = new CustomEvent('chippy-storybook-force-remount', {
           cancelable: true,
-          detail: { requestId: command.requestId || null },
+          detail: { requestId: command.requestId || null, avalanche: command.avalanche || null },
         });
         global.dispatchEvent(remountEvent);
         try {
@@ -599,6 +686,7 @@
             requestId: command.requestId || null,
             action: 'storybook-force-remount',
             ok: remountEvent.defaultPrevented,
+            error: remountEvent.defaultPrevented ? undefined : 'The Storybook preview did not remount: no rendered story matched the current selection',
           });
         } catch (e) {}
         break;
@@ -655,8 +743,9 @@
       }
       case 'find-fibers': {
         const requestId = command.requestId || null;
-        const result = evalFindFibers(command.filters || {});
-        send({ type: 'eval-probe-result', clientId, requestId, result });
+        Promise.resolve(evalFindFibers(command.filters || {}))
+          .then((result) => send({ type: 'eval-probe-result', clientId, requestId, result }))
+          .catch((e) => send({ type: 'eval-probe-result', clientId, requestId, result: { count: 0, items: [], error: e?.message || String(e) } }));
         break;
       }
       case 'capture-fiber-state': {
@@ -873,35 +962,40 @@
       if (!t) return null;
       return t.displayName || t.name || (typeof t === 'string' ? t : null);
     }
+    // Return the live HostRoot fiber of every React root. A FiberRoot (from
+    // `getFiberRoots`) exposes it as `.current`; a HostRoot fiber reached from a
+    // DOM container or by climbing `.return` may be the stale alternate, so it
+    // is re-resolved through its FiberRoot (`stateNode.current`).
     function getRootFibers() {
       const hook = devtoolsHook();
       const out = [];
-      if (!hook?.renderers) return out;
       const seen = new Set();
-      for (const [rendererId] of hook.renderers) {
-        try {
-          if (hook.getFiberRoots) {
+      function add(candidate) {
+        if (!candidate || typeof candidate !== 'object') return;
+        const fiberRoot = candidate.current ? candidate
+          : (candidate.tag === 3 && candidate.stateNode && candidate.stateNode.current ? candidate.stateNode : null);
+        const live = fiberRoot ? fiberRoot.current : candidate;
+        const key = fiberRoot || live;
+        if (!live || seen.has(key)) return;
+        seen.add(key);
+        out.push(live);
+      }
+      if (hook?.renderers && typeof hook.getFiberRoots === 'function') {
+        for (const [rendererId] of hook.renderers) {
+          try {
             const roots = hook.getFiberRoots(rendererId);
-            if (roots && typeof roots.forEach === 'function') {
-              roots.forEach((root) => {
-                if (root && !seen.has(root)) {
-                  seen.add(root);
-                  out.push(root);
-                }
-              });
-            }
-          }
-        } catch (_) {}
+            if (roots && typeof roots.forEach === 'function') roots.forEach(add);
+          } catch (_) {}
+        }
       }
-      // Robust fallback: walk all root containers via document
+      // Fallback for hooks without getFiberRoots: walk root containers in the document.
       const containers = document.querySelectorAll('[id], body div, body main');
       containers.forEach((el) => {
         const key = Object.keys(el).find((k) => k.startsWith('__reactContainer$') || k.startsWith('__reactFiber$'));
         if (!key) return;
         let fiber = el[key];
-        // climb to root
         while (fiber && fiber.return) fiber = fiber.return;
-        if (fiber && !seen.has(fiber)) { seen.add(fiber); out.push(fiber); }
+        add(fiber);
       });
       return out;
     }
@@ -1119,7 +1213,7 @@
   // Delegated to avalanche.iife.js — see src/chippy-bridge/fiber-invoke.ts
   function evalFiberPropContract(fiberId, propName) {
     const b = getBridge();
-    if (!b || !b.evalFiberPropContract) return { ok: false, error: 'bridge module not loaded' };
+    if (!b || !b.evalFiberPropContract) return { ok: false, ...BRIDGE_MODULE_MISSING };
     return b.evalFiberPropContract(fiberId, propName, {
       normalizeRememberedFiberId,
       getRememberedFiber,
@@ -1130,7 +1224,7 @@
   // Returns a Promise. The handler routes async responses through `send` once resolved.
   function evalFiberInvoke(fiberId, propName, args) {
     const b = getBridge();
-    if (!b || !b.evalFiberInvoke) return Promise.resolve({ ok: false, error: 'bridge module not loaded' });
+    if (!b || !b.evalFiberInvoke) return Promise.resolve({ ok: false, ...BRIDGE_MODULE_MISSING });
     return Promise.resolve(b.evalFiberInvoke(fiberId, propName, args, {
       normalizeRememberedFiberId,
       getRememberedFiber,
@@ -1143,7 +1237,7 @@
   function evalFiberScheduleUpdate(fiberId, ownerIndex) {
     const b = getBridge();
     if (!b || !b.evalFiberScheduleUpdate) {
-      return { ok: false, reason: 'no-scheduleUpdate', error: 'bridge module not loaded' };
+      return { ok: false, reason: 'no-scheduleUpdate', ...BRIDGE_MODULE_MISSING };
     }
     return b.evalFiberScheduleUpdate(fiberId, ownerIndex, {
       normalizeRememberedFiberId,
@@ -1154,7 +1248,7 @@
   // Delegated to avalanche.iife.js — see src/chippy-bridge/eval-helpers.ts
   function evalElementDom(element, parentLevel) {
     const b = getBridge();
-    if (!b) return { error: 'bridge module not loaded' };
+    if (!b) return { ...BRIDGE_MODULE_MISSING };
     return b.evalElementDom(element, parentLevel, window.getComputedStyle.bind(window));
   }
 
@@ -1167,14 +1261,14 @@
   // Delegated to avalanche.iife.js — see src/chippy-bridge/eval-helpers.ts
   function evalFiberProps(baseFiber, ownerIndex) {
     const b = getBridge();
-    if (!b) return { error: 'bridge module not loaded' };
+    if (!b) return { ...BRIDGE_MODULE_MISSING };
     return b.evalFiberProps(baseFiber, ownerIndex, chippy.layoutLab?.getHookSummary, resolveOwnerFiber);
   }
 
   // Delegated to avalanche.iife.js — see src/chippy-bridge/eval-helpers.ts
   function evalFiberPropValue(baseFiber, propName, ownerIndex) {
     const b = getBridge();
-    if (!b) return { error: 'bridge module not loaded' };
+    if (!b) return { ...BRIDGE_MODULE_MISSING };
     return b.evalFiberPropValue(baseFiber, propName, ownerIndex, chippy.layoutLab?.getHookSummary, resolveOwnerFiber, safeSerialize);
   }
 
@@ -1188,7 +1282,7 @@
 
   function summarizeHookList(raw) {
     const b = getBridge();
-    return b ? b.summarizeHookList(raw) : (raw || { error: 'bridge module not loaded' });
+    return b ? b.summarizeHookList(raw) : (raw || { ...BRIDGE_MODULE_MISSING });
   }
 
   function formatCounts(counts) {
@@ -1372,15 +1466,20 @@
   }
 
   // Delegated to avalanche.iife.js — see src/chippy-bridge/eval-helpers.ts
-  function evalFindFibers(filters) {
+  async function evalFindFibers(filters) {
     const b = getBridge();
-    if (!b) return { count: 0, items: [], error: 'bridge module not loaded' };
-    return b.evalFindFibers(filters, buildScriptHelpers([]), rememberFiber);
+    if (!b) return { count: 0, items: [], ...BRIDGE_MODULE_MISSING };
+    const result = b.evalFindFibers(filters, buildScriptHelpers([]), rememberFiber);
+    // Map each item's source through the served module, as `explain` does.
+    if (b.resolveFindFiberSources && b.resolveFiberSource) {
+      await b.resolveFindFiberSources(result.items, getRememberedFiber, b.resolveFiberSource);
+    }
+    return result;
   }
 
   function evalCaptureFiberState(options) {
     const b = getBridge();
-    if (!b?.captureFiberState) return { ok: false, error: 'bridge module not loaded' };
+    if (!b?.captureFiberState) return { ok: false, ...BRIDGE_MODULE_MISSING };
     const helpers = buildScriptHelpers([]);
     return b.captureFiberState({
       ...options,
@@ -1393,7 +1492,7 @@
 
   function evalCompareFiberStates(before, after, options) {
     const b = getBridge();
-    if (!b?.compareFiberStates) return { ok: false, error: 'bridge module not loaded' };
+    if (!b?.compareFiberStates) return { ok: false, ...BRIDGE_MODULE_MISSING };
     return b.compareFiberStates(before, after, options);
   }
 
@@ -1401,7 +1500,7 @@
   // extension shim stays version-coupled but implementation-free.
   function evalBoundaryChain(fiber, max) {
     const b = getBridge();
-    if (!b) return { ok: false, error: 'bridge module not loaded' };
+    if (!b) return { ok: false, ...BRIDGE_MODULE_MISSING };
     return b.inspectDeclarativeBoundaryChain(fiber, max, {
       rememberFiber,
       getFiberDomNode: getAvalancheApi()?.layoutLab?.getFiberDomNode || getFiberDomNode,
@@ -1422,7 +1521,7 @@
 
   function evalPageBoundaries(max) {
     const b = getBridge();
-    if (!b) return { ok: false, error: 'bridge module not loaded' };
+    if (!b) return { ok: false, ...BRIDGE_MODULE_MISSING };
     const helpers = buildScriptHelpers([]);
     return b.inspectPageDeclarativeBoundaries(max, {
       rememberFiber,
@@ -1470,7 +1569,7 @@
     const fiber = getRememberedFiber(fiberId);
     if (!fiber) return { error: 'Unknown fiberId: ' + fiberId };
     const b = getBridge();
-    if (!b) return { error: 'bridge module not loaded' };
+    if (!b) return { ...BRIDGE_MODULE_MISSING };
     return b.inspectFiberStructure(fiber, fiberId, hookIndex, windowSize, replayComponentHooks, evalFiberHooks);
   }
 
@@ -1515,7 +1614,7 @@
 
   async function evalDescribeComponent(fiberIdRaw, nameRaw) {
     const b = getBridge();
-    if (!b) return { ok: false, error: 'bridge module not loaded' };
+    if (!b) return { ok: false, ...BRIDGE_MODULE_MISSING };
     const target = resolveFiberTarget(null, fiberIdRaw, nameRaw);
     if (target.error) return { ok: false, error: target.error };
     if (b.resolveFiberSource) await b.resolveFiberSource(target.fiber);
@@ -1576,7 +1675,7 @@
     const fiber = getRememberedFiber(fiberId);
     if (!fiber) return { error: 'Unknown fiberId: ' + fiberId };
     const b = getBridge();
-    if (!b) return { error: 'bridge module not loaded' };
+    if (!b) return { ...BRIDGE_MODULE_MISSING };
     return b.inspectFiberOwners(fiber, fiberId, buildScriptHelpers([]));
   }
 
@@ -1708,6 +1807,22 @@
   };
   global.document.addEventListener('chippy-ext-command', onExtCommand);
 
+  // An extension bridge that is already running stands down when another
+  // integration claims the page; the background's owner check covers bridges
+  // that have not loaded yet.
+  function standDown(owner) {
+    if (destroyed) return;
+    destroy();
+    try { chippy.layoutLab?.clearAll?.(); } catch (e) {}
+    try { chippy.layoutLab?.removeInPageUi?.(); } catch (e) {}
+    chippy.standDown = { at: Date.now(), owner: owner?.integration || null };
+    setConnState('yielded');
+  }
+  onOwnerClaimed = () => {
+    if (isExtensionBridge() && isLiveForeignOwner(global.__CHIPPY_OWNER__)) standDown(global.__CHIPPY_OWNER__);
+  };
+  global.addEventListener('chippy-owner-claimed', onOwnerClaimed);
+
   locationInterval = global.setInterval(() => {
     if (global.location.href !== lastLocationHref) {
       lastLocationHref = global.location.href;
@@ -1763,6 +1878,7 @@
     try { if (onLayoutLabUpdate) global.removeEventListener('layout-lab:update', onLayoutLabUpdate); } catch (e) {}
     try { if (onWindowMessage) global.removeEventListener('message', onWindowMessage); } catch (e) {}
     try { if (onExtCommand) global.document.removeEventListener('chippy-ext-command', onExtCommand); } catch (e) {}
+    try { if (onOwnerClaimed) global.removeEventListener('chippy-owner-claimed', onOwnerClaimed); } catch (e) {}
   }
 
   // ─── Public API ──────────────────────────────────────────────────────────
@@ -1829,5 +1945,9 @@
     chippy.layoutLab?.exposeDefaultMarkers?.();
   }
 
-  connect();
+  if (isExtensionBridge() && isLiveForeignOwner(global.__CHIPPY_OWNER__)) {
+    standDown(global.__CHIPPY_OWNER__);
+  } else {
+    connect();
+  }
 })(window);

package/lib/mcp-skill/README.md

@@ -73,7 +73,7 @@ Chippy supports three page-side integrations:
 | Module import | A page without the extension UI | Applies to the current document; import again after reload/navigation |
 | Storybook addon | A Storybook preview | Reconnects through preview annotations |
 
-On extension-owned pages, Chippy starts as a small bottom-corner launcher. Expanding it reveals one unified panel with compact `P1 — drag to source` and `P2 — drag to source` rows that act as both dock and probe detail. Dragging a probe out keeps the panel expanded; once placed, the probe is document-anchored and follows its target during page scroll. Helper and optional forward-port settings live behind its gear. Probe and connection updates patch existing controls in place, so drafts, focus, and the settings form survive ordinary refreshes. Active probes commit their annotation when the intent changes or Enter is pressed in the comment; Shift+Enter inserts a newline. The toolbar popup shows the Chippy mark and name with Enable and Disable for the current origin. Storybook is the intentional exception: its details live in the manager panel, so its preview frame retains a standalone probe dock.
+On extension-owned pages, Chippy starts as a small bottom-corner launcher. Expanding it reveals one unified panel with compact `P1 — drag to source` and `P2 — drag to source` rows that act as both dock and probe detail. Dragging a probe out keeps the panel expanded; once placed, the probe is document-anchored and follows its target during page scroll. The helper URL and plugin switches live behind its gear. Probe and connection updates patch existing controls in place, so drafts, focus, and the settings form survive ordinary refreshes. Active probes commit their annotation when the intent changes or Enter is pressed in the comment; Shift+Enter inserts a newline. The toolbar popup shows the Chippy mark and name with Enable and Disable for the current origin. Storybook is the intentional exception: its details live in the manager panel, so its preview frame retains a standalone probe dock.
 
 When the extension workflow fits, load this skill's `extension` folder through **Load unpacked** in the browser's extension developer mode. The module-import and Playwright recipes live in [playwright-cli-setup](references/playwright-cli-setup.md).
 
@@ -97,7 +97,7 @@ Chippy deliberately keeps different facts separate:
 - **DOM facts:** the exact element, text, attributes, styles, and nearest test-id boundary.
 - **React facts:** the fiber, component, owners, parents, props, hooks, and source metadata for the current snapshot.
 - **Declarative boundary facts:** every Error/Suspense ancestor around a target, or the whole page reduced to a boundary-only containment forest, including current Suspense content/fallback state.
-- **Jira context:** optional probe enrichment for recognized ownership markers and `JSErrorBoundary` metadata; it appears in both the in-page and Storybook probe details, defaults on, and does not replace source evidence.
+- **Jira context:** optional probe enrichment for recognized ownership markers and `JSErrorBoundary` metadata; it appears in both the in-page and Storybook probe details once the Jira plugin is enabled (it is off by default), and does not replace source evidence.
 - **Source facts:** what the reported file and code can do.
 - **Render facts:** which commits, sources, restarts, effects, context updates, and collateral occurred in the measured window.
 - **Action facts:** what the user or automation did immediately before a measured commit.
@@ -142,8 +142,6 @@ Performance work has three distinct entry points:
 - Probes and commit captures are evidence anchors. Preserve them until the question is answered and any edit is verified.
 - Development source resolution supports React <=18 `_debugSource` and React 19 `_debugStack` plus the dev server's source map. React 19 requires no JSX-runtime instrumentation when its development build and maps are available.
 - Production or minified pages can reduce source and component confidence. Chippy reports the boundary instead of inventing missing detail.
-- Browser extension file changes require an extension publish cycle; rebuilding the bundled runtime alone does not publish it.
-- New commands, options, fields, and behavior changes require shell, wire, type/DTO, test, and documentation parity.
 
 ## License
 

package/lib/mcp-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chippy
-description: Debug a running React page with live runtime evidence. Use to explore components (find by name, text, test id, file, or prop; explain structure and hooks), debug where an element, value, prop, or loading/error boundary comes from, compare two rendered states or pages, and investigate slow interactions, re-renders, and initial load with Avalanche commit capture. Connects through the Chippy browser extension or an injected bundle and a local helper; not for static code review without a running page.
+description: Debug a running React page with live runtime evidence. Use to explore components (find by name, text, test id, file, or prop; explain structure and hooks), debug where an element, value, prop, or loading/error boundary comes from, compare two rendered states or pages, and investigate slow interactions, re-renders, and initial load with Avalanche commit capture. Connects a local helper to the page through the browser extension, an agent-driven Playwright browser, the helper's local proxy, the Storybook addon, or a console/module import; not for static code review without a running page.
 allowed-tools: Bash(chippy.sh:*)
 ---
 
@@ -21,15 +21,15 @@ Use the running page as evidence. Connect visible React behavior to exact source
 
 ## Start every task
 
-1. If neither Chippy MCP tools nor this skill's scripts are installed, have the user run `npx @atlassian/chippy install` and follow its printed steps. Resolve this skill's absolute path; do not assume the current repository contains a relative copy. Prefer available Chippy MCP tools when permitted by the host; otherwise run this skill's `scripts/chippy.sh`.
+1. If neither Chippy MCP tools nor this skill's scripts are installed, have the user run `npx skills add atlassian-labs/chippy --skill chippy -g`; the skill then lives in `~/.agents/skills/chippy`, and its `extension` folder is the unpacked browser extension. Resolve this skill's absolute path; do not assume the current repository contains a relative copy. Prefer available Chippy MCP tools when permitted by the host; otherwise run this skill's `scripts/chippy.sh`.
 2. With MCP available, use `chippy_status` → `chippy_pages` → `chippy_snapshot` (refresh, then read). MCP starts/reuses the helper automatically; follow [MCP setup and tools](references/mcp.md). MCP covers inspection, Avalanche capture and analysis, interaction, and annotation waits; compare (`fiber-state-*`), `page-boundaries`, `avalanche-arm`, `reload-with-avalanche`, and `recipes` are CLI-only, so use `scripts/chippy.sh` for them. Otherwise run `health` → `pages` → `request-snapshot <clientId>`; helper-contacting shell commands must run outside the agent sandbox. The agent owns helper startup and command execution.
-3. Select the page by URL, title, integration identity, and recency. Resolve a fresh `clientId` every turn; a reload or navigation can replace it. When two pages match closely, ask which page is in scope.
+3. Select the page by URL, title, integration identity, and recency. When no page is connected, choose a route in [Connection and bootstrap](#connection-and-bootstrap); the extension is one route, not a prerequisite. Resolve a fresh `clientId` every turn; a reload or navigation can replace it. When two pages match closely, ask which page is in scope.
 4. Use the first read-only signal to leave ❓ Disorder and name the Cynefin domain. Then iterate with OODA inside that domain: observe one fact, orient it to the invariant and proof gap, decide one permitted move, act, and observe again.
 5. Choose the narrowest route below. Do not edit until the proof packet names the fix layer and a repeatable verification command.
 
 `health`, `pages`, `request-snapshot`, and reads of existing probe state are orientation. Active stimuli, diagnosis, and source edits are not.
 
-When an extension-connected page already has the target state, work there first. Use Playwright only when automation or replay is required, the user asks for it, or the connected page cannot provide the evidence.
+When a page connected in the user's own browser already has the target state, work there first. Use Playwright only when automation or replay is required, the user asks for it, or the connected page cannot provide the evidence.
 
 ## Route by question
 
@@ -45,7 +45,8 @@ Before `explain-component`, `describe-component`, or `inspect-fiber-structure`,
 | What is inside this component? | `explain-component`; use `describe-component` for the detailed hook tree | The component's structure is described, with replay status and warnings disclosed. |
 | What changed between two rendered states or pages? | `fiber-state-capture` before and after → `fiber-state-compare` | The bounded diff names matched fibers and added, removed, or changed props without returning either full capture. |
 | Why is an interaction slow or re-rendering? | `avalanche-arm` → reproduce the interaction → `avalanche-status` → hot sources / commit list / commit peek | Trigger, hotspot, collateral, and fix layer are distinguished. |
-| Why is initial load slow? | `reload-with-avalanche` → status / hot sources / commit analysis | The measured load window is bounded and repeatable. |
+| Why is initial load slow? | Confirm the page's route records the initial load ([Connection and bootstrap](#connection-and-bootstrap)) → `reload-with-avalanche` → status / hot sources / commit analysis | The measured load window is bounded and repeatable. |
+| Does the user want render evidence in tests or scripts, with no agent at run time? | Point to the standalone Avalanche detector in the [npm package documentation](https://github.com/atlassian-labs/chippy/blob/main/docs/npm-package.md#standalone-avalanche) | The test installs the detector before React DOM loads and reads `detector.report()`. |
 | Is this subtree stable? | Load [stability-render](references/stability-render.md) and run one controlled nudge | The capture yields clean, leak, leak+cascade, or trasher evidence. |
 | Which hook is suspicious? | Use `avalanche-debug-hook` only after a capture identifies `sourceId + hookIndex` | Primitive/custom-hook ownership and next remediation branch are named. |
 | Are state dispatches or memo/effect recomputations driving the cost? | Load [hook-metrics](references/hook-metrics.md) | A before/after counter or tracker result is joined to the same interaction. |
@@ -62,7 +63,7 @@ Use [bdd-router](references/bdd-router.md) when the situation needs the complete
 
 - A probe identifies one exact DOM element rendered by one bundle. Its source location, fiber, owner chain, and marker coordinates are facts for that snapshot.
 - Open `source.fileName` at `lineNumber` directly once it is an authored path. On React 19, an initial `http(s)` module URL is the generated fallback; read the following `*-source-resolved` snapshot or run `describe-component` before treating its line as a repository position. Do not grep for a file the probe already identified. Search is the last resort after the runtime-to-source chain is exhausted.
-- Development source metadata is version-dependent: React <=18 supplies `_debugSource`; React 19 supplies `_debugStack`. Chippy filters dependency frames, fetches the served module in the page realm, decodes its inline or external source map, and republishes the authored file/line. Absence of `_debugSource` alone is not production evidence.
+- Development source metadata is version-dependent: React <=18 supplies `_debugSource`; React 19 supplies `_debugStack`. Chippy filters dependency frames, fetches the served module in the page realm, decodes its inline or external source map, and republishes the authored file/line. It also corrects `_debugSource` lines that a dev-server transform shifted before JSX compilation, such as Vite's Fast Refresh header. `find-fibers`, `describe-component`, and `explain-component` return the mapped position. Absence of `_debugSource` alone is not production evidence.
 - Read every returned field. Props, owner indices, keys, test IDs, hook counts, and source locations can each change the next move.
 - Static source proves what code can do. Runtime evidence proves what happened in this run. Never promote code shape, a global's presence, or a hot component into a runtime cause.
 - Screenshots confirm appearance; they do not replace probe, fiber, action, or commit evidence.
@@ -118,13 +119,17 @@ Chippy has a local helper and one page-side integration. `chippy_pages` or
 helper startup without a shell command; it needs host access to the browser's
 network environment. Closing an MCP session preserves the shared helper.
 
-| Integration | Owner | Reload behavior |
-|---|---|---|
-| Browser extension | Chippy extension | Re-injects automatically for enabled origins. |
-| Console/module import | The current document | Full reload/navigation removes Chippy; run the import again. |
-| Storybook addon | Storybook preview annotations | `page-reload` uses Storybook `FORCE_REMOUNT` to remount the SUT without reloading the preview iframe. |
+Each route below loads the same page runtime. The extension is one delivery route; choose by who owns the browser and whether the task needs initial-load capture.
+
+| Route | Who sets it up | Reload behavior | Initial-load capture |
+|---|---|---|---|
+| Browser extension | User, once per browser and origin | Re-injects automatically for enabled origins. | Yes, with `reload-with-avalanche`: the armed reload runs the early scripts at `document_start`. |
+| Agent-driven Playwright browser | Agent; no extension | Init scripts load again on every navigation; the ad-hoc import must be repeated. | Only with the [pre-page start-up](references/mode-a-injection.md#pre-page-start-up) variant, which installs the detector before React on every document. The packaged loader and the ad-hoc import start the detector after connection. |
+| Local proxy (`proxy-start <targetPort> [originalUrl]`) | Agent; the user or Playwright opens the page on the helper port | The proxy adds Chippy to every load of the `originalUrl` path, so pass `originalUrl`. | Yes, with `reload-with-avalanche`: the shim and Avalanche run before page scripts. Targets on this machine only. |
+| Storybook addon (`addons: ['@atlassian/chippy/storybook']`, Storybook 10.3+) | User, in the Storybook configuration | `page-reload` uses Storybook `FORCE_REMOUNT` to remount the SUT without reloading the preview iframe. | The story's mount, through the remount. |
+| Console/module import, including `connectChippy()` from `@atlassian/chippy/browser` | User or page code, in the current document | Full reload/navigation removes Chippy; run the import again. | No: use mid-page capture. |
 
-The extension toolbar popup shows the Chippy mark and name with Enable and Disable for the current origin. The in-page UI starts as one small bottom-corner Chippy button. Expand it to reveal compact `P1 — drag to source` and `P2 — drag to source` rows; each row is the probe's dock and expands into its details once placed. Dragging a probe out keeps the panel expanded, and a placed probe is document-anchored so it moves with its target during page scroll. The gear contains the helper URL, the optional forward port, and the Jira and ATL plugin switches. Active probes commit their annotation when the intent changes or Enter is pressed in the comment; Shift+Enter inserts a newline. Storybook intentionally keeps its probe dock in the preview because its details panel lives in the manager frame.
+The extension toolbar popup shows the Chippy mark and name with Enable and Disable for the current origin. The in-page UI starts as one small bottom-corner Chippy button. Expand it to reveal compact `P1 — drag to source` and `P2 — drag to source` rows; each row is the probe's dock and expands into its details once placed. Dragging a probe out keeps the panel expanded, and a placed probe is document-anchored so it moves with its target during page scroll. The gear contains the helper URL and the Jira and ATL plugin switches. Active probes commit their annotation when the intent changes or Enter is pressed in the comment; Shift+Enter inserts a newline. Storybook intentionally keeps its probe dock in the preview because its details panel lives in the manager frame.
 
 Each connected page reports `integration.kind`, `who`, `source`, `reinjectsOnReload`, and `reloadAction`. Use those fields instead of inferring how Chippy arrived.
 
@@ -136,14 +141,14 @@ For a user-controlled page without the extension, run this in the browser consol
 import('http://127.0.0.1:7823/__chippy/inject.mjs')
 ```
 
-The single `import(...)` is all that is needed: the ESM bootstrap installs Chippy, loads the Avalanche bridge runtime (so fiber-backed reads and captures work immediately — no second asset), and activates probes for the current document. It renders no in-page control panel/overlay. After reload or navigation, import again.
+The single `import(...)` is all that is needed: the ESM bootstrap installs Chippy, loads the Avalanche bridge runtime (so fiber-backed reads and captures work immediately — no second asset), and activates probes for the current document. It renders no in-page control panel/overlay. After reload or navigation, import again. A strict Content Security Policy blocks the import; on a local dev server, use the proxy instead, which removes the page's CSP headers.
 
-For extension-free pages where reload destroys Chippy (e.g. a production page using console import), **do not use `reload-with-avalanche`**. The correct workflow is mid-page capture: import Chippy once, install/arm Avalanche on the live page (`avalanche-install` or `avalanche-arm`), then trigger a controlled render stimulus such as `fiber-schedule-update` / the stability nudge. `reload-with-avalanche` is only for reload-surviving integrations such as the extension or Storybook addon. On Storybook, its reload step is a `FORCE_REMOUNT` of the current SUT, not an iframe navigation.
+For pages where reload destroys Chippy (console import or `connectChippy()`), **do not use `reload-with-avalanche`**. The correct workflow is mid-page capture: import Chippy once, install/arm Avalanche on the live page (`avalanche-install` or `avalanche-arm`), then trigger a controlled render stimulus such as `fiber-schedule-update` / the stability nudge. `reload-with-avalanche` is for routes that load Chippy before page scripts on the reloaded document: the extension, the local proxy, and the Storybook addon. On Storybook, its reload step is a `FORCE_REMOUNT` of the current SUT, not an iframe navigation. A Playwright page with the pre-page start-up variant installs the detector on every document itself, so a plain `page.reload()` captures the load.
 
 The helper serves matching source maps alongside its Avalanche bundles; browser
 developer tools can resolve the runtime frames without missing-map requests.
 
-For Playwright-controlled pages, use [playwright-cli-setup](references/playwright-cli-setup.md). The classic fallback requires `inject.js` followed by `avalanche.iife.js`; `bridge module not loaded` means the second asset is missing.
+For an agent-driven Playwright browser, follow [mode-a-injection](references/mode-a-injection.md) for the loader variants and their capture limits, and [playwright-cli-setup](references/playwright-cli-setup.md) for ad-hoc `playwright-cli` sessions. The classic fallback requires `inject.js` followed by `avalanche.iife.js`; `bridge module not loaded` means the second asset is missing.
 
 ### Explicit wait mode
 
@@ -276,7 +281,7 @@ Arm before the user or harness performs the slow interaction. Probes drill into
 
 `latestAction` is a clue, not causality. A confirmed root cause needs a source-to-collateral chain or source code that proves the update origin. Unmount and Suspense fields are branch signals; report DOM regions before wrapper names when the question is about DOM teardown.
 
-Use `detectionMode=full` when `commit-peek include=rendered` or per-component render evidence is required. `sources` and `stats` do not populate `renderedByCommit`. If broad triage began in the default `sources` mode, run `avalanche-recapture <clientId> full`, reproduce the identical interaction, and only then read rendered fields. Load [avalanche-detector](references/avalanche-detector.md) for exact schemas and [fixing-performance](references/fixing-performance.md) for fix-layer selection.
+Every mode records which components rendered and their prop changes (`commit-peek include=rendered`). `stats` leaves `isSelfSource` false, and only `full` or `amplifiers` fill `trasherCounts`. When amplifier evidence is required and triage began in the default `sources` mode, run `avalanche-recapture <clientId> full`, reproduce the identical interaction, and only then read `trasherCounts`. Load [avalanche-detector](references/avalanche-detector.md) for exact schemas and [fixing-performance](references/fixing-performance.md) for fix-layer selection.
 
 ## Snippets and active stimuli
 

package/lib/mcp-skill/extension/armed-reload-startup.js

@@ -0,0 +1,83 @@
+/* eslint-disable */
+// One-shot early startup for an armed reload, loaded into the background
+// service worker with importScripts().
+//
+// The background's normal startup injection waits on several asynchronous
+// lookups after navigation commits, so a fast page can commit React before
+// Avalanche installs. Before an armed reload, the page bridge stores the arm in
+// sessionStorage and asks for this registration. Chrome then runs the scripts
+// below synchronously at document_start of the next document, and
+// startup-handoff.js turns the stored arm into the startup config.
+//
+// The registration covers one navigation of one frame: it is removed when that
+// document finishes parsing, when its navigation fails, or when it is older
+// than PENDING_MAX_AGE_MS at the next navigation event.
+(function chippyArmedReloadStartup(global) {
+  const SCRIPT_ID = 'chippy-armed-reload-startup';
+  const PENDING_KEY = 'chippyArmedReloadPending';
+  const PENDING_MAX_AGE_MS = 60000;
+  const FILES = ['devtools-hook-shim.js', 'startup-handoff.js', 'avalanche.iife.js', 'early-bootstrap.js'];
+
+  function originPattern(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') throw new Error(`Unsupported page URL: ${url}`);
+    return `${parsed.origin}/*`;
+  }
+
+  async function unregister() {
+    try { await chrome.scripting.unregisterContentScripts({ ids: [SCRIPT_ID] }); } catch {}
+    try { await chrome.storage.session.remove(PENDING_KEY); } catch {}
+  }
+
+  // Registration calls run one at a time; Chrome rejects a concurrent
+  // registration of the same id.
+  let queue = Promise.resolve();
+  function serialized(task) {
+    const run = queue.then(task, task);
+    queue = run.catch(() => {});
+    return run;
+  }
+
+  async function register({ tabId, frameId, url }) {
+    const pattern = originPattern(url);
+    await unregister();
+    await chrome.scripting.registerContentScripts([{
+      id: SCRIPT_ID,
+      matches: [pattern],
+      js: FILES,
+      runAt: 'document_start',
+      world: 'MAIN',
+      allFrames: frameId !== 0,
+      persistAcrossSessions: false,
+    }]);
+    await chrome.storage.session.set({ [PENDING_KEY]: { tabId, frameId, pattern, at: Date.now() } });
+    return { ok: true, pattern };
+  }
+
+  async function settle(details) {
+    let pending;
+    try { pending = (await chrome.storage.session.get(PENDING_KEY))[PENDING_KEY]; } catch { return; }
+    if (!pending) return;
+    const ours = pending.tabId === details.tabId && pending.frameId === details.frameId;
+    if (ours || Date.now() - pending.at > PENDING_MAX_AGE_MS) await serialized(unregister);
+  }
+
+  chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+    if (message?.type !== 'chippy-register-armed-reload') return false;
+    const tabId = sender.tab?.id;
+    if (tabId == null || !sender.url) {
+      sendResponse({ ok: false, error: 'No sender tab for the armed reload' });
+      return false;
+    }
+    serialized(() => register({ tabId, frameId: sender.frameId ?? 0, url: sender.url }))
+      .then(sendResponse)
+      .catch((e) => sendResponse({ ok: false, error: e.message }));
+    return true;
+  });
+
+  // document_start injection has happened by DOMContentLoaded.
+  chrome.webNavigation.onDOMContentLoaded.addListener((details) => { settle(details); });
+  chrome.webNavigation.onErrorOccurred.addListener((details) => { settle(details); });
+
+  global.chippyArmedReloadStartup = { SCRIPT_ID, FILES, originPattern };
+})(globalThis);