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

package/lib/storybook/manager.jsx

@@ -0,0 +1,403 @@
+import { ChippyLogo } from './brand.jsx';
+import React, { useEffect, useState } from 'react';
+import { addons, types } from 'storybook/manager-api';
+import { AddonPanel, Badge, Button, ScrollArea } from 'storybook/internal/components';
+import { ADDON_ID, AVALANCHE_PANEL_ID, CHIPPY_PANEL_ID, EVENTS, PREVIEW_MESSAGE_SOURCE } from './constants.js';
+import { ChippyConnectionFallback } from './connection-fallback.jsx';
+import { commitSpan, describeCommitAction, groupCommitRows } from './avalanche-panel-model.js';
+import { ContextCard } from './context-card.jsx';
+import { ProbeAnnotationEditor } from './probe-annotation-editor.jsx';
+
+const panelFont = "'Atlassian Sans', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif";
+const theme = {
+  text: 'var(--ds-text, var(--color-default-text, CanvasText))',
+  muted: 'var(--color-subtle-text, color-mix(in srgb, CanvasText 64%, transparent))',
+  border: 'var(--color-medium-border, color-mix(in srgb, CanvasText 18%, transparent))',
+  panel: 'var(--ds-surface, var(--color-surface, Canvas))',
+  raised: 'var(--color-elevated-surface, color-mix(in srgb, Canvas 94%, CanvasText 6%))',
+  row: 'var(--color-hover-background, color-mix(in srgb, Canvas 88%, CanvasText 12%))',
+  danger: 'var(--color-negative-text, #ffb4ab)',
+};
+
+function postToPreview(message) {
+  const iframe = document.getElementById('storybook-preview-iframe');
+  iframe?.contentWindow?.postMessage({ source: PREVIEW_MESSAGE_SOURCE, ...message }, '*');
+}
+
+function isModeSelected(mode) {
+  const label = mode === 'avalanche' ? 'Avalanche' : 'Chippy';
+  const tab = Array.from(document.querySelectorAll('[role="tab"]'))
+    .find((candidate) => candidate.textContent?.trim() === label);
+  return tab?.getAttribute('aria-selected') === 'true';
+}
+
+function syncMode(channel, mode, active) {
+  if (!active || !isModeSelected(mode)) return;
+  channel.emit(EVENTS.SET_MODE, mode);
+  postToPreview({ event: EVENTS.SET_MODE, payload: mode });
+}
+
+function useChippyChannel(mode, active) {
+  const channel = addons.getChannel();
+  const [payload, setPayload] = useState(null);
+  const [lastResult, setLastResult] = useState(null);
+
+  useEffect(() => {
+    const onState = (next) => setPayload(next);
+    const onResult = (next) => setLastResult(next);
+    channel.on(EVENTS.STATE, onState);
+    channel.on(EVENTS.RESULT, onResult);
+    channel.emit(EVENTS.REQUEST_STATE);
+    syncMode(channel, mode, active);
+    const timer = setInterval(() => {
+      channel.emit(EVENTS.REQUEST_STATE);
+      syncMode(channel, mode, active);
+    }, 3000);
+    return () => {
+      clearInterval(timer);
+      channel.off(EVENTS.STATE, onState);
+      channel.off(EVENTS.RESULT, onResult);
+    };
+  }, [channel, active, mode]);
+
+  return {
+    payload,
+    lastResult,
+    command: (type, extra = {}) => {
+      const command = { type, ...extra };
+      if (!active || !isModeSelected(mode)) return;
+      channel.emit(EVENTS.COMMAND, command);
+      postToPreview({ event: EVENTS.COMMAND, payload: command });
+    },
+    refresh: () => channel.emit(EVENTS.REQUEST_STATE),
+  };
+}
+
+function statusFrom(payload) {
+  if (payload?.blocked) return { label: 'blocked', status: 'negative' };
+  const state = payload?.state;
+  if (!state) return { label: 'waiting', status: 'warning' };
+  return { label: state.connState || 'ready', status: state.connState === 'connected' ? 'positive' : 'warning' };
+}
+
+function RuntimeLine({ payload }) {
+  const state = payload?.state;
+  const owner = payload?.owner || state?.owner;
+  const integration = state?.integration || owner?.integration;
+  const status = statusFrom(payload);
+  const story = state?.page?.storyId || 'no story';
+  const client = state?.clientId ? String(state.clientId).slice(0, 8) : 'no client';
+  return (
+    <div style={{ display: 'flex', gap: 6, flexWrap: 'wrap', alignItems: 'center', color: theme.muted, fontSize: 11 }}>
+      <Badge status={status.status}>{status.label}</Badge>
+      <span>{integration?.who || 'Unidentified Chippy integration'}</span>
+      <span>({integration?.kind || 'unknown'})</span>
+      <span>·</span>
+      <span>{story}</span>
+      <span>·</span>
+      <span>{client}</span>
+    </div>
+  );
+}
+
+function Header({ title, children }) {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 12, marginBottom: 10 }}>
+      <h2 style={{ margin: 0, fontSize: 14, lineHeight: 1, color: theme.text, display: 'flex', alignItems: 'center', gap: 8 }}><ChippyLogo />{title}</h2>
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap', alignItems: 'center' }}>{children}</div>
+    </div>
+  );
+}
+
+function Footer({ payload }) {
+  return (
+    <details style={{ borderTop: `1px solid ${theme.border}`, paddingTop: 8, marginTop: 8 }}>
+      <summary style={{ cursor: 'pointer', color: theme.muted, fontSize: 11 }}>Connection details</summary>
+      <div style={{ marginTop: 8 }}><RuntimeLine payload={payload} /></div>
+    </details>
+  );
+}
+
+function Section({ title, children }) {
+  return (
+    <section style={{ borderTop: `1px solid ${theme.border}`, padding: '10px 0', color: theme.text }}>
+      {title ? <h3 style={{ margin: '0 0 8px', fontSize: 13, color: theme.text }}>{title}</h3> : null}
+      {children}
+    </section>
+  );
+}
+
+function Empty({ children }) {
+  return <div style={{ color: theme.muted, fontSize: 12, padding: '8px 0' }}>{children}</div>;
+}
+
+function SmallJson({ value }) {
+  if (value == null) return null;
+  return (
+    <details style={{ marginTop: 8, color: theme.text }}>
+      <summary style={{ cursor: 'pointer', color: theme.muted, fontSize: 12 }}>raw</summary>
+      <pre style={{ margin: '8px 0 0', whiteSpace: 'pre-wrap', fontSize: 11, lineHeight: 1.4, maxHeight: 240, overflow: 'auto', color: theme.text, background: theme.raised, border: `1px solid ${theme.border}`, borderRadius: 6, padding: 8 }}>
+        {JSON.stringify(value, null, 2)}
+      </pre>
+    </details>
+  );
+}
+
+function compactSource(source) {
+  if (!source?.fileName) return '—';
+  const file = String(source.fileName).split('/').slice(-2).join('/');
+  return `${file}${source.lineNumber ? `:${source.lineNumber}` : ''}`;
+}
+
+function MarkerSummary({ markers, onInspectBoundary, onAttachAnnotation }) {
+  const entries = Object.entries(markers || {});
+  if (!entries.length) return <Empty>Open the Chippy panel to activate probes. Drag P1/P2 from the dock onto the story.</Empty>;
+  return (
+    <div style={{ display: 'grid', gap: 8 }}>
+      {entries.map(([id, marker]) => {
+        const resolved = marker?.resolved || {};
+        const component = resolved.component || {};
+        const dom = resolved.dom || {};
+        const owners = component.owners || [];
+        const source = component.source || dom.source;
+        const markerContext = marker?.context ?? null;
+        return (
+          <div key={id} style={{ border: `1px solid ${theme.border}`, borderRadius: 8, padding: 8, background: theme.raised, color: theme.text }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', gap: 8 }}>
+              <strong>P{id}</strong>
+              <Badge status={resolved.confidence === 'dev' || resolved.confidence === 'high' ? 'positive' : 'neutral'}>{marker?.docked ? 'docked' : 'active'}</Badge>
+            </div>
+            <div style={{ color: theme.text, fontSize: 13, marginTop: 6, fontWeight: 600 }}>
+              {component.name || dom.tag || 'Drag marker onto the story'}
+            </div>
+            <div style={{ color: theme.muted, fontSize: 12, marginTop: 3 }}>
+              {resolved.nearestTestId ? `testId ${resolved.nearestTestId} · ` : ''}{dom.tag ? `<${dom.tag}>` : 'no DOM target'}
+            </div>
+            <div style={{ color: theme.muted, fontSize: 12, marginTop: 3 }}>source {compactSource(source)}</div>
+            {owners.length ? <div style={{ color: theme.muted, fontSize: 12, marginTop: 3 }}>owner {owners[0]?.name || '—'} · chain {owners.length}</div> : null}
+            <ContextCard
+              context={markerContext}
+              onInspectBoundary={
+                onInspectBoundary
+                  ? (kind) => onInspectBoundary(id, kind, markerContext?.boundaries?.[kind] || null)
+                  : undefined
+              }
+            />
+            {!marker?.docked ? (
+              <ProbeAnnotationEditor
+                markerId={id}
+                intent={marker?.intent}
+                comment={marker?.comment}
+                onAttach={(annotation) => onAttachAnnotation?.(id, annotation)}
+              />
+            ) : null}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function resultEnvelope(lastResult) {
+  const result = lastResult?.result || null;
+  const payload = result?.payload || null;
+  return { result, payload };
+}
+
+function rowsFromAvalanchePayload(payload) {
+  const auto = payload?.avalancheAuto || {};
+  return {
+    hotItems: auto.hotSources?.payload?.items || auto.hotSources?.items || [],
+    commitRows: auto.commitList?.rows || auto.commitList?.payload?.rows || [],
+  };
+}
+
+function rowsFromAvalancheResult(lastResult) {
+  const { result, payload } = resultEnvelope(lastResult);
+  if (!result) return { result: null, hotItems: [], commitRows: [], peek: null };
+  return {
+    result,
+    hotItems: result.action === 'hot-sources' ? payload?.items || [] : [],
+    commitRows: result.action === 'commit-list' ? result.rows || [] : [],
+    peek: result.action === 'commit-peek' ? payload || null : null,
+  };
+}
+
+function SimpleTable({ columns, rows, empty, onRowClick }) {
+  if (!rows?.length) return <Empty>{empty}</Empty>;
+  return (
+    <div style={{ border: `1px solid ${theme.border}`, borderRadius: 8, overflow: 'hidden', background: theme.panel, color: theme.text }}>
+      <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 12, color: theme.text }}>
+        <thead style={{ background: theme.raised }}>
+          <tr>{columns.map((column) => <th key={column.key} style={{ textAlign: 'left', padding: 8, borderBottom: `1px solid ${theme.border}`, color: theme.text }}>{column.label}</th>)}</tr>
+        </thead>
+        <tbody>
+          {rows.map((row, index) => (
+            <tr key={row.commitId || row.sourceId || index} onClick={onRowClick ? () => onRowClick(row) : undefined} style={{ cursor: onRowClick ? 'pointer' : 'default' }}>
+              {columns.map((column) => <td key={column.key} style={{ padding: 8, borderTop: index ? `1px solid ${theme.border}` : 'none', verticalAlign: 'top', color: theme.text }}>{column.render ? column.render(row) : String(row[column.key] ?? '—')}</td>)}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+function ChippyPanel({ active }) {
+  const { payload, command } = useChippyChannel('chippy', active);
+  const inspectBoundary = React.useCallback(
+    (markerId, boundaryKind, boundary) =>
+      command('inspect-boundary', {
+        markerId,
+        boundaryKind,
+        boundary,
+        distance: boundary?.distance ?? null,
+      }),
+    [command],
+  );
+  const attachAnnotation = React.useCallback(
+    (markerId, annotation) => command('set-probe-annotation', { markerId, ...annotation }),
+    [command],
+  );
+  const state = payload?.state;
+  const markers = state?.markers || {};
+  const probesVisible = Object.values(markers).some((marker) => marker?.position != null);
+  return (
+    <AddonPanel active={active}>
+      <ScrollArea vertical horizontal>
+        <div style={{ padding: 16, fontFamily: panelFont, maxWidth: 840, color: theme.text, background: theme.panel, minHeight: '100%' }}>
+          <Header title="Chippy">
+            <Button
+              size="small"
+              variant={probesVisible ? 'outline' : undefined}
+              onClick={() => command(probesVisible ? 'clear-probes' : 'ensure-probes')}
+            >
+              {probesVisible ? 'Hide probes' : 'Show probes'}
+            </Button>
+          </Header>
+          <ChippyConnectionFallback connState={state?.connState} />
+          <Section>
+            {probesVisible ? (
+              <div style={{ color: theme.muted, fontSize: 12, marginBottom: 8 }}>
+                While dragging: ← parent DOM · → toward target · ↑ parent component · ↓ toward target
+              </div>
+            ) : null}
+            {probesVisible
+              ? <MarkerSummary markers={markers} onInspectBoundary={inspectBoundary} onAttachAnnotation={attachAnnotation} />
+              : <Empty>Show probes when you want to inspect an element in the story.</Empty>}
+          </Section>
+          <Footer payload={payload} />
+        </div>
+      </ScrollArea>
+    </AddonPanel>
+  );
+}
+
+function AvalanchePanel({ active }) {
+  const { payload, lastResult, command } = useChippyChannel('avalanche', active);
+  const autoRows = rowsFromAvalanchePayload(payload);
+  const { result, peek } = rowsFromAvalancheResult(lastResult);
+  const hotItems = autoRows.hotItems;
+  const rows = autoRows.commitRows;
+  const patterns = groupCommitRows(rows);
+
+  const status = payload?.avalancheStatus?.status || payload?.state?.avalanche?.status || null;
+  const error = result?.ok === false ? result.error : null;
+
+  useEffect(() => {
+    if (!active) return;
+    if (status?.installed) return;
+    const timer = setTimeout(() => command('avalanche-install', { reason: 'panel-active-retry' }), 250);
+    return () => clearTimeout(timer);
+  }, [active, status?.installed]);
+
+  return (
+    <AddonPanel active={active}>
+      <ScrollArea vertical horizontal>
+        <div style={{ padding: 16, fontFamily: panelFont, maxWidth: 980, color: theme.text, background: theme.panel, minHeight: '100%' }}>
+          <Header title="Avalanche" />
+          <ChippyConnectionFallback connState={payload?.state?.connState} />
+          {error ? <div style={{ color: theme.danger, fontSize: 12, marginBottom: 8 }}>{error}</div> : null}
+          <Section title="Commit patterns">
+            <SimpleTable
+              rows={patterns}
+              empty="Waiting for the story to render something new."
+              onRowClick={(group) => command('avalanche-commit-peek', { commitId: group.representative.commitId })}
+              columns={[
+                { key: 'count', label: 'repeats', render: (group) => group.count === 1 ? 'once' : `${group.count}×` },
+                { key: 'span', label: 'commits', render: commitSpan },
+                { key: 'action', label: 'activity', render: (group) => describeCommitAction(group.representative) },
+                { key: 'sources', label: 'sources', render: (group) => group.representative.sourceCount ?? 0 },
+                { key: 'collateral', label: 'collateral', render: (group) => group.representative.stat?.collateral ?? 0 },
+                { key: 'effects', label: 'effects', render: (group) => group.representative.stat?.effects ?? 0 },
+              ]}
+            />
+          </Section>
+          <Section title="Sources with the widest impact">
+            <SimpleTable
+              rows={hotItems.slice(0, 10)}
+              empty="No source has caused measurable downstream work yet."
+              columns={[
+                { key: 'sourceId', label: 'source' },
+                { key: 'collateralUpdates', label: 'collateral' },
+                { key: 'causedUpdates', label: 'caused' },
+                { key: 'restartWaste', label: 'restart waste' },
+              ]}
+            />
+          </Section>
+          {peek ? (
+            <Section title={`Commit ${peek.commitId} peek`}>
+              <div style={{ display: 'flex', gap: 10, color: theme.muted, fontSize: 12, marginBottom: 8 }}>
+                <span>found: <strong style={{ color: theme.text }}>{String(!!peek.found)}</strong></span>
+                <span>sources: <strong style={{ color: theme.text }}>{peek.sourcesTotal ?? peek.sources?.length ?? 0}</strong></span>
+                <span>actions: <strong style={{ color: theme.text }}>{peek.actionsTotal ?? peek.actions?.length ?? 0}</strong></span>
+              </div>
+              <SimpleTable
+                rows={peek.sources || []}
+                empty="No source rows in this peek."
+                columns={[
+                  { key: 'sourceId', label: 'source' },
+                  { key: 'collateralAtCommit', label: 'collateral@commit' },
+                  { key: 'causedUpdatesTotal', label: 'caused total' },
+                  { key: 'collateralUpdatesTotal', label: 'collateral total' },
+                ]}
+              />
+              <SmallJson value={peek} />
+            </Section>
+          ) : null}
+          <details style={{ marginTop: 8 }}>
+            <summary style={{ cursor: 'pointer', color: theme.muted, fontSize: 12 }}>Individual commits ({rows.length})</summary>
+            <div style={{ marginTop: 8 }}>
+              <SimpleTable
+                rows={rows}
+                empty="No commits captured."
+                onRowClick={(row) => command('avalanche-commit-peek', { commitId: row.commitId })}
+                columns={[
+                  { key: 'commitId', label: 'commit' },
+                  { key: 'sourceCount', label: 'sources' },
+                  { key: 'collateral', label: 'collateral', render: (row) => row.stat?.collateral ?? 0 },
+                  { key: 'effects', label: 'effects', render: (row) => row.stat?.effects ?? 0 },
+                  { key: 'action', label: 'activity', render: describeCommitAction },
+                ]}
+              />
+            </div>
+          </details>
+          <Footer payload={payload} />
+        </div>
+      </ScrollArea>
+    </AddonPanel>
+  );
+}
+
+addons.register(ADDON_ID, () => {
+  addons.add(CHIPPY_PANEL_ID, {
+    title: 'Chippy',
+    type: types.PANEL,
+    render: ({ active }) => <ChippyPanel active={active} />,
+  });
+  addons.add(AVALANCHE_PANEL_ID, {
+    title: 'Avalanche',
+    type: types.PANEL,
+    render: ({ active }) => <AvalanchePanel active={active} />,
+  });
+});

package/lib/storybook/preset.js

@@ -0,0 +1,7 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export const managerEntries = (entry = []) => [...entry, join(here, 'manager.jsx')];
+export const previewAnnotations = (entry = []) => [...entry, join(here, 'preview.js')];

package/lib/storybook/preview.js

@@ -0,0 +1,263 @@
+import { addons } from 'storybook/preview-api';
+import { FORCE_REMOUNT, STORY_CHANGED, STORY_HOT_UPDATED } from 'storybook/internal/core-events';
+import { EVENTS, PREVIEW_MESSAGE_SOURCE } from './constants.js';
+import { OWNER_ID, ownerResult } from './setup.js';
+
+import '../extension/inspect-react.js';
+import '../extension/panel-dom.js';
+import '../extension/layout-lab.js';
+import '../extension/resolve-probes.js';
+import avalanche from '../extension/avalanche.es.js';
+import '../extension/chippy-page-bridge.js';
+
+if (ownerResult.ok) {
+  globalThis.__AVALANCHE__ = globalThis.__AVALANCHE__ || avalanche;
+  // Static ESM imports evaluate before setup.js can finish stamping
+  // __CHIPPY_STARTUP_CONFIG. Honor reload-with-avalanche autoStart here too,
+  // after setup.js has run and the addon owns the page.
+  const arm = globalThis.__CHIPPY_STARTUP_CONFIG?.avalanche || null;
+  const api = globalThis.__AVALANCHE__;
+  if (arm?.autoStart && api && typeof api.install === 'function' && !api.status?.().installed) {
+    try {
+      api.install({
+        detectionMode: arm.options?.detectionMode || 'sources',
+        historySize: arm.max || 1000,
+        captureFibers: arm.options?.captureFibers !== false,
+      });
+    } catch (_) {}
+  }
+}
+
+function emit(channel, event, payload) {
+  try {
+    channel.emit(event, payload);
+  } catch {
+    // Storybook channel can be briefly unavailable during preview reloads.
+  }
+}
+
+function getBridge() {
+  return globalThis.__CHIPPY?.pageBridge || null;
+}
+
+function getAvalancheApi() {
+  return globalThis.__AVALANCHE__ || avalanche || null;
+}
+
+function runAvalanche(action, command = {}) {
+  const api = getAvalancheApi();
+  const dispatcher = api?.bridge?.evalAvalanche;
+  if (typeof dispatcher !== 'function') {
+    return { ok: false, available: !!api, action, error: 'avalanche dispatcher unavailable' };
+  }
+  return dispatcher({ action, ...command }, api, api);
+}
+
+let avalancheStoryId = null;
+let avalancheAutoCache = null;
+
+function currentStoryId() {
+  return new URLSearchParams(globalThis.location.search || '').get('id') || globalThis.__STORYBOOK_STORY_STORE__?.selection?.storyId || null;
+}
+
+function ensureAvalancheInstalled({ resetForStory = false } = {}) {
+  const storyId = currentStoryId();
+  const status = runAvalanche('status');
+  const installed = status?.status?.installed || status?.result?.status?.installed;
+  if (!installed) {
+    runAvalanche('install', { options: { detectionMode: 'sources', historySize: 5000, captureFibers: true } });
+    avalancheStoryId = storyId;
+    avalancheAutoCache = null;
+    return;
+  }
+  if (resetForStory && storyId && storyId !== avalancheStoryId) {
+    runAvalanche('clear');
+    avalancheStoryId = storyId;
+    avalancheAutoCache = null;
+  }
+}
+
+function refreshAvalancheAuto() {
+  ensureAvalancheInstalled({ resetForStory: true });
+  avalancheAutoCache = {
+    storyId: currentStoryId(),
+    status: runAvalanche('status'),
+    hotSources: runAvalanche('hot-sources', { limit: 50 }),
+    commitList: runAvalanche('commit-list', { top: 1000, by: 'collateral' }),
+  };
+  return avalancheAutoCache;
+}
+
+function statePayload(extra = {}) {
+  const bridge = getBridge();
+  const mode = globalThis.__CHIPPY_OWNER__?.mode || bridge?.getState?.()?.config?.mode;
+  const avalancheAuto = mode === 'avalanche' ? refreshAvalancheAuto() : avalancheAutoCache;
+  return {
+    ok: !!bridge,
+    owner: globalThis.__CHIPPY_OWNER__ || null,
+    blocked: globalThis.__CHIPPY_BLOCKED__ || null,
+    state: bridge?.getState?.() || null,
+    avalancheStatus: avalancheAuto?.status || runAvalanche('status'),
+    avalancheAuto,
+    ...extra,
+  };
+}
+
+function activeMode() {
+  return globalThis.__CHIPPY_OWNER__?.mode || globalThis.__CHIPPY?.pageBridge?.getState?.()?.config?.mode;
+}
+
+function resetAvalancheForBoundary(reason) {
+  runAvalanche('clear');
+  avalancheStoryId = currentStoryId();
+  avalancheAutoCache = null;
+  if (activeMode() === 'avalanche') {
+    ensureAvalancheInstalled();
+    refreshAvalancheAuto();
+    publishState(channel, `avalanche-reset:${reason}`);
+  }
+}
+
+function syncActiveLifecycle() {
+  if (activeMode() === 'avalanche') ensureAvalancheInstalled({ resetForStory: true });
+}
+
+function publishState(channel, reason = 'state') {
+  syncActiveLifecycle();
+  emit(channel, EVENTS.STATE, statePayload({ reason }));
+}
+
+function executeCommand(command) {
+  const bridge = getBridge();
+  if (!bridge) return { ok: false, error: 'bridge-not-ready' };
+  switch (command?.type) {
+    case 'activate':
+      bridge.activate?.();
+      return { ok: true };
+    case 'deactivate':
+      bridge.deactivate?.();
+      return { ok: true };
+    case 'ensure-probes':
+      bridge.activate?.();
+      bridge.ensureProbes?.();
+      return { ok: true };
+    case 'clear-probes':
+      bridge.clearProbes?.();
+      return { ok: true };
+    case 'set-probe-annotation': {
+      const annotation = bridge.setProbeAnnotation?.(command.markerId, {
+        intent: command.intent ?? null,
+        comment: command.comment ?? '',
+      });
+      return annotation
+        ? { ok: true, markerId: command.markerId, annotation }
+        : { ok: false, error: `probe-not-found:${command.markerId || 'missing'}` };
+    }
+    case 'avalanche-install': {
+      globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID, { mode: 'avalanche' });
+      bridge.applyConfig?.({ mode: 'avalanche', activated: false });
+      ensureAvalancheInstalled({ resetForStory: true });
+      return runAvalanche('status');
+    }
+    case 'avalanche-stop':
+      return runAvalanche('uninstall');
+    case 'avalanche-clear':
+      ensureAvalancheInstalled();
+      return runAvalanche('clear');
+    case 'avalanche-status':
+      ensureAvalancheInstalled();
+      return runAvalanche('status');
+    case 'avalanche-export':
+      ensureAvalancheInstalled();
+      return runAvalanche('export');
+    case 'avalanche-hot-sources':
+      ensureAvalancheInstalled();
+      return runAvalanche('hot-sources', { limit: command.limit || 50 });
+    case 'avalanche-commit-list':
+      ensureAvalancheInstalled();
+      return runAvalanche('commit-list', { top: command.top || 1000, by: command.by || 'collateral' });
+    case 'avalanche-commit-peek':
+      ensureAvalancheInstalled();
+      return runAvalanche('commit-peek', {
+        commitId: command.commitId,
+        include: command.include || ['stats', 'sources', 'timing', 'metrics', 'actions'],
+        maxItems: command.maxItems || 20,
+      });
+    case 'inspect-boundary':
+      // Report the selected collateral boundary (owner/error/suspense) + its
+      // fiber-hop distance back to the backend. The click already carries the
+      // resolved descriptor; the addon acknowledges it as a first-class result
+      // so downstream consumers can act on the collateral boundary.
+      return {
+        ok: true,
+        markerId: command.markerId ?? null,
+        boundaryKind: command.boundaryKind ?? null,
+        boundary: command.boundary ?? null,
+        distance: command.distance ?? command.boundary?.distance ?? null,
+      };
+    default:
+      return { ok: false, error: `unknown-command:${command?.type || 'missing'}` };
+  }
+}
+
+const channel = addons.getChannel();
+
+function handleMode(mode) {
+  globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID, { mode });
+  const bridge = getBridge();
+  if (bridge?.applyConfig) bridge.applyConfig(mode === 'chippy' ? { mode } : { mode, activated: false });
+  if (mode !== 'chippy') {
+    bridge?.clearProbes?.();
+  }
+  if (mode === 'avalanche') ensureAvalancheInstalled({ resetForStory: true });
+  publishState(channel, 'mode');
+}
+
+function handleCommand(command) {
+  const result = executeCommand(command);
+  emit(channel, EVENTS.RESULT, { command, result, state: statePayload({ reason: 'command' }) });
+  publishState(channel, `command:${command?.type || 'unknown'}`);
+}
+
+channel.on(EVENTS.REQUEST_STATE, () => publishState(channel, 'request'));
+channel.on(EVENTS.SET_MODE, handleMode);
+channel.on(EVENTS.COMMAND, handleCommand);
+channel.on(STORY_CHANGED, () => resetAvalancheForBoundary('story-changed'));
+channel.on(FORCE_REMOUNT, () => resetAvalancheForBoundary('force-remount'));
+channel.on(STORY_HOT_UPDATED, () => resetAvalancheForBoundary('story-hot-updated'));
+window.addEventListener('message', (event) => {
+  const data = event.data || {};
+  if (data.source !== PREVIEW_MESSAGE_SOURCE) return;
+  if (data.event === EVENTS.SET_MODE) handleMode(data.payload);
+  if (data.event === EVENTS.COMMAND) handleCommand(data.payload);
+});
+
+window.addEventListener('chippy-storybook-force-remount', (event) => {
+  // Keep Storybook's manager and preview alive. FORCE_REMOUNT replaces only
+  // the rendered SUT, unlike reloading the preview iframe document.
+  emit(channel, FORCE_REMOUNT);
+  event.preventDefault();
+});
+
+window.addEventListener('chippy-conn-state', () => publishState(channel, 'conn-state'));
+window.addEventListener('layout-lab:update', () => publishState(channel, 'layout-lab'));
+
+// A marker starts life after a manager-panel button was focused. Because the
+// shared drag handler prevents pointerdown's default, Storybook would otherwise
+// keep keyboard focus in the manager document and arrow navigation would never
+// reach the preview iframe.
+document.addEventListener('pointerdown', (event) => {
+  const marker = event.target?.closest?.('[data-layout-lab-marker]');
+  marker?.focus?.({ preventScroll: true });
+}, true);
+
+setInterval(() => {
+  globalThis.__CHIPPY_LOCK__?.heartbeat?.(OWNER_ID);
+  publishState(channel, 'heartbeat');
+}, 5000);
+
+publishState(channel, ownerResult.ok ? 'ready' : 'blocked');
+
+export const decorators = [
+  (Story) => Story(),
+];