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/alibaba/vlayout 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 5y ago

• 8 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits
• ⚠ No CI workflows 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 alibaba/vlayout repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alibaba/vlayout.

What it runs against: a local clone of alibaba/vlayout — 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 alibaba/vlayout | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1789 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutManager.java" \\
  && ok "vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutManager.java" \\
  || miss "missing critical file: vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutManager.java"
test -f "vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java" \\
  && ok "vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java" \\
  || miss "missing critical file: vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java"
test -f "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java" \\
  && ok "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java" \\
  || miss "missing critical file: vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java"
test -f "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutManagerHelper.java" \\
  && ok "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutManagerHelper.java" \\
  || miss "missing critical file: vlayout/src/main/java/com/alibaba/android/vlayout/LayoutManagerHelper.java"
test -f "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelperFinder.java" \\
  && ok "vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelperFinder.java" \\
  || miss "missing critical file: vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelperFinder.java"

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

VLayout is a custom LayoutManager extension for Android's RecyclerView that enables mixing multiple layout types (linear, grid, staggered, fixed, floating) within a single RecyclerView instance. It uses a chain of LayoutHelpers to manage layout logic for different sections of content, solving the problem of creating complex multi-layout feeds common in e-commerce and social media apps. Standard Android library project structure: top-level build.gradle orchestrates the build; core layout logic lives in the main vlayout module (not shown in detail but implied); examples/ contains working demonstrations (VLayoutActivity.java, DebugActivity.java, OnePlusNLayoutActivity.java) that test various LayoutHelper combinations. Modular design: each LayoutHelper (LinearLayoutHelper, GridLayoutHelper, FixLayoutHelper, etc.) is a separate implementation handling one layout strategy.

Android developers building feed-style UIs (e-commerce product listings, social media feeds, news apps) who need to mix grids, lists, sticky headers, and fixed floating elements without managing multiple RecyclerViews or complex custom layouts.

Abandoned but stable. The README explicitly states 'This project is not maintained any more !!!'. The codebase appears mature (669KB Java code, structured examples), but the project has not been actively developed. This was part of Alibaba's Tangram ecosystem circa 2016–2017. It is production-ready if you accept no further upstream updates.

High risk for long-term maintenance: unmaintained status means no security patches, no Android API level updates, and no bug fixes. No visible CI/CD pipeline in the provided files, no test coverage metrics shown. Dependency on older Gradle (2.2.2) and Maven snapshots suggests compatibility issues with modern Android toolchains. Single-author history (Alibaba) with no community fork activity visible.

Nothing. The project is explicitly marked unmaintained. The README points users to the broader Tangram ecosystem (Tangram-Android, Virtualview-Android, UltraViewPager) but vlayout itself has no active development.

Clone and build with Gradle: git clone https://github.com/alibaba/vlayout.git && cd vlayout && ./gradlew build. Import the vlayout module into your Android Studio project, or add the published JAR from jcenter/MavenCentral (mentioned in README but not shown in file list). Example APKs can be built via ./gradlew assembleDebug in the examples/ directory.

Daily commands: Build the example APK: ./gradlew -p examples assembleDebug. Deploy to an emulator/device: adb install examples/build/outputs/apk/examples-debug.apk. Launch MainActivity, DebugActivity, or VLayoutActivity to see different layout combinations in action (product grids, linear lists, sticky headers, floating buttons).

• vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutManager.java — Core custom LayoutManager that orchestrates layout helpers and manages the main layout pass for RecyclerView; entry point for understanding the framework
• vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java — Adapter wrapper that bridges RecyclerView to VirtualLayoutManager and manages multiple delegates; essential for composing different layout types
• vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java — Abstract base class defining the interface all layout helpers must implement; defines the plugin architecture for custom layouts
• vlayout/src/main/java/com/alibaba/android/vlayout/LayoutManagerHelper.java — Provides helper methods that layout implementations use to interact with VirtualLayoutManager; critical bridge between helpers and manager
• vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelperFinder.java — Locates and retrieves the appropriate LayoutHelper for a given item position; essential for routing layout logic
• vlayout/DESIGN.md — Architecture and design rationale documentation; explains the helper-based layout strategy and core design decisions

