@component-anatomy/storybook 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Déramond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @component-anatomy/storybook
+
+Storybook addon that adds an **Anatomy** panel — an interactive part list synced two-way with the story canvas.
+
+- Hover a part in the panel → the element is highlighted in the canvas
+- Hover a `data-part` element in the canvas → the panel entry activates
+- Works with **Storybook 9 and 10**, any renderer (React, Vue, HTML, Web Components…)
+
+## Install
+
+```bash
+npm install --save-dev @component-anatomy/storybook
+```
+
+```ts
+// .storybook/main.ts
+export default {
+  addons: ['@component-anatomy/storybook'],
+};
+```
+
+## Use
+
+Annotate your story's DOM with `data-part` and add the `anatomy` parameter:
+
+```ts
+import type { AnatomyParameters } from '@component-anatomy/storybook';
+
+export const Anatomy: Story = {
+  parameters: {
+    anatomy: {
+      parts: [
+        { id: 'icon',  name: 'Icon',  description: 'Optional leading glyph.' },
+        { id: 'label', name: 'Label', description: 'The visible action text.' },
+      ],
+      // optional:
+      preset: 'blueprint',            // 'default' | 'minimal' | 'contrast' | 'blueprint'
+      theme: { accent: '#0d9488' },   // theme tokens for the canvas overlays
+      overlayLabel: true,             // floating name chip
+      overlayPadding: 2,              // inflate highlight boxes (px)
+      root: '.my-component',          // narrow the anatomy root (CSS selector)
+      disable: false,                 // turn off for a story
+    } satisfies AnatomyParameters,
+  },
+};
+```
+
+Omit `parts` (pass `{}`) and the panel lists parts auto-discovered from `data-part` attributes, with names derived from the ids.
+
+Parameters follow Storybook's normal inheritance — project-wide defaults in `.storybook/preview.ts`, per-component in `meta.parameters`, per-story overrides in `story.parameters`.
+
+## Example
+
+A complete Storybook 10 setup with Button/Slider/Tabs stories lives in [`examples/storybook`](https://github.com/julien-deramond/component-anatomy/tree/main/examples/storybook), deployed at https://julien-deramond.github.io/component-anatomy/storybook/.
+
+## Docs
+
+Full documentation: https://julien-deramond.github.io/component-anatomy/docs/storybook
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,48 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ADDON_ID: () => ADDON_ID,
+  EVENTS: () => EVENTS,
+  PANEL_ID: () => PANEL_ID,
+  PARAM_KEY: () => PARAM_KEY
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/constants.ts
+var ADDON_ID = "component-anatomy";
+var PANEL_ID = `${ADDON_ID}/panel`;
+var PARAM_KEY = "anatomy";
+var EVENTS = {
+  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  PART_ENTER: `${ADDON_ID}/part-enter`,
+  /** preview → manager: no part is active anymore. */
+  PART_LEAVE: `${ADDON_ID}/part-leave`,
+  /** preview → manager: resolved part list for the current story. */
+  PARTS: `${ADDON_ID}/parts`,
+  /** manager → preview: the user hovers/focuses a panel entry. */
+  HOVER_ITEM: `${ADDON_ID}/hover-item`,
+  /** manager → preview: the user left a panel entry. */
+  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
+  /** manager → preview: the panel mounted and wants the current part list. */
+  PARTS_REQUEST: `${ADDON_ID}/parts-request`
+};
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts", "../src/constants.ts"],
+  "sourcesContent": ["export { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';\nexport type { AnatomyParameters } from './types.js';\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/** Channel events used to sync the manager panel with the preview iframe. */\nexport const EVENTS = {\n  /** preview \u2192 manager: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 manager: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 manager: resolved part list for the current story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** manager \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** manager \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** manager \u2192 preview: the panel mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAO,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AAGlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,25 @@
+// src/constants.ts
+var ADDON_ID = "component-anatomy";
+var PANEL_ID = `${ADDON_ID}/panel`;
+var PARAM_KEY = "anatomy";
+var EVENTS = {
+  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  PART_ENTER: `${ADDON_ID}/part-enter`,
+  /** preview → manager: no part is active anymore. */
+  PART_LEAVE: `${ADDON_ID}/part-leave`,
+  /** preview → manager: resolved part list for the current story. */
+  PARTS: `${ADDON_ID}/parts`,
+  /** manager → preview: the user hovers/focuses a panel entry. */
+  HOVER_ITEM: `${ADDON_ID}/hover-item`,
+  /** manager → preview: the user left a panel entry. */
+  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
+  /** manager → preview: the panel mounted and wants the current part list. */
+  PARTS_REQUEST: `${ADDON_ID}/parts-request`
+};
+export {
+  ADDON_ID,
+  EVENTS,
+  PANEL_ID,
+  PARAM_KEY
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/constants.ts"],
+  "sourcesContent": ["export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/** Channel events used to sync the manager panel with the preview iframe. */\nexport const EVENTS = {\n  /** preview \u2192 manager: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 manager: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 manager: resolved part list for the current story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** manager \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** manager \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** manager \u2192 preview: the panel mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n"],
+  "mappings": ";AAAO,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AAGlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;",
+  "names": []
+}

package/dist/manager.js

@@ -0,0 +1,164 @@
+// src/manager.tsx
+import React2 from "react";
+import { addons, types } from "storybook/manager-api";
+import { AddonPanel } from "storybook/internal/components";
+
+// src/constants.ts
+var ADDON_ID = "component-anatomy";
+var PANEL_ID = `${ADDON_ID}/panel`;
+var PARAM_KEY = "anatomy";
+var EVENTS = {
+  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  PART_ENTER: `${ADDON_ID}/part-enter`,
+  /** preview → manager: no part is active anymore. */
+  PART_LEAVE: `${ADDON_ID}/part-leave`,
+  /** preview → manager: resolved part list for the current story. */
+  PARTS: `${ADDON_ID}/parts`,
+  /** manager → preview: the user hovers/focuses a panel entry. */
+  HOVER_ITEM: `${ADDON_ID}/hover-item`,
+  /** manager → preview: the user left a panel entry. */
+  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
+  /** manager → preview: the panel mounted and wants the current part list. */
+  PARTS_REQUEST: `${ADDON_ID}/parts-request`
+};
+
+// src/Panel.tsx
+import React, { useEffect, useState } from "react";
+import { useChannel, useParameter, useStorybookApi } from "storybook/manager-api";
+var ACCENT_FALLBACK = "#4f46e5";
+var styles = {
+  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"
+  }
+};
+var Panel = () => {
+  const params = useParameter(PARAM_KEY, void 0);
+  const api = useStorybookApi();
+  const storyId = api.getUrlState().storyId;
+  const [discovered, setDiscovered] = useState([]);
+  const [activeId, setActiveId] = useState(null);
+  const emit = useChannel({
+    [EVENTS.PARTS]: ({ parts: parts2 }) => setDiscovered(parts2),
+    [EVENTS.PART_ENTER]: ({ partId }) => setActiveId(partId),
+    [EVENTS.PART_LEAVE]: () => setActiveId(null)
+  });
+  useEffect(() => {
+    setDiscovered([]);
+    setActiveId(null);
+    emit(EVENTS.PARTS_REQUEST);
+  }, [storyId]);
+  const parts = params?.parts ?? discovered;
+  const accent = params?.theme?.accent ?? ACCENT_FALLBACK;
+  if (!params || params.disable) {
+    return /* @__PURE__ */ React.createElement("div", { style: styles.container }, /* @__PURE__ */ React.createElement("p", { style: styles.empty }, "No anatomy configured for this story. Add", " ", /* @__PURE__ */ React.createElement("code", { style: styles.code }, "parameters.anatomy"), " and annotate elements with", " ", /* @__PURE__ */ React.createElement("code", { style: styles.code }, 'data-part="name"'), "."));
+  }
+  if (parts.length === 0) {
+    return /* @__PURE__ */ React.createElement("div", { style: styles.container }, /* @__PURE__ */ React.createElement("p", { style: styles.empty }, "No parts found. Annotate elements in your story with", " ", /* @__PURE__ */ React.createElement("code", { style: styles.code }, 'data-part="name"'), " or pass", " ", /* @__PURE__ */ React.createElement("code", { style: styles.code }, "parameters.anatomy.parts"), "."));
+  }
+  return /* @__PURE__ */ React.createElement("div", { style: styles.container }, /* @__PURE__ */ React.createElement("ul", { style: styles.list, role: "list", "aria-label": "Anatomy parts" }, parts.map((part) => {
+    const active = activeId === part.id;
+    return /* @__PURE__ */ React.createElement(
+      "li",
+      {
+        key: part.id,
+        role: "listitem",
+        tabIndex: 0,
+        "aria-label": part.name,
+        style: {
+          ...styles.entry,
+          background: active ? `color-mix(in srgb, ${accent} 7%, transparent)` : void 0,
+          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)
+      },
+      /* @__PURE__ */ React.createElement("div", { style: styles.header }, /* @__PURE__ */ React.createElement(
+        "span",
+        {
+          "aria-hidden": "true",
+          style: {
+            ...styles.indicator,
+            background: active ? accent : void 0,
+            borderColor: active ? accent : "#d1d5db"
+          }
+        }
+      ), /* @__PURE__ */ React.createElement("span", { style: { ...styles.name, color: active ? accent : void 0 } }, part.name), /* @__PURE__ */ React.createElement("code", { style: styles.id }, part.id)),
+      part.description && /* @__PURE__ */ React.createElement("p", { style: styles.description }, part.description)
+    );
+  })));
+};
+
+// src/manager.tsx
+addons.register(ADDON_ID, () => {
+  addons.add(PANEL_ID, {
+    type: types.PANEL,
+    title: "Anatomy",
+    paramKey: PARAM_KEY,
+    match: ({ viewMode }) => viewMode === "story",
+    render: ({ active }) => /* @__PURE__ */ React2.createElement(AddonPanel, { active: !!active }, /* @__PURE__ */ React2.createElement(Panel, null))
+  });
+});
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/manager.tsx", "../src/constants.ts", "../src/Panel.tsx"],
+  "sourcesContent": ["import React from 'react';\nimport { addons, types } from 'storybook/manager-api';\nimport { AddonPanel } from 'storybook/internal/components';\n\nimport { ADDON_ID, PANEL_ID, PARAM_KEY } from './constants.js';\nimport { Panel } from './Panel.js';\n\naddons.register(ADDON_ID, () => {\n  addons.add(PANEL_ID, {\n    type: types.PANEL,\n    title: 'Anatomy',\n    paramKey: PARAM_KEY,\n    match: ({ viewMode }) => viewMode === 'story',\n    render: ({ active }) => (\n      <AddonPanel active={!!active}>\n        <Panel />\n      </AddonPanel>\n    ),\n  });\n});\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/** Channel events used to sync the manager panel with the preview iframe. */\nexport const EVENTS = {\n  /** preview \u2192 manager: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 manager: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 manager: resolved part list for the current story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** manager \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** manager \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** manager \u2192 preview: the panel mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n", "import React, { useEffect, useState } from 'react';\nimport { useChannel, useParameter, useStorybookApi } from 'storybook/manager-api';\nimport type { AnatomyPartDefinition } from '@component-anatomy/core';\n\nimport { EVENTS, PARAM_KEY } from './constants.js';\nimport type { AnatomyParameters } from './types.js';\n\nconst ACCENT_FALLBACK = '#4f46e5';\n\nconst styles: Record<string, React.CSSProperties> = {\n  container: {\n    padding: '12px 16px',\n    fontFamily:\n      '\"Nunito Sans\", -apple-system, \".SFNSText-Regular\", \"San Francisco\", BlinkMacSystemFont, \"Segoe UI\", \"Helvetica Neue\", Helvetica, Arial, sans-serif',\n    fontSize: 13,\n    lineHeight: 1.5,\n  },\n  empty: {\n    color: '#6b7280',\n  },\n  code: {\n    fontFamily: 'ui-monospace, \"Cascadia Code\", \"Fira Mono\", monospace',\n    fontSize: '0.85em',\n    background: 'rgba(0,0,0,0.06)',\n    borderRadius: 3,\n    padding: '1px 5px',\n  },\n  list: {\n    display: 'flex',\n    flexDirection: 'column',\n    gap: 2,\n    margin: 0,\n    padding: 0,\n    listStyle: 'none',\n  },\n  entry: {\n    padding: '8px 10px',\n    borderRadius: 6,\n    border: '1px solid transparent',\n    cursor: 'default',\n    outline: 'none',\n    transition: 'background 120ms ease, border-color 120ms ease',\n  },\n  header: {\n    display: 'flex',\n    alignItems: 'center',\n    gap: 8,\n  },\n  indicator: {\n    width: 8,\n    height: 8,\n    borderRadius: '50%',\n    border: '2px solid #d1d5db',\n    flexShrink: 0,\n    transition: 'background 120ms ease, border-color 120ms ease',\n  },\n  name: {\n    fontWeight: 700,\n    flex: 1,\n  },\n  id: {\n    fontFamily: 'ui-monospace, \"Cascadia Code\", \"Fira Mono\", monospace',\n    fontSize: 10,\n    padding: '1px 6px',\n    borderRadius: 4,\n    background: 'rgba(0,0,0,0.05)',\n    border: '1px solid rgba(0,0,0,0.08)',\n    color: '#6b7280',\n    flexShrink: 0,\n  },\n  description: {\n    margin: '4px 0 0',\n    paddingLeft: 16,\n    color: '#6b7280',\n  },\n};\n\nexport const Panel: React.FC = () => {\n  const params = useParameter<AnatomyParameters | undefined>(PARAM_KEY, undefined);\n  const api = useStorybookApi();\n  const storyId = api.getUrlState().storyId;\n\n  const [discovered, setDiscovered] = useState<AnatomyPartDefinition[]>([]);\n  const [activeId, setActiveId] = useState<string | null>(null);\n\n  const emit = useChannel({\n    [EVENTS.PARTS]: ({ parts }: { parts: AnatomyPartDefinition[] }) => setDiscovered(parts),\n    [EVENTS.PART_ENTER]: ({ partId }: { partId: string }) => setActiveId(partId),\n    [EVENTS.PART_LEAVE]: () => setActiveId(null),\n  });\n\n  // Ask the preview for the current part list on mount / story change.\n  useEffect(() => {\n    setDiscovered([]);\n    setActiveId(null);\n    emit(EVENTS.PARTS_REQUEST);\n  }, [storyId]);\n\n  const parts = params?.parts ?? discovered;\n  const accent = params?.theme?.accent ?? ACCENT_FALLBACK;\n\n  if (!params || params.disable) {\n    return (\n      <div style={styles.container}>\n        <p style={styles.empty}>\n          No anatomy configured for this story. Add{' '}\n          <code style={styles.code}>parameters.anatomy</code> and annotate elements with{' '}\n          <code style={styles.code}>data-part=\"name\"</code>.\n        </p>\n      </div>\n    );\n  }\n\n  if (parts.length === 0) {\n    return (\n      <div style={styles.container}>\n        <p style={styles.empty}>\n          No parts found. Annotate elements in your story with{' '}\n          <code style={styles.code}>data-part=\"name\"</code> or pass{' '}\n          <code style={styles.code}>parameters.anatomy.parts</code>.\n        </p>\n      </div>\n    );\n  }\n\n  return (\n    <div style={styles.container}>\n      <ul style={styles.list} role=\"list\" aria-label=\"Anatomy parts\">\n        {parts.map((part) => {\n          const active = activeId === part.id;\n          return (\n            <li\n              key={part.id}\n              role=\"listitem\"\n              tabIndex={0}\n              aria-label={part.name}\n              style={{\n                ...styles.entry,\n                background: active ? `color-mix(in srgb, ${accent} 7%, transparent)` : undefined,\n                borderColor: active ? `color-mix(in srgb, ${accent} 20%, transparent)` : 'transparent',\n              }}\n              onMouseEnter={() => emit(EVENTS.HOVER_ITEM, { partId: part.id })}\n              onMouseLeave={() => emit(EVENTS.LEAVE_ITEM)}\n              onFocus={() => emit(EVENTS.HOVER_ITEM, { partId: part.id })}\n              onBlur={() => emit(EVENTS.LEAVE_ITEM)}\n            >\n              <div style={styles.header}>\n                <span\n                  aria-hidden=\"true\"\n                  style={{\n                    ...styles.indicator,\n                    background: active ? accent : undefined,\n                    borderColor: active ? accent : '#d1d5db',\n                  }}\n                />\n                <span style={{ ...styles.name, color: active ? accent : undefined }}>\n                  {part.name}\n                </span>\n                <code style={styles.id}>{part.id}</code>\n              </div>\n              {part.description && <p style={styles.description}>{part.description}</p>}\n            </li>\n          );\n        })}\n      </ul>\n    </div>\n  );\n};\n"],
+  "mappings": "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",
+  "names": ["React", "parts", "React"]
+}

