Merge main into stable

.github/workflows/ci-superdoc.yml

@@ -154,6 +154,15 @@ jobs:
         # ESM, missing CDN files, unpublished `source` paths.
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
+      - name: Legacy public no-growth gates (SD-3176)
+        # No-growth snapshots for the legacy public compatibility surfaces.
+        # See tests/consumer-typecheck/snapshots/README.md for the policy.
+        # Runs after the matrix step so the packed-and-installed fixture
+        # is available for Snapshot B (resolved named exports).
+        run: |
+          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
+          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
+
   unit-tests:
     needs: build
     runs-on: ubuntu-latest

.github/workflows/release-cli.yml

@@ -27,8 +27,14 @@ permissions:
   packages: write
 
 concurrency:
+  # Release runs never cancel an in-progress release (each merge is a release-worthy
+  # state). queue: max keeps GitHub from dropping older pending stable releases when
+  # a stable push touches multiple wrapper packages in the shared release-stable group;
+  # default queue: single only allows one pending. queue: max requires
+  # cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -46,8 +52,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-create.yml

@@ -17,8 +17,14 @@ permissions:
   packages: write
 
 concurrency:
+  # Release runs never cancel an in-progress release (each merge is a release-worthy
+  # state). queue: max keeps GitHub from dropping older pending stable releases when
+  # a stable push touches multiple wrapper packages in the shared release-stable group;
+  # default queue: single only allows one pending. queue: max requires
+  # cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -36,8 +42,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-esign.yml

@@ -19,9 +19,13 @@ permissions:
 concurrency:
   # Stable releases share the `release-stable` group so @semantic-release/git
   # pushes to `stable` serialize across workflows; per-workflow groups would
-  # let releases race on `git push origin stable`.
+  # let releases race on `git push origin stable`. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
+  # queue: max requires cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -39,8 +43,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-mcp.yml

@@ -29,8 +29,14 @@ permissions:
   packages: write
 
 concurrency:
+  # Release runs never cancel an in-progress release (each merge is a release-worthy
+  # state). queue: max keeps GitHub from dropping older pending stable releases when
+  # a stable push touches multiple wrapper packages in the shared release-stable group;
+  # default queue: single only allows one pending. queue: max requires
+  # cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -48,8 +54,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-react.yml

@@ -30,9 +30,13 @@ permissions:
 concurrency:
   # Stable releases share the `release-stable` group so @semantic-release/git
   # pushes to `stable` serialize across workflows; per-workflow groups would
-  # let releases race on `git push origin stable`.
+  # let releases race on `git push origin stable`. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
+  # queue: max requires cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -52,8 +56,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-sdk.yml

@@ -44,8 +44,14 @@ permissions:
   id-token: write # PyPI trusted publishing (OIDC)
 
 concurrency:
+  # Release runs never cancel an in-progress release (each merge is a release-worthy
+  # state). queue: max keeps GitHub from dropping older pending stable releases when
+  # a stable push touches multiple wrapper packages in the shared release-stable group;
+  # default queue: single only allows one pending. queue: max requires
+  # cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   # -------------------------------------------------------------------
@@ -71,8 +77,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-stable.yml

@@ -29,9 +29,12 @@ concurrency:
   # `git push origin stable`, leaving npm/PyPI tarballs published without
   # a corresponding tag/commit pushed.
   # [skip ci] writeback runs use a per-run group so they cannot evict a real
-  # pending stable push while the bundle is active.
+  # pending stable push while the bundle is active. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
   group: ${{ github.event_name == 'push' && contains(github.event.head_commit.message, '[skip ci]') && format('release-stable-skip-{0}', github.run_id) || 'release-stable' }}
   cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -124,6 +127,11 @@ jobs:
       - name: Package shape gates
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
+      - name: Legacy public no-growth gates (SD-3176)
+        run: |
+          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
+          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
+
       - name: Release stable packages (orchestrator)
         id: stable_release
         env:

.github/workflows/release-superdoc.yml

@@ -34,9 +34,13 @@ permissions:
 concurrency:
   # Stable releases share the `release-stable` group so @semantic-release/git
   # pushes to `stable` serialize across workflows; per-workflow groups would
-  # let releases race on `git push origin stable`.
+  # let releases race on `git push origin stable`. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
+  # queue: max requires cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -68,8 +72,12 @@ jobs:
           ref: ${{ steps.pr.outputs.sha || '' }}
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable' && !inputs.pr_number
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
+        if: ${{ !inputs.pr_number }}
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"
@@ -141,6 +149,12 @@ jobs:
         # the packed tarball. Same step as PR CI.
         run: node tests/consumer-typecheck/package-shape-gate.mjs
 
