Merge branch 'main' into stable

Author: harbournick

.github/scripts/package-lock.json

@@ -31,9 +31,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Generate SDK artifacts
+        run: pnpm run generate:all
+
       - name: Build superdoc (dependency)
         run: pnpm run build:superdoc
 
+      - name: Build SDK (dependency)
+        run: pnpm --prefix packages/sdk/langs/node run build
+
       - name: Build
         run: pnpm --prefix apps/mcp run build
 

.github/workflows/ci-mcp.yml

@@ -35,7 +35,7 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.9
+          bun-version: 1.3.10
 
       - name: Install canvas system dependencies
         run: |
@@ -77,6 +77,9 @@ jobs:
       - name: Run slow tests
         run: pnpm test:slow
 
+      - name: Consumer typecheck (skipLibCheck off)
+        run: bash packages/superdoc/tests/consumer-types/run.sh
+
       - name: Install Playwright for UMD smoke test
         run: pnpm --filter @superdoc/umd-smoke-test exec playwright install --with-deps chromium
 
@@ -98,7 +101,7 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.9
+          bun-version: 1.3.10
 
       - name: Install dependencies
         run: pnpm install

.github/workflows/ci-superdoc.yml

@@ -48,9 +48,15 @@ jobs:
       - name: Install dependencies
         run: pnpm install
 
+      - name: Generate SDK artifacts
+        run: pnpm run generate:all
+
       - name: Build superdoc (dependency)
         run: pnpm run build:superdoc
 
+      - name: Build SDK (dependency)
+        run: pnpm --prefix packages/sdk/langs/node run build
+
       - name: Build MCP server
         run: pnpm --prefix apps/mcp run build
 

.github/workflows/release-mcp.yml

@@ -1,7 +1,9 @@
-name: 🔄 Sync Patches [disabled]
+name: 🔄 Sync stable → main
 
 on:
-  # Disabled to stop automatic PRs syncing stable/*.x back to main.
+  push:
+    branches:
+      - stable
   workflow_dispatch:
 
 permissions:
@@ -10,9 +12,9 @@ permissions:
 
 jobs:
   sync-to-main:
-    # Short-circuit to fully disable the workflow.
-    if: ${{ false }}
     runs-on: ubuntu-latest
+    # Skip release commits (chore(release): ... [skip ci]) to avoid noisy no-op PRs
+    if: "!contains(github.event.head_commit.message, '[skip ci]') || github.event_name == 'workflow_dispatch'"
 
     steps:
       - name: Generate token
@@ -27,31 +29,109 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.generate_token.outputs.token }}
 
-      - name: Create sync PR
+      - name: Sync stable into main
         env:
           GH_TOKEN: ${{ steps.generate_token.outputs.token }}
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
 
-          # Create patch branch
-          PATCH_BRANCH="sync-patch-${{ github.sha }}"
-          git checkout -b "$PATCH_BRANCH" origin/main
+          SYNC_BRANCH="sync/stable-to-main-$(date +%Y%m%d-%H%M%S)"
+          git checkout -b "$SYNC_BRANCH" origin/main
+
+          # Merge stable into the branch
+          if git merge origin/stable --no-edit -m "chore: merge stable into main"; then
+            # Check if there are actually new commits to sync
+            if git diff --quiet origin/main; then
+              echo "No changes to sync — stable and main are already in sync."
+              exit 0
+            fi
+
+            git push origin "$SYNC_BRANCH"
+
+            # Check for existing open sync PR
+            EXISTING=$(gh pr list --base main --head "$SYNC_BRANCH" --state open --json number -q '.[0].number' 2>/dev/null || true)
+            if [ -n "$EXISTING" ]; then
+              echo "Sync PR #$EXISTING already exists."
+              exit 0
+            fi
 
-          # Cherry-pick the commit
-          if git cherry-pick "${{ github.sha }}"; then
-            git push origin "$PATCH_BRANCH"
-            
-            # Create PR
             gh pr create \
               --base main \