Create a Custom LayoutHelper

1. Extend LayoutHelper abstract class to define your custom layout logic (vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java)
2. Implement layoutCount(), onLayout(), and measurement methods in your custom helper (vlayout/src/main/java/com/alibaba/android/vlayout/layout/AbstractFullFillLayoutHelper.java)
3. Register your helper in a LayoutView via DelegateAdapter's addLayoutHelper() method (vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java)
4. Create an adapter delegate implementing VirtualLayoutAdapter for your item type (vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutAdapter.java)

Compose Multiple Layouts in One RecyclerView

1. Create a DelegateAdapter and set it as the adapter for your RecyclerView (vlayout/src/main/java/com/alibaba/android/vlayout/DelegateAdapter.java)
2. Create VirtualLayoutManager and attach it to the RecyclerView (vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutManager.java)
3. Implement VirtualLayoutAdapter for each layout section's data type (vlayout/src/main/java/com/alibaba/android/vlayout/VirtualLayoutAdapter.java)
4. Call addLayoutHelper() on DelegateAdapter for each layout section with its helper and range (vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelperFinder.java)

Configure Layout Behavior and Appearance

1. Set layout properties (margins, padding, gaps) on your LayoutHelper instance (vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java)
2. Use LayoutHelper's setShowType() and setAutoExpand() to control visibility and expansion (vlayout/src/main/java/com/alibaba/android/vlayout/LayoutHelper.java)
3. Reference ATTRIBUTES.md documentation for all available layout properties (docs/ATTRIBUTES.md)
4. View example implementations in VLayoutActivity for property usage patterns (examples/src/main/java/com/alibaba/android/vlayout/example/VLayoutActivity.java)

• Custom LayoutManager (RecyclerView extension) — Provides low-level control over layout measurement and positioning; required to support mixed layout types in a single RecyclerView
• Helper/Plugin pattern (LayoutHelper abstract class) — Encapsulates different layout strategies (grid, linear, etc.) and allows independent development and composition of layout types without modifying core
• DelegateAdapter wrapper pattern — Decouples multi-section data management from layout logic; enables each section to manage its own adapter and ViewHolder without conflicts
• Range-based position tracking (SortedList + RangeLayoutHelperFinder) — Efficient O(log n) lookup of layout helpers by item position; critical for performance when handling large item counts across many layout sections

• Delegated adapter composition vs. single monolithic adapter

  • Why: Allows independent data management and view holder binding per layout section
  • Consequence: Added complexity in position mapping and adapter coordination; DelegateAdapter must translate between global and section-local positions

• Helper-based layout routing vs. item type-based routing

  • Why: Helpers define both layout strategy AND position ranges; enables mixing layout types without predefined item type segregation
  • Consequence: Requires careful management of position ranges and helper ordering; misconfiguration can cause layout gaps or overlaps

• Retained view recycling pool per section (InnerRecycledViewPool)

  • Why: Improves recycling efficiency and reduces pool contention when sections have distinct view types
  • Consequence: Higher memory footprint per section; potential wastage if section sizes fluctuate

Ancient Gradle version (2.2.2, from 2016) may fail on modern JDK 11+; use JDK 8 or patch build.gradle. Maven snapshot repositories in buildscript may be unavailable or slow. No built-in test suite visible; examples/ is the only validation. Documentation is split between ATTRIBUTES.md (English) and ATTRIBUTES-ch.md (Chinese), and some visual features are shown only in docs/images/ without detailed prose explanation. LayoutHelper chain order matters; incorrect sequencing causes layout corruption. RecyclerView version is not pinned—dependency conflicts with newer Support Library versions are likely.

