---
name: upgrade-lightweight-charts-android
description: Use when upgrading the TradingView lightweight-charts Android wrapper across upstream JavaScript lightweight-charts versions, checking version deltas, API parity, bridge changes, examples, tests, docs, or migration risk.
---

# Upgrade Lightweight Charts Android

## Overview

Use this for end-to-end upgrades of the Android wrapper around upstream JavaScript `lightweight-charts`. Success requires source-backed API research, scoped implementation, compatibility decisions, and verification evidence—not just a version bump.

## When to Use

- Upgrading `lightweightlibrary/package.json` to a newer `lightweight-charts` release.
- Reviewing wrapper parity after upstream major/minor releases.
- Planning or changing Kotlin APIs, JS bridge code, serializers, examples, Gradle/WebView assets, docs, or migration notes caused by upstream changes.

Do not use for Android dependency upgrades unrelated to `lightweight-charts`.

## Companion Workflow

- Use official upstream docs, release notes, package typings, and source checks for upstream API research. If your Codex environment has a source/research skill, it can help, but this skill must remain usable without one.
- Use a written plan before non-trivial implementation.
- Use fresh verification evidence before claiming upgrade success.
- **RECOMMENDED:** Use code review skills before merge when bridge/API surfaces change.

## Workflow

1. **Inspect first.** Locate `lightweightlibrary/package.json` and `app/src/main`; do not assume a checkout path. Run `git status --short --untracked-files=all` and protect unrelated user changes.
2. **Discover versions.** Run `scripts/inspect_versions.py <repo-root>` from this skill. Add `--npm-latest` only when shell network access is available. Verify “latest” live through npm, GitHub releases, and official docs when network state matters.
3. **Inventory deltas.** Compare releases from current to target. Audit package typings/source and wrapper surfaces for chart, series, panes, time/price scales, markers, watermarks, localization/formatters, options, events, and generated assets.
4. **Plan non-trivial work.** Include target version, release delta, Kotlin API, JS bridge, serialization, examples, tests, docs, compatibility/deprecation choices, unsupported custom/plugin internals, risks, and commands.
5. **Implement in slices.** Update package/lock files through the package manager, bridge imports, caches/managers for stable handles, Kotlin interfaces/delegates/models/enums/serializers, examples, docs, tests, and generated assets.
6. **Verify with evidence.** Run JS package scripts after bridge changes, Android tests/builds after Kotlin/example changes, and inspect generated WebView assets when asset loading changes.

## Migration Checklist

- Dependency/build/runtime: npm version, lockfile, module format, webpack, Node/WebView compatibility, generated assets.
- APIs: chart, series, panes, time scale, price scale, event payloads, options, localization, formatter hooks.
- Built-ins: markers, watermarks, new chart modes, horizontal-scale entry points that do not require custom behavior authoring.
- Examples, tests, docs, compatibility/deprecation strategy, rollout risks.

## Guardrails

- Prefer official upstream docs, package typings, and source over secondary summaries.
- Treat “latest” as unstable; verify it live or state that it could not be checked.
- Do not hand-wave parity. Search typings and wrapper interfaces, then add focused tests for important claims.
- Do not replace an existing public Kotlin signature with a narrower/newer type unless a deprecated compatibility overload remains.
- Preserve existing callback style and wrapper naming unless the migration intentionally breaks API.
- Bridge source changes require package script runs and generated `src/main/assets/.../main.js` review.
- Do not expose generic custom plugins, custom series, or custom primitives unless explicitly scoped.
- Use portable paths in plans/docs; do not use machine-specific absolute paths.
- Do not revert unrelated dirty worktree changes.

## Validation Scenarios

| Scenario | Expected behavior |
| --- | --- |
| “Update wrapper to latest lightweight-charts” | Verifies latest live, compares local version, inventories upstream deltas, plans before implementation. |
| “Make v5 panes work” | Checks upstream typings/docs and wrapper bridge/Kotlin/example surfaces before coding. |
| “Replace old API with new v5 type” | Preserves source compatibility with deprecated overloads when feasible. |
| Dirty worktree with unrelated files | Lists and avoids unrelated changes. |

## Common Mistakes

| Mistake | Fix |
| --- | --- |
| Bumping npm version only | Inventory release deltas and wrapper parity before declaring success. |
| Trusting stale local checkout | Verify npm/GitHub/docs live or state that latest could not be checked. |
| Exposing upstream custom internals by default | Defer custom plugins/series/primitives unless explicitly scoped. |
| Forgetting generated assets | Run package scripts and include expected asset diffs. |
| Breaking Kotlin source compatibility | Add deprecated compatibility overloads or document intentional breakage. |