-              --head "$PATCH_BRANCH" \
-              --title "🔄 Sync: ${{ github.event.head_commit.message }}" \
-              --body "Auto-sync patch from ${{ github.ref_name }}
-              
-              Commit: ${{ github.sha }}
-              
-              ---
-              _This PR was automatically created to sync a patch to main._" \
+              --head "$SYNC_BRANCH" \
+              --title "🔄 Sync stable → main" \
+              --body "$(cat <<'EOF'
+          ## Summary
+          Merges latest stable patches into main to keep branches in sync.
+
+          This ensures `@next` prereleases stay ahead of `@latest` releases.
+
+          ---
+          _Auto-created by sync-patches workflow._
+          EOF
+              )" \
               --label "patch-sync"
+
+            echo "✅ Created sync PR"
+          else
+            echo "Merge conflict — attempting auto-resolution of release artifacts..."
+
+            # Auto-resolve expected conflicts: package.json version and CHANGELOG.md.
+            # For these files, keep main's version (semantic-release manages them per-branch).
+            for f in packages/superdoc/package.json packages/superdoc/CHANGELOG.md; do
+              if git diff --name-only --diff-filter=U | grep -qF "$f"; then
+                echo "  Auto-resolving $f (keeping main's version)"
+                git checkout --ours "$f"
+                git add "$f"
+              fi
+            done
+
+            # Check if all conflicts are resolved
+            if [ -z "$(git diff --name-only --diff-filter=U)" ]; then
+              git commit --no-edit
+              git push origin "$SYNC_BRANCH"
+
+              gh pr create \
+                --base main \
+                --head "$SYNC_BRANCH" \
+                --title "🔄 Sync stable → main" \
+                --body "$(cat <<'EOF'
+          ## Summary
+          Merges latest stable patches into main to keep branches in sync.
+
+          Release artifact conflicts (package.json version, CHANGELOG.md) were auto-resolved.
+
+          ---
+          _Auto-created by sync-patches workflow._
+          EOF
+                )" \
+                --label "patch-sync"
+
+              echo "✅ Created sync PR (release conflicts auto-resolved)"
+            else
+              echo "⚠️ Unresolved conflicts remain — creating PR for manual resolution."
+
+              # Commit with conflict markers so the PR is reviewable
+              git add -A
+              git commit -m "chore: merge stable into main (conflicts need resolution)"
+              git push origin "$SYNC_BRANCH"
+
+              gh pr create \
+                --base main \
+                --head "$SYNC_BRANCH" \
+                --title "🔄 Sync stable → main (conflicts)" \
+                --body "$(cat <<'EOF'
+          ## Summary
+          Merges latest stable patches into main. **Has merge conflicts that need manual resolution.**
+
+          Release artifact conflicts were auto-resolved, but other conflicts remain.
+
+          ---
+          _Auto-created by sync-patches workflow._
+          EOF
+                )" \
+                --label "patch-sync"
+
+              echo "⚠️ Created sync PR with conflicts"
+            fi
           fi

.github/workflows/sync-patches.yml

@@ -71,6 +71,7 @@ perf-baseline-results.json
 .claude
 plans/
 
+tests/layout-snapshots
 tests/layout/candidate/
 tests/layout/reference/
 tests/layout/reports/
@@ -84,6 +85,7 @@ devtools/visual-testing/pnpm-lock.yaml
 __pycache__/
 *.pyc
 *.pyo
+venv/
 # Generated platform companion build metadata (do not commit)
 packages/sdk/langs/python/platforms/**/*.egg-info/
 # Generated python packaging metadata (do not commit)

.gitignore

@@ -59,7 +59,8 @@ tests/visual/        Visual regression tests (Playwright + R2 baselines)
 |------|----------|
 | React integration | `packages/react/src/SuperDocEditor.tsx` |
 | Editing features | `super-editor/src/extensions/` |
-| Presentation mode visuals | `layout-engine/painters/dom/src/renderer.ts` |
+| Presentation mode visuals | `layout-engine/painters/dom/src/features/feature-registry.ts` → feature module |
+| Rendering orchestration | `layout-engine/painters/dom/src/renderer.ts` |
 | DOCX import/export | `super-editor/src/core/super-converter/` |
 | Style resolution | `layout-engine/style-engine/` |
 | Main entry point (Vue) | `superdoc/src/SuperDoc.vue` |