• LayoutHelper chain / composite pattern — VLayout's core design: VirtualLayoutManager delegates layout decisions to a chain of LayoutHelpers, each responsible for a contiguous range of items. Understanding this pattern is essential to extending vlayout or debugging multi-section layouts.
• RecyclerView LayoutManager contract — VLayout is a LayoutManager extension; you must understand onLayoutChildren(), onMeasure(), canScrollVertically/Horizontally, and scroll offset management to modify or debug layout behavior.
• View recycling and item position ranges — Each LayoutHelper manages a startPosition–endPosition range; incorrect range management causes view reuse bugs and layout shifts. Critical for custom LayoutHelpers.
• Sticky/fixed positioning in scrollable containers — StickyLayoutHelper and FixLayoutHelper break normal flow layout to pin views during scroll. Requires careful state management and coordinate transformation; non-obvious when margins/padding interact with fixed layouts.
• Span and grid-based layout measurement — GridLayoutHelper and StaggeredGridLayoutHelper distribute items across spans; span count, item aspect ratio, and gap calculations directly affect visual output. Misconfiguration is a common source of layout bugs.
• Android Support Library compatibility and deprecation — VLayout targets old Support Library (pre-AndroidX); updating it to modern androidx requires careful dependency mapping. The project's unmaintained status means you may need to fork to add androidx support.

• alibaba/Tangram-Android — Sibling project in the same Tangram ecosystem; a higher-level framework that uses vlayout as its layout engine for building data-driven card-based UIs
• alibaba/UltraViewPager — Companion Alibaba project providing enhanced ViewPager functionality; often used alongside vlayout for horizontal scrolling + multi-layout vertical feeds
• google/flexbox-layout — Modern alternative for flexible layout on Android; addresses similar multi-layout use cases but with CSS flexbox semantics instead of LayoutHelper chains
• airbnb/epoxy — Contemporary multi-layout RecyclerView framework using composable models; provides a more maintainable approach than vlayout's LayoutHelper pattern

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 instrumented tests for VLayoutManager layout calculations across different layout types

The examples/src/androidTest directory only contains ApplicationTest.java stub. VLayout supports multiple layout types (grid, list, linear, etc.) that can be mixed in a single RecyclerView. Critical layout calculation logic needs instrumented tests to prevent regressions, especially for edge cases like span size calculations, alignment, and margin/padding application mentioned in docs/ATTRIBUTES.md.

• [ ] Create instrumented test classes in examples/src/androidTest/java/com/alibaba/android/vlayout/ for each layout type (GridLayoutTest, ListLayoutTest, LinearLayoutTest)
• [ ] Add tests for margin/padding combinations as shown in docs/images/MarginPadding.png
• [ ] Add tests for span count and span size calculations documented in docs/images/SpanCountSpanSize.png
• [ ] Add tests for alignment type calculations from docs/images/AlignTypeXY.png
• [ ] Test mixed layout scenarios in a single RecyclerView to verify the core value proposition

Add GitHub Actions CI workflow for Android builds and test execution

The repository has gradle setup and example app but no CI pipeline defined (no .github/workflows directory). This is critical for an open-source library to ensure contributions don't break builds. Given the project is Android-based with gradle, a CI workflow should run linting, unit tests, and instrumented tests on PR submissions.

• [ ] Create .github/workflows/android-build.yml with Android setup action
• [ ] Configure gradle build step for vlayout module (./gradlew build)
• [ ] Add linting check step (./gradlew lint)
• [ ] Configure Android emulator and run instrumented tests from examples module
• [ ] Add build status badge to README.md

Create specific API documentation for LayoutHelper classes with code examples in docs/

docs/ATTRIBUTES.md documents configuration options but there's no dedicated developer guide for the LayoutHelper class hierarchy. The DESIGN.md file in vlayout/ directory suggests architectural patterns but lacks concrete examples. New contributors need clear documentation on how to extend VLayout with custom LayoutHelper implementations.

• [ ] Review vlayout/src/main/java/com/alibaba/android/vlayout/ to identify LayoutHelper subclasses (GridLayoutHelper, LinearLayoutHelper, etc.)
• [ ] Create docs/LAYOUT_HELPERS.md with class hierarchy diagram and inheritance patterns
• [ ] Add code examples showing how to instantiate and configure each LayoutHelper type with real-world use cases
• [ ] Document the LayoutParams customization points and how to extend VLayout for custom layouts
• [ ] Cross-reference with existing example Activities (VLayoutActivity.java, OnePlusNLayoutActivity.java) to show practical implementations