package/dist/preview.js

@@ -0,0 +1,74 @@
+// src/preview.ts
+import { addons, useEffect } from "storybook/preview-api";
+import { createAnatomy } from "@component-anatomy/core";
+
+// src/constants.ts
+var ADDON_ID = "component-anatomy";
+var PANEL_ID = `${ADDON_ID}/panel`;
+var PARAM_KEY = "anatomy";
+var EVENTS = {
+  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  PART_ENTER: `${ADDON_ID}/part-enter`,
+  /** preview → manager: no part is active anymore. */
+  PART_LEAVE: `${ADDON_ID}/part-leave`,
+  /** preview → manager: resolved part list for the current story. */
+  PARTS: `${ADDON_ID}/parts`,
+  /** manager → preview: the user hovers/focuses a panel entry. */
+  HOVER_ITEM: `${ADDON_ID}/hover-item`,
+  /** manager → preview: the user left a panel entry. */
+  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
+  /** manager → preview: the panel mounted and wants the current part list. */
+  PARTS_REQUEST: `${ADDON_ID}/parts-request`
+};
+
+// src/preview.ts
+var withComponentAnatomy = (storyFn, context) => {
+  const params = context.parameters?.[PARAM_KEY];
+  useEffect(() => {
+    if (!params || params.disable) return;
+    const channel = addons.getChannel();
+    const canvas = context.canvasElement;
+    if (!canvas) return;
+    const root = params.root ? canvas.querySelector(params.root) ?? canvas : canvas;
+    const controller = createAnatomy({
+      root,
+      parts: params.parts,
+      preset: params.preset,
+      theme: params.theme,
+      overlay: {
+        label: params.overlayLabel !== false,
+        padding: params.overlayPadding
+      }
+    });
+    const announceParts = () => channel.emit(EVENTS.PARTS, { storyId: context.id, parts: controller.getParts() });
+    announceParts();
+    const offEnter = controller.on(
+      "part:enter",
+      (partId) => channel.emit(EVENTS.PART_ENTER, { partId })
+    );
+    const offLeave = controller.on(
+      "part:leave",
+      () => channel.emit(EVENTS.PART_LEAVE, {})
+    );
+    const onHoverItem = ({ partId }) => controller.highlight(partId);
+    const onLeaveItem = () => controller.unhighlight();
+    channel.on(EVENTS.HOVER_ITEM, onHoverItem);
+    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);
+    channel.on(EVENTS.PARTS_REQUEST, announceParts);
+    return () => {
+      channel.off(EVENTS.HOVER_ITEM, onHoverItem);
+      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
+      channel.off(EVENTS.PARTS_REQUEST, announceParts);
+      offEnter();
+      offLeave();
+      controller.destroy();
+    };
+  }, [context.id]);
+  return storyFn();
+};
+var decorators = [withComponentAnatomy];
+export {
+  decorators,
+  withComponentAnatomy
+};
+//# sourceMappingURL=preview.js.map

