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/VasSonic 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.

WAIT — Stale — last commit 3y ago

• 10 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Other licensed
• ⚠ Stale — last commit 3y ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected
• ⚠ 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/VasSonic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tencent/VasSonic.

What it runs against: a local clone of Tencent/VasSonic — 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/VasSonic | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1157 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tencent/VasSonic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tencent/VasSonic.git
#   cd VasSonic
#
# 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/VasSonic and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "sonic-android/build.gradle" \\
  && ok "sonic-android/build.gradle" \\
  || miss "missing critical file: sonic-android/build.gradle"
test -f "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicEngine.html" \\
  && ok "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicEngine.html" \\
  || miss "missing critical file: sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicEngine.html"
test -f "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSession.html" \\
  && ok "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSession.html" \\
  || miss "missing critical file: sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSession.html"
test -f "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnection.html" \\
  && ok "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnection.html" \\
  || miss "missing critical file: sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnection.html"
test -f "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicDBHelper.html" \\
  && ok "sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicDBHelper.html" \\
  || miss "missing critical file: sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicDBHelper.html"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1157 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1127d)"
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/VasSonic"
  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).

VasSonic is a hybrid framework that accelerates Android/iOS web view first-screen rendering by splitting HTML into template (static) and data (dynamic) sections, then streaming and caching them separately. It uses custom URL interception to request resources in parallel with WebKit rendering, reducing perceived load time through incremental DOM updates rather than waiting for full HTML. Monorepo structure: sonic-android/ (Java SDK + sample), sonic-iOS/ (Objective-C), sonic-nodejs/, sonic-php/, sonic-react/, sonic-java/ are separate platform implementations. Core modules in Android: src/com/tencent/sonic/sdk/ contains SonicEngine, SonicSession, SonicSessionConnection, SonicCacheInterceptor. Assets include specification docs (Sonic2.0.md, 3.0_preload.md) and architecture diagrams.

Mobile app developers (Android Java, iOS Objective-C) building hybrid applications who need to serve dynamic web content faster. Backend engineers (PHP, Node.js, Java, React) implementing the server-side Sonic specification to segment templates and data in their HTML responses.

Production-ready; Tencent VAS team built this for their own high-traffic mobile properties. The codebase shows maturity with 451K LOC Java, 235K Objective-C, comprehensive docs in sonic-android/docs/, and sample apps. However, the repo lacks visible commit timestamps and CI badge—check GitHub release dates and last commit to confirm active maintenance.

Moderate risk: platform-specific implementation (Android/iOS separately) means cross-platform bug fixes require dual coordination. No visible unit test directory in the file list, raising test coverage concerns. Multi-language support (Java, Objective-C, PHP, Node.js, React) creates maintenance burden. Single Tencent organization ownership suggests limited external contribution velocity.

Cannot determine from file metadata alone—no commit log visible. Check GitHub's commit history and releases page. Docs mention Sonic 3.0 preload optimization (assets/VasSonic3.0_preload.md) and subresource preload (assets/subresource_preload.png), suggesting active feature development around resource prefetching.

git clone https://github.com/Tencent/VasSonic.git
cd VasSonic/sonic-android
# Install Android SDK, then:
./gradlew build
./gradlew installDebug  # Deploy sample app to emulator/device

For PHP/Node.js servers, see sonic-php/ and sonic-nodejs/ README files.

Daily commands:

# Android sample app
cd sonic-android
./gradlew build
# Open sonic-android/app or sample/ in Android Studio, run on AVD/device

# For server-side test, see sonic-php/, sonic-nodejs/ for sample endpoints
cd sonic-nodejs
npm install
node server.js

