modBrowse Agent Instructions

Package Type: Shiny UI Module
Version: 0.9.3
See Also: Global guidance in D:/workspace/.agents/AGENTS.*.md
Exemplar: modGallery (D:/workspace/platform/app/modGallery)

This file contains requirements specific to modBrowse and other Artalytics Shiny module (mod) and app (app) packages. General R package requirements are documented in the global AGENTS files.

---

Before Starting Work

1. Read global guidance files:

   • D:/workspace/.agents/AGENTS.organization.md
   • D:/workspace/.agents/AGENTS.style.coding.md
   • D:/workspace/.agents/AGENTS.style.naming.md

2. Check README.md for environment variables required.

3. Review vignettes for module integration context:

   • vignettes/modBrowse.qmd - Overview and ecosystem
   • vignettes/developer-guide.qmd - Integration workflow
   • vignettes/module-architecture.qmd - Internal design

---

Shiny Module Package Requirements

These requirements apply to all mod* and app* packages:

Documentation Requirements

• Complete roxygen on all exported UI/Server functions
• Reactive parameter documentation (r parameter structure)
• Module integration examples in @examples
• Vignettes show full app integration, not isolated module usage
• README includes parent app context (appPlatform)

Module-Specific Patterns

• UI functions return shiny.tag.list
• Server functions use moduleServer()
• Namespace parameter documented with conflict prevention context
• Reactive list structure fully documented
• inst/app/app.R for isolated testing (not production deployment)

Environment Variables

• Document inherited variables with source attribution
• Never invent variable names - verify against dependency READMEs
• List in README before Quick Example

pkgdown Configuration

• Use template: package: templ.pkgdown
• Reference groups include: Browse Module, Sub-Modules, Helpers, Theming, App Lifecycle
• Get Started vignette shows integration with parent app
• Additional vignettes cover integration and architecture

Testing

• Tests cover module structure (UI/Server function signatures)
• Integration tests with mock reactive context
• No tests requiring full appPlatform deployment
• Note: Legacy tests in tests/testthat/legacy/ are deprecated

---

modBrowse Sub-Modules

modBrowse includes these sub-modules:

Module	Files	Purpose
enhancedStats	mod-enhancedStats.R	Premium value box display
collectionInfo	mod-collectionInfo.R	Collection summary statistics

Both sub-modules are exported for potential reuse.

---

Exported Helpers

Function	Purpose
createCollectionLabelBadge()	Collection name badge with truncation
artDisplayCard()	Artwork card with thumbnails and badges

These helpers are exported to support custom browse layouts.

---

Reactive Data Structure

The r parameter expects:

r <- reactiveValues(
  artist = "746bxxxx-...",          # Artist UUID (set by parent app)
  artwork = "99xxxxxx-...",         # Artwork UUID (managed by module)
  appdata = list(                   # From artutils::get_appdata()
    artist = list(
      info = list(...),
      stats = list(...),
      collections = character(),    # Named vector of collection UUIDs
      artDT = data.table(...)       # All artist artworks with metadata
    )
  )
)

Key columns in artDT: - art_uuid, art_title - Artwork identification - collection_uuid, collection_name - Collection assignment - is_nft, is_print, is_listed - Status flags - n_variants, brush_strokes, drawing_hours - Metrics - created_utc - Creation timestamp

---

Environment Variables

Inherited from dependencies (verify against artcore README.md):

Database (via artcore): - ART_PGHOST, ART_PGPORT, ART_PGUSER, ART_PGPASS

CDN (via artcore): - ART_BUCKETS_KEY_ID, ART_BUCKETS_KEY_SECRET

---

Key Development Patterns

Badge Asset Fallback

The .onLoad() function registers local badge assets as fallback when CDN or artutils fails. This ensures badge overlays display even in degraded conditions.

Filter Synchronization

Desktop checkbox filters and mobile select filters are synchronized bidirectionally with a syncing flag to prevent infinite loops. See app-server.R lines 321-403.

Naming Convention

TODO: Standardize function naming per AGENTS.style.naming.md: - Shiny module functions: camelCase (modBrowseUI, modBrowseServer) - Utility functions: snake_case - Internal functions: snake_case with leading dot (.addBadgeNFT)

Current code uses mixed conventions. Future work should standardize.

---

Modernization Pattern for Other Packages

This package demonstrates the documentation modernization pattern for other mod* packages. Key steps:

1. Phase 0: Update DESCRIPTION (VignetteBuilder, Suggests), export useful helpers
2. Phase 1: Enhance all roxygen (description, params, return, family, examples)
3. Phase 2: Create _pkgdown.yml and 3+ vignettes (narrative workflow style)
4. Phase 3: Rewrite README.md with env vars, quick example, hierarchy
5. Phase 4: Backfill NEWS.md with all version entries
6. Phase 5: Replace AGENTS.md with this template pattern
7. Phase 6: Run devtools::document(), devtools::check(), pkgdown::build_site()

Study modBrowse and modGallery as exemplars when modernizing other packages.

---

Testing

# Run tests
devtools::test()

# Run standalone app for testing
modBrowse::run_app(artist = "746b8207-72f5-4ab6-8d19-a91d03daec3d")

# Build documentation
devtools::document()
pkgdown::build_site()