Merge main into stable

.github/workflows/ci-behavior.yml

@@ -66,7 +66,7 @@ jobs:
         # detect gate above. When the suite does run, exercise all 3 browsers
         # so cross-browser regressions are caught at PR time.
         browser: [chromium, firefox, webkit]
-        shard: [1, 2, 3, 4, 5]
+        shard: [1, 2, 3, 4, 5, 6]
     steps:
       - uses: actions/checkout@v6
 
@@ -105,8 +105,8 @@ jobs:
         run: pnpm exec playwright install-deps ${{ matrix.browser }}
         working-directory: tests/behavior
 
-      - name: Run behavior tests (${{ matrix.browser }} shard ${{ matrix.shard }}/5)
-        run: pnpm exec playwright test --project=${{ matrix.browser }} --shard=${{ matrix.shard }}/5
+      - name: Run behavior tests (${{ matrix.browser }} shard ${{ matrix.shard }}/6)
+        run: pnpm exec playwright test --project=${{ matrix.browser }} --shard=${{ matrix.shard }}/6
         working-directory: tests/behavior
 
   validate:

.github/workflows/ci-demos.yml

@@ -59,16 +59,11 @@ jobs:
           - contract-templates
           - custom-ui
           - docx-from-html
-          - docxtemplater
-          - fields
+          - fields-source
           - grading-papers
           # - html-editor  # broken: imports unpublished superdoc/super-editor/style.css subpath
           - linked-sections
-          - loading-from-json
           - nextjs-ssr
-          # - replace-content  # broken: runtime nextSibling error in SuperDoc
-          - text-selection
-          - toolbar
     steps:
       - name: Restore workspace
         uses: actions/cache/restore@v4

.github/workflows/ci-examples.yml

@@ -57,7 +57,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [react, vue, vanilla, cdn, angular, nuxt, laravel]
+        example: [react, vue, vanilla, cdn, angular, nuxt, laravel, solid]
     steps:
       - name: Restore workspace
         uses: actions/cache/restore@v4

.github/workflows/ci-superdoc.yml

@@ -120,32 +120,20 @@ jobs:
         # tree (those are tracked under SD-2863 follow-up tickets).
         run: pnpm --filter superdoc run check:jsdoc
 
-      - name: Consumer typecheck (matrix)
-        # The matrix script owns the published-package validation path:
-        # it packs superdoc, installs the tarball into the standalone
-        # fixture (`pnpm install --ignore-workspace`), then runs every
-        # scenario under its declared resolution mode and strictness
-        # settings. Replaces the pre-SD-2831 bare `tsc --noEmit` step
-        # so the new pack-and-install scenarios are actually exercised
-        # in CI, not just locally.
-        run: |
-          cd tests/consumer-typecheck
-          node typecheck-matrix.mjs
-
-      - name: Deep public-type audit (report-only)
-        # Recursive walk of every type reachable from superdoc's public
-        # exports in the installed tarball. Reports inventory by tier and
-        # top files. Always exits 0 in default mode; the `--strict` flag
-        # turns it into a hard gate but is not used in CI yet because the
-        # current public surface is the accidental declaration graph, not
-        # a deliberate facade. SD-2966 will define that facade; once it
-        # lands, this step gets `--strict` added and an allowlist file is
-        # seeded against the facade-scoped findings. Until then, the step
-        # provides visibility without the maintenance burden of a giant
-        # public allowlist.
-        run: |
-          cd tests/consumer-typecheck
-          node deep-type-audit.mjs
+      - name: Public-contract check (matrix + supported-root strict audit)
+        # SD-673 Phase 1: collapse the previous two CI steps
+        # ('Consumer typecheck (matrix)' + 'Deep public-type audit') into
+        # the single wrapper command. Same coverage:
+        #   - typecheck-matrix.mjs packs superdoc, installs the tarball
+        #     into the consumer fixture, runs every scenario.
+        #   - deep-type-audit.mjs --strict-supported-root reuses that
+        #     install and gates on the supported-root any allowlist
+        #     (SD-3213e). Broad inventory still printed for visibility.
+        # --skip-build because the Build step above already ran
+        # `pnpm run build` (which includes build:superdoc).
+        # Local equivalent: `pnpm check:public-contract` (with the build
+        # stage included).
+        run: pnpm check:public-contract --skip-build
 
       - name: Package shape gates
         # External package-shape linters (publint + attw) running against
@@ -154,14 +142,24 @@ 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
+      - name: Public surface no-growth snapshots (SD-3176, SD-3212)
+        # Unified entry point for the three snapshot families:
+        #   - super-editor-package: @superdoc/super-editor package.json#exports keys
+        #   - legacy: resolved exports for superdoc/* legacy subpaths
+        #   - root: 4-source inventory (types.import, types.require, import,
+        #     require) for the superdoc root entry. Cross-source mismatches
+        #     are reported in the companion .md but are not blockers on their
+        #     own.
+        # Runs after the matrix step so the packed-and-installed fixture is
+        # available. See tests/consumer-typecheck/snapshots/README.md.
+        run: node tests/consumer-typecheck/snapshot.mjs --all --check
+
+      - name: Root classification closure gate (SD-3212 PR A1b)
+        # Asserts the dependency-closure rule from the A1 classification:
+        # no supported-root or legacy-root exported root symbol may reference
+        # an internal-candidate root symbol in its public declared type.
+        # Catches the failure class behind Phase 4a's 31-failure dry-run.
+        run: node tests/consumer-typecheck/check-root-classification-closure.mjs
 
   unit-tests:
     needs: build

