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/HandyOrg/HandyControl 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 5mo ago

• Last commit 5mo ago
• 7 active contributors
• MIT licensed
• CI configured
• ⚠ Slowing — last commit 5mo ago
• ⚠ Single-maintainer risk — top contributor 92% 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 HandyOrg/HandyControl repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/HandyOrg/HandyControl.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "HandyOrg/HandyControl(\\.git)?\\b" \\
  && ok "origin remote is HandyOrg/HandyControl" \\
  || miss "origin remote is not HandyOrg/HandyControl (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 "build/build.cake" \\
  && ok "build/build.cake" \\
  || miss "missing critical file: build/build.cake"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f "LICENSE" \\
  && ok "LICENSE" \\
  || miss "missing critical file: LICENSE"
test -f ".editorconfig" \\
  && ok ".editorconfig" \\
  || miss "missing critical file: .editorconfig"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

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

HandyControl is a WPF control library (2.4MB C# codebase) providing pre-built, commonly-used UI components for .NET desktop applications targeting .NET 4.0+. It bundles reusable controls like data grids, dropdowns, borders, and icon elements with attached behaviors to reduce boilerplate in Windows Forms-style UI development. Monolithic single NuGet package structure: source code organized by feature (attach/, controls/) with build scripts in build/ (build.cake for Cake build automation), multi-language docs in doc/ (Hexo site), and NuSpec templates for packaging (lib.nuspec.template, lang.nuspec.template, installer.nuspec.template) that produce separate binaries for language packs and library redistributables.

C# / .NET desktop developers building WPF applications on Windows who need production-grade UI controls without building from scratch. Primarily targets Windows developers using Visual Studio 2022 who want a NuGet-packaged control library with Chinese-language community support.

Actively maintained and production-ready: published to NuGet with active version management (myget.org + nuget.org feeds), CI/CD pipeline via GitHub Actions (build.yml, push-to-myget.yml, dotnet-format.yml), and documented on a live Hexo-based docs site (doc/ folder). Last activity visible in version-bump and format workflows indicates recent releases.

Low risk for core stability but moderate localization dependence: single primary maintainer context (ghost1372, DingpingZhang as contributors), no visible automated test suite in file listing, and .NET 4.0 support suggests legacy compatibility requirements that may constrain modernization. HLSL shaders (2.2KB) suggest graphics-intensive features that could have rendering edge cases.

Active maintenance cycle: dotnet-format.yml workflow enforces code style, bump-up-version.yml automates semantic versioning, and myget.org serves pre-release builds. Documentation is live with language-specific guides (attach/backgroundSwitchElement, borderElement, etc.) being actively documented in the Hexo site under doc/source/handycontrol/.

git clone https://github.com/HandyOrg/HandyControl.git && cd HandyControl && dotnet build build/build.cake (uses Cake build system defined in build/build.config.xml). For docs: cd doc && npm install && npm start (Hexo site with Node.js dependencies in doc/package.json).

Daily commands: Build: dotnet build (or cake build via build/build.cake). Package: NuSpec templates in build/ generate .nupkg files for NuGet distribution. Docs: cd doc && npm start launches Hexo dev server on http://localhost:4000. No traditional 'dev server'—this is a library, not an app.

• build/build.cake — Primary build orchestration script; defines how the entire project is compiled, packaged, and distributed via NuGet and MyGet.
• .github/workflows/build.yml — CI/CD pipeline definition that validates all commits and enforces code quality gates before merge.
• LICENSE — Legal foundation for the project; all contributors must understand licensing implications when submitting code.
• .editorconfig — Enforces consistent code style (indentation, line endings) across all contributors' IDEs and editors.
• README.md — Entry point for understanding the project's purpose, feature set, and contribution guidelines.
• CODE_OF_CONDUCT.md — Establishes community standards and expectations for all contributor interactions and behavior.

Add a New WPF Control

1. Create control class in src/Handycontrol/Controls/YourControl.cs inheriting from appropriate WPF base (Button, ComboBox, etc.) (src/Handycontrol/Controls/YourControl.cs)
2. Define XAML theme template in src/Handycontrol/Themes/Resources/Control/YourControl.xaml (src/Handycontrol/Themes/Resources/Control/YourControl.xaml)
3. Add control metadata (dependency properties, routed events) as public properties in code-behind (src/Handycontrol/Controls/YourControl.cs)
4. Document control API in doc/source/handycontrol/extend_controls/yourControl/index.md with parameter descriptions and usage examples (doc/source/handycontrol/extend_controls/yourControl/index.md)

Add a New Attached Behavior

1. Create static attached property class in src/Handycontrol/Attached/YourElement.cs with Get/Set methods (src/Handycontrol/Attached/YourElement.cs)
2. Register PropertyChangedCallback to wire up visual or behavioral changes when property is set (src/Handycontrol/Attached/YourElement.cs)
3. Add XAML trigger or style resource in src/Handycontrol/Themes/Resources/Base/YourElement.xaml if visual effects needed (src/Handycontrol/Themes/Resources/Base/YourElement.xaml)
4. Document attached property in doc/source/handycontrol/attach/yourElement/index.md with usage scenarios (doc/source/handycontrol/attach/yourElement/index.md)

Add a New Data Type or Model

1. Create model class in src/Handycontrol/Data/YourDataType.cs with public properties and optional validation (src/Handycontrol/Data/YourDataType.cs)
2. If notification-based updates needed, implement INotifyPropertyChanged and raise PropertyChanged events (src/Handycontrol/Data/YourDataType.cs)
3. Create documentation entry in doc/source/handycontrol/data/YourDataType/index.md explaining purpose, properties, and usage patterns (doc/source/handycontrol/data/YourDataType/index.md)

Release a New Version

1. Edit version number in build/build.config.xml and update breaking_changes docs if applicable in doc/source/handycontrol/breaking_changes/index.md (build/build.config.xml)
2. Commit all changes and push to master branch; GitHub Actions build.yml runs automatically (.github/workflows/build.yml)
3. Automated bump-up-version workflow creates a git tag and increments version for next cycle (.github/workflows/bump-up-version.yml)
4. Package is automatically published to NuGet via build pipeline; MyGet pre-release feed also updated (.github/workflows/push-to-myget.yml)

• WPF (Windows Presentation Foundation) — Desktop UI framework for rich, hardware-accelerated Windows applications; primary target platform for HandyControl
• C# 11+ with XAML — Modern, type-safe language paired with declarative UI markup; enables reusable control templates and attached behaviors
• Cake Build System — Cross-platform build orchestration in C# DSL; unifies compilation, testing, versioning, and packaging in one script
• GitHub Actions — Integrated CI/CD platform with no external service dependency; automates build, test, format, and publish on every commit
• NuGet & MyGet — Standard .NET package distribution channels; NuGet for stable releases, MyGet for pre-release/canary builds
• Hexo Static Site Generator — Lightweight Node.js documentation engine; generates searchable control API reference from Markdown source files

• WPF-only targeting (no WinUI 3 or Avalonia support)

  • Why: Simplifies test matrix and backward compatibility guarantees; WPF is mature and stable for enterprise desktop apps
  • Consequence: Users on modern .NET XAML platforms (WinUI 3, MAUI) must use alternative control libraries or contribute ports

• Monolithic control library rather than modular NuGet packages per control

  • Why: Reduces versioning complexity and dependency bloat; ensures consistent theming and behavior across all controls
  • Consequence: Users must consume entire library even if only 1–2 controls are needed; larger disk footprint

• Manual XAML theme templates for each control rather than code-generated styles

  • Why: Enables pixel-perfect design customization and theme authoring; designers can work directly with XAML
  • Consequence: More maintenance burden when adding new controls or updating theme resources across multiple theme files

• Cake build script in C# rather than MSBuild/csproj-only

  • Why: Provides higher-level orchestration (versioning, packaging, deployment) in a single scripted DSL
  • Consequence: Requires Cake runtime and adds build step abstraction; developers must understand both Cake and underlying tools

• Not a real-time UI framework; does not handle WebSocket push notifications or live data streaming natively
• Not a cross-platform (non-Windows) control library; targets WPF on .NET Framework and .NET Core on Windows only
• Not a theming engine with runtime theme switching; themes are baked into XAML resources at compile time
• Not an accessibility-first implementation; WCAG/ARIA support is limited and must be enhanced by consuming app
• Not a data-binding or state management solution; relies on WPF's built-in MVVM patterns (INotifyPropertyChanged, ICommand)

1. Build system uses Cake (build/build.cake) not native MSBuild—ensure Cake CLI is installed or use 'dotnet tool' commands. 2) .NET 4.0 target means older C# language features; watch for LINQ limitations and async/await compatibility. 3) HLSL shaders in repo suggest rendering code requires shader compilation on build (check build.cake for shader targets). 4) Documentation requires Node.js + npm (Hexo), separate from .NET build chain. 5) Version management automated by bump-up-version.yml—manual version edits will conflict.

