@atlassian/chippy 0.0.0-stage → 0.0.1-beta.2

package/lib/mcp-skill/extension/probe-descriptor.js

@@ -0,0 +1,241 @@
+/* eslint-disable */
+(function installProbeDescriptor(global) {
+  const chippy = global.__CHIPPY = global.__CHIPPY || {};
+
+  function normalizeText(value, max = 200) {
+    return String(value || '').replace(/\s+/g, ' ').trim().slice(0, max) || null;
+  }
+
+  function stableAttrs(node) {
+    if (!node || node.nodeType !== 1) return {};
+    const attrs = {};
+    const names = ['data-testid', 'role', 'aria-label', 'name', 'id', 'title', 'href', 'type'];
+    for (const name of names) {
+      const value = node.getAttribute?.(name);
+      if (value) attrs[name] = value;
+    }
+    return attrs;
+  }
+
+  function siblingIndex(node) {
+    if (!node?.parentElement) return 0;
+    const tag = node.tagName;
+    let index = 0;
+    for (const sibling of node.parentElement.children) {
+      if (sibling === node) return index;
+      if (sibling.tagName === tag) index += 1;
+    }
+    return index;
+  }
+
+  function ownerNames(fiber, max = 8) {
+    const names = [];
+    let owner = fiber?._debugOwner || null;
+    while (owner && names.length < max) {
+      const name = chippy.getDisplayName?.(owner.type) || owner.type?.displayName || owner.type?.name || null;
+      if (name) names.push(name);
+      owner = owner._debugOwner || null;
+    }
+    return names;
+  }
+
+  function describeSource(source) {
+    if (!source?.fileName) return null;
+    return {
+      fileName: source.fileName,
+      lineNumber: Number(source.lineNumber || 0) || null,
+      columnNumber: Number(source.columnNumber || 0) || null,
+    };
+  }
+
+  function getNearestTestId(node) {
+    return chippy.getNearestTestIdParent?.(node) || null;
+  }
+
+  function captureProbeDescriptor(target) {
+    const node = target?.nodeType === 1 ? target : null;
+    if (!node) return { ok: false, error: 'Target element is required' };
+
+    const inspection = chippy.inspectNode ? chippy.inspectNode(node) : null;
+    const component = inspection?.component || null;
+    const fiber = chippy.getClosestFiber ? chippy.getClosestFiber(node) : null;
+    const source = component?.source || describeSource(fiber?._debugSource || fiber?.type?._debugSource || null);
+    const descriptor = {
+      dom: {
+        tag: node.tagName?.toLowerCase() || null,
+        attrs: stableAttrs(node),
+        text: normalizeText(node.innerText || node.textContent || ''),
+        nearestTestId: getNearestTestId(node),
+        siblingIndex: siblingIndex(node),
+      },
+      component: {
+        name: component?.name || chippy.getDisplayName?.(fiber?.type) || fiber?.type?.displayName || fiber?.type?.name || null,
+        source,
+        ownerNames: ownerNames(fiber),
+      },
+    };
+    const hasIdentity = !!(
+      descriptor.dom.nearestTestId
+      || descriptor.component.name
+      || descriptor.component.source?.fileName
+      || Object.keys(descriptor.dom.attrs).length
+      || descriptor.dom.text
+    );
+    if (!hasIdentity) {
+      return { ok: false, error: 'Target does not expose stable identity yet', descriptor };
+    }
+    return { ok: true, descriptor };
+  }
+
+  function sourceKey(source) {
+    if (!source?.fileName) return null;
+    return [source.fileName, source.lineNumber || '', source.columnNumber || ''].join(':');
+  }
+
+  function elementFromFiber(fiber) {
+    const node = fiber?.stateNode;
+    return node && node.nodeType === 1 ? node : null;
+  }
+
+  function candidateFromNode(node, providedFiber) {
+    const fiber = providedFiber || (chippy.getClosestFiber ? chippy.getClosestFiber(node) : null);
+    const inspection = chippy.inspectNode ? chippy.inspectNode(node) : null;
+    const component = inspection?.component || null;
+    return {
+      node,
+      dom: {
+        tag: node.tagName?.toLowerCase() || null,
+        attrs: stableAttrs(node),
+        text: normalizeText(node.innerText || node.textContent || ''),
+        nearestTestId: getNearestTestId(node),
+        siblingIndex: siblingIndex(node),
+      },
+      component: {
+        name: component?.name || chippy.getDisplayName?.(fiber?.type) || fiber?.type?.displayName || fiber?.type?.name || null,
+        source: component?.source || describeSource(fiber?._debugSource || fiber?.type?._debugSource || null),
+        ownerNames: ownerNames(fiber),
+      },
+      fiber,
+    };
+  }
+
+  function getFiberCandidates(descriptor, limit = 250) {
+    const findFibers = chippy.pageBridge?.helpers?.findFibers;
+    if (typeof findFibers !== 'function') return [];
+    const seen = new Set();
+    const fibers = findFibers((fiber) => {
+      const node = elementFromFiber(fiber);
+      if (!node) return false;
+      const name = chippy.getDisplayName?.(fiber?.type) || fiber?.type?.displayName || fiber?.type?.name || null;
+      const source = describeSource(fiber?._debugSource || fiber?.type?._debugSource || null);
+      const testId = getNearestTestId(node);
+      if (descriptor.component.source?.fileName && sourceKey(source) === sourceKey(descriptor.component.source)) return true;
+      if (descriptor.component.name && name === descriptor.component.name) return true;
+      if (descriptor.dom.nearestTestId && testId === descriptor.dom.nearestTestId) return true;
+      if (descriptor.dom.text) {
+        const text = normalizeText(node.innerText || node.textContent || '');
+        if (text && (text.includes(descriptor.dom.text) || descriptor.dom.text.includes(text))) return true;
+      }
+      return false;
+    }, { max: limit });
+    for (const fiber of fibers) {
+      const node = elementFromFiber(fiber);
+      if (!node || seen.has(node)) continue;
+      seen.add(node);
+    }
+    return Array.from(seen).map((node) => candidateFromNode(node));
+  }
+
+  function getDomCandidates(root) {
+    return Array.from(root.querySelectorAll('*')).map((node) => candidateFromNode(node));
+  }
+
+  function scoreCandidate(descriptor, candidate) {
+    const matches = {};
+     let strict = true;
+    let score = 0;
+
+    function match(name, condition, weight, strictField = false) {
+      matches[name] = !!condition;
+      if (condition) score += weight;
+      if (strictField && !condition) strict = false;
+    }
+
+    match('nearestTestId', !descriptor.dom.nearestTestId || descriptor.dom.nearestTestId === candidate.dom.nearestTestId, 5, !!descriptor.dom.nearestTestId);
+    match('componentName', !descriptor.component.name || descriptor.component.name === candidate.component.name, 4, !!descriptor.component.name);
+    match('componentSource', !sourceKey(descriptor.component.source) || sourceKey(descriptor.component.source) === sourceKey(candidate.component.source), 6, !!sourceKey(descriptor.component.source));
+    match('tag', !descriptor.dom.tag || descriptor.dom.tag === candidate.dom.tag, 2);
+
+    const textMatch = descriptor.dom.text && candidate.dom.text
+      ? candidate.dom.text.includes(descriptor.dom.text) || descriptor.dom.text.includes(candidate.dom.text)
+      : !descriptor.dom.text;
+    match('text', textMatch, 2);
+
+    const ownerNames = descriptor.component.ownerNames || [];
+    const candidateOwners = candidate.component.ownerNames || [];
+    const ownerOverlap = ownerNames.length === 0 || ownerNames.every((name) => candidateOwners.includes(name));
+    match('ownerNames', ownerOverlap, 3);
+
+    const attrEntries = Object.entries(descriptor.dom.attrs || {});
+    const attrsMatch = attrEntries.every(([name, value]) => candidate.dom.attrs?.[name] === value);
+    match('attrs', attrsMatch, Math.min(4, attrEntries.length || 1));
+
+    match('siblingIndex', descriptor.dom.siblingIndex == null || descriptor.dom.siblingIndex === candidate.dom.siblingIndex, 1);
+
+    return { strict, score, matches };
+  }
+
+  function resolveProbeDescriptor(descriptor, options = {}) {
+    if (!descriptor?.dom || !descriptor?.component) return { ok: false, error: 'Descriptor is required' };
+    const root = options.root || document;
+    const preferFiber = options.preferFiber !== false;
+    const candidates = [];
+    const seenKeys = new Set();
+    const pools = [];
+    if (preferFiber) pools.push({ kind: 'fiber', items: getFiberCandidates(descriptor, Number(options.fiberLimit || 250)) });
+    pools.push({ kind: 'dom', items: getDomCandidates(root) });
+
+    for (const pool of pools) {
+      for (const candidate of pool.items) {
+        const key = [candidate.component.name || '', sourceKey(candidate.component.source) || '', candidate.dom.nearestTestId || '', candidate.dom.tag || '', candidate.dom.text || '', candidate.dom.siblingIndex ?? ''].join('||');
+        if (seenKeys.has(key)) continue;
+        seenKeys.add(key);
+        const evaluation = scoreCandidate(descriptor, candidate);
+        if (!evaluation.strict && evaluation.score < 5) continue;
+        candidates.push({
+          score: evaluation.score + (pool.kind === 'fiber' ? 2 : 0),
+          strict: evaluation.strict,
+          matches: evaluation.matches,
+          dom: candidate.dom,
+          component: candidate.component,
+          node: candidate.node,
+          fiber: candidate.fiber,
+          candidateKind: pool.kind,
+        });
+      }
+    }
+    candidates.sort((a, b) => {
+      if (a.strict !== b.strict) return a.strict ? -1 : 1;
+      if (a.score !== b.score) return b.score - a.score;
+      if (a.candidateKind !== b.candidateKind) return a.candidateKind === 'fiber' ? -1 : 1;
+      return 0;
+    });
+    const best = candidates[0] || null;
+    return {
+      ok: !!best,
+      best,
+      candidates: candidates.slice(0, 5).map((candidate) => ({
+        score: candidate.score,
+        strict: candidate.strict,
+        matches: candidate.matches,
+        dom: candidate.dom,
+        component: candidate.component,
+        candidateKind: candidate.candidateKind,
+      })),
+      error: best ? null : 'No matching element found',
+    };
+  }
+
+  chippy.captureProbeDescriptor = captureProbeDescriptor;
+  chippy.resolveProbeDescriptor = resolveProbeDescriptor;
+})(globalThis);

