[PF-1992] Migration orchestrator

.changeset/picasso-shared-react-event-helpers.md

@@ -0,0 +1,8 @@
+---
+'@toptal/picasso-shared': minor
+---
+
+### picasso-shared
+
+- add `toReactEvent<R>(event)` boundary-cast helper for bridging native DOM `Event` to React.SyntheticEvent variants at the `@base-ui/react` ↔ Picasso form-component interface. Proxy-based: preserves native event identity, synthesizes the four React-SyntheticEvent shim methods (`nativeEvent`, `persist`, `isDefaultPrevented`, `isPropagationStopped`).
+- add `toReactChangeEvent<T>(event)` specialized helper for form-input `onChange` adapters. Constrains `T` to `HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement` and dev-warns when the event target is not a DOM element. Delegates to `toReactEvent` for the Proxy machinery.

.claude/settings.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm davinci-syntax *)",
+      "Bash(pnpm davinci-qa *)",
+      "Bash(pnpm eslint *)",
+      "Bash(pnpm exec tsc --noEmit *)",
+      "Bash(pnpm typecheck *)",
+      "Bash(gh search *)",
+      "Bash(bash -n *)",
+      "Bash(pnpm tsc --noEmit *)",
+      "Bash(pnpm changeset status)",
+      "Bash(pnpm changeset status *)",
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_snapshot",
+      "mcp__playwright__browser_console_messages",
+      "mcp__playwright__browser_take_screenshot"
+    ]
+  }
+}

.envrc.example

@@ -0,0 +1,47 @@
+# Picasso migration orchestrator — environment template.
+#
+# Copy to `.envrc` (repo root, gitignored) OR `~/Projects/.envrc`, fill in,
+# then run `direnv allow`. The orchestrator's loadEnvrcUpwards() walks up from
+# the repo and auto-loads the nearest .envrc via direnv.
+#
+# No direnv? Either `source` this file before `pnpm orchestrate`, or pass the
+# vars inline:  HAPPO_API_KEY=… HAPPO_API_SECRET=… pnpm orchestrate --component=Note
+#
+# NOTE: claude / gh / ssh auth are NOT set here — they're CLI/agent-managed.
+#   See docs/migration/ORCHESTRATOR.md §"First-time setup".
+#   Verify your whole setup at once with: pnpm orchestrate --component=<X> --dry-run
+#   (reads the prerequisite report without starting a real run).
+
+# --- Required for the Happo visual gate ---------------------------------
+# Your personal Happo API credentials, with access to the Picasso Happo org
+# (account 675). Get them from https://happo.io account settings.
+# To run WITHOUT Happo instead, leave these unset and pass
+# MIGRATION_GATE_HAPPO=skip (sandbox / smoke runs only).
+export HAPPO_API_KEY=
+export HAPPO_API_SECRET=
+
+# --- Required for correct pnpm node_modules layout ----------------------
+# Any value works (e.g. `dummy`) — only used to authenticate registry fetches,
+# not for layout. Without it pnpm falls back to the isolated linker and tsc
+# can't resolve React types.
+export NPM_TOKEN=dummy
+
+# --- Optional: model preset (fable | opus) ------------------------------
+# Default: fable (current config — claude-fable-5[1m]). opus is claude-opus-4-8[1m]
+# at the same effort, ≈half fable's per-token cost. Override per-run with
+# `--preset=opus`; `--model` / `--effort` / `--thinking-tokens` override fields.
+# export MIGRATION_MODEL_PRESET=fable
+
+# --- Optional: gate / behavior knobs (env-only) -------------------------
+# Defaults are sensible; uncomment to override per-clone (e.g. a sandbox clone
+# that always skips the visual gate). Full list + effects:
+# docs/migration/ORCHESTRATOR.md §"Environment knobs".
+# export MIGRATION_GATE_HAPPO=skip               # bypass Happo visual gate (sandbox/smoke)
+# export MIGRATION_GATE_CHANGESET=skip           # bypass changeset validation
+# export MIGRATION_GATE_DOCTRINE=skip            # bypass code-doctrine check
+# export MIGRATION_GATE_HAPPO_CYPRESS_STRICT=1   # make Cypress visual diffs gate (default: advisory)
+# export MIGRATION_GATE_HAPPO_CYPRESS=skip       # disable the Cypress visual suite
+
+# --- Optional: Confluence status sync (silently skipped if unset) -------
+# export ATLASSIAN_EMAIL=
+# export ATLASSIAN_API_TOKEN=

.eslintignore

@@ -5,3 +5,7 @@ build
 node_modules
 !.changeset
 .changeset/README.md
+docs/migration
+docs/modernization
+bin
+migration-runs

.eslintrc.js

