git:20260610.3c92643 to git:20260614.c06aaf7

---

name: theme-update

description: "Safely update a Weaverse Pilot theme to the latest version — detects current version, fetches release diffs, plans changes category-by-category, preserves customizations, verifies build."

---

# Theme Update — Weaverse Pilot

Safely upgrade a Weaverse Pilot theme from its current version to a newer release. This skill walks through detection, planning, execution, and verification — never overwriting user customizations without explicit approval.

## Source

- Theme repo: https://github.com/Weaverse/pilot

- Releases: https://github.com/Weaverse/pilot/releases

- Package name: `@weaverse/pilot`

- Versioning: `YYYY.M.D` (e.g., `2026.4.7`). Older: semver (`v8.1.0`)

## Quick Check

```bash

node skills/theme-update/scripts/check_pilot_updates.mjs

node skills/theme-update/scripts/check_pilot_updates.mjs --target v2026.4.7

```

---

## Procedure

Follow these phases in order. Do NOT skip steps.

### Phase 1 — Detection

1. Read `package.json` → get `version` field

2. If `name` is not `@weaverse/pilot`, ask the user to confirm this is a Pilot-based project

3. Fetch releases:

```bash

curl -s "https://api.github.com/repos/Weaverse/pilot/releases?per_page=50"

```

4. Identify all releases between current version and latest (or user-specified target)

5. Present to user:

- Current version

- Target version (latest unless specified)

- Number of intermediate releases

- Summary of key changes (features, fixes, breaking changes)

**If already on latest → stop here and tell the user.**

### Phase 2 — Branch

```bash

git checkout -b update/v{CURRENT}-to-v{TARGET}

git push -u origin update/v{CURRENT}-to-v{TARGET}

```

Always work on a branch. Never update on main directly.

### Phase 3 — Plan

For each release in the update range (oldest to newest):

1. **Fetch the diff** between consecutive versions:

```bash

# Full comparison URL

https://api.github.com/repos/Weaverse/pilot/compare/v{OLD}...v{NEW}

# Raw diff

https://github.com/Weaverse/pilot/compare/v{OLD}...v{NEW}.diff

```

2. **Download the target version's source** (for reference files):

```bash

curl -sL "https://api.github.com/repos/Weaverse/pilot/tarball/v{TARGET}" | tar xz

```

3. **Categorize every changed file** into three buckets:

#### Auto-merge (safe to apply without asking)

- `package.json` version bump, dependencies

- Lock files (`package-lock.json`, `bun.lockb`, `pnpm-lock.yaml`)

- `tsconfig.json`, `vite.config.ts`, `tailwind.config.ts` — ONLY if user hasn't customized them

- New files that don't exist in user's project (additive only)

- `.github/`, `CHANGELOG.md`, `LICENSE`

#### Needs review (show diff, get approval)

- `app/components/` — UI components user may have customized

- `app/routes/` — route files user may have modified

- `app/lib/` — utility modules

- `app/root.tsx`, `app/entry.client.tsx`, `app/entry.server.tsx`

- `app/styles/` — CSS/Tailwind changes

- Any file where the user has local changes (`git diff` shows modifications from Pilot base)

#### Skip (mention but don't touch)

- Files the user deleted (they removed the feature intentionally)

- Files in directories the user reorganized

- `.env`, `.env.example` — never overwrite environment files

4. **Present the plan** in a clear table:

```

## Update Plan: v2026.3.23 → v2026.4.7

### Auto-merge (3 files)

✅ package.json — version + dependency bumps

✅ bun.lockb — lock file update

✅ app/lib/utils.ts — new helper function added

### Needs Review (5 files)

⚠️ app/components/Header.tsx — Pilot added shopify-account web component

Your version: custom mega menu logic

Pilot change: replaced AccountButton with <shopify-account>

→ Recommend: keep your mega menu, add shopify-account separately

⚠️ app/routes/_index.tsx — performance improvements

Your version: added custom hero section

Pilot change: caching + skeleton loading

→ Recommend: apply caching, keep your hero

### New Files (2 files)

➕ app/components/ScrollReveal.tsx — new scroll animation component

➕ app/lib/reviews.ts — extracted reviews API

### Skipped (1 file)

⏭️ app/components/CombinedListings.tsx — you deleted this file

```

**Wait for user confirmation before proceeding.** Ask:

> "Review the plan above. Approve to continue, or tell me which files to handle differently."

### Phase 4 — Execute

Apply changes in order, one release at a time if multi-version jump:

#### 4a. Auto-merge files

```bash

# Copy new file from Pilot source

cp /tmp/pilot-reference/{FILE_PATH} {FILE_PATH}

# Or apply targeted patch

git apply --3way <patch-file>

```