package/dist/preview.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/preview.ts", "../src/constants.ts"],
+  "sourcesContent": ["/**\n * Preview-side (iframe) entry. Registers a global decorator that mounts a\n * component-anatomy controller over the story canvas and syncs hover state\n * with the manager panel over the addon channel.\n */\nimport { addons, useEffect } from 'storybook/preview-api';\nimport type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';\nimport { createAnatomy } from '@component-anatomy/core';\n\nimport { EVENTS, PARAM_KEY } from './constants.js';\nimport type { AnatomyParameters } from './types.js';\n\nexport const withComponentAnatomy = (\n  storyFn: PartialStoryFn<Renderer>,\n  context: StoryContext<Renderer>\n) => {\n  const params = context.parameters?.[PARAM_KEY] as AnatomyParameters | undefined;\n\n  useEffect(() => {\n    if (!params || params.disable) return;\n\n    const channel = addons.getChannel();\n    const canvas = context.canvasElement as unknown as HTMLElement;\n    if (!canvas) return;\n\n    const root = params.root\n      ? canvas.querySelector<HTMLElement>(params.root) ?? canvas\n      : canvas;\n\n    const controller = createAnatomy({\n      root,\n      parts: params.parts,\n      preset: params.preset,\n      theme: params.theme,\n      overlay: {\n        label: params.overlayLabel !== false,\n        padding: params.overlayPadding,\n      },\n    });\n\n    const announceParts = () =>\n      channel.emit(EVENTS.PARTS, { storyId: context.id, parts: controller.getParts() });\n\n    announceParts();\n\n    const offEnter = controller.on('part:enter', (partId) =>\n      channel.emit(EVENTS.PART_ENTER, { partId })\n    );\n    const offLeave = controller.on('part:leave', () =>\n      channel.emit(EVENTS.PART_LEAVE, {})\n    );\n\n    const onHoverItem = ({ partId }: { partId: string }) => controller.highlight(partId);\n    const onLeaveItem = () => controller.unhighlight();\n\n    channel.on(EVENTS.HOVER_ITEM, onHoverItem);\n    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);\n    // The panel may mount after the story rendered \u2014 let it ask for the list.\n    channel.on(EVENTS.PARTS_REQUEST, announceParts);\n\n    return () => {\n      channel.off(EVENTS.HOVER_ITEM, onHoverItem);\n      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);\n      channel.off(EVENTS.PARTS_REQUEST, announceParts);\n      offEnter();\n      offLeave();\n      controller.destroy();\n    };\n  }, [context.id]);\n\n  return storyFn();\n};\n\nexport const decorators = [withComponentAnatomy];\n", "export const ADDON_ID = 'component-anatomy';\nexport const PANEL_ID = `${ADDON_ID}/panel`;\n\n/** Story parameter key: `parameters.anatomy = { ... }` */\nexport const PARAM_KEY = 'anatomy';\n\n/** Channel events used to sync the manager panel with the preview iframe. */\nexport const EVENTS = {\n  /** preview \u2192 manager: a part became active in the canvas (hover/programmatic). */\n  PART_ENTER: `${ADDON_ID}/part-enter`,\n  /** preview \u2192 manager: no part is active anymore. */\n  PART_LEAVE: `${ADDON_ID}/part-leave`,\n  /** preview \u2192 manager: resolved part list for the current story. */\n  PARTS: `${ADDON_ID}/parts`,\n  /** manager \u2192 preview: the user hovers/focuses a panel entry. */\n  HOVER_ITEM: `${ADDON_ID}/hover-item`,\n  /** manager \u2192 preview: the user left a panel entry. */\n  LEAVE_ITEM: `${ADDON_ID}/leave-item`,\n  /** manager \u2192 preview: the panel mounted and wants the current part list. */\n  PARTS_REQUEST: `${ADDON_ID}/parts-request`,\n} as const;\n"],
+  "mappings": ";AAKA,SAAS,QAAQ,iBAAiB;AAElC,SAAS,qBAAqB;;;ACPvB,IAAM,WAAW;AACjB,IAAM,WAAW,GAAG,QAAQ;AAG5B,IAAM,YAAY;AAGlB,IAAM,SAAS;AAAA;AAAA,EAEpB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,OAAO,GAAG,QAAQ;AAAA;AAAA,EAElB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,YAAY,GAAG,QAAQ;AAAA;AAAA,EAEvB,eAAe,GAAG,QAAQ;AAC5B;;;ADRO,IAAM,uBAAuB,CAClC,SACA,YACG;AACH,QAAM,SAAS,QAAQ,aAAa,SAAS;AAE7C,YAAU,MAAM;AACd,QAAI,CAAC,UAAU,OAAO,QAAS;AAE/B,UAAM,UAAU,OAAO,WAAW;AAClC,UAAM,SAAS,QAAQ;AACvB,QAAI,CAAC,OAAQ;AAEb,UAAM,OAAO,OAAO,OAChB,OAAO,cAA2B,OAAO,IAAI,KAAK,SAClD;AAEJ,UAAM,aAAa,cAAc;AAAA,MAC/B;AAAA,MACA,OAAO,OAAO;AAAA,MACd,QAAQ,OAAO;AAAA,MACf,OAAO,OAAO;AAAA,MACd,SAAS;AAAA,QACP,OAAO,OAAO,iBAAiB;AAAA,QAC/B,SAAS,OAAO;AAAA,MAClB;AAAA,IACF,CAAC;AAED,UAAM,gBAAgB,MACpB,QAAQ,KAAK,OAAO,OAAO,EAAE,SAAS,QAAQ,IAAI,OAAO,WAAW,SAAS,EAAE,CAAC;AAElF,kBAAc;AAEd,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,CAAC,WAC5C,QAAQ,KAAK,OAAO,YAAY,EAAE,OAAO,CAAC;AAAA,IAC5C;AACA,UAAM,WAAW,WAAW;AAAA,MAAG;AAAA,MAAc,MAC3C,QAAQ,KAAK,OAAO,YAAY,CAAC,CAAC;AAAA,IACpC;AAEA,UAAM,cAAc,CAAC,EAAE,OAAO,MAA0B,WAAW,UAAU,MAAM;AACnF,UAAM,cAAc,MAAM,WAAW,YAAY;AAEjD,YAAQ,GAAG,OAAO,YAAY,WAAW;AACzC,YAAQ,GAAG,OAAO,YAAY,WAAW;AAEzC,YAAQ,GAAG,OAAO,eAAe,aAAa;AAE9C,WAAO,MAAM;AACX,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,YAAY,WAAW;AAC1C,cAAQ,IAAI,OAAO,eAAe,aAAa;AAC/C,eAAS;AACT,eAAS;AACT,iBAAW,QAAQ;AAAA,IACrB;AAAA,EACF,GAAG,CAAC,QAAQ,EAAE,CAAC;AAEf,SAAO,QAAQ;AACjB;AAEO,IAAM,aAAa,CAAC,oBAAoB;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@component-anatomy/storybook",
+  "version": "0.0.1",
+  "description": "Storybook addon — interactive component anatomy panel synced with the story canvas",
+  "license": "MIT",
+  "author": "Julien Déramond",
+  "homepage": "https://github.com/julien-deramond/component-anatomy#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/julien-deramond/component-anatomy",
+    "directory": "packages/storybook"
+  },
+  "bugs": {
+    "url": "https://github.com/julien-deramond/component-anatomy/issues"
+  },
+  "keywords": [
+    "storybook-addon",
+    "component-anatomy",
+    "design-system",
+    "documentation",
+    "anatomy",
+    "appearance"
+  ],
+  "storybook": {
+    "displayName": "Component Anatomy",
+    "supportedFrameworks": [
+      "react",
+      "vue",
+      "angular",
+      "web-components",
+      "html"
+    ]
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./manager": "./dist/manager.js",
+    "./preview": "./dist/preview.js",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@component-anatomy/core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "esbuild": "^0.21.0",
+    "react": "^18.3.1",
+    "storybook": "^10.0.0",
+    "typescript": "^5.4.5"
+  },
+  "peerDependencies": {
+    "storybook": ">=9.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/Panel.tsx

@@ -0,0 +1,168 @@
+import React, { useEffect, useState } from 'react';
+import { useChannel, useParameter, useStorybookApi } from 'storybook/manager-api';
+import type { AnatomyPartDefinition } from '@component-anatomy/core';
+
+import { EVENTS, PARAM_KEY } from './constants.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();
+  const storyId = api.getUrlState().storyId;
+
+  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),
+  });
+
+  // Ask the preview for the current part list on mount / story change.
+  useEffect(() => {
+    setDiscovered([]);
+    setActiveId(null);
+    emit(EVENTS.PARTS_REQUEST);
+  }, [storyId]);
+
+  const parts = params?.parts ?? discovered;
+  const accent = params?.theme?.accent ?? ACCENT_FALLBACK;
+
+  if (!params || 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>
+    );
+  }
+
+  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>
+    );
+  }
+
+  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>
+  );
+};

