@component-anatomy/storybook 0.0.2 → 0.2.0

package/src/AnatomyTable.tsx

@@ -0,0 +1,238 @@
+/**
+ * The anatomy part table — pure presentation, no Storybook imports.
+ *
+ * This module is deliberately free of `storybook/manager-api` and
+ * `storybook/preview-api`: it is bundled into *both* the manager entry (the
+ * addon panel) and the blocks entry (the `<Anatomy>` MDX doc block), which
+ * run in different runtimes and cannot share either of those APIs. Only the
+ * data acquisition differs between the two; the markup must not.
+ */
+import React from 'react';
+import { useTheme } from 'storybook/theming';
+import { resolvePanelAccent } from '@component-anatomy/core';
+import type {
+  AnatomyPartDefinition,
+  AnatomyPresetName,
+  AnatomyTheme,
+} from '@component-anatomy/core';
+
+/**
+ * The subset of Storybook's theme this table reads. Typed loosely on purpose:
+ * `useTheme()` resolves to an empty `Theme` interface (Emotion augmentation),
+ * and outside a ThemeProvider it returns `{}` — so every read is optional and
+ * every value has a literal fallback below.
+ */
+type PartialStorybookTheme = {
+  fgColor?: { default?: string; muted?: string };
+  bgColor?: { default?: string; muted?: string };
+  borderColor?: { default?: string };
+  typography?: { fonts?: { base?: string; mono?: string } };
+};
+
+const FONT_BASE_FALLBACK =
+  '"Nunito Sans", -apple-system, ".SFNSText-Regular", "San Francisco", BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif';
+const FONT_MONO_FALLBACK = 'ui-monospace, "Cascadia Code", "Fira Mono", monospace';
+
+/**
+ * Resolves the table's chrome colors from Storybook's theme so the same
+ * markup reads correctly in the manager panel *and* in a docs page under a
+ * dark theme.
+ *
+ * `surfaceBg`/`surfaceFg` are not painted anywhere — they are what the accent
+ * is measured against in {@link useAccent}. They carry Storybook's own light
+ * defaults as fallbacks so the measurement stays meaningful outside a
+ * ThemeProvider, where `useTheme()` returns `{}`.
+ */
+function usePalette() {
+  const theme = useTheme() as PartialStorybookTheme;
+  return {
+    text: theme.fgColor?.default,
+    muted: theme.fgColor?.muted ?? '#6b7280',
+    mutedBg: theme.bgColor?.muted ?? 'rgba(0,0,0,0.06)',
+    border: theme.borderColor?.default ?? 'rgba(0,0,0,0.08)',
+    surfaceBg: theme.bgColor?.default ?? '#ffffff',
+    surfaceFg: theme.fgColor?.default ?? '#2e3438',
+    fontBase: theme.typography?.fonts?.base ?? FONT_BASE_FALLBACK,
+    fontMono: theme.typography?.fonts?.mono ?? FONT_MONO_FALLBACK,
+  };
+}
+
+type Palette = ReturnType<typeof usePalette>;
+
+/**
+ * The accent for the active row — the story's own `{ preset, theme }`, so the
+ * table agrees with the overlays it describes, lifted to WCAG AA against the
+ * surface it is painted on when the two disagree.
+ *
+ * The check is not optional polish: `preset: 'contrast'` is black on yellow
+ * and the Storybook manager is dark by default, so the preset that exists for
+ * users who need contrast is exactly the one that would land at 1.3:1 here.
+ */
+function useAccent(palette: Palette, preset?: AnatomyPresetName, theme?: AnatomyTheme): string {
+  return resolvePanelAccent(preset, theme, {
+    background: palette.surfaceBg,
+    foreground: palette.surfaceFg,
+  });
+}
+
+const makeStyles = (p: Palette): Record<string, React.CSSProperties> => ({
+  container: {
+    padding: '12px 16px',
+    fontFamily: p.fontBase,
+    fontSize: 13,
+    lineHeight: 1.5,
+    color: p.text,
+  },
+  empty: {
+    color: p.muted,
+    margin: 0,
+  },
+  code: {
+    fontFamily: p.fontMono,
+    fontSize: '0.85em',
+    background: p.mutedBg,
+    borderRadius: 3,
+    padding: '1px 5px',
+  },
+  list: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    margin: 0,
+    padding: 0,
+    listStyle: 'none',
+  },
+  entry: {
+    padding: '8px 10px',
+    borderRadius: 6,
+    border: '1px solid transparent',
+    cursor: 'default',
+    outline: 'none',
+    transition: 'background 120ms ease, border-color 120ms ease',
+  },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: 8,
+  },
+  indicator: {
+    width: 8,
+    height: 8,
+    borderRadius: '50%',
+    border: `2px solid ${p.border}`,
+    flexShrink: 0,
+    transition: 'background 120ms ease, border-color 120ms ease',
+  },
+  name: {
+    fontWeight: 700,
+    flex: 1,
+  },
+  id: {
+    fontFamily: p.fontMono,
+    fontSize: 10,
+    padding: '1px 6px',
+    borderRadius: 4,
+    background: p.mutedBg,
+    border: `1px solid ${p.border}`,
+    color: p.muted,
+    flexShrink: 0,
+  },
+  description: {
+    margin: '4px 0 0',
+    paddingLeft: 16,
+    color: p.muted,
+  },
+});
+
+/**
+ * An inline `<code>` styled for the surrounding message text. Exported so
+ * both runtimes can compose their own empty-state copy without duplicating
+ * the style object.
+ */
+export const AnatomyCode: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const styles = makeStyles(usePalette());
+  return <code style={styles.code}>{children}</code>;
+};
+
+/** A padded, muted paragraph — used for every "nothing to show" state. */
+export const AnatomyMessage: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const styles = makeStyles(usePalette());
+  return (
+    <div style={styles.container}>
+      <p style={styles.empty}>{children}</p>
+    </div>
+  );
+};
+
+export type AnatomyTableProps = {
+  /** Parts to list, in the order they should be shown. */
+  parts: AnatomyPartDefinition[];
+  /** Id of the part currently highlighted in the canvas, if any. */
+  activeId?: string | null;
+  /** The story's `anatomy.preset` — the active row follows it. */
+  preset?: AnatomyPresetName;
+  /** The story's `anatomy.theme` — token overrides on top of the preset. */
+  theme?: AnatomyTheme;
+  /** Called when the user hovers or focuses an entry. */
+  onItemEnter?: (partId: string) => void;
+  /** Called when the user leaves or blurs an entry. */
+  onItemLeave?: () => void;
+};
+
+export const AnatomyTable: React.FC<AnatomyTableProps> = ({
+  parts,
+  activeId = null,
+  preset,
+  theme,
+  onItemEnter,
+  onItemLeave,
+}) => {
+  const palette = usePalette();
+  const styles = makeStyles(palette);
+  const accent = useAccent(palette, preset, theme);
+
+  return (
+    <div style={styles.container}>
+      <ul style={styles.list} role="list" aria-label="Anatomy parts">
+        {parts.map((part) => {
+          const active = activeId === part.id;
+          return (
+            <li
+              key={part.id}
+              role="listitem"
+              tabIndex={0}
+              aria-label={part.name}
+              style={{
+                ...styles.entry,
+                background: active ? `color-mix(in srgb, ${accent} 7%, transparent)` : undefined,
+                borderColor: active
+                  ? `color-mix(in srgb, ${accent} 20%, transparent)`
+                  : 'transparent',
+              }}
+              onMouseEnter={() => onItemEnter?.(part.id)}
+              onMouseLeave={() => onItemLeave?.()}
+              onFocus={() => onItemEnter?.(part.id)}
+              onBlur={() => onItemLeave?.()}
+            >
+              <div style={styles.header}>
+                <span
+                  aria-hidden="true"
+                  style={{
+                    ...styles.indicator,
+                    background: active ? accent : undefined,
+                    borderColor: active ? accent : palette.border,
+                  }}
+                />
+                <span style={{ ...styles.name, color: active ? accent : undefined }}>
+                  {part.name}
+                </span>
+                <code style={styles.id}>{part.id}</code>
+              </div>
+              {part.description && <p style={styles.description}>{part.description}</p>}
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+};

package/src/Panel.tsx

@@ -3,78 +3,11 @@ import { useChannel, useParameter, useStorybookApi } from 'storybook/manager-api
 import type { AnatomyPartDefinition } from '@component-anatomy/core';
 
 import { EVENTS, PARAM_KEY } from './constants.js';
+import { matchesStory } from './channel.js';
+import type { PartEnterEvent, PartsEvent, StoryScopedEvent } from './channel.js';
+import { AnatomyCode, AnatomyMessage, AnatomyTable } from './AnatomyTable.js';
 import type { AnatomyParameters } from './types.js';
 
-const ACCENT_FALLBACK = '#4f46e5';
-
-const styles: Record<string, React.CSSProperties> = {
-  container: {
-    padding: '12px 16px',
-    fontFamily:
-      '"Nunito Sans", -apple-system, ".SFNSText-Regular", "San Francisco", BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif',
-    fontSize: 13,
-    lineHeight: 1.5,
-  },
-  empty: {
-    color: '#6b7280',
-  },
-  code: {
-    fontFamily: 'ui-monospace, "Cascadia Code", "Fira Mono", monospace',
-    fontSize: '0.85em',
-    background: 'rgba(0,0,0,0.06)',
-    borderRadius: 3,
-    padding: '1px 5px',
-  },
-  list: {
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 2,
-    margin: 0,
-    padding: 0,
-    listStyle: 'none',
-  },
-  entry: {
-    padding: '8px 10px',
-    borderRadius: 6,
-    border: '1px solid transparent',
-    cursor: 'default',
-    outline: 'none',
-    transition: 'background 120ms ease, border-color 120ms ease',
-  },
-  header: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: 8,
-  },
-  indicator: {
-    width: 8,
-    height: 8,
-    borderRadius: '50%',
-    border: '2px solid #d1d5db',
-    flexShrink: 0,
-    transition: 'background 120ms ease, border-color 120ms ease',
-  },
-  name: {
-    fontWeight: 700,
-    flex: 1,
-  },
-  id: {
-    fontFamily: 'ui-monospace, "Cascadia Code", "Fira Mono", monospace',
-    fontSize: 10,
-    padding: '1px 6px',
-    borderRadius: 4,
-    background: 'rgba(0,0,0,0.05)',
-    border: '1px solid rgba(0,0,0,0.08)',
-    color: '#6b7280',
-    flexShrink: 0,
-  },
-  description: {
-    margin: '4px 0 0',
-    paddingLeft: 16,
-    color: '#6b7280',
-  },
-};
-
 export const Panel: React.FC = () => {
   const params = useParameter<AnatomyParameters | undefined>(PARAM_KEY, undefined);
   const api = useStorybookApi();
@@ -83,86 +16,74 @@ export const Panel: React.FC = () => {
   const [discovered, setDiscovered] = useState<AnatomyPartDefinition[]>([]);
   const [activeId, setActiveId] = useState<string | null>(null);
 
-  const emit = useChannel({
-    [EVENTS.PARTS]: ({ parts }: { parts: AnatomyPartDefinition[] }) => setDiscovered(parts),
-    [EVENTS.PART_ENTER]: ({ partId }: { partId: string }) => setActiveId(partId),
-    [EVENTS.PART_LEAVE]: () => setActiveId(null),
-  });
+  // `useChannel` captures its handlers on the given deps — `storyId` has to be
+  // listed or the filters below would close over a stale story.
+  const emit = useChannel(
+    {
+      [EVENTS.PARTS]: (event: PartsEvent) => {
+        if (!matchesStory(event?.storyId, storyId)) return;
+        setDiscovered(event.parts);
+      },
+      [EVENTS.PART_ENTER]: (event: PartEnterEvent) => {
+        if (!matchesStory(event?.storyId, storyId)) return;
+        setActiveId(event.partId);
+      },
+      [EVENTS.PART_LEAVE]: (event: StoryScopedEvent = {}) => {
+        if (!matchesStory(event?.storyId, storyId)) return;
+        setActiveId(null);
+      },
+    },
+    [storyId]
+  );
 
   // Ask the preview for the current part list on mount / story change.
   useEffect(() => {
     setDiscovered([]);
     setActiveId(null);
-    emit(EVENTS.PARTS_REQUEST);
+    emit(EVENTS.PARTS_REQUEST, { storyId } satisfies StoryScopedEvent);
   }, [storyId]);
 
   const parts = params?.parts ?? discovered;
-  const accent = params?.theme?.accent ?? ACCENT_FALLBACK;
 
-  if (!params || params.disable) {
+  if (!params) {
+    return (
+      <AnatomyMessage>
+        No anatomy configured for this story. Add <AnatomyCode>parameters.anatomy</AnatomyCode> and
+        annotate elements with <AnatomyCode>data-part="name"</AnatomyCode>.
+      </AnatomyMessage>
+    );
+  }
+
+  // Defence in depth: Storybook removes a panel from the tab bar entirely when
+  // `parameters[paramKey].disable` is set, so this normally never renders. If
+  // it ever does, say the right thing — a disabled story *has* an anatomy, and
+  // telling its author to add one sends them the wrong way.
+  if (params.disable) {
     return (
-      <div style={styles.container}>
-        <p style={styles.empty}>
-          No anatomy configured for this story. Add{' '}
-          <code style={styles.code}>parameters.anatomy</code> and annotate elements with{' '}
-          <code style={styles.code}>data-part="name"</code>.
-        </p>
-      </div>
+      <AnatomyMessage>
+        Anatomy is disabled for this story (<AnatomyCode>anatomy.disable</AnatomyCode>).
+      </AnatomyMessage>
     );
   }
 
   if (parts.length === 0) {
     return (
-      <div style={styles.container}>
-        <p style={styles.empty}>
-          No parts found. Annotate elements in your story with{' '}
-          <code style={styles.code}>data-part="name"</code> or pass{' '}
-          <code style={styles.code}>parameters.anatomy.parts</code>.
-        </p>
-      </div>
+      <AnatomyMessage>
+        No parts found. Annotate elements in your story with{' '}
+        <AnatomyCode>data-part="name"</AnatomyCode> or pass{' '}
+        <AnatomyCode>parameters.anatomy.parts</AnatomyCode>.
+      </AnatomyMessage>
     );
   }
 
   return (
-    <div style={styles.container}>
-      <ul style={styles.list} role="list" aria-label="Anatomy parts">
-        {parts.map((part) => {
-          const active = activeId === part.id;
-          return (
-            <li
-              key={part.id}
-              role="listitem"
-              tabIndex={0}
-              aria-label={part.name}
-              style={{
-                ...styles.entry,
-                background: active ? `color-mix(in srgb, ${accent} 7%, transparent)` : undefined,
-                borderColor: active ? `color-mix(in srgb, ${accent} 20%, transparent)` : 'transparent',
-              }}
-              onMouseEnter={() => emit(EVENTS.HOVER_ITEM, { partId: part.id })}
-              onMouseLeave={() => emit(EVENTS.LEAVE_ITEM)}
-              onFocus={() => emit(EVENTS.HOVER_ITEM, { partId: part.id })}
-              onBlur={() => emit(EVENTS.LEAVE_ITEM)}
-            >
-              <div style={styles.header}>
-                <span
-                  aria-hidden="true"
-                  style={{
-                    ...styles.indicator,
-                    background: active ? accent : undefined,
-                    borderColor: active ? accent : '#d1d5db',
-                  }}
-                />
-                <span style={{ ...styles.name, color: active ? accent : undefined }}>
-                  {part.name}
-                </span>
-                <code style={styles.id}>{part.id}</code>
-              </div>
-              {part.description && <p style={styles.description}>{part.description}</p>}
-            </li>
-          );
-        })}
-      </ul>
-    </div>
+    <AnatomyTable
+      parts={parts}
+      activeId={activeId}
+      preset={params.preset}
+      theme={params.theme}
+      onItemEnter={(partId) => emit(EVENTS.HOVER_ITEM, { storyId, partId })}
+      onItemLeave={() => emit(EVENTS.LEAVE_ITEM, { storyId })}
+    />
   );
 };

package/src/blocks.tsx

@@ -0,0 +1,196 @@
+/**
+ * Docs blocks entry — the `<Anatomy>` block for MDX pages.
+ *
+ * Unlike the addon panel, this runs in the **preview iframe**, where
+ * `storybook/manager-api` does not exist. It reaches the story's controller
+ * over the addon channel instead: `Channel.emit` dispatches to local
+ * listeners as well as across transports, so a block and the decorator that
+ * mounted the story talk to each other directly, in-frame, with no extra
+ * plumbing.
+ *
+ * ```mdx
+ * import { Meta, Canvas } from '@storybook/addon-docs/blocks';
+ * import { Anatomy } from '@component-anatomy/storybook/blocks';
+ * import * as ButtonStories from './Button.stories';
+ *
+ * <Meta of={ButtonStories} />
+ *
+ * <Canvas of={ButtonStories.Anatomy} />
+ * <Anatomy of={ButtonStories.Anatomy} />
+ * ```
+ */
+import React, { useEffect, useState } from 'react';
+import { addons } from 'storybook/preview-api';
+import { Unstyled, useOf } from '@storybook/addon-docs/blocks';
+import type { Of } from '@storybook/addon-docs/blocks';
+import type { AnatomyPartDefinition } from '@component-anatomy/core';
+
+import { EVENTS, PARAM_KEY } from './constants.js';
+import { matchesStory } from './channel.js';
+import type { PartEnterEvent, PartsEvent, StoryScopedEvent } from './channel.js';
+import { AnatomyCode, AnatomyMessage, AnatomyTable } from './AnatomyTable.js';
+import type { AnatomyParameters } from './types.js';
+
+export type AnatomyBlockProps = {
+  /**
+   * The CSF export to document — a story export, or the whole module export
+   * of a CSF file to read the meta's parameters.
+   *
+   * Omit it on an attached docs page (one with `<Meta of={...} />`, or an
+   * autodocs page) to fall back to the page's current story, mirroring how
+   * the other docs blocks resolve `of`.
+   */
+  of?: Of;
+  /**
+   * Part list override. Skips both `parameters.anatomy.parts` and
+   * auto-discovery — useful for a hand-curated subset in prose.
+   */
+  parts?: AnatomyPartDefinition[];
+  /**
+   * Two-way hover sync with the rendered story. Default: `true`. Set to
+   * `false` for a purely static table (also skips auto-discovery, since that
+   * arrives over the channel).
+   */
+  sync?: boolean;
+};
+
+/**
+ * `addons.getChannel()` throws when no channel is installed. That should not
+ * happen inside a rendered docs page, but an MDX page is user-authored
+ * content and a throw here would blank the whole page — degrade to a static
+ * table instead.
+ */
+function getChannelSafely() {
+  try {
+    return addons.getChannel();
+  } catch {
+    return null;
+  }
+}
+
+export const Anatomy: React.FC<AnatomyBlockProps> = ({ of, parts: partsProp, sync = true }) => {
+  const resolved = useOf(of ?? 'story', ['story', 'meta']);
+
+  const params = (
+    resolved.type === 'meta'
+      ? resolved.preparedMeta.parameters?.[PARAM_KEY]
+      : resolved.story.parameters?.[PARAM_KEY]
+  ) as AnatomyParameters | undefined;
+
+  // Only a story has a canvas to sync with. `of={SomeStories}` (a meta)
+  // documents the component as a whole and can render static parts only.
+  const storyId = resolved.type === 'story' ? resolved.story.id : undefined;
+
+  const [discovered, setDiscovered] = useState<AnatomyPartDefinition[]>([]);
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  const staticParts = partsProp ?? params?.parts;
+  // Hover sync is wired even when the parts are static — an explicit list
+  // still wants the canvas to light up. Only discovery depends on the channel.
+  const wired = sync && !!storyId;
+
+  useEffect(() => {
+    setDiscovered([]);
+    setActiveId(null);
+    if (!wired) return;
+
+    const channel = getChannelSafely();
+    if (!channel) return;
+
+    const onParts = (event: PartsEvent) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      setDiscovered(event.parts);
+    };
+    const onEnter = (event: PartEnterEvent) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      setActiveId(event.partId);
+    };
+    const onLeave = (event: StoryScopedEvent = {}) => {
+      if (!matchesStory(event?.storyId, storyId)) return;
+      setActiveId(null);
+    };
+
+    channel.on(EVENTS.PARTS, onParts);
+    channel.on(EVENTS.PART_ENTER, onEnter);
+    channel.on(EVENTS.PART_LEAVE, onLeave);
+
+    // The block usually mounts before the story below it finishes rendering;
+    // the request covers the other order.
+    channel.emit(EVENTS.PARTS_REQUEST, { storyId } satisfies StoryScopedEvent);
+
+    return () => {
+      channel.off(EVENTS.PARTS, onParts);
+      channel.off(EVENTS.PART_ENTER, onEnter);
+      channel.off(EVENTS.PART_LEAVE, onLeave);
+    };
+  }, [wired, storyId]);
+
+  const parts = staticParts ?? discovered;
+
+  const emitHover = (partId: string) => {
+    if (!wired) return;
+    getChannelSafely()?.emit(EVENTS.HOVER_ITEM, { storyId, partId });
+  };
+  const emitLeave = () => {
+    if (!wired) return;
+    getChannelSafely()?.emit(EVENTS.LEAVE_ITEM, { storyId } satisfies StoryScopedEvent);
+  };
+
+  // `Unstyled` keeps the docs page's prose CSS (`.sbdocs` restyles ul/li/p/
+  // code) from reaching the table.
+  if (!params && !partsProp) {
+    return (
+      <Unstyled>
+        <AnatomyMessage>
+          No anatomy configured. Add <AnatomyCode>parameters.anatomy</AnatomyCode> to the story you
+          pass to <AnatomyCode>of</AnatomyCode>, or pass a{' '}
+          <AnatomyCode>parts</AnatomyCode> list to this block.
+        </AnatomyMessage>
+      </Unstyled>
+    );
+  }
+
+  if (params?.disable && !partsProp) {
+    return (
+      <Unstyled>
+        <AnatomyMessage>
+          Anatomy is disabled for this story (<AnatomyCode>anatomy.disable</AnatomyCode>).
+        </AnatomyMessage>
+      </Unstyled>
+    );
+  }
+
+  if (parts.length === 0) {
+    return (
+      <Unstyled>
+        <AnatomyMessage>
+          {resolved.type === 'meta' ? (
+            <>
+              No parts found. A meta has no canvas to discover parts from — pass a story to{' '}
+              <AnatomyCode>of</AnatomyCode>, or list <AnatomyCode>parts</AnatomyCode> explicitly.
+            </>
+          ) : (
+            <>
+              No parts found. Auto-discovery reads the rendered story, so make sure it is on this
+              page (e.g. with a <AnatomyCode>{'<Canvas of={…} />'}</AnatomyCode> block above), or
+              list <AnatomyCode>parts</AnatomyCode> explicitly.
+            </>
+          )}
+        </AnatomyMessage>
+      </Unstyled>
+    );
+  }
+
+  return (
+    <Unstyled>
+      <AnatomyTable
+        parts={parts}
+        activeId={activeId}
+        preset={params?.preset}
+        theme={params?.theme}
+        onItemEnter={emitHover}
+        onItemLeave={emitLeave}
+      />
+    </Unstyled>
+  );
+};

package/src/channel.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared channel payload contract between the preview decorator, the manager
+ * panel, and the MDX doc block.
+ *
+ * Every payload carries the `storyId` it refers to. In story view this is
+ * redundant — only one story is mounted — but a docs page mounts *many*
+ * stories at once, each with its own controller, and each `<Anatomy>` block
+ * must talk to exactly one of them. Without addressing, hovering a part in
+ * one block highlights the matching part in every other story on the page.
+ */
+import type { AnatomyPartDefinition } from '@component-anatomy/core';
+
+/** preview → consumers: the resolved part list for one story. */
+export type PartsEvent = { storyId?: string; parts: AnatomyPartDefinition[] };
+
+/** preview → consumers: a part became active in that story's canvas. */
+export type PartEnterEvent = { storyId?: string; partId: string };
+
+/** consumer → preview: highlight this part in that story's canvas. */
+export type HoverItemEvent = { storyId?: string; partId: string };
+
+/** Payload for the events that only need to name a story. */
+export type StoryScopedEvent = { storyId?: string };
+
+/**
+ * Whether an event addressed to `eventStoryId` concerns `storyId`.
+ *
+ * A missing id on *either* side matches everything. That keeps the protocol
+ * backward compatible: a manager panel from a newer build still understands
+ * an older preview bundle that emits unaddressed events, and vice versa.
+ */
+export const matchesStory = (
+  eventStoryId: string | undefined,
+  storyId: string | undefined
+): boolean => !eventStoryId || !storyId || eventStoryId === storyId;