package/lib/mcp-skill/extension/resolve-probes.js

@@ -0,0 +1,342 @@
+/* eslint-disable */
+(function installResolveProbes(global) {
+  const chippy = global.__CHIPPY = global.__CHIPPY || {};
+  // Always reinstall — guards caused stale code to win after extension reload.
+
+  // ─── Source confidence ────────────────────────────────────────────────────
+  // In a dev build React <=18 exposes _debugSource; React 19 exposes
+  // _debugStack, which the bundled resolver turns into a source location.
+  // In a production build neither exists — we only have component function
+  // names from fiber.type, which may also be minified.
+  //
+  // Every resolved probe carries a `confidence` field:
+  //   "dev"         — React development source evidence is present
+  //   "production"  — no _debugSource, component names only (may be minified)
+  //   "unknown"     — could not determine anything useful
+
+  function sourceConfidence(source, owners) {
+    if (source?.fileName) return 'dev';
+    if (owners?.some((o) => o?.source?.fileName)) return 'dev';
+    return 'production';
+  }
+
+  function summarizeSource(source) {
+    if (!source) return null;
+    return {
+      fileName: source.fileName || null,
+      lineNumber: source.lineNumber || null,
+      columnNumber: source.columnNumber || null,
+    };
+  }
+
+  function summarizeChainEntry(entry) {
+    if (!entry) return null;
+    return {
+      name: entry.name || null,
+      key: entry.key ?? null,
+      source: summarizeSource(entry.source),
+      // props from layout-lab getOwnerChain/getReturnComponentChain are already key arrays
+      propNames: Array.isArray(entry.props)
+        ? entry.props.filter((k) => k !== 'children')
+        : (entry.props && typeof entry.props === 'object' ? listPropNames(entry.props) : []),
+      hookCount: entry.hookCount ?? null,
+      hookCountTruncated: entry.hookCountTruncated ?? false,
+      hookCountMax: entry.hookCountMax ?? null,
+      complexityNote: typeof entry.hookCount === 'number' && entry.hookCount >= 40
+        ? 'High enough hook count to inspect carefully before changing local logic.'
+        : null,
+    };
+  }
+
+  function summarizeProps(props) {
+    if (!props || typeof props !== 'object') return {};
+    return Object.entries(props)
+      .filter(([k]) => !['children', 'style', 'className'].includes(k))
+      .reduce((acc, [k, v]) => {
+        if (v == null) { acc[k] = v; return acc; }
+        if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+          acc[k] = v; return acc;
+        }
+        if (Array.isArray(v)) { acc[k] = `[array:${v.length}]`; return acc; }
+        if (typeof v === 'function') { acc[k] = '[function]'; return acc; }
+        acc[k] = v?.id || v?.key || v?.name || '[object]';
+        return acc;
+      }, {});
+  }
+
+  // List all prop names (excluding children) for a props object — used for compact snapshot
+  function listPropNames(props) {
+    if (!props || typeof props !== 'object') return [];
+    return Object.keys(props).filter((k) => k !== 'children');
+  }
+
+  // ─── Component stack fallback for production ──────────────────────────────
+  // When _debugSource is absent we still try to provide a useful component
+  // stack by walking fiber.return. Names may be minified in production.
+
+  function getComponentStack(fiber) {
+    if (!fiber) return [];
+    const stack = [];
+    let current = fiber.return;
+    while (current) {
+      const name =
+        current.type?.displayName ||
+        current.type?.name ||
+        current.type?.render?.displayName ||
+        current.type?.render?.name ||
+        null;
+      if (name && typeof current.type !== 'string') {
+        stack.push({ name, key: current.key ?? null, source: null });
+      }
+      current = current.return;
+    }
+    return stack;
+  }
+
+  // ─── Full probe summary ───────────────────────────────────────────────────
+
+  function summarizeProbe(probe) {
+    const best = probe?.probe?.best;
+    return {
+      dom: {
+        tag: best?.exact?.domTag,
+        text: best?.exact?.domText,
+        fiberType: best?.exact?.fiberType,
+        source: best?.exact?.source,
+      },
+      component: {
+        name: best?.component?.name,
+        key: best?.component?.key ?? null,
+        props: best?.component?.props,
+        propNames: listPropNames(best?.component?.props),
+        hookCount: best?.component?.hookCount ?? null,
+        hookCountTruncated: best?.component?.hookCountTruncated ?? false,
+        hookCountMax: best?.component?.hookCountMax ?? null,
+        complexityNote: typeof best?.component?.hookCount === 'number' && best.component.hookCount >= 40
+          ? 'High enough hook count to inspect carefully before changing local logic.'
+          : null,
+        source: best?.component?.source,
+        owners: best?.component?.owners,
+        parents: best?.component?.parents,
+      },
+    };
+  }
+
+  // ─── Compact probe summary (used by bridge for publishing) ────────────────
+
+  function compactProbeSummary(probe) {
+    const best = probe?.probe?.best;
+
+    const componentSource = summarizeSource(best?.component?.source);
+    const owners = (best?.component?.owners || []).map(summarizeChainEntry);
+    const confidence = sourceConfidence(componentSource, owners);
+
+    // In production, owners from _debugOwner chain are absent.
+    // Fall back to the fiber return-chain component stack.
+    let resolvedOwners = owners;
+    let componentStack = null;
+    if (confidence === 'production') {
+      // Try to get the raw fiber for fallback stack
+      const rawFiber = probe?.probe?.rawFiber || null;
+      componentStack = getComponentStack(rawFiber);
+    }
+
+    // Matched CSS rules — rules from all sheets whose selector matches the target element
+    const targetEl = probe?.probe?._targetEl || null;
+    const inspectedTarget = targetEl ? chippy.inspectReact?.inspectNode?.(targetEl) : null;
+    const nearestTestId = inspectedTarget?.nearestTestIdParent?.testId || null;
+    const matchedStyles = [];
+    if (targetEl) {
+      try {
+        for (const sheet of document.styleSheets) {
+          let rules;
+          try { rules = sheet.cssRules; } catch { continue; }
+          for (const rule of rules) {
+            if (rule instanceof CSSStyleRule) {
+              try {
+                if (targetEl.matches(rule.selectorText)) {
+                  matchedStyles.push({
+                    selector: rule.selectorText,
+                    declarations: rule.style.cssText,
+                    source: sheet.href || 'inline',
+                  });
+                }
+              } catch { /* invalid selector — skip */ }
+            }
+          }
+        }
+      } catch { /* sheet access failed */ }
+    }
+
+    // DOM parent chain — walk up to 10 parentElement levels from the target element
+    const domParents = [];
+    if (targetEl) {
+      let el = targetEl.parentElement;
+      while (el && domParents.length < 10) {
+        const cls = el.className && typeof el.className === 'string'
+          ? el.className.trim().split(/\s+/).slice(0, 3).join(' ')
+          : null;
+        domParents.push({
+          tag: el.tagName?.toLowerCase() || null,
+          id: el.id || null,
+          className: cls || null,
+        });
+        el = el.parentElement;
+      }
+    }
+
+    return {
+      nearestTestId,
+      confidence,
+      dom: {
+        tag: best?.exact?.domTag || null,
+        text: (best?.exact?.domText || '').slice(0, 80),
+        fiberType: best?.exact?.fiberType || null,
+        source: summarizeSource(best?.exact?.source),
+        parents: domParents,
+        matchedStyles,
+      },
+      component: {
+        name: best?.component?.name || null,
+        key: best?.component?.key ?? null,
+        propNames: listPropNames(best?.component?.props),
+        props: summarizeProps(best?.component?.props),
+        hookCount: best?.component?.hookCount ?? null,
+        hookCountTruncated: best?.component?.hookCountTruncated ?? false,
+        hookCountMax: best?.component?.hookCountMax ?? null,
+        complexityNote: typeof best?.component?.hookCount === 'number' && best.component.hookCount >= 40
+          ? 'High enough hook count to inspect carefully before changing local logic.'
+          : null,
+        source: componentSource,
+        owners: resolvedOwners,
+        // In production: source-free stack from fiber.return walk
+        componentStack: confidence !== 'dev' ? componentStack : null,
+        parents: (best?.component?.parents || []).map(summarizeChainEntry),
+      },
+      // Human-readable note about what is and isn't available
+      note: confidence === 'dev'
+        ? null
+        : confidence === 'production'
+          ? 'Production build: no React development source metadata is available. Component names may be minified. Source locations are not reliable. Use component stack and names only.'
+          : 'Could not determine build mode. Probe data may be incomplete.',
+    };
+  }
+
+  // ─── Cross-source correlation hint ───────────────────────────────────────
+  // When one probe is on a dev page and another is on a production page
+  // pointing at "around the same component", the agent can use this to
+  // try to match names across the two.
+
+
+  function componentIdentity(entry) {
+    if (!entry) return null;
+    const src = entry.source || null;
+    const srcKey = src && src.fileName ? `${src.fileName}:${src.lineNumber || 0}:${src.columnNumber || 0}` : '';
+    return `${entry.name || ''}|${entry.key ?? ''}|${srcKey}`;
+  }
+
+  function ancestryForSummary(summary) {
+    if (!summary?.component) return [];
+    const out = [];
+    out.push({
+      name: summary.component.name || null,
+      key: summary.component.key ?? null,
+      source: summary.component.source || null,
+      propNames: summary.component.propNames || [],
+      hookCount: summary.component.hookCount ?? null,
+      hookCountTruncated: summary.component.hookCountTruncated ?? false,
+      hookCountMax: summary.component.hookCountMax ?? null,
+      complexityNote: summary.component.complexityNote || null,
+    });
+    for (const parent of summary.component.parents || []) out.push(parent);
+    return out.filter(Boolean);
+  }
+
+  function findCommonParent(summaries) {
+    const ids = Object.keys(summaries).filter((id) => !id.startsWith('__') && summaries[id]?.component);
+    if (ids.length < 2) return null;
+    const chains = ids.map((id) => ancestryForSummary(summaries[id]));
+    if (chains.some((c) => c.length === 0)) return null;
+    const otherSets = chains.slice(1).map((chain) => new Set(chain.map(componentIdentity).filter(Boolean)));
+    for (const entry of chains[0]) {
+      const id = componentIdentity(entry);
+      if (!id) continue;
+      if (otherSets.every((set) => set.has(id))) {
+        return {
+          confidence: 'dev',
+          dom: null,
+          component: {
+            name: entry.name || null,
+            key: entry.key ?? null,
+            propNames: entry.propNames || [],
+            props: {},
+            hookCount: entry.hookCount ?? null,
+            hookCountTruncated: entry.hookCountTruncated ?? false,
+            hookCountMax: entry.hookCountMax ?? null,
+            complexityNote: entry.complexityNote || null,
+            source: entry.source || null,
+            owners: [],
+            componentStack: null,
+            parents: [],
+          },
+          note: `Nearest common parent for probes ${ids.join(', ')}.`,
+        };
+      }
+    }
+    return null;
+  }
+
+  function correlatePairs(summaries) {
+    const ids = Object.keys(summaries);
+    const devProbes = ids.filter((id) => summaries[id]?.confidence === 'dev');
+    const prodProbes = ids.filter((id) => summaries[id]?.confidence === 'production');
+    if (devProbes.length === 0 || prodProbes.length === 0) return null;
+
+    const hints = [];
+    for (const devId of devProbes) {
+      for (const prodId of prodProbes) {
+        const devName = summaries[devId]?.component?.name;
+        const prodName = summaries[prodId]?.component?.name;
+        hints.push({
+          devProbe: devId,
+          productionProbe: prodId,
+          devComponentName: devName || null,
+          productionComponentName: prodName || null,
+          note: devName && prodName && devName === prodName
+            ? `Component names match ("${devName}") — likely the same component.`
+            : devName && prodName
+              ? `Component names differ ("${devName}" vs "${prodName}") — may still be the same component if production is minified. Check component stack for structural similarity.`
+              : 'Could not compare — one or both probes have no component name.',
+        });
+      }
+    }
+    return hints.length > 0 ? hints : null;
+  }
+
+  // ─── Public API ───────────────────────────────────────────────────────────
+
+  function resolveProbes(...ids) {
+    const result = {};
+    for (const id of ids) {
+      const probe = chippy.layoutLab?.getMarkerProbe(id);
+      result[id] = probe ? summarizeProbe(probe) : null;
+    }
+    return result;
+  }
+
+  function resolveProbesCompact(...ids) {
+    const result = {};
+    for (const id of ids) {
+      const probe = chippy.layoutLab?.getMarkerProbe(id);
+      result[id] = probe ? compactProbeSummary(probe) : null;
+    }
+    const crossSourceHints = correlatePairs(result);
+    if (crossSourceHints) result.__crossSourceHints = crossSourceHints;
+    const commonParent = findCommonParent(result);
+    if (commonParent) result.__commonParent = commonParent;
+    return result;
+  }
+
+  chippy.resolveProbes = resolveProbes;
+  chippy.resolveProbesCompact = resolveProbesCompact;
+})(window);