• Attached Properties and Attached Behaviors — Core pattern in WPF for adding behavior to controls without subclassing; entire attach/ folder is built on this pattern to keep controls lean and composable
• Control Templating (ControlTemplate) — WPF controls' appearance is separated from logic via XAML templates; critical for understanding how HandyControl provides consistent theming across controls
• Dependency Properties — WPF's property system enabling binding, animation, and change notification; all HandyControl control properties likely use DependencyProperty for data binding
• Resource Dictionaries (XAML themes) — Centralized styling via XAML ResourceDictionary objects allows HandyControl to provide theme switching and consistent styling across the library
• Cake Build Automation — Build orchestration language used in build/build.cake; understanding Cake is essential for modifying the release and packaging pipeline
• HLSL Pixel Shaders — 2.2KB of HLSL in repo suggests GPU-accelerated rendering for certain controls (likely effects/animations); rare in WPF libraries and worth understanding for performance-critical features
• NuSpec Package Manifests — Multiple .nuspec.template files define how the library is packaged and distributed; critical for understanding multi-package strategy (lib vs. language packs vs. installer)

• MaterialDesignInXAML/MaterialDesignInXamlToolkit — Mature competing WPF control library with Material Design theme; same audience of .NET desktop devs needing pre-styled controls
• DingpingZhang/WpfExtensions — Authored by HandyControl contributor; syntactic sugar helpers that complement HandyControl's core controls with binding and behavior utilities
• DingpingZhang/SimpleFactoryGenerator — Source generator by HandyControl contributor used internally for factory patterns in control initialization and dependency injection
• microsoft/WPF — Official WPF framework repository; HandyControl extends WPF, so tracking framework changes is essential for long-term compatibility
• HandyOrg/HandyControlDemo — Sister repository containing live runnable examples and test cases for HandyControl components (referenced in community but not in main repo file listing)

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 documentation for all Attached Behaviors in doc/source/handycontrol/attach/