• Add unit tests for GridLayoutHelper and StaggeredGridLayoutHelper: examples/androidTest/ contains only ApplicationTest.java stub; writing parameterized tests for span counts, item sizing, and gap handling would catch regressions and document behavior.
• Migrate build.gradle to modern Gradle + Kotlin DSL: replace classpath versions (gradle:2.2.2 → 7.x), update Maven snapshot repos to public registries, and fix deprecated Android Gradle Plugin APIs so the project builds on JDK 11+.
• Add JavaDoc comments to core LayoutHelper classes: the main vlayout module classes lack inline documentation; add method-level docs explaining onLayoutChildren(), measure callbacks, and sticky/float behavior for first-time contributors.

The vlayout project has a poor security posture primarily due to its unmaintained status and heavily outdated dependencies. Critical issues include: (1) Gradle plugin from 2016 with unpatched vulnerabilities, (2) Insecure HTTP repository URLs enabling MITM attacks, (3) Multiple outdated build dependencies, and (4) Explicit notice that the project is no longer maintained. These factors

• High · Outdated Gradle Build Plugin — build.gradle - classpath 'com.android.tools.build:gradle:2.2.2'. The project uses Gradle plugin version 2.2.2 (released in 2016), which is significantly outdated and contains known security vulnerabilities. This version has not received security patches for years and lacks critical security fixes for Android builds. Fix: Upgrade to the latest stable Gradle plugin version (currently 7.x or 8.x). Review and update all build dependencies to their latest versions.
• High · Insecure Maven Repository URLs — build.gradle - maven { url 'http://oss.jfrog.org/oss-snapshot-local/' }. The build.gradle file uses HTTP (not HTTPS) for Maven repository URLs. This creates a man-in-the-middle (MITM) vulnerability where dependencies could be intercepted and tampered with during download. Fix: Replace all HTTP URLs with HTTPS equivalents: https://oss.jfrog.org/oss-snapshot-local/. Ensure all repository URLs use HTTPS for secure communication.
• High · Outdated Gradle Dependencies — build.gradle - classpath dependencies block. Multiple build dependencies are outdated and vulnerable: gradle-bintray-plugin:1.4 (2016), build-info-extractor-gradle:4.0.0 (2016), android-maven-gradle-plugin:1.5 (2015), and view-inspector-plugin:0.1.1. These old versions contain unpatched security vulnerabilities. Fix: Update all dependencies to their latest versions. Replace deprecated plugins like gradle-bintray-plugin with modern alternatives. Review maven-publish gradle plugin as a replacement.
• Medium · Project Marked as Unmaintained — README.md - first line. The README clearly states 'Attention. This project is not maintained any more !!!'. Using unmaintained libraries in production creates security risks as vulnerabilities will never be patched and issues will go unresolved. Fix: Evaluate whether to continue using this library. Consider migrating to actively maintained alternatives or forking and maintaining internally. If continuing use, implement additional security monitoring and testing.
• Medium · ProGuard Configuration Present — vlayout/proguard-rules.pro, examples/proguard-rules.pro. ProGuard rule files exist (vlayout/proguard-rules.pro, examples/proguard-rules.pro) but their content is not visible for analysis. Misconfigured ProGuard rules could fail to obfuscate sensitive code, exposing business logic. Fix: Review ProGuard configuration to ensure: (1) Sensitive classes are properly obfuscated, (2) Rules are comprehensive, (3) No debug symbols are exposed in release builds.
• Low · Snapshot Dependencies Usage — build.gradle - repositories block. The build configuration includes snapshot repositories (https://oss.sonatype.org/content/repositories/snapshots/ and http://oss.jfrog.org/oss-snapshot-local/). Snapshot builds are unstable and may contain untested code. Fix: Remove snapshot repositories from production builds. Use only stable release versions. If needed, restrict snapshot usage to development builds only.
• Low · Missing Security Configuration in AndroidManifest — vlayout/src/main/AndroidManifest.xml, examples/src/main/AndroidManifest.xml. The AndroidManifest.xml files are present but their content is not visible. Without review, potential security misconfigurations cannot be assessed (e.g., exported components, missing permissions restrictions). Fix: Review AndroidManifest.xml to ensure: (1) Activities/Services are not unnecessarily exported, (2) Proper permission declarations, (3) No debug flags in production builds, (4) Appropriate intent filters.

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.