After each auto-merge, verify with `git diff --stat`.

#### 4b. Needs-review files

For each file:

1. Show a **three-way comparison**:

- Pilot at user's version (baseline)

- Pilot at target version (their changes)

- User's current file (local modifications)

2. Identify what the user changed vs what Pilot changed:

- User-only changes → preserve

- Pilot-only changes → apply

- Overlapping changes → flag conflict

3. For conflicts, present options:

- Accept Pilot's version (lose user customization)

- Keep user's version (skip Pilot improvement)

- Manual merge (show both, let user edit)

- Smart merge (try to combine both — only if non-overlapping regions)

4. Wait for user decision on each conflict before proceeding.

#### 4c. Commit per release

```bash

git add -A

git commit -m "chore: update Pilot v{OLD} → v{NEW}

- [list key changes applied]

- [list files with manual merge decisions]

"

```

If doing multi-version jump, repeat for each intermediate release.

### Phase 5 — Verify

After all changes applied:

```bash

# 1. Install dependencies

bun install # or npm install / pnpm install based on lockfile

# 2. TypeScript check

bun run typecheck

# 3. Build check

bun run build

```

**If build fails:**

1. List the errors

2. Analyze root cause (dependency mismatch? breaking change missed?)

3. Propose fixes

4. Apply fixes with user approval

5. Re-run build

**If build succeeds:**

1. Run `bun run dev` briefly to check no runtime errors

2. Summarize all changes made

3. List any **manual follow-up steps**:

- New features that need configuration

- Breaking changes requiring code updates in customized files

- Deprecated patterns to migrate later

### Phase 6 — Finalize

1. Present final summary:

```

## Update Complete: v2026.3.23 → v2026.4.7

✅ 12 files auto-merged

✅ 5 files reviewed and merged

✅ 2 new files added

✅ Build passes

✅ TypeCheck passes

### New features available

- Shopify Account Web Component (<shopify-account>)

- Vite chunk splitting for better caching

- ScrollReveal component for animations

### Manual follow-up (optional)

- Configure shopify-account in your Header if you want native sign-in

- Review ScrollReveal component for use in custom sections

### Rollback

git checkout main

git branch -D update/v2026.3.23-to-v2026.4.7

```

2. Ask user: "Ready to merge into main?"

```bash

# If approved

git checkout main

git merge update/v{CURRENT}-to-v{TARGET}

git push origin main

```

---

## Safety Rules

1. **Always branch first** — never update on main directly

2. **Never overwrite without asking** — every file that could have user changes needs review

3. **Commit per release** — easy to bisect if something breaks

4. **Build must pass** — don't declare success until `typecheck` + `build` both pass

5. **Offer rollback** — always tell user how to undo the whole update

6. **Respect user deletions** — if they removed a file, don't re-add it without asking

## Common Pitfalls

- **Version format**: package.json has no `v` prefix (`2026.4.7`), GitHub tags have `v` prefix (`v2026.4.7`). Always normalize.

- **Lock files**: After updating `package.json`, MUST run the correct package manager (check which lockfile exists)

- **Custom components**: User components not in original Pilot are always preserved — never delete or move them

- **Route structure**: If user reorganized routes, don't force Pilot's structure — apply route logic changes to user's structure instead

- **CSS conflicts**: Pilot may change Tailwind classes or base styles — these need careful merge to avoid breaking user styling

## SDK-Only Bumps (`@weaverse/hydrogen`)

Sometimes the ask is only "update the Weaverse SDK", not a full theme update. Verified procedure (used for a 5.5.0 → 5.15.1 client jump):

1. **Baseline before bumping.** Run `npx react-router typegen && npm run typecheck` on the CURRENT version and record every error (client forks usually have pre-existing failures). After the bump, diff against this baseline — you only own the delta. Without the baseline you'll chase errors that were always there.

3. **Known break at 5.15**: `errorComponent` is typed `FC<{ error: unknown }>` (was an Error-like object). Port upstream Pilot's `GenericError`, which narrows at runtime (`error && typeof error === "object" && "message" in error`).

4. Finish with full `shopify hydrogen build --codegen` — typecheck alone misses bundler-level issues.

## Weaverse-Internal: Pilot Lock & Demo Deploy

- Pilot lives inside the Weaverse pnpm monorepo but ships an **npm** lockfile. Refresh it with `npm i --package-lock-only --workspaces=false`; plain `npm i` fails on the monorepo's `catalog:` protocol.

- Deploying `pilot.weaverse.dev`: merge to `Weaverse/pilot` `main`, then `gh repo sync Weaverse/pilot-demo --source Weaverse/pilot` — the fork carries the Oxygen deploy action and ships on sync (~1 min).