package/lib/mcp-skill/extension/startup-handoff.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+// Runs in MAIN at document_start, before avalanche.iife.js, on the one
+// navigation that follows an armed reload. The page bridge stored the arm in
+// sessionStorage just before reloading; reading it here is synchronous, so the
+// startup config exists when Avalanche evaluates and the detector installs
+// before React's first commit. The entry is removed on read and ignored when old.
+(function chippyStartupHandoff(global) {
+  var KEY = '__chippyStartupHandoff';
+  var MAX_AGE_MS = 60000;
+  var handoff = null;
+  try {
+    var raw = global.sessionStorage.getItem(KEY);
+    if (raw == null) return;
+    global.sessionStorage.removeItem(KEY);
+    handoff = JSON.parse(raw);
+  } catch (_) {
+    return;
+  }
+  if (!handoff || !handoff.avalanche || !handoff.avalanche.autoStart) return;
+  if (!(Date.now() - Number(handoff.at) <= MAX_AGE_MS)) return;
+  if (global.__CHIPPY_STARTUP_CONFIG) return;
+  global.__CHIPPY_STARTUP_CONFIG = {
+    enabled: true,
+    helperBaseUrl: handoff.helperBaseUrl,
+    avalanche: handoff.avalanche,
+    plugins: Array.isArray(handoff.plugins) ? handoff.plugins : undefined,
+    contextUiEnabled: true,
+    startupSource: 'armed-reload-handoff',
+  };
+})(typeof globalThis !== 'undefined' ? globalThis : window);