.github/workflows/promote-stable-docs.yml

@@ -1,10 +1,11 @@
 # Advances docs-stable to the current stable HEAD (or a chosen SHA).
 #
 # Auto path (workflow_run): release-stable.yml is the orchestrator that
-# releases superdoc on stable, so we trigger off its completion and gate on
-# whether a real v* tag appeared between the triggering run's head_sha and
-# origin/stable. Tools-only runs (CLI/SDK/MCP without a superdoc release)
-# leave docs-stable unchanged - no new v* tag, no push.
+# releases superdoc on stable, so we trigger off its completion, wait for the
+# shared stable release lane to settle, and gate on whether a real v* tag
+# appeared between the triggering run's head_sha and origin/stable. Tools-only
+# runs (CLI/SDK/MCP without a superdoc release) leave docs-stable unchanged -
+# no new v* tag, no push.
 #
 # We accept conclusion: failure as well as success because the orchestrator
 # runs chains independently. A tools-chain failure that follows a successful
@@ -60,6 +61,43 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
+      - name: Wait for stable release lane to drain
+        if: github.event_name == 'workflow_run'
+        env:
+          GH_TOKEN: ${{ steps.generate_token.outputs.token }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+
+          deadline=$((SECONDS + 1800))
+          while true; do
+            active_runs=$(gh run list \
+              --repo "$REPO" \
+              --branch stable \
+              --limit 100 \
+              --json databaseId,name,status,url \
+              --jq '[.[] | select((.name == "📦 Release stable tooling (CLI/SDK/MCP)" or .name == "📦 Release esign" or .name == "📦 Release template-builder") and .status != "completed")] | length')
+
+            if [ "$active_runs" -eq 0 ]; then
+              echo "Stable release lane is idle."
+              break
+            fi
+
+            if [ "${SECONDS}" -ge "${deadline}" ]; then
+              echo "Timed out waiting for stable release lane to drain."
+              gh run list \
+                --repo "$REPO" \
+                --branch stable \
+                --limit 100 \
+                --json databaseId,name,status,url \
+                --jq '.[] | select((.name == "📦 Release stable tooling (CLI/SDK/MCP)" or .name == "📦 Release esign" or .name == "📦 Release template-builder") and .status != "completed") | "\(.databaseId)\t\(.name)\t\(.status)\t\(.url)"'
+              exit 1
+            fi
+
+            echo "Waiting for ${active_runs} stable release run(s) to finish..."
+            sleep 30
+          done
+
       # Auto path: gate on a real SuperDoc release between the triggering
       # run's head_sha and origin/stable. A no-op semantic-release run must
       # not advance docs-stable.
@@ -108,25 +146,46 @@ jobs:
 
       - name: Push docs-stable (auto)
         if: github.event_name == 'workflow_run' && steps.detect.outputs.released == 'true'
-        run: git push origin "refs/remotes/origin/stable:refs/heads/docs-stable"
+        run: |
+          set -euo pipefail
+          git fetch origin stable docs-stable --tags --force
+
+          docs_only_commits=$(git log --oneline origin/stable..origin/docs-stable -- apps/docs/ || true)
+          if [ -n "${docs_only_commits}" ]; then
+            echo "docs-stable has docs changes that are not on stable; refusing to overwrite:"
+            echo "${docs_only_commits}"
+            exit 1
+          fi
+
+          target=$(git rev-parse origin/stable)
+          expected=$(git rev-parse origin/docs-stable)
+          echo "Promoting ${target} to docs-stable with lease ${expected}."
+          git push --force-with-lease=refs/heads/docs-stable:"${expected}" origin "${target}:refs/heads/docs-stable"
 
       # Manual path: trust the operator. Promote either the requested SHA
-      # or the current origin/stable head. The push is rejected by GitHub
-      # if it isn't a fast-forward, so this stays safe even on operator
-      # error - no `--force`.
+      # or the current origin/stable head, while still using a lease so we
+      # never overwrite a concurrently updated docs-stable branch.
       - name: Push docs-stable (manual)
         if: github.event_name == 'workflow_dispatch'
         env:
           REQUESTED_SHA: ${{ inputs.sha }}
         run: |
           set -euo pipefail
-          git fetch origin stable --tags --force
+          git fetch origin stable docs-stable --tags --force
 
           if [ -n "${REQUESTED_SHA}" ]; then
             target="${REQUESTED_SHA}"
           else
             target=$(git rev-parse origin/stable)
           fi
 
-          echo "Promoting ${target} to docs-stable."
-          git push origin "${target}:refs/heads/docs-stable"
+          docs_only_commits=$(git log --oneline "${target}"..origin/docs-stable -- apps/docs/ || true)
+          if [ -n "${docs_only_commits}" ]; then
+            echo "docs-stable has docs changes that are not on ${target}; refusing to overwrite:"
+            echo "${docs_only_commits}"
+            exit 1
+          fi
+
+          expected=$(git rev-parse origin/docs-stable)
+          echo "Promoting ${target} to docs-stable with lease ${expected}."
+          git push --force-with-lease=refs/heads/docs-stable:"${expected}" origin "${target}:refs/heads/docs-stable"