Address PR #906 review findings in google-translate plugin

.agents/skills/migrate-styled-components-to-vanilla-extract/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: migrate-styled-components-to-vanilla-extract
+description: Step-by-step procedure for migrating a workspace off styled-components to vanilla-extract (zero-runtime CSS). Use when converting styled() components to .css.ts files, removing a styled-components dependency, adding a ./bundle.css export, or when asked to migrate styling to vanilla-extract. Pair with the sanity-plugin-best-practices styling reference for the underlying patterns.
+metadata:
+  author: Sanity.io
+  version: '1.0.0'
+---
+
+# Migrate styled-components to vanilla-extract
+
+The repeatable procedure for converting a workspace's styling from `styled-components` (the Studio's
+legacy styling library) to [vanilla-extract](https://vanilla-extract.style).
+
+This skill covers the **workflow**: what to change, in what order, and how to verify it. The styling
+**patterns** themselves (dynamic theming, variants, keyframes, the `&&` specificity trick,
+encapsulation) live in the `sanity-plugin-best-practices` skill's
+[styling reference](../sanity-plugin-best-practices/references/styling.md) — read it first and defer
+to it for pattern details. For monorepo-specific policy (one plugin per PR, never during a transfer,
+which plugins are reference implementations), see `AGENTS.md` →
+`Migrating plugin styling off styled-components`.
+
+## Ground rules
+
+- **Identical visual output is the goal.** This is a refactor, not a redesign — every rule, theme
+  token, and specificity outcome must be preserved. Verify the result against the original rendering
+  before opening the PR.
+
+## Step 1: Inventory
+
+Find every styled-components usage in the workspace and classify it before touching code:
+
+```bash
+rg "styled-components" <workspace>/src
+```
+
+| Usage                                               | Migration target                                                                   |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Static `styled(Primitive)` / `styled.div`           | `style()` in a colocated `.css.ts` + thin wrapper component (or plain `className`) |
+| Theme reads (`({theme}) => theme.sanity...`)        | `createVar()` + `assignInlineVars()` + `useTheme_v2()`                             |
+| Prop-driven variants (`$isInvalid`, `css` branches) | `styleVariants()` or conditional class composition                                 |
+| `keyframes` animations                              | vanilla-extract `keyframes()`                                                      |
+| Descendant selectors (`& img`, third-party classes) | class on the child directly, or `globalStyle()` scoped under a local wrapper class |
+| `createGlobalStyle`                                 | `globalStyle()` (scope it — never leak outside the workspace)                      |
+| `*.styles.tsx` modules                              | replaced by `.css.ts` (+ a component layer where call sites need it)               |
+| Computed inline `style={{}}` objects                | static parts into `style()`, changing values via `createVar()` (Shape C below)     |
+
+Each row's pattern is documented with examples in the
+[styling reference](../sanity-plugin-best-practices/references/styling.md).
+
+## Step 2: Migrate the code
+
+Work component by component. Create a `.css.ts` next to each component and move its rules over. Two
+real shapes cover most cases:
+
+**Shape A — keep the component layer.** When the styled element is used like a component (composed,
+given props), replace it with a `style()` rule plus a thin wrapper that keeps the same name and API,
+so call sites don't change:
+
+```ts
+// FloatingCard.css.ts
+import {style} from '@vanilla-extract/css'
+
+export const floatingCard = style({
+  position: 'fixed',
+  bottom: 0,
+  left: 0,
+  zIndex: 1000,
+})
+```
+
+```tsx
+// FloatingCard.tsx — before: const StyledFloatingCard = styled(Card)`position: fixed; ...`
+import {Card} from '@sanity/ui'
+import {clsx} from 'clsx/lite'
+import type {ComponentProps} from 'react'
+
+import {floatingCard} from './FloatingCard.css'
+
+function StyledFloatingCard({className, ...props}: ComponentProps<typeof Card>) {
+  return <Card {...props} className={clsx(floatingCard, className)} />
+}
+```
+
+Type the wrapper with `ComponentProps<typeof Primitive>` (or `ComponentProps<'div'>`) and never use
+`forwardRef` — `ref` is a regular prop on React 19. **Merge, don't clobber:** a fixed
+`className={floatingCard}` after `{...props}` silently drops a `className` a caller passes in. Pull
+`className` out of props and merge it with `clsx(floatingCard, className)` — prefer
+`import {clsx} from 'clsx/lite'` when only joining strings (the usual case); reach for full `clsx`
+only if you need the object/array API. A `` `${floatingCard} ${className ?? ''}` `` template literal
+also works. See
+[Keep the component layer](../sanity-plugin-best-practices/references/styling.md#keep-the-component-layer-encapsulation).
+
+**Shape B — flatten single-use wrappers.** When the styled element was an internal, single-use
+`styled.div` with no meaningful API, put the class directly on the element. Descendant selectors
+like `& img { ... }` usually migrate best by styling the child directly when you render it yourself:
+
+```tsx
+// Before: <MapDiffImage><img ... /></MapDiffImage> where MapDiffImage = styled.div`& img {...}`
+<img className={mapDiffImage} alt="" src={url} height={280} width={500} />
+```
+
+**Shape C — dynamic values through CSS variables.** When a value varies per instance, with
+props/state, or reads the theme, keep the static parts in `style()` and bridge only the changing
+values through `createVar()` + `assignInlineVars()` (from `@vanilla-extract/dynamic`). This also
+migrates computed inline `style={{}}` objects — hoist the static properties into the `.css.ts` and
+keep only the variables inline:
+
+```ts
+// Checkboard.css.ts
+import {createVar, style} from '@vanilla-extract/css'
+
+export const borderRadiusVar = createVar()
+export const backgroundImageVar = createVar()
+
+export const checkboard = style({
+  borderRadius: borderRadiusVar,
+  position: 'absolute',
+  inset: 0,
+  background: backgroundImageVar,
+})
+```
+
+```tsx
+// Checkboard.tsx — before: <div style={{borderRadius, position: 'absolute', inset: 0, background}} />
+import {assignInlineVars} from '@vanilla-extract/dynamic'
+
+import {backgroundImageVar, borderRadiusVar, checkboard} from './Checkboard.css'
+
+function Checkboard({borderRadius, background}: {borderRadius?: string; background?: string}) {
+  return (
+    <div
+      className={checkboard}
+      style={assignInlineVars({
+        [borderRadiusVar]: borderRadius,
+        [backgroundImageVar]: background ? `url(${background}) center left` : undefined,
+      })}
+    />
+  )
+}
+```
+
+`assignInlineVars` omits `undefined` values, so one class serves every instance. Theme tokens flow
+the same way: read them with `useTheme_v2()` in a small wrapper and assign them to variables.
+
+For everything else — variants (`styleVariants`), keyframes, theming third-party widgets'
+classes, and overriding a `@sanity/ui` primitive's own styles (the `selectors: {'&&': {...}}`
+trick) — follow the corresponding section of the
+[styling reference](../sanity-plugin-best-practices/references/styling.md). Where styled-components
+silently won specificity battles via CSSOM insertion order, you may need `&&` to match the original
+rendering.
+
+Delete the `*.styles.tsx` modules (and their `styled-components` imports) as they empty out.
+
+## Step 3: Switch the build config
+
+In the workspace's `tsdown.config.ts`, drop `styledComponents: true` and add `vanillaExtract: true`:
+
+```ts
+import {defineConfig} from '@sanity/tsdown-config'
+import type {UserConfig} from 'tsdown'
+
+export default defineConfig({
+  reactCompiler: true,
+  vanillaExtract: true,
+}) satisfies Promise<UserConfig>
+```
+
+The integration extracts all `.css.ts` rules into `dist/bundle.css` at build time, auto-imports it
+from `dist/index.js`, and writes/syncs the `./bundle.css` entry in `package.json` `exports` and
+`publishConfig.exports` on every build — nothing to hand-edit there. After the first build the
+export block looks like:
+
+```jsonc
+"./bundle.css": {
+  "types": "./dist/bundle-css.d.ts",
+  "browser": "./dist/bundle.css",
+  "style": "./dist/bundle.css",
+  "node": "./dist/bundle-css.js",
+  "default": "./dist/bundle-css.js"
+}
+```
+
+## Step 4: Update dependencies
+
+In the workspace's `package.json`:
+
+- **Add** dev dependencies `"@sanity/vanilla-extract-vite-plugin": "catalog:"` and
+  `"@vanilla-extract/css": "catalog:"`. Both are build-time only — never runtime `dependencies`.
+  (If the workspace uses `assignInlineVars`, add `"@vanilla-extract/dynamic": "catalog:"` under
+  `dependencies` — that one is a small runtime helper.)
+- **Remove** the `styled-components` entry from `peerDependencies`, and any
+  `babel-plugin-styled-components` devDependency.
+- **Peer alignment:** when the workspace depends on `@sanity/ui` (which peers on styled-components),
+  removing the `"styled-components": "catalog:"` devDependency can make pnpm resolve a separate
+  styled-components copy, forking the workspace's `sanity` peer variant away from the rest of the
+  monorepo and breaking type-aware lint. Dropping it can be fine, but you must verify: after
+  `pnpm install`, the workspace's `sanity` / `@sanity/ui` resolution strings in `pnpm-lock.yaml` must
+  match other workspaces that depend on `@sanity/ui`. If they fork, keep the `catalog:`
+  devDependency.
+
+No `knip.jsonc` or catalog changes are needed — `@vanilla-extract/css` is globally ignored and all
+the catalog entries already exist.
+
+## Step 5: Register the Vite plugin for Vitest
+
+The package-exports test resolves the workspace `exports` map, whose `.` entry points at
+`./src/index.ts` — so it imports real `.css.ts` source and Vitest must compile it. Add the plugin to
+the workspace's `vitest.config.ts`:
+
+```ts
+import {vanillaExtractPlugin} from '@sanity/vanilla-extract-vite-plugin'
+import {defineConfig} from 'vitest/config'
+
+export default defineConfig({
+  plugins: [vanillaExtractPlugin()],
+  // ...existing test config
+})
+```
+
+Use `@sanity/vanilla-extract-vite-plugin` (faster drop-in for the upstream
+`@vanilla-extract/vite-plugin`). If a host app or studio already registers the Vite plugin
+globally, you don't need to touch that file for the workspace under migration.
+
+> **Optional, jsdom-only:** if the workspace has `jsdom`/`happy-dom` suites that don't assert on real
+> CSS (layout, `getComputedStyle`), you can skip runtime style injection with
+> `setupFiles: ['@vanilla-extract/css/disableRuntimeStyles']`. This does **not** replace the Vite
+> plugin, is irrelevant under the default `node` environment, and is opted into per workspace — never
+> monorepo-wide. See
+> [Disabling runtime styles in tests](../sanity-plugin-best-practices/references/styling.md#disabling-runtime-styles-in-tests)
+> in the styling reference.
+
+## Step 6: Build and update the exports snapshot
+
+```bash
+pnpm install
+pnpm build --filter=<workspace-name>
+```
+
+Check the output: `dist/bundle.css` must contain every migrated rule, and `dist/index.js` must
+import it. Then update the package-exports inline snapshot, which gains a `"./bundle.css"` entry:
+
+```bash
+pnpm test -u --project <workspace-name>
+```
+
+## Step 7: Verify
+
+Run the full pre-PR suite (all must pass):
+
+```bash
+pnpm format
+pnpm lint
+pnpm knip
+pnpm build
+pnpm test run
+```
+
+Then verify **visual fidelity** manually: exercise the workspace's UI and compare against the
+pre-migration rendering — theme tokens, spacing, stacking, hover/sticky/fixed behavior. If an
+override no longer takes effect, reach for the `&&` trick rather than `!important`.
+
+Optionally lock the migration in: once the workspace no longer imports `styled-components`, a
+`no-restricted-imports` ban in a workspace-level lint override keeps it from creeping back.
+
+## Step 8: Add a changeset
+
+One patch changeset for the migrated workspace:
+
+```markdown
+---
+'<workspace-name>': patch
+---
+
+Migrate styling from styled-components to vanilla-extract (zero-runtime CSS)
+```
+
+## Checklist
+
+- [ ] Every `styled-components` import in `src/` removed; `.styles.tsx` modules deleted
+- [ ] `.css.ts` files colocated with their components; component layer preserved where call sites
+      need it
+- [ ] `tsdown.config.ts`: `styledComponents` removed, `vanillaExtract: true` added
+- [ ] `package.json`: vanilla-extract devDeps added; `styled-components` peer removed; `sanity` /
+      `@sanity/ui` peer variants verified aligned in `pnpm-lock.yaml`
+- [ ] `vitest.config.ts` registers `vanillaExtractPlugin()`
+- [ ] `dist/bundle.css` emitted with all rules; package-exports snapshot updated
+- [ ] `pnpm format` / `pnpm lint` / `pnpm knip` / `pnpm build` / `pnpm test run` all pass
+- [ ] Visual fidelity verified against the pre-migration rendering
+- [ ] Patch changeset added

.agents/skills/plugin-test-coverage/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: plugin-test-coverage
+description: Guides agents through expanding Vitest and Playwright e2e coverage for a monorepo plugin. Use when adding or improving plugin tests, wiring e2e-studio, or following the internationalized-array / document-internationalization coverage playbook.
+---
+
+# Plugin Test Coverage
+
+Use this skill when expanding **Vitest** and/or **Playwright e2e** coverage for a plugin under `plugins/`.
+
+Reference implementations:
+
+- `@sanity/document-internationalization` — Vitest + e2e under `e2e/tests/document-internationalization/`
+- `sanity-plugin-internationalized-array` — Vitest + e2e under `e2e/tests/internationalized-array/`
+
+Also read [`e2e/README.md`](../../../e2e/README.md) before writing Playwright specs.
+
+## When to use
+
+- Filling unit/integration gaps for a published plugin
+- Wiring a plugin into `dev/e2e-studio` and adding Playwright specs
+- Porting the doc-i18n / internationalized-array coverage process to another plugin
+
+## Workflow
+
+1. **Inventory use cases** from README + source (authoring loops, config knobs, integrations).
+2. **Map each use case** to Vitest (pure logic, components with mocks) vs Playwright (studio UX that needs a real form).
+3. **Fill Vitest gaps** co-located under `plugins/<pkg>/src/` — plugin assembly, context/providers, utils, components.
+4. **Wire e2e-studio** — `definePlugin` example file, register in **both** chromium/firefox workspaces.
+5. **Add helpers + specs** — `e2e/helpers/<plugin>/`, `e2e/tests/<plugin>/`.
+6. **Changesets** — separate patch changeset per published package that gained `data-testid`s or runtime changes. Private e2e/studio files need none.
+7. **Verify** — `pnpm format && pnpm lint && pnpm knip && pnpm build && pnpm test` (and targeted e2e when secrets allow).
+8. **PR** — draft, `🤖 bot` label, inventory + e2e test table in the description.
+
+Skip one-off tooling (migrations, banners) unless they are part of the main authoring loop.
+
+## Vitest patterns
+
+- Co-locate `*.test.ts(x)` next to source; use jsdom via the package `vitest.config.ts`.
+- Shared mocks/fixtures in `src/test/helpers.ts` and `src/test/component-helpers.tsx` (`ThemeWrapper` for `@sanity/ui`).
+- Plugin assembly tests: call the plugin factory, assert schema type names, document layout, form input wrappers, nested plugins.
+- Context/provider tests: mock `useClient` / `useWorkspace` / pane hooks; use `Suspense` + `act` for async `React.use` language resolution; call any module-level `clear()` between tests.
+- Timeouts: `test('name', {timeout: 30_000}, async () => { … })` — options object as second arg.
+- Keep the package-exports snapshot test; update with `pnpm test -u` only when exports intentionally change.
+- React Compiler is on — do not add unnecessary `useMemo` / `useCallback`.
+
+Run a single package:
+
+```bash
+pnpm --filter <package-name> test run
+```
+
+## E2e structure
+
+```
+e2e/
+├── tests/
+│   ├── smoke.spec.ts                 # studio-wide only
+│   └── <plugin-name>/
+│       └── <plugin-name>.spec.ts
+└── helpers/
+    └── <plugin-name>/
+        └── <helpers>.ts
+```
+
+Do not dump plugin specs at the top level of `tests/`.
+
+## E2e-studio wiring
+
+1. Add `dev/e2e-studio/src/<example>.ts` with `definePlugin` that registers schema + the plugin under test.
+2. Import and add it to **both** workspaces in `dev/e2e-studio/sanity.config.ts`.
+3. Ensure the workspace `package.json` already depends on the plugin (`workspace:*`).
+4. Update the “Currently wired” list in `e2e/README.md`.
+
+## Hard-won Playwright lessons
+
+- Project `baseURL` must end with a **trailing slash** (`…/chromium/`, `…/firefox/`).
+- Navigate with **relative** intents: `intent/edit/id=…;type=…`. Never host-absolute `/intent/…` (drops workspace basePath → “Workspace not found”).
+- Auth: Playwright `storageState` seeds `__studio_auth_token_<projectId>`; preflight `/users/me`. Never use `SANITY_DEPLOY_TOKEN` for e2e session auth.
+- Local pitfall: stale server on `:3333` + `reuseExistingServer` → signed-out studio. Kill and restart.
+- Prefer accessible role/name locators; add `data-testid` + a **patch** changeset only when selectors are flaky or ambiguous (e.g. duplicate add-button grids).
+- Seed documents via the Content Lake API; always `try/finally` cleanup.
+- Video: `SANITY_E2E_VIDEO=on` when debugging.
+- Document existence matters: some plugins only auto-seed after `_rev` exists — seed empty persisted docs, don’t rely on brand-new unsaved drafts.
+
+## PR checklist
+
+- [ ] Separate changeset per published package touched
+- [ ] Draft PR with `🤖 bot` label
+- [ ] Use-case inventory + e2e test table in the description
+- [ ] `pnpm format` / `lint` / `knip` / `build` / `test` green
+- [ ] CI e2e (chromium + firefox) green when studio wiring changed
+
+## Pointers
+
+- [`e2e/README.md`](../../../e2e/README.md)
+- [`AGENTS.md`](../../../AGENTS.md) — CI commands, changesets, Node version notes
+- Doc-i18n + internationalized-array as living examples