[WIP] New Understudy v4 Page.* Routes

.github/workflows/ci.yml

@@ -88,7 +88,8 @@ jobs:
               - 'package.json'
               - 'pnpm-lock.yaml'
             server:
-              - 'packages/server/**'
+              - 'packages/server-v3/**'
+              - 'packages/server-v4/**'
               - 'packages/core/**'
               - 'package.json'
               - 'pnpm-lock.yaml'
@@ -243,8 +244,10 @@ jobs:
             packages/core/lib/dom/build/**
             packages/core/lib/v3/dom/build/**
             packages/evals/dist/**
-            packages/server/dist/**
-            packages/server/openapi.v3.yaml
+            packages/server-v3/dist/**
+            packages/server-v3/openapi.v3.yaml
+            packages/server-v4/dist/**
+            packages/server-v4/openapi.v4.yaml
           retention-days: 1
 
   discover-core-tests:
@@ -339,7 +342,7 @@ jobs:
       - name: Discover server test files
         id: set-matrix
         run: |
-          int_json=$(pnpm --filter @browserbasehq/stagehand-server --silent run test:server -- --list integration)
+          int_json=$(pnpm --filter @browserbasehq/stagehand-server-v3 --silent run test:server -- --list integration)
           echo "integration-tests=$int_json" >> $GITHUB_OUTPUT
 
           if [ "$int_json" = "[]" ]; then
@@ -351,27 +354,27 @@ jobs:
           echo "Found server integration tests: $int_json"
 
   build-server-sea:
-    name: Build SEA binary (tests)
-    uses: ./.github/workflows/stagehand-server-sea-build.yml
+    name: Build SEA binary (tests, v3)
+    uses: ./.github/workflows/stagehand-server-v3-sea-build.yml
     needs: [run-build]
     with:
       matrix: |
         [
-          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-linux-x64","include_sourcemaps":false},
-          {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-linux-arm64","include_sourcemaps":false},
-          {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-darwin-arm64","include_sourcemaps":false},
-          {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-darwin-x64","include_sourcemaps":false},
-          {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-win32-x64.exe","include_sourcemaps":false},
-          {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-win32-arm64.exe","include_sourcemaps":false},
-          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-linux-x64-sourcemap","include_sourcemaps":true}
+          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-v3-linux-x64","include_sourcemaps":false},
+          {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-v3-linux-arm64","include_sourcemaps":false},
+          {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-v3-darwin-arm64","include_sourcemaps":false},
+          {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-v3-darwin-x64","include_sourcemaps":false},
+          {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-v3-win32-x64.exe","include_sourcemaps":false},
+          {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-v3-win32-arm64.exe","include_sourcemaps":false},
+          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-v3-linux-x64-sourcemap","include_sourcemaps":true}
         ]
       use-prebuilt-artifacts: "true"
       restore-turbo-cache: "false"
       node-version: "20.x"
-      upload-only-binary: stagehand-server-linux-x64-sourcemap
+      upload-only-binary: stagehand-server-v3-linux-x64-sourcemap
 
   server-integration-tests:
-    name: server/integration/${{ matrix.test.name }}
+    name: server/v3/integration/${{ matrix.test.name }}
     runs-on: ubuntu-latest
     needs: [build-server-sea, discover-server-tests, run-build]
     if: needs.discover-server-tests.outputs.has-integration-tests == 'true'
@@ -406,31 +409,31 @@ jobs:
       - name: Download SEA binary
         uses: actions/download-artifact@v4
         with:
-          name: stagehand-server-linux-x64-sourcemap
+          name: stagehand-server-v3-linux-x64-sourcemap
           path: .
 
       - name: Ensure SEA binary is present and executable
         shell: bash
         run: |
           set -euo pipefail
-          test -f packages/server/dist/sea/stagehand-server-linux-x64-sourcemap
-          chmod +x packages/server/dist/sea/stagehand-server-linux-x64-sourcemap
+          test -f packages/server-v3/dist/sea/stagehand-server-v3-linux-x64-sourcemap
+          chmod +x packages/server-v3/dist/sea/stagehand-server-v3-linux-x64-sourcemap
 
       - name: Run server integration test - ${{ matrix.test.name }}
         env:
-          SEA_BINARY_NAME: stagehand-server-linux-x64-sourcemap
+          SEA_BINARY_NAME: stagehand-server-v3-linux-x64-sourcemap
         run: |
-          pnpm exec turbo run test:server --only --filter=@browserbasehq/stagehand-server -- "${{ matrix.test.path }}"
+          pnpm exec turbo run test:server --only --filter=@browserbasehq/stagehand-server-v3 -- "${{ matrix.test.path }}"
 
       - uses: ./.github/actions/upload-ctrf-report
         if: always()
         with:
-          name: ctrf/server-integration/${{ matrix.test.name }}.json
+          name: ctrf/server-v3-integration/${{ matrix.test.name }}.json
 
       - uses: ./.github/actions/upload-v8-coverage
         if: always()
         with:
-          name: coverage/server-integration/${{ matrix.test.name }}
+          name: coverage/server-v3-integration/${{ matrix.test.name }}
 
   discover-e2e-tests:
     runs-on: ubuntu-latest

.github/workflows/stagehand-server-release.yml → .github/workflows/stagehand-server-v3-release.yml

@@ -1,4 +1,4 @@
-name: Release stagehand/server
+name: Release stagehand/server-v3
 
 on:
   push:
@@ -14,11 +14,11 @@ permissions:
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
 env:
-  OAS_PATH: packages/server/openapi.v3.yaml
+  OAS_PATH: packages/server-v3/openapi.v3.yaml
 
 jobs:
   detect:
-    name: Detect server release (changesets)
+    name: Detect server-v3 release (changesets)
     runs-on: ubuntu-latest
     outputs:
       release: ${{ steps.meta.outputs.release }}
@@ -43,7 +43,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          latest_tag="$(git tag -l 'stagehand-server/v*' --sort=-v:refname | head -n 1 || true)"
+          latest_tag="$(git tag -l 'stagehand-server-v3/v*' --sort=-v:refname | head -n 1 || true)"
           rm -f changeset-status.json
           if [ -n "${latest_tag}" ]; then
             pnpm changeset status --since "${latest_tag}" --output changeset-status.json
@@ -59,27 +59,27 @@ jobs:
           const releases = Array.isArray(status.releases) ? status.releases : [];
 
           const shouldRelease = changesets.some((cs) =>
-            (cs.releases || []).some((r) => r?.name === '@browserbasehq/stagehand-server')
+            (cs.releases || []).some((r) => r?.name === '@browserbasehq/stagehand-server-v3')
           );
 
-          const serverRelease = releases.find((r) => r?.name === '@browserbasehq/stagehand-server');
+          const serverRelease = releases.find((r) => r?.name === '@browserbasehq/stagehand-server-v3');
           if (shouldRelease && !serverRelease?.newVersion) {
             throw new Error(
-              'Expected @browserbasehq/stagehand-server to have a computed newVersion in changeset-status.json.'
+              'Expected @browserbasehq/stagehand-server-v3 to have a computed newVersion in changeset-status.json.'
             );
           }
 
           const release = shouldRelease ? 'true' : 'false';
           const version = shouldRelease ? serverRelease.newVersion : '';
-          const tag = `stagehand-server/v${version}`;
+          const tag = `stagehand-server-v3/v${version}`;
 
           const out = process.env.GITHUB_OUTPUT;
           fs.appendFileSync(out, `release=${release}\n`);
           fs.appendFileSync(out, `version=${version}\n`);
           fs.appendFileSync(out, `tag=${tag}\n`);
           NODE
 
-      - name: Create stagehand/server tag
+      - name: Create stagehand/server-v3 tag
         if: steps.meta.outputs.release == 'true'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -101,23 +101,23 @@ jobs:
             exit 0
           fi
 
-          git tag -a "${TAG}" "${TARGET_SHA}" -m "stagehand/server v${VERSION}"
+          git tag -a "${TAG}" "${TARGET_SHA}" -m "stagehand/server-v3 v${VERSION}"
           git push origin "${TAG}"
 
   build_binaries:
     name: Build SEA binaries
     needs: detect
     if: needs.detect.outputs.release == 'true'
-    uses: ./.github/workflows/stagehand-server-sea-build.yml
+    uses: ./.github/workflows/stagehand-server-v3-sea-build.yml
     with:
       matrix: |
         [
-          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-linux-x64","include_sourcemaps":false},
-          {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-linux-arm64","include_sourcemaps":false},
-          {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-darwin-arm64","include_sourcemaps":false},
-          {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-darwin-x64","include_sourcemaps":false},
-          {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-win32-x64.exe","include_sourcemaps":false},
-          {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-win32-arm64.exe","include_sourcemaps":false}
+          {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-v3-linux-x64","include_sourcemaps":false},
+          {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-v3-linux-arm64","include_sourcemaps":false},
+          {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-v3-darwin-arm64","include_sourcemaps":false},
+          {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-v3-darwin-x64","include_sourcemaps":false},
+          {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-v3-win32-x64.exe","include_sourcemaps":false},
+          {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-v3-win32-arm64.exe","include_sourcemaps":false}
         ]
 
   release:
@@ -135,15 +135,15 @@ jobs:
       - name: Prepare release assets directory
         run: mkdir -p release-assets
 
-      - name: Prepare stagehand/server release assets
+      - name: Prepare stagehand/server-v3 release assets
         run: |
           set -euo pipefail
-          cp "${{ env.OAS_PATH }}" "release-assets/openapi.v3.stagehand-server-${{ needs.detect.outputs.version }}.yaml"
+          cp "${{ env.OAS_PATH }}" "release-assets/openapi.v3.stagehand-server-v3-${{ needs.detect.outputs.version }}.yaml"
 
       - name: Download SEA binary artifacts
         uses: actions/download-artifact@v4
         with:
-          pattern: stagehand-server-*
+          pattern: stagehand-server-v3-*
           path: .
           merge-multiple: true
 
@@ -152,7 +152,7 @@ jobs:
         run: |
           set -euo pipefail
           shopt -s nullglob
-          for f in packages/server/dist/sea/stagehand-server-*; do
+          for f in packages/server-v3/dist/sea/stagehand-server-v3-*; do
             cp "$f" release-assets/
           done
 
@@ -163,7 +163,7 @@ jobs:
           cd release-assets
           # Only checksum binaries (exclude openapi yaml). Avoid failing if no matches.
           shopt -s nullglob
-          files=(stagehand-server-*)
+          files=(stagehand-server-v3-*)
           bins=()
           for f in "${files[@]}"; do
             [[ "$f" == *openapi* ]] && continue
@@ -174,13 +174,13 @@ jobs:
             shasum -a 256 "${bins[@]}" > checksums.sha256
           fi
 
-      - name: Publish stagehand/server GitHub release
+      - name: Publish stagehand/server-v3 GitHub release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ needs.detect.outputs.tag }}
-          name: stagehand/server v${{ needs.detect.outputs.version }}
+          name: stagehand/server-v3 v${{ needs.detect.outputs.version }}
           generate_release_notes: true
           files: |
-            release-assets/openapi.v3.stagehand-server-${{ needs.detect.outputs.version }}.yaml
-            release-assets/stagehand-server-*
+            release-assets/openapi.v3.stagehand-server-v3-${{ needs.detect.outputs.version }}.yaml
+            release-assets/stagehand-server-v3-*
             release-assets/checksums.sha256

.github/workflows/stagehand-server-sea-build.yml → .github/workflows/stagehand-server-v3-sea-build.yml

@@ -1,4 +1,4 @@
-name: Stagehand Server SEA Build
+name: Stagehand Server v3 SEA Build
 
 on:
   workflow_call:
@@ -9,12 +9,12 @@ on:
         type: string
         default: |
           [
-            {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-linux-x64","include_sourcemaps":false},
-            {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-linux-arm64","include_sourcemaps":false},
-            {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-darwin-arm64","include_sourcemaps":false},
-            {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-darwin-x64","include_sourcemaps":false},
-            {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-win32-x64.exe","include_sourcemaps":false},
-            {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-win32-arm64.exe","include_sourcemaps":false}
+            {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-v3-linux-x64","include_sourcemaps":false},
+            {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-v3-linux-arm64","include_sourcemaps":false},
+            {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-v3-darwin-arm64","include_sourcemaps":false},
+            {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-v3-darwin-x64","include_sourcemaps":false},
+            {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-v3-win32-x64.exe","include_sourcemaps":false},
+            {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-v3-win32-arm64.exe","include_sourcemaps":false}
           ]
       use-prebuilt-artifacts:
         description: "Whether to download pre-built package artifacts."
@@ -43,12 +43,12 @@ on:
         required: false
         default: |
           [
-            {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-linux-x64","include_sourcemaps":false},
-            {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-linux-arm64","include_sourcemaps":false},
-            {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-darwin-arm64","include_sourcemaps":false},
-            {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-darwin-x64","include_sourcemaps":false},
-            {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-win32-x64.exe","include_sourcemaps":false},
-            {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-win32-arm64.exe","include_sourcemaps":false}
+            {"os":"ubuntu-latest","platform":"linux","arch":"x64","binary_name":"stagehand-server-v3-linux-x64","include_sourcemaps":false},
+            {"os":"ubuntu-24.04-arm","platform":"linux","arch":"arm64","binary_name":"stagehand-server-v3-linux-arm64","include_sourcemaps":false},
+            {"os":"macos-15","platform":"darwin","arch":"arm64","binary_name":"stagehand-server-v3-darwin-arm64","include_sourcemaps":false},
+            {"os":"macos-15-intel","platform":"darwin","arch":"x64","binary_name":"stagehand-server-v3-darwin-x64","include_sourcemaps":false},
+            {"os":"windows-latest","platform":"win32","arch":"x64","binary_name":"stagehand-server-v3-win32-x64.exe","include_sourcemaps":false},
+            {"os":"windows-11-arm","platform":"win32","arch":"arm64","binary_name":"stagehand-server-v3-win32-arm64.exe","include_sourcemaps":false}
           ]
       use-prebuilt-artifacts:
         description: "Whether to download pre-built package artifacts."
@@ -103,12 +103,12 @@ jobs:
           SEA_TARGET_ARCH: ${{ matrix.arch }}
           SEA_BINARY_NAME: ${{ matrix.binary_name }}
           SEA_INCLUDE_SOURCEMAPS: ${{ matrix.include_sourcemaps && '1' || '0' }}
-        run: pnpm exec turbo run build:sea:esm --filter=@browserbasehq/stagehand-server
+        run: pnpm exec turbo run build:sea:esm --filter=@browserbasehq/stagehand-server-v3
 
       - name: Verify SEA binary exists
         shell: bash
         run: |
-          test -f "packages/server/dist/sea/${{ matrix.binary_name }}"
+          test -f "packages/server-v3/dist/sea/${{ matrix.binary_name }}"
 
       - name: Verify SEA binary launches cleanly
         shell: bash
@@ -117,7 +117,7 @@ jobs:
         run: |
           set -euo pipefail
 
-          binary="packages/server/dist/sea/${{ matrix.binary_name }}"
+          binary="packages/server-v3/dist/sea/${{ matrix.binary_name }}"
           matrix_arch="${{ matrix.arch }}"
           runner_arch="$(echo "${RUNNER_ARCH}" | tr '[:upper:]' '[:lower:]')"
 
@@ -176,5 +176,5 @@ jobs:
           # package.json is included to anchor artifact paths at repo root.
           path: |
             package.json
-            packages/server/dist/sea/${{ matrix.binary_name }}
+            packages/server-v3/dist/sea/${{ matrix.binary_name }}
           retention-days: 7