package/src/constants.ts

@@ -0,0 +1,21 @@
+export const ADDON_ID = 'component-anatomy';
+export const PANEL_ID = `${ADDON_ID}/panel`;
+
+/** Story parameter key: `parameters.anatomy = { ... }` */
+export const PARAM_KEY = 'anatomy';
+
+/** Channel events used to sync the manager panel with the preview iframe. */
+export const EVENTS = {
+  /** preview → manager: a part became active in the canvas (hover/programmatic). */
+  PART_ENTER: `${ADDON_ID}/part-enter`,
+  /** preview → manager: no part is active anymore. */
+  PART_LEAVE: `${ADDON_ID}/part-leave`,
+  /** preview → manager: resolved part list for the current story. */
+  PARTS: `${ADDON_ID}/parts`,
+  /** manager → preview: the user hovers/focuses a panel entry. */
+  HOVER_ITEM: `${ADDON_ID}/hover-item`,
+  /** manager → preview: the user left a panel entry. */
+  LEAVE_ITEM: `${ADDON_ID}/leave-item`,
+  /** manager → preview: the panel mounted and wants the current part list. */
+  PARTS_REQUEST: `${ADDON_ID}/parts-request`,
+} as const;

package/src/index.ts

@@ -0,0 +1,2 @@
+export { ADDON_ID, PANEL_ID, PARAM_KEY, EVENTS } from './constants.js';
+export type { AnatomyParameters } from './types.js';

