Sync stable into main

.github/package-impact-map.md

@@ -9,7 +9,7 @@ Source of truth for which repo paths should trigger CI and release workflows for
 - **CI gates compatibility.** A change to SuperDoc core should run the CI of every dependent package — that's how breakage in `@superdoc-dev/react` or `@superdoc-dev/sdk` gets caught before it ships. CI paths follow *compatibility* impact.
 - **Release gates artifact changes.** A package should only publish a new version when its own published artifact actually changes. Release paths follow *artifact* impact.
 
-These two are not the same. `template-builder` and `esign` externalize `superdoc` in their builds and declare it as a `peerDependency`, so a core change doesn't change their tarballs → CI broad, release narrow. CLI bundles core into platform binaries, so a core change does change the CLI tarball → both broad.
+These two are not the same. `template-builder` and `esign` externalize `superdoc` in their builds and declare it as both a dependency and peer dependency, so a core change inside the declared range doesn't change their tarballs → CI broad, release narrow. CLI bundles core into platform binaries, so a core change does change the CLI tarball → both broad.
 
 ## Surfaces
 
@@ -49,7 +49,7 @@ These two are not the same. `template-builder` and `esign` externalize `superdoc
 
 ## Why each classification
 
-- **`template-builder` and `esign`** externalize `superdoc` in their Vite build (`rollupOptions.external`) and declare it as a `peerDependency`. A SuperDoc core change does not change the wrapper's published bundle — consumers receive the new core through their own `npm install`. Release-on-core is pure version noise; CI-on-core remains necessary to catch breaking API changes.
+- **`template-builder` and `esign`** externalize `superdoc` in their Vite build (`rollupOptions.external`) and declare it in **both** `dependencies` and `peerDependencies`. The `dependencies` entry preserves auto-install for customers who use the wrapper as their SuperDoc entrypoint; the `peerDependencies` entry signals the singleton contract for apps that also install SuperDoc directly. A SuperDoc core change inside the declared range does not change the wrapper's published bundle or manifest, so release-on-core is pure version noise; CI-on-core remains necessary to catch breaking API changes.
 - **`react`** externalizes `superdoc` in its Vite build the same way, and declares `superdoc` in **both** `dependencies` and `peerDependencies`. The `dependencies` entry preserves auto-install for every consumer (zero-break regardless of package manager); the `peerDependencies` entry signals the singleton contract and aligns the manifest with template-builder/esign. Because the `dependencies` entry still pins via lockfiles, existing consumers only pick up a new core version when react republishes, so release-on-core stays correct *today*. The unlock for release-narrow is to remove `superdoc` from `dependencies` entirely — that is a breaking change and tracked as a separate decision.
 - **CLI / SDK** bundle engine behavior into platform-specific native binaries (see `apps/cli/.releaserc.cjs` and `packages/sdk/.releaserc.cjs` — both use `patch-commit-filter.cjs` to expand release analysis into core paths). The published artifact genuinely changes when core changes.
 - **MCP** depends on SDK via `workspace:*` and imports engine/session code directly. Its current release trigger (`apps/mcp/**` only) causes it to lag SDK releases. Expand to match SDK's release paths.
@@ -61,6 +61,6 @@ These two are not the same. `template-builder` and `esign` externalize `superdoc
 ## Notes
 
 - `packages/ai/**` has been removed from all release and CI triggers. `@superdoc-dev/ai` is being deprecated; npm-side deprecation is a separate operational step.
-- When SuperDoc core ships a breaking API change, `template-builder` and `esign` must be manually updated and released. Their `peerDependencies` version bump is the signal; semantic-release won't auto-trigger on upstream changes for them.
-- `@superdoc-dev/react` declares `superdoc` in both `dependencies` and `peerDependencies` to preserve zero-break install semantics while still signaling the singleton contract. Removing `superdoc` from `dependencies` is the unlock for release-narrow and is tracked as a separate decision.
+- When SuperDoc core ships a breaking API change, `template-builder` and `esign` must be manually updated and released. Their dependency and peer-dependency floor bump is the signal; semantic-release won't auto-trigger on upstream changes for them.
+- `@superdoc-dev/react`, `@superdoc-dev/template-builder`, and `@superdoc-dev/esign` declare `superdoc` in both `dependencies` and `peerDependencies` to preserve automatic install semantics while still signaling the singleton contract. Removing `superdoc` from `dependencies` is the unlock for release-narrow and is tracked as a separate decision.
 - When editing a release or CI workflow, its `paths:` filter must match the corresponding row in this map. Workflow-lint rules should enforce this.

.github/workflows/promote-stable.yml

@@ -31,9 +31,6 @@ jobs:
         with:
           app-id: ${{ secrets.APP_ID }}
           private-key: ${{ secrets.APP_PRIVATE_KEY }}
-          permission-contents: write
-          permission-pull-requests: write
-          permission-workflows: write
 
       - uses: actions/checkout@v6
         with:
@@ -71,19 +68,60 @@ jobs:
           if git merge --no-ff --no-edit "origin/${SOURCE_BRANCH}"; then
             MERGE_STATUS="clean"
           else
-            # Auto-resolve release artifact conflicts: keep stable's version.
+            normalize_json_without_keys() {
+              python3 -c 'import json, sys; data = json.load(sys.stdin); [data.pop(key, None) for key in sys.argv[1:]]; sys.stdout.write(json.dumps(data, sort_keys=True, separators=(",", ":")))' "$@"
+            }
+
+            release_artifact_only_conflict() {
+              local f="$1"
+              local tmpdir
+              local status
+              tmpdir="$(mktemp -d)"
+
+              case "$f" in
+                package.json|*/package.json)
+                  git show ":2:${f}" | normalize_json_without_keys version > "${tmpdir}/ours" || { rm -rf "${tmpdir}"; return 1; }
+                  git show ":3:${f}" | normalize_json_without_keys version > "${tmpdir}/theirs" || { rm -rf "${tmpdir}"; return 1; }
+                  ;;
+                pyproject.toml|*/pyproject.toml)
+                  git show ":2:${f}" | sed -E '/^[[:space:]]*version[[:space:]]*=/d' > "${tmpdir}/ours" || { rm -rf "${tmpdir}"; return 1; }
+                  git show ":3:${f}" | sed -E '/^[[:space:]]*version[[:space:]]*=/d' > "${tmpdir}/theirs" || { rm -rf "${tmpdir}"; return 1; }
+                  ;;
+                version.json|*/version.json)
+                  git show ":2:${f}" | normalize_json_without_keys version sdkVersion > "${tmpdir}/ours" || { rm -rf "${tmpdir}"; return 1; }
+                  git show ":3:${f}" | normalize_json_without_keys version sdkVersion > "${tmpdir}/theirs" || { rm -rf "${tmpdir}"; return 1; }
+                  ;;
+                *)
+                  rm -rf "${tmpdir}"
+                  return 1
+                  ;;
+              esac
+
+              cmp -s "${tmpdir}/ours" "${tmpdir}/theirs"
+              status=$?
+              rm -rf "${tmpdir}"
+              return "${status}"
+            }
+
+            # Auto-resolve release artifact conflicts only when the conflict is
+            # version-only: keep stable's version, but never drop dependency,
+            # script, export, or package metadata changes from main.
             # npm/PyPI already have stable's published version; downgrading to
             # main's track would break the next stable release. Mirrors the
             # auto-resolve in sync-patches.yml, biased the other direction.
