@sxl-studio/storybook-addon 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+- **Embed debug:** `parameters.sxl.debugFigmaEmbed` now works in runtime. The panel logs resolved embed diagnostics and iframe load/error events when enabled.
+- **Token status compatibility:** `sxl.tokenStatus` now maps to `tokensBool` in runtime (deprecated but supported), so documented override behavior is consistent.
+- **CSP merge hardening:** `mergeSxlFigmaFrameSrcHeader` now merges into an existing `frame-src` directive instead of appending raw strings.
+- **Quality gates:** added ESLint pipeline and unit tests for entry resolution, composition loading fallback chain, and Storybook preset behavior.
+
+## 1.1.1
+
+- **Registry matching:** removed the behavior where a **single** registry entry was applied to **every** story. Matching now always uses the same story-context heuristic (or explicit `sxl.component` / `sxl.figmaNodeId`). Unrelated stories show the “no Figma integration” state.
+
 ## 1.1.0
 
 - **Preset (zero-config):** merges Content-Security-Policy so the Figma embed iframe can load (`frame-src` includes `https://www.figma.com`).

package/README.md

@@ -4,7 +4,7 @@ Storybook addon for [SXL Studio](https://sxl-studio.com) — displays Figma Embe
 
 ## Changelog
 
-See [CHANGELOG.md](./CHANGELOG.md) (e.g. **1.1.0**: preset CSP, `/sxl-tokens` for local composition, optional legacy registry filename alias, quieter logs).
+See [CHANGELOG.md](./CHANGELOG.md) (e.g. **1.1.1** registry matching fix; **1.1.0** preset CSP, `/sxl-tokens`, legacy filename alias, quieter logs).
 
 ## Features
 
@@ -21,9 +21,11 @@ npm install @sxl-studio/storybook-addon --save-dev
 
 ## Setup
 
-### 1. Register the addon
+### 1. Register the addon (`main`)
 
-`.storybook/main.ts`:
+List **`@sxl-studio/storybook-addon`** in **`addons`**. The preset ships with the package and is applied when Storybook loads the addon (no separate preset import in `main` unless your setup requires the explicit `@sxl-studio/storybook-addon/preset` entry — see troubleshooting in docs).
+
+**Minimal `main.ts`:**
 
 ```ts
 export default {
@@ -34,21 +36,35 @@ export default {
 };
 ```
 
-### 2. Import the registry
+**With a shared Storybook config** (internal design-system package, monorepo): **append** to the shared addons array — do not drop existing entries.
+
+```ts
+import sharedMain from '@your-org/storybook-vue/main';
+
+const config = {
+  ...sharedMain,
+  addons: [...(sharedMain.addons ?? []), '@sxl-studio/storybook-addon'],
+};
+
+export default config;
+```
+
+### 2. Import the registry (`preview`)
 
-The SXL Studio Figma plugin generates a `sxl-codeconnect.json` (or `diff-code-connect.<fileKey>.json`) file that maps Figma components to your codebase. Import it in your Storybook preview config.
+The SXL Studio Figma plugin generates **`diff-code-connect.<figmaFileKey>.json`** (or an exported `sxl-codeconnect.json`). Put it in **`parameters.sxl.registry`**. The **relative import path is up to your repo** (e.g. `../../tokens/tokens/diff-code-connect.xxx.json`).
 
-**Preset (automatic):** when the addon preset is loaded (default if the package is listed under `addons`), it:
+- **`fromDiffCodeConnect(raw)`** — explicit normalization; use if you prefer one code path.
+- **Raw `import registry from '...json'`** — often enough for current plugin output.
 
-- Serves the sibling folder `tokens/tokens` (if present next to the Storybook app or two levels above `.storybook`) at **`/sxl-tokens/…`**, so composition JSON paths from the registry resolve in dev and via `staticDirs` in `storybook build`.
-- If `diff-code-connect.SXL-Components.json` is **missing** but another `diff-code-connect.*.json` exists in that folder, Vite gets a **`resolve.alias`** from the legacy path to the first matching file (sorted by name). You can keep a stable import path in preview while the plugin emits `diff-code-connect.<figmaFileKey>.json`.
+**Preset (automatic):** when the addon preset runs, it:
 
-**Option A** — using `sxl-codeconnect.json` (exported from plugin):
+- Serves a nearby **`tokens/tokens`** folder at **`/sxl-tokens/…`** (dev + `storybook build` via `staticDirs`) so `compositionFilePath` in the registry resolves without extra Vite config.
+- Can **`resolve.alias`** a stable filename like `diff-code-connect.SXL-Components.json` to the real `diff-code-connect.*.json` when only one candidate exists in that folder (see CHANGELOG).
 
-`.storybook/preview.ts`:
+**Minimal `preview.ts`:**
 
 ```ts
-import registry from '../sxl-codeconnect.json';
+import registry from '../path/to/diff-code-connect.<fileKey>.json';
 
 export default {
   parameters: {
@@ -57,10 +73,25 @@ export default {
 };
 ```
 
-**Option B** — using the existing `diff-code-connect` file:
+**With a shared `preview`** — merge **`parameters`** so shared decorators/globals stay intact:
 
 ```ts
-import raw from '../diff-code-connect.abc123.json';
+import sharedPreview from '@your-org/storybook-vue/preview';
+import registry from '../../tokens/tokens/diff-code-connect.<fileKey>.json';
+
+export default {
+  ...sharedPreview,
+  parameters: {
+    ...sharedPreview.parameters,
+    sxl: { registry },
+  },
+};
+```
+
+**Alternative — converter:**
+
+```ts
+import raw from '../diff-code-connect.<fileKey>.json';
 import { fromDiffCodeConnect } from '@sxl-studio/storybook-addon';
 
 export default {
@@ -72,6 +103,8 @@ export default {
 
 ### 3. Match stories to Figma components
 
+Stories are matched to registry entries by explicit `sxl.component` / `sxl.figmaNodeId`, or by a **heuristic** on story title and file path. **A registry with a single component is not shown on every story** — unrelated stories show a “no integration” state until the story context matches or you set parameters manually.
+
 Per-story matching:
 
 ```ts
@@ -142,13 +175,14 @@ export const Default = {
 | `sxl.figmaNodeId` | `string` | Match entry by Figma node ID |
 | `sxl.figmaUrl` | `string` | Direct Figma URL (no registry needed) |
 | `sxl.description` | `string` | Override description |
-| `sxl.tokenStatus` | `"assigned" \| "partial" \| "none"` | Override token status |
+| `sxl.tokensBool` | `"true" \| "false"` | Explicit override for Tokens badge |
+| `sxl.tokenStatus` | `"assigned" \| "partial" \| "none"` | Deprecated compatibility override; internally mapped to `tokensBool` |
 | `sxl.readiness` | `"complete" \| "ready-for-dev" \| "in-progress" \| "backlog"` | Override readiness |
 | `sxl.compositionSources` | `Record<string, string>` | Map repo-relative composition paths → raw JSON (recommended) |
 | `sxl.compositionFetchBaseUrl` | `string` | Base URL to `fetch()` composition by path (e.g. static dir) |
 | `sxl.compositionDevProxyPrefix` | `string` | Same-origin prefix (e.g. Vite proxy) so fetches avoid CORS to private Git |
 | `sxl.resolveComposition` | `(path) => Promise<string \| undefined>` | Custom loader for composition file content |
-| `sxl.debugFigmaEmbed` | `boolean` | Log embed URL and iframe `load` to the console |
+| `sxl.debugFigmaEmbed` | `boolean` | Log embed diagnostics (`resolved`, `iframe-load`, `iframe-error`) to the console |
 
 ## Composition JSON (repo file, not inlined in diff)
 

package/dist/index.d.ts

@@ -92,7 +92,7 @@ type SxlStoryParameters = {
     figmaUrl?: string;
     /** Direct description (overrides registry). */
     description?: string;
-    /** Override token badge per-story. */
+    /** @deprecated Prefer `tokensBool`; kept for backward compatibility and mapped to `tokensBool` internally. */
     tokenStatus?: SxlTokenStatus;
     tokensBool?: SxlTokensBool;
     /** Override readiness per-story. */

package/dist/manager.js

@@ -12,123 +12,6 @@ var SXL_TOKENS_URL_PREFIX = "/sxl-tokens";
 import React2, { useCallback as useCallback3, useEffect, useState } from "react";
 import { useParameter, useStorybookState } from "@storybook/manager-api";
 
-// src/convert.ts
-function fromDiffCodeConnect(data) {
-  if (!data || typeof data !== "object") {
-    return { version: 1, figmaFileKey: "", entries: [] };
-  }
-  const d = data;
-  const fileKey = typeof d.$figmaFileKey === "string" ? d.$figmaFileKey : "";
-  const fileName = typeof d.$figmaFileName === "string" ? d.$figmaFileName : void 0;
-  const repository = d.repository && typeof d.repository === "object" ? d.repository : void 0;
-  const isV2 = Array.isArray(d.components);
-  const entries = isV2 ? convertV2Components(d.components, fileKey) : convertV1Entries(Array.isArray(d.entries) ? d.entries : [], fileKey);
-  return {
-    version: 1,
-    figmaFileKey: fileKey,
-    figmaFileName: fileName,
-    repository: repository ? {
-      ...typeof repository.url === "string" ? { url: repository.url } : {},
-      ...typeof repository.documentationUrl === "string" ? { documentationUrl: repository.documentationUrl } : {}
-    } : void 0,
-    entries
-  };
-}
-function tokensBoolFromStorybook(sb) {
-  if (sb.tokensReady === true) return "true";
-  return "false";
-}
-function convertV2Components(components, fileKey) {
-  return components.filter((c) => c.linked === true).map((c) => {
-    const nodeId = String(c.nodeId ?? "");
-    const sb = c.storybook ?? {};
-    const cc = c.codeConnect ?? {};
-    const figmaUrl = typeof sb.figmaUrl === "string" && sb.figmaUrl.trim() ? sb.figmaUrl.trim() : fileKey ? `https://www.figma.com/design/${fileKey}?node-id=${nodeId.replace(":", "-")}` : void 0;
-    const statusRaw = typeof sb.status === "string" ? sb.status : void 0;
-    const readiness = statusRaw === "complete" || statusRaw === "ready-for-dev" || statusRaw === "in-progress" || statusRaw === "backlog" ? statusRaw : void 0;
-    const files = parseFiles(Array.isArray(cc.files) ? cc.files : []);
-    const componentApi = parseComponentApi(sb.componentApi);
-    return {
-      nodeId,
-      displayName: String(c.displayName ?? c.name ?? ""),
-      description: sb.description ? String(sb.description) : void 0,
-      figmaUrl,
-      designEmbed: sb.designEmbed === true,
-      compositionJson: sb.compositionJson === true,
-      metadata: sb.metadata === true,
-      updatedAt: typeof c.updatedAt === "string" ? c.updatedAt : void 0,
-      importPath: typeof cc.importPath === "string" ? cc.importPath : void 0,
-      snippetTemplate: typeof cc.snippetTemplate === "string" ? cc.snippetTemplate : void 0,
-      files: files.length > 0 ? files : void 0,
-      compositionFilePath: typeof sb.compositionFilePath === "string" ? sb.compositionFilePath : void 0,
-      compositionSnapshot: typeof sb.compositionSnapshot === "string" ? sb.compositionSnapshot : void 0,
-      compositionName: typeof sb.compositionName === "string" ? sb.compositionName : void 0,
-      componentApi,
-      meta: {
-        tokensBool: tokensBoolFromStorybook(sb),
-        ...readiness ? { readiness } : {}
-      }
-    };
-  });
-}
-function parseComponentApi(raw) {
-  if (!raw || typeof raw !== "object") return void 0;
-  const o = raw;
-  if (!Array.isArray(o.properties)) return void 0;
-  const properties = o.properties.filter((p) => !!p && typeof p === "object").map((p) => ({
-    name: String(p.name ?? ""),
-    kind: String(p.kind ?? ""),
-    ...p.defaultValue !== void 0 ? { defaultValue: p.defaultValue } : {},
-    ...Array.isArray(p.options) ? { options: p.options.map(String) } : {}
-  }));
-  return properties.length ? { properties } : void 0;
-}
-function convertV1Entries(rawEntries, fileKey) {
-  return rawEntries.filter((e) => {
-    if (!e || typeof e !== "object") return false;
-    const o = e;
-    return o.linked === true && !!o.binding;
-  }).map((e) => {
-    const b = e.binding;
-    const sb = b.storybook ?? {};
-    const nodeId = String(e.nodeId ?? "");
-    const figmaUrl = typeof sb.figmaUrl === "string" && sb.figmaUrl.trim() ? sb.figmaUrl.trim() : fileKey ? `https://www.figma.com/design/${fileKey}?node-id=${nodeId.replace(":", "-")}` : void 0;
-    const statusRaw = typeof sb.status === "string" ? sb.status : void 0;
-    const readiness = statusRaw === "complete" || statusRaw === "ready-for-dev" || statusRaw === "in-progress" || statusRaw === "backlog" ? statusRaw : void 0;
-    const files = parseFiles(Array.isArray(b.files) ? b.files : []);
-    const componentApi = parseComponentApi(sb.componentApi);
-    return {
-      nodeId,
-      displayName: String(b.displayName ?? e.nodeName ?? ""),
-      description: sb.description ? String(sb.description) : void 0,
-      figmaUrl,
-      designEmbed: sb.designEmbed === true,
-      compositionJson: sb.compositionJson === true,
-      metadata: sb.metadata === true,
-      updatedAt: typeof e.updatedAt === "string" ? e.updatedAt : void 0,
-      importPath: typeof b.importPath === "string" ? b.importPath : void 0,
-      snippetTemplate: typeof b.snippetTemplate === "string" ? b.snippetTemplate : void 0,
-      files: files.length > 0 ? files : void 0,
-      compositionFilePath: typeof sb.compositionFilePath === "string" ? sb.compositionFilePath : void 0,
-      compositionSnapshot: typeof sb.compositionSnapshot === "string" ? sb.compositionSnapshot : void 0,
-      compositionName: typeof sb.compositionName === "string" ? sb.compositionName : void 0,
-      componentApi,
-      meta: {
-        tokensBool: tokensBoolFromStorybook(sb),
-        ...readiness ? { readiness } : {}
-      }
-    };
-  });
-}
-function parseFiles(raw) {
-  return raw.filter((f) => !!f && typeof f === "object").map((f) => ({
-    framework: String(f.framework ?? ""),
-    filePath: String(f.filePath ?? ""),
-    ...f.componentName ? { componentName: String(f.componentName) } : {},
-    ...f.importPath ? { importPath: String(f.importPath) } : {}
-  }));
-}
-
 // src/compositionLoad.ts
 function normalizeCompositionPath(p) {
   return p.trim().replace(/\\/g, "/").replace(/^\/+/, "");
@@ -278,28 +161,304 @@ async function loadCompositionJsonText(path, legacyInline, params) {
       };
     }
   }
-  const sxlPresetUrls = candidateRelativePaths(p).map((rel) => joinFetchUrl(SXL_TOKENS_URL_PREFIX, rel));
-  const sxlPresetHit = await fetchFirstOk(sxlPresetUrls);
-  if (sxlPresetHit) {
-    return { text: sxlPresetHit.text, source: "fetch" };
+  const sxlPresetUrls = candidateRelativePaths(p).map((rel) => joinFetchUrl(SXL_TOKENS_URL_PREFIX, rel));
+  const sxlPresetHit = await fetchFirstOk(sxlPresetUrls);
+  if (sxlPresetHit) {
+    return { text: sxlPresetHit.text, source: "fetch" };
+  }
+  const repoUrl = extractRepositoryUrl(params);
+  if (repoUrl) {
+    const gitlabCandidates = buildGitlabRawCandidates(repoUrl, p);
+    const hit = await fetchFirstOk(gitlabCandidates);
+    if (hit) {
+      return { text: hit.text, source: "fetch" };
+    }
+  }
+  const localCandidates = candidateRelativePaths(p).map((rel) => `/${rel}`);
+  const localHit = await fetchFirstOk(localCandidates);
+  if (localHit) {
+    return { text: localHit.text, source: "fetch" };
+  }
+  return {
+    error: "Composition file is not inlined and auto-fetch failed. Use compositionSources, compositionFetchBaseUrl + staticDirs, resolveComposition(), or compositionDevProxyPrefix (same-origin proxy; private Git hosts usually block CORS) \u2014 see @sxl-studio/storybook-addon README."
+  };
+}
+
+// src/convert.ts
+function fromDiffCodeConnect(data) {
+  if (!data || typeof data !== "object") {
+    return { version: 1, figmaFileKey: "", entries: [] };
+  }
+  const d = data;
+  const fileKey = typeof d.$figmaFileKey === "string" ? d.$figmaFileKey : "";
+  const fileName = typeof d.$figmaFileName === "string" ? d.$figmaFileName : void 0;
+  const repository = d.repository && typeof d.repository === "object" ? d.repository : void 0;
+  const isV2 = Array.isArray(d.components);
+  const entries = isV2 ? convertV2Components(d.components, fileKey) : convertV1Entries(Array.isArray(d.entries) ? d.entries : [], fileKey);
+  return {
+    version: 1,
+    figmaFileKey: fileKey,
+    figmaFileName: fileName,
+    repository: repository ? {
+      ...typeof repository.url === "string" ? { url: repository.url } : {},
+      ...typeof repository.documentationUrl === "string" ? { documentationUrl: repository.documentationUrl } : {}
+    } : void 0,
+    entries
+  };
+}
+function tokensBoolFromStorybook(sb) {
+  if (sb.tokensReady === true) return "true";
+  return "false";
+}
+function convertV2Components(components, fileKey) {
+  return components.filter((c) => c.linked === true).map((c) => {
+    const nodeId = String(c.nodeId ?? "");
+    const sb = c.storybook ?? {};
+    const cc = c.codeConnect ?? {};
+    const figmaUrl = typeof sb.figmaUrl === "string" && sb.figmaUrl.trim() ? sb.figmaUrl.trim() : fileKey ? `https://www.figma.com/design/${fileKey}?node-id=${nodeId.replace(":", "-")}` : void 0;
+    const statusRaw = typeof sb.status === "string" ? sb.status : void 0;
+    const readiness = statusRaw === "complete" || statusRaw === "ready-for-dev" || statusRaw === "in-progress" || statusRaw === "backlog" ? statusRaw : void 0;
+    const files = parseFiles(Array.isArray(cc.files) ? cc.files : []);
+    const componentApi = parseComponentApi(sb.componentApi);
+    return {
+      nodeId,
+      displayName: String(c.displayName ?? c.name ?? ""),
+      description: sb.description ? String(sb.description) : void 0,
+      figmaUrl,
+      designEmbed: sb.designEmbed === true,
+      compositionJson: sb.compositionJson === true,
+      metadata: sb.metadata === true,
+      updatedAt: typeof c.updatedAt === "string" ? c.updatedAt : void 0,
+      importPath: typeof cc.importPath === "string" ? cc.importPath : void 0,
+      snippetTemplate: typeof cc.snippetTemplate === "string" ? cc.snippetTemplate : void 0,
+      files: files.length > 0 ? files : void 0,
+      compositionFilePath: typeof sb.compositionFilePath === "string" ? sb.compositionFilePath : void 0,
+      compositionSnapshot: typeof sb.compositionSnapshot === "string" ? sb.compositionSnapshot : void 0,
+      compositionName: typeof sb.compositionName === "string" ? sb.compositionName : void 0,
+      componentApi,
+      meta: {
+        tokensBool: tokensBoolFromStorybook(sb),
+        ...readiness ? { readiness } : {}
+      }
+    };
+  });
+}
+function parseComponentApi(raw) {
+  if (!raw || typeof raw !== "object") return void 0;
+  const o = raw;
+  if (!Array.isArray(o.properties)) return void 0;
+  const properties = o.properties.filter((p) => !!p && typeof p === "object").map((p) => ({
+    name: String(p.name ?? ""),
+    kind: String(p.kind ?? ""),
+    ...p.defaultValue !== void 0 ? { defaultValue: p.defaultValue } : {},
+    ...Array.isArray(p.options) ? { options: p.options.map(String) } : {}
+  }));
+  return properties.length ? { properties } : void 0;
+}
+function convertV1Entries(rawEntries, fileKey) {
+  return rawEntries.filter((e) => {
+    if (!e || typeof e !== "object") return false;
+    const o = e;
+    return o.linked === true && !!o.binding;
+  }).map((e) => {
+    const b = e.binding;
+    const sb = b.storybook ?? {};
+    const nodeId = String(e.nodeId ?? "");
+    const figmaUrl = typeof sb.figmaUrl === "string" && sb.figmaUrl.trim() ? sb.figmaUrl.trim() : fileKey ? `https://www.figma.com/design/${fileKey}?node-id=${nodeId.replace(":", "-")}` : void 0;
+    const statusRaw = typeof sb.status === "string" ? sb.status : void 0;
+    const readiness = statusRaw === "complete" || statusRaw === "ready-for-dev" || statusRaw === "in-progress" || statusRaw === "backlog" ? statusRaw : void 0;
+    const files = parseFiles(Array.isArray(b.files) ? b.files : []);
+    const componentApi = parseComponentApi(sb.componentApi);
+    return {
+      nodeId,
+      displayName: String(b.displayName ?? e.nodeName ?? ""),
+      description: sb.description ? String(sb.description) : void 0,
+      figmaUrl,
+      designEmbed: sb.designEmbed === true,
+      compositionJson: sb.compositionJson === true,
+      metadata: sb.metadata === true,
+      updatedAt: typeof e.updatedAt === "string" ? e.updatedAt : void 0,
+      importPath: typeof b.importPath === "string" ? b.importPath : void 0,
+      snippetTemplate: typeof b.snippetTemplate === "string" ? b.snippetTemplate : void 0,
+      files: files.length > 0 ? files : void 0,
+      compositionFilePath: typeof sb.compositionFilePath === "string" ? sb.compositionFilePath : void 0,
+      compositionSnapshot: typeof sb.compositionSnapshot === "string" ? sb.compositionSnapshot : void 0,
+      compositionName: typeof sb.compositionName === "string" ? sb.compositionName : void 0,
+      componentApi,
+      meta: {
+        tokensBool: tokensBoolFromStorybook(sb),
+        ...readiness ? { readiness } : {}
+      }
+    };
+  });
+}
+function parseFiles(raw) {
+  return raw.filter((f) => !!f && typeof f === "object").map((f) => ({
+    framework: String(f.framework ?? ""),
+    filePath: String(f.filePath ?? ""),
+    ...f.componentName ? { componentName: String(f.componentName) } : {},
+    ...f.importPath ? { importPath: String(f.importPath) } : {}
+  }));
+}
+
+// src/entryResolve.ts
+function getRegistryFigmaFileKey(raw) {
+  if (!raw || typeof raw !== "object") return "";
+  const fk = raw.figmaFileKey;
+  return typeof fk === "string" ? fk.trim() : "";
+}
+function buildFigmaDesignUrlFromFileKey(fileKey, nodeId) {
+  if (!fileKey || !nodeId) return void 0;
+  return `https://www.figma.com/design/${fileKey}?node-id=${String(nodeId).replace(/:/g, "-")}`;
+}
+function tokenStatusToTokensBool(status) {
+  if (status === "assigned") return "true";
+  if (status === "partial" || status === "none") return "false";
+  return void 0;
+}
+function normalizeRegistry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw;
+  if (Array.isArray(obj.components)) {
+    return fromDiffCodeConnect(raw);
+  }
+  const entries = Array.isArray(obj.entries) ? obj.entries : [];
+  if (entries.length === 0) return null;
+  const first = entries[0];
+  if (first && "binding" in first && "linked" in first) {
+    return fromDiffCodeConnect(raw);
+  }
+  if (first && "nodeId" in first && "displayName" in first) {
+    return raw;
+  }
+  return null;
+}
+function resolveEntry(params, ctx) {
+  if (!params) return { status: "no-registry" };
+  const registry = normalizeRegistry(params.registry);
+  const tokensOverride = params.tokensBool ?? tokenStatusToTokensBool(params.tokenStatus);
+  if (params.figmaUrl || params.description) {
+    return {
+      status: "found",
+      entry: {
+        nodeId: params.figmaNodeId ?? "",
+        displayName: params.component ?? params.componentName ?? "",
+        description: params.description,
+        figmaUrl: params.figmaUrl,
+        designEmbed: params.designEmbed ?? !!params.figmaUrl,
+        compositionJson: params.compositionJson,
+        metadata: params.metadata,
+        meta: {
+          tokensBool: tokensOverride,
+          readiness: params.readiness,
+          tokenStatus: params.tokenStatus
+        }
+      }
+    };
+  }
+  if (!registry) return { status: "no-registry" };
+  let found;
+  if (params.figmaNodeId) {
+    found = registry.entries.find((e) => e.nodeId === params.figmaNodeId);
   }
-  const repoUrl = extractRepositoryUrl(params);
-  if (repoUrl) {
-    const gitlabCandidates = buildGitlabRawCandidates(repoUrl, p);
-    const hit = await fetchFirstOk(gitlabCandidates);
-    if (hit) {
-      return { text: hit.text, source: "fetch" };
+  if (!found) {
+    const name = (params.component ?? params.componentName ?? "").toLowerCase();
+    if (name) {
+      found = registry.entries.find((e) => e.displayName.toLowerCase() === name);
     }
   }
-  const localCandidates = candidateRelativePaths(p).map((rel) => `/${rel}`);
-  const localHit = await fetchFirstOk(localCandidates);
-  if (localHit) {
-    return { text: localHit.text, source: "fetch" };
+  if (!found) {
+    found = matchByStoryContext(registry.entries, ctx);
   }
+  if (!found) {
+    const hint = extractComponentName(ctx.title) || ctx.name || "";
+    return { status: "no-match", componentHint: hint };
+  }
+  const rootFileKey = getRegistryFigmaFileKey(params.registry);
+  const figmaUrlResolved = found.figmaUrl ?? buildFigmaDesignUrlFromFileKey(rootFileKey, found.nodeId);
   return {
-    error: "Composition file is not inlined and auto-fetch failed. Use compositionSources, compositionFetchBaseUrl + staticDirs, resolveComposition(), or compositionDevProxyPrefix (same-origin proxy; private Git hosts usually block CORS) \u2014 see @sxl-studio/storybook-addon README."
+    status: "found",
+    entry: {
+      ...found,
+      figmaUrl: figmaUrlResolved,
+      meta: {
+        ...found.meta,
+        tokensBool: tokensOverride ?? found.meta?.tokensBool ?? tokenStatusToTokensBool(found.meta?.tokenStatus),
+        tokenStatus: params.tokenStatus ?? found.meta?.tokenStatus,
+        readiness: params.readiness ?? found.meta?.readiness
+      },
+      description: params.description ?? found.description,
+      compositionJson: params.compositionJson ?? found.compositionJson,
+      metadata: params.metadata ?? found.metadata,
+      designEmbed: params.designEmbed ?? found.designEmbed,
+      compositionFilePath: found.compositionFilePath,
+      compositionSnapshot: found.compositionSnapshot,
+      componentApi: found.componentApi
+    }
   };
 }
+function resolveTokensBool(entry, params) {
+  const explicit = params?.tokensBool ?? tokenStatusToTokensBool(params?.tokenStatus);
+  if (explicit) return explicit;
+  const fromEntry = entry.meta?.tokensBool ?? tokenStatusToTokensBool(entry.meta?.tokenStatus);
+  if (fromEntry) return fromEntry;
+  return "false";
+}
+function matchByStoryContext(entries, ctx) {
+  const tokens = [
+    extractComponentName(ctx.title),
+    ctx.name,
+    ctx.storyId,
+    ctx.importPath,
+    fileStem(ctx.importPath)
+  ].filter(Boolean).map(norm);
+  if (tokens.length === 0) return void 0;
+  let best;
+  let bestScore = 0;
+  let tie = false;
+  for (const entry of entries) {
+    const sc = score(entry, tokens);
+    if (sc > bestScore) {
+      bestScore = sc;
+      best = entry;
+      tie = false;
+    } else if (sc === bestScore && sc > 0) {
+      tie = true;
+    }
+  }
+  if (tie || bestScore < 60) return void 0;
+  return best;
+}
+function score(entry, tokens) {
+  const display = norm(entry.displayName);
+  const imprt = norm(entry.importPath ?? "");
+  const stems = (entry.files ?? []).map((f) => norm(fileStem(f.filePath))).filter(Boolean);
+  let s = 0;
+  for (const t of tokens) {
+    if (!t) continue;
+    if (display && t === display) s += 120;
+    else if (display && t.includes(display)) s += 70;
+    else if (display && display.includes(t)) s += 65;
+    if (imprt && t.includes(imprt)) s += 55;
+    for (const stem of stems) {
+      if (stem && t.includes(stem)) s += 30;
+    }
+  }
+  return s;
+}
+function extractComponentName(title) {
+  if (!title) return "";
+  const parts = title.split("/");
+  return parts[parts.length - 1].trim();
+}
+function norm(v) {
+  return v.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function fileStem(p) {
+  const f = (p || "").split("/").pop() ?? "";
+  const d = f.lastIndexOf(".");
+  return d > 0 ? f.slice(0, d) : f;
+}
 
 // src/components/JsonHighlighted.tsx
 import React from "react";
@@ -3642,157 +3801,12 @@ var JsonHighlighted = ({ code }) => {
 };
 
 // src/components/SxlPanel.tsx
-function getRegistryFigmaFileKey(raw) {
-  if (!raw || typeof raw !== "object") return "";
-  const fk = raw.figmaFileKey;
-  return typeof fk === "string" ? fk.trim() : "";
-}
-function buildFigmaDesignUrlFromFileKey(fileKey, nodeId) {
-  if (!fileKey || !nodeId) return void 0;
-  return `https://www.figma.com/design/${fileKey}?node-id=${String(nodeId).replace(/:/g, "-")}`;
-}
 var READINESS_BADGE = {
   backlog: { label: "Backlog", bg: "#111827", fg: "#f9fafb" },
   "in-progress": { label: "In Progress", bg: "#ea580c", fg: "#ffffff" },
   "ready-for-dev": { label: "Ready for Dev", bg: "#16a34a", fg: "#ffffff" },
   complete: { label: "Completed", bg: "#9ca3af", fg: "#111827" }
 };
-function normalizeRegistry(raw) {
-  if (!raw || typeof raw !== "object") return null;
-  const obj = raw;
-  if (Array.isArray(obj.components)) {
-    return fromDiffCodeConnect(raw);
-  }
-  const entries = Array.isArray(obj.entries) ? obj.entries : [];
-  if (entries.length === 0) return null;
-  const first = entries[0];
-  if (first && "binding" in first && "linked" in first) {
-    return fromDiffCodeConnect(raw);
-  }
-  if (first && "nodeId" in first && "displayName" in first) {
-    return raw;
-  }
-  return null;
-}
-function resolveEntry(params, ctx) {
-  if (!params) return { status: "no-registry" };
-  const registry = normalizeRegistry(params.registry);
-  if (params.figmaUrl || params.description) {
-    return {
-      status: "found",
-      entry: {
-        nodeId: params.figmaNodeId ?? "",
-        displayName: params.component ?? params.componentName ?? "",
-        description: params.description,
-        figmaUrl: params.figmaUrl,
-        designEmbed: params.designEmbed ?? !!params.figmaUrl,
-        compositionJson: params.compositionJson,
-        metadata: params.metadata,
-        meta: {
-          tokensBool: params.tokensBool,
-          readiness: params.readiness
-        }
-      }
-    };
-  }
-  if (!registry) return { status: "no-registry" };
-  let found;
-  if (params.figmaNodeId) {
-    found = registry.entries.find((e) => e.nodeId === params.figmaNodeId);
-  }
-  if (!found) {
-    const name = (params.component ?? params.componentName ?? "").toLowerCase();
-    if (name) {
-      found = registry.entries.find((e) => e.displayName.toLowerCase() === name);
-    }
-  }
-  if (!found && registry.entries.length === 1) {
-    found = registry.entries[0];
-  }
-  if (!found && registry.entries.length > 1) {
-    found = matchByStoryContext(registry.entries, ctx);
-  }
-  if (!found) {
-    const hint = extractComponentName(ctx.title) || ctx.name || "";
-    return { status: "no-match", componentHint: hint };
-  }
-  const rootFileKey = getRegistryFigmaFileKey(params.registry);
-  const figmaUrlResolved = found.figmaUrl ?? buildFigmaDesignUrlFromFileKey(rootFileKey, found.nodeId);
-  return {
-    status: "found",
-    entry: {
-      ...found,
-      figmaUrl: figmaUrlResolved,
-      meta: {
-        ...found.meta,
-        tokensBool: params.tokensBool ?? found.meta?.tokensBool,
-        readiness: params.readiness ?? found.meta?.readiness
-      },
-      description: params.description ?? found.description,
-      compositionJson: params.compositionJson ?? found.compositionJson,
-      metadata: params.metadata ?? found.metadata,
-      designEmbed: params.designEmbed ?? found.designEmbed,
-      compositionFilePath: found.compositionFilePath,
-      compositionSnapshot: found.compositionSnapshot,
-      componentApi: found.componentApi
-    }
-  };
-}
-function matchByStoryContext(entries, ctx) {
-  const tokens = [
-    extractComponentName(ctx.title),
-    ctx.name,
-    ctx.storyId,
-    ctx.importPath,
-    fileStem(ctx.importPath)
-  ].filter(Boolean).map(norm);
-  if (tokens.length === 0) return void 0;
-  let best;
-  let bestScore = 0;
-  let tie = false;
-  for (const entry of entries) {
-    const sc = score(entry, tokens);
-    if (sc > bestScore) {
-      bestScore = sc;
-      best = entry;
-      tie = false;
-    } else if (sc === bestScore && sc > 0) {
-      tie = true;
-    }
-  }
-  if (tie || bestScore < 60) return void 0;
-  return best;
-}
-function score(entry, tokens) {
-  const display = norm(entry.displayName);
-  const imprt = norm(entry.importPath ?? "");
-  const stems = (entry.files ?? []).map((f) => norm(fileStem(f.filePath))).filter(Boolean);
-  let s = 0;
-  for (const t of tokens) {
-    if (!t) continue;
-    if (display && t === display) s += 120;
-    else if (display && t.includes(display)) s += 70;
-    else if (display && display.includes(t)) s += 65;
-    if (imprt && t.includes(imprt)) s += 55;
-    for (const stem of stems) {
-      if (stem && t.includes(stem)) s += 30;
-    }
-  }
-  return s;
-}
-function extractComponentName(title) {
-  if (!title) return "";
-  const parts = title.split("/");
-  return parts[parts.length - 1].trim();
-}
-function norm(v) {
-  return v.toLowerCase().replace(/[^a-z0-9]+/g, "");
-}
-function fileStem(p) {
-  const f = (p || "").split("/").pop() ?? "";
-  const d = f.lastIndexOf(".");
-  return d > 0 ? f.slice(0, d) : f;
-}
 function buildEmbedUrl(figmaUrl) {
   if (figmaUrl.includes("figma.com/embed")) return figmaUrl;
   return `https://www.figma.com/embed?embed_host=share&url=${encodeURIComponent(figmaUrl)}`;
@@ -3821,12 +3835,6 @@ function formatDate(iso) {
     return iso;
   }
 }
-function resolveTokensBool(entry, params) {
-  const p = params?.tokensBool ?? entry.meta?.tokensBool;
-  if (p === "true" || p === "false") return p;
-  if (entry.meta?.tokenStatus === "assigned") return "true";
-  return "false";
-}
 function formatJsonSnapshot(raw) {
   if (!raw) return "";
   try {
@@ -3835,6 +3843,10 @@ function formatJsonSnapshot(raw) {
     return raw;
   }
 }
+function logFigmaEmbedDebug(enabled, event, payload) {
+  if (!enabled) return;
+  console.debug("[SXL Studio addon] Figma embed", { event, ...payload });
+}
 var TokensBadge = ({ value }) => {
   const on = value === "true";
   return /* @__PURE__ */ React2.createElement(
@@ -3948,6 +3960,8 @@ var SxlPanel = () => {
   const entryForRender = result.status === "found" ? result.entry : null;
   const showEmbed = !!entryForRender?.figmaUrl && entryForRender.designEmbed !== false;
   const renderEmbedSection = entryForRender?.designEmbed === true || !!entryForRender?.figmaUrl;
+  const debugFigmaEmbed = params?.debugFigmaEmbed === true;
+  const embedUrl = showEmbed && entryForRender?.figmaUrl ? buildEmbedUrl(entryForRender.figmaUrl) : void 0;
   useEffect(() => {
     if (!entryForRender) return;
     if (entryForRender.designEmbed === true && !entryForRender.figmaUrl) {
@@ -3956,7 +3970,23 @@ var SxlPanel = () => {
         { nodeId: entryForRender.nodeId, displayName: entryForRender.displayName }
       );
     }
-  }, [entryForRender?.designEmbed, entryForRender?.figmaUrl, entryForRender?.nodeId, entryForRender?.displayName]);
+    logFigmaEmbedDebug(debugFigmaEmbed, "resolved", {
+      nodeId: entryForRender.nodeId,
+      displayName: entryForRender.displayName,
+      designEmbed: entryForRender.designEmbed ?? null,
+      figmaUrl: entryForRender.figmaUrl ?? null,
+      embedUrl: embedUrl ?? null,
+      storyId: ctx.storyId || null
+    });
+  }, [
+    debugFigmaEmbed,
+    embedUrl,
+    ctx.storyId,
+    entryForRender?.designEmbed,
+    entryForRender?.figmaUrl,
+    entryForRender?.nodeId,
+    entryForRender?.displayName
+  ]);
   if (result.status === "no-registry") {
     return React2.createElement(NoRegistryState, null);
   }
@@ -3974,16 +4004,28 @@ var SxlPanel = () => {
     "iframe",
     {
       title: "Figma embed",
-      src: buildEmbedUrl(entry.figmaUrl),
+      src: embedUrl,
       style: iframe,
       allowFullScreen: true,
       allow: "clipboard-write; fullscreen",
-      referrerPolicy: "no-referrer-when-downgrade"
+      referrerPolicy: "no-referrer-when-downgrade",
+      onLoad: () => {
+        logFigmaEmbedDebug(debugFigmaEmbed, "iframe-load", {
+          nodeId: entry.nodeId,
+          embedUrl: embedUrl ?? null
+        });
+      },
+      onError: () => {
+        logFigmaEmbedDebug(debugFigmaEmbed, "iframe-error", {
+          nodeId: entry.nodeId,
+          embedUrl: embedUrl ?? null
+        });
+      }
     }
   ), /* @__PURE__ */ React2.createElement("div", { style: embedFooter }, /* @__PURE__ */ React2.createElement(
     "a",
     {
-      href: buildEmbedUrl(entry.figmaUrl),
+      href: embedUrl,
       target: "_blank",
       rel: "noopener noreferrer",
       style: { ...link, marginRight: "12px" }

package/dist/preset.js

@@ -166,9 +166,16 @@ function staticDirs(entries, options) {
   return [...e, { from: root, to: `/${mount}` }];
 }
 function mergeSxlFigmaFrameSrcHeader(config) {
-  const directive = "frame-src 'self' https://www.figma.com https://*.figma.com data: blob:;";
+  const requiredSources = [
+    "'self'",
+    "https://www.figma.com",
+    "https://*.figma.com",
+    "data:",
+    "blob:"
+  ];
+  const directive = `frame-src ${requiredSources.join(" ")}`;
   const prev = config.server?.headers?.["Content-Security-Policy"];
-  const merged = typeof prev === "string" && prev.trim() ? `${prev.trim()}; ${directive}` : directive;
+  const merged = typeof prev === "string" && prev.trim() ? mergeCspFrameSrcDirective(prev, requiredSources) : directive;
   return {
     ...config,
     server: {
@@ -180,6 +187,32 @@ function mergeSxlFigmaFrameSrcHeader(config) {
     }
   };
 }
+function mergeCspFrameSrcDirective(policy, requiredSources) {
+  const directives = policy.split(";").map((d) => d.trim()).filter(Boolean);
+  let hasFrameSrc = false;
+  const mergedDirectives = directives.map((directive) => {
+    const parts = directive.split(/\s+/).filter(Boolean);
+    if (parts.length === 0) return directive;
+    const name = parts[0].toLowerCase();
+    if (name !== "frame-src") return directive;
+    hasFrameSrc = true;
+    const existing = parts.slice(1);
+    const next = [...existing];
+    const seen = new Set(existing.map((v) => v.toLowerCase()));
+    for (const src of requiredSources) {
+      const key = src.toLowerCase();
+      if (!seen.has(key)) {
+        seen.add(key);
+        next.push(src);
+      }
+    }
+    return `frame-src ${next.join(" ")}`;
+  });
+  if (!hasFrameSrc) {
+    mergedDirectives.push(`frame-src ${requiredSources.join(" ")}`);
+  }
+  return mergedDirectives.join("; ");
+}
 export {
   managerEntries,
   mergeSxlFigmaFrameSrcHeader,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sxl-studio/storybook-addon",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Storybook addon for SXL Studio — displays Figma Embed, component info and design token status for linked components",
   "type": "module",
   "main": "dist/index.js",
@@ -25,8 +25,11 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "lint": "eslint \"src/**/*.{ts,tsx}\" --max-warnings=0",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "prepublishOnly": "npm run build",
+    "push": "npm run build && npm publish"
   },
   "keywords": [
     "storybook",
@@ -43,14 +46,19 @@
     "storybook": "^8.0.0 || ^9.0.0 || ^10.0.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.27.0",
     "@storybook/components": "^8.6.14",
     "@storybook/manager-api": "^8.6.14",
     "@types/node": "^22.19.17",
     "@types/react": "^18.0.0",
+    "eslint": "^9.27.0",
+    "globals": "^15.15.0",
     "react": "^18.0.0",
     "storybook": "^8.0.0",
+    "tsx": "^4.19.2",
     "tsup": "^8.5.1",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.33.1"
   },
   "storybook": {
     "preset": "./preset.js",