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

package/lib/mcp-skill/scripts/search-recipes.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createReadStream } = require('node:fs');
+const { createInterface } = require('node:readline');
+
+const REQUIRED_FIELDS = ['id', 'q', 'tags', 'a', 'done', 'guard', 'refs'];
+const STOP_WORDS = new Set([
+  'a', 'an', 'and', 'are', 'can', 'do', 'does', 'for', 'from', 'how', 'i', 'in',
+  'is', 'it', 'my', 'of', 'on', 'or', 'the', 'this', 'to', 'use', 'what', 'when',
+  'where', 'which', 'why', 'with',
+]);
+
+function usage() {
+  process.stderr.write('Usage: chippy.sh recipes <query...> [--limit N]\n');
+}
+
+function parseArgs(argv) {
+  let limit = 5;
+  const queryParts = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--limit') {
+      const next = argv[index + 1];
+      if (!next || !/^\d+$/.test(next)) {
+        throw new Error('--limit requires an integer from 1 to 20');
+      }
+      limit = Number(next);
+      index += 1;
+      continue;
+    }
+    queryParts.push(value);
+  }
+
+  if (limit < 1 || limit > 20) {
+    throw new Error('--limit must be between 1 and 20');
+  }
+
+  const query = queryParts.join(' ').trim();
+  if (!query) {
+    throw new Error('recipes requires a search query');
+  }
+
+  return { limit, query };
+}
+
+function normalizeToken(token) {
+  let value = token.toLowerCase();
+  if (value.length > 4 && value.endsWith('ies')) value = `${value.slice(0, -3)}y`;
+  else if (value.length > 4 && value.endsWith('ing')) value = value.slice(0, -3);
+  else if (value.length > 4 && value.endsWith('ed')) value = value.slice(0, -2);
+  else if (value.length > 3 && value.endsWith('s')) value = value.slice(0, -1);
+  return value;
+}
+
+function tokenize(value) {
+  return String(value)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map(normalizeToken)
+    .filter((token) => token.length > 1 && !STOP_WORDS.has(token));
+}
+
+function parseRecord(line, lineNumber) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+
+  const fields = {};
+  for (const part of trimmed.split(' | ')) {
+    const equals = part.indexOf('=');
+    if (equals <= 0) throw new Error(`invalid recipe field at line ${lineNumber}`);
+    fields[part.slice(0, equals)] = part.slice(equals + 1);
+  }
+
+  const missing = REQUIRED_FIELDS.filter((field) => !fields[field]);
+  if (missing.length > 0) {
+    throw new Error(`recipe at line ${lineNumber} is missing: ${missing.join(', ')}`);
+  }
+  return fields;
+}
+
+async function forEachRecipe(file, visit) {
+  const lines = createInterface({
+    input: createReadStream(file, { encoding: 'utf8' }),
+    crlfDelay: Infinity,
+  });
+  let lineNumber = 0;
+  for await (const line of lines) {
+    lineNumber += 1;
+    const record = parseRecord(line, lineNumber);
+    if (record) await visit(record);
+  }
+}
+
+function isEditDistanceOne(left, right) {
+  if (left === right || Math.abs(left.length - right.length) > 1) return false;
+  let edits = 0;
+  let leftIndex = 0;
+  let rightIndex = 0;
+  while (leftIndex < left.length && rightIndex < right.length) {
+    if (left[leftIndex] === right[rightIndex]) {
+      leftIndex += 1;
+      rightIndex += 1;
+      continue;
+    }
+    edits += 1;
+    if (edits > 1) return false;
+    if (left.length > right.length) leftIndex += 1;
+    else if (right.length > left.length) rightIndex += 1;
+    else {
+      leftIndex += 1;
+      rightIndex += 1;
+    }
+  }
+  return edits + (leftIndex < left.length || rightIndex < right.length ? 1 : 0) === 1;
+}
+
+function matchWeight(queryToken, documentToken) {
+  if (queryToken === documentToken) return 1;
+  if (
+    Math.min(queryToken.length, documentToken.length) >= 4
+    && (queryToken.startsWith(documentToken) || documentToken.startsWith(queryToken))
+  ) return 0.72;
+  if (
+    Math.min(queryToken.length, documentToken.length) >= 5
+    && isEditDistanceOne(queryToken, documentToken)
+  ) return 0.58;
+  return 0;
+}
+
+function indexedTokens(record) {
+  const weightedFields = [
+    ['id', 3],
+    ['q', 2],
+    ['tags', 3],
+    ['a', 1],
+    ['done', 1],
+    ['guard', 1],
+    ['refs', 1],
+  ];
+  const result = [];
+  for (const [field, weight] of weightedFields) {
+    for (const token of tokenize(record[field])) result.push({ token, weight });
+  }
+  return result;
+}
+
+function termFrequency(queryToken, tokens) {
+  let frequency = 0;
+  for (const { token, weight } of tokens) {
+    frequency += matchWeight(queryToken, token) * weight;
+  }
+  return frequency;
+}
+
+function insertTop(results, candidate, limit) {
+  results.push(candidate);
+  results.sort((left, right) => right.score - left.score || left.record.id.localeCompare(right.record.id));
+  if (results.length > limit) results.length = limit;
+}
+
+async function search(file, query, limit) {
+  const queryTokens = [...new Set(tokenize(query))];
+  if (queryTokens.length === 0) throw new Error('search query contains no searchable words');
+
+  let documentCount = 0;
+  let totalLength = 0;
+  const documentFrequency = new Map(queryTokens.map((token) => [token, 0]));
+
+  await forEachRecipe(file, (record) => {
+    const tokens = indexedTokens(record);
+    documentCount += 1;
+    totalLength += tokens.length;
+    for (const queryToken of queryTokens) {
+      if (termFrequency(queryToken, tokens) > 0) {
+        documentFrequency.set(queryToken, documentFrequency.get(queryToken) + 1);
+      }
+    }
+  });
+
+  if (documentCount === 0) throw new Error('recipe corpus is empty');
+  const averageLength = totalLength / documentCount;
+  const results = [];
+  const k1 = 1.2;
+  const b = 0.75;
+  const normalizedPhrase = tokenize(query).join(' ');
+
+  await forEachRecipe(file, (record) => {
+    const tokens = indexedTokens(record);
+    let score = 0;
+    for (const queryToken of queryTokens) {
+      const frequency = termFrequency(queryToken, tokens);
+      if (frequency === 0) continue;
+      const df = documentFrequency.get(queryToken);
+      const inverseDocumentFrequency = Math.log(1 + ((documentCount - df + 0.5) / (df + 0.5)));
+      const denominator = frequency + k1 * (1 - b + b * (tokens.length / averageLength));
+      score += inverseDocumentFrequency * ((frequency * (k1 + 1)) / denominator);
+    }
+
+    const searchablePhrase = tokenize(`${record.id} ${record.q} ${record.tags}`).join(' ');
+    if (normalizedPhrase.length >= 5 && searchablePhrase.includes(normalizedPhrase)) score += 1.5;
+    if (score > 0) insertTop(results, { record, score }, limit);
+  });
+
+  return results;
+}
+
+function printResults(query, results) {
+  if (results.length === 0) {
+    process.stderr.write(`No Chippy recipe matched: ${query}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  results.forEach(({ record, score }, index) => {
+    if (index > 0) process.stdout.write('\n');
+    process.stdout.write(`recipe: ${record.id}\n`);
+    process.stdout.write(`score: ${score.toFixed(3)}\n`);
+    process.stdout.write(`question: ${record.q}\n`);
+    process.stdout.write(`answer: ${record.a}\n`);
+    process.stdout.write(`done: ${record.done}\n`);
+    process.stdout.write(`guard: ${record.guard}\n`);
+    process.stdout.write(`refs: ${record.refs}\n`);
+  });
+}
+
+async function main() {
+  const [file, ...argv] = process.argv.slice(2);
+  if (!file) {
+    usage();
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const { query, limit } = parseArgs(argv);
+    printResults(query, await search(file, query, limit));
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    usage();
+    process.exitCode = 1;
+  }
+}
+
+main();

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

@@ -0,0 +1,89 @@
+# Chippy snippets
+
+Snippets are version-controlled page-realm programs executed through `chippy.sh eval-page`. Use them for a reusable inspection question or reproducible procedure that existing commands cannot answer and that does not justify another bridge round trip.
+
+Do not add a snippet to walk React fibers from a probe or remembered fiber until `probe-parents`, `explain-component`, `inspect-fiber-parents`, and `find-fibers` have proven the command surface cannot supply the path evidence. `probe-owners` reads debug-build `_debugOwner`, not the `fiber.return` parent chain; do not use it as a production-build route.
+
+Most snippets are read-only. Active or stateful snippets declare the target they touch, the state they own, and what becomes ambiguous after execution.
+
+## Run a snippet
+
+From the Chippy skill directory:
+
+```bash
+./scripts/chippy.sh eval-snippets
+./scripts/chippy.sh eval-page <clientId> <snippet-name> [--key value ...]
+```
+
+`snippet-name` resolves to `snippets/<name>.js`. An absolute path or a path relative to the current directory also works.
+
+The shell wrapper forwards every `--key value` pair into `ctx.args`, coercing numbers and `true`/`false`. Its page-script timeout is fixed at five seconds; the wrapper does not expose a timeout override.
+
+## Choose a packaged snippet
+
+| Snippet | Kind | Use it when |
+|---|---|---|
+| `find-context-providers` | Read-only | List modern `React.createContext` providers; filter with `--name <regex>`. |
+| `find-legacy-context` | Read-only | Find legacy `childContextTypes` / `contextTypes` producers and consumers. |
+| `count-context-consumers` | Read-only | Count consumers for a Context display-name regex with `--name`. |
+| `find-prop` | Read-only | Find fibers by prop name or value when a probe revealed a clue but the owner chain is broad. |
+| `hook-metrics` | Read-only (ATL plugin) | Read the host `__ATL_REACT_METRICS`, including NaN/undefined-safe `setStateCount`. |
+| `hook-metrics-sample` | Active, bounded (ATL plugin) | Measure a labeled before/after `setStateCount` delta, optionally clicking one test-id. |
+| `hook-tracker` | Stateful instrument (ATL plugin) | Install, query, reset, or remove the `onHookUpdate` recomputation tracker. |
+| `stability-nudge` | Active stimulus | Schedule one controlled component render for the stability-render procedure. |
+
+Read [hook metrics](../references/hook-metrics.md) before using the metrics snippets. Read [stability render](../references/stability-render.md) before using `stability-nudge`.
+
+## Authoring contract
+
+Each snippet is the body of an `async function (ctx) { ... }` executed in the connected page. Return a JSON-serializable value.
+
+`ctx` provides:
+
+| Field | Contract |
+|---|---|
+| `ctx.args` | Object built from `--key value` pairs. |
+| `ctx.log` | Array of human-readable trace strings returned with the result. |
+| `ctx.helpers.getRootFibers()` | Root fibers across all React renderers on the page. |
+| `ctx.helpers.walkAll(visit, opts?)` | Walk every fiber; `opts.limit` defaults to 200,000. |
+| `ctx.helpers.findFibers(predicate, opts?)` | Return matching fibers; `opts.max` defaults to 5,000. |
+| `ctx.helpers.getDisplayName(fiber)` | Best-effort display name. |
+| `ctx.helpers.fiberInfo(fiber)` | Circular-safe view of name, source, owner, and DOM context. |
+| `ctx.helpers.ancestorFibers(fiber, max?)` | Walk the fiber return chain. |
+| `ctx.helpers.devtoolsHook()` | Raw React DevTools global hook when a documented procedure requires it. |
+
+Prefer the smallest result that answers the question. Return summaries or bounded matches, not entire fiber trees.
+
+## Result envelope
+
+`eval-page` returns this shape:
+
+```json
+{
+  "ok": true,
+  "durationMs": 42,
+  "log": ["matched 3 fibers"],
+  "result": { "count": 3 }
+}
+```
+
+The helper removes circular references, trims depth, represents functions as strings, and caps arrays at 200 items per level.
+
+## Safety and ownership
+
+- Do not commit secrets or return sensitive page data.
+- Keep read-only snippets read-only.
+- For an active snippet, document the exact target, stimulus, owned state, pollution boundary, and required cleanup or recapture.
+- Use a current composite fiber for render stimuli. Re-resolve it after state changes or navigation.
+- Use one stimulus per bounded capture. Clear or recapture before repeating it.
+- Promote version-coupled React internals to a tested bridge capability; keep procedure and target resolution in the snippet.
+
+`hook-tracker` owns `window.__CHIPPY_HOOK_TRACKER` and the host `onHookUpdate` callback until `--action uninstall`. `stability-nudge` delegates the render to the bundled `fiber-schedule-update` capability and owns no hook or prop state.
+
+## Add or revise a snippet
+
+1. Name the reusable question or procedure and choose read-only, active, or stateful behavior.
+2. Add one JavaScript file under `snippets/` with a bounded input and result contract.
+3. Document its arguments, ownership, failure shape, and cleanup in this catalog or its owning reference.
+4. Exercise it through `eval-page`, not by calling its body directly.
+5. If the snippet becomes a documented multi-step procedure, link its canonical reference from [the reference guide](../references/README.md).

package/lib/mcp-skill/snippets/count-context-consumers.js

@@ -0,0 +1,40 @@
+// Count modern Context consumers for a given Context displayName regex.
+// A consumer is any fiber whose dependencies list contains the matching context.
+// Args:
+//   --name <regex>   REQUIRED. Context displayName regex (case-insensitive).
+//   --max  <N>       cap consumer samples returned (default 100)
+
+const { walkAll, fiberInfo } = ctx.helpers;
+if (!ctx.args.name) return { error: '--name <regex> is required' };
+const nameRe = new RegExp(String(ctx.args.name), 'i');
+const max = Number(ctx.args.max) || 100;
+
+const consumers = [];
+let scanned = 0;
+let totalConsumers = 0;
+walkAll((f) => {
+  scanned++;
+  // dependencies.firstContext is a singly-linked list of ContextDependency
+  const dep = f?.dependencies;
+  if (!dep) return;
+  let cur = dep.firstContext;
+  while (cur) {
+    const c = cur.context;
+    const name = c?.displayName || c?._context?.displayName || null;
+    if (name && nameRe.test(name)) {
+      totalConsumers++;
+      if (consumers.length < max) {
+        consumers.push({
+          contextName: name,
+          consumer: fiberInfo(f),
+          owner: f._debugOwner ? fiberInfo(f._debugOwner) : null,
+        });
+      }
+      break;
+    }
+    cur = cur.next;
+  }
+});
+
+ctx.log.push('scanned fibers: ' + scanned);
+return { matchedContexts: nameRe.source, totalConsumers, sampleCount: consumers.length, consumers };

package/lib/mcp-skill/snippets/find-context-providers.js

@@ -0,0 +1,38 @@
+// List active modern React Context providers on the page.
+// Optional args:
+//   --name <regex>   filter by Context displayName / name (case-insensitive)
+//   --max  <N>       cap results (default 500)
+
+const { findFibers, fiberInfo, ancestorFibers, getDisplayName } = ctx.helpers;
+const nameRe = ctx.args.name ? new RegExp(String(ctx.args.name), 'i') : null;
+const max = Number(ctx.args.max) || 500;
+
+// Provider fibers: tag === 10 in modern React, type._context exists.
+const fibers = findFibers((f) => {
+  const t = f?.type;
+  if (!t || typeof t !== 'object') return false;
+  // ContextProvider: type._context, $$typeof matches React.createContext output
+  return !!t._context;
+}, { max: max * 4 });
+
+const seen = new Map(); // key = contextId → { name, count, samples[] }
+for (const f of fibers) {
+  const ctxObj = f.type._context;
+  const name = ctxObj.displayName || ctxObj._currentValue?.displayName || ctxObj?.Provider?.displayName || null;
+  if (nameRe && !nameRe.test(name || '')) continue;
+  const id = name || ('anon@' + Object.keys(seen).length);
+  let rec = seen.get(id);
+  if (!rec) { rec = { name, count: 0, samples: [] }; seen.set(id, rec); }
+  rec.count++;
+  if (rec.samples.length < 3) {
+    rec.samples.push({
+      provider: fiberInfo(f),
+      owner: f._debugOwner ? fiberInfo(f._debugOwner) : null,
+      ancestors: ancestorFibers(f, 6).map((a) => a.name),
+    });
+  }
+}
+
+const rows = Array.from(seen.values()).sort((a, b) => b.count - a.count);
+ctx.log.push('matched providers: ' + rows.length);
+return { totalProviders: rows.length, top: rows.slice(0, max) };

package/lib/mcp-skill/snippets/find-legacy-context.js

@@ -0,0 +1,47 @@
+// Find class components using the legacy React context API.
+// Producer:   class with `childContextTypes`
+// Consumer:   class with `contextTypes`
+// Args:
+//   --name <regex>   filter by component displayName / name
+//   --kind <producer|consumer|both>   default both
+//   --max  <N>       default 500
+
+const { findFibers, fiberInfo, ancestorFibers, getDisplayName } = ctx.helpers;
+const nameRe = ctx.args.name ? new RegExp(String(ctx.args.name), 'i') : null;
+const kind = String(ctx.args.kind || 'both');
+const max = Number(ctx.args.max) || 500;
+
+function classifies(t) {
+  if (!t) return null;
+  const isProducer = !!t.childContextTypes && Object.keys(t.childContextTypes).length > 0;
+  const isConsumer = !!t.contextTypes && Object.keys(t.contextTypes).length > 0;
+  if (!isProducer && !isConsumer) return null;
+  return { isProducer, isConsumer };
+}
+
+const fibers = findFibers((f) => !!classifies(f?.type), { max: max * 4 });
+const groups = { producers: new Map(), consumers: new Map() };
+for (const f of fibers) {
+  const c = classifies(f.type);
+  const name = getDisplayName(f) || '<anonymous>';
+  if (nameRe && !nameRe.test(name)) continue;
+  if (c.isProducer && (kind === 'producer' || kind === 'both')) {
+    let rec = groups.producers.get(name);
+    if (!rec) { rec = { name, count: 0, contextKeys: Object.keys(f.type.childContextTypes), samples: [] }; groups.producers.set(name, rec); }
+    rec.count++;
+    if (rec.samples.length < 3) rec.samples.push({ self: fiberInfo(f), owner: f._debugOwner ? fiberInfo(f._debugOwner) : null });
+  }
+  if (c.isConsumer && (kind === 'consumer' || kind === 'both')) {
+    let rec = groups.consumers.get(name);
+    if (!rec) { rec = { name, count: 0, contextKeys: Object.keys(f.type.contextTypes), samples: [] }; groups.consumers.set(name, rec); }
+    rec.count++;
+    if (rec.samples.length < 3) rec.samples.push({ self: fiberInfo(f), owner: f._debugOwner ? fiberInfo(f._debugOwner) : null });
+  }
+}
+
+const sortRows = (m) => Array.from(m.values()).sort((a, b) => b.count - a.count).slice(0, max);
+return {
+  scannedFibers: fibers.length,
+  producers: sortRows(groups.producers),
+  consumers: sortRows(groups.consumers),
+};

package/lib/mcp-skill/snippets/find-prop.js

@@ -0,0 +1,83 @@
+// Find fibers carrying a given prop, optionally with a matching value.
+// Args:
+//   --prop  <name>         REQUIRED. Prop key to look for (exact match).
+//   --value <regex>        OPTIONAL. Regex matched against String(propValue) (case-insensitive). Objects/functions become tag strings.
+//   --name  <regex>        OPTIONAL. Filter by component displayName regex (case-insensitive).
+//   --file  <regex>        OPTIONAL. Filter by _debugSource.fileName regex (case-insensitive).
+//   --max   <N>            cap result rows (default 200)
+//   --groupBy <name|file|none>  default 'name'. Groups identical components into one row with samples.
+//   --depth <N>            depth-trim for sample value (default 2)
+
+const { walkAll, fiberInfo, getDisplayName } = ctx.helpers;
+if (!ctx.args.prop) return { error: '--prop <name> is required' };
+const propKey = String(ctx.args.prop);
+const valueRe = ctx.args.value ? new RegExp(String(ctx.args.value), 'i') : null;
+const nameRe = ctx.args.name ? new RegExp(String(ctx.args.name), 'i') : null;
+const fileRe = ctx.args.file ? new RegExp(String(ctx.args.file), 'i') : null;
+const max = Number(ctx.args.max) || 200;
+const groupBy = ['name', 'file', 'none'].includes(String(ctx.args.groupBy)) ? String(ctx.args.groupBy) : 'name';
+const depth = Number.isFinite(Number(ctx.args.depth)) ? Math.max(0, Number(ctx.args.depth) | 0) : 2;
+
+function tagOf(v) {
+  if (v == null) return String(v);
+  const t = typeof v;
+  if (t === 'function') return '[Function ' + (v.name || 'anonymous') + ']';
+  if (t === 'object') return Array.isArray(v) ? '[Array len=' + v.length + ']' : '[Object]';
+  return String(v);
+}
+
+function trim(value, d) {
+  if (d <= 0 || value == null) {
+    if (value && typeof value === 'object') return Array.isArray(value) ? '[Array]' : '[Object]';
+    return value;
+  }
+  if (Array.isArray(value)) return value.slice(0, 10).map((v) => trim(v, d - 1));
+  if (typeof value === 'object') {
+    const out = {};
+    let n = 0;
+    for (const k of Object.keys(value)) {
+      if (n++ > 20) { out._truncated = true; break; }
+      try { out[k] = trim(value[k], d - 1); } catch (_) { out[k] = '[Unserializable]'; }
+    }
+    return out;
+  }
+  if (typeof value === 'function') return '[Function ' + (value.name || 'anonymous') + ']';
+  return value;
+}
+
+const groups = new Map();
+let scanned = 0;
+let matched = 0;
+
+walkAll((f) => {
+  scanned++;
+  const props = f?.memoizedProps;
+  if (!props || typeof props !== 'object') return;
+  if (!Object.prototype.hasOwnProperty.call(props, propKey)) return;
+  const name = getDisplayName(f) || '<anonymous>';
+  if (nameRe && !nameRe.test(name)) return;
+  const file = f?._debugSource?.fileName || f?.type?._debugSource?.fileName || null;
+  if (fileRe && !fileRe.test(file || '')) return;
+  const v = props[propKey];
+  const tag = tagOf(v);
+  if (valueRe && !valueRe.test(tag) && !(typeof v === 'string' && valueRe.test(v))) return;
+  matched++;
+  const key = groupBy === 'name' ? name
+            : groupBy === 'file' ? (file || '<no-source>')
+            : (name + '|' + (file || '') + '|' + (f?._debugSource?.lineNumber || ''));
+  let rec = groups.get(key);
+  if (!rec) { rec = { key, name, file, line: f?._debugSource?.lineNumber || null, count: 0, samples: [] }; groups.set(key, rec); }
+  rec.count++;
+  if (rec.samples.length < 3) {
+    rec.samples.push({
+      self: fiberInfo(f),
+      owner: f._debugOwner ? fiberInfo(f._debugOwner) : null,
+      propValueTag: tag,
+      propValue: trim(v, depth),
+    });
+  }
+});
+
+const rows = Array.from(groups.values()).sort((a, b) => b.count - a.count).slice(0, max);
+ctx.log.push('scanned: ' + scanned + ' matched: ' + matched + ' groups: ' + groups.size);
+return { propKey, totalFibers: scanned, matched, groups: groups.size, top: rows };

package/lib/mcp-skill/snippets/hook-metrics-sample.js

@@ -0,0 +1,69 @@
+// Capture a labeled before/after setStateCount delta in ONE call.
+//
+// This is the "lighthouse number" pattern as a first-class read: sample the cheap
+// counter, run a bounded action (a click by testId, or just settle), sample again,
+// return the delta. Answers "how many components fired setState during <phase>".
+//
+// METRIC IS OPTIONAL. The react-dom patch that emits __ATL_REACT_METRICS.setStateCount
+// may or may not be present. If it is absent, wiped, or non-finite (NaN), this snippet
+// returns { available:false, reason } and NEVER throws — callers must not rely on the
+// metric being there.
+//
+// Args:
+//   --label <text>     OPTIONAL. Human label for the phase (default "sample").
+//   --click <testId>   OPTIONAL. data-testid to click between before/after samples.
+//   --clicks <n>       OPTIONAL. repeat the click n times (default 1).
+//   --settleMs <n>     OPTIONAL. ms to wait after the action before the after-sample
+//                      (default 300). Also used as the whole wait when no --click.
+//
+// Output (available):
+//   { available:true, label, before, after, delta, clicked, settleMs }
+// Output (unavailable):
+//   { available:false, label, reason }
+
+function readSSC() {
+  const m = globalThis.__ATL_REACT_METRICS;
+  if (m == null) return { ok: false, reason: 'metrics absent (__ATL_REACT_METRICS is ' + String(m) + ')' };
+  const v = m.setStateCount;
+  if (typeof v !== 'number' || !Number.isFinite(v)) {
+    return { ok: false, reason: 'setStateCount is ' + String(v) + ' (patch absent or seeded non-numeric)' };
+  }
+  return { ok: true, value: v };
+}
+
+const label = ctx.args.label ? String(ctx.args.label) : 'sample';
+const settleMs = Number.isFinite(Number(ctx.args.settleMs)) ? Number(ctx.args.settleMs) : 300;
+const clickId = ctx.args.click ? String(ctx.args.click) : null;
+const clicks = Number(ctx.args.clicks) > 0 ? Number(ctx.args.clicks) : 1;
+
+const b = readSSC();
+if (!b.ok) {
+  ctx.log.push('setStateCount unavailable: ' + b.reason);
+  return { available: false, label, reason: b.reason };
+}
+const before = b.value;
+
+let clicked = 0;
+if (clickId) {
+  const sel = '[data-testid="' + clickId + '"]';
+  for (let i = 0; i < clicks; i++) {
+    const el = document.querySelector(sel);
+    if (el) { el.click(); clicked++; }
+    // small yield so React can flush between clicks
+    await new Promise((r) => setTimeout(r, Math.min(80, settleMs)));
+  }
+  if (clicked === 0) ctx.log.push('no element matched ' + sel);
+}
+
+await new Promise((r) => setTimeout(r, settleMs));
+
+const a = readSSC();
+if (!a.ok) {
+  // metric vanished mid-sample (host wiped it) — report honestly
+  return { available: false, label, reason: 'after-sample: ' + a.reason, before };
+}
+const after = a.value;
+
+ctx.log.push(label + ': ' + before + ' -> ' + after + ' (delta ' + (after - before) + ')');
+
+return { available: true, label, before, after, delta: after - before, clicked, settleMs };

package/lib/mcp-skill/snippets/hook-metrics.js

@@ -0,0 +1,60 @@
+// Read the host-owned React metrics object (__ATL_REACT_METRICS) — READ ONLY.
+//
+// Chippy READS this object; it does not create or seed it (the host/app owns it,
+// same way Chippy reads any avalanche counter). The only new hook-related number
+// here is `setStateCount` (useState/useReducer dispatches scheduled). Richer
+// hook-update accounting lives in the separate `hook-tracker` snippet.
+//
+// Args:
+//   --keys <csv>   OPTIONAL. Comma-separated counter names to return (default: all).
+//   --raw          OPTIONAL. If present, return every own key regardless of type.
+//
+// Output:
+//   { present, wiped, setStateCount, setStateCountValid, counters:{...}, onHookUpdateInstalled }
+//
+// NaN/undefined-safe: the host may seed setStateCount as null (then react-dom's
+// `null++` yields NaN) or wipe the whole object to undefined after hydration.
+// This reader reports those states honestly instead of throwing.
+
+const m = globalThis.__ATL_REACT_METRICS;
+
+if (m == null) {
+  ctx.log.push('__ATL_REACT_METRICS is ' + String(m) + ' (host absent or wiped post-hydration)');
+  return {
+    present: false,
+    wiped: typeof m === 'undefined',
+    note: 'Host metrics object not present. It may not exist yet, or the app wiped it after hydration. Reads return no data; use hook-tracker to own the onHookUpdate slot regardless.',
+  };
+}
+
+const wantKeys = ctx.args.keys
+  ? String(ctx.args.keys).split(',').map((s) => s.trim()).filter(Boolean)
+  : null;
+const raw = !!ctx.args.raw;
+
+const isNumericCounter = (v) => typeof v === 'number';
+
+const counters = {};
+for (const k of Object.keys(m)) {
+  if (wantKeys && !wantKeys.includes(k)) continue;
+  const v = m[k];
+  if (raw) { counters[k] = typeof v === 'function' ? '[Function ' + (v.name || 'anonymous') + ']' : v; continue; }
+  if (isNumericCounter(v)) counters[k] = v;
+}
+
+const ssc = m.setStateCount;
+const setStateCountValid = typeof ssc === 'number' && Number.isFinite(ssc);
+
+ctx.log.push('setStateCount=' + String(ssc) + ' valid=' + setStateCountValid + ' onHookUpdate=' + typeof m.onHookUpdate);
+
+return {
+  present: true,
+  wiped: false,
+  setStateCount: ssc,
+  setStateCountValid,
+  setStateCountNote: setStateCountValid
+    ? null
+    : 'setStateCount is ' + String(ssc) + '. Host likely seeded it as null/undefined and react-dom incremented it to NaN. It is still monotonic-per-run once numeric; re-seed via hook-tracker install if you need a clean baseline.',
+  onHookUpdateInstalled: typeof m.onHookUpdate === 'function',
+  counters,
+};