package/src/manager.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import { addons, types } from 'storybook/manager-api';
+import { AddonPanel } from 'storybook/internal/components';
+
+import { ADDON_ID, PANEL_ID, PARAM_KEY } from './constants.js';
+import { Panel } from './Panel.js';
+
+addons.register(ADDON_ID, () => {
+  addons.add(PANEL_ID, {
+    type: types.PANEL,
+    title: 'Anatomy',
+    paramKey: PARAM_KEY,
+    match: ({ viewMode }) => viewMode === 'story',
+    render: ({ active }) => (
+      <AddonPanel active={!!active}>
+        <Panel />
+      </AddonPanel>
+    ),
+  });
+});

package/src/preview.ts

@@ -0,0 +1,74 @@
+/**
+ * Preview-side (iframe) entry. Registers a global decorator that mounts a
+ * component-anatomy controller over the story canvas and syncs hover state
+ * with the manager panel over the addon channel.
+ */
+import { addons, useEffect } from 'storybook/preview-api';
+import type { Renderer, PartialStoryFn, StoryContext } from 'storybook/internal/types';
+import { createAnatomy } from '@component-anatomy/core';
+
+import { EVENTS, PARAM_KEY } from './constants.js';
+import type { AnatomyParameters } from './types.js';
+
+export const withComponentAnatomy = (
+  storyFn: PartialStoryFn<Renderer>,
+  context: StoryContext<Renderer>
+) => {
+  const params = context.parameters?.[PARAM_KEY] as AnatomyParameters | undefined;
+
+  useEffect(() => {
+    if (!params || params.disable) return;
+
+    const channel = addons.getChannel();
+    const canvas = context.canvasElement as unknown as HTMLElement;
+    if (!canvas) return;
+
+    const root = params.root
+      ? canvas.querySelector<HTMLElement>(params.root) ?? canvas
+      : canvas;
+
+    const controller = createAnatomy({
+      root,
+      parts: params.parts,
+      preset: params.preset,
+      theme: params.theme,
+      overlay: {
+        label: params.overlayLabel !== false,
+        padding: params.overlayPadding,
+      },
+    });
+
+    const announceParts = () =>
+      channel.emit(EVENTS.PARTS, { storyId: context.id, parts: controller.getParts() });
+
+    announceParts();
+
+    const offEnter = controller.on('part:enter', (partId) =>
+      channel.emit(EVENTS.PART_ENTER, { partId })
+    );
+    const offLeave = controller.on('part:leave', () =>
+      channel.emit(EVENTS.PART_LEAVE, {})
+    );
+
+    const onHoverItem = ({ partId }: { partId: string }) => controller.highlight(partId);
+    const onLeaveItem = () => controller.unhighlight();
+
+    channel.on(EVENTS.HOVER_ITEM, onHoverItem);
+    channel.on(EVENTS.LEAVE_ITEM, onLeaveItem);
+    // The panel may mount after the story rendered — let it ask for the list.
+    channel.on(EVENTS.PARTS_REQUEST, announceParts);
+
+    return () => {
+      channel.off(EVENTS.HOVER_ITEM, onHoverItem);
+      channel.off(EVENTS.LEAVE_ITEM, onLeaveItem);
+      channel.off(EVENTS.PARTS_REQUEST, announceParts);
+      offEnter();
+      offLeave();
+      controller.destroy();
+    };
+  }, [context.id]);
+
+  return storyFn();
+};
+
+export const decorators = [withComponentAnatomy];

