# Zync OS Visual QA Follow-up Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use /ship or /executing-plans to implement this plan task-by-task. Steps use checkbox syntax.

**Goal:** Make the 24-execution design-system visual gate load built assets correctly and complete predictably within CI bounds.

**Architecture:** Restrict the Vite API proxy to the `/api/` route boundary so root-level `api-*` chunks remain static assets. Use one worker-scoped browser context/page per visual project, navigate once, and reuse the stable showcase session across its three checks. Keep the existing eight projects, full-page screenshot, axe, computed contrast, keyboard/focus, and reduced-motion coverage.

**Tech Stack:** Vite preview, React, Playwright, Node test runner.

## Wave Plan

| Wave | Tasks | Files touched | Safe to parallelize? |
|---|---|---|---|
| 1 | Task 1 | `apps/zync-app/tests/design-system-contract.spec.mjs` | single task |
| 2 | Task 2 | `apps/zync-app/vite.config.ts`, `apps/zync-app/tests/visual/design-system.visual.spec.ts` | blocked by Task 1; same files are intentionally sequential |
| 3 | Task 3 | `docs/specs/2026-07-13-zync-os-qa-round1-design.md`, this plan | blocked by implementation evidence |

## Task 1: Asset/proxy contract

**Wave:** 1
**Blocks:** Task 2
**Files:** Modify `apps/zync-app/tests/design-system-contract.spec.mjs`.

**Contract:** The Vite config MUST expose an API proxy context that matches `/api/` routes only and MUST NOT use the bare `/api` prefix. The contract test MUST fail against the current broad proxy before the implementation change.

**Acceptance:** `pnpm --filter zync-app test -- tests/design-system-contract.spec.mjs` passes with the new boundary assertion.

## Task 2: Routing and suite architecture

**Wave:** 2
**Blocks:** Task 3
**Files:** Modify `apps/zync-app/vite.config.ts` and `apps/zync-app/tests/visual/design-system.visual.spec.ts`.

**Contract:**

- `/api/` requests retain the existing backend proxy target; `/api-usage-*.js` and other root-level built assets MUST bypass the proxy and load with HTTP success.
- Each Playwright project MUST create one worker-scoped context/page with its project viewport, theme, locale, and base URL, install diagnostics before navigation, and open `/design-system` once.
- The three existing test behaviors remain separate assertions over the shared page; no variant, check, warning/error diagnostic, reduced-motion setting, or screenshot baseline is removed.
- The full-page baseline remains authoritative unless measured repeated clean runs show instability attributable to image size; semantic section segmentation may be introduced only with equivalent complete coverage and no weakened comparison.

**Acceptance:** The isolated mounted visual command completes all 24 tests, with zero page errors, console warnings/errors, failed requests, or web-server proxy errors.

## Task 3: Spec reconciliation

**Wave:** 3
**Blocks:** —
**Files:** Modify `docs/specs/2026-07-13-zync-os-qa-round1-design.md` and this plan if the final architecture differs from the contract.

**Contract:** Document the `/api/` proxy boundary, one-navigation-per-project fixture, and evidence-based full-page baseline decision as the visual gate’s required architecture. Keep the eight exact viewport/theme/direction variants and all accessibility/interaction requirements explicit.

**Acceptance:** `git diff --check` passes and the spec contains no requirement that contradicts the implementation.

## Verification

- Clean-build isolated visual suite twice consecutively; record duration and exact 24/24 result for each run.
- Run design-system contract tests, scoped app typecheck, scoped app lint, and the app build.
- Run the final diff check and inspect server output for zero warnings/errors.