feat(ui): add reusable developer surface system

.github/workflows/repair-pr3-stack-20260831.yml

@@ -0,0 +1,177 @@
+name: Repair PR 3 stack
+
+on:
+  push:
+    branches:
+      - feat/developer-surface-system
+
+permissions:
+  contents: write
+
+concurrency:
+  group: repair-pr3-stack
+  cancel-in-progress: false
+
+jobs:
+  repair:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Check out feature branch
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          ref: feat/developer-surface-system
+          fetch-depth: 0
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+        with:
+          version: 10.17.1
+
+      - name: Set up Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Set up Chrome for Testing
+        id: chrome
+        uses: browser-actions/setup-chrome@2e1d749697dd1612b833dba4a722266286fbefcd # v2.1.2
+        with:
+          chrome-version: stable
+
+      - name: Rebuild PR 3 from the verified PR 2 tree
+        env:
+          CHROME_PATH: ${{ steps.chrome.outputs.chrome-path }}
+        run: |
+          set -euo pipefail
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin feat/developer-surface-system test/specimen-visual-review
+
+          old_head="$(git rev-parse origin/feat/developer-surface-system)"
+
+          # PR 2 removes its one-shot repair workflow only after full CI and the
+          # browser/mobile matrix pass. Wait for that proven head rather than
+          # racing a partially repaired stack.
+          base_head=""
+          for _ in $(seq 1 180); do
+            git fetch origin test/specimen-visual-review
+            candidate="$(git rev-parse origin/test/specimen-visual-review)"
+            if ! git cat-file -e "$candidate:.github/workflows/repair-pr2-stack-20260831.yml" 2>/dev/null; then
+              base_head="$candidate"
+              break
+            fi
+            sleep 5
+          done
+
+          if [[ -z "$base_head" ]]; then
+            echo "Timed out waiting for PR 2's verified repair head." >&2
+            exit 1
+          fi
+
+          git checkout --detach "$base_head"
+
+          preserve=(
+            .github/workflows/visual-review.yml
+            apps/specimens/src/developer-showcase.tsx
+            apps/specimens/src/main.tsx
+            docs/developer-surface.md
+            package.json
+            packages/ui/src/blocks/developer-surface.tsx
+            packages/ui/src/components/command-receipt.tsx
+            packages/ui/src/components/connection-status.tsx
+            packages/ui/src/components/ui/tabs.tsx
+            packages/ui/src/index.ts
+            packages/ui/tests/developer-surface.test.tsx
+            packages/ui/tests/tabs.test.tsx
+            registry/developer/registry.fragment.json
+            scripts/check-registry-clean.mjs
+            scripts/compose-registry.mjs
+            scripts/developer-visual-review.mjs
+            scripts/test-registry-consumer.mjs
+            scripts/verify-contracts.mjs
+            vercel.json
+          )
+
+          for path in "${preserve[@]}"; do
+            mkdir -p "$(dirname "$path")"
+            git show "$old_head:$path" > "$path"
+          done
+
+          rm -f .github/workflows/repair-pr3-stack-20260831.yml
+          rm -f .github/workflows/refine-visual-clipping-check.yml
+
+          # Preserve all developer-surface contracts while importing the final
+          # intrinsic-grid regression guard from the verified shell base.
+          python - <<'PY'
+          from pathlib import Path
+
+          path = Path("scripts/verify-contracts.mjs")
+          text = path.read_text()
+          marker = '''  [
+            "specimen chrome avoids decorative gradients",
+            !specimenCss.includes("gradient("),
+          ],'''
+          assertion = '''  [
+            "responsive grids allow intrinsic shrinking",
+            specimenFixes.includes(
+              ".specimen-shell {\\n    grid-template-columns: minmax(0, 1fr);",
+            ) &&
+              specimenFixes.includes(
+                ".catalog-group__grid {\\n    grid-template-columns: minmax(0, 1fr);",
+              ),
+          ],
+'''
+          if "responsive grids allow intrinsic shrinking" not in text:
+              if marker not in text:
+                  raise SystemExit("Could not locate contract insertion point")
+              text = text.replace(marker, assertion + marker, 1)
+          path.write_text(text)
+          PY
+
+          pnpm install --frozen-lockfile
+          pnpm registry:build
+          pnpm exec prettier --write \
+            "${preserve[@]}" \
+            registry.json \
+            'public/r/*.json'
+
+          git add -A
+          tree="$(git write-tree)"
+          merge_commit="$(printf '%s\n' 'chore(stack): rebuild developer surface on verified visual base' | git commit-tree "$tree" -p "$old_head" -p "$base_head")"
+
+          git checkout --detach "$merge_commit"
+          pnpm check
+
+          rm -rf artifacts/visual-review artifacts/mobile-quality
+          mkdir -p artifacts/visual-review artifacts/mobile-quality
+          preview_log="$RUNNER_TEMP/specimens-preview.log"
+          pnpm --filter @opencoven/specimens preview --host 127.0.0.1 --port 4173 >"$preview_log" 2>&1 &
+          preview_pid=$!
+          cleanup() {
+            kill "$preview_pid" 2>/dev/null || true
+            wait "$preview_pid" 2>/dev/null || true
+          }
+          trap cleanup EXIT
+
+          ready=false
+          for _ in $(seq 1 120); do
+            if curl --fail --silent http://127.0.0.1:4173/ >/dev/null; then
+              ready=true
+              break
+            fi
+            sleep 0.1
+          done
+          if [[ "$ready" != "true" ]]; then
+            cat "$preview_log"
+            exit 1
+          fi
+
+          node scripts/visual-review.mjs
+          node scripts/developer-visual-review.mjs
+          node scripts/mobile-quality-review.mjs
+
+          git push origin "$merge_commit":refs/heads/feat/developer-surface-system

.github/workflows/visual-review.yml

@@ -6,7 +6,10 @@ on:
       - ".github/workflows/visual-review.yml"
       - "apps/specimens/**"
       - "packages/ui/**"
+      - "registry/**"
+      - "scripts/compose-registry.mjs"
       - "scripts/visual-review.mjs"
+      - "scripts/developer-visual-review.mjs"
       - "scripts/mobile-quality-review.mjs"
   workflow_dispatch:
 
@@ -21,7 +24,7 @@ jobs:
   specimens:
     name: Specimen browser
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 25
 
     steps:
       - name: Check out repository
@@ -43,8 +46,8 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build package and specimen app
-        run: pnpm build
+      - name: Build registry, package, and specimen app
+        run: pnpm registry:build && pnpm build
 
       - name: Set up Chrome for Testing
         id: chrome
@@ -89,14 +92,16 @@ jobs:
 
           set +e
           node scripts/visual-review.mjs
-          visual_status=$?
+          browser_status=$?
+          node scripts/developer-visual-review.mjs
+          developer_status=$?
           node scripts/mobile-quality-review.mjs
           mobile_status=$?
           set -e
 
           cp "$preview_log" artifacts/visual-review/preview.log
 
-          if [[ "$visual_status" -ne 0 || "$mobile_status" -ne 0 ]]; then
+          if [[ "$browser_status" -ne 0 || "$developer_status" -ne 0 || "$mobile_status" -ne 0 ]]; then
             exit 1
           fi