• sonic-android/build.gradle — Root build configuration defining Gradle versions, Android plugin, and build plugins for the entire Android SDK—essential for understanding the build system and dependency management.
• sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicEngine.html — Core engine documentation; SonicEngine is the main entry point and orchestrator for the Sonic framework, managing sessions and resource caching.
• sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSession.html — Primary session abstraction; SonicSession handles the HTTP request/response lifecycle and template-data separation logic central to Sonic's architecture.
• sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnection.html — Network connection layer; manages custom URL connections to enable parallel resource fetching and partial rendering before full page load.
• sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicDBHelper.html — Local cache persistence layer; handles storage and retrieval of cached HTML templates and data, critical for offline support.
• sonic-android/sample/src/main/java/com/tencent/sonic/demo/BrowserActivity.java — Reference implementation showing how to integrate Sonic into an Android WebView, demonstrating the public API contract.
• sonic-android/docs/Sonic接入指引.md — Integration guide documenting how to initialize SonicEngine, configure sessions, and handle the session lifecycle in client applications.

Add a Custom Cache Interceptor

1. Implement the SonicCacheInterceptor interface to define custom cache hit/miss logic (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicCacheInterceptor.html)
2. Register your interceptor via SonicConfig.Builder.setCacheInterceptor() during engine initialization (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicConfig.Builder.html)
3. Test by creating a sample session using SonicEngine.getInstance().createSession() with the new config (sonic-android/sample/src/main/java/com/tencent/sonic/demo/BrowserActivity.java)

Implement a Session Callback Handler

1. Create a class implementing SonicSession.Callback to receive session lifecycle events (onSessionStart, onDiffDataComplete, etc.) (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSession.Callback.html)
2. Pass your callback to the session via SonicSessionClient.bindClient() in your Activity/Fragment (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionClient.html)
3. Update your WebView with content in callback methods using SonicSessionStream.Callback for streaming partial HTML (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionStream.Callback.html)
4. See the reference implementation in BrowserActivity for a complete example (sonic-android/sample/src/main/java/com/tencent/sonic/demo/BrowserActivity.java)

Configure a Subresource Download Task

1. Create a SonicDownloadCallback instance (or extend SimpleDownloadCallback) to handle resource completion/failure (sonic-android/docs/javadoc/com/tencent/sonic/sdk/download/SonicDownloadCallback.html)
2. Submit a download task via SonicDownloadClient.enqueueDownloadTask() with resource URLs and your callback (sonic-android/docs/javadoc/com/tencent/sonic/sdk/download/SonicDownloadClient.DownloadTask.html)
3. Resources are cached by SonicDownloadCache and checked for availability before network fetch (sonic-android/docs/javadoc/com/tencent/sonic/sdk/download/SonicDownloadCache.html)

Add Custom Connection Behavior

1. Extend SonicSessionConnection or SessionConnectionDefaultImpl to override request/response handling (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnection.SessionConnectionDefaultImpl.html)
2. Apply custom logic in methods like getInputStream() to inject cached data or modify headers (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConnectionInterceptor.html)
3. Register via session config or engine config to replace the default connection factory (sonic-android/docs/javadoc/com/tencent/sonic/sdk/SonicSessionConfig.Builder.html)

1. HTML Specification compliance: Server must insert exact Sonic comment markers (<!--sonic-template-->, <!--sonic-data-->) or client caching fails silently. 2. SQLite schema lock: Multiple sessions updating cache DB concurrently can deadlock; see SonicDBHelper for transaction handling. 3. Template version mismatch: Client caches by template hash, but if server pushes new template without incrementing version, client may refuse update; check SonicResourceDataHelper.ResourceData versioning logic. 4. WebView bridge timing: SonicSessionClient callbacks must be wired before loadUrl() or early data arrives before listener attached. 5. Android API levels: Check build.gradle minSdkVersion; custom URL protocol interception uses API-specific URLConnection classes.

