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

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,
+};

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

@@ -0,0 +1,198 @@
+// Drive the React hook-update tracker on the connected page.
+//
+// The react-dom patch only ever calls `metrics.onHookUpdate(fiber, kind, slot)` when
+// a memo/callback/effect RE-COMPUTES because its deps actually changed (update path,
+// post dep-equality check). It stores nothing itself. This snippet OWNS that callback
+// — the one thing Chippy installs (a consumer hook, not a whole detector) — records
+// per-(componentType, slot) update counts, and reports DB-safe histograms + dev-only
+// offenders. Faithful port of react-patch `src/metrics/hookTracker.ts`.
+//
+// Hook kinds are numeric on the hot path: 1 = memo, 2 = callback, 3 = effect.
+//
+// State persists across eval-page calls on `window.__CHIPPY_HOOK_TRACKER` because
+// install / interact / read / uninstall are separate invocations.
+//
+// Args:
+//   --action <name>   REQUIRED. One of:
+//                       install    seed metrics if absent, take ownership of onHookUpdate, mode='counts'
+//                       mode       set --mode off|counts|debug
+//                       status     report installed/mode/entryCount/onHookUpdate ownership
+//                       counts     dump source-of-truth: per componentType -> {counts[],type[]} (compact)
+//                       histogram  DB-safe: per-kind counts of slot identities reaching each --buckets bucket
+//                       offenders  dev-only: hook slots with count > --threshold, carrying component name
+//                       reset      clear accumulated counts (stay installed)
+//                       uninstall  restore onHookUpdate (only if we still own it), keep last counts
+//   --mode <m>        for action=mode: off | counts | debug
+//   --buckets <csv>   for action=histogram (default "3,6,11"). Positive finite numbers only.
+//   --threshold <N>   for action=offenders (default 10). Reports slots with count > N.
+//   --top <N>         for action=offenders: cap rows (default 20).
+//
+// NOTE: install requires a metrics object. On hosts that wipe __ATL_REACT_METRICS
+// to undefined (e.g. after hydration) this snippet SEEDS a minimal one so the tracker
+// can own the slot — mirroring how the tracker is meant to be installed independently.
+// It never overwrites an existing host object; it only adds the onHookUpdate slot.
+
+const MEMO = 1, CALLBACK = 2, EFFECT = 3;
+const KIND_NAME = { 1: 'memo', 2: 'callback', 3: 'effect' };
+
+function getDisplayName(t) {
+  if (typeof t === 'function') return t.displayName || t.name || 'anonymous';
+  return typeof t === 'string' ? t : 'unknown';
+}
+
+// ── persistent tracker singleton on the page ────────────────────────────────
+function getTracker() {
+  let T = globalThis.__CHIPPY_HOOK_TRACKER;
+  if (T && T.__v === 1) return T;
+
+  const state = {
+    __v: 1,
+    mode: 'off',
+    installed: false,
+    countsByType: new Map(),      // componentType -> { counts:number[], type:number[] }
+    lastFiberByType: new Map(),   // componentType -> fiber (debug mode only)
+    record: null,
+  };
+
+  function ctype(fiber) {
+    if (fiber == null || typeof fiber !== 'object') return 'unknown';
+    return fiber.elementType || fiber.type || 'unknown';
+  }
+
+  state.record = function record(fiber, kind, slot) {
+    if (state.mode === 'off') return;
+    const t = ctype(fiber);
+    let e = state.countsByType.get(t);
+    if (e == null) { e = { counts: [], type: [] }; state.countsByType.set(t, e); }
+    e.counts[slot] = (e.counts[slot] || 0) + 1;
+    e.type[slot] = kind;
+    if (state.mode === 'debug') state.lastFiberByType.set(t, fiber);
+  };
+
+  globalThis.__CHIPPY_HOOK_TRACKER = state;
+  return state;
+}
+
+function ensureMetrics() {
+  let m = globalThis.__ATL_REACT_METRICS;
+  if (m != null && typeof m === 'object') return { metrics: m, seeded: false };
+  // Host absent/wiped — seed a minimal object so the tracker can own onHookUpdate.
+  m = { setStateCount: 0 };
+  globalThis.__ATL_REACT_METRICS = m;
+  return { metrics: m, seeded: true };
+}
+
+const T = getTracker();
+const action = String(ctx.args.action || '').trim();
+
+if (action === 'install') {
+  const { metrics, seeded } = ensureMetrics();
+  // TODO: Preserve the displaced callback and owning metrics object on
+  // first install, then restore that callback only when this record function
+  // still owns the same slot. The current uninstall path calls this a restore
+  // but clears the slot to undefined, permanently dropping an earlier consumer.
+  metrics.onHookUpdate = T.record;
+  T.installed = true;
+  if (T.mode === 'off') T.mode = 'counts';
+  ctx.log.push('installed onHookUpdate; metrics ' + (seeded ? 'SEEDED' : 'existing') + '; mode=' + T.mode);
+  return { ok: true, action, installed: true, mode: T.mode, metricsSeeded: seeded, owns: metrics.onHookUpdate === T.record };
+}
+
+if (action === 'mode') {
+  const next = String(ctx.args.mode || '').trim();
+  if (!['off', 'counts', 'debug'].includes(next)) return { ok: false, error: "--mode must be off|counts|debug" };
+  T.mode = next;
+  return { ok: true, action, mode: T.mode };
+}
+
+if (action === 'status') {
+  const m = globalThis.__ATL_REACT_METRICS;
+  return {
+    ok: true, action,
+    installed: T.installed,
+    mode: T.mode,
+    owns: !!(m && m.onHookUpdate === T.record),
+    onHookUpdateType: m ? typeof m.onHookUpdate : 'no-metrics',
+    entryCount: T.countsByType.size,
+    setStateCount: m ? m.setStateCount : null,
+  };
+}
+
+if (action === 'reset') {
+  T.countsByType = new Map();
+  T.lastFiberByType = new Map();
+  return { ok: true, action, cleared: true, mode: T.mode, installed: T.installed };
+}
+
+if (action === 'uninstall') {
+  const m = globalThis.__ATL_REACT_METRICS;
+  let restored = false;
+  if (m != null && m.onHookUpdate === T.record) { m.onHookUpdate = undefined; restored = true; }
+  T.installed = false;
+  ctx.log.push('uninstalled; restored=' + restored);
+  return { ok: true, action, restored, entryCountRetained: T.countsByType.size };
+}
+
+if (action === 'counts') {
+  // Source of truth, compact. Aggregated by component TYPE (instances merge).
+  const rows = [];
+  for (const [t, e] of T.countsByType.entries()) {
+    let total = 0; const slots = [];
+    for (let s = 0; s < e.counts.length; s++) {
+      const c = e.counts[s] || 0;
+      if (!c) continue;
+      total += c;
+      slots.push({ slot: s, count: c, kind: KIND_NAME[e.type[s]] || e.type[s] });
+    }
+    rows.push({ type: getDisplayName(t), totalUpdates: total, activeSlots: slots.length, slots });
+  }
+  rows.sort((a, b) => b.totalUpdates - a.totalUpdates);
+  return { ok: true, action, mode: T.mode, entryCount: rows.length, types: rows };
+}
+
+if (action === 'histogram') {
+  const raw = ctx.args.buckets ? String(ctx.args.buckets) : '3,6,11';
+  const buckets = raw.split(',').map((s) => Number(s.trim()))
+    .filter((n) => Number.isFinite(n) && n > 0).sort((a, b) => a - b);
+  if (buckets.length === 0) return { ok: false, error: 'histogram requires at least one positive finite bucket' };
+  const out = { buckets: buckets.slice(), memo: buckets.map(() => 0), callback: buckets.map(() => 0), effect: buckets.map(() => 0) };
+  const arrFor = (k) => (k === MEMO ? out.memo : k === CALLBACK ? out.callback : out.effect);
+  for (const e of T.countsByType.values()) {
+    for (let s = 0; s < e.counts.length; s++) {
+      const c = e.counts[s] || 0;
+      if (!c) continue;
+      const k = e.type[s];
+      if (k !== MEMO && k !== CALLBACK && k !== EFFECT) continue;
+      const target = arrFor(k);
+      for (let b = 0; b < buckets.length; b++) if (c >= buckets[b]) target[b] += 1;
+    }
+  }
+  return { ok: true, action, histogram: out };
+}
+
+if (action === 'offenders') {
+  const threshold = Number.isFinite(Number(ctx.args.threshold)) ? Number(ctx.args.threshold) : 10;
+  const top = Number(ctx.args.top) || 20;
+  const offenders = [];
+  for (const [t, e] of T.countsByType.entries()) {
+    for (let s = 0; s < e.counts.length; s++) {
+      const c = e.counts[s] || 0;
+      if (c <= threshold) continue;
+      const k = e.type[s];
+      if (k !== MEMO && k !== CALLBACK && k !== EFFECT) continue;
+      const fiber = T.lastFiberByType.get(t);
+      offenders.push({
+        component: getDisplayName(t),
+        source: fiber && fiber._debugSource ? { fileName: fiber._debugSource.fileName, lineNumber: fiber._debugSource.lineNumber } : null,
+        hookId: s,
+        type: KIND_NAME[k],
+        count: c,
+      });
+    }
+  }
+  offenders.sort((a, b) => b.count - a.count);
+  if (T.mode !== 'debug') ctx.log.push('mode is "' + T.mode + '": source locations require --mode debug before reproducing.');
+  return { ok: true, action, threshold, mode: T.mode, offenders: offenders.slice(0, top) };
+}
+
+return { ok: false, error: 'unknown --action "' + action + '". Use install|mode|status|counts|histogram|offenders|reset|uninstall' };