-            git diff --name-only --diff-filter=U | while read -r f; do
+            while read -r f; do
               case "$f" in
                 package.json|*/package.json|pyproject.toml|*/pyproject.toml|version.json|*/version.json)
-                  echo "  Auto-resolving $f (keeping stable's version)"
-                  git checkout --ours "$f"
-                  git add "$f"
+                  if release_artifact_only_conflict "$f"; then
+                    echo "  Auto-resolving $f (version-only; keeping stable's version)"
+                    git checkout --ours "$f"
+                    git add "$f"
+                  else
+                    echo "  Leaving $f unresolved (contains non-version changes)"
+                  fi
                   ;;
               esac
-            done
+            done < <(git diff --name-only --diff-filter=U)
 
             if [ -z "$(git diff --name-only --diff-filter=U)" ]; then
               MERGE_STATUS="auto_resolved"
@@ -141,7 +179,7 @@ jobs:
 
           - creates \`${BRANCH_NAME}\` from \`${BASE_BRANCH}\`
           - merges \`${SOURCE_BRANCH}\` into the candidate branch
-          - release artifact conflicts (package.json, pyproject.toml, version.json) auto-resolved to keep stable's published version
+          - version-only release artifact conflicts (package.json, pyproject.toml, version.json) auto-resolved to keep stable's published version
 
           ---
           _Auto-created by promote-stable workflow._

.github/workflows/release-react.yml

@@ -40,6 +40,8 @@ concurrency:
 
 jobs:
   release:
+    # Stable publishes must go through release-stable.yml.
+    if: ${{ github.event_name != 'workflow_dispatch' || github.ref_name != 'stable' }}
     runs-on: ubuntu-24.04
     steps:
       - name: Generate token

.github/workflows/release-superdoc.yml

@@ -44,6 +44,8 @@ concurrency:
 
 jobs:
   release:
+    # Stable publishes must go through release-stable.yml; PR previews are still allowed.
+    if: ${{ github.event_name != 'workflow_dispatch' || github.ref_name != 'stable' || inputs.pr_number }}
     runs-on: ubuntu-24.04
     steps:
       - name: Generate token

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

@@ -38,6 +38,8 @@ concurrency:
 
 jobs:
   release:
+    # Stable publishes must go through release-stable.yml.
+    if: ${{ github.event_name != 'workflow_dispatch' || github.ref_name != 'stable' }}
     runs-on: ubuntu-latest
     steps:
       - name: Generate token

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "type": "module",
   "bin": {
     "superdoc": "./dist/index.js"

apps/cli/platforms/cli-darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli-darwin-arm64",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "os": [
     "darwin"
   ],

apps/cli/platforms/cli-darwin-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli-darwin-x64",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "os": [
     "darwin"
   ],

apps/cli/platforms/cli-linux-arm64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli-linux-arm64",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "os": [
     "linux"
   ],

apps/cli/platforms/cli-linux-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli-linux-x64",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "os": [
     "linux"
   ],

apps/cli/platforms/cli-windows-x64/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/cli-windows-x64",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "os": [
     "win32"
   ],

apps/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/mcp",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "type": "module",
   "engines": {
     "node": ">=20"

apps/vscode-ext/package.json

@@ -2,7 +2,7 @@
   "name": "superdoc-vscode-ext",
   "displayName": "SuperDoc - Word Document Editor",
   "description": "Open and edit Word documents (.docx) directly in VS Code using SuperDoc",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "publisher": "superdoc-dev",
   "icon": "logo.png",
   "homepage": "https://superdoc.dev",