package/lib/mcp-skill/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/mcp-skill/references/README.md

@@ -0,0 +1,56 @@
+# Chippy reference guide
+
+Choose the Chippy decision in front of you—position evidence, trace the page, investigate performance, automate a browser, parse a contract, or recover a failed path—then load only the owning reference. Each page owns one decision or contract.
+
+## Start with the work
+
+| Need | Read | What it gives you |
+|---|---|---|
+| Connect through an MCP-capable host | [MCP](mcp.md) | Automatic helper startup, typed tools, lifecycle, and sandbox requirements |
+| Position an uncertain case | [Cynefin and OODA](cynefin.md) | The permitted evidence move for Clear, Complicated, Complex, Chaotic, or unpositioned work |
+| Define proof and edit gates | [Operating model](operating-model.md) | Observation contract, proof packet, confidence rule, and Apply gate |
+| Select an exact workflow | [BDD router](bdd-router.md) | Situation-to-procedure routing with completion checks |
+| Execute the selected workflow | [Procedures](procedures.md) | P-01 and later ceremonies, procedures, and plays |
+| Use a mutating or synthetic action | [Active stimulus](active-stimulus.md) | Anchor contract, pollution boundary, and recovery rules |
+
+## Trace the page
+
+| Need | Read | What it gives you |
+|---|---|---|
+| Interpret hook output | [Hooks inspection](hooks-inspection.md) | Hook tree reading, limits, and `useDebugValue` guidance |
+| Automate probe handling | [Playwright probes](playwright-probes.md) | Probe lifecycle, measurement operations, and extension handoff |
+| Work on minified Jira pages | [Jira taxonomy](jira-taxonomy.md) | Production-name patterns and bounded fallback signals |
+
+## Investigate performance
+
+| Need | Read | What it gives you |
+|---|---|---|
+| Capture and interpret commits | [Avalanche detector](avalanche-detector.md) | Capture modes, schemas, causality reading, unmounts, Suspense, and large-capture analysis |
+| Choose the fix layer | [Fixing performance](fixing-performance.md) | Source/boundary/collateral classification and targeted remediation |
+| Grade one subtree | [Stability render](stability-render.md) | Deterministic nudge procedure and clean/leak/cascade/trasher verdicts |
+| Identify one captured hook | [Debug-hook](debug-hook.md) | Hook primitive, custom-hook ownership, confidence, and remediation branch |
+| Count dispatches or recomputations | [Hook metrics](hook-metrics.md) | `setStateCount`, hook tracker actions, histograms, and Avalanche joins |
+
+These pages are siblings, not substitutes. Start with Avalanche for a real slow interaction or load, use stability-render for a known subtree, and use debug-hook only when a capture already produced `sourceId + hookIndex`.
+
+## Automate a browser
+
+| Need | Read | What it gives you |
+|---|---|---|
+| Load Chippy into a Playwright-controlled page | [Playwright CLI setup](playwright-cli-setup.md) | The shortest current-document bootstrap and reload recovery recipe |
+| Build a repeatable browser loop | [Test mode playbook](test-mode-playbook.md) | Sidecar and Playwright-controlled automation contracts |
+| Load Chippy before page scripts, or record the initial load without the extension | [Mode A injection](mode-a-injection.md) | Init-script loader variants, pre-page start-up, boot-time limits, and failure signatures |
+
+Use Playwright CLI setup for ad-hoc inspection. Use the test-mode playbook for scripted or CI workflows. Use Mode A injection when Chippy must stay across reloads or record the initial load in a Playwright browser.
+
+## Look up a contract
+
+| Need | Read | What it gives you |
+|---|---|---|
+| Find the recipe for a task or symptom | Run `chippy.sh recipes <query...>` against [the grep-friendly corpus](recipes.txt) | Ranked, self-contained answers with completion signals, guardrails, and canonical deeper references |
+| Select a shell command | [Command surface](command-surface.md) | Complete public command catalog and important option modes |
+| Parse a response | [Command output formats](command-output-formats.md) | Exact envelopes, DTOs, field semantics, and examples |
+| Work in the page runtime | [Browser runtime API](browser-runtime-api.md) | Public globals, bridge API, and helper-to-page commands |
+| Recover a failed path | [Troubleshooting](troubleshooting.md) | Failure signature, failing layer, and one recovery action |
+
+The shell wrapper's `help` output owns mechanical command signatures. Recipe search owns task-to-answer lookup, command surface explains selection and boundaries, and command output formats owns exact response shapes.