feat(ci): add StackBlitz collection link to PR preview comment

.github/scripts/build-preview-urls-comment.js

@@ -12,7 +12,21 @@
  * governing permissions and limitations under the License.
  */
 
-export const buildPreviewURLComment = (prNumber) => {
+/**
+ * @param {number} prNumber pull request number
+ * @param {object} [options]
+ * @param {string} [options.headCommitSha] PR head SHA (for StackBlitz “open repo at commit”)
+ * @param {string} [options.repositoryFullName] `owner/name` (fork-aware)
+ * @param {string} [options.stackBlitzStoryLinksSection] markdown from `extract-storybook-stackblitz-links.js`
+ */
+export const buildPreviewURLComment = (
+  prNumber,
+  {
+    headCommitSha = '',
+    repositoryFullName = 'adobe/spectrum-web-components',
+    stackBlitzStoryLinksSection = '',
+  } = {}
+) => {
   // Use just PR number so each commit overwrites the previous deployment
   const prHash = `pr-${prNumber}`;
 
@@ -86,12 +100,42 @@ export const buildPreviewURLComment = (prNumber) => {
   const storybookFirstGenUrl = `${baseUrl}/${prHash}/docs/first-gen-storybook/`;
   const storybookSecondGenUrl = `${baseUrl}/${prHash}/docs/second-gen-storybook/`;
 
+  const stackBlitzCollectionUrl =
+    'https://stackblitz.com/orgs/custom/SWC-Team/collections/spectrum-web-components';
+
+  const shortSha =
+    headCommitSha && headCommitSha.length >= 7
+      ? headCommitSha.slice(0, 7)
+      : headCommitSha;
+
+  const stackBlitzForkUrl = headCommitSha
+    ? `https://stackblitz.com/fork/github/${repositoryFullName}/tree/${headCommitSha}`
+    : '';
+
+  const stackBlitzForkBullet = stackBlitzForkUrl
+    ? `- [Open repository at head commit \`${shortSha}\` (StackBlitz fork)](${stackBlitzForkUrl}) — full monorepo at this PR’s commit. Large project: \`yarn install\` can take several minutes. To run second-gen Storybook locally: \`yarn workspace @spectrum-web-components/2nd-gen storybook\`.`
+    : '';
+
   let comment = `## 📚 Branch Preview Links
 
 - [Documentation Site (first-gen)](${docsFirstGenUrl})
 - [Storybook (first-gen)](${storybookFirstGenUrl})
 - [Storybook (second-gen)](${storybookSecondGenUrl})
 
+<h3><strong>🧪 StackBlitz</strong></h3>
+
+**Branch / commit**
+
+${stackBlitzForkBullet || '- _StackBlitz repository link unavailable (missing commit SHA)._'}
+
+**Curated collection** (SWC-Team workspace; published package demos)
+
+- [Spectrum Web Components collection](${stackBlitzCollectionUrl})
+
+**Story-linked templates** (from 2nd-gen \`parameters.stackblitz.url\`; standalone StackBlitz projects use the **published** npm package—use Storybook previews above for this branch’s build)
+
+${stackBlitzStoryLinksSection || '- _No story-level StackBlitz URLs extracted._'}
+
 <h3><strong>🔍 First Generation Visual Regression Test Results</strong></h3>
 
 When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

.github/scripts/extract-storybook-stackblitz-links.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'fs';
+import { dirname, join, relative } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Collect `.stories.ts` files under a directory (recursive).
+ * @param {string} dir
+ * @param {string[]} acc
+ * @returns {string[]}
+ */
+const collectStoryFiles = (dir, acc = []) => {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+  for (const name of names) {
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      collectStoryFiles(full, acc);
+    } else if (name.endsWith('.stories.ts')) {
+      acc.push(full);
+    }
+  }
+  return acc;
+};
+
+/**
+ * Parse `parameters.stackblitz.url` from a Storybook CSF file (best-effort regex).
+ * @param {string} source
+ * @returns {string | null}
+ */
+const extractStackBlitzUrl = (source) => {
+  const match = source.match(
+    /stackblitz\s*:\s*\{[\s\S]*?\burl\s*:\s*['"](https:\/\/[^'"]+)['"]/m
+  );
+  return match ? match[1] : null;
+};
+
+/**
+ * Derive a short component label from `.../components/<name>/stories/...`.
+ * @param {string} storyPath
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+const componentLabelFromPath = (storyPath, repoRoot) => {
+  const rel = relative(repoRoot, storyPath);
+  const parts = rel.split(/[/\\]/);
+  const componentsIdx = parts.indexOf('components');
+  if (componentsIdx >= 0 && parts[componentsIdx + 1]) {
+    return parts[componentsIdx + 1];
+  }
+  return parts.at(-1)?.replace(/\.stories\.ts$/, '') ?? 'story';
+};
+
+/**
+ * Build markdown list items for 2nd-gen stories that define `parameters.stackblitz.url`.
+ *
+ * @param {string} [repoRoot] repository root (defaults to two levels above this script)
+ * @returns {string} markdown lines starting with `- ` or a fallback line
+ */
+export const buildStackBlitzStoryLinksSection = (
+  repoRoot = join(__dirname, '..', '..')
+) => {
+  const storiesRoot = join(repoRoot, '2nd-gen/packages/swc/components');
+  const files = collectStoryFiles(storiesRoot);
+  /** @type {Map<string, { label: string; rel: string }>} */
+  const byUrl = new Map();
+
+  for (const file of files) {
+    let source;
+    try {
+      source = readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    const url = extractStackBlitzUrl(source);
+    if (!url) {
+      continue;
+    }
+    const label = componentLabelFromPath(file, repoRoot);
+    const rel = relative(repoRoot, file).replace(/\\/g, '/');
+    if (!byUrl.has(url)) {
+      byUrl.set(url, { label, rel });
+    }
+  }
+
+  if (byUrl.size === 0) {
+    return '- _No `parameters.stackblitz.url` entries found in 2nd-gen Storybook stories._';
+  }
+
+  const rows = [...byUrl.entries()]
+    .sort((a, b) => a[1].label.localeCompare(b[1].label))
+    .map(([url, { label, rel }]) => {
+      return `- [${label}](${url}) — \`${rel}\``;
+    });
+
+  return rows.join('\n');
+};

.github/workflows/preview-docs.yml

@@ -155,10 +155,21 @@ jobs:
         with:
           script: |
             const { buildPreviewURLComment } = await import('${{ github.workspace }}/.github/scripts/build-preview-urls-comment.js');
+            const { buildStackBlitzStoryLinksSection } = await import('${{ github.workspace }}/.github/scripts/extract-storybook-stackblitz-links.js');
             const { commentOrUpdate } = await import('${{ github.workspace }}/.github/scripts/comment-or-update.js');
 
             const prNumber = context.payload.pull_request.number;
-            const body = buildPreviewURLComment(prNumber);
+            const head = context.payload.pull_request.head;
+            const headSha = head.sha;
+            // Use head repo so fork PRs resolve commits that are not on the base repo yet.
+            const repositoryFullName = head.repo.full_name;
+            const stackBlitzStoryLinksSection = buildStackBlitzStoryLinksSection(process.env.GITHUB_WORKSPACE);
+
+            const body = buildPreviewURLComment(prNumber, {
+              headCommitSha: headSha,
+              repositoryFullName,
+              stackBlitzStoryLinksSection,
+            });
 
             console.log(`Posting comment to PR #${prNumber}`);
             commentOrUpdate(github, context, '## 📚 Branch Preview Links', body);