package/src/types.ts

@@ -0,0 +1,43 @@
+import type {
+  AnatomyPartDefinition,
+  AnatomyPresetName,
+  AnatomyTheme,
+} from '@component-anatomy/core';
+
+/**
+ * Configuration for the anatomy addon, set through story parameters:
+ *
+ * ```ts
+ * export const Primary: Story = {
+ *   parameters: {
+ *     anatomy: {
+ *       parts: [
+ *         { id: 'label', name: 'Label', description: 'The visible text.' },
+ *       ],
+ *     },
+ *   },
+ * };
+ * ```
+ */
+export type AnatomyParameters = {
+  /**
+   * Part definitions. If omitted, parts are auto-discovered from
+   * `data-part` attributes in the rendered story.
+   */
+  parts?: AnatomyPartDefinition[];
+  /** Named visual preset for the canvas overlays. Default: 'default'. */
+  preset?: AnatomyPresetName;
+  /** Theme token overrides (applied on top of the preset). */
+  theme?: AnatomyTheme;
+  /** Show the floating name label chip in the canvas. Default: true. */
+  overlayLabel?: boolean;
+  /** Inflate highlight boxes by N pixels. Default: 0. */
+  overlayPadding?: number;
+  /**
+   * CSS selector to narrow the anatomy root inside the story canvas.
+   * Defaults to the whole canvas element.
+   */
+  root?: string;
+  /** Disable the addon for this story. */
+  disable?: boolean;
+};