If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tencent/Hippy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 2w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tencent/Hippy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/Hippy.

What it runs against: a local clone of Tencent/Hippy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tencent/Hippy | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 47 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/Hippy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/Hippy.git
#   cd Hippy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tencent/Hippy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tencent/Hippy(\\.git)?\\b" \\
  && ok "origin remote is Tencent/Hippy" \\
  || miss "origin remote is not Tencent/Hippy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "build.gradle" \\
  && ok "build.gradle" \\
  || miss "missing critical file: build.gradle"
test -f ".github/workflows/android_build_tests.yml" \\
  && ok ".github/workflows/android_build_tests.yml" \\
  || miss "missing critical file: .github/workflows/android_build_tests.yml"
test -f ".github/workflows/frontend_build_tests.yml" \\
  && ok ".github/workflows/frontend_build_tests.yml" \\
  || miss "missing critical file: .github/workflows/frontend_build_tests.yml"
test -f "buildconfig/cmake/GlobalPackagesModule.cmake" \\
  && ok "buildconfig/cmake/GlobalPackagesModule.cmake" \\
  || miss "missing critical file: buildconfig/cmake/GlobalPackagesModule.cmake"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 47 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~17d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tencent/Hippy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Hippy is a cross-platform development framework that lets developers write JavaScript/TypeScript once (using React or Vue) and deploy to iOS, Android, Web, and other platforms. It compiles to native code with a JS engine binding layer, enabling apps like Mobile QQ, Tencent Video, and QQ Music to reach hundreds of millions of users while maintaining write-once performance. Monorepo architecture: core/ contains the C++/Java VM binding layer and layout engine (using Tencent's taitank flex layout); driver/ has platform implementations (iOS, Android, Web); modules/ provides recyclable UI components; examples/ contains React/Vue demo apps; separate devtools/, docs/, and build/ directories.

Web developers (especially React/Vue specialists) at enterprises like Tencent who need to ship mobile apps without maintaining separate native codebases. Also contributes from native engineers (C++, Kotlin, Objective-C) who implement platform-specific bridges.

Production-ready and actively maintained. The project is in heavy use across Tencent's major apps, has comprehensive CI/CD (40+ GitHub Actions workflows), extensive native SDKs (iOS, Android, Dart), and consistent recent commits. The polyglot codebase (4.4M C++, 2.3M Java, 1.7M TypeScript lines) indicates significant engineering investment.

Low-to-medium risk for new adopters: the framework is battle-tested at scale, but documentation and community support are primarily in Chinese, making troubleshooting harder for Western teams. The monorepo complexity (C++, Java, TypeScript, Dart, Objective-C in one repo) means local builds require Android NDK + Xcode + Node.js, creating high onboarding friction.

Active development evident from 50+ GitHub Actions workflows (v8 prebuilts, SQLite 3rd-party builds, Android/iOS/Voltron test matrices). Workflows for PR auto-merging, license checking, CodeQL security analysis, and artifact snapshot/release suggest ongoing release cadence and security hardening.

git clone https://github.com/Tencent/Hippy.git
cd Hippy
git lfs install && git lfs pull  # Required for .so, .gz, .otf files
npm install
# For iOS: cd examples/hippy-react-demo && npm run build:ios
# For Android: cd examples/hippy-react-demo && npm run build:android

Daily commands: After npm install: npm run build (compiles TypeScript), then platform-specific: iOS simulator: cd examples/hippy-react-demo && npm run build:ios && open build/HippyDemo.xcodeproj; Android: npm run build:android (requires Android Studio + NDK); Web: npm run dev:web.

• README.md — Framework overview and getting started guide—defines Hippy's cross-platform value proposition and architectural intent
• build.gradle — Root Gradle configuration managing Android build and dependency resolution across the entire project
• .github/workflows/android_build_tests.yml — CI/CD pipeline for Android builds—enforces quality gates and integration test coverage
• .github/workflows/frontend_build_tests.yml — CI/CD pipeline for frontend/JS builds—validates cross-platform JavaScript transpilation and bundling
• buildconfig/cmake/GlobalPackagesModule.cmake — CMake configuration for native module management—coordinates C++ compilation across iOS, Android, and Linux targets
• devtools/devtools-backend/include/api/adapter/devtools_common_protocol_adapter.h — Core debugging protocol adapter—enables IDE integration and runtime inspection for all platforms
• .github/CONTRIBUTING.md — Contribution guidelines and development workflow—establishes code review and commit standards for maintainers

Add a new native module binding for iOS/Android

1. Create module header in C++ following the Hippy bridge API contract (devtools/devtools-backend/include/api/adapter/devtools_common_protocol_adapter.h)
2. Add Android JNI bindings referencing the build.gradle module structure (build.gradle)
3. Configure iOS target in CMake toolchain with cross-compilation flags (buildconfig/cmake/ios.toolchain.cmake)
4. Register module in CMake global packages configuration (buildconfig/cmake/GlobalPackagesModule.cmake)
5. Update CI pipeline to compile and test the new binding on both platforms (.github/workflows/android_build_tests.yml)

Add a new DevTools inspection capability

1. Define new data structure in devtools-backend/include/api/adapter/data/ following existing metas patterns (devtools/devtools-backend/include/api/adapter/data/serializable.h)
2. Extend the protocol adapter to serialize and transmit the new inspection data (devtools/devtools-backend/include/api/adapter/devtools_common_protocol_adapter.h)
3. Add corresponding DOM or render tree adapter method if inspecting UI hierarchy (devtools/devtools-backend/include/api/adapter/devtools_dom_tree_adapter.h)
4. Update frontend build tests to validate DevTools message serialization (.github/workflows/frontend_build_tests.yml)

Modify build process for a new target platform

1. Create platform-specific CMake toolchain following iOS/Android patterns (buildconfig/cmake/compiler_toolchain.cmake)
2. Add platform dependencies to the global CMake module configuration (buildconfig/cmake/GlobalPackagesModule.cmake)
3. Update root Gradle configuration if platform uses JVM/Android components (build.gradle)
4. Create GitHub Actions CI workflow following existing android_build_tests.yml and ios_build_tests.yml patterns (.github/workflows/android_build_tests.yml)
5. Document platform setup and build instructions in CONTRIBUTING.md (.github/CONTRIBUTING.md)

• Gradle (Android) + CMake (Native) — Decouples Android JVM build from cross-platform C++ native code; CMake provides iOS/Linux/Web flexibility without runtime JVM dependency
• GitHub Actions workflows — Vendor-agnostic CI/CD with matrix builds for iOS/Android/Web in parallel; Git-native trigger reduces operational overhead
• Chrome DevTools Protocol (devtools-backend) — Industry-standard debugging protocol enables IDE integration and live inspection without custom tooling per platform
• Docker build environments — Reproducible isolated builds reduce machine-local drift; enables distributed CI scaling without per-developer setup
• Husky + commitlint — Enforces semantic versioning and changelog discipline at commit time; reduces release merge conflicts and automates CHANGELOG generation

• Separate Android Gradle + cross-platform CMake instead of unified Kotlin multiplatform

  • Why: Tencent's existing Android infrastructure and need to support Web/Linux separately without JVM
  • Consequence: Developers must maintain two build systems; coordination overhead during shared library updates

• Git-based workflows with Husky pre-commit hooks instead of ticket-driven releases

  • Why: Fast iteration on cross-platform fixes; commit semantics drive artifact versioning automatically
  • Consequence: Requires strict discipline; a single malformed commit can block CI for all platforms

• DevTools protocol adapter in C++ headers vs. runtime protocol negotiation

  • Why: Compile-time safety and minimal inspect overhead; protocol version locked to build
  • Consequence: Cannot hot-swap debugger versions; mismatched DevTools client may fail silently

• Matrix workflows (iOS/Android/Web) in parallel vs. serialized gates

  • Why: Fast feedback on platform-specific regressions; developers see Android JNI errors before iOS build finishes
  • Consequence: Higher CI resource usage; requires artifact caching to avoid redundant compilations

• Does not provide managed cloud hosting or backend-as-a-service for Hippy apps
• Does not include a visual UI builder or drag-and-drop IDE (developers write React/Vue code)
• Does not support real-time collaborative editing within the framework
• Does not abstract operating system APIs beyond JavaScript bridge (native permissions, file I/O require platform-specific code)
• Does not provide automatic performance optimization or code splitting (developer responsibility)

git-lfs required: .so, .gz, .otf files are LFS-tracked; skipping git lfs install causes silent build failures. NDK + Xcode mandatory: local Android/iOS builds require specific NDK version (check workflow configs in .github/workflows/) and Xcode 13.2+. V8 prebuilts are massive: 3rd party v8 binaries are cached by CI; first local build downloads 500MB+. Platform-specific build oddities: iOS uses CocoaPods (see driver/ios/Podfile), Android uses Gradle AAR fat plugin (classpath 'com.github.kezong:fat-aar:1.3.8'), and Web build differs from native due to Metro vs Webpack split. No Windows iOS support: Workflows and docs explicitly exclude Windows from iOS builds.

• JS Engine Binding (JNI/FFI) — Hippy's core innovation—the bridge between V8/JSC and native code (Java, Objective-C) is what enables near-native performance vs. WebView approaches; understanding JNI bindings in core/napi/ is essential to contributing
• Flex Layout Engine (Yoga/taitank) — Hippy uses taitank (not Meta's Yoga) for CSS-like layout calculation; critical for understanding how LayoutNode calculations happen without native SDK layouts
• JSI (JavaScript Interface) — Similar concept to React Native's JSI—a synchronous bridge allowing JS to call native code directly; Hippy implements this via C++ bindings in core/napi/
• Monorepo with Multi-Language Build Systems — This repo mixes CMake (C++), Gradle (Java), CocoaPods (Objective-C), npm (TypeScript), and Dart—understanding each build system's role is critical for troubleshooting local builds
• Platform Driver Architecture — Each platform (iOS, Android, Web, Dart) implements a Driver interface; this abstraction allows new platform support by implementing a new driver—key to understanding extensibility
• Ahead-of-Time (AOT) vs. Just-in-Time (JIT) Compilation — Hippy's use of V8 involves both JIT compilation strategies and AOT snapshot bundling; understanding the performance tradeoff is important for optimization contributions
• Recyclable View Pattern — Hippy's built-in recyclable list/grid components (similar to Android RecyclerView) are mentioned as a key performance advantage; examine modules/ for how view recycling avoids DOM churn

• facebook/react-native — Direct competitor with similar write-once-run-anywhere philosophy; same React paradigm but different native bridge architecture
• flutter/flutter — Alternative cross-platform framework using Dart instead of JS; used by Hippy's own Dart driver but different compilation model
• Tencent/taitank — Sibling Tencent repo providing the flex layout engine that Hippy depends on; essential for understanding Hippy's layout system
• ionic-team/ionic — Web-first cross-platform approach using Cordova/Capacitor; contrasts with Hippy's native-first JS binding strategy
• apache/cordova-android — Legacy cross-platform framework that influenced WebView-based approaches; helps understand why Hippy's V8 binding is faster

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for Hippy JavaScript/TypeScript utilities

The repo has extensive GitHub Actions for Android, iOS, and frontend builds, but there's no dedicated workflow file for JavaScript unit tests. Given that Hippy is a cross-platform framework with complex frontend logic (evidenced by frontend_build_tests.yml), adding a focused unit test suite with coverage reporting would catch regressions early. This is critical for a framework that compiles to multiple platforms.

• [ ] Create a new GitHub Actions workflow: .github/workflows/frontend_unit_tests.yml
• [ ] Add Jest configuration and test scripts to frontend package.json files
• [ ] Implement unit tests for core utilities in the frontend/packages directory (starting with the most complex modules)
• [ ] Integrate coverage reporting with existing Codecov badge setup
• [ ] Add test results to PR checks in gh_pr_checks_approval.yml

Add missing platform-specific build documentation and workflow status matrix

The repo has 27+ workflow files for different platforms (Android, iOS, V8, SQLite) but no centralized status dashboard or troubleshooting guide. New contributors can't easily understand which workflows apply to which platforms or how to debug failed builds. The README snippet is incomplete, suggesting documentation gaps.

• [ ] Create docs/BUILD_MATRIX.md documenting each workflow file's purpose, trigger conditions, and supported platforms
• [ ] Add troubleshooting section for common Android build failures in docs/ (reference android_build_tests.yml patterns)
• [ ] Document the fat-aar build process used by Hippy in docs/ANDROID_BUILD_GUIDE.md
• [ ] Create a workflow status summary in docs/CI_STATUS.md showing which checks are required for merges
• [ ] Link from CONTRIBUTING.md to these new documentation files

Implement Dependabot/automated security patching for Gradle and NPM dependencies

The repo has security_codeql_analyses.yml but no proactive dependency update workflow. The build.gradle snippet shows static versions (gradle 7.2.2, kotlin 1.8.21) that may have vulnerabilities. The powermock and mockito versions are from 2018-2020. Adding automated dependency scanning and PR creation would improve supply chain security for a framework used by many downstream applications.

• [ ] Create .github/workflows/dependency_updates.yml to run Dependabot (or Renovate) on schedule
• [ ] Add dependabot.yml in .github/ directory to auto-update gradle, kotlin-gradle-plugin, and all testing dependencies
• [ ] Configure automatic PR creation with security labels for vulnerable dependencies
• [ ] Integrate with gh_pr_auto_merger.yml to auto-merge patch-level dependency updates
• [ ] Document dependency maintenance process in CONTRIBUTING.md

• Add missing unit tests for driver/js/types/animation.ts—currently no test file exists in test/ for animation type definitions; good way to learn the testing setup.
• Improve TypeScript strict mode compliance in packages/hippy-web—several .ts files have // @ts-ignore comments that could be resolved by fixing types; great for understanding the web driver integration.
• Document the V8 prebuilt workflow**: .github/workflows/3rd_prebuilt_v8.yml exists but is not explained in README or contributing guide; add a developer doc explaining when/how it runs and how to troubleshoot prebuilt mismatches.

The Hippy project's build configuration contains several security concerns primarily related to outdated dependencies that may have known vulnerabilities. The most critical issues are: (1) outdated Android Gradle Plugin (7.2.2), (2) outdated testing frameworks (Mockito 2.x, PowerMock 2.0.9), and (3) overly aggressive dependency caching that bypasses security checks. The incomplete dependency declarations and lack of dependency verification further increase security risks. Immediate action is needed to update all dependencies to current stable versions and implement proper dependency verification mechanisms. The codebase also lacks explicit security scanning and dependency audit configurations in the visible build setup.

• High · Outdated Gradle Build Tools — build.gradle (buildscript dependencies). The build.gradle file specifies gradle version 7.2.2, which is outdated. This version may contain known security vulnerabilities and lacks important security patches. Fix: Update to the latest stable version of Android Gradle Plugin (currently 8.1.x or later). Review gradle release notes for security patches.
• High · Outdated Kotlin Gradle Plugin — build.gradle (classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:1.8.21'). Kotlin Gradle Plugin version 1.8.21 is outdated and may contain security vulnerabilities. Current stable versions are 1.9.x or later. Fix: Update Kotlin Gradle Plugin to the latest stable version (1.9.20+). Review changelog for security fixes.
• High · Outdated Mockito Dependencies — build.gradle (ext.deps: mockito_core, mockito_android). Mockito versions 2.28.2 and 2.18.3 are outdated and may have known vulnerabilities. These are significantly behind the current stable version (5.x). Fix: Update to Mockito 5.x or latest stable version. Verify compatibility with your test infrastructure.
• High · Outdated PowerMock Dependencies — build.gradle (ext.deps: powermock_module_junit, powermock_api_mockito2, powermock_core). PowerMock version 2.0.9 is outdated and may contain security vulnerabilities. The library has not received updates in several years. Fix: Consider migrating away from PowerMock to modern alternatives like Mockito 4+ or JUnit 5 extensions. If must use, update to latest available version.
• Medium · Short Dependency Cache Expiry — build.gradle (resolutionStrategy.cacheChangingModulesFor and resolutionStrategy.cacheDynamicVersionsFor). The build configuration sets very aggressive caching policies with 1 second expiry for both changing and dynamic modules. This may bypass security checks and make the build vulnerable to dependency substitution attacks. Fix: Increase cache duration to reasonable values (e.g., 1 hour for changing modules, 24 hours for dynamic versions) or use explicit dependency pinning and verification.
• Medium · Incomplete Dependency Declaration — build.gradle (ext.deps: powermock_core). The 'powermock_core' dependency declaration in ext.deps appears to be truncated/incomplete in the provided file. This could indicate incomplete dependency management or maintenance issues. Fix: Complete the dependency declaration and verify all dependencies are fully specified. Run 'gradle dependencies' to ensure all transitive dependencies are accounted for.
• Medium · Missing Dependency Verification — build.gradle (global configuration). No evidence of dependency verification or signature validation in the gradle configuration. This makes the build susceptible to supply chain attacks. Fix: Implement dependency verification using gradle's built-in verification metadata. Add checksum verification for critical dependencies.
• Low · Multiple Repository Sources — build.gradle (repositories configuration). Dependencies are fetched from multiple repositories (google() and mavenCentral()). While not inherently dangerous, this increases attack surface if any repository is compromised. Fix: Use repository filtering and consider implementing a private artifact repository/proxy to control and audit dependency sources.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.