• Template/Data Separation (Sonic Specification) — Core innovation of Sonic—splitting HTML into rarely-changing template and frequently-changing data allows incremental caching and delta updates, reducing bandwidth and rendering latency by orders of magnitude on dynamic pages
• URL Interception / Custom Protocol Handler — Sonic intercepts WebView requests at the URLConnection/NSURLProtocol layer before the network stack, enabling parallel resource fetching and cache-before-network delivery without JavaScript shims
• Incremental DOM Rendering / Streaming HTML — Sonic sends partial HTML to the WebView while network request is still in-flight; browsers render what they have immediately rather than waiting for </html>, dramatically improving perceived first screen time
• Cache Invalidation by Template Hash — Sonic caches templates keyed by content hash; when server increments template version, client knows to discard old cache and fetch fresh template, avoiding stale data bugs common in HTTP caching
• Connection Pooling / Session Lifecycle — Sonic reuses TCP connections and cached sessions across multiple page loads via SonicEngine pool; understanding session states (preload, active, dead) is critical for debugging resource leaks
• Hybrid App Bridge Pattern — Sonic sits between native app and WebView; the SonicSessionClient callback interface is the bridge for native code to inject session data, control loading state, and handle errors—misconfiguration here breaks the entire optimization
• Preload / Prefetch Strategy — Sonic 3.0 (assets/VasSonic3.0_preload.md) adds subresource preload; understanding when to prefetch (on navigation vs. on idle) and how it competes with user interaction is key to avoiding jank

• square/okhttp — OkHttp is referenced in Android Sonic docs as alternative to URLConnection; many Sonic integrations layer on OkHttp interceptors
• google/chromium — Sonic relies on WebKit/Blink incremental rendering; understanding Blink's document streaming is key to optimizing data interleaving
• facebook/react-native — React Native also optimizes hybrid web performance; Sonic's template/data split complements RN's bridge batching strategy
• Tencent/QMUI_Android — Tencent's complementary UI framework; often paired with Sonic in production QQ/WeChat-like apps for full mobile optimization
• airbnb/lottie-android — Alternative approach to web-first UI in Android; Sonic and Lottie together can optimize hybrid content + custom animations

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 SonicSession and SonicEngine core classes

The sonic-android/docs/javadoc shows extensive public APIs for SonicSession, SonicEngine, and related classes, but there are no visible test files in the file structure. These are critical components for the hybrid framework's caching and session management. Adding unit tests would improve code reliability, prevent regressions, and help new contributors understand the expected behavior of these core classes.

• [ ] Create sonic-android/src/test/java/com/tencent/sonic/sdk/ directory structure
• [ ] Add SonicSessionTest.java with tests for session lifecycle, caching strategies, and callback mechanisms
• [ ] Add SonicEngineTest.java with tests for engine initialization, session management, and configuration
• [ ] Add tests for SonicSessionConnection and SonicSessionStream classes documented in javadoc
• [ ] Set up JUnit4 and Mockito dependencies in sonic-android/build.gradle

Add GitHub Actions CI/CD workflow for Android builds and tests

The repo uses Gradle 2.3.0 and has build.gradle files, but there's no visible CI/CD workflow file (.github/workflows/). This is critical for a maintained open-source project to catch build failures, ensure tests pass, and prevent regressions before merging PRs. A GitHub Actions workflow would be lightweight and free.

• [ ] Create .github/workflows/android-build.yml for automated Gradle builds
• [ ] Configure workflow to run 'gradle build' on push and pull requests to sonic-android/
• [ ] Add test step to run 'gradle test' to catch unit test failures
• [ ] Set up Android SDK caching to speed up workflow execution
• [ ] Add status badge to README.md showing CI/CD status

Create iOS equivalent documentation and sample code matching Android docs structure

The sonic-android/docs/ folder contains detailed Chinese documentation for Sonic Quick mode, Standard mode, integration guide, and framework overview. However, there's no corresponding ios directory in the file structure visible. For a cross-platform framework with iOS support, documentation parity is essential for developer adoption and maintenance. This would significantly improve discoverability for iOS developers.

• [ ] Create sonic-ios/docs/ directory structure mirroring sonic-android/docs/
• [ ] Translate and adapt 'Sonic Quick模式实现原理.md' to iOS-specific implementation details
• [ ] Translate and adapt 'Sonic Standard模式实现原理.md' for iOS architecture
• [ ] Create 'Sonic接入指引.md' (Integration Guide) for iOS in English
• [ ] Create 'Sonic框架介绍.md' (Framework Overview) for iOS platform
• [ ] Add references to iOS documentation in main README.md