@@ -79,7 +80,7 @@ tests/visual/        Visual regression tests (Playwright + R2 baselines)
 
 ## When to Modify Which System
 
-- **Visual rendering**: Modify `pm-adapter/` (to feed data) and/or `painters/dom/` (to render it)
+- **Visual rendering**: Check `painters/dom/src/features/feature-registry.ts` to find the feature module, then modify it. If no module exists yet, create one (see layout-engine CLAUDE.md). Feed data via `pm-adapter/`
 - **Style resolution**: Modify `style-engine/` — called by pm-adapter during conversion
 - **Editing commands/behavior**: Modify `super-editor/src/extensions/`
 - **State bridging**: Modify `PresentationEditor.ts`
@@ -111,13 +112,31 @@ Many packages use `.js` files with JSDoc `@typedef` for type definitions (e.g.,
 - `pnpm dev` - Start dev server (from examples/)
 - `pnpm run generate:all` - Generate all derived artifacts (schemas, SDK clients, tool catalogs, reference docs)
 
+## AI Eval Suite
+
+The `evals/` directory contains a Promptfoo-based evaluation suite for validating AI tool call quality.
+
+| Command | What it does | Cost |
+|---------|-------------|------|
+| `pnpm --filter @superdoc-testing/evals run eval` | Run deterministic evals (reading + argument tests) | ~$0.30 |
+| `pnpm --filter @superdoc-testing/evals run eval:reading` | Run reading tool tests only | ~$0.15 |
+| `pnpm --filter @superdoc-testing/evals run eval:gdpval` | Run GDPval benchmark (Model+SuperDoc vs Model-Only) | ~$1-2 |
+| `pnpm --filter @superdoc-testing/evals run eval:view` | Open Promptfoo web UI with results | Free |
+| `pnpm --filter @superdoc-testing/evals run baseline:save <label>` | Save versioned results snapshot | Free |
+
+Tool definitions are extracted from `packages/sdk/tools/` via `evals/tools/extract.mjs`. Run `pnpm run generate:all` first if SDK artifacts are missing.
+
+Test files are YAML in `evals/tests/`. Each test has a `vars.task` prompt and JavaScript assertions that check tool call structure (Level 1: tool selection + argument accuracy, not execution).
+
+The system prompt at `evals/prompts/agent.txt` is a copy of the proven prompt from `examples/eval-demo/lib/agent.ts`. Update both when changing the prompt.
+
 ## Generated Artifacts
 
 These directories are produced by `pnpm run generate:all`:
 
 | Directory | In git? | What it contains |
 |-----------|---------|-----------------|
-| `packages/document-api/generated/` | No (gitignored) | Agent tool schemas, JSON schemas, manifest |
+| `packages/document-api/generated/` | No (gitignored) | Agent artifacts, JSON schemas |
 | `apps/cli/generated/` | No (gitignored) | SDK contract JSON exported from CLI metadata |
 | `packages/sdk/langs/node/src/generated/` | No (gitignored) | Node SDK generated client code |
 | `packages/sdk/langs/python/superdoc/generated/` | No (gitignored) | Python SDK generated client code |

CLAUDE.md

@@ -105,6 +105,18 @@ The command automatically:
 - Runs pixel-level comparison against the same reference version
 - Generates an interactive HTML report in `devtools/visual-testing/results/`
 
+## Uploading Test Documents
+
+Upload a `.docx` file to the shared test corpus (used by layout, visual, and behavior tests):
+
+```bash
+pnpm corpus:upload ~/Downloads/my-file.docx
+# Prompts for: Linear issue ID, short description
+# → uploads as rendering/sd-1741-paragraph-between-borders.docx
+```
+
+After uploading, pull it locally with `pnpm corpus:pull` so it's available for all test suites.
+
 ## When to Run What
 
 | I changed... | Run |