@@ -39,6 +39,15 @@ const generateSameSettingRules = (ruleNames, setting) => {
 }
 
 module.exports = {
+  // root: true stops ESLint from walking up the directory tree looking for
+  // ancestor configs. Required for `git worktree`-based dev flows
+  // (orchestrator's worktrees live under `migration-runs/<date>/<comp>/worktree/`,
+  // and without `root: true`, ESLint walks up from the worktree's source
+  // through `migration-runs/`, eventually re-discovering this same config in
+  // the main repo via a different filesystem path. That double-load registers
+  // `eslint-plugin-ssr-friendly` from two node_modules paths and fails with
+  // "ESLint couldn't determine the plugin uniquely". Fixed 2026-05-07.)
+  root: true,
   extends: [
     require.resolve('@toptal/davinci-syntax/src/configs/.eslintrc.cjs'),
     'plugin:ssr-friendly/recommended',

.github/workflows/danger.yaml

@@ -3,7 +3,7 @@ name: Danger
 on:
   pull_request:
     types: [opened, synchronize, reopened, edited, assigned, unassigned]
-    branches: [master]
+    branches: [master, 'feature/**']
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

.github/workflows/design-patterns-check.yaml

@@ -0,0 +1,123 @@
+name: Picasso Design Patterns Check
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  design-patterns:
+    name: Picasso design patterns
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude design-patterns review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: '--allowed-tools "Bash(git diff:*),Bash(git fetch:*),Read,Write"'
+          prompt: |
+            You are reviewing this pull request against the Picasso component
+            library design-pattern rules. Follow these steps:
+
+            1. Read `./PICASSO_COMPONENT_DESIGN_PATTERNS.md`. It contains:
+               - Rules under `## Patterns` (apply to all components).
+               - Rules under `## Form components` (apply only to
+                 form/field-style components: inputs, selects, checkboxes,
+                 radios, date pickers, file uploaders, etc.). Label these
+                 rules F1, F2, F3 in the table.
+            2. Run `git fetch --no-tags --depth=1 origin ${{ github.base_ref }}`
+               and then `git diff origin/${{ github.base_ref }}...HEAD --
+               'packages/**/*.tsx' 'packages/**/*.ts'
+               ':(exclude)**/*.test.*' ':(exclude)**/*.spec.*'
+               ':(exclude)**/*.stories.*'` to obtain the PR diff. Evaluate
+               ONLY the added/modified component code in that diff.
+            3. Skip rules that are not relevant to the diff. Skip the F-rules
+               for non-form components.
+            4. Write your review to `design-patterns-report.md` as a single
+               Markdown table — and ONLY that table. No preamble, no notes,
+               no summary, no surrounding prose.
+
+            Table format:
+
+            | Rule | Status |
+            | --- | --- |
+            | <id> — <short label> | :white_check_mark: OR :x: <short reason ≤ 20 words> |
+
+            - Use the rule's id followed by an em-dash and short label
+              (e.g., `1 — Optimize defaults for the common case`).
+            - One row per evaluated rule. Use `:white_check_mark:` for pass,
+              `:x: <reason>` for fail.
+            - If every evaluated rule passes, every row is
+              `:white_check_mark:`.
+
+            5. After writing the file, also output the exact same table as
+               your final message so it appears in the PR comment.
+
+      - name: Post report as PR comment on failure
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          MARKER: '<!-- picasso-design-patterns-report -->'
+        run: |
+          if [ ! -f design-patterns-report.md ]; then
+            echo "No report to post."
+            exit 0
+          fi
+          if ! grep -q ':x:' design-patterns-report.md; then
+            echo "All rules passed — skipping PR comment."
+            exit 0
+          fi
+          {
+            echo "$MARKER"
+            echo "### Picasso design patterns check failed"
+            echo ""
+            cat design-patterns-report.md
+          } > pr-comment.md
+
+          existing_ids=$(gh api --paginate "repos/$REPO/issues/$PR_NUMBER/comments" \
+            --jq "map(select(.body | contains(\"$MARKER\"))) | .[].id")
+
+          for id in $existing_ids; do
+            echo "Deleting previous comment $id."
+            gh api --method DELETE "repos/$REPO/issues/comments/$id"
+          done
+
+          echo "Creating new comment."
+          gh pr comment "$PR_NUMBER" --body-file pr-comment.md
+
+      - name: Check design patterns report
+        if: always()
+        run: |
+          if [ ! -f design-patterns-report.md ]; then
+            echo "No report produced — failing."
+            exit 1
+          fi
+          echo "===== Picasso design patterns report ====="
+          cat design-patterns-report.md
+          echo "=========================================="
+          if grep -q ':x:' design-patterns-report.md; then
+            echo "One or more design pattern rules failed. See the table above or the PR comment."
+            exit 1
+          fi
+          echo "All design pattern rules satisfied."

.gitignore

@@ -26,3 +26,61 @@ reports
 gha-creds-*.json
 
 llm-docs
+
+# Per-run artifacts emitted by bin/migration-orchestrator.ts (PF-1992).
+# Worktrees, gate logs, diff reports, agent prompts/responses, escalation
+# blocks. Reproducible per run; do not commit.
+migration-runs
+
+# Playwright MCP runtime artifacts emitted into the worktree when the
+# orchestrator runs with `--with-mcp` (page snapshots, console logs, etc.).
+# Captured by the agent for inspection during iter but should not land in
+# the migration PR. Without this entry the agent's `git add -A` step
+# (orchestrator-driven) sweeps them into the commit. See PR #4949 for the
+# debris example.
+.playwright-mcp
+
+# Migration diagnostic scratch at the worktree root. The orchestrator's
+# Happo-stalemate prompt (orchestrator-core.ts) tells the agent to save
+# computed-style + thumb-position dumps under `migration-runs/<date>/
+# <Component>/...` — which is the worktree's PARENT dir, NOT the worktree
+# itself. Agents that don't expand the path correctly default to writing
+# the file in CWD (= the worktree root = the repo root from git's view),
+# which `git add -A` then sweeps into the PR. Reviewers consistently flag
+# these as committed scratch files (PR #4955 Slider, PR #4965 Switch).
+# These patterns are a defensive backstop alongside fixing the prompt.
+/*-computed.json
+/*-thumbs*.json
+/after-fix-*.json
+/baseline-*.json
+/local-*.json
+/local--*.png
+/baseline--*.png
+/scripts/diff-happo.js
+**/__tests__/pixel-diff*.test.ts
+# Flat scratch dir the Happo-stalemate prompt now points the agent at, plus the
+# prefix-named computed-style dumps the old suffix globs above missed (the exact
+# files reviewers flagged in PR #4965 Switch: `.scratch-pngdiff.py`,
+# `computed-styles-local.json`). The orchestrator stray-guard also self-appends
+# here when it strips a novel scratch file.
+/.scratch/
+/.scratch-*
+/computed-styles-*.json
+/.tmp-payload.json
+/docs/migration/Button-diff.json
+/patches/@base-ui__utils@0.2.8.patch
+/computed-styles-local.json
+/docs/migration/Switch-diff.json
+/baseline--components-slider--slider--full-1280.png
+/baseline--components-slider--slider--tooltip-section.png
+/baseline--components-slider--slider.png
+/local--components-slider--slider--default.png
+/local--components-slider--slider--full-1280.png
+/local--components-slider--slider--tooltip-section.png
+/a11y-violation-1.png
+/a11y-violation-2.png
+/zoom-checked-diff.png
+/zoom2.png
+/zoom3.png
+/zoom4.png
+.claude/worktrees/

.npmrc

@@ -1,7 +1 @@
 //registry.npmjs.org/:_authToken=${NPM_TOKEN}
-
-node-linker=hoisted
-strict-peer-dependencies=false
-auto-install-peers=true
-link-workspace-packages=true
-resolve-peers-from-workspace-root=true

.storybook/main.js

@@ -62,6 +62,28 @@ module.exports = {
 
     const { reactDocgen, reactDocgenTypescriptOptions } = typescriptOptions
 
+    // Storybook's default rule for .(mjs|tsx?|jsx?) uses babel-loader with
+    // `exclude: /node_modules/`. That's correct for normal npm packages but
+    // wrong for `@toptal/picasso-*` workspace packages, which ship their
+    // `src/` directory alongside `dist-package/` in the published tarball.
+    // Picasso has at least one cross-package story import (Form's story
+    // pulls in FormLabel's story via `@toptal/picasso-form-label/src/...`)
+    // that resolves through node_modules into raw TypeScript source. Without
+    // babel applied, webpack tries to parse `import type` and fails with
+    // ModuleParseError. Narrow the exclude so workspace package sources go
+    // through babel even when resolved through node_modules.
+    const babelRule = config.module.rules.find(
+      rule => rule.test && rule.test.toString() === '/\\.(mjs|tsx?|jsx?)$/'
+    )
+
+    if (babelRule) {
+      babelRule.exclude = filePath =>
+        filePath.includes('/node_modules/') &&
+        !/[/\\]node_modules[/\\]@toptal[/\\]picasso-[^/\\]+[/\\]src[/\\]/.test(
+          filePath
+        )
+    }
+
     const cssRule = config.module.rules.find(
       rule => rule.test && rule.test.toString().includes('.css')
     )

.syncpackrc

@@ -6,5 +6,18 @@
     "prod",
     "resolutions",
     "local"
+  ],
+  "versionGroups": [
+    {
+      "label": "internal packages reference each other via the workspace protocol",
+      "dependencies": [
+        "$LOCAL"
+      ],
+      "dependencyTypes": [
+        "prod",
+        "dev"
+      ],
+      "pinVersion": "workspace:*"
+    }
   ]
 }