package/lib/mcp-skill/snippets/stability-nudge.js

@@ -0,0 +1,101 @@
+// Stability render nudge — trigger a controlled re-render on a single fiber.
+//
+// PROCEDURE layer. The CAPABILITY (forcing a re-render via the React DevTools
+// renderer's scheduleUpdate) lives in the bundle:
+//   src/chippy-bridge/fiber-schedule-update.ts → window.__AVALANCHE__.bridge.evalFiberScheduleUpdate
+//
+// This snippet composes the stability-render procedure on top of that capability:
+// it resolves a probe/testId to a component fiber (DOM context the bridge does
+// not have), optionally climbs the owner chain, then asks the capability to
+// schedule exactly one re-render. Mutates nothing.
+//
+// Because the mechanism lives in the bundle, this procedure can evolve here with
+// zero extension/store publish. See references/stability-render.md.
+//
+// Args (one of --probeId or --testId is required):
+//   --probeId <id>            probe id ("1" | "2" | "3")
+//   --testId <string>         data-testid of the target element
+//   --ownerIndex <N>          optional, walk N steps up owner chain (default 0)
+//   --label <string>          optional, echoed into ctx.log
+//   --dryRun <true|false>     resolve + report fiber, do not schedule
+//
+// Returns: { ok, fiberName, source, ownerIndex, label?, reason? }
+
+const probeId = ctx.args.probeId == null ? null : String(ctx.args.probeId);
+const testId = ctx.args.testId == null ? null : String(ctx.args.testId);
+const ownerIndex = Number.isFinite(Number(ctx.args.ownerIndex)) ? (Number(ctx.args.ownerIndex) | 0) : 0;
+const label = ctx.args.label != null ? String(ctx.args.label) : null;
+const dryRun = ctx.args.dryRun === true || ctx.args.dryRun === 'true';
+
+if (!probeId && !testId) return { ok: false, reason: 'missing-target (need --probeId or --testId)' };
+if (label) ctx.log.push('label: ' + label);
+
+// 1. Resolve target → DOM node → composite fiber.
+function fiberFromNode(node) {
+  if (!node) return null;
+  const keys = Object.keys(node).filter((k) => k.startsWith('__reactFiber$'));
+  let f = keys.length ? node[keys[0]] : null;
+  while (f && (typeof f.type === 'string' || f.type == null)) f = f.return;
+  return f;
+}
+
+let fiber = null;
+if (testId) {
+  const node = document.querySelector('[data-testid="' + testId.replace(/"/g, '\\"') + '"]');
+  if (!node) return { ok: false, reason: 'testid-not-found: ' + testId, label };
+  ctx.log.push('resolved by testId: ' + testId);
+  fiber = fiberFromNode(node);
+  if (!fiber) return { ok: false, reason: 'no-composite-fiber-for-testid', label };
+} else {
+  const resolveAll = globalThis.__resolveProbes || globalThis.__resolveProbesCompact;
+  if (typeof resolveAll !== 'function') return { ok: false, reason: 'no-resolver', label };
+  const resolved = resolveAll(probeId);
+  const entry = Array.isArray(resolved) ? resolved[0] : resolved && resolved[probeId];
+  if (entry && entry.__fiber) {
+    fiber = entry.__fiber;
+  } else {
+    const lab = globalThis.__layoutLab;
+    const probe = lab && lab.getMarkerProbe ? lab.getMarkerProbe(probeId) : null;
+    const node = probe && probe.element;
+    if (!node) return { ok: false, reason: 'no-fiber', label };
+    fiber = fiberFromNode(node);
+    if (!fiber) return { ok: false, reason: 'no-composite-fiber', label };
+  }
+}
+
+if (dryRun) {
+  // Climb here only for reporting; the capability does its own walk on the real run.
+  let preview = fiber;
+  let walked = 0;
+  while (walked < ownerIndex && preview) { preview = preview._debugOwner || null; walked++; }
+  if (!preview) return { ok: false, reason: 'owner-out-of-range', label };
+  const name =
+    (preview.type && (preview.type.displayName || preview.type.name)) ||
+    (preview.elementType && (preview.elementType.displayName || preview.elementType.name)) ||
+    '<anonymous>';
+  const src = preview._debugSource
+    ? { fileName: preview._debugSource.fileName, lineNumber: preview._debugSource.lineNumber }
+    : null;
+  ctx.log.push('dryRun target: ' + name + (src ? ' @ ' + src.fileName + ':' + src.lineNumber : ''));
+  return { ok: true, dryRun: true, fiberName: name, source: src, ownerIndex, label };
+}
+
+// 2. Delegate the actual re-render to the bundle capability. We already hold the
+//    fiber, so we hand the capability deps that resolve straight to it.
+const av = globalThis.__AVALANCHE__;
+const bridge = av && av.bridge;
+if (!bridge || typeof bridge.evalFiberScheduleUpdate !== 'function') {
+  return { ok: false, reason: 'bridge-capability-missing (avalanche.iife.js not loaded)', label };
+}
+
+const FIXED_ID = '__nudge_target__';
+const result = bridge.evalFiberScheduleUpdate(FIXED_ID, ownerIndex, {
+  normalizeRememberedFiberId: (id) => (id === FIXED_ID ? FIXED_ID : null),
+  getRememberedFiber: (id) => (id === FIXED_ID ? fiber : null),
+});
+
+if (result && result.ok) {
+  ctx.log.push('scheduled: ' + result.fiberName + (result.source ? ' @ ' + result.source.fileName + ':' + result.source.lineNumber : ''));
+  return { ok: true, fiberName: result.fiberName, source: result.source, ownerIndex: result.ownerIndex, label };
+}
+return { ok: false, reason: (result && result.reason) || 'schedule-failed', error: result && result.error, fiberName: result && result.fiberName, label };

package/lib/package.json

@@ -0,0 +1 @@
+{"type":"module","sideEffects":["./bootstrap.js","./storybook/**","./extension/**"]}