+      - name: Legacy public no-growth gates (SD-3176)
+        # Same gate as PR CI. Catches releases that bypass PR CI.
+        run: |
+          node tests/consumer-typecheck/snapshot-super-editor-package-exports.mjs --check
+          node tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs --check
+
       # PR preview: publish with pr-<number> dist-tag
       - name: Publish PR preview
         if: inputs.pr_number

.github/workflows/release-template-builder.yml

@@ -19,9 +19,13 @@ permissions:
 concurrency:
   # Stable releases share the `release-stable` group so @semantic-release/git
   # pushes to `stable` serialize across workflows; per-workflow groups would
-  # let releases race on `git push origin stable`.
+  # let releases race on `git push origin stable`. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
+  # queue: max requires cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -39,8 +43,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

.github/workflows/release-vscode-ext.yml

@@ -28,9 +28,13 @@ permissions:
 concurrency:
   # Stable releases share the `release-stable` group so @semantic-release/git
   # pushes to `stable` serialize across workflows; per-workflow groups would
-  # let releases race on `git push origin stable`.
+  # let releases race on `git push origin stable`. queue: max keeps GitHub
+  # from dropping older pending stable releases when a stable push touches
+  # multiple wrapper packages; default queue: single only allows one pending.
+  # queue: max requires cancel-in-progress: false (cannot be combined with true).
   group: ${{ github.ref_name == 'stable' && 'release-stable' || format('{0}-{1}', github.workflow, github.ref) }}
-  cancel-in-progress: ${{ github.ref_name != 'stable' }}
+  cancel-in-progress: false
+  queue: max
 
 jobs:
   release:
@@ -50,8 +54,11 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Refresh stable branch head
-        if: github.ref_name == 'stable'
+      - name: Refresh branch head
+        # Queued release runs may start against a stale checkout (queue: max
+        # plus cancel-in-progress: false). Refresh to the current branch head
+        # so @semantic-release/git pushes fast-forward; semantic-release no-ops
+        # if no new commits were added since the previous queued run released.
         run: |
           git fetch origin "${{ github.ref_name }}" --tags
           git checkout -B "${{ github.ref_name }}" "origin/${{ github.ref_name }}"

apps/cli/.releaserc.cjs

@@ -33,6 +33,10 @@ const branches = [
 
 const isPrerelease = branches.some((b) => typeof b === 'object' && b.name === branch && b.prerelease);
 
+// stable -> main syncs (real merges) re-attribute prereleases to PRs already shipped on @latest.
+// Gate per-PR/issue success comments off on prereleases to avoid duplicate "shipped" comments.
+const shouldCommentOnRelease = !isPrerelease;
+
 // Use AI-powered notes for stable releases, conventional generator for prereleases
 const notesPlugin = isPrerelease ? createReleaseNotesGenerator() : ['semantic-release-ai-notes', { style: 'concise' }];
 
@@ -75,7 +79,7 @@ config.plugins.push([
   'semantic-release-linear-app',
   {
     teamKeys: ['SD'],
-    addComment: true,
+    addComment: shouldCommentOnRelease,
     packageName: 'superdoc-cli',
     commentTemplate: 'shipped in {package} {releaseLink} {channel}',
   },
@@ -86,6 +90,7 @@ config.plugins.push([
   {
     successComment:
       ':tada: This ${issue.pull_request ? "PR" : "issue"} is included in **superdoc-cli** v${nextRelease.version}\n\nThe release is available on [GitHub release](${releases.find(release => release.pluginName === "@semantic-release/github").url})',
+    successCommentCondition: shouldCommentOnRelease ? undefined : false,
   },
 ]);
 

apps/create/.releaserc.cjs

@@ -13,6 +13,10 @@ const branches = [
 
 const isPrerelease = branches.some((b) => typeof b === 'object' && b.name === branch && b.prerelease);
 
+// stable -> main syncs (real merges) re-attribute prereleases to PRs already shipped on @latest.
+// Gate per-PR/issue success comments off on prereleases to avoid duplicate "shipped" comments.
+const shouldCommentOnRelease = !isPrerelease;
+
 const notesPlugin = isPrerelease ? createReleaseNotesGenerator() : ['semantic-release-ai-notes', { style: 'concise' }];
 
 const config = {
@@ -35,7 +39,7 @@ config.plugins.push([
   'semantic-release-linear-app',
   {
     teamKeys: ['SD'],
-    addComment: true,
+    addComment: shouldCommentOnRelease,
     packageName: 'create',
     commentTemplate: 'shipped in {package} {releaseLink} {channel}',
   },
@@ -46,6 +50,7 @@ config.plugins.push([
   {
     successComment:
       ':tada: This ${issue.pull_request ? "PR" : "issue"} is included in **@superdoc-dev/create** v${nextRelease.version}\n\nThe release is available on [GitHub release](${releases.find(release => release.pluginName === "@semantic-release/github").url})',
+    successCommentCondition: shouldCommentOnRelease ? undefined : false,
   },
 ]);