• Add unit tests for SonicCacheInterceptor—trace cache hit/miss logic for template vs. data and write JUnit tests covering the three modes (Quick, Standard, offline). Currently no tests/ directory visible.
• Write integration test for server Sonic Specification compliance in sonic-php/ and sonic-nodejs/—verify HTML output includes proper <!--sonic-template--> and <!--sonic-data--> markers, and validate against Android client parser.
• Document the exact HTML comment syntax required by Sonic Specification in a dedicated SPEC.md—currently only referenced in Chinese docs and buried in assets/Sonic2.0.md.

• High · Outdated Gradle Build Tools — build.gradle (dependencies section). The build.gradle file specifies 'com.android.tools.build:gradle:2.3.0', which was released in 2017 and is severely outdated. This version contains multiple known security vulnerabilities and lacks modern security features and bug fixes. Android Gradle Plugin 2.3.0 has reached end-of-life and no longer receives security updates. Fix: Update to the latest stable Android Gradle Plugin version (currently 8.0+). This ensures access to security patches, performance improvements, and modern Android development standards. Use 'com.android.tools.build:gradle:8.0.0' or later.
• High · Outdated Gradle Maven Plugin — build.gradle (classpath 'com.github.dcendents:android-maven-gradle-plugin:1.5'). The dependency 'com.github.dcendents:android-maven-gradle-plugin:1.5' is outdated and no longer maintained. This plugin may contain unpatched security vulnerabilities and compatibility issues with modern Gradle versions. Fix: Replace with the maintained alternative 'com.vanniktech:gradle-maven-publish-plugin' or use Maven Central's official publishing mechanisms. Ensure the chosen plugin is actively maintained and compatible with current Gradle versions.
• High · Outdated Bintray Plugin — build.gradle (classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.6'). The 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.6' dependency is outdated. Bintray has been sunset by JFrog, and this plugin is no longer maintained or supported, creating security and reliability concerns. Fix: Migrate to JFrog Artifactory or Maven Central for artifact distribution. Use 'io.github.gradle-nexus:publish-plugin' for Maven Central publishing, which is the current standard for Java/Android library distribution.
• Medium · Insecure Repository Configuration — build.gradle (repositories section: jcenter()). The build configuration uses 'jcenter()' repository which has been shutdown by JFrog as of February 2021. Dependencies from this repository are no longer available, and builds will fail. Additionally, relying on deprecated repositories increases supply chain attack risk. Fix: Replace 'jcenter()' with 'mavenCentral()'. Update all repository declarations to use: repositories { mavenCentral() google() } to ensure dependencies are sourced from maintained, secure repositories.
• Medium · Missing Security Configuration Review — sonic-android/src (inferred from javadoc references to SonicSessionConnection and SonicServer). As a hybrid framework handling web content and caching mechanisms, there is no visible implementation of security headers (CSP, X-Frame-Options, etc.) or input validation patterns in the file structure. The framework appears to use custom URL connections which could be vulnerable to MITM attacks if not properly configured. Fix: Implement comprehensive security measures: (1) Add certificate pinning for HTTPS connections; (2) Validate all cached content; (3) Implement Content Security Policy headers; (4) Use HSTS for all connections; (5) Add input sanitization for web content; (6) Implement integrity checks for cached resources.
• Medium · Potential Cache Injection Vulnerability — sonic-android/docs/javadoc/com/tencent/sonic/sdk/ (SonicCacheInterceptor, SonicDownloadCache related classes). The framework implements caching mechanisms (SonicCacheInterceptor, SonicDownloadCache) with cache update functionality. Without proper validation of cached content origins and integrity, this could be exploited for cache poisoning attacks or serving malicious content from cache. Fix: Implement cache validation mechanisms: (1) Verify cache source authenticity; (2) Implement cache integrity checks (HMAC/signatures); (3) Add cache expiration validation; (4) Sanitize all cached HTML/JavaScript content before rendering; (5) Implement cache versioning and secure updates.
• Low · Missing CHANGELOG and Security Policy — undefined. The repository lacks a SECURITY.md or security policy file, and there is no visible CHANGELOG documenting security patches. This makes it difficult for users to track security updates and understand the security history Fix: undefined

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.