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/SoySauceLab/CollectionKit 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

• 9 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 4y ago
• ⚠ Single-maintainer risk — top contributor 87% of recent commits

_{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 SoySauceLab/CollectionKit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/SoySauceLab/CollectionKit.

What it runs against: a local clone of SoySauceLab/CollectionKit — 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 SoySauceLab/CollectionKit | 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 ≤ 1316 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "SoySauceLab/CollectionKit(\\.git)?\\b" \\
  && ok "origin remote is SoySauceLab/CollectionKit" \\
  || miss "origin remote is not SoySauceLab/CollectionKit (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 "Sources/CollectionKit.swift" \\
  && ok "Sources/CollectionKit.swift" \\
  || miss "missing critical file: Sources/CollectionKit.swift"
test -f "Sources/Provider.swift" \\
  && ok "Sources/Provider.swift" \\
  || miss "missing critical file: Sources/Provider.swift"
test -f "Sources/CollectionViewManager.swift" \\
  && ok "Sources/CollectionViewManager.swift" \\
  || miss "missing critical file: Sources/CollectionViewManager.swift"
test -f "Sources/Composed/ComposedProvider.swift" \\
  && ok "Sources/Composed/ComposedProvider.swift" \\
  || miss "missing critical file: Sources/Composed/ComposedProvider.swift"
test -f "Sources/Layout/Layout.swift" \\
  && ok "Sources/Layout/Layout.swift" \\
  || miss "missing critical file: Sources/Layout/Layout.swift"

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

CollectionKit is a Swift framework that reimplements UICollectionView from scratch on top of UIScrollView, providing automatic data diffing, composable provider-based architecture, and Swift generics for type-safe collection layouts. It eliminates UICollectionView's delegate/datasource boilerplate and adds built-in support for batched updates, cell reuse, and custom layout/animation systems without the performance penalties of the system framework. Monorepo structure: CollectionKit/ contains the core framework (providers, layouts, view system); CollectionKitTests/ holds Nimble/Quick specs for all major components; Examples/CollectionKitExamples/ has 6+ standalone example apps (GridExample, ChatExample, AnimatorExample, etc.) demonstrating features like header composition, custom animators, and gallery patterns.

iOS developers building data-driven UIs in Swift who want to replace UICollectionView with a more composable, type-safe, and performant alternative—particularly those building complex multi-section layouts (chat, feeds, grids) and tired of UICollectionViewDataSource/Delegate complexity.

Actively maintained and production-ready: v2.0 is the current stable version with a v2 migration guide, comprehensive test suite across CollectionKitTests/ (BasicProviderSpec, ComposedProviderSpec, FlowLayoutSpec, etc.), Travis CI configured (.travis.yml), and 8+ example apps demonstrating real use cases. Codebase is 147K lines of Swift with regular iteration.

Single-repository architecture with no obvious monorepo splits; no visible recent commit history or open PR/issue counts in provided data, making it unclear if still actively developed or maintenance-mode. Strong dependency on Swift stdlib/UIKit but no external pod dependencies listed, reducing supply-chain risk. Breaking change from v1→v2 suggests API evolution; v3 incompatibilities possible.

Active iteration on core provider patterns (ComposedProviderSpec, ComposedHeaderProviderSpec suggest recent composition features), layout systems (FlowLayoutSpec, RowLayoutSpec, WaterfallLayoutSpec for advanced layouts), and animator/transition systems. Example apps suggest ongoing feature exploration (message cells, advanced chat UI).

Clone the repository and open in Xcode 8.2+:

git clone https://github.com/SoySauceLab/CollectionKit.git
cd CollectionKit
open CollectionKit.xcworkspace  # Use workspace, not project file

For CocoaPods users: pod 'CollectionKit'. For Carthage: github "SoySauceLab/CollectionKit".

Daily commands: Open CollectionKit.xcworkspace in Xcode and run the main CollectionKit scheme to execute unit tests. For examples, open Examples/CollectionKitExamples.xcworkspace and run individual example schemes (AnimatorExample, GridExample, ChatExample, etc.).

• Sources/CollectionKit.swift — Main entry point and core collection view abstraction that replaces UICollectionView with a composable, data-driven architecture
• Sources/Provider.swift — Core protocol defining the Provider abstraction—the fundamental building block for composing data sources, layouts, and bindings
• Sources/CollectionViewManager.swift — Manages the lifecycle of a CollectionView, handling data updates, layout calculations, and view recycling
• Sources/Composed/ComposedProvider.swift — Enables composition of multiple providers into a single provider, allowing nested and modular collection structures
• Sources/Layout/Layout.swift — Protocol defining the layout engine abstraction that calculates frames for collection items without tight coupling to UICollectionView
• Examples/CollectionKitExamples/Supporting Files/ViewController.swift — Example demonstrating how to integrate CollectionKit into a real UIViewController with various provider and layout combinations

• Provider (Swift generics, protocols) — Abstracts data source, cell type, layout, and binding logic; each conformer is a complete, reusable collection specification
  • Failure mode: Data binding fails if cell type does not match provided data type; layout crashes if item count mismatches
• Layout Engine (CGRect, CGSize calculations) — Converts item count and container size into frame rectangles; decoupled from data so multiple layouts can reuse same provider
  • Failure mode: Frame calculations produce off-screen or overlapping cells if algorithm is incorrect or viewport size is zero
• CollectionViewManager — Orchestrates provider queries, layout calculations

Add a new custom Layout

1. Create a new Swift file in Sources/Layout/ (e.g., CustomLayout.swift) (Sources/Layout/Layout.swift)
2. Conform to the Layout protocol and implement the required methods: layout(items:containerSize:) returning frame for each item (Sources/Layout/Layout.swift)
3. Use the custom layout in a Provider by passing it to the provider's layout parameter when instantiating (Sources/Provider/BasicProvider.swift)

Add a new Provider type

1. Create a new struct/class conforming to Provider protocol in Sources/Provider/ (Sources/Provider.swift)
2. Implement required properties: data, layout, and cellType, plus required methods: numberOfItems() and cell(at:, view:) (Sources/Provider.swift)
3. For composition, wrap multiple providers using ComposedProvider (Sources/Composed/ComposedProvider.swift)

Create an example showcasing a new feature

1. Create a new subdirectory in Examples/CollectionKitExamples/ (e.g., MyFeatureExample/) (Examples/CollectionKitExamples/ViewController.swift)
2. Add a ViewController file implementing the feature using CollectionKit providers and layouts (Examples/CollectionKitExamples/GridExample/GridViewController.swift)
3. Register the example in the main ViewController.swift file to make it accessible from the example app (Examples/CollectionKitExamples/Supporting Files/ViewController.swift)

Add custom cell animations

1. Create a custom animator by conforming to the Animator protocol (Sources/Animator.swift)
2. Implement the required animate() method to define cell transition behavior (Sources/Animator.swift)
3. Reference the example implementations in Examples/CollectionKitExamples/AnimatorExample/ for pattern guidance (Examples/CollectionKitExamples/AnimatorExample/EdgeShrinkAnimator.swift)

• Swift generics and protocols — Enable type-safe, composable abstractions without runtime type checking, allowing flexible provider and layout combinations
• UIView subclassing (not UICollectionView) — Escape UICollectionView's complexity and inflexibility; rebuild with modern Swift patterns prioritizing composability over backward compatibility
• Protocol-based provider architecture — Allow any conforming type to provide data/layout/bindings, enabling composition, testing, and independent evolution of concerns

• Reimplemented collection view from scratch instead of subclassing UICollectionView

  • Why: UICollectionView's delegate/datasource pattern is verbose and inflexible; CollectionKit's provider model is more declarative and composable
  • Consequence: Not backward-compatible with UICollectionView; requires learning new API but offers simpler composition and less boilerplate

• Separate Layout protocol from Provider

  • Why: Decouples data/binding logic from layout logic, allowing reusable layouts and providers
  • Consequence: Slightly more instantiation code, but enables true composability (same provider with different layouts, different providers with same layout)

• No built-in data diffing—relies on manual update calls

  • Why: Simplifies API and avoids hidden performance pitfalls from automatic diffing
  • Consequence: Developer must call reloadData() or animate updates explicitly; trade-off favoring explicitness over magic

• Does not support UICollectionView interoperability or migration helpers
• Does not include built-in cell animations (leaves animation to separate Animator protocol)
• Does not provide automatic data diffing or change tracking
• Does not support tvOS or macOS (iOS-only as of current version)

.swift-version file specifies exact Swift compiler version (likely 3.x or 4.x); mismatched Xcode/Swift version will cause build failures. No explicit iOS deployment target visible in provided snippet but README states iOS 8.0+; target version in .pbxproj must match your test devices. CollectionKit.xcworkspace required — opening the .xcodeproj directly may fail to link framework dependencies. Example apps are separate projects (CollectionKitExamples.xcworkspace) and use framework by source; they may drift from main repo if not tested together in CI.

• Data Diffing Algorithm (Myers' Diff) — CollectionKit automatically diffs old/new data and batches only changed cells; understanding diff complexity (O(n+m) vs O(n²)) explains why it outperforms naive UICollectionView reloads with 1000s of items.
• Provider Pattern (Composition over Delegation) — CoreKit's fundamental abstraction replaces UICollectionViewDataSource/Delegate with composable, type-safe Provider objects; critical for understanding how BasicProvider, ComposedProvider, and EmptyStateProvider stack.
• Value Type Semantics in Swift (Struct-based Data) — CollectionKit uses Swift structs for data diffing instead of reference types; avoids reference equality bugs and enables deterministic change detection.
• Cell Reuse and Object Pooling — CollectionKit implements aggressive cell pooling atop UIScrollView without UICollectionView's overhead; essential for smooth scrolling with 1000+ items.
• Swift Generics and Associated Types — BasicProvider<Data, View> uses generics for type-safe data→view mapping; compiler catches mismatches at build time, eliminating runtime crashes from casting errors.
• Visible-Only Rendering Optimization — CollectionKit only diffs and renders cells in the scroll viewport; skipping off-screen diffing cuts computation by 90%+ in large lists.
• Custom Layout Engine (UIView Frame Calculation) — FlowLayout, RowLayout, WaterfallLayout compute cell frames independently; this decouples layout logic from UICollectionViewLayout's inflexible API.

• ReactiveX/RxSwift — Provides reactive bindings for data streams; CollectionKit's data diffing pairs naturally with RxSwift observables for reactive UI updates.
• lkzhao/Hero — Custom UIView transition library from same author ecosystem; often used alongside CollectionKit for choreographed cell animations and shared element transitions.
• Instagram/IGListKit — Comparable Objective-C alternative (Facebook's answer to UICollectionView) with section-based composition; reference for competing architecture decisions in the same problem space.
• realm/realm-swift — Commonly paired as a DataSource for CollectionKit; Realm's automatic change notifications integrate seamlessly with CollectionKit's diffing system.
• SwiftyJSON/SwiftyJSON — Typical data parsing layer upstream of CollectionKit's DataSource; reduces boilerplate in example apps that fetch remote data.

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 ComposedProvider composition logic

CollectionKitTests/ComposedProviderSpec.swift exists but appears minimal. ComposedProvider is a core feature for 'reimagining UICollectionView' with composable data-driven patterns. The test suite should cover edge cases like nested compositions, provider updates, and layout consistency across multiple composed providers—especially given the complexity shown in Examples/CollectionKitExamples/ChatExample with advanced composition.

• [ ] Expand CollectionKitTests/ComposedProviderSpec.swift with tests for: nested provider composition, dynamic provider addition/removal, data reload propagation across composed layers
• [ ] Add tests for interaction between ComposedProvider and various layout types (FlowLayout, WaterfallLayout, RowLayout) to ensure composed data updates layout correctly
• [ ] Add regression tests for memory management in composed hierarchies (deallocate when providers are removed)

Add missing test coverage for WaterfallLayout edge cases and animation scenarios

CollectionKitTests/WaterfallLayoutSpec.swift exists but WaterfallLayout is complex (multi-column balancing). Given that Examples/ReloadAnimationExample exists, there's no corresponding test for animation behavior with WaterfallLayout during reloads. This is a specific gap that could prevent layout corruption bugs.

• [ ] Add tests to CollectionKitTests/WaterfallLayoutSpec.swift for: column height balancing with varied item sizes, insertion/deletion animations, bounds checking on edge columns
• [ ] Cross-reference Examples/ReloadAnimationExample/ReloadAnimationViewController.swift and add unit tests for WaterfallLayout-specific reload animations
• [ ] Test WaterfallLayout with ComposedProvider (similar to header examples) to ensure proper layout reflow

Create GitHub Actions CI workflow to replace deprecated Travis CI (.travis.yml)

.travis.yml is present but Travis CI is deprecated for new projects. The repo shows Xcode 8.2+, iOS 8.0+, Swift 3.0+ support with codecov integration. A GitHub Actions workflow would modernize CI, add caching, and improve visibility.

• [ ] Create .github/workflows/ci.yml with: Xcode test job (using macos-latest with appropriate Xcode version), Swift linting via swiftlint (config exists at .swiftlint.yml)
• [ ] Add codecov upload step to match existing .travis.yml coverage reporting setup
• [ ] Remove or deprecate .travis.yml with a note in CONTRIBUTING.md directing to GitHub Actions

• Add unit tests for EmptyStateProvider: CollectionKitTests/EmptyStateProviderSpec.swift exists but may have incomplete coverage for edge cases (zero items, state transitions). Run test suite and identify untested code paths in Sources/Provider/EmptyStateProvider.swift.
• Document the Animator pattern used in Examples/CollectionKitExamples/AnimatorExample/ (EdgeShrinkAnimator.swift, ZoomAnimator.swift): These files lack inline comments explaining how custom animators integrate with layout updates. Add doc comments explaining the animator lifecycle.
• Expand WaterfallLayout tests in CollectionKitTests/WaterfallLayoutSpec.swift: Check if all layout edge cases (single column, uneven heights, dynamic width) are covered; add missing test cases for improved robustness.

The CollectionKit codebase demonstrates a relatively secure posture as a Swift UI framework. No critical injection vulnerabilities, hardcoded secrets, or exposed credentials were identified in the file structure. The primary concerns are related to dependency management practices (version pinning), version control configuration best practices (workspace files), and asset source verification. The framework appears well-structured with appropriate separation of examples, tests, and core library code. No database interaction, network security, or encryption-sensitive operations are evident from the file listing, reducing attack surface. Recommendations focus on enhancing dependency security practices and documenting external asset sources.

• Medium · Missing Dependency Pinning in CocoaPods Specification — CollectionKit.podspec. The CollectionKit.podspec file is present but dependency versions are not explicitly pinned in the provided context. Without explicit version constraints, the framework could inadvertently pull in vulnerable versions of dependencies during installation. Fix: Specify exact or minimum version constraints for all dependencies in the podspec file. Use pessimistic version constraints (~>) to allow patch updates while preventing major version changes.
• Low · Workspace Configuration Files Committed to Repository — CollectionKit.xcodeproj, CollectionKit.xcworkspace. Xcode workspace and project configuration files (.xcworkspace, .xcodeproj) are committed to version control. These files may contain local paths, build settings, or IDE-specific configurations that could vary between developers or expose system paths. Fix: Consider adding .xcodeproj and .xcworkspace to .gitignore, or document that developers should use standard Xcode project references. Ensure sensitive build settings are not hardcoded in scheme files.
• Low · Example Project Assets Not Validated — Examples/CollectionKitExamples/Supporting Files/Assets.xcassets. The Examples directory contains multiple image assets from external sources (e.g., URLs in filenames like 'winstonthewhitecorgi'). These assets could potentially be outdated or sourced from unreliable origins without verification. Fix: Document the source and licensing of all included assets. Verify that external images are properly licensed and hosted. Consider using placeholder images for examples instead of external assets.
• Low · Missing HTTPS Enforcement in Travis CI Configuration — .travis.yml. The .travis.yml file is present, indicating CI/CD pipeline usage. The README shows a Travis CI badge but the configuration file content is not provided for review. Without visibility, potential security misconfigurations in the CI pipeline cannot be assessed. Fix: Review and ensure the Travis CI configuration uses secure defaults: HTTPS for all repository communications, secure storage of build secrets (using Travis encrypted variables), and signed commits. Keep the file in version control but ensure sensitive values use CI/CD secret management.

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.