The file structure shows 15+ attach behavior documentation files (backgroundSwitchElement, borderElement, dataGridAttach, etc.), but many appear to be stub files with only index.md. Each attach behavior lacks usage examples, property descriptions, and code samples that would help developers integrate these controls. This is a high-value contribution that directly improves the developer experience and reduces support burden.

• [ ] Review each index.md file in doc/source/handycontrol/attach/*/ to identify missing content
• [ ] For each attach behavior, add: purpose/description, list of attached properties with types, usage code examples in XAML/C#, and common scenarios
• [ ] Cross-reference the actual control implementations in the source code (not shown but inferred from folder names)
• [ ] Add a summary table in doc/source/handycontrol/attach/index.md listing all behaviors with brief descriptions
• [ ] Test documentation builds with hexo generate in the doc/ directory

Create GitHub Actions workflow for automated documentation deployment

The repo has build.yml, bump-up-version.yml, dotnet-format.yml, and push-to-myget.yml workflows, but lacks a workflow to automatically build and deploy the Hexo documentation site (doc/) on pushes to main. This ensures docs stay in sync with code releases and improves discoverability.

• [ ] Create .github/workflows/deploy-docs.yml triggered on pushes to master/main branch and documentation file changes
• [ ] Add build steps: install Node.js, install Hexo dependencies (npm install in doc/), run hexo generate, and deploy to GitHub Pages or alternative hosting
• [ ] Ensure the workflow only runs when doc/ or related markdown files change to avoid unnecessary builds
• [ ] Test the workflow by making a docs-only change and verifying the site builds correctly
• [ ] Document the deployment process in a CONTRIBUTING.md or update existing documentation

Add unit test stubs and CI integration for WPF control behaviors

The .github/workflows/ directory contains build automation but no dedicated test execution workflow. Given this is a WPF controls library with 15+ attach behaviors and controls, there are likely unit tests in the codebase (not visible in the partial file structure) that should be executed in CI to catch regressions. Adding explicit test execution ensures code quality.

• [ ] Locate the test project(s) in the source tree (likely *Tests.csproj or *Test directories)
• [ ] Create or update .github/workflows/run-tests.yml to execute tests on every PR and commit to main
• [ ] Configure the workflow to run dotnet test with coverage reporting (using Coverlet or similar)
• [ ] Add test failure notifications and coverage reports as PR comments using actions like codecov/codecov-action
• [ ] Ensure build.yml and run-tests.yml are coordinated to prevent duplicate runs

• Add unit tests for existing Attach behaviors: Create xUnit test project under tests/HandyControl.Tests/Attach/ with fixtures for BackgroundSwitchElement, BorderElement, and IconElement (currently no test folder visible in file listing).
• Expand XAML control documentation: Several controls listed in doc/source/handycontrol/attach/ have minimal index.md files—write property reference pages and usage examples for DropDownElement, EdgeElement, and ImageAttach.
• Enable GitHub Discussions or issue templates for non-English speakers: Add localized issue templates under .github/ISSUE_TEMPLATE/ mirroring bug_report.yaml and feature_request.yaml for simplified Chinese (given the active Chinese community and bilingual README-cn.md).

The HandyControl repository has moderate security concerns primarily related to outdated npm dependencies used in the documentation build system. The main vulnerability is the use of Hexo 3.8.0 (2017) and its associated plugins, which contain known unpatched vulnerabilities. However, these dependencies appear isolated to documentation generation and do not directly impact the production WPF control library distributed via NuGet. The C# library itself would require static code analysis to assess for injection risks, hardcoded credentials, and other code-level vulnerabilities. The security policy is functional but minimal and should be enhanced. Immediate action: update the doc/package.json dependencies to recent versions and implement npm audit scanning in CI/CD.

• High · Outdated Hexo Dependency Version — doc/package.json - hexo dependency. The package.json in the doc directory specifies hexo@^3.8.0, which was released in 2017 and contains multiple known security vulnerabilities. Hexo 3.x is no longer maintained and has unpatched CVEs related to template injection and other security issues. Fix: Update hexo to the latest stable version (v6.x or v7.x) and audit all other hexo-* dependencies for security patches. Run 'npm audit' and 'npm audit fix' to resolve known vulnerabilities.
• Medium · Multiple Outdated Hexo Plugin Dependencies — doc/package.json - all hexo plugin dependencies. Several hexo-generator and hexo-renderer packages are pinned to very old versions (2017-2018 era). These dependencies may contain security vulnerabilities and lack security updates. Specifically: hexo-generator-archive@^0.1.5, hexo-generator-category@^0.1.3, hexo-generator-index@^0.2.1, hexo-renderer-ejs@^0.3.1, hexo-renderer-marked@^0.3.2, hexo-renderer-stylus@^0.3.3. Fix: Update all hexo plugins to their latest versions. Review upstream security advisories and changelogs. Consider using 'npm audit' and implementing automated dependency scanning in CI/CD pipelines.
• Low · Private Package Not Clearly Marked in Source — doc/package.json - package metadata. The documentation site (doc/package.json) is marked as private, but there is no clear separation or documentation explaining that the main library code resides in a separate location. This could lead to confusion about which package to audit for production security. Fix: Clearly document in README.md that the doc/ directory is only for documentation generation and is not part of the production HandyControl NuGet package. Point users to the actual source code location for security audits.
• Low · Security Policy Lacks Detailed Vulnerability Management — SECURITY.md. The SECURITY.md policy is minimal and lacks important details: no specific response time SLA, no vulnerability disclosure timeline, no security update process documentation, and the support email is not explicitly listed. Fix: Enhance SECURITY.md with: (1) specific response times for vulnerability reports, (2) disclosure timeline, (3) details on security update release process, (4) explicit security contact email, (5) PGP key if applicable, and (6) past security advisories if any.

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.