ci: align release and CI triggers with package impact map (#2938)

* ci: align release and CI triggers with package impact map

Test broad, release narrow. CI gates compatibility (a core change should
run dependent CI to catch breakage). Release gates artifact changes (a
package should only publish when its own published artifact actually
changes).

- Shrink release-react, release-template-builder, release-esign and
  their .releaserc.cjs to own-path-only. These wrappers externalize
  superdoc in their Vite builds, so republishing on core changes
  produces near-identical tarballs; consumers pick up core via
  peerDependencies on their own install.

- Expand release-mcp trigger paths and .releaserc.cjs to cover SDK,
  CLI, document-api, and core. MCP depends on SDK via workspace:* and
  imports engine/session code directly. Current trigger only watched
  apps/mcp/**, causing MCP to lag SDK releases.

- Strip packages/ai/** from every workflow and .releaserc.cjs include
  list. @superdoc-dev/ai is being deprecated; npm-side deprecation is
  a separate operational step.

- Add .github/package-impact-map.md as the source of truth for which
  paths should trigger CI and release per surface. Workflow changes
  derive from it.

* ci(react): keep release broad - superdoc is a regular dep, not peer

React declares superdoc in dependencies (">=1.0.0") rather than
peerDependencies, unlike template-builder and esign. That means
existing consumers with pinned lockfiles won't pick up a new core
version until react republishes. Shrinking release-react to own paths
would strand them on old core fixes.

Revert release-react to broad core paths and restore the minor-cap
release rules. The impact-map rationale now distinguishes react from
the peer-dep wrappers and calls out the future peer-dep migration as
the prerequisite for going narrow.

No breaking change to consumers; migration to peerDependencies is
tracked as a separate decision.

* chore(react): dual-list superdoc as dep and peer for singleton signal

Add superdoc to peerDependencies while keeping it in dependencies.
Preserves auto-install for every consumer regardless of package
manager (no breaking change) and signals the singleton contract that
template-builder and esign already express via peer-dep.

This is a semantic cleanup, not a release-policy change. release-react
stays broad because existing consumers still pick up core versions
via the dependencies pin. Removing superdoc from dependencies would
unlock release-narrow but is a breaking change tracked separately.

Verified with pnpm install --frozen-lockfile — no lockfile changes.

* ci: ignore packages/ai/** in ci-superdoc paths-ignore

Review found ci-superdoc uses paths-ignore and did not list
packages/ai/**, so an AI-only PR still triggered the full SuperDoc CI
despite ai being deprecated. Add it to paths-ignore to match the
impact-map claim that ai is removed from all release and CI triggers.

Author: caio-pizzol

.github/package-impact-map.md

@@ -0,0 +1,66 @@
+# Package impact map
+
+Source of truth for which repo paths should trigger CI and release workflows for each published surface.
+
+## Principle
+
+**Test broad, release narrow.**
+
+- **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.
+
+## Surfaces
+
+| Surface | Purpose | Release impact | CI impact |
+|---|---|---|---|
+| `superdoc` | Main browser DOCX editor/runtime | core | core |
+| `@superdoc-dev/react` | React wrapper around superdoc | react + core (see note below) | react + core |
+| `@superdoc-dev/template-builder` | React SDT/template authoring UI | `packages/template-builder/**` only | template-builder + core |
+| `@superdoc-dev/esign` | React signing workflow | `packages/esign/**` only | esign + core |
+| `@superdoc-dev/cli` | Native Document API CLI | cli + doc-api + core | same |
+| `@superdoc-dev/sdk` | JS/Python SDK packaging CLI binaries | sdk + cli + doc-api + core | same |
+| `@superdoc-dev/mcp` | MCP server over SDK/document engine | mcp + sdk + cli + doc-api + core | same |
+| `superdoc-vscode-ext` | VS Code DOCX editor | vscode-ext + core | same |
+| `@superdoc-dev/create` | Project scaffolder | `apps/create/**` only | own changes only |
+| `@superdoc-dev/superdoc-yjs-collaboration` | Standalone Yjs server (no SuperDoc dep) | `packages/collaboration-yjs/**` only | own changes + collaboration examples |
+| `@superdoc/docs` (private) | Documentation site | N/A (not published) | docs + public API / doc generation |
+| demos, examples (private) | Compatibility samples | N/A (not published) | own paths + relevant upstream runtime |
+
+## Path expansions
+
+**core** expands to:
+- `packages/superdoc/**`
+- `packages/super-editor/**`
+- `packages/layout-engine/**`
+- `packages/word-layout/**`
+- `packages/preset-geometry/**`
+- `shared/**`
+- `pnpm-workspace.yaml`
+
+**doc-api** is `packages/document-api/**`.
+
+**cli** is `apps/cli/**`.
+
+**sdk** is `packages/sdk/**`.
+
+**mcp**, **vscode-ext**, **create** are their respective `apps/*/**` or `packages/*/**` paths.
+
+## 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.
+- **`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.
+- **VS Code extension** packages SuperDoc into the extension VSIX. Treated like CLI/SDK.
+- **collaboration-yjs** has no SuperDoc dependency. It's a standalone Yjs server. Release and CI both narrow.
+- **create** is a scaffolder with no dependencies on SuperDoc runtime. Release and CI both narrow.
+- **docs, demos, examples** are not published. They get CI on changes to anything they render to catch visual or behavior regressions.
+
+## 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 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/ci-behavior.yml

@@ -10,7 +10,6 @@ on:
       - 'packages/superdoc/**'
       - 'packages/layout-engine/**'
       - 'packages/super-editor/**'
-      - 'packages/ai/**'
       - 'packages/word-layout/**'
       - 'packages/preset-geometry/**'
       - 'tests/behavior/**'

.github/workflows/ci-superdoc.yml

@@ -16,6 +16,7 @@ on:
       - 'packages/sdk/**'
       - 'packages/template-builder/**'
       - 'packages/esign/**'
+      - 'packages/ai/**'
       - 'evals/**'
       - '**/*.md'
   merge_group:

.github/workflows/release-cli.yml

@@ -14,7 +14,6 @@ on:
       - 'packages/superdoc/**'
       - 'packages/super-editor/**'
       - 'packages/layout-engine/**'
-      - 'packages/ai/**'
       - 'packages/word-layout/**'
       - 'packages/preset-geometry/**'
       - 'shared/**'

.github/workflows/release-esign.yml

@@ -8,13 +8,6 @@ on:
       - main
     paths:
       - 'packages/esign/**'
-      - 'packages/superdoc/**'
-      - 'packages/layout-engine/**'
-      - 'packages/super-editor/**'
-      - 'packages/ai/**'
-      - 'packages/word-layout/**'
-      - 'packages/preset-geometry/**'
-      - 'shared/**'
       - 'pnpm-workspace.yaml'
       - '!**/*.md'
   workflow_dispatch:

.github/workflows/release-mcp.yml

@@ -7,7 +7,19 @@ on:
     branches:
       - main
     paths:
+      # MCP depends on SDK (workspace:*) and imports engine/session code directly.
+      # Keep in sync with apps/mcp/.releaserc.cjs include list and
+      # .github/package-impact-map.md.
       - 'apps/mcp/**'
+      - 'packages/sdk/**'
+      - 'apps/cli/**'
+      - 'packages/document-api/**'
+      - 'packages/superdoc/**'
+      - 'packages/super-editor/**'
+      - 'packages/layout-engine/**'
+      - 'packages/word-layout/**'
+      - 'packages/preset-geometry/**'
+      - 'shared/**'
       - 'pnpm-workspace.yaml'
       - '!**/*.md'
   workflow_dispatch:

.github/workflows/release-react.yml

@@ -7,11 +7,14 @@ on:
     branches:
       - main
     paths:
+      # React declares `superdoc` in dependencies (not peerDependencies), so
+      # existing consumers with lockfiles won't pick up a new core version
+      # until react republishes. Keep release broad until the peer-dep
+      # migration lands (tracked separately). See .github/package-impact-map.md.
       - 'packages/react/**'
       - 'packages/superdoc/**'
       - 'packages/layout-engine/**'
       - 'packages/super-editor/**'
-      - 'packages/ai/**'
       - 'packages/word-layout/**'
       - 'packages/preset-geometry/**'
       - 'shared/**'

.github/workflows/release-sdk.yml

@@ -15,7 +15,6 @@ on:
       - 'packages/superdoc/**'
       - 'packages/super-editor/**'
       - 'packages/layout-engine/**'
-      - 'packages/ai/**'
       - 'packages/word-layout/**'
       - 'packages/preset-geometry/**'
       - 'shared/**'

.github/workflows/release-superdoc.yml

@@ -11,7 +11,6 @@ on:
       - 'packages/superdoc/**'
       - 'packages/layout-engine/**'
       - 'packages/super-editor/**'
-      - 'packages/ai/**'
       - 'packages/word-layout/**'
       - 'packages/preset-geometry/**'
       - 'shared/**'

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

@@ -8,13 +8,6 @@ on:
       - main
     paths:
       - 'packages/template-builder/**'
-      - 'packages/superdoc/**'
-      - 'packages/layout-engine/**'
-      - 'packages/super-editor/**'
-      - 'packages/ai/**'
-      - 'packages/word-layout/**'
-      - 'packages/preset-geometry/**'
-      - 'shared/**'
       - 'pnpm-workspace.yaml'
       - '!**/*.md'
   workflow_dispatch: