Merge main into stable

.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

@@ -6,17 +6,6 @@ permissions:
 on:
   pull_request:
     branches: [main, stable]
-    paths:
-      - 'packages/superdoc/**'
-      - 'packages/layout-engine/**'
-      - 'packages/super-editor/**'
-      - 'packages/ai/**'
-      - 'packages/word-layout/**'
-      - 'packages/preset-geometry/**'
-      - 'tests/behavior/**'
-      - 'shared/**'
-      - '.github/workflows/ci-behavior.yml'
-      - '!**/*.md'
   merge_group:
   workflow_dispatch:
 
@@ -30,7 +19,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        browser: [chromium, firefox, webkit]
+        # PRs run chromium only for fast feedback. merge_group and workflow_dispatch
+        # run the full 3-browser matrix before anything lands on main.
+        browser: ${{ fromJSON(github.event_name == 'pull_request' && '["chromium"]' || '["chromium", "firefox", "webkit"]') }}
         shard: [1, 2, 3, 4]
     steps:
       - uses: actions/checkout@v6
@@ -75,12 +66,14 @@ jobs:
         working-directory: tests/behavior
 
   validate:
+    name: Behavior Tests / validate
     if: always()
     needs: [test]
     runs-on: ubuntu-latest
     steps:
       - name: Check results
         run: |
-          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}" == "true" ]]; then
+            echo "One or more required jobs did not succeed."
             exit 1
           fi

.github/workflows/ci-demos.yml

@@ -84,12 +84,14 @@ jobs:
         run: DEMO=${{ matrix.demo }} npx playwright test
 
   validate:
+    name: CI Demos / validate
     if: always()
     needs: [smoke-test]
     runs-on: ubuntu-latest
     steps:
       - name: Check results
         run: |
-          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}" == "true" ]]; then
+            echo "One or more required jobs did not succeed."
             exit 1
           fi

.github/workflows/ci-docs.yml

@@ -15,6 +15,7 @@ on:
 
 jobs:
   validate:
+    name: CI Docs / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

.github/workflows/ci-document-api.yml

@@ -19,6 +19,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI Document API / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-esign.yml

@@ -16,6 +16,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI eSign / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

.github/workflows/ci-examples.yml

@@ -172,12 +172,14 @@ jobs:
         run: npx tsx src/index.test.ts
 
   validate:
+    name: CI Examples / validate
     if: always()
     needs: [getting-started, collaboration, features, advanced-headless-toolbar, headless]
     runs-on: ubuntu-latest
     steps:
       - name: Check results
         run: |
-          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}" == "true" ]]; then
+            echo "One or more required jobs did not succeed."
             exit 1
           fi

.github/workflows/ci-mcp.yml

@@ -16,6 +16,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI MCP / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-react.yml

@@ -16,6 +16,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI React / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-sdk.yml

@@ -22,6 +22,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI SDK / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/ci-superdoc.yml

@@ -16,6 +16,7 @@ on:
       - 'packages/sdk/**'
       - 'packages/template-builder/**'
       - 'packages/esign/**'
+      - 'packages/ai/**'
       - 'evals/**'
       - '**/*.md'
   merge_group:
@@ -40,7 +41,7 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.12
+          bun-version: 1.3.13
 
       - name: Install canvas system dependencies
         run: |
@@ -108,7 +109,7 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.12
+          bun-version: 1.3.13
 
       - name: Install canvas system dependencies
         run: |
@@ -195,7 +196,7 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.12
+          bun-version: 1.3.13
 
       - name: Install dependencies
         run: pnpm install
@@ -232,12 +233,14 @@ jobs:
           flags: superdoc
 
   validate:
+    name: CI SuperDoc / validate
     if: always()
     needs: [build, unit-tests, cli-tests, coverage]
     runs-on: ubuntu-latest
     steps:
       - name: Check results
         run: |
-          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
+          if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}" == "true" ]]; then
+            echo "One or more required jobs did not succeed."
             exit 1
           fi

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

@@ -16,6 +16,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI Template Builder / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v6

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

@@ -17,6 +17,7 @@ concurrency:
 
 jobs:
   validate:
+    name: CI VS Code Extension / validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4